@vitavision/ui 0.12.0 → 0.14.0

package/README.md

@@ -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) · `Breakdown`, `breakdownText` (counts by verdict as one thin stacked bar) · `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, and `selectionFollowsFocus` for keyboard selection) ·
 `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

@@ -154,6 +154,69 @@ export declare function CountRun({ counts, className }: {
   className?: string | undefined;
 }): import("react").JSX.Element;
 //#endregion
+//#region src/components/ui/Breakdown.d.ts
+/**
+ * The colour of a `Breakdown` segment: a verdict (`normal`, `warn`, `defect`) for things the app
+ * has judged, or `neutral` for a category that is no verdict (skipped, not applicable).
+ */
+type BreakdownTone = "normal" | "warn" | "defect" | "neutral";
+/** One category of a `Breakdown`: how many, in which colour, and what a reader calls them. */
+interface BreakdownSegment {
+  /** How many. Negative and non-finite values count as 0, and a segment of 0 is left out. */
+  value: number;
+  /** The colour, by meaning. */
+  tone: BreakdownTone;
+  /** What the count is, as it reads after the number: `"done"` gives "412 done". Unique among the segments. */
+  label: string;
+}
+/** Options of `breakdownText`, the same as the `Breakdown` props of the same names. */
+interface BreakdownTextOptions {
+  /** The whole. Defaults to the sum of the segments; a total below the sum counts as the sum. */
+  total?: number | undefined;
+  /** What the rest of the total is, as it reads after the number: `"to do"` gives "131 to do". */
+  remainderLabel?: string | undefined;
+}
+/**
+ * The counts of a breakdown in words: `"412 done, 20 to check, 3 problems, 131 to do of 566"`.
+ *
+ * It is the default accessible name of `Breakdown`, and the text for a tooltip or a label printed
+ * beside the bar. Segments of 0 are left out; the rest of the total is named only with a
+ * `remainderLabel`. With nothing to count it reads `"0 of 566"`.
+ *
+ * @param segments - The categories, in order.
+ * @param options - The `total` and the `remainderLabel`.
+ * @returns The text.
+ */
+export declare function breakdownText(segments: readonly BreakdownSegment[], options?: BreakdownTextOptions): string;
+/** Props of `Breakdown`: the segments and their total, plus the `<div>` props. */
+type BreakdownProps = Omit<ComponentProps<"div">, "children" | "role"> & {
+  /** The categories, drawn left to right in this order, each as wide as its share of the total. */
+  segments: readonly BreakdownSegment[];
+  /**
+   * The whole. Defaults to the sum of the segments; the rest is drawn as empty track. A total
+   * below the sum counts as the sum.
+   */
+  total?: number | undefined;
+  /** What the empty track counts, for the accessible name: `"to do"` gives "131 to do". */
+  remainderLabel?: string | undefined;
+};
+/**
+ * A thin bar of counts by category: 412 done, 20 to check and 3 problems out of 566, with the
+ * rest as empty track. Segments are drawn in the order given, each as wide as its share of the
+ * total (a non-zero count is never narrower than 2 px); segments of 0 are left out.
+ *
+ * Its colours are verdicts, so use it only for things the app has judged — never for a share of
+ * a continuous quantity or for series side by side (use `Progress` or a chart).
+ *
+ * A `role="img"` whose name lists every non-zero count, as `breakdownText` writes it: "412 done,
+ * 20 to check, 3 problems, 131 to do of 566". `aria-label` or `aria-labelledby` replaces it. The track
+ * matches `Progress` and follows the density in force. State is exposed as `data-state`
+ * (`"empty"` with nothing counted, `"partial"`, or `"complete"` when the segments fill the
+ * total), and each segment's tone as its `data-tone`. Width changes ease over 300 ms, and not at
+ * all with reduced motion.
+ */
+export declare function Breakdown({ segments, total, remainderLabel, className, "aria-label": ariaLabel, ...rest }: BreakdownProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/ui/Button.d.ts
 /**
  * A button's look, by what the action is: `primary` for the one action a screen is for,
@@ -464,6 +527,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 +576,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 +733,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 +906,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 {
@@ -1064,6 +1227,25 @@ type Column<Row> = {
    */
   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.
  *
@@ -1078,8 +1260,13 @@ type Column<Row> = {
  * `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 `selectionFollowsFocus` each of those moves also activates the row it lands on.
+ * 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, sort: controlledSort, defaultSort, onSortChange, manualSort }: {
+export declare function Table<Row>({ columns, rows, rowKey, empty, caption, className, onRowClick, isRowActive, onRowHover, sort: controlledSort, defaultSort, onSortChange, manualSort, windowed, selectionFollowsFocus }: {
   /** The columns, in order. */
   columns: Column<Row>[];
   /** The rows, in their own order: the order shown while the table is not sorted. */
@@ -1122,8 +1309,58 @@ export declare function Table<Row>({ columns, rows, rowKey, empty, caption, clas
    * 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;
+  /**
+   * Activate a row as soon as the keyboard moves to it: each arrow key, Page Up / Page Down,
+   * Home or End that lands on another row also calls `onRowClick` for that row, with the key
+   * press as the event — selection follows focus, as in a list where the selected item shows
+   * its detail beside the list. Clicks, Enter and Space work as without it. Leave it off when
+   * activating a row is costly or navigates away: then a reader can move through the rows and
+   * choose one. Needs `onRowClick`.
+   */
+  selectionFollowsFocus?: boolean | 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").
@@ -1422,5 +1659,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, SortDirection, TabItem, TableSort, ThemeChoice, ToastOptions, ToastRecord, ToastStore, ToastTone, ToasterProps, Tone, Vec3, VectorInputProps };
+export type { BackLink, BreakdownProps, BreakdownSegment, BreakdownTextOptions, BreakdownTone, 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