@vitavision/ui 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitavision/ui",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "The vitavision instrument design system: Tailwind v4 tokens, theme, and React primitives.",
   "license": "MIT OR Apache-2.0",
   "repository": {

package/src/components/ThemeToggle.tsx

@@ -1,5 +1,5 @@
 /*
- * The palette switch, shared by every lab app.
+ * The palette switch.
  *
  * Three states, not two, and cycled by one button rather than spread across a
  * segmented control: this sits in a header next to the thing the app is
@@ -8,8 +8,7 @@
  * silently stops following the OS the first time you touch the switch has taken
  * something away.
  *
- * Lived in visual-anomaly-lab's own `App.tsx` first. It moved here the moment a
- * second app needed it, rather than being copied: two copies of a control that
+ * One shared control rather than a copy per app: two copies of a control that
  * writes to `localStorage` is two chances to disagree about the key, the cycle
  * order, or which icon means which state.
  *

package/src/components/ui/Table.tsx

@@ -4,12 +4,18 @@
  * `numeric` is the column property that matters here. Quantities are set in mono with
  * tabular figures and aligned right, so a column of scores or measurements can be compared
  * by eye down its decimal point rather than read one row at a time.
+ *
+ * Sorting is per column and follows the sortable-table pattern of the ARIA Authoring
+ * Practices: the header's content is a button, and only the sorted header carries
+ * `aria-sort`. The order itself lives in `tableSort.ts`.
  */
 
-import type { KeyboardEvent, MouseEvent, ReactNode } from "react";
+import { ArrowDown, ArrowUp, ArrowUpDown } from "lucide-react";
+import { type KeyboardEvent, type MouseEvent, type ReactNode, useMemo, useState } from "react";
 
 import { byDensity, useDensity } from "./Density";
-import { cn } from "./cn";
+import { cn, focusRing } from "./cn";
+import { isSortable, nextSort, type SortDirection, sortOrder, type TableSort } from "./tableSort";
 
 /** One column of a `Table`: its header and how to render a row's cell. */
 export type Column<Row> = {
@@ -23,14 +29,49 @@ export type Column<Row> = {
   width?: string;
   /** The cell's content for a row. */
   cell: (row: Row) => ReactNode;
+  /**
+   * Whether the header sorts the table. Defaults to `true` when the column has a `sortValue`
+   * or a `compare`. Set it `true` with neither for a column the app sorts itself (see the
+   * table's `manualSort`), or `false` to keep a column with a `sortValue` unsortable.
+   */
+  sortable?: boolean | undefined;
+  /**
+   * The value the column sorts by. Numbers compare by value; strings by a fixed English
+   * collation that reads digit runs as numbers ("frame 9" before "frame 10"), so a server
+   * render and the browser agree; numbers come before strings. `null`, `undefined` and `NaN`
+   * go last in both directions.
+   */
+  sortValue?: ((row: Row) => number | string | null | undefined) | undefined;
+  /**
+   * A full ascending comparison, for an order one value cannot express (two fields, a rank):
+   * negative when `a` comes first. Takes precedence over `sortValue`. Reversed for
+   * `"descending"`; rows that compare equal keep their order in `rows` either way.
+   */
+  compare?: ((a: Row, b: Row) => number) | undefined;
+  /**
+   * The direction of the first click on the header. Defaults to `"ascending"`; `"descending"`
+   * suits a score, where the best comes first.
+   */
+  firstSort?: SortDirection | undefined;
 };
 
+/** The header icon for a sort state: the direction when sorted, both arrows when only sortable. */
+const SORT_ICONS = { ascending: ArrowUp, descending: ArrowDown, none: ArrowUpDown } as const;
+
 /**
  * A table of rows, with numeric columns set in mono and right-aligned.
  *
  * With `onRowClick` the rows are keyboard-reachable (Tab, then Enter or Space) while keeping
  * their table semantics. The active row carries `aria-current` and `data-state="active"`;
  * padding follows the density in force. With no rows it renders the `empty` message instead.
+ *
+ * A column with a `sortValue` or a `compare` gets a header button: each click moves its sort
+ * from the column's `firstSort` direction to the other one, then back to the rows' own order.
+ * The sorted header carries `aria-sort` and `data-sort` (`"ascending"` or `"descending"`);
+ * other sortable headers carry `data-sort="none"`. The sort is kept by the table (from
+ * `defaultSort`) or controlled (`sort` with `onSortChange`); with `manualSort` the headers
+ * show it and the rows render as given. Row callbacks always receive a row's index in `rows`,
+ * whatever the order on screen.
  */
 export function Table<Row>({
   columns,
@@ -42,12 +83,16 @@ export function Table<Row>({
   onRowClick,
   isRowActive,
   onRowHover,
+  sort: controlledSort,
+  defaultSort = null,
+  onSortChange,
+  manualSort = false,
 }: {
   /** The columns, in order. */
   columns: Column<Row>[];
-  /** The rows, in order. */
+  /** The rows, in their own order: the order shown while the table is not sorted. */
   rows: Row[];
-  /** A stable key per row. */
+  /** A stable key per row. `index` is the row's position in `rows`, whatever the sort. */
   rowKey: (row: Row, index: number) => string | number;
   /** Shown instead of the table when there are no rows. Defaults to "Nothing here.". */
   empty?: ReactNode;
@@ -58,20 +103,53 @@ export function Table<Row>({
   /** Makes rows activatable. Keyboard-reachable, so a table used as a list of
    * destinations is not a mouse-only control. The event is passed so a caller can read
    * modifiers — a list kept in step with a canvas needs shift-range and meta-toggle to mean
-   * the same thing in both places. */
+   * the same thing in both places. `index` is the row's position in `rows`, whatever the
+   * sort. */
   onRowClick?: (
     row: Row,
     index: number,
     event: MouseEvent<HTMLTableRowElement> | KeyboardEvent<HTMLTableRowElement>,
   ) => void;
   /** Marks the row that is current — the selected match, the open frame. Rendered as
-   * `aria-current`, so it is announced rather than only tinted. */
+   * `aria-current`, so it is announced rather than only tinted. `index` is the row's
+   * position in `rows`, whatever the sort. */
   isRowActive?: (row: Row, index: number) => boolean;
   /** Pointer enter/leave, for tables kept in step with a canvas overlay.
-   * `null` on leave. */
+   * `null` on leave. `index` is the row's position in `rows`, whatever the sort. */
   onRowHover?: (row: Row | null, index: number | null) => void;
+  /**
+   * The sort, controlled: a column `key` and a direction, or `null` for the rows' own order.
+   * Leave it undefined and the table keeps the sort itself, starting from `defaultSort`.
+   */
+  sort?: TableSort | null | undefined;
+  /** The sort the table starts with when `sort` is not given. Defaults to `null`, the rows' own order. */
+  defaultSort?: TableSort | null | undefined;
+  /**
+   * Called on a header click with the new sort: the column's `firstSort` direction, then the
+   * other, then `null`. A click on another column starts that column at its `firstSort`.
+   */
+  onSortChange?: ((sort: TableSort | null) => void) | undefined;
+  /**
+   * The app orders the rows (on a server, say): the headers show the sort and report clicks,
+   * and the rows render exactly as given. Mark the columns it can sort `sortable: true`.
+   */
+  manualSort?: boolean | undefined;
 }) {
   const density = useDensity();
+  const [ownSort, setOwnSort] = useState<TableSort | null>(defaultSort);
+  const controlled = controlledSort !== undefined;
+  const sort = controlled ? controlledSort : ownSort;
+  // Indices into `rows`, so a row keeps its own index (and key) for the callbacks below.
+  const order = useMemo(
+    () => (manualSort ? rows.map((_, index) => index) : sortOrder(rows, columns, sort)),
+    [rows, columns, sort, manualSort],
+  );
+
+  const changeSort = (column: Column<Row>) => {
+    const next = nextSort(sort, column);
+    if (!controlled) setOwnSort(next);
+    onSortChange?.(next);
+  };
 
   if (rows.length === 0) {
     return (
@@ -93,68 +171,113 @@ export function Table<Row>({
         {caption && <caption className="sr-only">{caption}</caption>}
         <thead>
           <tr className="border-b border-line">
-            {columns.map((column) => (
-              <th
-                key={column.key}
-                scope="col"
-                style={column.width ? { width: column.width } : undefined}
-                className={cn(
-                  "font-medium text-fg-muted",
-                  byDensity(density, "pb-2 pr-3 text-xs", "pb-1 pr-2 text-[10px]"),
-                  column.numeric && "text-right",
-                )}
-              >
-                {column.header}
-              </th>
-            ))}
-          </tr>
-        </thead>
-        <tbody>
-          {rows.map((row, index) => (
-            <tr
-              key={rowKey(row, index)}
-              data-state={isRowActive?.(row, index) ? "active" : undefined}
-              className={cn(
-                "border-b border-line/60 last:border-0",
-                onRowClick && "cursor-pointer hover:bg-raised",
-                isRowActive?.(row, index) && "bg-signal/10",
-              )}
-              tabIndex={onRowClick ? 0 : undefined}
-              // Deliberately *not* `role="button"`. Overriding a `<tr>`'s implicit `row`
-              // makes its `<td>`s' implicit `cell` invalid too — the cells have no row to
-              // belong to — so a screen reader stops announcing the table as a table and a
-              // reader loses the column each value came from, which on a table of
-              // quantities is the whole content. `tabIndex` plus the Enter/Space handler
-              // below is what makes the row reachable; the role stays what the element is.
-              aria-current={isRowActive?.(row, index) ? true : undefined}
-              onClick={onRowClick ? (event) => onRowClick(row, index, event) : undefined}
-              onKeyDown={
-                onRowClick
-                  ? (event) => {
-                      if (event.key === "Enter" || event.key === " ") {
-                        event.preventDefault();
-                        onRowClick(row, index, event);
-                      }
-                    }
-                  : undefined
-              }
-              onPointerEnter={onRowHover ? () => onRowHover(row, index) : undefined}
-              onPointerLeave={onRowHover ? () => onRowHover(null, null) : undefined}
-            >
-              {columns.map((column) => (
-                <td
+            {columns.map((column) => {
+              const sortable = isSortable(column);
+              const direction = sortable && sort?.key === column.key ? sort.direction : undefined;
+              const SortIcon = SORT_ICONS[direction ?? "none"];
+              return (
+                <th
                   key={column.key}
+                  scope="col"
+                  style={column.width ? { width: column.width } : undefined}
+                  // Only the sorted header: `aria-sort="none"` on every other one would be
+                  // announced on each, and tells a reader nothing.
+                  aria-sort={direction}
+                  data-sort={sortable ? (direction ?? "none") : undefined}
                   className={cn(
-                    "align-middle text-fg last:pr-0",
-                    byDensity(density, "py-2 pr-3", "py-0.5 pr-2"),
-                    column.numeric && "text-right font-mono tabular-nums",
+                    // `last:pr-0`, as on the body cells: the last column's header ends where
+                    // its values do, so a numeric header sits flush with its numbers.
+                    "font-medium text-fg-muted last:pr-0",
+                    byDensity(density, "pb-2 pr-3 text-xs", "pb-1 pr-2 text-[10px]"),
+                    column.numeric && "text-right",
                   )}
                 >
-                  {column.cell(row)}
-                </td>
-              ))}
-            </tr>
-          ))}
+                  {sortable ? (
+                    <button
+                      type="button"
+                      onClick={() => changeSort(column)}
+                      className={cn(
+                        // Block-level `flex`, not `inline-flex`: an inline box would sit on the
+                        // cell's line box and make a sortable header row 2px taller than a plain
+                        // one. The padding, cancelled by the margin, gives the focus ring room
+                        // without moving the label off the column's edge.
+                        "-mx-1 flex w-fit max-w-full cursor-pointer items-center gap-1 rounded-control px-1",
+                        "font-medium transition-colors hover:text-fg",
+                        focusRing,
+                        // The arrow sits on the inner side of a right-aligned header, so the
+                        // label stays flush with the numbers under it.
+                        column.numeric ? "ml-auto flex-row-reverse text-right" : "text-left",
+                        direction && "text-fg",
+                      )}
+                    >
+                      {column.header}
+                      <SortIcon
+                        aria-hidden
+                        className={cn(
+                          "shrink-0",
+                          byDensity(density, "size-3", "size-2.5"),
+                          !direction && "text-fg-subtle",
+                        )}
+                      />
+                    </button>
+                  ) : (
+                    column.header
+                  )}
+                </th>
+              );
+            })}
+          </tr>
+        </thead>
+        <tbody>
+          {order.map((index) => {
+            const row = rows[index]!;
+            const active = isRowActive?.(row, index) ?? false;
+            return (
+              <tr
+                key={rowKey(row, index)}
+                data-state={active ? "active" : undefined}
+                className={cn(
+                  "border-b border-line/60 last:border-0",
+                  onRowClick && "cursor-pointer hover:bg-raised",
+                  active && "bg-signal/10",
+                )}
+                tabIndex={onRowClick ? 0 : undefined}
+                // Deliberately *not* `role="button"`. Overriding a `<tr>`'s implicit `row`
+                // makes its `<td>`s' implicit `cell` invalid too — the cells have no row to
+                // belong to — so a screen reader stops announcing the table as a table and a
+                // reader loses the column each value came from, which on a table of
+                // quantities is the whole content. `tabIndex` plus the Enter/Space handler
+                // below is what makes the row reachable; the role stays what the element is.
+                aria-current={active ? true : undefined}
+                onClick={onRowClick ? (event) => onRowClick(row, index, event) : undefined}
+                onKeyDown={
+                  onRowClick
+                    ? (event) => {
+                        if (event.key === "Enter" || event.key === " ") {
+                          event.preventDefault();
+                          onRowClick(row, index, event);
+                        }
+                      }
+                    : undefined
+                }
+                onPointerEnter={onRowHover ? () => onRowHover(row, index) : undefined}
+                onPointerLeave={onRowHover ? () => onRowHover(null, null) : undefined}
+              >
+                {columns.map((column) => (
+                  <td
+                    key={column.key}
+                    className={cn(
+                      "align-middle text-fg last:pr-0",
+                      byDensity(density, "py-2 pr-3", "py-0.5 pr-2"),
+                      column.numeric && "text-right font-mono tabular-nums",
+                    )}
+                  >
+                    {column.cell(row)}
+                  </td>
+                ))}
+              </tr>
+            );
+          })}
         </tbody>
       </table>
     </div>

package/src/components/ui/index.ts

@@ -70,6 +70,7 @@ export { SegmentedControl } from "./SegmentedControl";
 export { Select, type SelectOption } from "./Select";
 export { Slider } from "./Slider";
 export { Table, type Column } from "./Table";
+export { sortRows, type SortDirection, type TableSort } from "./tableSort";
 export { Checkbox, Switch } from "./Toggle";
 export { ToggleChip } from "./ToggleChip";
 export { Toaster, type ToasterProps } from "./Toaster";

package/src/components/ui/tableSort.ts

@@ -0,0 +1,121 @@
+/*
+ * The order of a sorted `Table`, as pure functions so it is tested without a DOM, and so an app
+ * can reproduce the table's order (next/previous navigation, an export, a server that sorts the
+ * same way) with `sortRows`.
+ *
+ * The order is deterministic across machines: strings go through one collator with a fixed
+ * locale, so a server render and the browser that hydrates it put the rows in the same order.
+ * A `Collator` is not DOM, so building it once at module scope keeps the package SSR-safe.
+ */
+
+import type { Column } from "./Table";
+
+/** Which way a column is sorted. Named as `aria-sort` names them: `"ascending"` puts the smallest first. */
+export type SortDirection = "ascending" | "descending";
+
+/** The column a table is sorted by, and which way. Where a sort is expected, `null` means the rows' own order. */
+export interface TableSort {
+  /** The sorted column's `key`. */
+  key: string;
+  /** Which way. */
+  direction: SortDirection;
+}
+
+/** The column fields that decide the order. */
+type SortColumn<Row> = Pick<Column<Row>, "key" | "sortable" | "sortValue" | "compare">;
+
+/** Strings by a fixed English collation that reads digit runs as numbers: "frame 9" before "frame 10". */
+const collator = new Intl.Collator("en", { numeric: true });
+
+/**
+ * Whether a column's header sorts the table: `sortable` if given, otherwise whether the column
+ * says how to order (`sortValue` or `compare`).
+ */
+export function isSortable<Row>(column: Pick<Column<Row>, "sortable" | "sortValue" | "compare">): boolean {
+  return column.sortable ?? (column.sortValue !== undefined || column.compare !== undefined);
+}
+
+/** The sort after a click on `column`'s header: its first direction, then the other, then none. */
+export function nextSort<Row>(
+  current: TableSort | null,
+  column: Pick<Column<Row>, "key" | "firstSort">,
+): TableSort | null {
+  const first = column.firstSort ?? "ascending";
+  if (current?.key !== column.key) return { key: column.key, direction: first };
+  if (current.direction !== first) return null;
+  return { key: column.key, direction: first === "ascending" ? "descending" : "ascending" };
+}
+
+/** A value with no place in the order: `null`, `undefined` or `NaN`. */
+function missing(value: number | string | null | undefined): boolean {
+  return value === null || value === undefined || Number.isNaN(value);
+}
+
+/**
+ * Two present values in ascending order: numbers by value (compared, not subtracted, so two
+ * infinities tie), strings by the collator, and every number before every string.
+ */
+function compareValues(a: number | string, b: number | string): number {
+  if (typeof a === "number" && typeof b === "number") return a < b ? -1 : a > b ? 1 : 0;
+  if (typeof a === "string" && typeof b === "string") return collator.compare(a, b);
+  return typeof a === "number" ? -1 : 1;
+}
+
+/**
+ * The display order of `rows` under `sort`, as indices into `rows`. `Table` renders through it
+ * so each row keeps its original index for the row callbacks.
+ */
+export function sortOrder<Row>(
+  rows: readonly Row[],
+  columns: readonly SortColumn<Row>[],
+  sort: TableSort | null | undefined,
+): number[] {
+  const order = rows.map((_, index) => index);
+  if (!sort) return order;
+  const column = columns.find((candidate) => candidate.key === sort.key);
+  if (!column || !isSortable(column)) return order;
+  const sign = sort.direction === "descending" ? -1 : 1;
+
+  // Every comparison falls back to the original index, so equal rows keep their order in both
+  // directions: descending is not ascending reversed, it is ascending with each run of ties kept.
+  const { compare, sortValue } = column;
+  if (compare) return order.sort((a, b) => sign * compare(rows[a]!, rows[b]!) || a - b);
+  if (!sortValue) return order;
+
+  // One call per row, not two per comparison: a `sortValue` may parse or look something up.
+  const values = rows.map((row) => sortValue(row));
+  return order.sort((a, b) => {
+    const left = values[a];
+    const right = values[b];
+    const leftMissing = missing(left);
+    const rightMissing = missing(right);
+    // Missing values go last whichever way the column is sorted: a reader sorting by score in
+    // either direction wants the rows that have one.
+    if (leftMissing || rightMissing) return leftMissing === rightMissing ? a - b : leftMissing ? 1 : -1;
+    return sign * compareValues(left!, right!) || a - b;
+  });
+}
+
+/**
+ * The rows in the order a `Table` with these columns shows them under `sort`.
+ *
+ * The sort is stable in both directions: rows that compare equal keep their order in `rows`.
+ * With the column's `compare`, that function decides (reversed for `"descending"`). With its
+ * `sortValue`, numbers compare by value and strings by a fixed English collation that reads
+ * digit runs as numbers ("frame 9" before "frame 10"), the same on a server as in any
+ * browser; numbers come before strings; and `null`, `undefined` and `NaN` go last in both
+ * directions. A `null` sort, a `key` that names no column, and a column that is not sortable or
+ * has neither function leave the order as given.
+ *
+ * @param rows - The rows, in their own order. Not modified.
+ * @param columns - The table's columns; only `key`, `sortable`, `sortValue` and `compare` are read.
+ * @param sort - The column and direction, or `null` for the rows' own order.
+ * @returns A new array of the same rows, sorted.
+ */
+export function sortRows<Row>(
+  rows: readonly Row[],
+  columns: readonly Pick<Column<Row>, "key" | "sortable" | "sortValue" | "compare">[],
+  sort: TableSort | null | undefined,
+): Row[] {
+  return sortOrder(rows, columns, sort).map((index) => rows[index]!);
+}

package/src/fonts/fonts.css

@@ -1,5 +1,5 @@
 /*
- * IBM Plex for the @vitavision packages (ADR-0003): import once, next to styles.css.
+ * IBM Plex for the @vitavision packages: import once, next to styles.css.
  *
  *   @import "@vitavision/ui/fonts.css";
  *

package/src/styles.css

@@ -5,12 +5,8 @@
 @source "./";
 
 /*
- * The design token layer.
- *
- * Extracted from visual-anomaly-lab's own token layer (its ADR-0021), where it was written
- * to close a real gap: eleven screens with every colour inlined as a raw `slate-*` utility
- * at 250-odd call sites — the same palette restated 250 times rather than defined once.
- * This file is that definition, shared now by every lab app rather than owned by one.
+ * The design token layer: every colour, radius and font the components use, defined once
+ * here rather than restated as raw palette utilities at each call site.
  *
  * The direction is *instrument*: the chrome is grey so the data can be loud. Anomaly maps,
  * colormaps, grayscale sensor images and vector measurement overlays are what these
@@ -70,7 +66,7 @@
  * Every value below is held by `contrast.test.ts` (WCAG 2.2 AA, both themes): text ≥ 4.5:1
  * on every surface, including each verdict colour and `signal` on its own /12 tint, and the
  * control boundary `line-strong` and `signal` (focus, checked) ≥ 3:1. `signal` and `normal`
- * are also kept apart for a tritanope (docs/visual-language.md §1) — the reason the light
+ * are also kept apart for a tritanope — the reason the light
  * accent is a deep slate-teal rather than a brighter one. Change a value only with the tests.
  */
 :root {