diff --git a/packages/components/psammead-grid/CHANGELOG.md b/packages/components/psammead-grid/CHANGELOG.md index 715c60dde0..e0f47cb2cf 100644 --- a/packages/components/psammead-grid/CHANGELOG.md +++ b/packages/components/psammead-grid/CHANGELOG.md @@ -3,6 +3,7 @@ | Version | Description | |---------|-------------| +| 1.1.1 | [PR#2893](https://github.com/bbc/psammead/pull/2893) Add `parentColumns` to prop list in README | | 1.1.0 | [PR#2876](https://github.com/bbc/psammead/pull/2876) Remove alpha tag | | 1.1.0-alpha.2 | [PR#2815](https://github.com/bbc/psammead/pull/2815) Remove display:inline on outer grids | | 1.1.0-alpha.1 | [PR#2796](https://github.com/bbc/psammead/pull/2796) Fix padding on outer grid | diff --git a/packages/components/psammead-grid/README.md b/packages/components/psammead-grid/README.md index 9cea62bdde..c164afc19b 100644 --- a/packages/components/psammead-grid/README.md +++ b/packages/components/psammead-grid/README.md @@ -19,6 +19,7 @@ Psammead Grid is a component that you can use to set out column-based layouts us | item | boolean | no | false | `item` | | enableGelGutters | boolean | no | false | `enableGelGutter` | | margins | object | no | `{ group0: false, group1: false, group2: false, group3: false, group4: false, group5: false }` | `{ group0: true, group1: true, group2: true, group3: true }` | +| parentColumns | object | no | null | `columns: { group0: 6, group1: 6, group2: 3, group3: 3, group4: 4, group5: 4}` | - When should I use the `columns` prop? - This should always be defined. @@ -41,7 +42,7 @@ Psammead Grid is a component that you can use to set out column-based layouts us group2: 1, group3: 1, group4: 1, - group5: 1 + group5: 1, }} > This spans 1 out of 6 columns for all widths @@ -54,7 +55,7 @@ Psammead Grid is a component that you can use to set out column-based layouts us group2: 5, group3: 5, group4: 5, - group5: 5 + group5: 5, }} > This spans 5 out of 6 columns for all widths @@ -67,6 +68,8 @@ Psammead Grid is a component that you can use to set out column-based layouts us - If you don't pass it in, the offset value defaults to 1, the start of the grid. - Why is there no vertical spacing on the grid? - The Grid implementation only has gutters/margins for columns, [according to the GEL specification](https://www.bbc.co.uk/gel/guidelines/grid#grid-sizes). This is to allow flexibility for a variety of spacing. To add vertical spacing, you should add padding/margin/top/bottom to the contents. +- When should I use the `parentColumns` prop? + - `parentColumns` is an object structured just like the `columns` prop. This prop explicitly passes the parent grid's columns configuration into a child `` element. [See example.](https://github.com/bbc/psammead/tree/latest/packages/components/psammead-grid#parentcolumns-prop) ## Usage @@ -74,12 +77,14 @@ We use the GEL Grid for our breakpoints, as well as for our standard gutters and When we refer to `group3` in this component, we're referring to the breakpoint with a minimum width `GEL_GROUP_3_SCREEN_WIDTH_MIN` & a maximum width `GEL_GROUP_3_SCREEN_WIDTH_MAX`. These values are defined within [`@bbc/gel-foundations/breakpoints`](https://github.com/bbc/psammead/blob/latest/packages/utilities/gel-foundations/src/breakpoints.js). +When using one of the extended Grid components, if you wish to extend it using the `as` prop, you'll need to use `forwardedAs`. This prop enables you to pass down the element down further than one level. + #### Simple example Here is an example of a `` that has 8 columns for `group4` (from 1008px to 1279px). It has four child `` elements, one which spans 6/8 columns and three others which spans 2/8 columns within this breakpoint. ```jsx -import Grid from "@bbc/psammead-grid"; +import Grid from '@bbc/psammead-grid'; const MyComponent = () => ( ( group2: 8, group3: 8, group4: 8, - group5: 8 + group5: 8, }} > ( group2: 6, group3: 6, group4: 6, - group5: 6 + group5: 6, }} >

Item 1 - Paragraph that spans 6 out of 8 columns through group4

@@ -113,7 +118,7 @@ const MyComponent = () => ( group2: 2, group3: 2, group4: 2, - group5: 2 + group5: 2, }} >

Item 2 - Paragraph that spans 2 out of 8 columns through group4

@@ -126,7 +131,7 @@ const MyComponent = () => ( group2: 2, group3: 2, group4: 2, - group5: 2 + group5: 2, }} >

Item 3 - Paragraph that spans 2 out of 8 columns through group4

@@ -139,7 +144,7 @@ const MyComponent = () => ( group2: 2, group3: 2, group4: 2, - group5: 2 + group5: 2, }} >

Item 4 - Paragraph that spans 2 out of 8 columns through group4

@@ -157,7 +162,7 @@ Using `enableGelGutters` on the `Grid` element. Note: this should _not_ be added Usage of `margins` can be on either `` or ``. ```jsx -import Grid from "@bbc/psammead-grid"; +import Grid from '@bbc/psammead-grid'; const MyComponent = () => ( ( group2: 4, group3: 6, group4: 8, - group5: 12 + group5: 12, }} margins={{ group0: true, @@ -187,7 +192,7 @@ const MyComponent = () => ( group2: 4, group3: 6, group4: 6, - group5: 12 + group5: 12, }} >

@@ -202,7 +207,7 @@ const MyComponent = () => ( group2: 4, group3: 6, group4: 2, - group5: 12 + group5: 12, }} >

@@ -226,7 +231,7 @@ Note that here, any time you use `` that generates a new grid. The total n Here we have no margins on the Grid item around the Image, but there is on the Paragraph items. ```jsx -import Grid from "@bbc/psammead-grid"; +import Grid from '@bbc/psammead-grid'; const MyComponent = () => ( ( group2: 6, group3: 6, group4: 6, - group5: 6 + group5: 6, }} > ( group2: 6, group3: 6, group4: 6, - group5: 6 + group5: 6, }} > ( group2: 6, group3: 3, group4: 3, - group5: 3 + group5: 3, }} > @@ -270,7 +275,7 @@ const MyComponent = () => ( group2: 6, group3: 3, group4: 3, - group5: 3 + group5: 3, }} > @@ -284,7 +289,7 @@ const MyComponent = () => ( group2: 2, group3: 2, group4: 2, - group5: 2 + group5: 2, }} > @@ -297,7 +302,7 @@ const MyComponent = () => ( group2: 4, group3: 4, group4: 4, - group5: 4 + group5: 4, }} > @@ -306,6 +311,48 @@ const MyComponent = () => ( ); ``` +#### Child grid using parentColumns prop + +Note that, any time you render a child `` outside of the parent grid, the parent's columns configuration is not automagically passed to the child. This causes the layout to break in browsers that do not support css grid. To ensure the configuration is passed correctly, you need to explicitly pass in the parentColumns prop. + +```jsx +import Grid from '@bbc/psammead-grid'; + +const parentProps = { + columns: { + group0: 6, + group1: 6, + group2: 6, + group3: 6, + group4: 6, + group5: 6, + }, +}; + +const childProps = { + columns: { + group0: 6, + group1: 6, + group2: 6, + group3: 6, + group4: 6, + group5: 6, + }, +}; + +const renderChildGrid = () => ( + + + +); + +const MyComponent = () => ( + + {renderChildGrid()} + +); +``` + ### When to use this component This `Grid` component can be used for page-level layouts as well as for layouts of individual components. You can nest Grids within one another for more complex layouts. Please see the Storybook Stories for examples. diff --git a/packages/components/psammead-grid/package-lock.json b/packages/components/psammead-grid/package-lock.json index 0a5b8cd69b..ef403442fd 100644 --- a/packages/components/psammead-grid/package-lock.json +++ b/packages/components/psammead-grid/package-lock.json @@ -1,6 +1,6 @@ { "name": "@bbc/psammead-grid", - "version": "1.1.0", + "version": "1.1.1", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/packages/components/psammead-grid/package.json b/packages/components/psammead-grid/package.json index a0ad2ee28f..7655fd3331 100644 --- a/packages/components/psammead-grid/package.json +++ b/packages/components/psammead-grid/package.json @@ -1,6 +1,6 @@ { "name": "@bbc/psammead-grid", - "version": "1.1.0", + "version": "1.1.1", "description": "Grid component", "main": "dist/index.js", "module": "esm/index.js", diff --git a/packages/components/psammead-grid/src/index.jsx b/packages/components/psammead-grid/src/index.jsx index 33719e4c20..7e407fa4d8 100644 --- a/packages/components/psammead-grid/src/index.jsx +++ b/packages/components/psammead-grid/src/index.jsx @@ -334,6 +334,13 @@ Grid.propTypes = { group5: number, }), item: bool, + parentColumns: shape({ + group1: number, + group2: number, + group3: number, + group4: number, + group5: number, + }), }; Grid.defaultProps = { @@ -348,6 +355,7 @@ Grid.defaultProps = { }, startOffset: {}, item: false, + parentColumns: null, }; export default Grid;