diff --git a/site/components/illustrations/components/grid-cell/anatomy.tsx b/site/components/illustrations/components/grid-cell/anatomy.tsx new file mode 100644 index 0000000000..e51752974b --- /dev/null +++ b/site/components/illustrations/components/grid-cell/anatomy.tsx @@ -0,0 +1,210 @@ +import React from 'react'; +import {Svg} from '../../svg'; +import {Path} from '../../path'; +import {Rect} from '../../rect'; + +export const anatomy: React.FC = () => ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +); + +export default anatomy; diff --git a/site/components/illustrations/components/grid-cell/behaviours/max-width.tsx b/site/components/illustrations/components/grid-cell/behaviours/max-width.tsx new file mode 100644 index 0000000000..77693e9c3c --- /dev/null +++ b/site/components/illustrations/components/grid-cell/behaviours/max-width.tsx @@ -0,0 +1,85 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const maxWidth: React.FC = () => ( + + + + + + + + + + + + + + + + + + + + + +); + +export default maxWidth; diff --git a/site/components/illustrations/components/grid-cell/behaviours/nested-grids.tsx b/site/components/illustrations/components/grid-cell/behaviours/nested-grids.tsx new file mode 100644 index 0000000000..b2a35ceb43 --- /dev/null +++ b/site/components/illustrations/components/grid-cell/behaviours/nested-grids.tsx @@ -0,0 +1,69 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const nestedgrids: React.FC = () => ( + + + + + + + + + + + + + + + +); + +export default nestedgrids; diff --git a/site/components/illustrations/components/grid-cell/celloptions/offset.tsx b/site/components/illustrations/components/grid-cell/celloptions/offset.tsx new file mode 100644 index 0000000000..7174e3c54b --- /dev/null +++ b/site/components/illustrations/components/grid-cell/celloptions/offset.tsx @@ -0,0 +1,39 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const offset: React.FC = () => ( + + + + + + + + +); + +export default offset; diff --git a/site/components/illustrations/components/grid-cell/celloptions/order.tsx b/site/components/illustrations/components/grid-cell/celloptions/order.tsx new file mode 100644 index 0000000000..1acc24ebd3 --- /dev/null +++ b/site/components/illustrations/components/grid-cell/celloptions/order.tsx @@ -0,0 +1,91 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const order: React.FC = () => ( + + + + + + + + + + + + + + + + + + + + + +); + +export default order; diff --git a/site/components/illustrations/components/grid-cell/celloptions/span.tsx b/site/components/illustrations/components/grid-cell/celloptions/span.tsx new file mode 100644 index 0000000000..e673b75a2c --- /dev/null +++ b/site/components/illustrations/components/grid-cell/celloptions/span.tsx @@ -0,0 +1,93 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const span: React.FC = () => ( + + + + + + + + + + + + + + + + + + + + + + +); + +export default span; diff --git a/site/components/illustrations/components/grid-cell/celloptions/visibility.tsx b/site/components/illustrations/components/grid-cell/celloptions/visibility.tsx new file mode 100644 index 0000000000..d99fba7833 --- /dev/null +++ b/site/components/illustrations/components/grid-cell/celloptions/visibility.tsx @@ -0,0 +1,83 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const visibility: React.FC = () => ( + + + + + + + + + + + + + + + + + + + +); + +export default visibility; diff --git a/site/components/illustrations/components/grid-cell/gridoptions/breakpoints.tsx b/site/components/illustrations/components/grid-cell/gridoptions/breakpoints.tsx new file mode 100644 index 0000000000..346df62a11 --- /dev/null +++ b/site/components/illustrations/components/grid-cell/gridoptions/breakpoints.tsx @@ -0,0 +1,77 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const breakpoints: React.FC = () => ( + + + + + + + + + + + + + + + + + + +); + +export default breakpoints; diff --git a/site/components/illustrations/components/grid-cell/gridoptions/gutter-width.tsx b/site/components/illustrations/components/grid-cell/gridoptions/gutter-width.tsx new file mode 100644 index 0000000000..cb3ca6741b --- /dev/null +++ b/site/components/illustrations/components/grid-cell/gridoptions/gutter-width.tsx @@ -0,0 +1,36 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const gutterwidth: React.FC = () => ( + + + + + + + + +); + +export default gutterwidth; diff --git a/site/components/illustrations/components/grid-cell/gridoptions/margin-width.tsx b/site/components/illustrations/components/grid-cell/gridoptions/margin-width.tsx new file mode 100644 index 0000000000..fd8d9f7573 --- /dev/null +++ b/site/components/illustrations/components/grid-cell/gridoptions/margin-width.tsx @@ -0,0 +1,91 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const marginwidth: React.FC = () => ( + + + + + + + + + + + + + + + + + + + + + +); + +export default marginwidth; diff --git a/site/components/illustrations/components/grid-cell/gridoptions/max-width.tsx b/site/components/illustrations/components/grid-cell/gridoptions/max-width.tsx new file mode 100644 index 0000000000..33cfafcfb7 --- /dev/null +++ b/site/components/illustrations/components/grid-cell/gridoptions/max-width.tsx @@ -0,0 +1,83 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const maxwidth: React.FC = () => ( + + + + + + + + + + + + + + + + + + + +); + +export default maxwidth; diff --git a/site/components/illustrations/components/grid-cell/hero.tsx b/site/components/illustrations/components/grid-cell/hero.tsx new file mode 100644 index 0000000000..2756507545 --- /dev/null +++ b/site/components/illustrations/components/grid-cell/hero.tsx @@ -0,0 +1,73 @@ +import React from 'react'; +import {Svg} from '../../svg'; +import {Rect} from '../../rect'; + +export const hero: React.FC = () => ( + + + + + + + + + + +); + +export default hero; diff --git a/site/components/illustrations/components/grid-cell/usage/do-01.tsx b/site/components/illustrations/components/grid-cell/usage/do-01.tsx new file mode 100644 index 0000000000..537849db5e --- /dev/null +++ b/site/components/illustrations/components/grid-cell/usage/do-01.tsx @@ -0,0 +1,41 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const do01: React.FC = () => ( + + + + + + + + +); + +export default do01; diff --git a/site/components/illustrations/components/grid-cell/usage/dont-01.tsx b/site/components/illustrations/components/grid-cell/usage/dont-01.tsx new file mode 100644 index 0000000000..b7eba74a0e --- /dev/null +++ b/site/components/illustrations/components/grid-cell/usage/dont-01.tsx @@ -0,0 +1,241 @@ +import React from 'react'; +import {getSSRId} from 'newskit'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const dont01: React.FC = () => { + const filter0 = getSSRId(); + const filter1 = getSSRId(); + + return ( + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ); +}; + +export default dont01; diff --git a/site/components/illustrations/components/grid-cell/usage/dont-02.tsx b/site/components/illustrations/components/grid-cell/usage/dont-02.tsx new file mode 100644 index 0000000000..1911be1696 --- /dev/null +++ b/site/components/illustrations/components/grid-cell/usage/dont-02.tsx @@ -0,0 +1,42 @@ +import React from 'react'; +import {Svg} from '../../../svg'; +import {Path} from '../../../path'; + +export const dont02: React.FC = () => ( + + + + + + + + + + + +); + +export default dont02; diff --git a/site/pages/components/grid.mdx b/site/pages/components/grid.mdx deleted file mode 100644 index 9934a80dc2..0000000000 --- a/site/pages/components/grid.mdx +++ /dev/null @@ -1,190 +0,0 @@ -import Layout from '../../components/layout'; -import Playground from '../../components/playground'; -import Prop from '../../components/prop'; -import {LegacyBlock} from '../../components/legacy-block'; - -export default Layout; - -# Grid & Cell - -## Overview - -### Usage - -The Grid and Cell components are used together to construct a visual grid for responsive page layout. The Grid containers children must be Cell components, which can span different widths at each of the 5 breakpoints. - -The 5 breakpoints (xs, sm, md, lg, xl) widths are set via the theme, as are the grid settings. The NewsKit light default grid settings are as follows (set in `componentDefaults`): - -| Setting | Default Value | Explanation | -| --------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| maxWidth | 1920px | The maximum width of the Grid container component. The Grid will not grow bigger than 1920px wide. | -| containerMargin | space040, space050 | The margin either side of the Grid container component. The margin can be different for each breakpoint. By default it is space040 for xs, sm & md, and space050 for lg & xl. | -| columnGutters | space040, space050 | The spacing between each Cell component column (i.e. left and right). The margin can be different for each breakpoint. By default it is space040 for xs, sm & md, and space050 for lg & xl. | -| rowGutters | space040, space050 | The spacing between each Cell component row (i.e. top and bottom when Cells are wrapped). The margin can be different for each breakpoint. By default it is space040 for xs, sm & md, and space050 for lg & xl. | -| columns | 12 | The total columns available to use. Each Cell by default takes up 1 column. If there are more Cells in a Grid than columns, or the Cell components inside a Grid span a total greater than 12, they will wrap. | - -## Grid Props - - - - The Cell components must be used as children of the Grid. Using anything - other than the Cell components will break the Grid functionality. - - - An override for the grid margin spacing at the xs and upwards breakpoint. - - - An override for the grid margin spacing at the sm and upwards breakpoint. - - - An override for the grid margin spacing at the md and upwards breakpoint. - - - An override for the grid margin spacing at the lg and upwards breakpoint. - - - An override for the grid margin spacing at the xl breakpoint. - - - An override for the column gutter spacing at the xs and upwards breakpoint. - This applies to all direct children cells, but not the cells in further - nested grids. - - - An override for the column gutter spacing at the sm and upwards breakpoint. - This applies to all direct children cells, but not the cells in further - nested grids. - - - An override for the column gutter spacing at the md and upwards breakpoint. - This applies to all direct children cells, but not the cells in further - nested grids. - - - An override for the column gutter spacing at the lg and upwards breakpoint. - This applies to all direct children cells, but not the cells in further - nested grids. - - - An override for the column gutter spacing at the xl breakpoint. This applies - to all direct children cells, but not the cells in further nested grids. - - - An override for the row gutter spacing at the xs and upwards breakpoint. - This applies to all direct children cells, but not the cells in further - nested grids. - - - An override for the row gutter spacing at the sm and upwards breakpoint. - This applies to all direct children cells, but not the cells in further - nested grids. - - - An override for the row gutter spacing at the md and upwards breakpoint. - This applies to all direct children cells, but not the cells in further - nested grids. - - - An override for the row gutter spacing at the lg and upwards breakpoint. - This applies to all direct children cells, but not the cells in further - nested grids. - - - An override for the row gutter spacing at the xl breakpoint. This applies to - all direct children cells, but not the cells in further nested grids. - - - -## Cell Props - - - - The children of a column are rendered in that column, any supported React - node is allowed. - - - The amount of columns for Cell to span at the xs and upwards breakpoint. If - set to "full-width" the Cell will span all 12 columns and breakout across - the margin of the Grid. It will still be confined by the Grid's max-width. - - - The amount of columns for Cell to span at the sm and upwards breakpoint. If - set to "full-width" the Cell will span all 12 columns and breakout across - the margin of the Grid. It will still be confined by the Grid's max-width. - - - The amount of columns for Cell to span at the md and upwards breakpoint. If - set to "full-width" the Cell will span all 12 columns and breakout across - the margin of the Grid. It will still be confined by the Grid's max-width. - - - The amount of columns for Cell to span at the lg and upwards breakpoint. If - set to "full-width" the Cell will span all 12 columns and breakout across - the margin of the Grid. It will still be confined by the Grid's max-width. - - - The amount of columns for Cell to span at the xl breakpoint. If set to - "full-width" the Cell will span all 12 columns and breakout across the - margin of the Grid. It will still be confined by the Grid's max-width. - - - If true, the Cell will be hidden at the xs breakpoint. Unlike other - breakpoint props this has no effect on other breakpoints. - - - If true, the Cell will be hidden at the sm breakpoint. Unlike other - breakpoint props this has no effect on other breakpoints. - - - If true, the Cell will be hidden at the md breakpoint. Unlike other - breakpoint props this has no effect on other breakpoints. - - - If true, the Cell will be hidden at the lg breakpoint. Unlike other - breakpoint props this has no effect on other breakpoints. - - - If true, the Cell will be hidden at the lg breakpoint. Unlike other - breakpoint props this has no effect on other breakpoints. - - - If set, this is the flex order number than will be applied at the xs and - upwards breakpoint. - - - If set, this is the flex order number than will be applied at the sm and - upwards breakpoint. - - - If set, this is the flex order number than will be applied at the md and - upwards breakpoint. - - - If set, this is the flex order number than will be applied at the lg and - upwards breakpoint. - - - If set, this is the flex order number than will be applied at the xl - breakpoint. - - - If set, specifies the amount of columns the cell will be offset by at the xs - and larger breakpoints. - - - If set, specifies the amount of columns the cell will be offset by at the sm - and larger breakpoints. - - - If set, specifies the amount of columns the cell will be offset by at the md - and larger breakpoints. - - - If set, specifies the amount of columns the cell will be offset by at the lg - and larger breakpoints. - - - If set, specifies the amount of columns the cell will be offset by at the xl - breakpoint. - - diff --git a/site/pages/components/grid.tsx b/site/pages/components/grid.tsx new file mode 100644 index 0000000000..a1a702ab7a --- /dev/null +++ b/site/pages/components/grid.tsx @@ -0,0 +1,815 @@ +import React from 'react'; +import {Block, InlineMessage, toNewsKitIcon} from 'newskit'; +import {Info as FilledInfo} from '@emotion-icons/material/Info'; +import {ComponentPageTemplate} from '../../templates/component-page-template'; +import {LayoutProps} from '../../components/layout'; +import {MetaStatus} from '../../components/meta/types'; +import {getIllustrationComponent} from '../../components/illustrations/illustration-loader'; +import {Link} from '../../components/link'; +import {UsageKind} from '../../components/usage-card'; +import {ContentText} from '../../components/text-section/content-text'; + +const IconFilledInfo = toNewsKitIcon(FilledInfo); + +const infoIcon = ( + +); + +const gridPropsRows = [ + { + name: 'children', + type: 'Cell', + default: undefined, + description: `The cell components must be used as children of the grid. Using anything other than the cell components will break the grid functionality.`, + required: true, + }, + { + name: 'xsMargin', + type: 'string', + default: 'space040', + description: ( + <> + An override for the grid margin spacing at the xs and upwards + breakpoint. + + ), + required: undefined, + }, + { + name: 'smMargin', + type: 'string', + default: 'space040', + description: ( + <> + An override for the grid margin spacing at the sm and upwards + breakpoint. + + ), + required: undefined, + }, + { + name: 'mdMargin', + type: 'string', + default: 'space040', + description: ( + <> + An override for the grid margin spacing at the md and upwards + breakpoint. + + ), + required: undefined, + }, + { + name: 'lgMargin', + type: 'string', + default: 'space050', + description: ( + <> + An override for the grid margin spacing at the lg and upwards + breakpoint. + + ), + required: undefined, + }, + { + name: 'xlMargin', + type: 'string', + default: 'space050', + description: ( + <> + An override for the grid margin spacing at the xl breakpoint. + + ), + required: undefined, + }, + { + name: 'xsColumnGutter', + type: 'string', + default: 'space040', + description: ( + <> + An override for the column gutter spacing at the xs and upwards + breakpoint. This applies to all direct children cells, but not the cells + in further nested grids. + + ), + required: undefined, + }, + { + name: 'smColumnGutter', + type: 'string', + default: 'space040', + description: ( + <> + An override for the column gutter spacing at the sm and upwards + breakpoint. This applies to all direct children cells, but not the cells + in further nested grids. + + ), + required: undefined, + }, + { + name: 'mdColumnGutter', + type: 'string', + default: 'space040', + description: ( + <> + An override for the column gutter spacing at the md and upwards + breakpoint. This applies to all direct children cells, but not the cells + in further nested grids. + + ), + required: undefined, + }, + { + name: 'lgColumnGutter', + type: 'string', + default: 'space050', + description: ( + <> + An override for the column gutter spacing at the lg and upwards + breakpoint. This applies to all direct children cells, but not the cells + in further nested grids. + + ), + required: undefined, + }, + { + name: 'xlColumnGutter', + type: 'string', + default: 'space050', + description: ( + <> + An override for the column gutter spacing at the xl breakpoint. + This applies to all direct children cells, but not the cells in further + nested grids. + + ), + required: undefined, + }, + { + name: 'xsRowGutter', + type: 'string', + default: 'space040', + description: ( + <> + An override for the row gutter spacing at the xs and upwards + breakpoint. This applies to all direct children cells, but not the cells + in further nested grids. + + ), + required: undefined, + }, + { + name: 'smRowGutter', + type: 'string', + default: 'space040', + description: ( + <> + An override for the row gutter spacing at the sm and upwards + breakpoint. This applies to all direct children cells, but not the cells + in further nested grids. + + ), + required: undefined, + }, + { + name: 'mdRowGutter', + type: 'string', + default: 'space040', + description: ( + <> + An override for the row gutter spacing at the md and upwards + breakpoint. This applies to all direct children cells, but not the cells + in further nested grids. + + ), + required: undefined, + }, + { + name: 'lgRowGutter', + type: 'string', + default: 'space050', + description: ( + <> + An override for the row gutter spacing at the lg and upwards + breakpoint. This applies to all direct children cells, but not the cells + in further nested grids. + + ), + required: undefined, + }, + { + name: 'xlRowGutter', + type: 'string', + default: 'space050', + description: ( + <> + An override for the row gutter spacing at the xl breakpoint. This + applies to all direct children cells, but not the cells in further + nested grids. + + ), + required: undefined, + }, + { + name: 'maxWidth', + type: 'string', + default: '1920px', + description: + 'The maximum width of the Grid container component. The Grid will not grow bigger than 1920px wide.', + required: undefined, + }, +]; + +const GridCellComponent = (layoutProps: LayoutProps) => ( + + + This demo + {' '} + allows you to preview the grid, the variations, and configuration + options. + + ), + }} + anatomy={{ + introduction: + 'The grid contains no required elements and five optional elements.', + media: getIllustrationComponent('components/grid-cell/anatomy'), + rows: [ + { + name: 'Column', + description: + 'The NewsKit grid has 12 columns. The width of the columns depends on the size of the grid.', + optional: true, + }, + { + name: 'Column gutter', + description: + 'The space between columns are called gutters. These are fixed sizes but vary at different breakpoints.', + optional: true, + }, + { + name: 'Container margin', + description: + 'The container margins are on the outside edges of the grid, providing space between the edge of the screen and the grid.', + optional: true, + }, + { + name: 'Cell', + description: + 'Cells are used to contain the content. They can span any number of columns, resize with the grid and change at different breakpoints.', + optional: true, + }, + { + name: 'Row gutter', + description: + 'The spacing between each cell row (i.e. top and bottom when cells are wrapped) is called the row gutters. These can vary at different breakpoints.', + optional: true, + }, + ], + }} + options={{ + components: [ + { + title: 'Grid options', + introduction: + 'The grid has the following options to provide an appropriate experience for different scenarios.', + cards: [ + { + title: 'Breakpoints', + description: ( + <> + There are 5 breakpoints. The breakpoint ranges can be set via + the{' '} + + theme breakpoint values. + + + ), + + media: getIllustrationComponent( + 'components/grid-cell/gridoptions/breakpoints', + ), + }, + { + title: 'Gutter width', + description: + 'The gutter width can be set for each breakpoint. These can be set via the theme or overridden at the component level.', + + media: getIllustrationComponent( + 'components/grid-cell/gridoptions/gutter-width', + ), + }, + { + title: 'Margin width', + description: + 'The margin width can be set for each breakpoint. These can be set via the theme or overridden at the component level.', + + media: getIllustrationComponent( + 'components/grid-cell/gridoptions/margin-width', + ), + }, + { + title: 'Max width', + description: + 'The maximum width of the grid can be set. This can be set via the theme or overridden at the component level.', + + media: getIllustrationComponent( + 'components/grid-cell/gridoptions/max-width', + ), + }, + ], + }, + { + title: 'Cell options', + introduction: + 'Cells have the following options to provide an appropriate experience for different scenarios.', + cards: [ + { + title: 'Span', + description: + 'Cells can be set to span any number of columns in the grid. If set to ‘full-width’ the cell will span all 12 columns and breakout across the margin of the grid. It will still be confined by the grids max-width.', + + media: getIllustrationComponent( + 'components/grid-cell/celloptions/span', + ), + }, + { + title: 'Order', + description: + 'The order that cells appear can be changed at different breakpoints.', + + media: getIllustrationComponent( + 'components/grid-cell/celloptions/order', + ), + }, + { + title: 'Visibility', + description: + 'Cells can be set to be hidden at different breakpoints.', + + media: getIllustrationComponent( + 'components/grid-cell/celloptions/visibility', + ), + }, + { + title: 'Offset', + description: + 'Cells can be set to be offset by a specified number of columns.', + + media: getIllustrationComponent( + 'components/grid-cell/celloptions/offset', + ), + }, + ], + }, + ], + cards: [], + }} + behaviors={{ + title: 'Grid behaviours', + introduction: 'The following guidance describes how the grid behaves.', + cards: [ + { + title: 'Max-width', + description: + 'When the maximum width of the grid is reached, the grid will become fixed and the margins grow to fill the screen.', + media: getIllustrationComponent( + 'components/grid-cell/behaviours/max-width', + ), + }, + { + title: 'Nested grids', + description: ( + <> + A grid can be{' '} + + nested inside of a parent grid + {' '} + by adding it to a cell of that grid. + + ), + media: getIllustrationComponent( + 'components/grid-cell/behaviours/nested-grids', + ), + }, + ], + }} + usage={{ + introduction: + 'The following guidance describes how and when to appropriately use the grid.', + layout: '2-span', + cards: [ + { + description: + 'Align your content. Whenever possible, make sure page elements are lined up both horizontally and/or vertically.', + kind: UsageKind.DO, + media: getIllustrationComponent('components/grid-cell/usage/do-01'), + }, + { + description: + 'Avoid aligning everything to the grid. Individual elements within the cells should align with each other rather than with the grid columns.', + kind: UsageKind.DONT, + media: getIllustrationComponent('components/grid-cell/usage/dont-01'), + }, + { + description: + 'Avoid making gutters too wide. They should be balanced against the column width to ensure page elements relate to each other.', + kind: UsageKind.DONT, + media: getIllustrationComponent('components/grid-cell/usage/dont-02'), + }, + ], + }} + accessibility={{ + introduction: ( + <> + The grid has the following accessibility considerations: + + + Content passed to cells can be set as{' '} + + visible and hidden + {' '} + at different breakpoints. When used 'hidden' excludes + content from focus order when the screen size matches the applied + breakpoint. + + + ), + }} + componentAPI={{ + components: [ + { + title: 'Grid', + summary: + 'The grid has a range of props that can be used to define an appropriate experience for different use cases.', + propsRows: gridPropsRows, + }, + { + title: 'Cell', + summary: `The cell has a range of props that can be used to define an appropriate experience for different use cases.`, + propsRows: [ + { + name: 'children', + type: 'React.ReactNode', + default: '', + description: + 'The children of a column are rendered in that column, any supported React node is allowed.', + required: true, + }, + { + name: 'xs', + type: 'number | ‘full-width’', + default: '1', + description: ( + <> + The amount of columns for cell to span at the xs and + upwards breakpoint. If set to 'full-width' the cell + will span all 12 columns and breakout across the margin of the + grid. It will still be confined by the grid 's max-width. + + ), + required: undefined, + }, + { + name: 'sm', + type: 'number | ‘full-width’', + default: '1', + description: ( + <> + The amount of columns for cell to span at the sm and + upwards breakpoint. If set to 'full-width' the cell + will span all 12 columns and breakout across the margin of the + grid. It will still be confined by the grid 's max-width. + + ), + required: undefined, + }, + { + name: 'md', + type: 'number | ‘full-width’', + default: '1', + description: ( + <> + The amount of columns for cell to span at the md and + upwards breakpoint. If set to 'full-width' the cell + will span all 12 columns and breakout across the margin of the + grid. It will still be confined by the grid 's max-width. + + ), + required: undefined, + }, + { + name: 'lg', + type: 'number | ‘full-width’', + default: '1', + description: ( + <> + The amount of columns for cell to span at the lg and + upwards breakpoint. If set to 'full-width' the cell + will span all 12 columns and breakout across the margin of the + grid. It will still be confined by the grid 's max-width. + + ), + required: undefined, + }, + { + name: 'xl', + type: 'number | ‘full-width’', + default: '1', + description: ( + <> + The amount of columns for cell to span at the xl and + upwards breakpoint. If set to 'full-width' the cell + will span all 12 columns and breakout across the margin of the + grid. It will still be confined by the grid 's max-width. + + ), + required: undefined, + }, + { + name: 'xsHidden', + type: 'boolean', + default: 'false', + description: ( + <> + If true, the Cell will be hidden at the xs breakpoint. + Unlike other breakpoint props this has no effect on other + breakpoints. + + ), + required: undefined, + }, + { + name: 'smHidden', + type: 'boolean', + default: 'false', + description: ( + <> + If true, the Cell will be hidden at the sm breakpoint. + Unlike other breakpoint props this has no effect on other + breakpoints. + + ), + required: undefined, + }, + { + name: 'mdHidden', + type: 'boolean', + default: 'false', + description: ( + <> + If true, the Cell will be hidden at the md breakpoint. + Unlike other breakpoint props this has no effect on other + breakpoints. + + ), + required: undefined, + }, + { + name: 'lgHidden', + type: 'boolean', + default: 'false', + description: ( + <> + If true, the Cell will be hidden at the lg breakpoint. + Unlike other breakpoint props this has no effect on other + breakpoints. + + ), + required: undefined, + }, + { + name: 'xlHidden', + type: 'boolean', + default: 'false', + description: ( + <> + If true, the Cell will be hidden at the xl breakpoint. + Unlike other breakpoint props this has no effect on other + breakpoints. + + ), + required: undefined, + }, + { + name: 'xsOrder', + type: 'number', + description: ( + <> + If set, this is the flex order number than will be applied at + the xs and upwards breakpoint. + + ), + required: undefined, + }, + { + name: 'smOrder', + type: 'number', + description: ( + <> + If set, this is the flex order number than will be applied at + the sm and upwards breakpoint. + + ), + required: undefined, + }, + { + name: 'mdOrder', + type: 'number', + description: ( + <> + If set, this is the flex order number than will be applied at + the md and upwards breakpoint. + + ), + required: undefined, + }, + { + name: 'lgOrder', + type: 'number', + description: ( + <> + If set, this is the flex order number than will be applied at + the lg and upwards breakpoint. + + ), + required: undefined, + }, + { + name: 'xlOrder', + type: 'number', + description: ( + <> + If set, this is the flex order number than will be applied at + the xl and upwards breakpoint. + + ), + required: undefined, + }, + { + name: 'xsOffset', + type: 'number', + description: ( + <> + If set, specifies the amount of columns the cell will be + offset by at the xs and larger breakpoints. + + ), + required: undefined, + }, + { + name: 'smOffset', + type: 'number', + description: ( + <> + If set, specifies the amount of columns the cell will be + offset by at the sm and larger breakpoints. + + ), + required: undefined, + }, + { + name: 'mdOffset', + type: 'number', + description: ( + <> + If set, specifies the amount of columns the cell will be + offset by at the md and larger breakpoints. + + ), + required: undefined, + }, + { + name: 'lgOffset', + type: 'number', + description: ( + <> + If set, specifies the amount of columns the cell will be + offset by at the lg and larger breakpoints. + + ), + required: undefined, + }, + { + name: 'xlOffset', + type: 'number', + description: ( + <> + If set, specifies the amount of columns the cell will be + offset by at the xl breakpoints. + + ), + required: undefined, + }, + ], + propsFooter: ( + <> + + The number of columns are set globally at the theme level. + + + ), + }, + { + title: 'Grid component defaults', + summary: 'The grid has a range of predefined defaults.', + overridesRows: [ + { + attribute: 'grid.containerMargin', + type: 'MQ', + default: [ + 'xs = space04', + 'sm = space040', + 'md = space040', + 'lg = space050', + 'xl = space050', + ], + description: + 'An override for the grid margin spacing at a specific breakpoint and upwards. and upwards breakpoint.', + }, + { + attribute: 'grid.columnGutters', + type: 'String', + default: [ + 'xs = space04', + 'sm = space040', + 'md = space040', + 'lg = space050', + 'xl = space050', + ], + description: + 'An override for the column gutter spacing at a specific breakpoint and upwards. This applies to all direct children cells, but not the cells in further nested grids.', + }, + { + attribute: 'grid.rowGutters', + type: 'String', + default: [ + 'xs = space04', + 'sm = space040', + 'md = space040', + 'lg = space050', + 'xl = space050', + ], + description: + 'An override for the row gutter spacing at a specific breakpoint and upwards.. This applies to all direct children cells, but not the cells in further nested grids.', + }, + { + attribute: 'grid.columns', + type: 'number', + default: '12', + description: + 'The total columns available to use. Each Cell by default takes up 1 column. If there are more Cells in a Grid than columns, or the Cell components inside a Grid span a total greater than 12, they will wrap.', + }, + ], + }, + ], + }} + related={{ + related: ['Grid Layout', 'Block', 'Stack', 'Visibility'], + }} + /> +); +export default GridCellComponent; diff --git a/site/routes.ts b/site/routes.ts index 95a922a434..56f607ca68 100644 --- a/site/routes.ts +++ b/site/routes.ts @@ -532,7 +532,7 @@ export const routes = [ page: true, id: '/components/grid', description: - 'Used together to construct a visual grid for responsive page layout.', + 'The grid and cell are used together to construct a visual grid for responsive page layout.', illustration: 'components/grid-cell-illustration', }, { diff --git a/site/templates/template-sections/interactive-demo-section.tsx b/site/templates/template-sections/interactive-demo-section.tsx index 3c6c3d97d4..1e7ad02b6e 100644 --- a/site/templates/template-sections/interactive-demo-section.tsx +++ b/site/templates/template-sections/interactive-demo-section.tsx @@ -6,8 +6,8 @@ import {ComponentPageCell} from '../../components/layout-cells'; import {CommonSection} from './common-section'; export interface InteractiveDemoSectionProps { - introduction: string; - playground: PlaygroundProps; + introduction: string | React.ReactElement; + playground?: PlaygroundProps; } export const InteractiveDemoSection: React.FC = ({ @@ -19,10 +19,12 @@ export const InteractiveDemoSection: React.FC = ({ id="interactive-demo" introduction={introduction} > - - - - - + {playground && ( + + + + + + )} ); diff --git a/site/templates/template-sections/options-section.tsx b/site/templates/template-sections/options-section.tsx index f17e914cc6..02a16d9939 100644 --- a/site/templates/template-sections/options-section.tsx +++ b/site/templates/template-sections/options-section.tsx @@ -4,25 +4,64 @@ import {IntroductionText} from './types'; import {CommonSection} from './common-section'; import {ComponentPageCell} from '../../components/layout-cells'; -export type OptionsSectionProps = MediaListProps & IntroductionText; +export type SingleComponentOptionsProps = IntroductionText & MediaListProps; + +export interface OptionsComponentsProps { + components?: SingleComponentOptionsProps[]; +} + +export type OptionsSectionProps = MediaListProps & + IntroductionText & + OptionsComponentsProps; export const OptionsSection: React.FC = ({ + title, introduction, + components, ...options -}) => ( - - - - - -); +}) => { + const renderOptionsSection = ( + optionsTitle?: string, + optionsIntroduction?: string | React.ReactElement, + optionsCards?: MediaListProps, + ) => ( + + + {optionsCards && ( + + )} + + + ); + return ( + <> + {components ? ( + components.map( + ({ + title: renderTitle, + introduction: renderIntroduction, + ...props + }) => ( + <>{renderOptionsSection(renderTitle, renderIntroduction, props)} + ), + ) + ) : ( + <>{renderOptionsSection(title, introduction, options)} + )} + + ); +}; diff --git a/site/templates/template-sections/types.ts b/site/templates/template-sections/types.ts index bc018448fa..dafab02833 100644 --- a/site/templates/template-sections/types.ts +++ b/site/templates/template-sections/types.ts @@ -1,3 +1,4 @@ export interface IntroductionText { + title?: string; introduction?: string | React.ReactElement; }