@tempoxyz/ds 0.2.6 → 0.3.1

package/src/web/components/Table.tsx

@@ -1,6 +1,8 @@
 import type { ComponentPropsWithRef } from 'react'
 import type * as zyzz from 'zyzz'
-import { variants } from '../zyzz.config.js'
+import { keyframes } from 'zyzz/web'
+import { ChevronDown } from '../icons/ChevronDown.js'
+import { style, variants, vars } from '../zyzz.config.js'
 
 /**
  * A native `table` with styled parts. It renders the same element as `Table.Root` and accepts the
@@ -9,7 +11,13 @@ import { variants } from '../zyzz.config.js'
  *
  * - Use it for tabular data only, never for layout.
  * - Name the table with `Table.Caption`, which renders below the rows.
- * - The last column aligns to the end. Set `justify="end"` on other numeric columns to match.
+ * - Each row pads its cells 12px at its edges and keeps 12px between their content.
+ * - The last column aligns to the end. Set `justify="end"` on other amount columns to match, or
+ *   `justify="start"` on a last cell to keep it at the start.
+ * - Set a second line in `Table.Subtitle`, and lead a cell with a `TokenLogo` or a
+ *   `Table.LeadTile`.
+ * - For a sortable column, set `aria-sort` on its `Table.HeaderCell` and put a `Table.SortButton`
+ *   in it.
  * - With `interactive`, make each clickable row reachable by keyboard through a link or button.
  *
  * @example
@@ -18,18 +26,24 @@ import { variants } from '../zyzz.config.js'
  *   <Table.Head>
  *     <Table.Row>
  *       <Table.HeaderCell>Recipient</Table.HeaderCell>
- *       <Table.HeaderCell>Amount</Table.HeaderCell>
+ *       <Table.HeaderCell aria-sort="descending">
+ *         <Table.SortButton>Amount</Table.SortButton>
+ *       </Table.HeaderCell>
  *     </Table.Row>
  *   </Table.Head>
  *   <Table.Body>
  *     <Table.Row>
- *       <Table.Cell>Ada</Table.Cell>
- *       <Table.Cell numeric>120.00</Table.Cell>
+ *       <Table.Cell>
+ *         Ada
+ *         <Table.Subtitle>Rent</Table.Subtitle>
+ *       </Table.Cell>
+ *       <Table.Cell>120.00</Table.Cell>
  *     </Table.Row>
  *   </Table.Body>
  * </Table>
  *
  * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/table/ | WAI-ARIA APG Table pattern}
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/sortable-table/ | WAI-ARIA APG Sortable Table example}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/table | MDN table element}
  * @see {@link https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html | WCAG 2.2 Info and Relationships}
  * @see {@link https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html | WCAG 2.2 Meaningful Sequence}
@@ -50,7 +64,11 @@ export namespace Table {
     export type Props = ComponentPropsWithRef<'tbody'>
   }
 
-  /** The table's accessible name, rendered as a `caption` below the rows. */
+  /**
+   * The table's accessible name, rendered as a `caption` below the rows, such as a note on hidden
+   * rows with an action. An icon in it takes the tertiary color, apart from the icons of its
+   * buttons and links.
+   */
   export function Caption(props: Caption.Props) {
     const { className, vars, ...attributes } = props
 
@@ -63,17 +81,28 @@ export namespace Table {
   }
 
   /**
-   * A data cell. `numeric` sets tabular figures in the foreground color, `mono` sets monospace
-   * type, and `status` colors the text `negative`, `positive` or `warning`. Pair a status color
-   * with text that carries the same meaning.
+   * A data cell, with its text in the primary color. `muted` sets the text in the tertiary color,
+   * `status` colors it `negative`, `positive` or `warning`, `numeric` sets tabular figures, and
+   * `mono` sets monospace type. A `Table.Subtitle` keeps its own type and color. Pair a status
+   * color with text that carries the same meaning. A `StatusChip` in a cell sits 8px inside the
+   * edges of the cell's content.
    */
   export function Cell(props: Cell.Props) {
-    const { className, justify, mono, numeric, status, vars, ...attributes } = props
+    const { className, justify, mono, muted, numeric, status, vars, ...attributes } = props
 
     return (
       <td
         {...attributes}
-        {...styles.cell({ className, justify, mono, numeric, status, style: props.style, vars })}
+        {...styles.cell({
+          className,
+          justify,
+          mono,
+          muted,
+          numeric,
+          status,
+          style: props.style,
+          vars,
+        })}
       />
     )
   }
@@ -97,7 +126,9 @@ export namespace Table {
 
   /**
    * A column header with `scope="col"` by default. Pass `scope="row"` for a row header. Its text
-   * renders in the `label.14.strong` set, heavier than the `copy.14` body cells.
+   * renders in the tertiary color and the smaller `body.b3Strong` set, apart from the primary
+   * `body.b2` body cells. `aria-sort="ascending"` or `"descending"` marks the sorted column and
+   * sets its text in the primary color.
    */
   export function HeaderCell(props: HeaderCell.Props) {
     const { className, justify, vars, ...attributes } = props
@@ -116,12 +147,28 @@ export namespace Table {
   }
 
   /**
-   * The `table` element and its row styles. `size` sets 32, 40 or 56px body rows. Pass
-   * `dividers={false}` to drop row separators. `striped` shades even rows, `fade` masks the bottom
-   * 4rem, and `interactive` adds row hover and focus-visible styles.
+   * A 32px rounded-square `span` that centers a 16px icon at the start of a cell, beside two lines
+   * of text. It adds no semantics, so the text beside it names the row.
+   */
+  export function LeadTile(props: LeadTile.Props) {
+    const { className, vars, ...attributes } = props
+
+    return <span {...attributes} {...styles.leadTile({ className, style: props.style, vars })} />
+  }
+
+  export namespace LeadTile {
+    export type Props = ComponentPropsWithRef<'span'> & zyzz.Props.Variants<typeof styles.leadTile>
+  }
+
+  /**
+   * The `table` element and its row styles. `size` sets 32, 40 or 56px body rows. Rows draw a
+   * divider inset by their padding, except the last one. Pass `dividers={false}` to drop the
+   * dividers, and `interactive` to fill a hovered row and outline a focus-visible one. An
+   * interactive table clips each body row to its 12px corners, so a popup in a cell renders in a
+   * portal.
    */
   export function Root(props: Root.Props) {
-    const { className, dividers, fade, interactive, size, striped, vars, ...attributes } = props
+    const { className, dividers, interactive, size, vars, ...attributes } = props
 
     // `Surface` reads the size to inset the last row's text by its own padding.
     return (
@@ -131,10 +178,8 @@ export namespace Table {
         {...styles.root({
           className,
           dividers,
-          fade,
           interactive,
           size,
-          striped,
           style: props.style,
           vars,
         })}
@@ -146,6 +191,7 @@ export namespace Table {
     export type Props = ComponentPropsWithRef<'table'> & zyzz.Props.Variants<typeof styles.root>
   }
 
+  /** A row. `aria-busy` marks a row of `Skeleton` placeholders, which draw their fill alone. */
   export function Row(props: Row.Props) {
     return <tr {...props} />
   }
@@ -153,48 +199,92 @@ export namespace Table {
   export namespace Row {
     export type Props = ComponentPropsWithRef<'tr'>
   }
+
+  /**
+   * A `button` that fills its `Table.HeaderCell` and sorts the column, with a chevron after its
+   * label. The chevron shows at reduced opacity on hover and focus, and in full once the header
+   * cell sets `aria-sort="ascending"` or `"descending"`. It points up for an ascending sort. The
+   * button handles no sorting itself, so update `aria-sort` in its `onClick`.
+   */
+  export function SortButton(props: SortButton.Props) {
+    const { children, className, vars, ...attributes } = props
+
+    return (
+      <button
+        type="button"
+        {...attributes}
+        {...styles.sortButton({ className, style: props.style, vars })}
+      >
+        <span {...styles.sortLabel()}>
+          {children}
+          <ChevronDown {...styles.sortIcon()} />
+        </span>
+      </button>
+    )
+  }
+
+  export namespace SortButton {
+    export type Props = ComponentPropsWithRef<'button'> &
+      zyzz.Props.Variants<typeof styles.sortButton>
+  }
+
+  /** The second line of a cell, such as the token amount below a value, in secondary `body.b3`. */
+  export function Subtitle(props: Subtitle.Props) {
+    const { className, vars, ...attributes } = props
+
+    return <div {...attributes} {...styles.subtitle({ className, style: props.style, vars })} />
+  }
+
+  export namespace Subtitle {
+    export type Props = ComponentPropsWithRef<'div'> & zyzz.Props.Variants<typeof styles.subtitle>
+  }
 }
 
+const fill = keyframes({ from: { opacity: 0 }, to: { opacity: 1 } }, { id: 'tds/web/table/fill' })
+
 namespace styles {
   export const caption = variants(
     {
       base: {
         captionSide: 'bottom',
-        color: 'gray.900',
-        paddingBlock: '12',
-        paddingInline: '16',
+        color: 'content.secondary',
+        paddingBlockEnd: '4',
+        paddingBlockStart: '12',
+        paddingInline: '12',
         textAlign: 'start',
-        typography: 'copy.13',
+        typography: 'body.b3',
+        selectors: {
+          // `:where` keeps the specificity of the caption, so an icon's own class still applies.
+          '& :where(svg:not(:is(a, button) svg))': { color: 'content.tertiary' },
+        },
       },
     },
     { id: 'tds/web/table/caption' },
   )
 
+  // Cells pad 6px at each side, so the content of neighboring cells sits 12px apart. The root
+  // pads the cells at the edges of a row by 12px.
   export const cell = variants(
     {
       base: {
         boxSizing: 'border-box',
-        color: 'gray.900',
+        color: 'content.primary',
         height: '56',
         paddingBlock: '12',
-        paddingInline: '16',
+        paddingInline: '6',
+        textAlign: 'start',
         verticalAlign: 'middle',
       },
-      defaultVariants: { justify: 'start', mono: false, numeric: false },
+      defaultVariants: { mono: false, muted: false, numeric: false },
       variants: {
         justify: { end: { textAlign: 'end' }, start: { textAlign: 'start' } },
-        mono: { false: {}, true: { typography: 'copy.13.mono', fontSize: '14' } },
-        numeric: {
-          false: {},
-          true: {
-            color: 'foreground',
-            fontVariantNumeric: 'tabular-nums !custom',
-          },
-        },
+        mono: { false: {}, true: { typography: 'mono.m1', fontSize: '14' } },
+        muted: { false: {}, true: { color: 'content.tertiary' } },
+        numeric: { false: {}, true: { fontVariantNumeric: 'tabular-nums !custom' } },
         status: {
-          negative: { color: 'red.900' },
-          positive: { color: 'green.900' },
-          warning: { color: 'amber.900' },
+          negative: { color: 'content.negative' },
+          positive: { color: 'content.positive' },
+          warning: { color: 'content.warning' },
         },
       },
     },
@@ -211,7 +301,7 @@ namespace styles {
           true: {
             selectors: {
               '& th': {
-                backgroundColor: 'background.surface',
+                backgroundColor: 'background.elevated',
                 insetBlockStart: '0',
                 position: 'sticky',
                 zIndex: '1 !custom',
@@ -227,13 +317,18 @@ namespace styles {
   export const headerCell = variants(
     {
       base: {
-        // Body cells share gray.900, the lightest gray step at 4.5:1, so weight separates the header.
-        color: 'gray.900',
-        paddingBlock: '12',
-        paddingInline: '16',
-        typography: 'label.14.strong',
+        color: 'content.tertiary',
+        paddingBlock: '8',
+        paddingInline: '6',
+        textAlign: 'start',
+        transitionDuration: '160',
+        transitionProperty: 'color',
+        transitionTimingFunction: 'snappy',
+        typography: 'body.b3Strong',
+        selectors: {
+          '&:is([aria-sort="ascending"], [aria-sort="descending"])': { color: 'content.primary' },
+        },
       },
-      defaultVariants: { justify: 'start' },
       variants: {
         justify: { end: { textAlign: 'end' }, start: { textAlign: 'start' } },
       },
@@ -241,57 +336,112 @@ namespace styles {
     { id: 'tds/web/table/header-cell' },
   )
 
+  export const leadTile = style(
+    {
+      alignItems: 'center',
+      backgroundColor: 'container.regular',
+      borderRadius: '2xs',
+      boxSizing: 'border-box',
+      color: 'content.primary',
+      display: 'inline-flex',
+      flexShrink: '0 !custom',
+      fontSize: '16',
+      height: '32',
+      justifyContent: 'center',
+      verticalAlign: 'middle',
+      width: '32',
+    },
+    { id: 'tds/web/table/lead-tile' },
+  )
+
   export const root = variants(
     {
       base: {
         borderCollapse: 'separate',
         borderSpacing: '0',
-        color: 'foreground',
-        typography: 'copy.14',
+        color: 'content.primary',
+        typography: 'body.b2',
         width: '100% !custom',
         selectors: {
-          '& tbody td': {
-            borderBlockEnd: '1px solid !custom',
-            borderColor: 'grayAlpha.200',
-          },
-          '& tbody tr:last-child td': { borderBlockEnd: 'none !custom' },
-          '& tr > :last-child': { textAlign: 'end' },
+          // A row has no padding of its own, so the cells at its edges pad its 12px.
+          '& tr > :first-child': { paddingInlineStart: '12' },
+          '& tr > :last-child': { paddingInlineEnd: '12' },
+          // A cell with an explicit `justify` carries `data-justify` and keeps its own alignment.
+          '& tr > :last-child:not([data-justify])': { textAlign: 'end' },
+          // A status chip carries `data-intent`, as its dot does, and sits 8px inside the edges of
+          // the content.
+          '& td [data-intent]:not([data-intent] *)': { marginBlock: '8' },
+          // The placeholders of a loading row draw their fill without the sweep, which a shown
+          // `Skeleton` paints in its `::after`.
+          '& tbody tr[aria-busy="true"] [data-show]::after': { display: 'none' },
         },
       },
       defaultVariants: {
         dividers: true,
-        fade: false,
         interactive: false,
         size: 'medium',
-        striped: false,
       },
       variants: {
+        // A row draws its divider in the 1px that its cells leave below their padding, inset by
+        // the 12px padding of the row.
         dividers: {
-          false: { selectors: { '& tbody td': { borderBlockEnd: 'none !custom' } } },
-          true: {},
-        },
-        fade: {
           false: {},
           true: {
-            maskImage: 'linear-gradient(to bottom, black calc(100% - 4rem), transparent) !custom',
+            selectors: {
+              '& tbody tr:not(:last-child)': { position: 'relative' },
+              '& tbody tr:not(:last-child) > :is(td, th)': {
+                borderBlockEnd: '1px solid transparent !custom',
+              },
+              '& tbody tr:not(:last-child)::after': {
+                backgroundColor: 'line.secondary',
+                content: '"" !custom',
+                height: '1',
+                insetBlockEnd: '0',
+                insetInline: '12',
+                position: 'absolute',
+                transitionDuration: '160',
+                transitionProperty: 'background-color',
+                transitionTimingFunction: 'snappy',
+              },
+            },
           },
         },
+        // A hovered row paints container.subtle over background.elevated, rounded by its clip, so
+        // the opaque fill hides the dividers above and below it. Chromium gives a row's `::before`
+        // a column of its own, so the `::after` that draws the divider also draws the subtle layer,
+        // behind the cells, and fades it in with a keyframe instead of from the divider color.
         interactive: {
           false: {},
           true: {
             selectors: {
               '& tbody tr': {
+                borderRadius: 'xs',
+                // The clip rounds the fill of the row by radius xs, which a row background ignores.
+                clipPath: 'inset(0 round 12px) !custom',
                 outlineColor: 'transparent !custom',
                 outlineOffset: '0',
                 outlineStyle: 'solid !custom',
                 outlineWidth: '2',
+                position: 'relative',
                 transitionDuration: '160',
                 transitionProperty: 'background-color, outline-color, outline-offset',
                 transitionTimingFunction: 'snappy',
               },
-              '& tbody tr:hover': { backgroundColor: 'grayAlpha.100' },
+              '& tbody tr:hover': { backgroundColor: 'background.elevated' },
+              '& tbody tr:hover::after': {
+                animation: `${fill} 160ms ${vars.ease.snappy} !custom`,
+                backgroundColor: 'container.subtle',
+                borderRadius: 'xs',
+                content: '"" !custom',
+                height: 'auto !custom',
+                inset: '0',
+                position: 'absolute',
+                transitionProperty: 'none',
+                zIndex: '-1 !custom',
+              },
+              '& tbody tr:has(+ tr:hover)::after': { backgroundColor: 'transparent !custom' },
               '& tbody tr:focus-visible': {
-                outlineColor: 'blue.700',
+                outlineColor: 'border.focus',
                 outlineOffset: '-2',
               },
               '& tbody tr:is([tabindex], [role="button"], [data-href]):hover': {
@@ -305,24 +455,85 @@ namespace styles {
             },
           },
         },
-        // Body rows follow the shared control scale: 32, 40 and 56px. Cells keep their typography.
+        // Body rows follow the shared control scale: 32, 40 and 56px. Header cells keep 8px above
+        // and below their text, apart from small tables. Cells keep their typography.
         size: {
           large: {},
-          medium: {
-            selectors: { '& :is(td, th)': { paddingBlock: '8' }, '& td': { height: '40' } },
-          },
+          medium: { selectors: { '& td': { height: '40', paddingBlock: '8' } } },
           small: {
             selectors: { '& :is(td, th)': { paddingBlock: '4' }, '& td': { height: '32' } },
           },
         },
-        striped: {
-          false: {},
-          true: {
-            selectors: { '& tbody tr:nth-child(even)': { backgroundColor: 'grayAlpha.100' } },
-          },
-        },
       },
     },
     { id: 'tds/web/table/root' },
   )
+
+  export const sortButton = style(
+    {
+      backgroundColor: 'transparent !custom',
+      border: 'none !custom',
+      borderRadius: '3xs',
+      boxSizing: 'border-box',
+      color: 'content.tertiary',
+      cursor: 'pointer',
+      display: 'block',
+      margin: '0',
+      outlineColor: 'transparent !custom',
+      outlineOffset: '0',
+      outlineStyle: 'solid !custom',
+      outlineWidth: '2',
+      padding: '0',
+      // The label follows the alignment of its header cell.
+      textAlign: 'inherit !custom',
+      transitionDuration: '160',
+      transitionProperty: 'color, outline-color, outline-offset',
+      transitionTimingFunction: 'snappy',
+      typography: 'body.b3Strong',
+      width: '100% !custom',
+      selectors: {
+        '&:is(:hover, :focus-visible):not(:disabled), [aria-sort="ascending"] > &, [aria-sort="descending"] > &':
+          { color: 'content.primary' },
+        // A disabled button sorts nothing, so it keeps its resting look under the pointer.
+        '&:disabled': { cursor: 'default' },
+        '&:focus-visible': { outlineColor: 'border.focus', outlineOffset: '2' },
+      },
+      '@media (prefers-reduced-motion: reduce)': { transitionProperty: 'color, outline-color' },
+    },
+    { id: 'tds/web/table/sort-button' },
+  )
+
+  export const sortIcon = style(
+    {
+      color: 'content.tertiary',
+      display: 'none',
+      flexShrink: '0 !custom',
+      fontSize: '12',
+      opacity: '0.4 !custom',
+      transitionDuration: '160',
+      transitionProperty: 'opacity, rotate',
+      transitionTimingFunction: 'snappy',
+      selectors: {
+        // The icon sits in the label of the button, in the header cell.
+        ':is(:hover, :focus-visible):not(:disabled) > * > &': { display: 'block' },
+        ':is([aria-sort="ascending"], [aria-sort="descending"]) > * > * > &': {
+          display: 'block',
+          opacity: '1 !custom',
+        },
+        '[aria-sort="ascending"] > * > * > &': { rotate: '180deg !custom' },
+      },
+      '@media (prefers-reduced-motion: reduce)': { transitionProperty: 'opacity' },
+    },
+    { id: 'tds/web/table/sort-icon' },
+  )
+
+  export const sortLabel = style(
+    { alignItems: 'center', columnGap: '4', display: 'inline-flex' },
+    { id: 'tds/web/table/sort-label' },
+  )
+
+  export const subtitle = style(
+    { color: 'content.secondary', marginBlockStart: '2', typography: 'body.b3' },
+    { id: 'tds/web/table/subtitle' },
+  )
 }