@simplybusiness/mobius 3.0.0

package/src/components/Grid/Grid.story.mdx

@@ -0,0 +1,807 @@
+import { useState, Fragment } from "react";
+import styled from "@emotion/styled";
+import { Meta, ArgsTable, Story } from "@storybook/addon-docs";
+import { Grid } from ".";
+import { Box } from "../Box";
+import { Flex } from "../Flex";
+import { RadioGroup, Radio, Select } from "../Radio";
+
+import { ThemeContext } from "../../contexts";
+
+export const sizeOptions = [
+  "",
+  "size-0",
+  "size-10",
+  "size-20",
+  "size-30",
+  "size-40",
+  "size-50",
+  "size-60",
+  "size-70",
+  "size-80",
+  "size-90",
+  "size-100",
+];
+
+<Meta
+  title="Layout/Grid"
+  component={Grid}
+  argTypes={{
+    columns: {
+      control: "number",
+    },
+    gap: {
+      control: "select",
+      options: [...sizeOptions],
+    },
+    rowGap: {
+      control: "select",
+      options: [...sizeOptions],
+      if: {
+        arg: "gap",
+        truthy: false,
+      },
+    },
+    columnGap: {
+      control: "select",
+      options: [...sizeOptions],
+      if: {
+        arg: "gap",
+        truthy: false,
+      },
+    },
+    alignContent: {
+      control: "select",
+      options: [
+        "",
+        "center",
+        "space-around",
+        "space-between",
+        "space-evenly",
+        "stretch",
+      ],
+    },
+    justifyContent: {
+      control: "select",
+      options: [
+        "",
+        "center",
+        "start",
+        "end",
+        "space-around",
+        "space-between",
+        "space-evenly",
+      ],
+    },
+    alignItems: {
+      control: "select",
+      options: ["", "center", "start", "end", "stretch", "baseline"],
+    },
+    justifyItems: {
+      control: "select",
+      options: ["", "start", "end", "center", "stretch"],
+    },
+  }}
+/>
+
+# Grid
+
+Grid helps create layouts based on a vertical grid of columns. It uses Flexbox to position the elements in the grid.
+
+- A grid is made of a container and several items
+- The space between the items is fixed and can be configured with the `gap`, `columnGap` or `rowGap` props
+- The width of each item is determined by the number of columns it spans across, which can be configured with the `span` prop
+
+## Install
+
+```bash
+yarn add @simplybusiness/mobius
+```
+
+## Usage
+
+```js
+import { Grid } from "@simplybusiness/mobius";
+```
+
+## Playground
+
+export const Card = ({ children, ...props }) => (
+  <Box
+    style={{
+      borderRadius: "4px",
+      padding: "8px",
+      backgroundColor: "#dddddd",
+      width: "80%",
+    }}
+    {...props}
+  >
+    {children}
+  </Box>
+);
+
+export const DynamicGrid = () => {
+  let [spacing, setSpacing] = useState("size-20");
+  let [columns, setColumns] = useState(12);
+  return (
+    <Fragment>
+      <Grid columnGap={spacing} rowGap={spacing} columns={columns}>
+        {[...new Array(12)].map((_, i) => (
+          <Grid.Item key={i} columns={columns} span={1}>
+            <Card>Item</Card>
+          </Grid.Item>
+        ))}
+      </Grid>
+      <Flex
+        style={{
+          borderWidth: 1,
+          borderColor: "grey",
+          padding: "16px",
+          marginTop: "16px",
+        }}
+      >
+        <Box style={{ marginRight: "32px" }}>
+          <RadioGroup label="Columns" value={columns} onChange={setColumns}>
+            <Flex flexDirection="column">
+              <Radio value={12}>12</Radio>
+              <Radio value={8}>8</Radio>
+              <Radio value={4}>4</Radio>
+              <Radio value={2}>2</Radio>
+            </Flex>
+          </RadioGroup>
+        </Box>
+        <Box>
+          <RadioGroup label="Spacing" value={spacing} onChange={setSpacing}>
+            <Flex flexDirection="column">
+              <Radio value="size-0">size-0</Radio>
+              <Radio value="size-10">size-10</Radio>
+              <Radio value="size-20">size-20</Radio>
+              <Radio value="size-30">size-30</Radio>
+              <Radio value="size-40">size-40</Radio>
+              <Radio value="size-50">size-50</Radio>
+            </Flex>
+          </RadioGroup>
+        </Box>
+      </Flex>
+    </Fragment>
+  );
+};
+
+<DynamicGrid />
+
+Different items can have different widths. This is especially useful when creating layouts with sidebars.
+
+<Grid gap="size-20">
+  <Grid.Item span={12}>
+    <Card>span=12</Card>
+  </Grid.Item>
+  <Grid.Item span={11}>
+    <Card>span=11</Card>
+  </Grid.Item>
+  <Grid.Item span={1}>
+    <Card>span=1</Card>
+  </Grid.Item>
+  <Grid.Item span={10}>
+    <Card>span=10</Card>
+  </Grid.Item>
+  <Grid.Item span={2}>
+    <Card>span=2</Card>
+  </Grid.Item>
+  <Grid.Item span={9}>
+    <Card>span=9</Card>
+  </Grid.Item>
+  <Grid.Item span={3}>
+    <Card>span=3</Card>
+  </Grid.Item>
+  <Grid.Item span={8}>
+    <Card>span=8</Card>
+  </Grid.Item>
+  <Grid.Item span={4}>
+    <Card>span=4</Card>
+  </Grid.Item>
+  <Grid.Item span={7}>
+    <Card>span=7</Card>
+  </Grid.Item>
+  <Grid.Item span={5}>
+    <Card>span=5</Card>
+  </Grid.Item>
+  <Grid.Item span={6}>
+    <Card>span=6</Card>
+  </Grid.Item>
+  <Grid.Item span={6}>
+    <Card>span=6</Card>
+  </Grid.Item>
+</Grid>
+
+```jsx
+import { Grid } from "@simplybusiness/mobius";
+
+// Card component is here only for demonstration purposes
+const Card = ({ children, ...props }) => (
+  <Box
+    style={{
+      borderRadius: "4px",
+      padding: "8px",
+      backgroundColor: "#dddddd",
+      width: "100%",
+    }}
+    {...props}
+  >
+    {children}
+  </Box>
+);
+
+<Grid gap="size-20">
+  <Grid.Item span={12}>
+    <Card>span=12</Card>
+  </Grid.Item>
+  <Grid.Item span={11}>
+    <Card>span=11</Card>
+  </Grid.Item>
+  <Grid.Item span={1}>
+    <Card>span=1</Card>
+  </Grid.Item>
+  <Grid.Item span={10}>
+    <Card>span=10</Card>
+  </Grid.Item>
+  <Grid.Item span={2}>
+    <Card>span=2</Card>
+  </Grid.Item>
+  <Grid.Item span={9}>
+    <Card>span=9</Card>
+  </Grid.Item>
+  <Grid.Item span={3}>
+    <Card>span=3</Card>
+  </Grid.Item>
+  <Grid.Item span={8}>
+    <Card>span=8</Card>
+  </Grid.Item>
+  <Grid.Item span={4}>
+    <Card>span=4</Card>
+  </Grid.Item>
+  <Grid.Item span={7}>
+    <Card>span=7</Card>
+  </Grid.Item>
+  <Grid.Item span={5}>
+    <Card>span=5</Card>
+  </Grid.Item>
+  <Grid.Item span={6}>
+    <Card>span=6</Card>
+  </Grid.Item>
+  <Grid.Item span={6}>
+    <Card>span=6</Card>
+  </Grid.Item>
+</Grid>;
+```
+
+### Alignment
+
+Grid items can be aligned using the standard grid alignment properties:
+
+- `align-content`
+- `justify-content`
+- `align-items`
+- `justify-items`
+
+export const Square = ({ children, ...props }) => (
+  <Flex
+    alignItems="center"
+    justifyContent="center"
+    style={{ height: "100%" }}
+    {...props}
+  >
+    {children}
+  </Flex>
+);
+
+export const FixedSizeGrid = styled(Grid)`
+  max-width: fit-content;
+  max-height: fit-content;
+  border: 1px solid grey;
+  margin-inline: auto;
+`;
+
+export const GridAlignmentItem = styled(Grid.Item)`
+  background-color: #dddddd;
+  width: 50px;
+  height: 50px;
+`;
+
+<Story
+  name="Alignment properties"
+  args={{
+    columns: 12,
+    gap: "size-20",
+    rowGap: "",
+    columnGap: "",
+    alignContent: "",
+    justifyContent: "",
+    alignItems: "stretch",
+    justifyItems: "stretch",
+  }}
+>
+  {args => (
+    <FixedSizeGrid {...args}>
+      <GridAlignmentItem span={4}>
+        <Square>1</Square>
+      </GridAlignmentItem>
+      <GridAlignmentItem span={4}>
+        <Square>2</Square>
+      </GridAlignmentItem>
+      <GridAlignmentItem span={4}>
+        <Square>3</Square>
+      </GridAlignmentItem>
+      <GridAlignmentItem span={4}>
+        <Square>4</Square>
+      </GridAlignmentItem>
+      <GridAlignmentItem span={4}>
+        <Square>5</Square>
+      </GridAlignmentItem>
+      <GridAlignmentItem span={4}>
+        <Square>6</Square>
+      </GridAlignmentItem>
+      <GridAlignmentItem span={4}>
+        <Square>7</Square>
+      </GridAlignmentItem>
+      <GridAlignmentItem span={4}>
+        <Square>8</Square>
+      </GridAlignmentItem>
+      <GridAlignmentItem span={4}>
+        <Square>9</Square>
+      </GridAlignmentItem>
+    </FixedSizeGrid>
+  )}
+</Story>
+
+```jsx
+import { Grid } from "@simplybusiness/mobius";
+
+<FixedSizeGrid gap="size-20">
+  <GridAlignmentItem span={4}>
+    <Square>1</Square>
+  </GridAlignmentItem>
+  <GridAlignmentItem span={4}>
+    <Square>2</Square>
+  </GridAlignmentItem>
+  <GridAlignmentItem span={4}>
+    <Square>3</Square>
+  </GridAlignmentItem>
+  <GridAlignmentItem span={4}>
+    <Square>4</Square>
+  </GridAlignmentItem>
+  <GridAlignmentItem span={4}>
+    <Square>5</Square>
+  </GridAlignmentItem>
+  <GridAlignmentItem span={4}>
+    <Square>6</Square>
+  </GridAlignmentItem>
+  <GridAlignmentItem span={4}>
+    <Square>7</Square>
+  </GridAlignmentItem>
+  <GridAlignmentItem span={4}>
+    <Square>8</Square>
+  </GridAlignmentItem>
+  <GridAlignmentItem span={4}>
+    <Square>9</Square>
+  </GridAlignmentItem>
+</FixedSizeGrid>;
+```
+
+## Examples
+
+### Normal
+
+<Story
+  name="Normal"
+  args={{
+    columns: 12,
+    gap: "size-20",
+    rowGap: "",
+    columnGap: "",
+    alignContent: "",
+    justifyContent: "",
+    alignItems: "stretch",
+    justifyItems: "stretch",
+  }}
+>
+  {args => (
+    <Grid {...args}>
+      <Grid.Item span={12}>
+        <Card>span=12</Card>
+      </Grid.Item>
+      <Grid.Item span={11}>
+        <Card>span=11</Card>
+      </Grid.Item>
+      <Grid.Item span={1}>
+        <Card>span=1</Card>
+      </Grid.Item>
+      <Grid.Item span={10}>
+        <Card>span=10</Card>
+      </Grid.Item>
+      <Grid.Item span={2}>
+        <Card>span=2</Card>
+      </Grid.Item>
+      <Grid.Item span={9}>
+        <Card>span=9</Card>
+      </Grid.Item>
+      <Grid.Item span={3}>
+        <Card>span=3</Card>
+      </Grid.Item>
+      <Grid.Item span={8}>
+        <Card>span=8</Card>
+      </Grid.Item>
+      <Grid.Item span={4}>
+        <Card>span=4</Card>
+      </Grid.Item>
+      <Grid.Item span={7}>
+        <Card>span=7</Card>
+      </Grid.Item>
+      <Grid.Item span={5}>
+        <Card>span=5</Card>
+      </Grid.Item>
+      <Grid.Item span={6}>
+        <Card>span=6</Card>
+      </Grid.Item>
+      <Grid.Item span={6}>
+        <Card>span=6</Card>
+      </Grid.Item>
+    </Grid>
+  )}
+</Story>
+
+```jsx
+import { Grid } from "@simplybusiness/mobius";
+
+// Card component is here only for demonstration purposes
+const Card = ({ children, ...props }) => (
+  <Box
+    style={{
+      borderRadius: "4px",
+      padding: "8px",
+      backgroundColor: "#dddddd",
+      width: "100%",
+    }}
+    {...props}
+  >
+    {children}
+  </Box>
+);
+
+<Grid gap="size-20">
+  <Grid.Item span={12}>
+    <Card>span=12</Card>
+  </Grid.Item>
+  <Grid.Item span={11}>
+    <Card>span=11</Card>
+  </Grid.Item>
+  <Grid.Item span={1}>
+    <Card>span=1</Card>
+  </Grid.Item>
+  <Grid.Item span={10}>
+    <Card>span=10</Card>
+  </Grid.Item>
+  <Grid.Item span={2}>
+    <Card>span=2</Card>
+  </Grid.Item>
+  <Grid.Item span={9}>
+    <Card>span=9</Card>
+  </Grid.Item>
+  <Grid.Item span={3}>
+    <Card>span=3</Card>
+  </Grid.Item>
+  <Grid.Item span={8}>
+    <Card>span=8</Card>
+  </Grid.Item>
+  <Grid.Item span={4}>
+    <Card>span=4</Card>
+  </Grid.Item>
+  <Grid.Item span={7}>
+    <Card>span=7</Card>
+  </Grid.Item>
+  <Grid.Item span={5}>
+    <Card>span=5</Card>
+  </Grid.Item>
+  <Grid.Item span={6}>
+    <Card>span=6</Card>
+  </Grid.Item>
+  <Grid.Item span={6}>
+    <Card>span=6</Card>
+  </Grid.Item>
+</Grid>;
+```
+
+### Eight Columns
+
+<Story
+  name="Eight Columns"
+  args={{
+    columns: 8,
+    gap: "size-20",
+    alignContent: "",
+    justifyContent: "",
+    alignItems: "stretch",
+    justifyItems: "stretch",
+  }}
+>
+  {args => (
+    <Grid style={{ height: 300 }} {...args}>
+      {[...new Array(8)].map((_, k) => (
+        <Card key={k}>span=1</Card>
+      ))}
+    </Grid>
+  )}
+</Story>
+
+```jsx
+import { Grid } from "@simplybusiness/mobius";
+
+// Card component is here only for demonstration purposes
+const Card = ({ children, ...props }) => (
+  <Box
+    style={{
+      borderRadius: "4px",
+      padding: "8px",
+      backgroundColor: "#dddddd",
+      width: "100%",
+    }}
+    {...props}
+  >
+    {children}
+  </Box>
+);
+
+<Grid columns={8} gap="size-20">
+  <Card columns={8}>span=1</Card>
+  <Card columns={8}>span=1</Card>
+  <Card columns={8}>span=1</Card>
+  <Card columns={8}>span=1</Card>
+  <Card columns={8}>span=1</Card>
+  <Card columns={8}>span=1</Card>
+  <Card columns={8}>span=1</Card>
+  <Card columns={8}>span=1</Card>
+</Grid>;
+```
+
+### Responsive
+
+<Story
+  name="Responsive"
+  args={{
+    gap: "size-20",
+    rowGap: "",
+    columnGap: "",
+    alignContent: "",
+    justifyContent: "",
+    alignItems: "stretch",
+    justifyItems: "stretch",
+    xs: 12,
+    sm: 6,
+    md: 2,
+    lg: 8,
+    xl: 12,
+    xxl: 4,
+  }}
+  parameters={{ controls: { exclude: ["columns"] } }}
+  argTypes={() => {
+    const breakpointControl = {
+      control: {
+        type: "number",
+        min: 0,
+        max: 12,
+        step: 1,
+      },
+    };
+    return {
+      xs: breakpointControl,
+      sm: breakpointControl,
+      md: breakpointControl,
+      lg: breakpointControl,
+      xl: breakpointControl,
+      xxl: breakpointControl,
+    };
+  }}
+  decorators={[
+    Story => (
+      <ThemeContext.Provider
+        value={{
+          breakpoints: [
+            { size: "xs", value: 320 },
+            { size: "sm", value: 540 },
+            { size: "md", value: 720 },
+            { size: "lg", value: 960 },
+            { size: "xl", value: 1140 },
+            { size: "xxl", value: 1320 },
+          ],
+        }}
+      >
+        <Story />
+      </ThemeContext.Provider>
+    ),
+  ]}
+>
+  {args => {
+    const breakpointArgs = ["xs", "sm", "md", "lg", "xl", "xxl"];
+    const allArgs = Object.entries(args)
+      .filter(([breakpoint]) => breakpointArgs.includes(breakpoint))
+      .map(([breakpoint, value]) => `${breakpoint}=${value}`)
+      .join(" ");
+    return (
+      <Grid {...args}>
+        <Grid.Item>
+          <Card>{allArgs}</Card>
+        </Grid.Item>
+        <Grid.Item lg={4}>
+          <Card>lg=4</Card>
+        </Grid.Item>
+        <Grid.Item xs={5}>
+          <Card>xs=5</Card>
+        </Grid.Item>
+        <Grid.Item span={5}>
+          <Card>span=5</Card>
+        </Grid.Item>
+      </Grid>
+    );
+  }}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Grid, ThemeContext } from "@simplybusiness/mobius";
+
+// Card component is here only for demonstration purposes
+const Card = ({ children, ...props }) => (
+  <Box
+    style={{
+      borderRadius: "4px",
+      padding: "8px",
+      backgroundColor: "#dddddd",
+      width: "100%",
+    }}
+    {...props}
+  >
+    {children}
+  </Box>
+);
+
+<ThemeContext.Provider
+  value={{
+    breakpoints: [
+      { size: "xs", value: 320 },
+      { size: "sm", value: 540 },
+      { size: "md", value: 720 },
+      { size: "lg", value: 960 },
+      { size: "xl", value: 1140 },
+      { size: "xxl", value: 1320 },
+    ],
+  }}
+>
+  <Grid gap="size-20">
+    <Grid.Item xs={12} sm={6} md={2} lg={8} xl={12} xxl={4}>
+      <Card>xs=12 sm=6 md=2 lg=8 xl=12 xxl=4</Card>
+    </Grid.Item>
+    <Grid.Item lg={4}>
+      <Card>lg=4</Card>
+    </Grid.Item>
+    <Grid.Item xs={5}>
+      <Card>xs=5</Card>
+    </Grid.Item>
+    <Grid.Item span={5}>
+      <Card>span=5</Card>
+    </Grid.Item>
+  </Grid>
+</ThemeContext.Provider>
+```
+
+## Item positioning
+
+Individual grid items may be positioned separately to the rest of the grid items using the following properties:
+
+- `alignSelf` - aligns the grid item along the block (column) axis
+- `justifySelf` - aligns the grid item along the inline (row) axis
+
+The example demonstrates the positioning of the first block. Using `alignSelf="center"` and `justifySelf="end"` places the item in vertical centre (1) and horizontal end (2)
+
+export const AlignSquareItem = styled(Grid.Item)`
+  background-color: #dddddd;
+`;
+
+export const AlignSquare = ({ children, ...props }) => (
+  <Box style={{}} {...props}>
+    {children}
+  </Box>
+);
+
+<Story
+  name="Item positioning"
+  args={{
+    alignSelf: "center",
+    justifySelf: "end",
+  }}
+  argTypes={{
+    alignSelf: {
+      control: "select",
+      options: ["", "center", "start", "end", "stretch"],
+    },
+    justifySelf: {
+      control: "select",
+      options: ["", "center", "start", "end", "stretch"],
+    },
+  }}
+  parameters={{
+    controls: {
+      exclude: [
+        "columns",
+        "gap",
+        "rowGap",
+        "columnGap",
+        "alignContent",
+        "justifyContent",
+        "alignItems",
+        "justifyItems",
+      ],
+    },
+  }}
+>
+  {args => (
+    <FixedSizeGrid
+      columns={12}
+      gap="size-20"
+      alignContent=""
+      justifyContent=""
+      alignItems="stretch"
+      justifyItems="stretch"
+    >
+      <AlignSquareItem span={4} {...args}>
+        <AlignSquare>1</AlignSquare>
+      </AlignSquareItem>
+      <AlignSquareItem span={4}>
+        <AlignSquare>2</AlignSquare>
+      </AlignSquareItem>
+      <AlignSquareItem span={4}>
+        <AlignSquare>3</AlignSquare>
+      </AlignSquareItem>
+      <AlignSquareItem span={4}>
+        <AlignSquare>4</AlignSquare>
+      </AlignSquareItem>
+    </FixedSizeGrid>
+  )}
+</Story>
+
+<!-- prettier-ignore -->
+```jsx
+import { Grid, ThemeContext } from "@simplybusiness/mobius";
+
+// AlignSquareItem component is here only for demonstration purposes
+const AlignSquareItem = styled(Grid.Item)`
+  background-color: #dddddd;
+`;
+
+// AlignSquare component is here only for demonstration purposes
+const AlignSquare = ({ children, ...props }) => (
+  <Box {...props}>
+    {children}
+  </Box>
+);
+<FixedSizeGrid gap="size-20">
+  <AlignSquareItem span={4} alignSelf="center" justifySelf="end">
+    <AlignSquare>1</AlignSquare>
+  </AlignSquareItem>
+  <AlignSquareItem span={4}>
+    <AlignSquare>2</AlignSquare>
+  </AlignSquareItem>
+  <AlignSquareItem span={4}>
+    <AlignSquare>3</AlignSquare>
+  </AlignSquareItem>
+  <AlignSquareItem span={4}>
+    <AlignSquare>4</AlignSquare>
+  </AlignSquareItem>
+</FixedSizeGrid>
+```
+
+## Props
+
+<ArgsTable of={Grid} />
+
+---
+
+[See on Github](https://github.com/simplybusiness/mobius/tree/master/packages/mobius/src/components/Grid) | [Give feedback](https://simplybusiness.atlassian.net/CreateIssue.jspa?issuetype=10103&pid=10609) | [Get support](https://simplybusiness.slack.com/archives/C016CC0NDNE)