@purpurds/grid 4.6.0 → 5.1.0

package/readme.mdx

@@ -1,8 +1,7 @@
 import { Meta, Stories, ArgTypes, Primary, Subtitle } from "@storybook/blocks";
 
 import * as GridStories from "./src/grid.stories";
-import * as GridColStories from "./src/grid.col.stories";
-import * as GridRowStories from "./src/grid.row.stories";
+import * as GridItemStories from "./src/grid.item.stories";
 import packageInfo from "./package.json";
 
 <Meta name="Docs" title="Components/Grid" of={GridStories} />
@@ -21,13 +20,9 @@ import packageInfo from "./package.json";
 
 <ArgTypes of={GridStories} />
 
-#### Grid.Row
+#### Grid.Item
 
-<ArgTypes of={GridRowStories} />
-
-#### Grid.Col
-
-<ArgTypes of={GridColStories} />
+<ArgTypes of={GridItemStories} />
 
 ### Installation
 
@@ -35,6 +30,10 @@ import packageInfo from "./package.json";
 
 Add the dependency to your consumer app like `"@purpurds/purpur": "^x.y.z"`
 
+### Usage
+
+The standard usage is to have multiple elements directly as children of the `Grid` component. It's also possible to only have one, to get the standard page padding, max width and prevent getting gaps between elements.
+
 In MyApp.tsx
 
 ```tsx
@@ -43,23 +42,72 @@ import "@purpurds/purpur/styles";
 
 In MyComponent.tsx
 
+#### Basic grid with same-width columns
+
 ```tsx
 import { Grid } from "@purpurds/purpur";
 
 export const MyComponent = () => {
   return (
-    <div>
-      <Grid style={{ backgroundColor: "green" }}>
-        <Grid.Row>
-          <Grid.Col width={12} widthMd={6}>
-            <p>Column 1</p>
-          </Grid.Col>
-          <Grid.Col width={12} widthMd={6}>
-            <p>Column 2</p>
-          </Grid.Col>
-        </Grid.Row>
+    <Grid colsSm={2} colsMd={4} colsLg={6}>
+      <div>Grid item 1</div>
+      <div>Grid item 2</div>
+      <div>Grid item 3</div>
+      <div>Grid item 4</div>
+      <div>Grid item 5</div>
+      <div>Grid item 6</div>
+    </Grid>
+  );
+};
+```
+
+#### Advanced grid using nested grids
+
+```tsx
+import { Grid } from "@purpurds/purpur";
+
+export const MyComponent = () => {
+  return (
+    <Grid>
+      <Grid colsSm={1} colsMd={3} colsLg={3}>
+        <div>Grid item 1</div>
+        <div>Grid item 2</div>
+        <div>Grid item 3</div>
+      </Grid>
+      <Grid colsSm={1} colsMd={2} colsLg={2}>
+        <div>Grid item 4</div>
+        <div>Grid item 5</div>
       </Grid>
-    </div>
+      <Grid colsSm={1} colsMd={2} colsLg={2}>
+        <div>Grid item 6</div>
+        <div>Grid item 7</div>
+      </Grid>
+    </Grid>
+  );
+};
+```
+
+#### Advanced grid using Grid.Item
+
+```tsx
+import { Grid } from "@purpurds/purpur";
+
+export const MyComponent = () => {
+  return (
+    <Grid>
+      <Grid.Item colSpanSm={2} colSpanMd={5} colSpanLg={3}>
+        Grid item 1
+      </Grid.Item>
+      <Grid.Item colSpanSm={2} colSpanMd={3} colSpanLg={9}>
+        Grid item 2
+      </Grid.Item>
+      <Grid.Item colSpanSm={4} colSpanMd={2} colSpanLg={6}>
+        Grid item 3
+      </Grid.Item>
+      <Grid.Item colSpanSm={4} colSpanMd={6} colSpanLg={6}>
+        Grid item 4
+      </Grid.Item>
+    </Grid>
   );
 };
 ```

package/src/grid.item.module.scss

@@ -0,0 +1,43 @@
+@import "@purpurds/tokens/breakpoint/variables";
+
+.purpur-grid-item {
+  $root: &;
+  --padding: calc(var(--purpur-spacing-gutter-sm) / 2);
+
+  padding: 0 var(--padding);
+  box-sizing: border-box;
+
+  @media screen and (min-width: $purpur-breakpoint-md) {
+    --padding: calc(var(--purpur-spacing-gutter-md) / 2);
+  }
+
+  @media screen and (min-width: $purpur-breakpoint-lg) {
+    --padding: calc(var(--purpur-spacing-gutter-lg) / 2);
+  }
+
+  @media screen and (min-width: $purpur-breakpoint-xl) {
+    --padding: calc(var(--purpur-spacing-gutter-xl) / 2);
+  }
+
+  @for $i from 4 through 1 {
+    &#{$root}-colspan-sm-#{$i} {
+      width: calc($i / 4 * 100%);
+    }
+  }
+
+  @for $i from 8 through 1 {
+    @media screen and (min-width: $purpur-breakpoint-md) {
+      &#{$root}-colspan-md-#{$i} {
+        width: calc($i / 8 * 100%);
+      }
+    }
+  }
+
+  @for $i from 12 through 1 {
+    @media screen and (min-width: $purpur-breakpoint-lg) {
+      &#{$root}-colspan-lg-#{$i} {
+        width: calc($i / 12 * 100%);
+      }
+    }
+  }
+}

package/src/grid.item.stories.tsx

@@ -0,0 +1,47 @@
+/* eslint-disable react/prop-types */
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Grid } from "./grid";
+
+const meta: Meta<typeof Grid.Item> = {
+  title: "Components/Grid",
+  component: Grid.Item,
+  parameters: {
+    design: [
+      {
+        name: "Grid",
+        type: "figma",
+        url: "https://www.figma.com/file/2QIcZVqP99ZKY4rNW7VuSx/Purpur-DS---Foundations-Library?type=design&node-id=5704%3A10669&mode=design&t=lPtp9KR80NhTNx9u-1",
+      },
+    ],
+  },
+  argTypes: {
+    ["data-testid"]: { control: { type: "text" } },
+    className: { control: { type: "text" } },
+    children: { control: { type: "text" } },
+    colSpanSm: { control: { type: "range", min: 1, max: 4, step: 1 } },
+    colSpanMd: { control: { type: "range", min: 1, max: 8, step: 1 } },
+    colSpanLg: { control: { type: "range", min: 1, max: 12, step: 1 } },
+  },
+  args: {
+    colSpanSm: 4,
+    colSpanMd: 8,
+    colSpanLg: 12,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Grid.Item>;
+
+export const Item: Story = {
+  render: ({ children, ...args }) => (
+    <Grid.Item {...args}>
+      <div style={{ border: "1px solid lightgray", padding: ".5rem" }}>
+        <p>Column</p>
+        {children}
+      </div>
+    </Grid.Item>
+  ),
+};

package/src/grid.item.tsx

@@ -0,0 +1,68 @@
+import React, {
+  isValidElement,
+  ReactChild,
+  ReactElement,
+  ReactFragment,
+  ReactNode,
+  ReactPortal,
+} from "react";
+import c from "classnames/bind";
+
+import styles from "./grid.item.module.scss";
+
+const cx = c.bind(styles);
+
+export type ItemProps = {
+  children: ReactNode;
+  ["data-testid"]?: string;
+  className?: string;
+  /** The number of columns that the item spans on small screens. */
+  colSpanSm?: 1 | 2 | 3 | 4;
+  /** The number of columns that the item spans on medium screens. */
+  colSpanMd?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+  /** The number of columns that the item spans on large screens. */
+  colSpanLg?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+};
+
+const rootClassName = "purpur-grid-item";
+
+export const Item = ({
+  children,
+  className,
+  ["data-testid"]: dataTestId,
+  colSpanSm = 4,
+  colSpanMd = 8,
+  colSpanLg = 12,
+}: ItemProps) => {
+  const classes = cx([
+    className,
+    rootClassName,
+    {
+      [`${rootClassName}-colspan-sm-${colSpanSm}`]: colSpanSm,
+      [`${rootClassName}-colspan-md-${colSpanMd}`]: colSpanMd,
+      [`${rootClassName}-colspan-lg-${colSpanLg}`]: colSpanLg,
+    },
+  ]);
+
+  return (
+    <div className={classes} data-testid={dataTestId}>
+      {children}
+    </div>
+  );
+};
+
+export const isItem = (
+  child:
+    | ReactChild
+    | ReactElement
+    | ReactFragment
+    | ReactPortal
+    | string
+    | number
+    | boolean
+    | null
+    | undefined
+): child is ReactElement<ItemProps> =>
+  !!child &&
+  isValidElement<ItemProps>(child) &&
+  (!!child.props.colSpanSm || !!child.props.colSpanMd || !!child.props.colSpanLg);

package/src/grid.module.scss

@@ -1,23 +1,83 @@
 @import "@purpurds/tokens/breakpoint/variables";
 
 .purpur-grid {
+  $root: &;
+
+  --gap: var(--purpur-spacing-gutter-sm);
   --padding: var(--purpur-spacing-page-padding-sm);
 
   box-sizing: border-box;
-  display: block;
-  margin-left: auto;
-  margin-right: auto;
+  row-gap: var(--gap);
+  width: 100%;
   max-width: var(--purpur-breakpoint-xl);
+  margin: 0 auto;
   padding: 0 var(--padding);
-  width: 100%;
 
-  @media screen and (min-width: #{$purpur-breakpoint-md}) {
+  /* Remove padding for nested grids */
+  #{$root} {
+    padding: 0;
+  }
+
+  @media screen and (min-width: $purpur-breakpoint-md) {
+    --gap: var(--purpur-spacing-gutter-md);
     --padding: var(--purpur-spacing-page-padding-md);
   }
-  @media screen and (min-width: #{$purpur-breakpoint-lg}) {
+
+  @media screen and (min-width: $purpur-breakpoint-lg) {
+    --gap: var(--purpur-spacing-gutter-lg);
     --padding: var(--purpur-spacing-page-padding-lg);
   }
-  @media screen and (min-width: #{$purpur-breakpoint-xl}) {
+
+  @media screen and (min-width: $purpur-breakpoint-xl) {
+    --gap: var(--purpur-spacing-gutter-xl);
     --padding: var(--purpur-spacing-page-padding-xl);
   }
-}
+
+  &--grid {
+    display: grid;
+    column-gap: var(--gap);
+
+    @for $i from 4 through 2 {
+      &#{$root}-col-sm-#{$i} {
+        grid-template-columns: repeat($i, 1fr);
+      }
+    }
+
+    @for $i from 8 through 2 {
+      @media screen and (min-width: $purpur-breakpoint-md) {
+        &#{$root}-col-md-#{$i} {
+          grid-template-columns: repeat($i, 1fr);
+        }
+      }
+    }
+
+    @for $i from 12 through 2 {
+      @media screen and (min-width: $purpur-breakpoint-lg) {
+        &#{$root}-col-lg-#{$i} {
+          grid-template-columns: repeat($i, 1fr);
+        }
+      }
+    }
+  }
+
+  &--flex {
+    --gutter: var(--purpur-spacing-gutter-sm);
+
+    display: flex;
+    flex-wrap: wrap;
+    width: calc(100% + var(--gutter));
+    margin: 0 calc(-1 * (var(--gutter) / 2));
+
+    @media screen and (min-width: $purpur-breakpoint-md) {
+      --gutter: var(--purpur-spacing-gutter-md);
+    }
+
+    @media screen and (min-width: $purpur-breakpoint-lg) {
+      --gutter: var(--purpur-spacing-gutter-lg);
+    }
+
+    @media screen and (min-width: $purpur-breakpoint-xl) {
+      --gutter: var(--purpur-spacing-gutter-xl);
+    }
+  }
+}

package/src/grid.stories.tsx

@@ -1,5 +1,7 @@
 /* eslint-disable react/prop-types */
+import type { ReactNode } from "react";
 import React from "react";
+import { Link } from "@purpurds/link";
 import type { Meta, StoryObj } from "@storybook/react";
 
 import { Grid } from "./grid";
@@ -20,6 +22,14 @@ const meta: Meta<typeof Grid> = {
     ["data-testid"]: { control: { type: "text" } },
     className: { control: { type: "text" } },
     children: { control: { type: "text" } },
+    colsSm: { control: { type: "range", min: 1, max: 4, step: 1 } },
+    colsMd: { control: { type: "range", min: 1, max: 8, step: 1 } },
+    colsLg: { control: { type: "range", min: 1, max: 12, step: 1 } },
+  },
+  args: {
+    colsSm: 2,
+    colsMd: 4,
+    colsLg: 6,
   },
 };
 
@@ -27,43 +37,92 @@ export default meta;
 
 type Story = StoryObj<typeof Grid>;
 
+const Column = ({ number, children }: { number: number; children?: ReactNode }) => {
+  return (
+    <div style={{ border: "1px solid lightgray", padding: ".5rem" }}>
+      <p>Column {number}</p>
+      {children}
+    </div>
+  );
+};
+
 export const Showcase: Story = {
   render: ({ children, ...args }) => (
     <Grid {...args}>
-      <Grid.Row>
-        <Grid.Col width={6} widthMd={4} widthLg={3}>
-          <p>Column 1</p>
-          {children}
-        </Grid.Col>
-        <Grid.Col width={6} widthMd={4} widthLg={3}>
-          <p>Column 2</p>
-          {children}
-        </Grid.Col>
-        <Grid.Col width={6} widthMd={4} widthLg={3}>
-          <p>Column 3</p>
-          {children}
-        </Grid.Col>
-        <Grid.Col width={6} widthMd={4} widthLg={3}>
-          <p>Column 4</p>
-          {children}
-        </Grid.Col>
-        <Grid.Col width={6} widthMd={4} widthLg={3}>
-          <p>Column 5</p>
-          {children}
-        </Grid.Col>
-        <Grid.Col width={6} widthMd={4} widthLg={3}>
-          <p>Column 6</p>
-          {children}
-        </Grid.Col>
-        <Grid.Col width={6} widthMd={4} widthLg={3}>
-          <p>Column 7</p>
-          {children}
-        </Grid.Col>
-        <Grid.Col width={6} widthMd={4} widthLg={3}>
-          <p>Column 8</p>
+      {Array.from(Array(12).keys()).map((x) => (
+        <Column key={x} number={x + 1}>
           {children}
-        </Grid.Col>
-      </Grid.Row>
+        </Column>
+      ))}
     </Grid>
   ),
 };
+
+export const AdvancedWithNestedGrids: Story = {
+  parameters: {
+    controls: {
+      exclude: ["colsSm", "colsMd", "colsLg"],
+    },
+  },
+  render: ({ children }) => (
+    <>
+      <Grid>
+        <Grid colsSm={1} colsMd={3} colsLg={3}>
+          <Column number={1}>{children}</Column>
+          <Column number={2}>{children}</Column>
+          <Column number={3}>{children}</Column>
+        </Grid>
+        <Grid colsSm={1} colsMd={2} colsLg={2}>
+          <Column number={4}>{children}</Column>
+          <Column number={5}>{children}</Column>
+        </Grid>
+        <Grid colsSm={1} colsMd={2} colsLg={2}>
+          <Column number={6}>{children}</Column>
+          <Column number={7}>{children}</Column>
+        </Grid>
+      </Grid>
+      <div style={{ marginTop: "3rem" }}>
+        <Link
+          variant="standalone"
+          href="/?path=/docs/components-grid--docs#advanced-grid-using-nested-grids"
+        >
+          See the example code in Docs
+        </Link>
+      </div>
+    </>
+  ),
+};
+
+export const AdvancedWithGridItems: Story = {
+  parameters: {
+    controls: {
+      exclude: ["colsSm", "colsMd", "colsLg"],
+    },
+  },
+  render: ({ children }) => (
+    <>
+      <Grid>
+        <Grid.Item colSpanSm={2} colSpanMd={5} colSpanLg={3}>
+          <Column number={1}>{children}</Column>
+        </Grid.Item>
+        <Grid.Item colSpanSm={2} colSpanMd={3} colSpanLg={9}>
+          <Column number={2}>{children}</Column>
+        </Grid.Item>
+        <Grid.Item colSpanSm={4} colSpanMd={2} colSpanLg={6}>
+          <Column number={3}>{children}</Column>
+        </Grid.Item>
+        <Grid.Item colSpanSm={4} colSpanMd={6} colSpanLg={6}>
+          <Column number={4}>{children}</Column>
+        </Grid.Item>
+      </Grid>
+      <div style={{ marginTop: "3rem" }}>
+        <Link
+          variant="standalone"
+          href="/?path=/docs/components-grid--docs#advanced-grid-using-griditem"
+        >
+          See the example code in Docs
+        </Link>
+      </div>
+    </>
+  ),
+};

package/src/grid.tsx

@@ -1,38 +1,62 @@
-import React, { ReactNode } from "react";
-import c from "classnames";
+import React, { Children, ReactNode } from "react";
+import c from "classnames/bind";
 
-import { Col } from "./col";
+import { isItem, Item } from "./grid.item";
 import styles from "./grid.module.scss";
-import { Row } from "./row";
 
-type GridCmp<P> = React.FunctionComponent<P> & {
-  Row: typeof Row;
-  Col: typeof Col;
-};
+const cx = c.bind(styles);
 
 export type GridProps = {
   children: ReactNode;
   ["data-testid"]?: string;
   className?: string;
+  /** The number of columns on small screens. */
+  colsSm?: 1 | 2 | 3 | 4;
+  /** The number of columns on medium screens. */
+  colsMd?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+  /** The number of columns on large screens. */
+  colsLg?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
 };
 
-export type { ColumnWidthType } from "./col";
+export type GridCmp<P> = React.FunctionComponent<P> & {
+  Item: typeof Item;
+};
 
 const rootClassName = "purpur-grid";
 
-export const Grid: GridCmp<GridProps> = ({
+export const Grid = ({
   children,
   className,
   ["data-testid"]: dataTestId,
+  colsSm = 1,
+  colsMd = 1,
+  colsLg = 1,
   ...props
-}) => {
-  const classes = c([className, styles[rootClassName]]);
+}: GridProps) => {
+  const gridItemChildren = Children.toArray(children).filter(isItem);
+  const hasItemChildren = gridItemChildren.length;
+
+  const classes = cx([
+    className,
+    rootClassName,
+    {
+      [`${rootClassName}--grid`]: !hasItemChildren,
+      [`${rootClassName}--flex`]: hasItemChildren,
+      [`${rootClassName}-col-sm-${colsSm}`]: colsSm > 1 && !hasItemChildren,
+      [`${rootClassName}-col-md-${colsMd}`]: colsMd > 1 && !hasItemChildren,
+      [`${rootClassName}-col-lg-${colsLg}`]: colsLg > 1 && !hasItemChildren,
+    },
+  ]);
+
   return (
     <div className={classes} data-testid={dataTestId} {...props}>
-      {children}
+      {hasItemChildren
+        ? Children.map(gridItemChildren, ({ props: { children, ...colProps } }) => (
+            <Item {...colProps}>{children}</Item>
+          ))
+        : children}
     </div>
   );
 };
 
-Grid.Col = Col;
-Grid.Row = Row;
+Grid.Item = Item;

package/dist/col.d.ts

@@ -1,13 +0,0 @@
-import { default as React, ReactNode } from 'react';
-
-export type ColumnWidthType = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
-export type ColProps = {
-    children: ReactNode;
-    className?: string;
-    ["data-testid"]?: string;
-    width?: ColumnWidthType;
-    widthMd?: ColumnWidthType;
-    widthLg?: ColumnWidthType;
-};
-export declare const Col: ({ children, ["data-testid"]: dataTestId, width, className, widthMd, widthLg, ...props }: ColProps) => React.JSX.Element;
-//# sourceMappingURL=col.d.ts.map

package/dist/col.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"col.d.ts","sourceRoot":"","sources":["../src/col.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKzC,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAE/E,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAE,SAAS,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B,CAAC;AAIF,eAAO,MAAM,GAAG,4FAQb,QAAQ,sBAgBV,CAAC"}

package/dist/row.d.ts

@@ -1,18 +0,0 @@
-import { default as React, ReactNode } from 'react';
-
-export declare const RowSpacings: {
-    readonly SM: "sm";
-    readonly MD: "md";
-    readonly LG: "lg";
-};
-export declare const RowSpacingSizes: ("sm" | "md" | "lg")[];
-export type RowSpacingsType = (typeof RowSpacings)[keyof typeof RowSpacings];
-export type RowProps = {
-    className?: string;
-    colGap?: boolean;
-    ["data-testid"]?: string;
-    children: ReactNode;
-    spacing?: RowSpacingsType;
-};
-export declare const Row: ({ children, ["data-testid"]: dataTestId, spacing, className, colGap, ...props }: RowProps) => React.JSX.Element;
-//# sourceMappingURL=row.d.ts.map

package/dist/row.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"row.d.ts","sourceRoot":"","sources":["../src/row.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKzC,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAEX,eAAO,MAAM,eAAe,wBAA6B,CAAC;AAC1D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAE7E,MAAM,MAAM,QAAQ,GAAG;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B,CAAC;AAIF,eAAO,MAAM,GAAG,oFAOb,QAAQ,sBAeV,CAAC"}