Skip to content

Commit 3cc0353

Browse files
rugoncalvesbrandyscarneyIonitronShaneK
authored
feat(grid): modernizing component (#30658)
<!-- Please do not submit updates to dependencies unless it fixes an issue. --> <!-- Please try to limit your pull request to one type (bugfix, feature, etc). Submit multiple pull requests if needed. --> ## What is the current behavior? <!-- Please describe the current behavior that you are modifying. --> The existing grid component (`ion-grid`, `ion-row`, and `ion-col`) in Ionic was developed several years ago and has not received significant updates since then. As a result, it does not leverage modern CSS features. For example, the gutter (spacing) between columns is implemented using the border property, which is an outdated technique. ## What is the new behavior? <!-- Please describe the behavior or changes that are being added by this PR. --> - `--ion-grid-gap`: this new CSS variable, will indicate the gap size in the grid. Defaults to `0px` - the current value. - `ion-col`: has a new way to calculate the width of the column. Additionally a new property `order` (and responsive variants) was added, and will control the order of the column. - `ion-row`: uses the newly introduced custom property `--ion-grid-gap`. This property will indicate the gap size in the grid. ## Does this introduce a breaking change? - [x] Yes - [ ] No <!-- If this introduces a breaking change: 1. Describe the impact and migration path for existing applications below. 2. Update the BREAKING.md file with the breaking change. 3. Add "BREAKING CHANGE: [...]" to the commit description when merging. See https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer for more information. --> The properties `pull` and `push` from `ion-col`, have been removed. The functionality achieved with them, is now achieved with the new property `order` and the existing `size`. More information and migration examples can be read in `BREAKING.md` file. ## Other information <!-- Any other information that is important to this PR such as screenshots of how the component looks before and after the change. --> --------- Co-authored-by: Brandy Smith <6577830+brandyscarney@users.noreply.github.com> Co-authored-by: Brandy Smith <brandyscarney@users.noreply.github.com> Co-authored-by: ionitron <hi@ionicframework.com> Co-authored-by: Shane <shane@shanessite.net>
1 parent 9f546ed commit 3cc0353

File tree

45 files changed

+498
-85
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+498
-85
lines changed

‎BREAKING.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ This is a comprehensive list of the breaking changes introduced in the major ver
1818
- [Button](#version-9x-button)
1919
- [Card](#version-9x-card)
2020
- [Chip](#version-9x-chip)
21+
- [Grid](#version-9x-grid)
2122

2223
<h2 id="version-9x-components">Components</h2>
2324

@@ -32,3 +33,105 @@ This is a comprehensive list of the breaking changes introduced in the major ver
3233
<h4 id="version-9x-chip">Chip</h4>
3334

3435
- The `border-radius` of the `ios` and `md` chip now defaults to `10px` and `8px`, respectively, instead of `16px` in accordance with the iOS and Material Design 3 guidelines. To revert to the previous appearance, set the `shape` to `"round"`, or override the `--border-radius` CSS variable to specify a different value.
36+
37+
<h4 id="version-9x-grid">Grid</h4>
38+
39+
- The properties `pull` and `push` have been deprecated and no longer work. A similar look can be achieved with the newly added property `order`.
40+
41+
<h5>Example 1: Swap two columns</h5>
42+
43+
**Version up to 8.x**
44+
```html
45+
<ion-grid>
46+
<ion-row>
47+
<ion-col push="4">1</ion-col>
48+
<ion-col pull="4">2</ion-col>
49+
<ion-col>3</ion-col>
50+
</ion-row>
51+
</ion-grid>
52+
```
53+
**Version 9.x+**
54+
```html
55+
<ion-grid>
56+
<ion-row>
57+
<ion-col order="2">1</ion-col>
58+
<ion-col order="1">2</ion-col>
59+
<ion-col order="3">3</ion-col>
60+
</ion-row>
61+
</ion-grid>
62+
```
63+
64+
<h5>Example 2: Reorder columns with specific sizes</h5>
65+
To reorder two columns where column 1 has `size="9" push="3"` and column 2 has `size="3" pull="9"`:
66+
67+
**Version up to 8.x**
68+
```html
69+
<ion-grid>
70+
<ion-row>
71+
<ion-col push="3">1</ion-col>
72+
<ion-col pull="9">2</ion-col>
73+
</ion-row>
74+
</ion-grid>
75+
```
76+
**Version 9.x+**
77+
```html
78+
<ion-grid>
79+
<ion-row>
80+
<ion-col order="2">1</ion-col>
81+
<ion-col size="3" order="1">2</ion-col>
82+
</ion-row>
83+
</ion-grid>
84+
```
85+
<h5>Example 3: Push</h5>
86+
```html
87+
<ion-grid>
88+
<ion-row>
89+
<ion-col size="auto" push="1">
90+
<div>ion-col push 1</div>
91+
</ion-col>
92+
<ion-col size="auto" push="1">
93+
<div>ion-col push 1</div>
94+
</ion-col>
95+
</ion-row>
96+
</ion-grid>
97+
```
98+
**Version 9.x+**
99+
```html
100+
<ion-grid>
101+
<ion-row>
102+
<ion-col size="auto" offset="1">
103+
<div>ion-col size="auto" offset="1"</div>
104+
</ion-col>
105+
<ion-col size="auto">
106+
<div>ion-col size="auto"</div>
107+
</ion-col>
108+
</ion-row>
109+
</ion-grid>
110+
```
111+
112+
<h5>Example 4: Push and Pull</h5>
113+
```html
114+
<ion-grid>
115+
<ion-row>
116+
<ion-col size="3" size-md="6" push="9" push-md="6">
117+
<div>ion-col size="3" size-md="6" push="9" push-md="6"</div>
118+
</ion-col>
119+
<ion-col size="9" size-md="6" pull="3" pull-md="6">
120+
<div>ion-col size="9" size-md="6" pull="3" pull-md="6"</div>
121+
</ion-col>
122+
</ion-row>
123+
</ion-grid>
124+
```
125+
**Version 9.x+**
126+
```html
127+
<ion-grid>
128+
<ion-row>
129+
<ion-col size="auto" order="2" order-md="2">
130+
<div>ion-col size="auto" order="2" order-md="2"</div>
131+
</ion-col>
132+
<ion-col size="auto" order="1" order-md="1">
133+
<div>ion-col size="auto" order="1" order-md="1"</div>
134+
</ion-col>
135+
</ion-row>
136+
</ion-grid>
137+
```

‎core/api.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -622,6 +622,12 @@ ion-col,prop,offsetMd,string | undefined,undefined,false,false
622622
ion-col,prop,offsetSm,string | undefined,undefined,false,false
623623
ion-col,prop,offsetXl,string | undefined,undefined,false,false
624624
ion-col,prop,offsetXs,string | undefined,undefined,false,false
625+
ion-col,prop,order,string | undefined,undefined,false,false
626+
ion-col,prop,orderLg,string | undefined,undefined,false,false
627+
ion-col,prop,orderMd,string | undefined,undefined,false,false
628+
ion-col,prop,orderSm,string | undefined,undefined,false,false
629+
ion-col,prop,orderXl,string | undefined,undefined,false,false
630+
ion-col,prop,orderXs,string | undefined,undefined,false,false
625631
ion-col,prop,pull,string | undefined,undefined,false,false
626632
ion-col,prop,pullLg,string | undefined,undefined,false,false
627633
ion-col,prop,pullMd,string | undefined,undefined,false,false
@@ -641,6 +647,7 @@ ion-col,prop,sizeSm,string | undefined,undefined,false,false
641647
ion-col,prop,sizeXl,string | undefined,undefined,false,false
642648
ion-col,prop,sizeXs,string | undefined,undefined,false,false
643649
ion-col,prop,theme,"ios" | "md" | "ionic",undefined,false,false
650+
ion-col,css-prop,--col-unit-size
644651
ion-col,css-prop,--ion-grid-column-padding
645652
ion-col,css-prop,--ion-grid-column-padding-lg
646653
ion-col,css-prop,--ion-grid-column-padding-md
@@ -2006,6 +2013,7 @@ ion-router-outlet,prop,theme,"ios" | "md" | "ionic",undefined,false,false
20062013
ion-row,shadow
20072014
ion-row,prop,mode,"ios" | "md",undefined,false,false
20082015
ion-row,prop,theme,"ios" | "md" | "ionic",undefined,false,false
2016+
ion-row,css-prop,--ion-grid-gap
20092017

20102018
ion-searchbar,scoped
20112019
ion-searchbar,prop,animated,boolean,false,false,false

‎core/src/components.d.ts‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -927,52 +927,88 @@ export namespace Components {
927927
* The amount to offset the column for xs screens, in terms of how many columns it should shift to the end of the total available.
928928
*/
929929
"offsetXs"?: string;
930+
/**
931+
* The order of the column, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
932+
*/
933+
"order"?: string;
934+
/**
935+
* The order of the column for lg screens, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
936+
*/
937+
"orderLg"?: string;
938+
/**
939+
* The order of the column for md screens, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
940+
*/
941+
"orderMd"?: string;
942+
/**
943+
* The order of the column for sm screens, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
944+
*/
945+
"orderSm"?: string;
946+
/**
947+
* The order of the column for xl screens, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
948+
*/
949+
"orderXl"?: string;
950+
/**
951+
* The order of the column for xs screens, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
952+
*/
953+
"orderXs"?: string;
930954
/**
931955
* The amount to pull the column, in terms of how many columns it should shift to the start of the total available.
956+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
932957
*/
933958
"pull"?: string;
934959
/**
935960
* The amount to pull the column for lg screens, in terms of how many columns it should shift to the start of the total available.
961+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
936962
*/
937963
"pullLg"?: string;
938964
/**
939965
* The amount to pull the column for md screens, in terms of how many columns it should shift to the start of the total available.
966+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
940967
*/
941968
"pullMd"?: string;
942969
/**
943970
* The amount to pull the column for sm screens, in terms of how many columns it should shift to the start of the total available.
971+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
944972
*/
945973
"pullSm"?: string;
946974
/**
947975
* The amount to pull the column for xl screens, in terms of how many columns it should shift to the start of the total available.
976+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
948977
*/
949978
"pullXl"?: string;
950979
/**
951980
* The amount to pull the column for xs screens, in terms of how many columns it should shift to the start of the total available.
981+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
952982
*/
953983
"pullXs"?: string;
954984
/**
955985
* The amount to push the column, in terms of how many columns it should shift to the end of the total available.
986+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
956987
*/
957988
"push"?: string;
958989
/**
959990
* The amount to push the column for lg screens, in terms of how many columns it should shift to the end of the total available.
991+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
960992
*/
961993
"pushLg"?: string;
962994
/**
963995
* The amount to push the column for md screens, in terms of how many columns it should shift to the end of the total available.
996+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
964997
*/
965998
"pushMd"?: string;
966999
/**
9671000
* The amount to push the column for sm screens, in terms of how many columns it should shift to the end of the total available.
1001+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
9681002
*/
9691003
"pushSm"?: string;
9701004
/**
9711005
* The amount to push the column for xl screens, in terms of how many columns it should shift to the end of the total available.
1006+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
9721007
*/
9731008
"pushXl"?: string;
9741009
/**
9751010
* The amount to push the column for xs screens, in terms of how many columns it should shift to the end of the total available.
1011+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
9761012
*/
9771013
"pushXs"?: string;
9781014
/**
@@ -6861,52 +6897,88 @@ declare namespace LocalJSX {
68616897
* The amount to offset the column for xs screens, in terms of how many columns it should shift to the end of the total available.
68626898
*/
68636899
"offsetXs"?: string;
6900+
/**
6901+
* The order of the column, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
6902+
*/
6903+
"order"?: string;
6904+
/**
6905+
* The order of the column for lg screens, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
6906+
*/
6907+
"orderLg"?: string;
6908+
/**
6909+
* The order of the column for md screens, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
6910+
*/
6911+
"orderMd"?: string;
6912+
/**
6913+
* The order of the column for sm screens, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
6914+
*/
6915+
"orderSm"?: string;
6916+
/**
6917+
* The order of the column for xl screens, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
6918+
*/
6919+
"orderXl"?: string;
6920+
/**
6921+
* The order of the column for xs screens, in terms of where the column should position itself in the columns renderer. If no value is passed, the column order implicit value will be the order in the html structure.
6922+
*/
6923+
"orderXs"?: string;
68646924
/**
68656925
* The amount to pull the column, in terms of how many columns it should shift to the start of the total available.
6926+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
68666927
*/
68676928
"pull"?: string;
68686929
/**
68696930
* The amount to pull the column for lg screens, in terms of how many columns it should shift to the start of the total available.
6931+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
68706932
*/
68716933
"pullLg"?: string;
68726934
/**
68736935
* The amount to pull the column for md screens, in terms of how many columns it should shift to the start of the total available.
6936+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
68746937
*/
68756938
"pullMd"?: string;
68766939
/**
68776940
* The amount to pull the column for sm screens, in terms of how many columns it should shift to the start of the total available.
6941+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
68786942
*/
68796943
"pullSm"?: string;
68806944
/**
68816945
* The amount to pull the column for xl screens, in terms of how many columns it should shift to the start of the total available.
6946+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
68826947
*/
68836948
"pullXl"?: string;
68846949
/**
68856950
* The amount to pull the column for xs screens, in terms of how many columns it should shift to the start of the total available.
6951+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
68866952
*/
68876953
"pullXs"?: string;
68886954
/**
68896955
* The amount to push the column, in terms of how many columns it should shift to the end of the total available.
6956+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
68906957
*/
68916958
"push"?: string;
68926959
/**
68936960
* The amount to push the column for lg screens, in terms of how many columns it should shift to the end of the total available.
6961+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
68946962
*/
68956963
"pushLg"?: string;
68966964
/**
68976965
* The amount to push the column for md screens, in terms of how many columns it should shift to the end of the total available.
6966+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
68986967
*/
68996968
"pushMd"?: string;
69006969
/**
69016970
* The amount to push the column for sm screens, in terms of how many columns it should shift to the end of the total available.
6971+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
69026972
*/
69036973
"pushSm"?: string;
69046974
/**
69056975
* The amount to push the column for xl screens, in terms of how many columns it should shift to the end of the total available.
6976+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
69066977
*/
69076978
"pushXl"?: string;
69086979
/**
69096980
* The amount to push the column for xs screens, in terms of how many columns it should shift to the end of the total available.
6981+
* @deprecated Use the combination of `size` and `order` properties to achieve the same effect.
69106982
*/
69116983
"pushXs"?: string;
69126984
/**

‎core/src/components/col/col.scss‎

Lines changed: 56 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@
44
// --------------------------------------------------
55

66
:host {
7+
/**
8+
* @prop --col-unit-size: The size of each Column unit.
9+
*/
10+
--col-unit-size: calc(
11+
(100% - (var(--ion-grid-columns, 12) - 1) * var(--ion-grid-gap, 0px)) / var(--ion-grid-columns, 12)
12+
);
13+
714
/**
815
* @prop --ion-grid-columns: The number of total Columns in the Grid
916
* @prop --ion-grid-column-padding: Padding for the Column
@@ -20,10 +27,55 @@
2027

2128
position: relative;
2229

23-
flex-basis: 0;
24-
flex-grow: 1;
30+
flex: 1;
2531

26-
width: 100%;
27-
max-width: 100%;
2832
min-height: 1px; // Prevent columns from collapsing when empty
33+
34+
overflow: auto;
35+
}
36+
37+
:host(.ion-grid-col-auto) {
38+
flex: 0 0 auto;
39+
}
40+
41+
:host([class^="ion-grid-col--"]),
42+
:host([class*=" ion-grid-col--"]) {
43+
flex: 0 0
44+
calc(var(--ion-grid-col-span) * var(--col-unit-size) + (var(--ion-grid-col-span) - 1) * var(--ion-grid-gap, 0px));
45+
46+
max-width: calc(
47+
var(--ion-grid-col-span) * var(--col-unit-size) + (var(--ion-grid-col-span) - 1) * var(--ion-grid-gap, 0px)
48+
);
49+
}
50+
51+
:host([class^="ion-grid-offset-col--"]),
52+
:host([class*=" ion-grid-offset-col--"]) {
53+
--margin-calc: calc(
54+
var(--col-unit-size) * var(--ion-grid-col-margin) + (var(--ion-grid-gap, 0px) * var(--ion-grid-col-margin))
55+
);
56+
57+
@include margin-horizontal(var(--margin-calc), 0);
58+
}
59+
60+
/*
61+
* While the number of columns can be customized, we generate
62+
* a default set of classes for 12 columns. In the future, this
63+
* will be configurable at build time as Ionic becomes more modular.
64+
* For now, 12 columns is a practical default. Developers who need
65+
* more columns can override or extend these styles as needed.
66+
*/
67+
$grid-col-number: 12;
68+
69+
@for $i from 1 through $grid-col-number {
70+
:host(.ion-grid-col--#{$i}) {
71+
--ion-grid-col-span: #{$i};
72+
}
73+
74+
:host(.ion-grid-order-col--#{$i}) {
75+
order: #{$i};
76+
}
77+
78+
:host(.ion-grid-offset-col--#{$i}) {
79+
--ion-grid-col-margin: #{$i};
80+
}
2981
}

0 commit comments

Comments
 (0)