@hyphen/hyphen-components 9.0.0-beta.0 → 9.0.0

package/dist/index.d.ts

@@ -55,7 +55,7 @@ declare type ResponsiveProp<T> = {
 };
 type Row = UnknownPropertiesObjType;
 type Cell = Row[string];
-declare type Column = {
+declare type Column<TRow extends object = Row> = {
     /**
      * Text alignment for column cells (including header alignment). Cells will default to left if not defined.
      */
@@ -63,11 +63,11 @@ declare type Column = {
     /**
      * CSS Class to be applied uniformly to all individual cells in a column.
      */
-    cellClassName?: string | ((cell?: Cell, row?: Row, rowIndex?: number) => string);
+    cellClassName?: string | ((cell?: Cell, row?: TRow, rowIndex?: number) => string);
     /**
      * The key value to be rendered based on the table `rows`.
      */
-    dataKey?: string;
+    dataKey?: Extract<keyof TRow, string>;
     /**
      * Placeholder for empty cells Applies only to the cells of the particular column with this prop.
      */
@@ -93,7 +93,7 @@ declare type Column = {
      * Render method for column cell data. Provides ability to render any aspect of the cell/row with custom
      * markup.
      */
-    render?: (cell?: Cell, row?: Row, rowIndex?: number) => ReactNode;
+    render?: (cell?: Cell, row?: TRow, rowIndex?: number) => ReactNode;
     /**
      * Whether the column is stuck to the left or right.
      */
@@ -2401,20 +2401,20 @@ interface SwitchProps {
 }
 declare const Switch: FC<SwitchProps>;
 
-interface TableProps {
+interface TableProps<TRow extends object = Row> {
     /**
      * Columns for the table. See Column definition below for details.
      */
-    columns: Column[];
+    columns: Column<TRow>[];
     /**
      * The data rows to be displayed
      */
-    rows: Row[];
+    rows: TRow[];
     /**
      * Key that represents a unique value for a row. This is necessary in
      * order to supply React with a node key on each row.
      */
-    rowKey: string;
+    rowKey: Extract<keyof TRow, string>;
     /**
      * Additional classes to add.
      */
@@ -2484,7 +2484,7 @@ interface TableProps {
      */
     truncateOverflow?: boolean;
 }
-declare const Table: FC<TableProps>;
+declare const Table: <TRow extends object = Row>({ columns, rows, rowKey, align, className, emptyCellPlaceholder, hoverableRows, isBorderless, isCompact, hasStickyHeader, isLoading, isScrollable, isStriped, onSort, sortedColumn, useFixedTableLayout, truncateOverflow, }: TableProps<TRow>) => React__default.JSX.Element;
 
 type Theme = 'dark' | 'light' | 'system';
 type ThemeProviderProps = {
@@ -2729,7 +2729,7 @@ declare function generateResponsiveClasses(classRoot: string, value: ResponsiveP
 
 declare function getAutoCompleteValue(value: string | boolean): string;
 
-declare const getColumnKeys: (columns: Column[]) => Key[];
+declare const getColumnKeys: <TRow extends object = Row>(columns: Column<TRow>[]) => Key[];
 
 declare function getDimensionStyles(dimension: CssDimensionAbbreviation, value?: DimensionSize | ResponsiveProp<DimensionSize> | string): {
     [key: string]: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyphen/hyphen-components",
-  "version": "9.0.0-beta.0",
+  "version": "9.0.0",
   "license": "MIT",
   "author": {
     "name": "@hyphen"
@@ -56,7 +56,7 @@
     "react-select": "^5.10.0",
     "react-select-event": "^5.5.1",
     "uuid": "^11.1.1",
-    "@hyphen/hyphen-design-tokens": "^9.0.0-beta.0"
+    "@hyphen/hyphen-design-tokens": "^9.0.0"
   },
   "devDependencies": {
     "@babel/core": "^7.27.4",

package/src/components/Box/Box.mdx

@@ -13,6 +13,9 @@ A `<Box>` is a layout component to build UIs with consistent padding and spacing
 - Allows you to specify the spacing between child elements using `gap`
 - Many props accept `ResponsiveProp` that take an object with keys that correspond to [breakpoint tokens](?path=/docs/foundation-design-tokens--docs#breakpoints).
 
+See [Polymorphic Composition](?path=/docs/about-polymorphic-composition--docs)
+for native element, router component, ref, and extracted prop object patterns.
+
 <Canvas of={Stories.Overview} />
 
 ## Props

package/src/components/Button/Button.mdx

@@ -75,4 +75,16 @@ The interface should make it clear why the button is disabled and what needs to
 
 ## As Child
 
-Apply the `asChild` prop to apply the button styles to a child element.
+Apply the `asChild` prop to apply the button styles to one child element. This
+keeps navigation semantics when a link needs to look like a button and prevents
+nested interactive elements.
+
+```tsx
+<Button asChild>
+  <a href="/settings">Settings</a>
+</Button>
+```
+
+Place navigation props on the child and Button props on `Button`. See
+[Polymorphic Composition](?path=/docs/about-polymorphic-composition--docs) for
+router links, custom ref-forwarding children, and accessibility guidance.

package/src/components/Table/Table.mdx

@@ -30,6 +30,26 @@ An example showcasing the props required to render a list of customers in a tabl
 
 <Canvas of={Stories.CommonExample} />
 
+## TypeScript row types
+
+`Table` accepts interfaces and infers its row type from `rows`. Type separately declared columns with `Column<TRow>[]` to validate `dataKey` values and type the `row` argument passed to render callbacks.
+
+```tsx
+interface Customer {
+  id: string;
+  name: string;
+}
+
+const columns: Column<Customer>[] = [
+  {
+    dataKey: 'name',
+    render: (_cell, row) => row?.name,
+  },
+];
+
+<Table columns={columns} rows={customers} rowKey="id" />;
+```
+
 ## Loading
 
 Use the `isLoading` prop on the `<Table />` component to display an overlay that prevents user interaction. Useful for when

package/src/components/Table/Table.tsx

@@ -1,4 +1,4 @@
-import React, { FC } from 'react';
+import React from 'react';
 import classNames from 'classnames';
 import { Column, Row, EventWithColumnKey } from '../../types';
 import { Spinner } from '../Spinner/Spinner';
@@ -6,20 +6,20 @@ import styles from './Table.module.scss';
 import { TableBody } from './TableBody/TableBody';
 import { TableHead } from './TableHead/TableHead';
 
-export interface TableProps {
+export interface TableProps<TRow extends object = Row> {
   /**
    * Columns for the table. See Column definition below for details.
    */
-  columns: Column[];
+  columns: Column<TRow>[];
   /**
    * The data rows to be displayed
    */
-  rows: Row[];
+  rows: TRow[];
   /**
    * Key that represents a unique value for a row. This is necessary in
    * order to supply React with a node key on each row.
    */
-  rowKey: string;
+  rowKey: Extract<keyof TRow, string>;
   /**
    * Additional classes to add.
    */
@@ -90,7 +90,7 @@ export interface TableProps {
   truncateOverflow?: boolean;
 }
 
-export const Table: FC<TableProps> = ({
+export const Table = <TRow extends object = Row,>({
   columns,
   rows,
   rowKey,
@@ -108,7 +108,7 @@ export const Table: FC<TableProps> = ({
   sortedColumn = undefined,
   useFixedTableLayout = false,
   truncateOverflow = false,
-}) => {
+}: TableProps<TRow>) => {
   const containerClasses = classNames(styles.container, {
     [styles['full-height']]: !!isScrollable?.y,
   });

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

@@ -1,5 +1,6 @@
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import type { Column } from '../../../types';
 import { TableBody } from './TableBody';
 
 const columns = [
@@ -14,6 +15,18 @@ const rows = [
   { id: 3, color: 'green', flavor: 'strawberry' },
 ];
 
+const inputColumns: Column<(typeof rows)[number]>[] = [
+  {
+    dataKey: 'color',
+    render: (_cell, row) => (
+      <input
+        aria-label={`Color for row ${row?.id}`}
+        defaultValue={row?.color}
+      />
+    ),
+  },
+];
+
 describe('TableBody', () => {
   test("It renders with striped rows if passed 'isStriped' prop", () => {
     render(<TableBody columns={columns} rows={rows} rowKey="id" isStriped />);
@@ -35,4 +48,79 @@ describe('TableBody', () => {
     const tableBody = screen.getByRole('rowgroup');
     expect(tableBody).toHaveClass('my-custom-class');
   });
+
+  test('It preserves row identity when rows are reordered', () => {
+    const { rerender } = render(
+      <table>
+        <TableBody columns={inputColumns} rows={rows} rowKey="id" />
+      </table>
+    );
+
+    fireEvent.change(screen.getByLabelText('Color for row 1'), {
+      target: { value: 'purple' },
+    });
+
+    rerender(
+      <table>
+        <TableBody
+          columns={inputColumns}
+          rows={[...rows].reverse()}
+          rowKey="id"
+        />
+      </table>
+    );
+
+    expect(screen.getByLabelText('Color for row 1')).toHaveValue('purple');
+  });
+
+  test('It avoids duplicate keys when row key values cannot be used', () => {
+    const consoleError = jest.spyOn(console, 'error').mockImplementation();
+    const rowsWithoutUsableKeys = [
+      { id: undefined, color: 'red' },
+      { id: undefined, color: 'blue' },
+      { id: null, color: 'green' },
+      { id: null, color: 'yellow' },
+      { id: {}, color: 'black' },
+      { id: {}, color: 'white' },
+    ];
+
+    render(
+      <table>
+        <TableBody
+          columns={[{ dataKey: 'color' }]}
+          rows={rowsWithoutUsableKeys}
+          rowKey="id"
+        />
+      </table>
+    );
+
+    const duplicateKeyWarnings = consoleError.mock.calls.filter((call) =>
+      call.some(
+        (argument) =>
+          typeof argument === 'string' &&
+          argument.includes('Encountered two children with the same key')
+      )
+    );
+    consoleError.mockRestore();
+
+    expect(duplicateKeyWarnings).toHaveLength(0);
+  });
+
+  test('It handles nullish row values at runtime', () => {
+    const rowsWithNullishValues = [undefined, null] as unknown as typeof rows;
+
+    expect(() =>
+      render(
+        <table>
+          <TableBody
+            columns={columns}
+            rows={rowsWithNullishValues}
+            rowKey="id"
+          />
+        </table>
+      )
+    ).not.toThrow();
+
+    expect(screen.getAllByRole('row')).toHaveLength(2);
+  });
 });

package/src/components/Table/TableBody/TableBody.tsx

@@ -1,22 +1,22 @@
-import React, { FC, Key } from 'react';
+import React from 'react';
 import classNames from 'classnames';
 import styles from './TableBody.module.scss';
 import { Column, Row } from '../../../types';
 import { TableRow } from '../common/TableRow/TableRow';
 
-export interface TableBodyProps {
+export interface TableBodyProps<TRow extends object = Row> {
   /**
    * The table columns to be rendered
    */
-  columns: Column[];
+  columns: Column<TRow>[];
   /**
    * The unique key to identify a React node for each row.
    */
-  rowKey: Key;
+  rowKey: Extract<keyof TRow, string>;
   /**
    * The table rows to be rendered
    */
-  rows: Row[];
+  rows: TRow[];
   /**
    * Text alignment for all table cells. Can be superseded by passing the same prop into the `Column` object
    * for a specific column.
@@ -54,9 +54,10 @@ export interface TableBodyProps {
   truncateOverflow?: boolean;
 }
 
-export const TableBody: FC<TableBodyProps> = ({
+export const TableBody = <TRow extends object = Row,>({
   columns,
   rows,
+  rowKey,
   align = 'left',
   className = '',
   emptyCellPlaceholder = '',
@@ -65,7 +66,7 @@ export const TableBody: FC<TableBodyProps> = ({
   isCompact = false,
   isStriped = false,
   truncateOverflow = false,
-}) => {
+}: TableBodyProps<TRow>) => {
   const tableBodyClasses = classNames(
     styles['table-body'],
     {
@@ -75,6 +76,20 @@ export const TableBody: FC<TableBodyProps> = ({
     className
   );
 
+  const getRowKey = (row: TRow, rowIndex: number): string => {
+    const keyValue = row?.[rowKey];
+
+    if (
+      typeof keyValue === 'string' ||
+      typeof keyValue === 'number' ||
+      typeof keyValue === 'bigint'
+    ) {
+      return `row-key-${String(keyValue)}`;
+    }
+
+    return `row-index-${rowIndex}`;
+  };
+
   return (
     <tbody className={tableBodyClasses}>
       {rows.map((row, rowIndex) => (
@@ -83,7 +98,7 @@ export const TableBody: FC<TableBodyProps> = ({
           row={row}
           rowIndex={rowIndex}
           align={align}
-          key={rowIndex}
+          key={getRowKey(row, rowIndex)}
           emptyCellPlaceholder={emptyCellPlaceholder}
           truncateOverflow={truncateOverflow}
           isBorderless={isBorderless}

package/src/components/Table/TableHead/TableHead.tsx

@@ -1,13 +1,13 @@
-import React, { FC } from 'react';
+import React from 'react';
 import classNames from 'classnames';
-import { Column, EventWithColumnKey } from '../../../types';
+import { Column, EventWithColumnKey, Row } from '../../../types';
 import { TableRow } from '../common/TableRow/TableRow';
 
-export interface TableHeadProps {
+export interface TableHeadProps<TRow extends object = Row> {
   /**
    * The table columns to be rendered
    */
-  columns: Column[];
+  columns: Column<TRow>[];
   /**
    * Text alignment for all table cells. Can be superseded by passing the same prop into the `Column` object
    * for a specific column.
@@ -47,7 +47,7 @@ export interface TableHeadProps {
   truncateOverflow?: boolean;
 }
 
-export const TableHead: FC<TableHeadProps> = ({
+export const TableHead = <TRow extends object = Row,>({
   columns,
   align = 'left',
   className = '',
@@ -57,7 +57,7 @@ export const TableHead: FC<TableHeadProps> = ({
   onSort = undefined,
   sortedColumn = undefined,
   truncateOverflow = false,
-}) => {
+}: TableHeadProps<TRow>) => {
   const tableHeadClasses = classNames(className);
 
   return (

package/src/components/Table/TableHead/TableHeaderCell/TableHeaderCell.tsx

@@ -1,15 +1,15 @@
-import React, { FC, Key, KeyboardEvent, MouseEvent, ReactNode } from 'react';
+import React, { Key, KeyboardEvent, MouseEvent, ReactNode } from 'react';
 import classNames from 'classnames';
 import { Box } from '../../../Box/Box';
 import { Icon } from '../../../Icon/Icon';
-import { Column, EventWithColumnKey } from '../../../../types';
+import { Column, EventWithColumnKey, Row } from '../../../../types';
 import styles from './TableHeaderCell.module.scss';
 
-export interface TableHeaderCellProps {
+export interface TableHeaderCellProps<TRow extends object = Row> {
   /**
    * Title to display for the column.
    */
-  column: Column;
+  column: Column<TRow>;
   /**
    * Text alignment for all table cells. Can be superseded by passing the same prop into the `Column` object
    * for a specific column.
@@ -69,7 +69,7 @@ export interface TableHeaderCellProps {
 }
 
 // eslint-disable-line import/prefer-default-export
-export const TableHeaderCell: FC<TableHeaderCellProps> = ({
+export const TableHeaderCell = <TRow extends object = Row,>({
   column,
   align = 'left',
   className = undefined,
@@ -83,7 +83,7 @@ export const TableHeaderCell: FC<TableHeaderCellProps> = ({
   sticky = undefined,
   truncateOverflow = false,
   width = undefined,
-}) => {
+}: TableHeaderCellProps<TRow>) => {
   const isColumnSorted = (columnDataKey: Key | undefined): boolean =>
     !!sortedColumn && sortedColumn.dataKey === columnDataKey;
 

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

@@ -33,7 +33,7 @@ describe('TableRow', () => {
       render(
         <TableRow row={row} rowIndex={rowIndex} columns={customClassCell} />
       );
-      expect(func).toHaveBeenCalledWith(customClassCell[0], row, rowIndex);
+      expect(func).toHaveBeenCalledWith(row.id, row, rowIndex);
       const element = document.getElementsByClassName('my-custom-class')[0];
       expect(element).toBeInTheDocument();
     });

package/src/components/Table/common/TableRow/TableRow.tsx

@@ -1,4 +1,4 @@
-import React, { FC, ReactNode } from 'react';
+import React, { ReactNode } from 'react';
 import classNames from 'classnames';
 import styles from './TableRow.module.scss';
 import { Column, EventWithColumnKey, Row } from '../../../../types';
@@ -6,11 +6,11 @@ import { getColumnKeys } from '../../../../lib/getColumnKeys';
 import TableBodyCell from '../../TableBody/TableBodyCell/TableBodyCell';
 import { TableHeaderCell } from '../../TableHead/TableHeaderCell/TableHeaderCell';
 
-export interface TableRowProps {
+export interface TableRowProps<TRow extends object = Row> {
   /**
    * The table columns to be rendered
    */
-  columns: Column[];
+  columns: Column<TRow>[];
   /**
    * Text alignment for all table cells. Can be superseded by passing the same prop into the `Column` object
    * for a specific column.
@@ -52,7 +52,7 @@ export interface TableRowProps {
   /**
    * The specific row to be rendered.
    */
-  row?: Row;
+  row?: TRow;
   /**
    * The unique key to identify a React node for each row.
    */
@@ -71,7 +71,7 @@ export interface TableRowProps {
   truncateOverflow?: boolean;
 }
 
-export const TableRow: FC<TableRowProps> = ({
+export const TableRow = <TRow extends object = Row,>({
   columns,
   align = 'left',
   className = '',
@@ -86,7 +86,7 @@ export const TableRow: FC<TableRowProps> = ({
   row = undefined,
   rowIndex = undefined,
   truncateOverflow = false,
-}) => {
+}: TableRowProps<TRow>) => {
   const tableRowClasses = classNames(
     styles['table-row'],
     { [styles.hoverable]: isHoverable },
@@ -110,7 +110,7 @@ export const TableRow: FC<TableRowProps> = ({
     return React.isValidElement(value);
   };
 
-  const renderCellContent = (column: Column): ReactNode => {
+  const renderCellContent = (column: Column<TRow>): ReactNode => {
     if (column.render) {
       const cellValue = column.dataKey && row ? row[column.dataKey] : undefined;
       return column.render(cellValue, row, rowIndex);
@@ -120,10 +120,12 @@ export const TableRow: FC<TableRowProps> = ({
     return isRenderableCell(cellValue) ? cellValue : null;
   };
 
-  const getCellClassName = (column: Column): string | undefined => {
+  const getCellClassName = (column: Column<TRow>): string | undefined => {
     if (column.cellClassName) {
       if (typeof column.cellClassName === 'function') {
-        return column.cellClassName(column, row, rowIndex);
+        const cellValue =
+          column.dataKey && row ? row[column.dataKey] : undefined;
+        return column.cellClassName(cellValue, row, rowIndex);
       }
       return column.cellClassName;
     }

package/src/docs/GetStarted.mdx

@@ -45,3 +45,10 @@ function App() {
 
 ReactDOM.render(<App />, document.querySelector('#app'));
 ```
+
+### 6. Compose with the right element
+
+Use `as` or `asChild` when a Hyphen component needs to render with different
+HTML semantics or reuse a router link or trigger. See
+[Polymorphic Composition](?path=/docs/about-polymorphic-composition--docs) for
+the supported patterns and accessibility guidance.