@nypl/design-system-react-components 0.25.9 → 0.25.10

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

@@ -4,17 +4,13 @@ import {
   Canvas,
   ArgsTable,
   Description,
-} from "@storybook/addon-docs/blocks";
+} from "@storybook/addon-docs";
 import { withDesign } from "storybook-addon-designs";
 
 import Table from "./Table";
 import DSProvider from "../../theme/provider";
 import { getCategory } from "../../utils/componentCategories";
 
-<Description of={Table} />
-
-The `Table` component is used to organize and display tabular data in rows and columns.
-
 <Meta
   title={getCategory("Table")}
   component={Table}
@@ -22,45 +18,148 @@ The `Table` component is used to organize and display tabular data in rows and c
   parameters={{
     design: {
       type: "figma",
-      url:
-        "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=46780%3A27675",
+      url: "https://www.figma.com/file/qShodlfNCJHb8n03IFyApM/Main?node-id=46780%3A27675",
     },
     jest: ["Table.test.tsx"],
   }}
   argTypes={{
-    columnHeaders: [],
+    columnHeaders: { control: { disable: true } },
     columnHeadersBackgroundColor: { control: { type: "color" } },
-    columnHeadersTextColor: {control: {type: "color"}},
-    id: {control: false},
+    columnHeadersTextColor: { control: { type: "color" } },
+    id: { control: false },
     tableData: { control: false },
   }}
 />
 
-
 # Table
 
 | Component Version | DS Version |
 | ----------------- | ---------- |
 | Added             | `0.25.9`   |
-| Latest            | `0.25.9`   |
+| Latest            | `0.25.10`  |
 
 <Description of={Table} />
 
+export const columnHeaders = [
+  "First Name",
+  "Last Name",
+  "Nick Name",
+  "Address1",
+  "City",
+  "State",
+  "Zipcode",
+];
+export const tableData = [
+  ["Tom", "Nook", "Tanukichi", "Main Street", "New York", "NY", "23458"],
+  ["Isabelle", "-", "Shizue", "Walnut Street", "New York", "NY", "23458"],
+  ["K.K.", "Slider", "Totakeke", "Niper Place", "New York", "NY", "98765"],
+  [
+    "Sonny",
+    "Resetti",
+    "Risetto san",
+    "Village Road",
+    "New York",
+    "NY",
+    "09873",
+  ],
+];
+
 <Canvas withToolbar>
   <Story
     name="Table"
     args={{
-      columnHeaders: ["First Name", "Last Name", "Nick Name", "Address1", "City", "Zipcode", "State"],
-      tableData: [ ["Tom", "Nook", "Tanukichi", "Main Street", "New York", "23458", "NY" ], [ "Isabelle", "-", "Shizue", "Walnut Street", "New York", "23458", "NY"], [ "K.K.", "Slider", "Totakeke", "Niper Place", "New York", "98765", "NY"], [ "Sonny", "Resetti", "Risetto san", "Village Road", "New York", "09873", "NY" ], ],
-      useRowHeaders: false,
+      className: undefined,
+      columnHeaders,
+      columnHeadersBackgroundColor: undefined,
+      columnHeadersTextColor: undefined,
+      id: undefined,
       showRowDividers: false,
+      tableData,
+      titleText: undefined,
+      useRowHeaders: false,
     }}
   >
-    {(args) => (
-      <Table {...args}>
-      </Table>
-    )}
+    {(args) => <Table {...args}></Table>}
   </Story>
 </Canvas>
 
 <ArgsTable story="Table" />
+
+## 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.
+
+## With a title
+
+Use the `titleText` prop to add a title to the table.
+
+<Canvas>
+  <DSProvider>
+    <Table
+      columnHeaders={columnHeaders}
+      id="title-table"
+      tableData={tableData}
+      titleText="Table with a title"
+    />
+  </DSProvider>
+</Canvas>
+
+## With Row Dividers
+
+Use the `showRowDividers` prop to render a divider between each row.
+
+<Canvas>
+  <DSProvider>
+    <Table
+      columnHeaders={columnHeaders}
+      id="showRowDividers-table"
+      showRowDividers
+      tableData={tableData}
+    />
+  </DSProvider>
+</Canvas>
+
+## With Row Headers
+
+Use the `useRowHeaders` prop to render the first cell in every row as a header.
+Notice that they turn bold.
+
+<Canvas>
+  <DSProvider>
+    <Table
+      columnHeaders={columnHeaders}
+      id="rowHeaders-table"
+      tableData={tableData}
+      useRowHeaders
+    />
+  </DSProvider>
+</Canvas>
+
+## With Custom Header Colors
+
+It's possible to customize the header colors by using the `columnHeadersBackgroundColor`
+and `columnHeadersTextColor` props. Note that the colors need to have sufficient
+color contrast.
+
+<Canvas>
+  <DSProvider>
+    <Table
+      columnHeaders={columnHeaders}
+      columnHeadersBackgroundColor="var(--nypl-colors-ui-link-secondary)"
+      columnHeadersTextColor="var(--nypl-colors-ui-white)"
+      id="rowHeaders-table"
+      showRowDividers
+      tableData={tableData}
+      useRowHeaders
+    />
+  </DSProvider>
+</Canvas>

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

@@ -1,6 +1,8 @@
 import * as React from "react";
 import { render, screen } from "@testing-library/react";
 import { axe } from "jest-axe";
+import renderer from "react-test-renderer";
+
 import Table from "./Table";
 
 export const columnHeaders = [
@@ -43,10 +45,30 @@ describe("Table Accessibility", () => {
 });
 
 describe("Table", () => {
-  it("Renders table data", () => {
+  it("renders a caption", () => {
+    render(<Table tableData={tableData} titleText="this is the caption" />);
+    expect(screen.getByText("this is the caption")).toBeInTheDocument();
+  });
+
+  it("renders a table header", () => {
+    render(
+      <Table
+        columnHeaders={columnHeaders}
+        tableData={tableData}
+        titleText="this is the caption"
+      />
+    );
+
+    expect(screen.getByText("First Name")).toBeInTheDocument();
+    expect(screen.getByText("Last Name")).toBeInTheDocument();
+    expect(screen.getByText("Nick Name")).toBeInTheDocument();
+  });
+
+  it("renders table data", () => {
     render(<Table tableData={tableData} columnHeaders={columnHeaders} />);
+
     expect(screen.getByText("Tom")).toBeInTheDocument();
-    expect(screen.getByText("First Name")).toBeInTheDocument();
+    expect(screen.getByText("Nook")).toBeInTheDocument();
     expect(screen.getByText("Village Road")).toBeInTheDocument();
   });
 
@@ -54,7 +76,62 @@ describe("Table", () => {
     const warn = jest.spyOn(console, "warn");
     render(<Table tableData={[]} />);
     expect(warn).toHaveBeenCalledWith(
-      "Table data should be two dimensional array."
+      "Table: data should be two dimensional array."
     );
   });
+
+  it("renders the UI snapshot correctly", () => {
+    const basic = renderer
+      .create(<Table id="basic" tableData={tableData} />)
+      .toJSON();
+    const withCaption = renderer
+      .create(
+        <Table
+          id="withCaption"
+          tableData={tableData}
+          titleText="this is the caption"
+        />
+      )
+      .toJSON();
+    const withHeaders = renderer
+      .create(
+        <Table
+          columnHeaders={columnHeaders}
+          id="withHeaders"
+          tableData={tableData}
+          titleText="this is the caption"
+        />
+      )
+      .toJSON();
+    const withRowHeaders = renderer
+      .create(
+        <Table
+          columnHeaders={columnHeaders}
+          id="withHeaders"
+          tableData={tableData}
+          titleText="this is the caption"
+          useRowHeaders
+        />
+      )
+      .toJSON();
+    const withCustomHeaderColors = renderer
+      .create(
+        <Table
+          columnHeadersBackgroundColor="var(--nypl-colors-ui-link-primary)"
+          columnHeadersTextColor="var(--nypl-colors-ui-white)"
+          columnHeaders={columnHeaders}
+          id="withHeaders"
+          tableData={tableData}
+          titleText="this is the caption"
+          useRowHeaders
+        />
+      )
+      .toJSON();
+
+    expect(basic).toMatchSnapshot();
+    expect(withCaption).toMatchSnapshot();
+    expect(withHeaders).toMatchSnapshot();
+    expect(withRowHeaders).toMatchSnapshot();
+    expect(withCustomHeaderColors).toMatchSnapshot();
+  });
 });

package/src/components/Table/Table.tsx

@@ -1,12 +1,12 @@
 import * as React from "react";
 import {
   Table as ChakraTable,
-  Thead as ChakraTHead,
+  TableCaption as ChakraTableCaption,
   Tbody as ChakraTbody,
-  Tr as ChakraTr,
-  Th as ChakraTh,
+  Thead as ChakraTHead,
   Td as ChakraTd,
-  TableCaption as ChakraTableCaption,
+  Th as ChakraTh,
+  Tr as ChakraTr,
   useMultiStyleConfig,
 } from "@chakra-ui/react";
 
@@ -23,16 +23,22 @@ export interface TableProps {
   columnHeadersTextColor?: string;
   /** ID that other components can cross reference for accessibility purposes. */
   id?: string;
-  /** If true, the first cell of each row in the `Table` component will be visually styled as a header.  The default value is false */
-  useRowHeaders?: boolean;
-  /** If true, a border will be displayed between each row in the `Table` component.  The default value is false. */
+  /** If true, a border will be displayed between each row in the `Table`
+   * component. The default value is false. */
   showRowDividers?: boolean;
   /** Two-dimensional array used to populate the table rows. */
   tableData: string[][];
   /** Displays `Table` title element. */
   titleText?: string;
+  /** If true, the first cell of each row in the `Table` component will be
+   * visually styled as a header. The default value is false */
+  useRowHeaders?: boolean;
 }
 
+/**
+ * Basic `Table` component used to organize and display tabular data in
+ * rows and columns.
+ */
 function Table(props: React.PropsWithChildren<TableProps>) {
   const {
     className,
@@ -40,10 +46,10 @@ function Table(props: React.PropsWithChildren<TableProps>) {
     columnHeadersBackgroundColor,
     columnHeadersTextColor,
     id = generateUUID(),
-    useRowHeaders = false,
     showRowDividers = false,
     tableData,
     titleText,
+    useRowHeaders = false,
   } = props;
 
   const customColors = {};
@@ -58,11 +64,15 @@ function Table(props: React.PropsWithChildren<TableProps>) {
     useRowHeaders,
   });
 
-  const columnHeadersElems = columnHeaders && (
+  const tableCaption = titleText && (
+    <ChakraTableCaption>{titleText}</ChakraTableCaption>
+  );
+
+  const columnHeadersElems = columnHeaders?.length > 0 && (
     <ChakraTHead>
       <ChakraTr>
         {columnHeaders.map((child, key) => (
-          <ChakraTh scope="col" key={key} sx={customColors}>
+          <ChakraTh key={key} scope="col" sx={customColors}>
             {child}
           </ChakraTh>
         ))}
@@ -70,14 +80,18 @@ function Table(props: React.PropsWithChildren<TableProps>) {
     </ChakraTHead>
   );
 
+  /**
+   * This renders a normal `tbody` DOM element structure if the `tableData`
+   * passed is a two-dimensional array. This is to render the appropriate
+   * row and column structure for a table.
+   */
   const tableBodyElems = () => {
-    /** tableData value should be two dimensional array */
     if (
       !Array.isArray(tableData) ||
       tableData.length <= 0 ||
       tableData[0].constructor !== Array
     ) {
-      console.warn(`Table data should be two dimensional array.`);
+      console.warn("Table: data should be two dimensional array.");
       return null;
     }
 
@@ -100,10 +114,6 @@ function Table(props: React.PropsWithChildren<TableProps>) {
     );
   };
 
-  const tableCaption = titleText && (
-    <ChakraTableCaption>{titleText}</ChakraTableCaption>
-  );
-
   return (
     <ChakraTable id={id} sx={styles} className={className}>
       {tableCaption}