@vitavision/ui 0.6.0

package/src/components/ui/SegmentedControl.tsx

@@ -0,0 +1,112 @@
+/*
+ * A choice among two or three, shown as two or three things.
+ *
+ * The control for a closed set the app can enumerate up front -- `Literal["small", "medium"]`, an axis choice -- shown all at once, no popup, no typing, and no way to enter
+ * a value the backend or algorithm would reject.
+ *
+ * Built on native radios rather than a headless package: a radio group in one `name` gets
+ * roving focus and arrow-key navigation from the platform, which is the entire reason to
+ * reach for a library here.
+ *
+ * **`""` means unset**, and this control keeps that true without showing it. The segment
+ * highlighted is always the *effective* value, so the reader sees what will happen;
+ * choosing the segment that matches the default stores `""` rather than the value, so the
+ * default is still sent by nobody and defined only in one place. See `api/schemaForm.ts`
+ * for why that rule is worth this much care.
+ */
+
+import { useId } from "react";
+
+import { useFieldDescription } from "./Field";
+import { cn } from "./cn";
+
+/**
+ * A choice among two or three, shown as a strip of segments (native radios in one group, so
+ * arrow keys move between them).
+ *
+ * **`""` means unset.** The highlighted segment is always the *effective* value — `value`,
+ * or `defaultValue` while `value` is `""` — and choosing the segment that matches
+ * `defaultValue` reports `""`, so the default stays defined in one place. Each segment
+ * carries `data-state="checked"` or `"unchecked"`; the group carries `data-disabled`.
+ */
+export function SegmentedControl({
+  value,
+  defaultValue,
+  options,
+  onValueChange,
+  disabled = false,
+  "aria-label": ariaLabel,
+  className,
+}: {
+  /** `""` when the field is untouched. */
+  value: string;
+  /** What applies when nothing is sent. Highlighted while `value` is `""`. */
+  defaultValue?: string | undefined;
+  /** The segments, in order. */
+  options: { value: string; label: string }[];
+  /** Called with the chosen value, or `""` when the default's segment is chosen. */
+  onValueChange: (value: string) => void;
+  /** Blocks every segment. */
+  disabled?: boolean | undefined;
+  /** Names the radio group. */
+  "aria-label"?: string | undefined;
+  /** Merged with the strip's own classes through `cn`. */
+  className?: string | undefined;
+}) {
+  const nameId = useId();
+  const described = useFieldDescription();
+  const effective = value === "" ? defaultValue : value;
+
+  return (
+    <div
+      role="radiogroup"
+      aria-label={ariaLabel}
+      aria-describedby={described["aria-describedby"]}
+      data-disabled={disabled ? "" : undefined}
+      className={cn(
+        // `shrink-0` because this is a control, not filler: in a crowded toolbar a flex item at
+        // its default `1 1 auto` gives up width first, and the segment labels are what pay for
+        // it. Let the row scroll instead of squeezing the choice.
+        "inline-flex w-fit max-w-full shrink-0 items-center gap-0.5 rounded-control border border-line-strong bg-raised p-0.5",
+        disabled && "opacity-50",
+        className,
+      )}
+    >
+      {options.map((option) => {
+        const checked = option.value === effective;
+        return (
+          <label
+            key={option.value}
+            data-state={checked ? "checked" : "unchecked"}
+            className={cn(
+              // `whitespace-nowrap` or a two-word label's min-content width is its longest
+              // *word*, and "Side by side" is free to stack onto three lines inside a
+              // fixed-height strip that then clips it.
+              "relative cursor-pointer whitespace-nowrap rounded-[0.3rem] px-2.5 py-1 text-xs font-medium transition-colors",
+              "has-focus-visible:outline-2 has-focus-visible:outline-offset-1 has-focus-visible:outline-signal",
+              checked
+                ? "bg-surface text-fg shadow-sm"
+                : "text-fg-muted hover:text-fg",
+              disabled && "cursor-not-allowed",
+            )}
+          >
+            <input
+              type="radio"
+              name={nameId}
+              value={option.value}
+              checked={checked}
+              disabled={disabled}
+              onChange={() =>
+                // Selecting the default returns the field to unset: same effective value,
+                // nothing sent, and the default keeps living in exactly one place.
+                onValueChange(option.value === defaultValue ? "" : option.value)
+              }
+              className="absolute inset-0 cursor-pointer opacity-0"
+            />
+            {option.label}
+          </label>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/ui/Select.tsx

@@ -0,0 +1,168 @@
+/*
+ * A picker with a list you can actually see.
+ *
+ * A native `<select>` cannot style its option list on macOS, so the popup arrives in the OS
+ * palette in the middle of an otherwise deliberate instrument panel, and it cannot render a
+ * two-line option or a disabled one with a reason.
+ *
+ * The one contract worth reading before changing this: **`""` means unset.** Radix reserves
+ * the empty string internally -- an `Item` may not carry it -- so an explicit "use the
+ * default" entry travels under a sentinel and is mapped back at the boundary. Callers only
+ * ever see `""`.
+ */
+
+import * as RadixSelect from "@radix-ui/react-select";
+import { Check, ChevronDown } from "lucide-react";
+import { useState } from "react";
+
+import { useFieldDescription } from "./Field";
+import { cn, focusRingInset } from "./cn";
+
+const UNSET_SENTINEL = "__unset__";
+
+/** One entry of a `Select`'s list. */
+export type SelectOption = {
+  /** What `onValueChange` reports. Must not be `""`, which means unset. */
+  value: string;
+  /** What the list and the trigger show. */
+  label: string;
+  /** Shown quietly after the label -- a strategy, a count, a reason it is unavailable. */
+  note?: string;
+  /** Shown but not choosable; say why in `note`. */
+  disabled?: boolean;
+};
+
+/**
+ * A picker whose option list is styled with the app, with room for a quiet note per option.
+ *
+ * Controlled, and **`""` means unset**: the trigger then shows `placeholder`, and the
+ * `unsetLabel` entry (when given) reports `""`. The trigger carries Radix's `data-state`
+ * (`open`/`closed`), `data-placeholder` while unset and `data-disabled`; inside a `Field` it
+ * is described by the field's description and error.
+ */
+export function Select({
+  value,
+  onValueChange,
+  options,
+  placeholder = "Choose…",
+  unsetLabel,
+  disabled = false,
+  "aria-label": ariaLabel,
+  "aria-describedby": ownDescribedBy,
+  className,
+}: {
+  /** The chosen option's value, or `""` for unset. */
+  value: string;
+  /** Called with the chosen value, or `""` for the unset entry. */
+  onValueChange: (value: string) => void;
+  /** The list, in order. */
+  options: SelectOption[];
+  /** Shown on the trigger while the value is unset. Defaults to "Choose…". */
+  placeholder?: string | undefined;
+  /** When given, adds a leading entry that returns the field to unset. */
+  unsetLabel?: string | undefined;
+  /** Blocks the trigger. */
+  disabled?: boolean | undefined;
+  /** Names the trigger, where no `<label>` does. */
+  "aria-label"?: string | undefined;
+  /** Ids of elements describing the trigger, merged with a surrounding `Field`'s. */
+  "aria-describedby"?: string | undefined;
+  /** Merged with the trigger's own classes through `cn`. */
+  className?: string | undefined;
+}) {
+  const [open, setOpen] = useState(false);
+  const described = useFieldDescription(ownDescribedBy);
+
+  return (
+    <RadixSelect.Root
+      // Controlled for its whole lifetime: Radix treats `value=""` as "no selection" and shows
+      // the placeholder, which is exactly this component's unset.
+      value={value}
+      onValueChange={(next) => onValueChange(next === UNSET_SENTINEL ? "" : next)}
+      open={open}
+      onOpenChange={setOpen}
+      disabled={disabled}
+    >
+      <RadixSelect.Trigger
+        aria-label={ariaLabel}
+        {...described}
+        // While the list is open Radix hides everything outside it from assistive technology
+        // (`aria-hidden`), this trigger included; a hidden element must not stay in the tab
+        // order. Focus returns to it on close all the same.
+        tabIndex={open ? -1 : undefined}
+        className={cn(
+          "flex h-8 w-full items-center justify-between gap-2 rounded-control border border-line-strong bg-raised px-2.5 text-sm text-fg",
+          "transition-colors hover:border-fg-subtle",
+          "disabled:cursor-not-allowed disabled:opacity-50",
+          "data-[placeholder]:text-fg-subtle",
+          focusRingInset,
+          className,
+        )}
+      >
+        <RadixSelect.Value placeholder={placeholder} />
+        <RadixSelect.Icon className="shrink-0 text-fg-subtle">
+          <ChevronDown className="size-3.5" />
+        </RadixSelect.Icon>
+      </RadixSelect.Trigger>
+
+      <RadixSelect.Portal>
+        <RadixSelect.Content
+          position="popper"
+          sideOffset={4}
+          className={cn(
+            "z-50 max-h-72 min-w-(--radix-select-trigger-width) overflow-hidden",
+            "rounded-panel border border-line bg-overlay shadow-lg shadow-black/25",
+          )}
+        >
+          <RadixSelect.Viewport className="p-1">
+            {unsetLabel !== undefined && (
+              <SelectItem value={UNSET_SENTINEL} label={unsetLabel} muted />
+            )}
+            {options.map((option) => (
+              <SelectItem
+                key={option.value}
+                value={option.value}
+                label={option.label}
+                note={option.note}
+                disabled={option.disabled}
+              />
+            ))}
+          </RadixSelect.Viewport>
+        </RadixSelect.Content>
+      </RadixSelect.Portal>
+    </RadixSelect.Root>
+  );
+}
+
+function SelectItem({
+  value,
+  label,
+  note,
+  disabled,
+  muted = false,
+}: {
+  value: string;
+  label: string;
+  note?: string | undefined;
+  disabled?: boolean | undefined;
+  muted?: boolean;
+}) {
+  return (
+    <RadixSelect.Item
+      value={value}
+      disabled={disabled ?? false}
+      className={cn(
+        "relative flex cursor-default items-center gap-2 rounded-control py-1.5 pr-2 pl-7 text-sm outline-none select-none",
+        "data-highlighted:bg-raised data-highlighted:text-fg",
+        "data-disabled:pointer-events-none data-disabled:opacity-45",
+        muted ? "text-fg-muted" : "text-fg",
+      )}
+    >
+      <RadixSelect.ItemIndicator className="absolute left-2 text-signal">
+        <Check className="size-3.5" />
+      </RadixSelect.ItemIndicator>
+      <RadixSelect.ItemText>{label}</RadixSelect.ItemText>
+      {note && <span className="ml-auto font-mono text-xs text-fg-subtle">{note}</span>}
+    </RadixSelect.Item>
+  );
+}

package/src/components/ui/Slider.tsx

@@ -0,0 +1,96 @@
+/*
+ * A continuous value, with its number always on screen.
+ *
+ * A slider that drives what you are looking at -- a results threshold, an overlay opacity,
+ * a caliper search range -- is a measurement instrument: the number matters as much as the
+ * position, so it is rendered beside the track rather than left to a separate line of prose.
+ */
+
+import * as RadixSlider from "@radix-ui/react-slider";
+import type { ReactNode } from "react";
+
+import { useFieldDescription } from "./Field";
+import { cn, focusRing } from "./cn";
+
+/**
+ * A continuous value, with its number rendered beside the track.
+ *
+ * Controlled. The name (`aria-label`) and a surrounding `Field`'s description go on the
+ * thumb — the element with `role="slider"` that a keyboard and a screen reader operate.
+ * Radix exposes `data-disabled` and `data-orientation` on the parts.
+ */
+export function Slider({
+  value,
+  onValueChange,
+  onValueCommit,
+  min = 0,
+  max = 1,
+  step = 0.01,
+  readout,
+  disabled = false,
+  "aria-label": ariaLabel,
+  "aria-describedby": ownDescribedBy,
+  className,
+}: {
+  /** The current value. */
+  value: number;
+  /** Called on every move. */
+  onValueChange: (value: number) => void;
+  /** Called once when a drag or a key press ends — for updates too expensive to run per move. */
+  onValueCommit?: ((value: number) => void) | undefined;
+  /** Defaults to 0. */
+  min?: number | undefined;
+  /** Defaults to 1. */
+  max?: number | undefined;
+  /** Defaults to 0.01. */
+  step?: number | undefined;
+  /** Rendered to the right of the track. Give it a fixed-width mono span for stability. */
+  readout?: ReactNode;
+  /** Blocks the thumb and dims the track. */
+  disabled?: boolean | undefined;
+  /** Names the slider (set on the thumb). */
+  "aria-label"?: string | undefined;
+  /** Ids of elements describing the slider, merged with a surrounding `Field`'s. */
+  "aria-describedby"?: string | undefined;
+  /** Merged with the row's own classes through `cn`. */
+  className?: string | undefined;
+}) {
+  const described = useFieldDescription(ownDescribedBy);
+
+  return (
+    // Grows by default: a slider that does not fill the space it is given collapses to a
+    // few pixels of track, which is unusable and reads as a rendering fault.
+    <div className={cn("flex min-w-0 flex-1 items-center gap-3", className)}>
+      <RadixSlider.Root
+        value={[value]}
+        onValueChange={([next]) => next !== undefined && onValueChange(next)}
+        onValueCommit={([next]) => next !== undefined && onValueCommit?.(next)}
+        min={min}
+        max={max}
+        step={step}
+        disabled={disabled}
+        className={cn(
+          "relative flex h-5 min-w-0 flex-1 touch-none items-center select-none",
+          "data-disabled:opacity-50",
+        )}
+      >
+        <RadixSlider.Track className="relative h-1 grow overflow-hidden rounded-full bg-line">
+          <RadixSlider.Range className="absolute h-full bg-signal" />
+        </RadixSlider.Track>
+        <RadixSlider.Thumb
+          aria-label={ariaLabel}
+          {...described}
+          className={cn(
+            "block size-3.5 rounded-full border-2 border-signal bg-surface transition-shadow",
+            "hover:shadow-[0_0_0_4px] hover:shadow-signal/20",
+            "disabled:cursor-not-allowed",
+            focusRing,
+          )}
+        />
+      </RadixSlider.Root>
+      {readout && (
+        <span className="shrink-0 font-mono text-xs text-fg tabular-nums">{readout}</span>
+      )}
+    </div>
+  );
+}

package/src/components/ui/Table.tsx

@@ -0,0 +1,162 @@
+/*
+ * A table.
+ *
+ * `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.
+ */
+
+import type { KeyboardEvent, MouseEvent, ReactNode } from "react";
+
+import { byDensity, useDensity } from "./Density";
+import { cn } from "./cn";
+
+/** One column of a `Table`: its header and how to render a row's cell. */
+export type Column<Row> = {
+  /** Unique among the columns; the React key of its header and cells. */
+  key: string;
+  /** The `<th>` content. */
+  header: ReactNode;
+  /** Right-aligned, mono, tabular. Use for anything that is a quantity. */
+  numeric?: boolean;
+  /** A CSS width for the column, e.g. `"6rem"`. */
+  width?: string;
+  /** The cell's content for a row. */
+  cell: (row: Row) => ReactNode;
+};
+
+/**
+ * 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.
+ */
+export function Table<Row>({
+  columns,
+  rows,
+  rowKey,
+  empty = "Nothing here.",
+  caption,
+  className,
+  onRowClick,
+  isRowActive,
+  onRowHover,
+}: {
+  /** The columns, in order. */
+  columns: Column<Row>[];
+  /** The rows, in order. */
+  rows: Row[];
+  /** A stable key per row. */
+  rowKey: (row: Row, index: number) => string | number;
+  /** Shown instead of the table when there are no rows. Defaults to "Nothing here.". */
+  empty?: ReactNode;
+  /** Names the table for assistive technology (a visually hidden `<caption>`). */
+  caption?: string | undefined;
+  /** Merged with the scroll wrapper's (or the empty message's) own classes through `cn`. */
+  className?: string | undefined;
+  /** 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. */
+  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. */
+  isRowActive?: (row: Row, index: number) => boolean;
+  /** Pointer enter/leave, for tables kept in step with a canvas overlay.
+   * `null` on leave. */
+  onRowHover?: (row: Row | null, index: number | null) => void;
+}) {
+  const density = useDensity();
+
+  if (rows.length === 0) {
+    return (
+      <p
+        className={cn(
+          "text-center text-fg-muted",
+          byDensity(density, "py-6 text-sm", "py-3 text-xs"),
+          className,
+        )}
+      >
+        {empty}
+      </p>
+    );
+  }
+
+  return (
+    <div className={cn("w-full overflow-x-auto", className)}>
+      <table className={cn("w-full text-left", byDensity(density, "text-sm", "text-[11px]"))}>
+        {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
+                  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>
+  );
+}