@vitavision/ui 0.12.0 → 0.13.0

package/src/components/ui/highlightSpans.ts

@@ -0,0 +1,110 @@
+/*
+ * The model behind `HighlightedText`: spans over a string, cut into the runs that render
+ * alike, and spans found by regular expressions. Pure, so it is tested without a DOM.
+ *
+ * Offsets are UTF-16 code-unit indices, as `String.prototype.slice` and `RegExp` use them.
+ */
+
+/** What a highlighted span is. Each kind has its own shape on screen, not only its own colour. */
+export type HighlightKind = "placeholder" | "tag" | "protected-term" | "mismatch";
+
+/** A highlighted range of the text: `[start, end)` in UTF-16 code units. */
+export 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 run of the text covered by one set of spans; two spans side by side are two runs. */
+export interface TextSegment {
+  /** The run's characters. */
+  text: string;
+  /** Where the run starts in the whole text. */
+  start: number;
+  /** Where it ends. */
+  end: number;
+  /** The spans covering the run, in their order in the input. Empty for plain text. */
+  spans: HighlightSpan[];
+}
+
+/** The kinds in the order their styles stack: a later one wins where two would clash. */
+export const HIGHLIGHT_KINDS: readonly HighlightKind[] = ["tag", "protected-term", "placeholder", "mismatch"];
+
+/**
+ * Cuts `text` into runs that are each covered by one fixed set of spans. Spans are clamped
+ * to the text; empty, inverted and non-finite ones are dropped. Overlapping spans are kept:
+ * the overlap is a run covered by both.
+ *
+ * @param text - The string, shown as text.
+ * @param spans - The highlights, in any order.
+ * @returns The runs, in order, together covering the whole text.
+ */
+export function segmentText(text: string, spans: readonly HighlightSpan[]): TextSegment[] {
+  const length = text.length;
+  const clamp = (offset: number) => Math.floor(Math.max(0, Math.min(length, offset)));
+  const valid = spans
+    .map((span) => ({ span, start: clamp(span.start), end: clamp(span.end) }))
+    .filter(({ start, end }) => Number.isFinite(start) && Number.isFinite(end) && end > start);
+  const cuts = new Set<number>([0, length]);
+  for (const { start, end } of valid) {
+    cuts.add(start);
+    cuts.add(end);
+  }
+  const points = [...cuts].sort((a, b) => a - b);
+  const segments: TextSegment[] = [];
+  for (let i = 0; i + 1 < points.length; i++) {
+    const start = points[i]!;
+    const end = points[i + 1]!;
+    const covering = valid.filter((v) => v.start <= start && v.end >= end).map((v) => v.span);
+    segments.push({ text: text.slice(start, end), start, end, spans: covering });
+  }
+  return segments;
+}
+
+/** A pattern whose matches become spans of one kind. */
+export 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 function findSpans(text: string, rules: readonly HighlightRule[]): HighlightSpan[] {
+  const spans: HighlightSpan[] = [];
+  for (const rule of rules) {
+    const flags = rule.pattern.flags.includes("g") ? rule.pattern.flags : `${rule.pattern.flags}g`;
+    for (const match of text.matchAll(new RegExp(rule.pattern.source, flags))) {
+      if (match[0] === "") continue;
+      const start = match.index;
+      spans.push({ start, end: start + match[0].length, kind: rule.kind, ...(rule.label === undefined ? {} : { label: rule.label }) });
+    }
+  }
+  return spans.sort((a, b) => a.start - b.start || b.end - a.end);
+}

package/src/components/ui/index.ts

@@ -22,55 +22,24 @@ export {
   type MenuCheckboxItemProps,
   type MenuItemProps,
 } from "./DropdownMenu";
-export {
-  Callout,
-  type CalloutTone,
-  Empty,
-  ErrorBox,
-  ProgressBar,
-  Skeleton,
-  SkeletonRows,
-} from "./Feedback";
+export { Callout, type CalloutTone, Empty, ErrorBox, ProgressBar, Skeleton, SkeletonRows } from "./Feedback";
 export { Field } from "./Field";
-export {
-  Input,
-  NumberInput,
-  Textarea,
-  controlClasses,
-  inputClasses,
-  useControlHeight,
-  type NumberInputProps,
-} from "./Input";
+export { HighlightedText, type HighlightedTextProps } from "./HighlightedText";
+export { findSpans, type HighlightKind, type HighlightRule, type HighlightSpan } from "./highlightSpans";
+export { Input, NumberInput, controlClasses, inputClasses, useControlHeight, type NumberInputProps } from "./Input";
 export { Kbd } from "./Kbd";
-export {
-  Listbox,
-  type ListboxOption,
-  type ListboxOptionState,
-  type ListboxProps,
-} from "./Listbox";
+export { Listbox, type ListboxOption, type ListboxOptionState, type ListboxProps } from "./Listbox";
 export { formatNumber, parseNumber } from "./numberText";
-export {
-  PageHeader,
-  type BackLink,
-  Panel,
-  ReadoutStrip,
-  Section,
-  type ReadoutItem,
-} from "./Panel";
+export { PageHeader, type BackLink, Panel, ReadoutStrip, Section, type ReadoutItem } from "./Panel";
+export { Progress, progressText, type ProgressProps } from "./Progress";
 export { Popover, PopoverClose, type PopoverProps } from "./Popover";
-export {
-  PoseInput,
-  type PoseInputProps,
-  type PoseValue,
-  type Quaternion,
-  type RotationView,
-  type Vec3,
-} from "./PoseInput";
+export { PoseInput, type PoseInputProps, type PoseValue, type Quaternion, type RotationView, type Vec3 } from "./PoseInput";
 export { SegmentedControl } from "./SegmentedControl";
 export { Select, type SelectOption } from "./Select";
 export { Slider } from "./Slider";
-export { Table, type Column } from "./Table";
+export { Table, type Column, type TableWindowing } from "./Table";
 export { sortRows, type SortDirection, type TableSort } from "./tableSort";
+export { Textarea, type TextareaProps } from "./Textarea";
 export { Checkbox, Switch } from "./Toggle";
 export { ToggleChip } from "./ToggleChip";
 export { Toaster, type ToasterProps } from "./Toaster";

package/src/components/ui/listboxModel.ts

@@ -21,12 +21,7 @@ export type ListboxKey = "ArrowDown" | "ArrowUp" | "Home" | "End" | "PageDown" |
  * @returns The new active index; `from` when there is nowhere to go; -1 when every option is
  *   disabled.
  */
-export function moveActive(
-  disabled: readonly boolean[],
-  from: number,
-  key: ListboxKey,
-  page = 10,
-): number {
+export function moveActive(disabled: readonly boolean[], from: number, key: ListboxKey, page = 10): number {
   const enabled = disabled.flatMap((off, index) => (off ? [] : [index]));
   if (enabled.length === 0) return -1;
   const first = enabled[0]!;

package/src/components/ui/tableSort.ts

@@ -36,10 +36,7 @@ export function isSortable<Row>(column: Pick<Column<Row>, "sortable" | "sortValu
 }
 
 /** 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 {
+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;
@@ -65,11 +62,7 @@ function compareValues(a: number | string, b: number | string): number {
  * 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[] {
+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);

package/src/components/ui/tableWindow.ts

@@ -0,0 +1,96 @@
+/*
+ * The arithmetic of a windowed table: which rows to render for a scroll position, and where
+ * to scroll to bring a row into view. Pure, so it is tested on its own (`tableWindow.test.ts`,
+ * `tableWindow.property.test.ts`) rather than through layout.
+ *
+ * Every row is `rowHeight` tall. The body starts below a sticky header `headerHeight` tall, and
+ * the scroll container shows `viewportHeight` of the whole (header included).
+ */
+
+/** The rows to render, as a half-open range of positions, and the space around them. */
+export interface RowWindow {
+  /** The first rendered position. */
+  start: number;
+  /** One past the last rendered position. */
+  end: number;
+  /** The height, in px, of the rows before `start`. */
+  before: number;
+  /** The height, in px, of the rows from `end` on. */
+  after: number;
+}
+
+/** What the window depends on. Lengths in px. */
+export interface WindowInput {
+  rowCount: number;
+  rowHeight: number;
+  /** The scroll container's `scrollTop`. */
+  scrollTop: number;
+  /** The scroll container's visible height, header included. */
+  viewportHeight: number;
+  /** The sticky header's height. */
+  headerHeight: number;
+  /** Rows rendered beyond each edge of the visible ones. */
+  overscan: number;
+}
+
+/**
+ * The rows that intersect the visible part of the body, plus `overscan` on each side.
+ * Degenerate input (no rows, a row height ≤ 0, NaN) gives an empty window.
+ */
+export function rowWindow({ rowCount, rowHeight, scrollTop, viewportHeight, headerHeight, overscan }: WindowInput): RowWindow {
+  const count = Number.isFinite(rowCount) ? Math.max(0, Math.floor(rowCount)) : 0;
+  if (count === 0 || !(rowHeight > 0)) return { start: 0, end: 0, before: 0, after: 0 };
+  const extra = Math.max(0, Math.floor(overscan) || 0);
+  // In the body's own coordinates the visible part is [scrollTop, scrollTop + viewport − header]:
+  // the sticky header covers the top of the container.
+  const top = Math.max(0, scrollTop || 0);
+  const bottom = Math.max(top, top + Math.max(0, viewportHeight || 0) - Math.max(0, headerHeight || 0));
+  const first = Math.min(count, Math.floor(top / rowHeight));
+  const last = Math.min(count, Math.max(first + 1, Math.ceil(bottom / rowHeight)));
+  const start = Math.max(0, first - extra);
+  const end = Math.min(count, last + extra);
+  return { start, end, before: start * rowHeight, after: (count - end) * rowHeight };
+}
+
+/**
+ * The `scrollTop` that shows the row at `position` in full below the sticky header, moving
+ * as little as possible: unchanged when it is already in view, else aligned to the nearer
+ * edge. A viewport shorter than one row aligns the row's top.
+ */
+export function scrollTopFor(
+  position: number,
+  { rowHeight, scrollTop, viewportHeight, headerHeight }: Pick<WindowInput, "rowHeight" | "scrollTop" | "viewportHeight" | "headerHeight">,
+): number {
+  const rowTop = position * rowHeight;
+  const visible = viewportHeight - headerHeight;
+  if (rowTop < scrollTop || visible < rowHeight) return rowTop;
+  if (rowTop + rowHeight > scrollTop + visible) return rowTop + rowHeight - visible;
+  return scrollTop;
+}
+
+/**
+ * The position a navigation key moves to from `position`, among `rowCount` rows, `page` rows
+ * to a screen; `null` for a key that does not navigate.
+ */
+export function navigate(key: string, position: number, rowCount: number, page: number): number | null {
+  const last = rowCount - 1;
+  if (last < 0) return null;
+  const step = Math.max(1, Math.floor(page));
+  const clamp = (p: number) => Math.min(last, Math.max(0, p));
+  switch (key) {
+    case "ArrowDown":
+      return clamp(position + 1);
+    case "ArrowUp":
+      return clamp(position - 1);
+    case "PageDown":
+      return clamp(position + step);
+    case "PageUp":
+      return clamp(position - step);
+    case "Home":
+      return 0;
+    case "End":
+      return last;
+    default:
+      return null;
+  }
+}

package/src/index.ts

@@ -7,14 +7,7 @@
  * @packageDocumentation
  */
 
-export {
-  DEFAULT_THEME_STORAGE_KEY,
-  initTheme,
-  readThemeChoice,
-  resolveTheme,
-  setThemeChoice,
-  type ThemeChoice,
-} from "./theme";
+export { DEFAULT_THEME_STORAGE_KEY, initTheme, readThemeChoice, resolveTheme, setThemeChoice, type ThemeChoice } from "./theme";
 
 export { toneColor, type MeasureTone } from "./tone";
 

package/src/styles.css

@@ -58,6 +58,20 @@
   --radius-panel: 0.625rem;
 }
 
+/* `Progress` while the amount is unknown: a third of the track sweeping across it. */
+@theme {
+  --animate-progress-sweep: progress-sweep 1.4s ease-in-out infinite;
+
+  @keyframes progress-sweep {
+    from {
+      transform: translateX(-100%);
+    }
+    to {
+      transform: translateX(300%);
+    }
+  }
+}
+
 /*
  * Light is the default so a document with no class still renders legibly -- a consumer's
  * own no-flash script sets `.dark` before first paint (see `theme.ts` and the README), but

package/src/theme.ts

@@ -36,9 +36,7 @@ export const DEFAULT_THEME_STORAGE_KEY = "vitavision-theme";
 // Every DOM access here is inside a function, and guarded: this module is imported on the
 // server too.
 const query = () =>
-  typeof window !== "undefined" && typeof window.matchMedia === "function"
-    ? window.matchMedia("(prefers-color-scheme: dark)")
-    : null;
+  typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia("(prefers-color-scheme: dark)") : null;
 
 /**
  * The stored preference.
@@ -81,10 +79,7 @@ function paint(choice: ThemeChoice): void {
  * @param choice - The new preference.
  * @param storageKey - The `localStorage` key. Defaults to `DEFAULT_THEME_STORAGE_KEY`.
  */
-export function setThemeChoice(
-  choice: ThemeChoice,
-  storageKey: string = DEFAULT_THEME_STORAGE_KEY,
-): void {
+export function setThemeChoice(choice: ThemeChoice, storageKey: string = DEFAULT_THEME_STORAGE_KEY): void {
   try {
     window.localStorage.setItem(storageKey, choice);
   } catch {