@vitavision/ui 0.11.0 → 0.12.0

package/README.md

@@ -2,7 +2,7 @@
 
 The vitavision *instrument* design system: true-neutral greys, one accent, and verdict colours
 reserved for verdicts. Tailwind v4 design tokens, a theme controller, and the React primitives
-every lab app shares. React 19, no CSS-in-JS, no runtime theme engine.
+every vitavision app shares. React 19, no CSS-in-JS, no runtime theme engine.
 
 ## Install
 
@@ -31,7 +31,7 @@ Each stylesheet ships **unprocessed** — Tailwind v4 *source*, resolved by your
 declares its own `@source "./"`, which Tailwind resolves against that stylesheet: the package's
 class names are found without an `@source` line of yours.
 
-`fonts.css` serves the type pair, IBM Plex Sans and IBM Plex Mono (ADR-0003), from files in this
+`fonts.css` serves the type pair, IBM Plex Sans and IBM Plex Mono, from files in this
 package (SIL Open Font License). Its Plex Mono is IBM's own build, which keeps the `zero` feature,
 so values get a slashed zero; `unicode-range` means a page fetches only the subsets its text
 uses (about 80 KB for Latin). Drop any fontsource or Google Fonts Plex you loaded before — their

package/dist/index.d.ts

@@ -998,6 +998,34 @@ export declare function Slider({ value, onValueChange, onValueCommit, min, max,
   className?: string | undefined;
 }): import("react").JSX.Element;
 //#endregion
+//#region src/components/ui/tableSort.d.ts
+/** Which way a column is sorted. Named as `aria-sort` names them: `"ascending"` puts the smallest first. */
+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. */
+interface TableSort {
+  /** The sorted column's `key`. */
+  key: string;
+  /** Which way. */
+  direction: SortDirection;
+}
+/**
+ * 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 declare function sortRows<Row>(rows: readonly Row[], columns: readonly Pick<Column<Row>, "key" | "sortable" | "sortValue" | "compare">[], sort: TableSort | null | undefined): Row[];
+//#endregion
 //#region src/components/ui/Table.d.ts
 /** One column of a `Table`: its header and how to render a row's cell. */
 type Column<Row> = {
@@ -1011,6 +1039,30 @@ 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;
 };
 /**
  * A table of rows, with numeric columns set in mono and right-aligned.
@@ -1018,13 +1070,21 @@ type Column<Row> = {
  * 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.
- */
-export declare function Table<Row>({ columns, rows, rowKey, empty, caption, className, onRowClick, isRowActive, onRowHover }: {
+ *
+ * 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 declare function Table<Row>({ columns, rows, rowKey, empty, caption, className, onRowClick, isRowActive, onRowHover, sort: controlledSort, defaultSort, onSortChange, manualSort }: {
   /** 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;
@@ -1035,14 +1095,33 @@ export declare function Table<Row>({ columns, rows, rowKey, empty, caption, clas
   /** 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;
 }): import("react").JSX.Element;
 //#endregion
 //#region src/components/ui/Toggle.d.ts
@@ -1343,5 +1422,5 @@ export declare function Tabs<Id extends string>({ items, active, onSelect, label
   className?: string | undefined;
 }): import("react").JSX.Element;
 //#endregion
-export type { BackLink, ButtonSize, ButtonVariant, CalloutTone, Column, Density, DropdownMenuProps, ListboxOption, ListboxOptionState, ListboxProps, MeasureTone, MenuCheckboxItemProps, MenuItemProps, NumberInputProps, PopoverProps, PoseInputProps, PoseValue, Quaternion, ReadoutItem, RotationView, SelectOption, TabItem, ThemeChoice, ToastOptions, ToastRecord, ToastStore, ToastTone, ToasterProps, Tone, Vec3, VectorInputProps };
+export type { BackLink, ButtonSize, ButtonVariant, CalloutTone, Column, Density, DropdownMenuProps, ListboxOption, ListboxOptionState, ListboxProps, MeasureTone, MenuCheckboxItemProps, MenuItemProps, NumberInputProps, PopoverProps, PoseInputProps, PoseValue, Quaternion, ReadoutItem, RotationView, SelectOption, SortDirection, TabItem, TableSort, ThemeChoice, ToastOptions, ToastRecord, ToastStore, ToastTone, ToasterProps, Tone, Vec3, VectorInputProps };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-import { AlertTriangle, Check, CheckCircle2, ChevronDown, ChevronRight, CircleCheck, CircleX, HelpCircle, Info, Loader2, Minus, Moon, Sun, SunMoon, TriangleAlert, X, XCircle } from "lucide-react";
+import { AlertTriangle, ArrowDown, ArrowUp, ArrowUpDown, Check, CheckCircle2, ChevronDown, ChevronRight, CircleCheck, CircleX, HelpCircle, Info, Loader2, Minus, Moon, Sun, SunMoon, TriangleAlert, X, XCircle } from "lucide-react";
 import { createContext, isValidElement, use, useCallback, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import * as RadixTooltip from "@radix-ui/react-tooltip";
 import { clsx } from "clsx";
@@ -1775,16 +1775,123 @@ function Slider({ value, onValueChange, onValueCommit, min = 0, max = 1, step =
 	});
 }
 //#endregion
+//#region src/components/ui/tableSort.ts
+/** 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`).
+*/
+function isSortable(column) {
+	return column.sortable ?? (column.sortValue !== void 0 || column.compare !== void 0);
+}
+/** The sort after a click on `column`'s header: its first direction, then the other, then none. */
+function nextSort(current, column) {
+	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) {
+	return value === null || value === void 0 || 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, b) {
+	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.
+*/
+function sortOrder(rows, columns, sort) {
+	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;
+	const { compare, sortValue } = column;
+	if (compare) return order.sort((a, b) => sign * compare(rows[a], rows[b]) || a - b);
+	if (!sortValue) return order;
+	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);
+		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.
+*/
+function sortRows(rows, columns, sort) {
+	return sortOrder(rows, columns, sort).map((index) => rows[index]);
+}
+//#endregion
 //#region src/components/ui/Table.tsx
+/** 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
+};
 /**
 * 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.
-*/
-function Table({ columns, rows, rowKey, empty = "Nothing here.", caption, className, onRowClick, isRowActive, onRowHover }) {
+*
+* 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.
+*/
+function Table({ columns, rows, rowKey, empty = "Nothing here.", caption, className, onRowClick, isRowActive, onRowHover, sort: controlledSort, defaultSort = null, onSortChange, manualSort = false }) {
 	const density = useDensity();
+	const [ownSort, setOwnSort] = useState(defaultSort);
+	const controlled = controlledSort !== void 0;
+	const sort = controlled ? controlledSort : ownSort;
+	const order = useMemo(() => manualSort ? rows.map((_, index) => index) : sortOrder(rows, columns, sort), [
+		rows,
+		columns,
+		sort,
+		manualSort
+	]);
+	const changeSort = (column) => {
+		const next = nextSort(sort, column);
+		if (!controlled) setOwnSort(next);
+		onSortChange?.(next);
+	};
 	if (rows.length === 0) return /* @__PURE__ */ jsx("p", {
 		className: cn("text-center text-fg-muted", byDensity(density, "py-6 text-sm", "py-3 text-xs"), className),
 		children: empty
@@ -1800,32 +1907,51 @@ function Table({ columns, rows, rowKey, empty = "Nothing here.", caption, classN
 				}),
 				/* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsx("tr", {
 					className: "border-b border-line",
-					children: columns.map((column) => /* @__PURE__ */ jsx("th", {
-						scope: "col",
-						style: column.width ? { width: column.width } : void 0,
-						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"),
-						children: column.header
-					}, column.key))
+					children: columns.map((column) => {
+						const sortable = isSortable(column);
+						const direction = sortable && sort?.key === column.key ? sort.direction : void 0;
+						const SortIcon = SORT_ICONS[direction ?? "none"];
+						return /* @__PURE__ */ jsx("th", {
+							scope: "col",
+							style: column.width ? { width: column.width } : void 0,
+							"aria-sort": direction,
+							"data-sort": sortable ? direction ?? "none" : void 0,
+							className: cn("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"),
+							children: sortable ? /* @__PURE__ */ jsxs("button", {
+								type: "button",
+								onClick: () => changeSort(column),
+								className: cn("-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, column.numeric ? "ml-auto flex-row-reverse text-right" : "text-left", direction && "text-fg"),
+								children: [column.header, /* @__PURE__ */ jsx(SortIcon, {
+									"aria-hidden": true,
+									className: cn("shrink-0", byDensity(density, "size-3", "size-2.5"), !direction && "text-fg-subtle")
+								})]
+							}) : column.header
+						}, column.key);
+					})
 				}) }),
-				/* @__PURE__ */ jsx("tbody", { children: rows.map((row, index) => /* @__PURE__ */ jsx("tr", {
-					"data-state": isRowActive?.(row, index) ? "active" : void 0,
-					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 : void 0,
-					"aria-current": isRowActive?.(row, index) ? true : void 0,
-					onClick: onRowClick ? (event) => onRowClick(row, index, event) : void 0,
-					onKeyDown: onRowClick ? (event) => {
-						if (event.key === "Enter" || event.key === " ") {
-							event.preventDefault();
-							onRowClick(row, index, event);
-						}
-					} : void 0,
-					onPointerEnter: onRowHover ? () => onRowHover(row, index) : void 0,
-					onPointerLeave: onRowHover ? () => onRowHover(null, null) : void 0,
-					children: columns.map((column) => /* @__PURE__ */ jsx("td", {
-						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"),
-						children: column.cell(row)
-					}, column.key))
-				}, rowKey(row, index))) })
+				/* @__PURE__ */ jsx("tbody", { children: order.map((index) => {
+					const row = rows[index];
+					const active = isRowActive?.(row, index) ?? false;
+					return /* @__PURE__ */ jsx("tr", {
+						"data-state": active ? "active" : void 0,
+						className: cn("border-b border-line/60 last:border-0", onRowClick && "cursor-pointer hover:bg-raised", active && "bg-signal/10"),
+						tabIndex: onRowClick ? 0 : void 0,
+						"aria-current": active ? true : void 0,
+						onClick: onRowClick ? (event) => onRowClick(row, index, event) : void 0,
+						onKeyDown: onRowClick ? (event) => {
+							if (event.key === "Enter" || event.key === " ") {
+								event.preventDefault();
+								onRowClick(row, index, event);
+							}
+						} : void 0,
+						onPointerEnter: onRowHover ? () => onRowHover(row, index) : void 0,
+						onPointerLeave: onRowHover ? () => onRowHover(null, null) : void 0,
+						children: columns.map((column) => /* @__PURE__ */ jsx("td", {
+							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"),
+							children: column.cell(row)
+						}, column.key))
+					}, rowKey(row, index));
+				}) })
 			]
 		})
 	});
@@ -2199,6 +2325,6 @@ function Tabs({ items, active, onSelect, label, idPrefix, className }) {
 	});
 }
 //#endregion
-export { Badge, Button, ButtonLink, Callout, Checkbox, ConfirmDialog, CountRun, DEFAULT_THEME_STORAGE_KEY, DensityProvider, Dialog, DialogClose, Disclosure, DropdownMenu, Empty, ErrorBox, Field, InfoHint, Input, Kbd, Listbox, MenuCheckboxItem, MenuItem, MenuLabel, MenuSeparator, NumberInput, PageHeader, Panel, Popover, PopoverClose, PoseInput, ProgressBar, ReadoutStrip, Section, SegmentedControl, Select, Skeleton, SkeletonRows, Slider, StatusDot, Switch, Table, Tabs, Textarea, ThemeToggle, Toaster, ToggleChip, Tooltip, TooltipProvider, VectorInput, buttonClasses, byDensity, cn, controlClasses, createToastStore, defaultToastStore, focusRing, focusRingInset, formatNumber, initTheme, inputClasses, parseNumber, readThemeChoice, resolveTheme, setThemeChoice, toast, toneColor, useControlHeight, useDensity };
+export { Badge, Button, ButtonLink, Callout, Checkbox, ConfirmDialog, CountRun, DEFAULT_THEME_STORAGE_KEY, DensityProvider, Dialog, DialogClose, Disclosure, DropdownMenu, Empty, ErrorBox, Field, InfoHint, Input, Kbd, Listbox, MenuCheckboxItem, MenuItem, MenuLabel, MenuSeparator, NumberInput, PageHeader, Panel, Popover, PopoverClose, PoseInput, ProgressBar, ReadoutStrip, Section, SegmentedControl, Select, Skeleton, SkeletonRows, Slider, StatusDot, Switch, Table, Tabs, Textarea, ThemeToggle, Toaster, ToggleChip, Tooltip, TooltipProvider, VectorInput, buttonClasses, byDensity, cn, controlClasses, createToastStore, defaultToastStore, focusRing, focusRingInset, formatNumber, initTheme, inputClasses, parseNumber, readThemeChoice, resolveTheme, setThemeChoice, sortRows, toast, toneColor, useControlHeight, useDensity };
 
 //# sourceMappingURL=index.js.map