@vitavision/ui 0.6.0

package/src/components/ui/Toggle.tsx

@@ -0,0 +1,163 @@
+/*
+ * The two binary controls, and the difference between them.
+ *
+ * A `Switch` changes how the thing behaves from now on -- "allow downloads", "show the
+ * mask", "lock the caliper axis" -- and reads as a setting. A `Checkbox` asserts something
+ * about a state you are about to commit -- "I have read the warnings", "keep this channel"
+ * -- and reads as a statement.
+ */
+
+import * as RadixCheckbox from "@radix-ui/react-checkbox";
+import * as RadixSwitch from "@radix-ui/react-switch";
+import { Check, Minus } from "lucide-react";
+import { useId, type MouseEvent, type ReactNode } from "react";
+
+import { useFieldDescription } from "./Field";
+import { cn, focusRing } from "./cn";
+
+/**
+ * A setting: changes how the thing behaves from now on, and reads as one ("show the mask").
+ * Always labelled; the label and the description sit beside the switch.
+ *
+ * Controlled. Radix exposes `data-state` (`checked`/`unchecked`) and `data-disabled`.
+ */
+export function Switch({
+  checked,
+  onCheckedChange,
+  label,
+  description,
+  disabled = false,
+  className,
+}: {
+  /** Whether it is on. */
+  checked: boolean;
+  /** Called with the new state. */
+  onCheckedChange: (checked: boolean) => void;
+  /** What the setting is. */
+  label: ReactNode;
+  /** What turning it on does. */
+  description?: ReactNode;
+  /** Blocks the switch. */
+  disabled?: boolean | undefined;
+  /** Merged with the row's own classes through `cn`. */
+  className?: string | undefined;
+}) {
+  const descriptionId = useId();
+  return (
+    <label className={cn("flex min-w-0 items-start gap-2.5", className)}>
+      <RadixSwitch.Root
+        checked={checked}
+        onCheckedChange={onCheckedChange}
+        disabled={disabled}
+        aria-describedby={description ? descriptionId : undefined}
+        className={cn(
+          "mt-0.5 h-4 w-7 shrink-0 rounded-full border border-line-strong bg-raised transition-colors",
+          "data-[state=checked]:border-signal data-[state=checked]:bg-signal",
+          "disabled:cursor-not-allowed disabled:opacity-50",
+          focusRing,
+        )}
+      >
+        <RadixSwitch.Thumb
+          className={cn(
+            "block size-3 rounded-full bg-fg-subtle transition-transform will-change-transform",
+            "translate-x-0.5 data-[state=checked]:translate-x-3.5 data-[state=checked]:bg-signal-fg",
+          )}
+        />
+      </RadixSwitch.Root>
+      <span className="flex min-w-0 flex-col gap-0.5">
+        <span className="text-sm leading-tight text-fg">{label}</span>
+        {description && (
+          <span id={descriptionId} className="text-xs leading-snug text-fg-muted">
+            {description}
+          </span>
+        )}
+      </span>
+    </label>
+  );
+}
+
+/**
+ * A statement about a state you are about to commit ("keep this channel"). With a `label`
+ * it renders its own row; without one it is a bare box (give it `aria-label`, e.g. in a
+ * table cell).
+ *
+ * Controlled. Radix exposes `data-state` (`checked`/`unchecked`/`indeterminate`) and
+ * `data-disabled`; inside a `Field` it is described by the field's description and error.
+ */
+export function Checkbox({
+  checked,
+  onCheckedChange,
+  onClick,
+  label,
+  description,
+  disabled = false,
+  "aria-label": ariaLabel,
+  className,
+}: {
+  /** `"indeterminate"` for a partial selection over a set. */
+  checked: boolean | "indeterminate";
+  /** Called with the new state (never `"indeterminate"`: a click resolves it). */
+  onCheckedChange: (checked: boolean) => void;
+  /**
+   * For a checkbox whose meaning depends on the modifier keys — extending a range with
+   * shift, toggling one out of a selection with the platform key. `onCheckedChange` gets a
+   * boolean and cannot carry them. Keyboard activation synthesises a click with its
+   * modifiers intact, so this sees both input paths.
+   */
+  onClick?: ((event: MouseEvent<HTMLButtonElement>) => void) | undefined;
+  /** What checking it asserts. Omit for a bare box. */
+  label?: ReactNode;
+  /** More about the statement, under the label. */
+  description?: ReactNode;
+  /** Blocks the box. */
+  disabled?: boolean | undefined;
+  /** For a checkbox in a table cell, where the row is the label. */
+  "aria-label"?: string | undefined;
+  /** Merged with the row's (or, without a label, the box's) own classes through `cn`. */
+  className?: string | undefined;
+}) {
+  const descriptionId = useId();
+  const described = useFieldDescription(description ? descriptionId : undefined);
+  const box = (
+    <RadixCheckbox.Root
+      checked={checked}
+      onCheckedChange={(next) => onCheckedChange(next === true)}
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      {...described}
+      className={cn(
+        "flex size-4 shrink-0 items-center justify-center rounded-[0.25rem] border border-line-strong bg-raised transition-colors",
+        "data-[state=checked]:border-signal data-[state=checked]:bg-signal",
+        "data-[state=indeterminate]:border-signal data-[state=indeterminate]:bg-signal",
+        "disabled:cursor-not-allowed disabled:opacity-50",
+        focusRing,
+        label === undefined && className,
+      )}
+    >
+      <RadixCheckbox.Indicator className="text-signal-fg">
+        {checked === "indeterminate" ? (
+          <Minus className="size-3" strokeWidth={3} />
+        ) : (
+          <Check className="size-3" strokeWidth={3} />
+        )}
+      </RadixCheckbox.Indicator>
+    </RadixCheckbox.Root>
+  );
+
+  if (label === undefined) return box;
+
+  return (
+    <label className={cn("flex min-w-0 items-start gap-2.5", className)}>
+      <span className="mt-0.5">{box}</span>
+      <span className="flex min-w-0 flex-col gap-0.5">
+        <span className="text-sm leading-tight text-fg">{label}</span>
+        {description && (
+          <span id={descriptionId} className="text-xs leading-snug text-fg-muted">
+            {description}
+          </span>
+        )}
+      </span>
+    </label>
+  );
+}

package/src/components/ui/ToggleChip.tsx

@@ -0,0 +1,81 @@
+/*
+ * A dense on/off control for a thing that is drawn on screen.
+ *
+ * `Switch` is a settings row — a stacked label, a description, generous padding — and
+ * three of them side by side over an image canvas is a panel, not a toolbar. This is the
+ * same binary decision in the space a toolbar has: one line, one target, and an optional
+ * swatch carrying the colour the layer is actually drawn in — an overlay's caliper boxes,
+ * a chart's series — so the legend and the control are the same object rather than two
+ * things to reconcile.
+ *
+ * Hand-built on a native `button` with `role="switch"`: this is not one of the four Radix
+ * primitives the rest of the toggle vocabulary is built on, and a chip does not need one.
+ */
+
+import type { ReactNode } from "react";
+
+import { cn, focusRing } from "./cn";
+
+/**
+ * A dense on/off chip for a layer drawn on screen, with an optional swatch in the layer's
+ * colour: a toolbar-sized `Switch` (`role="switch"`, `aria-checked`).
+ *
+ * Controlled. State is exposed as `data-state` (`checked`/`unchecked`).
+ */
+export function ToggleChip({
+  checked,
+  onCheckedChange,
+  children,
+  swatch,
+  disabled = false,
+  title,
+  className,
+}: {
+  /** Whether the layer is shown. */
+  checked: boolean;
+  /** Called with the new state. */
+  onCheckedChange: (checked: boolean) => void;
+  /** The layer's name. */
+  children: ReactNode;
+  /** A CSS colour: the colour this layer is drawn in, shown as a dot. */
+  swatch?: string;
+  /** Blocks the chip. */
+  disabled?: boolean | undefined;
+  /** Why the control is disabled, or what the layer is. Never the only explanation. */
+  title?: string | undefined;
+  /** Merged with the chip's own classes through `cn`. */
+  className?: string | undefined;
+}) {
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={checked}
+      data-state={checked ? "checked" : "unchecked"}
+      disabled={disabled}
+      title={title}
+      onClick={() => onCheckedChange(!checked)}
+      className={cn(
+        "inline-flex items-center gap-1.5 rounded-control border px-2 py-1 text-xs whitespace-nowrap transition-colors",
+        checked
+          ? "border-line-strong bg-raised text-fg"
+          : "border-line bg-transparent text-fg-muted hover:text-fg",
+        "disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:text-fg-muted",
+        focusRing,
+        className,
+      )}
+    >
+      {swatch !== undefined && (
+        <span
+          aria-hidden
+          className={cn(
+            "size-2 shrink-0 rounded-full border transition-opacity",
+            checked ? "opacity-100" : "opacity-30",
+          )}
+          style={{ backgroundColor: swatch, borderColor: swatch }}
+        />
+      )}
+      {children}
+    </button>
+  );
+}

package/src/components/ui/Tooltip.tsx

@@ -0,0 +1,99 @@
+/*
+ * A short explanation, on demand.
+ *
+ * Replaces the native `title` attribute, which appears after an unpredictable delay, in the
+ * OS palette, at a size nobody chose, and never at all for a keyboard user.
+ *
+ * A tooltip is for text that helps but is not needed to operate the control. Anything a
+ * reader must have in order to answer the question belongs in the field's description,
+ * where it is always visible.
+ */
+
+import * as RadixTooltip from "@radix-ui/react-tooltip";
+import { HelpCircle, type LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+
+import { cn, focusRing } from "./cn";
+
+/**
+ * Shares one open delay (200 ms) across the tooltips below it. Mount it once near the root:
+ * `Tooltip` and `InfoHint` need it above them.
+ */
+export function TooltipProvider({
+  children,
+}: {
+  /** The app, or the region that uses tooltips. */
+  children: ReactNode;
+}) {
+  return <RadixTooltip.Provider delayDuration={200}>{children}</RadixTooltip.Provider>;
+}
+
+/**
+ * A short explanation on hover or focus of its child, for text that helps but is not needed
+ * to operate the control (that belongs in a field's description).
+ *
+ * The child must be one focusable element that accepts a ref (Radix `asChild`). Radix
+ * exposes `data-state` (`closed`/`delayed-open`/`instant-open`) on it.
+ */
+export function Tooltip({
+  content,
+  children,
+}: {
+  /** The explanation. */
+  content: ReactNode;
+  /** The one element it explains. */
+  children: ReactNode;
+}) {
+  return (
+    <RadixTooltip.Root>
+      <RadixTooltip.Trigger asChild>{children}</RadixTooltip.Trigger>
+      <RadixTooltip.Portal>
+        <RadixTooltip.Content
+          sideOffset={6}
+          collisionPadding={8}
+          className={cn(
+            "z-50 max-w-xs rounded-control border border-line bg-overlay px-2.5 py-1.5",
+            "text-xs leading-snug text-fg shadow-lg shadow-black/25",
+          )}
+        >
+          {content}
+          <RadixTooltip.Arrow className="fill-overlay" />
+        </RadixTooltip.Content>
+      </RadixTooltip.Portal>
+    </RadixTooltip.Root>
+  );
+}
+
+/**
+ * The standard affordance: a quiet mark that yields the explanation on hover or focus.
+ *
+ * `icon` exists because the mark answers two different questions. The default `?` offers
+ * help with a control; `Info` offers *facts about the thing on screen* -- where a dataset
+ * came from, which method produced a measurement -- which the tone demotes here rather
+ * than spending a permanent line on. Reading them as the same affordance would be a small
+ * lie.
+ */
+export function InfoHint({
+  children,
+  label = "More information",
+  icon: Icon = HelpCircle,
+}: {
+  /** The explanation shown on hover or focus. */
+  children: ReactNode;
+  /** The button's accessible name. Defaults to "More information". */
+  label?: string | undefined;
+  /** The mark: `HelpCircle` (the default) for help, `Info` for facts about the thing. */
+  icon?: LucideIcon | undefined;
+}) {
+  return (
+    <Tooltip content={children}>
+      <button
+        type="button"
+        aria-label={label}
+        className={cn("rounded-full text-fg-subtle transition-colors hover:text-fg", focusRing)}
+      >
+        <Icon className="size-3.5" />
+      </button>
+    </Tooltip>
+  );
+}

package/src/components/ui/cn.ts

@@ -0,0 +1,41 @@
+/**
+ * Class composition, and the shared focus treatment.
+ *
+ * A naive primitive *appends* the caller's `className` to its own base string, so
+ * `<Button className="px-6">` produces `px-3 … px-6` and wins or loses on source order
+ * rather than on intent. `twMerge` resolves that by conflict group: the caller's `px-6`
+ * replaces the base `px-3` and leaves everything else alone.
+ */
+
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Compose class names: `clsx` for the conditionals, then `tailwind-merge` so a later class
+ * replaces an earlier one of the same conflict group (the caller's `px-6` beats the base
+ * `px-3`). Every primitive merges its caller's `className` through this.
+ *
+ * @param inputs - Class values: strings, arrays, and `{ class: condition }` records.
+ * @returns One class string with conflicts resolved.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}
+
+/**
+ * One focus treatment for every interactive element in the design system.
+ *
+ * `outline` rather than `ring` because an outline follows the element's own border-radius
+ * and needs no offset *colour* -- a ring offset has to know which surface it sits on, and
+ * these primitives are used on `ground`, `surface` and `raised` alike.
+ *
+ * `focus-visible` rather than `focus`, so a mouse click does not leave a ring behind.
+ */
+export const focusRing =
+  "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-signal";
+
+/**
+ * The focus treatment for controls whose own box is the hit target, where an offset ring
+ * would clip: the same outline as {@link focusRing}, drawn with no offset.
+ */
+export const focusRingInset = "focus-visible:outline-2 focus-visible:outline-offset-0 focus-visible:outline-signal";

package/src/components/ui/index.ts

@@ -0,0 +1,47 @@
+/*
+ * The primitive set.
+ *
+ * Import from `components/ui` (or the package root); the individual modules are an
+ * implementation detail.
+ */
+
+export { cn, focusRing, focusRingInset } from "./cn";
+
+export { Badge, CountRun, StatusDot, type Tone } from "./Badge";
+export { Button, ButtonLink, buttonClasses, type ButtonSize, type ButtonVariant } from "./Button";
+export { DensityProvider, byDensity, useDensity, type Density } from "./Density";
+export { ConfirmDialog, Dialog, DialogClose } from "./Dialog";
+export { Disclosure } from "./Disclosure";
+export {
+  Callout,
+  type CalloutTone,
+  Empty,
+  ErrorBox,
+  ProgressBar,
+  Skeleton,
+  SkeletonRows,
+} from "./Feedback";
+export { Field } from "./Field";
+export {
+  Input,
+  NumberInput,
+  Textarea,
+  controlClasses,
+  inputClasses,
+  useControlHeight,
+} from "./Input";
+export {
+  PageHeader,
+  type BackLink,
+  Panel,
+  ReadoutStrip,
+  Section,
+  type ReadoutItem,
+} from "./Panel";
+export { SegmentedControl } from "./SegmentedControl";
+export { Select, type SelectOption } from "./Select";
+export { Slider } from "./Slider";
+export { Table, type Column } from "./Table";
+export { Checkbox, Switch } from "./Toggle";
+export { ToggleChip } from "./ToggleChip";
+export { InfoHint, Tooltip, TooltipProvider } from "./Tooltip";

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * `@vitavision/ui` — the instrument design system: tokens, theme, and the primitive set.
+ *
+ * Import `@vitavision/ui/styles.css` once, from the CSS entry that already has
+ * `@import "tailwindcss";` — see the README for the wiring.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  DEFAULT_THEME_STORAGE_KEY,
+  initTheme,
+  readThemeChoice,
+  resolveTheme,
+  setThemeChoice,
+  type ThemeChoice,
+} from "./theme";
+
+export { toneColor, type MeasureTone } from "./tone";
+
+export { ThemeToggle } from "./components/ThemeToggle";
+
+export * from "./components/ui";
+
+export { Tabs, type TabItem } from "./components/Tabs";

package/src/styles.css

@@ -0,0 +1,170 @@
+@import "tailwindcss";
+
+/* This package's own classes: Tailwind resolves `@source` against the stylesheet that declares
+   it, and this file is exported from `src/` (which ships), so it scans the package's sources. */
+@source "./";
+
+/*
+ * The design token layer.
+ *
+ * Extracted from visual-anomaly-lab's own token layer (its ADR-0021), where it was written
+ * to close a real gap: eleven screens with every colour inlined as a raw `slate-*` utility
+ * at 250-odd call sites — the same palette restated 250 times rather than defined once.
+ * This file is that definition, shared now by every lab app rather than owned by one.
+ *
+ * The direction is *instrument*: the chrome is grey so the data can be loud. Anomaly maps,
+ * colormaps, grayscale sensor images and vector measurement overlays are what these
+ * applications exist to show, so the chrome around them carries no saturation at all.
+ * Exactly one accent -- `signal` -- and it means "you can act here": focus, selection, the
+ * active nav item, the primary button. The verdict colours are reserved for verdicts and
+ * never used as decoration; a green border that means nothing is a green border that
+ * teaches a reader to ignore green.
+ *
+ * The greys are true neutral rather than Tailwind's blue-tinted `slate`. A blue-cast grey
+ * beside a viridis or inferno map, or beside a caliper overlay drawn in the verdict
+ * colours, shifts how the loud thing reads -- a real cost on the one screen that matters
+ * most in either app.
+ *
+ * Mechanism: `@theme inline` registers semantic *names* that point at custom properties, so
+ * `bg-surface` compiles to `var(--surface)` rather than to a baked hex. Both themes are then
+ * one class swap on <html>, and the whole palette is retunable in this file alone. A
+ * consuming app pulls this file in as Tailwind v4 *source* (see the package README), so its
+ * own build resolves `@theme inline` against its own Tailwind — nothing here is pre-compiled.
+ */
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+@theme inline {
+  --color-ground: var(--ground);
+  --color-surface: var(--surface);
+  --color-raised: var(--raised);
+  --color-overlay: var(--overlay);
+  --color-line: var(--line);
+  --color-line-strong: var(--line-strong);
+  --color-canvas: var(--canvas);
+
+  --color-fg: var(--fg);
+  --color-fg-muted: var(--fg-muted);
+  --color-fg-subtle: var(--fg-subtle);
+
+  --color-signal: var(--signal);
+  --color-signal-strong: var(--signal-strong);
+  --color-signal-fg: var(--signal-fg);
+
+  --color-normal: var(--normal);
+  --color-defect: var(--defect);
+  --color-warn: var(--warn);
+
+  --font-sans: "IBM Plex Sans Variable", ui-sans-serif, system-ui, sans-serif;
+  --font-mono: "IBM Plex Mono", ui-monospace, "SF Mono", monospace;
+
+  --radius-control: 0.375rem;
+  --radius-panel: 0.625rem;
+}
+
+/*
+ * 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
+ * a failure there should degrade to a readable page rather than black text on black.
+ *
+ * Contrast (WCAG AA, 4.5:1 for text): `fg-muted` and `fg-subtle` clear it on `ground`,
+ * `surface`, `raised` and `overlay`; `signal-fg` on `signal`; and each verdict colour, and
+ * `signal`, as text on its own /8–/15 tint over `ground`. That last pair is what sets the
+ * light verdict and accent values — change one only with the ratios re-measured.
+ */
+:root {
+  /* Held a little below the panel surface so a card reads as raised off the page without
+     needing a shadow to say so. */
+  --ground: #eef1f2;
+  --surface: #ffffff;
+  --raised: #f4f6f7;
+  --overlay: #ffffff;
+  --line: #e3e6e8;
+  --line-strong: #c8cdd1;
+  --canvas: #101214;
+
+  --fg: #14171a;
+  --fg-muted: #5b646d;
+  --fg-subtle: #646d74;
+
+  --signal: #0a6b7a;
+  --signal-strong: #085763;
+  --signal-fg: #ffffff;
+
+  --normal: #046e4d;
+  --defect: #b31d1d;
+  --warn: #9d4808;
+}
+
+.dark {
+  --ground: #0b0d0f;
+  --surface: #14171a;
+  --raised: #1b1f23;
+  --overlay: #1f242a;
+  --line: #23282d;
+  --line-strong: #3a4147;
+  --canvas: #080a0b;
+
+  --fg: #e8ebed;
+  --fg-muted: #8b949b;
+  --fg-subtle: #838d94;
+
+  --signal: #3bc9db;
+  --signal-strong: #6fdde8;
+  --signal-fg: #04262c;
+
+  --normal: #34d399;
+  --defect: #f87171;
+  --warn: #fbbf24;
+}
+
+@layer base {
+  html {
+    background-color: var(--ground);
+    /* Native scrollbars, range thumbs and select popups follow the app, not the OS. */
+    color-scheme: light;
+  }
+
+  html.dark {
+    color-scheme: dark;
+  }
+
+  body {
+    font-family: var(--font-sans);
+    /* Metric tables, calliper readouts and live-updating counters must not reflow as
+       digits change. */
+    font-variant-numeric: tabular-nums;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  /* A zero that cannot be read as an O, in UIs that print a great many of both. */
+  code,
+  kbd,
+  pre,
+  samp,
+  .font-mono {
+    font-variant-numeric: tabular-nums slashed-zero;
+  }
+
+  /*
+   * The disclosure marker is drawn by `Disclosure` wherever a <details> is styled, so the
+   * UA triangle would be a second, differently-aligned caret next to it.
+   */
+  summary::-webkit-details-marker {
+    display: none;
+  }
+
+  summary {
+    list-style: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+}