@vitavision/ui 0.11.0 → 0.13.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
@@ -125,11 +125,14 @@ keep independent preferences.
 **Primitives** — `Badge`, `CountRun`, `StatusDot` · `Button`, `ButtonLink` (a navigation styled as a button — never nest a `Button` in a link), `buttonClasses` · `Dialog`, `ConfirmDialog`,
 `DialogClose` · `Disclosure` · `DropdownMenu`, `MenuItem`, `MenuCheckboxItem`, `MenuLabel`,
 `MenuSeparator` (a non-modal command and toggle menu) · `Callout`, `Empty`, `ErrorBox`,
-`ProgressBar`, `Skeleton`, `SkeletonRows` · `Field` · `Input`, `NumberInput` (with an optional
-`unit` written in the field; number-valued with `onValueChange`), `Textarea` · `VectorInput`,
+`Skeleton`, `SkeletonRows` · `Progress` (a count out of a total, or indeterminate; `ProgressBar` is
+deprecated) · `Field` · `Input`, `NumberInput` (with an optional
+`unit` written in the field; number-valued with `onValueChange`), `Textarea` (optionally growing
+with its content between `minRows` and `maxRows`) · `HighlightedText`, `findSpans` (a string
+with its placeholders, tags and terms marked, never parsed as HTML) · `VectorInput`,
 `PoseInput` · `Kbd` · `Listbox` (single choice among options that render their own content) ·
 `PageHeader`, `Panel`, `ReadoutStrip`, `Section` · `Popover`, `PopoverClose` ·
-`SegmentedControl` · `Select` · `Slider` · `Table` ·
+`SegmentedControl` · `Select` · `Slider` · `Table` (with `windowed` for thousands of rows) ·
 `Checkbox`, `Switch` · `ToggleChip` · `Toaster`, `toast()` (notifications from anywhere; mount one `<Toaster />` near the root) ·
 `InfoHint`, `Tooltip`, `TooltipProvider` ·
 `ThemeToggle` · plus `cn`, `focusRing`, `focusRingInset`, and `formatNumber` / `parseNumber`

package/dist/index.d.ts

@@ -464,6 +464,9 @@ export declare function SkeletonRows({ rows, className }: {
  * A `role="progressbar"` with `aria-valuenow` in percent. Its accessible name is
  * `aria-label` if given, else `label`, else "Progress" — pass one that names the job when
  * a screen shows more than one bar.
+ *
+ * @deprecated Use `Progress`: a value out of a `max` with a "412 of 2,556" value text, an
+ * indeterminate state, and a track that follows the density.
  */
 export declare function ProgressBar({ fraction, label, "aria-label": ariaLabel, className }: {
   /** Done, from 0 to 1. Clamped. */
@@ -510,6 +513,75 @@ export declare function Field({ label, description, error, required, annotation,
   children: ReactNode;
 }): import("react").JSX.Element;
 //#endregion
+//#region src/components/ui/highlightSpans.d.ts
+/** What a highlighted span is. Each kind has its own shape on screen, not only its own colour. */
+type HighlightKind = "placeholder" | "tag" | "protected-term" | "mismatch";
+/** A highlighted range of the text: `[start, end)` in UTF-16 code units. */
+interface HighlightSpan {
+  /** The offset of the span's first code unit. */
+  start: number;
+  /** The offset just past the span's last code unit. */
+  end: number;
+  /** What the span is; it decides the span's shape and its default label. */
+  kind: HighlightKind;
+  /**
+   * What a screen reader hears after the span, instead of the kind's default label: say
+   * *why* it is marked ("missing from the translation").
+   */
+  label?: string | undefined;
+}
+/** A pattern whose matches become spans of one kind. */
+interface HighlightRule {
+  /** Matched against the whole text, every match (the `g` flag is added if missing). */
+  pattern: RegExp;
+  /** The kind every match gets. */
+  kind: HighlightKind;
+  /** The spans' `label`, if they need one. */
+  label?: string | undefined;
+}
+/**
+ * Spans for every match of every rule: `%1`, `<b>`, a glossary term. Empty matches are
+ * skipped. The result is sorted by start, then longest first.
+ *
+ * @param text - The string to search.
+ * @param rules - Each pattern and the kind its matches get.
+ * @returns The spans, ready for `HighlightedText`.
+ *
+ * @example
+ * ```ts
+ * findSpans("Open %1 in <b>ParamsManager</b>", [
+ *   { pattern: /%\d+/, kind: "placeholder" },
+ *   { pattern: /<\/?[a-z][^>]*>/i, kind: "tag" },
+ *   { pattern: /\bParamsManager\b/, kind: "protected-term" },
+ * ]);
+ * ```
+ */
+export declare function findSpans(text: string, rules: readonly HighlightRule[]): HighlightSpan[];
+//#endregion
+//#region src/components/ui/HighlightedText.d.ts
+/** Props of `HighlightedText`: the text, its spans, and every `<span>` prop but `children`. */
+type HighlightedTextProps = Omit<ComponentProps<"span">, "children"> & {
+  /** The string. Shown as text, whitespace and line breaks kept; markup in it is not interpreted. */
+  text: string;
+  /** The ranges to mark, in UTF-16 offsets, in any order; overlaps are allowed. `findSpans` builds them from patterns. */
+  spans?: readonly HighlightSpan[] | undefined;
+  /**
+   * What a screen reader hears after a span of each kind: "placeholder", "markup",
+   * "protected term" and "mismatch" by default. `null` silences a kind. A span's own `label` wins.
+   */
+  labels?: Partial<Record<HighlightKind, string | null>> | undefined;
+};
+/**
+ * A string with highlighted spans: placeholders (`%1`, `{count}`), markup tags (`<b>`),
+ * protected terms (`ParamsManager`) and mismatches, each drawn in its own shape. The caller
+ * supplies the spans, or finds them with `findSpans`.
+ *
+ * The text is rendered as text, never as HTML. Each span is a `<mark>` with `data-kind` (the
+ * kinds covering it, space-separated), followed by its label for screen readers ("%1,
+ * placeholder"), which a copy of the text leaves out.
+ */
+export declare function HighlightedText({ text, spans, labels, className, ...rest }: HighlightedTextProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/ui/Input.d.ts
 /**
  * The shared look of a text-like control — border, palette, placeholder, hover, disabled and
@@ -598,11 +670,6 @@ type NumberInputProps = Omit<ComponentProps<"input">, "min" | "max" | "value"> &
  * is the native text-valued input.
  */
 export declare function NumberInput({ onValueChange, onClear, precision, ...props }: NumberInputProps): import("react").JSX.Element;
-/**
- * Multi-line text — set in mono, for JSON and lists. Takes every `<textarea>` prop, `ref`
- * included.
- */
-export declare function Textarea({ className, "aria-describedby": describedBy, ...rest }: ComponentProps<"textarea">): import("react").JSX.Element;
 //#endregion
 //#region src/components/ui/Kbd.d.ts
 /**
@@ -776,6 +843,39 @@ export declare function ReadoutStrip({ items, className }: {
   className?: string | undefined;
 }): import("react").JSX.Element | null;
 //#endregion
+//#region src/components/ui/Progress.d.ts
+/**
+ * The accessible value text of a progress: `"412 of 2,556"`, or `null` while indeterminate.
+ *
+ * @param value - Done so far; `null` or `undefined` for an unknown amount.
+ * @param max - The whole. Defaults to 100.
+ * @returns The text, with the value clamped to `[0, max]`.
+ */
+export declare function progressText(value: number | null | undefined, max?: number): string | null;
+/** Props of `Progress`: a value out of a `max`, or none for an unknown amount, plus the `<div>` props. */
+type ProgressProps = Omit<ComponentProps<"div">, "children" | "role"> & {
+  /** Done so far, from 0 to `max`; clamped. `null` or left out: indeterminate, the amount unknown. */
+  value?: number | null | undefined;
+  /** The whole. Defaults to 100; a value ≤ 0 counts as 100. */
+  max?: number | undefined;
+  /**
+   * What a screen reader says for the value. Defaults to `"412 of 2,556"`; give your own when
+   * the unit matters ("412 of 2,556 strings").
+   */
+  valueText?: string | undefined;
+};
+/**
+ * A progress bar: determinate when it has a `value` (a `max`, 100 by default), indeterminate
+ * without one. Name it with `aria-label` or `aria-labelledby`.
+ *
+ * A `progressbar` with `aria-valuenow`, `aria-valuemax` and `aria-valuetext` ("412 of 2,556",
+ * or your `valueText`); indeterminate, it has none of them, as the ARIA pattern asks.
+ * The track follows the density in force. State is exposed as `data-state`
+ * (`"indeterminate"`, `"loading"` or `"complete"`). With reduced motion the indeterminate bar
+ * holds still.
+ */
+export declare function Progress({ value, max, valueText, className, ...rest }: ProgressProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/ui/Popover.d.ts
 /** Props of `Popover`. */
 interface PopoverProps {
@@ -998,6 +1098,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,20 +1139,75 @@ 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;
 };
+/**
+ * Windowed rendering for a long table: only the rows in view, plus `overscan` on each side,
+ * are in the DOM. The rows scroll under a sticky header drawn on `surface`, the panel colour.
+ */
+interface TableWindowing {
+  /**
+   * Every body row's height in px. Rows are drawn exactly this tall and cells keep to one line
+   * (longer content is cut with an ellipsis), so it must be at least the density's own row
+   * height: 36 px comfortable, 22 px compact.
+   */
+  rowHeight: number;
+  /**
+   * The scroll area's height in px, header included. Leave it out to fill the height of the
+   * container, which must then have one (a flex child with `min-h-0`, a fixed-height panel).
+   */
+  height?: number | undefined;
+  /** Rows rendered beyond each edge of the view, so a fast scroll shows no gap. Defaults to 8. */
+  overscan?: number | undefined;
+}
 /**
  * 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.
+ *
+ * Activatable rows also move focus with the arrow keys, Page Up / Page Down and Home / End.
+ * With `windowed` the table scrolls itself (vertically, under a sticky header), renders only the
+ * rows in view, and uses a fixed layout: give columns a `width` where the content needs it.
  */
-export declare function Table<Row>({ columns, rows, rowKey, empty, caption, className, onRowClick, isRowActive, onRowHover }: {
+export declare function Table<Row>({ columns, rows, rowKey, empty, caption, className, onRowClick, isRowActive, onRowHover, sort: controlledSort, defaultSort, onSortChange, manualSort, windowed }: {
   /** 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,16 +1218,76 @@ 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;
+  /**
+   * Render only the rows in view, for a long table: every row `rowHeight` tall, in a scroll
+   * area of `height` (or the container's height) under a sticky header. Sorting, row
+   * callbacks and keyboard navigation work as without it.
+   */
+  windowed?: TableWindowing | undefined;
 }): import("react").JSX.Element;
 //#endregion
+//#region src/components/ui/Textarea.d.ts
+/**
+ * Props of `Textarea`: every `<textarea>` prop, `ref` included, plus an invalid state, the
+ * mono face, and growing with the content between `minRows` and `maxRows`.
+ */
+type TextareaProps = ComponentProps<"textarea"> & {
+  /** Called with the new text on every edit, alongside the native `onChange`. */
+  onValueChange?: ((value: string) => void) | undefined;
+  /**
+   * Marks the value as wrong: `aria-invalid`, `data-invalid` and a border in the defect
+   * colour. Inside a `Field` with an `error` it is on without this. Say what is wrong in
+   * text too (the field's `error`): the border alone is a colour.
+   */
+  invalid?: boolean | undefined;
+  /** Sets the text in IBM Plex Mono, for code, JSON, lists, or strings whose characters all matter. */
+  mono?: boolean | undefined;
+  /**
+   * Grows with the content from this many lines. Set it or `maxRows` to turn growing on;
+   * `rows` is then ignored.
+   */
+  minRows?: number | undefined;
+  /** Stops growing at this many lines and scrolls beyond them. Set it or `minRows` to turn growing on. */
+  maxRows?: number | undefined;
+};
+/**
+ * Multi-line text, on the shared control palette. Takes every `<textarea>` prop, `ref`
+ * included; inside a `Field` it is described by the field's description and error, and
+ * shown invalid while the field has an error.
+ *
+ * With `minRows` or `maxRows` it grows with its content between the two (and scrolls past
+ * `maxRows`); without them it is `rows` tall and the reader can resize it. State is exposed
+ * as `data-invalid`.
+ */
+export declare function Textarea({ className, "aria-describedby": describedBy, invalid, mono, minRows, maxRows, rows, value, onChange, onValueChange, ref, ...rest }: TextareaProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/ui/Toggle.d.ts
 /**
  * A setting: changes how the thing behaves from now on, and reads as one ("show the mask").
@@ -1343,5 +1586,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, HighlightKind, HighlightRule, HighlightSpan, HighlightedTextProps, ListboxOption, ListboxOptionState, ListboxProps, MeasureTone, MenuCheckboxItemProps, MenuItemProps, NumberInputProps, PopoverProps, PoseInputProps, PoseValue, ProgressProps, Quaternion, ReadoutItem, RotationView, SelectOption, SortDirection, TabItem, TableSort, TableWindowing, TextareaProps, ThemeChoice, ToastOptions, ToastRecord, ToastStore, ToastTone, ToasterProps, Tone, Vec3, VectorInputProps };
 //# sourceMappingURL=index.d.ts.map