@nypl/design-system-react-components 0.25.13 → 0.27.0

package/src/components/StyleGuide/Spacing.stories.mdx

@@ -1,5 +1,4 @@
 import { Meta } from "@storybook/addon-docs";
-import { withDesign } from "storybook-addon-designs";
 
 import Card from "../Card/Card";
 import List from "../List/List";
@@ -7,66 +6,106 @@ import { ListTypes } from "../List/ListTypes";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
 
-<Meta
-  title={getCategory("Spacing")}
-  decorators={[withDesign]}
-  parameters={{
-    design: {
-      type: "figma",
-      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=17249%3A13",
-    },
-  }}
-/>
+<Meta title={getCategory("Spacing")} />
 
 # Spacing
 
-| Table of Contents                                |
-| ------------------------------------------------ |
-| 1. [General Information](#general-information)   |
-| 2. [CSS Variables](#css-variables)               |
-| 3. [Section Spacing](#section-spacing)           |
-| 4. [Grid Spacing](#grid-spacing)                 |
-| 5. [Tabular Data Spacing](#tabular-data-spacing) |
-| 6. [Form Spacing](#form-spacing)                 |
-| 7. [Figma Reference](#figma-reference)           |
+| Table of Contents                                    |
+| ---------------------------------------------------- |
+| 1. [General Information](#general-information)       |
+| 2. [Default Spacing Values](#default-spacing-values) |
+| 3. [Page Section Spacing](#page-section-spacing)     |
+| 4. [Grid Spacing](#grid-spacing)                     |
+| 5. [Form Spacing](#form-spacing)                     |
+| 6. [Tabular Data Spacing](#tabular-data-spacing)     |
+| 7. [Figma Reference](#figma-reference)               |
 
 ## General Information
 
-The DS spacing values are based on a root font size of `16px` (`1rem` = `16px`).
+The Reservoir Design System (DS) spacing values are based on a root unit
+of `16px` (`1rem` = `16px`).
 
-## CSS Variables
+## Default Spacing Values
 
 <DSProvider>
-The following CSS variables are available through the DS.
-
-| Variable Name       | REM Equivalent | Pixel Equivalent | Visual Reference                                                                                              |
-| ------------------- | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
-| `--nypl-space-xxs`  | `0.25rem`      | `4px`            | <div style={{ width: "var(--nypl-space-xxs)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>  |
-| `--nypl-space-xs`   | `0.5rem`       | `8px`            | <div style={{ width: "var(--nypl-space-xs)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>   |
-| `--nypl-space-s`    | `1rem`         | `16px`           | <div style={{ width: "var(--nypl-space-s)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>    |
-| `--nypl-space-m`    | `1.5rem`       | `24px`           | <div style={{ width: "var(--nypl-space-m)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>    |
-| `--nypl-space-l`    | `2rem`         | `32px`           | <div style={{ width: "var(--nypl-space-l)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>    |
-| `--nypl-space-xl`   | `3rem`         | `48px`           | <div style={{ width: "var(--nypl-space-xl)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>   |
-| `--nypl-space-xxl`  | `4rem`         | `64px`           | <div style={{ width: "var(--nypl-space-xxl)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>  |
-| `--nypl-space-xxxl` | `6rem`         | `96px`           | <div style={{ width: "var(--nypl-space-xxxl)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div> |
+The following default spacing values are available through the DS.
+
+| JS Theme Object | CSS Variable        | REM Equivalent | Pixel Equivalent | Visual Reference                                                                                              |
+| --------------- | ------------------- | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
+| `xxxs`          | `--nypl-space-xxxs` | `0.125rem`     | `2px`            | <div style={{ width: "var(--nypl-space-xxxs)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div> |
+| `xxs`           | `--nypl-space-xxs`  | `0.25rem`      | `4px`            | <div style={{ width: "var(--nypl-space-xxs)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>  |
+| `xs`            | `--nypl-space-xs`   | `0.5rem`       | `8px`            | <div style={{ width: "var(--nypl-space-xs)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>   |
+| `s`             | `--nypl-space-s`    | `1rem`         | `16px`           | <div style={{ width: "var(--nypl-space-s)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>    |
+| `m`             | `--nypl-space-m`    | `1.5rem`       | `24px`           | <div style={{ width: "var(--nypl-space-m)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>    |
+| `l`             | `--nypl-space-l`    | `2rem`         | `32px`           | <div style={{ width: "var(--nypl-space-l)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>    |
+| `xl`            | `--nypl-space-xl`   | `3rem`         | `48px`           | <div style={{ width: "var(--nypl-space-xl)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>   |
+| `xxl`           | `--nypl-space-xxl`  | `4rem`         | `64px`           | <div style={{ width: "var(--nypl-space-xxl)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div>  |
+| `xxxl`          | `--nypl-space-xxxl` | `6rem`         | `96px`           | <div style={{ width: "var(--nypl-space-xxxl)", backgroundColor: "var(--nypl-colors-ui-focus)" }}>&nbsp;</div> |
 
 </DSProvider>
 
-## Section Spacing
+## Page Section Spacing
 
-In consuming apps, the major page sections should be separated vertically by `3rem` `(--nypl-space-xl`). This includes the space after the page global `header` and the space before the global `footer`.
+In consuming apps, the major page sections should be separated vertically by
+`2rem`. This includes the space after the page global `header` and the space
+before the global `footer`. Similarly, the major page sections should be
+separated horizontally by `2rem`.
 
-## Grid Spacing
+|                        | Value  | JS Theme Object | CSS Variable                 |
+| ---------------------- | ------ | --------------- | ---------------------------- |
+| **Vertical Spacing**   | `2rem` | `page.vstack`   | `--nypl-spacing-page-vstack` |
+| **Horizontal Spacing** | `2rem` | `page.hstack`   | `--nypl-spacing-page-hstack` |
 
-When elements are displayed in a grid (i.e. Cards, Images, etc.), the space between elements, both horizontal and vertical, should be `2rem` (`--nypl-space-l`).
+## Grid Spacing
 
-## Tabular Data Spacing
+When elements are displayed in a grid (i.e. Cards, Images, etc.), the space
+between elements, both horizontal and vertical, should be `2rem`.
 
-When data is displayed in a tabular layout (i.e. rows and columns in a table, a definition list, etc.), the space between data cells in a row should be `1.5rem` (`--nypl-space-m`) and the space between rows should be `2rem` (`--nypl-space-l`).
+|                 | Value  | JS Theme Object | CSS Variable                  |
+| --------------- | ------ | --------------- | ----------------------------- |
+| **Default Gap** | `2rem` | `grid.default`  | `--nypl-spacing-grid-default` |
 
 ## Form Spacing
 
-Form input components should have a `2rem` (`--nypl-space-l`) space between each component. This includes both vertical (column) and horizontal (row) stacking. The DS [Form](https://nypl.github.io/nypl-design-system/storybook-static/?path=/story/form-elements-form--form) component has correct spacing incorporated into its UI structure and should always be used when building forms.
+Form input components should have a `2rem` space between each form input
+component. This includes both vertical (column) and horizontal (row) stacking.
+The DS [Form](https://nypl.github.io/nypl-design-system/storybook-static/?path=/docs/components-form-elements-form--form-with-controls)
+component has correct spacing incorporated into its UI structure and should
+always be used when building forms. Please note that the spacing in the `Form`
+component is identical to the spacing in the `Grid` component.
+
+When `Checkbox` and `Radio` components are grouped together, the components
+should have a `1rem` space between components for vertical (column) stacking
+and a `2rem` space between components for horizontal (row) stacking. The DS
+`CheckboxGroup` and `RadioGroup` components have the correct spacing built
+
+in and should be used respectively when multiple `Checkbox` or `radio`
+components are being used together.
+
+When `Button` components are grouped together, the `Button` components should
+have a `0.5rem` space between component. This includes both vertical (column)
+and horizontal (row) stacking. The DS `ButtonGroup` component has the correct
+spacing built in and should be used when multiple `Button` components are being
+used together.
+
+|                                        | Value    | JS Theme Object              | CSS Variable                                |
+| -------------------------------------- | -------- | ---------------------------- | ------------------------------------------- |
+| **Default Form Gap**                   | `2rem`   | `grid.default`               | `--nypl-spacing-grid-default`               |
+| **Input Group Default Row Spacing**    | `2rem`   | `input.group.default.hstack` | `--nypl-spacing-input-group-default-hstack` |
+| **Input Group Default Column Spacing** | `1rem`   | `input.group.default.vstack` | `--nypl-spacing-input-group-default-vstack` |
+| **Button Group Row Spacing**           | `0.5rem` | `input.group.button.hstack`  | `--nypl-spacing-input-group-button-hstack`  |
+| **Button Group Column Spacing**        | `0.5rem` | `input.group.button.vstack`  | `--nypl-spacing-input-group-button-vstack`  |
+
+## Tabular Data Spacing
+
+When data is displayed in a tabular layout (i.e. rows and columns in a table,
+a description list, etc.), the space between data cells in a row should be
+`1.5rem` and the space between rows should be `2rem`.
+
+|                | Value    | JS Theme Object | CSS Variable                  |
+| -------------- | -------- | --------------- | ----------------------------- |
+| **Column Gap** | `1.5rem` | `table.column`  | `--nypl-spacing-table-column` |
+| **Row Gap**    | `2rem`   | `table.row`     | `--nypl-spacing-table-row`    |
 
 ## Figma Reference
 

package/src/components/StyleGuide/Typography.stories.mdx

@@ -1,5 +1,4 @@
 import { Canvas, Meta } from "@storybook/addon-docs";
-import { withDesign } from "storybook-addon-designs";
 
 import Heading from "../Heading/Heading";
 import { HeadingSizes, HeadingLevels } from "../Heading/HeadingTypes";
@@ -10,16 +9,7 @@ import { TextSizes } from "../Text/TextTypes";
 import { getCategory } from "../../utils/componentCategories";
 import DSProvider from "../../theme/provider";
 
-<Meta
-  title={getCategory("Typography")}
-  decorators={[withDesign]}
-  parameters={{
-    design: {
-      type: "figma",
-      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Master?node-id=10975%3A16",
-    },
-  }}
-/>
+<Meta title={getCategory("Typography")} />
 
 # Typography
 
@@ -38,13 +28,18 @@ import DSProvider from "../../theme/provider";
 
 ## General Information
 
-Consuming applications should utilize the DS standard text components as much as possible. In cases where that is not possible, the DS exposes CSS variables to assist with formatting text elements.
+Consuming applications should utilize the Reservoir Design System (DS) standard
+text components as much as possible. In cases where that is not possible, the
+DS exposes CSS variables to assist with formatting text elements.
 
-The sizing of all text elements in the Design System is based on `1rem` being equal to `16px`.
+The sizing of all text elements in the Design System is based on `1rem` being
+equal to `16px`.
 
 ## Heading Component
 
-Use the NYPL Design System [Heading](/docs/components-typography-styles-heading--heading-props) component to render a standard HTML `<h>` tag. The `level` prop can be used to set the specific `<h>` tag that you require.
+Use the DS [Heading](/docs/components-typography-styles-heading--heading-props)
+component to render a standard HTML `<h>` tag. The `level` prop can be used to
+set the specific `<h>` tag that you require.
 
 <Canvas>
   <DSProvider>
@@ -110,7 +105,9 @@ applied to any `Heading` element.
 
 ## Text Component
 
-Use the NYPL Design System [Text](/docs/components-typography-styles-text--text) component to render a standard HTML `<p>` tag. The Text component is generally used for body copy, captions and secondary captions.
+Use the DS [Text](/docs/components-typography-styles-text--text)
+component to render a standard HTML `<p>` tag. The Text component is generally
+used for body copy, captions and secondary captions.
 
 <Canvas>
   <DSProvider>
@@ -168,7 +165,9 @@ The `size` prop can be used to render a specific style from the DS default text
 
 ## Font Family
 
-With website accessibility in mind, font choices for the DS were made with an eye toward clarity and readability. Headings and body content use the following font family assignment:
+With website accessibility in mind, font choices for the DS were made with an
+eye toward clarity and readability. Headings and body content use the
+following font family assignment:
 
 <Canvas>
   <DSProvider>
@@ -184,11 +183,15 @@ The following CSS variables are available through the DS.
 ```
 
 > **RECOMMENDATIONS**  
-> When making font selections for project based components outside the DS, sans serif fonts display better on computers and mobile devices. Avoid decorative or overly stylized fonts, as they are often difficult to read even for users without visual impairments or reading Standard Text Default
+> When making font selections for project based components outside the DS,
+> sans serif fonts display better on computers and mobile devices. Avoid
+> decorative or overly stylized fonts, as they are often difficult to read even
+> for users without visual impairments or reading Standard Text Default
 
 ## Font Color
 
-All text within a project, unless specifically noted in mockups, should be black on a white background.
+All text within a project, unless specifically noted in mockups, should be
+black on a white background.
 
 <Canvas>
   <DSProvider>
@@ -203,7 +206,10 @@ All text within a project, unless specifically noted in mockups, should be black
   </DSProvider>
 </Canvas>
 
-In cases where specific colors must be applied to text elements, the DS provides CSS variables for the full NYPL color palette. Refer to the [Colors](https://nypl.github.io/nypl-design-system/storybook-static/?path=/docs/style-guide-colors--colors-brand) section of the Style Guide for details.
+In cases where specific colors must be applied to text elements, the DS
+provides CSS variables for the full NYPL color palette. Refer to the
+[Colors](https://nypl.github.io/nypl-design-system/storybook-static/?path=/docs/style-guide-colors--colors-brand)
+section of the Style Guide for details.
 
 ## Font Weight
 
@@ -347,7 +353,9 @@ The following font size design tokens are available through the DS.
 
 ## Text Case
 
-In general, the New York Public Library uses Title Case for titles. This means only using capital letters for the principal words. Articles, conjunctions, and prepositions do not get capital letters unless they start the title. For example:
+In general, the New York Public Library uses Title Case for titles. This means
+only using capital letters for the principal words. Articles, conjunctions, and
+prepositions do not get capital letters unless they start the title. For example:
 
 <Canvas>
   <DSProvider>
@@ -378,7 +386,8 @@ In general, the New York Public Library uses Title Case for titles. This means o
 ### Summaries
 
 140 characters max<br />
-Note: Online Exhibitions, with their longer, legacy summaries are an exception to this.
+Note: Online Exhibitions, with their longer, legacy summaries are an exception
+to this.
 
 <Canvas>
   <DSProvider>

package/src/components/Table/Table.stories.mdx

@@ -36,7 +36,19 @@ import { getCategory } from "../../utils/componentCategories";
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.25.9`   |
-| Latest            | `0.25.10`  |
+| Latest            | `0.26.0`   |
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component Props](#component-props)
+- [Accessibility](#accessibility)
+- [With a title](#with-a-title)
+- [With Row Dividers](#with-row-dividers)
+- [With Row Headers](#with-row-headers)
+- [With Custom Header Colors](#with-custom-header-colors)
+
+## Overview
 
 <Description of={Table} />
 
@@ -64,6 +76,8 @@ export const tableData = [
   ],
 ];
 
+## Component Props
+
 <Canvas withToolbar>
   <Story
     name="Table"
@@ -87,16 +101,29 @@ export const tableData = [
 
 ## Accessibility
 
-- The HTML for the `Table` element is structured with proper semantic use of the
-  `table`, `caption`, `thead`, `tbody`, `tr`, and `td` HTML elements.
-- When titles are added through the `titleText` prop, the `caption` element will
-  be rendered on the page.
-- The first row and/or the first cell in a `tr` row can be headers. Each `th`
-  header cell has an appropriate scope attribute set to either `scope="col"` or
-  `scope="row"`. For example, every `th` cell in a `thead` `tr` row will have
-  `scope="col"`. Every `th` cell in a `tbody` `tr` row will have `scope="row"`.
-  These headers are visually different from the data. Use the `useRowHeaders`
-  prop to render the first cell in every row as a header.
+Internally, the HTML for the `Table` element is structured with proper semantic
+use of the `table`, `caption`, `thead`, `tbody`, `tr`, and `td` HTML elements.
+When titles are added through the `titleText` prop, the `caption` element will
+be rendered above the `thead` element.
+
+This component should be used to render tabular data only and not used for layout
+purposes.
+
+The first row and/or the first cell in a `tr` row can be headers. Each `th`
+header cell has an appropriate scope attribute set to either `scope="col"` or
+`scope="row"`. For example, every `th` cell in a `thead` `tr` row will have
+`scope="col"`. Every `th` cell in a `tbody` `tr` row will have `scope="row"`.
+These headers are visually different from the data. Use the `useRowHeaders`
+prop to render the first cell in every row as a header. If a table has two levels
+of headers (such as two levels of horizontal headers), break the data into two
+separate tables.
+
+Resources:
+
+- [W3C Tables Tutorial](https://www.w3.org/WAI/tutorials/tables/)
+- [MDN table: The Table element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table)
+- [MDN HTML table advance features and accessibility](https://developer.mozilla.org/en-US/docs/Learn/HTML/Tables/Advanced)
+- [Chakra UI Table](https://chakra-ui.com/docs/components/data-display/table)
 
 ## With a title
 

package/src/components/Table/Table.test.tsx

@@ -127,11 +127,26 @@ describe("Table", () => {
         />
       )
       .toJSON();
+    const withChakraProps = renderer
+      .create(
+        <Table
+          id="chakra"
+          tableData={tableData}
+          p="20px"
+          color="ui.error.primary"
+        />
+      )
+      .toJSON();
+    const withOtherProps = renderer
+      .create(<Table id="props" tableData={tableData} data-testid="props" />)
+      .toJSON();
 
     expect(basic).toMatchSnapshot();
     expect(withCaption).toMatchSnapshot();
     expect(withHeaders).toMatchSnapshot();
     expect(withRowHeaders).toMatchSnapshot();
     expect(withCustomHeaderColors).toMatchSnapshot();
+    expect(withChakraProps).toMatchSnapshot();
+    expect(withOtherProps).toMatchSnapshot();
   });
 });

package/src/components/Table/Table.tsx

@@ -1,5 +1,5 @@
-import * as React from "react";
 import {
+  chakra,
   Table as ChakraTable,
   TableCaption as ChakraTableCaption,
   Tbody as ChakraTbody,
@@ -9,8 +9,7 @@ import {
   Tr as ChakraTr,
   useMultiStyleConfig,
 } from "@chakra-ui/react";
-
-import generateUUID from "../../helpers/generateUUID";
+import * as React from "react";
 
 export interface TableProps {
   /** Additional class name for the `Table` component. */
@@ -39,17 +38,18 @@ export interface TableProps {
  * Basic `Table` component used to organize and display tabular data in
  * rows and columns.
  */
-function Table(props: React.PropsWithChildren<TableProps>) {
+export const Table = chakra((props: React.PropsWithChildren<TableProps>) => {
   const {
     className,
     columnHeaders,
     columnHeadersBackgroundColor,
     columnHeadersTextColor,
-    id = generateUUID(),
+    id,
     showRowDividers = false,
     tableData,
     titleText,
     useRowHeaders = false,
+    ...rest
   } = props;
 
   const customColors = {};
@@ -117,12 +117,12 @@ function Table(props: React.PropsWithChildren<TableProps>) {
   };
 
   return (
-    <ChakraTable id={id} sx={styles} className={className}>
+    <ChakraTable id={id} sx={styles} className={className} {...rest}>
       {tableCaption}
       {columnHeadersElems}
       {tableBodyElems()}
     </ChakraTable>
   );
-}
+});
 
 export default Table;