@vitavision/ui 0.6.0

package/src/components/ui/Badge.tsx

@@ -0,0 +1,125 @@
+/*
+ * Status colour, in one place.
+ *
+ * The tone vocabulary is deliberately small and deliberately *about verdicts*. The chrome
+ * carries no saturation, so a colour on screen means something: green is a normal sample
+ * (or an in-tolerance measurement), red is a defect (or an out-of-tolerance one), amber is
+ * a caveat. `info` is the one tone that borrows the interaction accent, and it is reserved
+ * for statements of fact about a method -- "produces anomaly maps", "caliper axis fixed" --
+ * rather than for anything a reader must act on.
+ */
+
+import type { ReactNode } from "react";
+
+import { cn } from "./cn";
+
+/**
+ * The badge and status-dot vocabulary: the verdicts (`normal`, `defect`, `warning`),
+ * `unlabeled` for a sample with no verdict yet, `info` for a statement of fact about a
+ * method, and `neutral` for everything else.
+ */
+export type Tone = "neutral" | "normal" | "defect" | "unlabeled" | "warning" | "info";
+
+const TONE_CLASSES: Record<Tone, string> = {
+  neutral: "bg-raised text-fg-muted ring-line",
+  normal: "bg-normal/12 text-normal ring-normal/25",
+  defect: "bg-defect/12 text-defect ring-defect/25",
+  unlabeled: "bg-raised text-fg-subtle ring-line",
+  warning: "bg-warn/12 text-warn ring-warn/25",
+  info: "bg-signal/12 text-signal ring-signal/25",
+};
+
+const DOT_CLASSES: Record<Tone, string> = {
+  neutral: "bg-fg-subtle",
+  normal: "bg-normal",
+  defect: "bg-defect",
+  unlabeled: "bg-line-strong",
+  warning: "bg-warn",
+  info: "bg-signal",
+};
+
+/**
+ * A short label in a tone: a verdict, a status, a count.
+ *
+ * The tone is exposed as `data-tone`, so a stylesheet or a test can read it without parsing
+ * class names.
+ */
+export function Badge({
+  tone = "neutral",
+  className,
+  children,
+}: {
+  /** Which colour, by meaning. Defaults to `neutral`. */
+  tone?: Tone | undefined;
+  /** Merged with the badge's own classes through `cn`. */
+  className?: string | undefined;
+  /** The label. */
+  children: ReactNode;
+}) {
+  return (
+    <span
+      data-tone={tone}
+      className={cn(
+        "inline-flex items-center gap-1 rounded-control px-1.5 py-0.5 text-xs font-medium ring-1 ring-inset",
+        TONE_CLASSES[tone],
+        className,
+      )}
+    >
+      {children}
+    </span>
+  );
+}
+
+/**
+ * A status as a dot and a word.
+ *
+ * The mapping from a domain status to a tone belongs to each caller -- only it knows
+ * whether "running" is good news -- but the *rendering* of the answer does not.
+ */
+export function StatusDot({
+  tone,
+  className,
+  children,
+}: {
+  /** The status, as a tone; also exposed as `data-tone`. */
+  tone: Tone;
+  /** Merged with the row's own classes through `cn`. */
+  className?: string | undefined;
+  /** The word beside the dot. The dot alone is decoration: say the status in words. */
+  children?: ReactNode;
+}) {
+  return (
+    <span
+      data-tone={tone}
+      className={cn("inline-flex items-center gap-1.5 text-xs text-fg-muted", className)}
+    >
+      <span className={cn("size-1.5 shrink-0 rounded-full", DOT_CLASSES[tone])} aria-hidden />
+      {children}
+    </span>
+  );
+}
+
+/** Counts as a compact `12 normal · 9 defect` run of badges, skipping the zeroes. */
+export function CountRun({
+  counts,
+  className,
+}: {
+  /** `[name, count, tone]` triples, in display order. Zero counts are dropped. */
+  counts: [string, number, Tone][];
+  /** Merged with the run's own classes through `cn`. */
+  className?: string | undefined;
+}) {
+  const shown = counts.filter(([, value]) => value > 0);
+  if (shown.length === 0) {
+    return <span className={cn("text-xs text-fg-subtle", className)}>empty</span>;
+  }
+  return (
+    <span className={cn("flex flex-wrap items-center gap-1.5", className)}>
+      {shown.map(([name, value, tone]) => (
+        <Badge key={name} tone={tone}>
+          <span className="font-mono">{value}</span> {name}
+        </Badge>
+      ))}
+    </span>
+  );
+}

package/src/components/ui/Button.tsx

@@ -0,0 +1,188 @@
+import { Slot, Slottable } from "@radix-ui/react-slot";
+import { Loader2 } from "lucide-react";
+import type { ComponentProps, ReactNode } from "react";
+
+import { byDensity, useDensity } from "./Density";
+import { cn, focusRing } from "./cn";
+
+/**
+ * A button's look, by what the action is: `primary` for the one action a screen is for,
+ * `secondary` for the rest, `ghost` for toolbar actions, `danger` for an action that
+ * destroys something.
+ */
+export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger";
+
+/** A button's height and padding. `md` is the comfortable density's size, `sm` the compact one's. */
+export type ButtonSize = "sm" | "md";
+
+const VARIANT_CLASSES: Record<ButtonVariant, string> = {
+  primary: "bg-signal text-signal-fg hover:bg-signal-strong",
+  secondary: "bg-surface text-fg ring-1 ring-inset ring-line-strong hover:bg-raised",
+  ghost: "text-fg-muted hover:bg-raised hover:text-fg",
+  // Soft rather than a solid red block. The verdict red is also the colour of a defect
+  // badge, and a filled button of it reads as an alarm on a screen that is mostly grey.
+  // Genuinely destructive actions are behind a confirmation dialog regardless. The hover
+  // tint stops at /15 so the red label keeps 4.5:1 on it.
+  danger: "bg-defect/10 text-defect ring-1 ring-inset ring-defect/30 hover:bg-defect/15",
+};
+
+const SIZE_CLASSES: Record<ButtonSize, string> = {
+  sm: "h-7 gap-1.5 px-2.5 text-xs",
+  md: "h-8 gap-2 px-3 text-sm",
+};
+
+/**
+ * The classes that make a control look like a button, for the one element that has to be
+ * something else. Prefer `Button` and `ButtonLink`; this exists so a third shape — a
+ * `<label>` wrapping a file input, say — does not have to copy the variant table.
+ *
+ * @param options - The variant (default `secondary`), the size (default `md`) and the
+ *   caller's own classes, merged last.
+ * @returns The class string.
+ */
+export function buttonClasses({
+  variant = "secondary",
+  size = "md",
+  className,
+}: {
+  variant?: ButtonVariant | undefined;
+  size?: ButtonSize | undefined;
+  className?: string | undefined;
+} = {}): string {
+  return cn(
+    "inline-flex shrink-0 items-center justify-center rounded-control font-medium transition-colors",
+    "disabled:cursor-not-allowed disabled:opacity-45",
+    SIZE_CLASSES[size],
+    VARIANT_CLASSES[variant],
+    focusRing,
+    className,
+  );
+}
+
+function ButtonIcon({ icon }: { icon: ReactNode }) {
+  return (
+    <span className="shrink-0 [&>svg]:size-3.5" aria-hidden>
+      {icon}
+    </span>
+  );
+}
+
+/**
+ * An action. `asChild` renders the button's look onto the single child element instead of a
+ * `<button>` — how a router's link becomes a button-shaped navigation without this package
+ * knowing about routers: `<Button asChild><Link to="/runs">Runs</Link></Button>`.
+ * For a plain URL, `ButtonLink` is the shorter spelling.
+ *
+ * Takes every `<button>` prop, `ref` included. State is exposed as `data-variant` and, while
+ * `loading`, `data-loading` (plus `aria-busy`).
+ */
+export function Button({
+  variant = "secondary",
+  size,
+  type = "button",
+  loading = false,
+  icon,
+  asChild = false,
+  className,
+  children,
+  disabled,
+  ...rest
+}: ComponentProps<"button"> & {
+  /** What kind of action this is. Defaults to `secondary`. */
+  variant?: ButtonVariant | undefined;
+  /** Defaults to the density in force — `md` comfortable, `sm` compact. */
+  size?: ButtonSize | undefined;
+  /** Swaps the icon for a spinner and blocks the click, without the label changing. */
+  loading?: boolean | undefined;
+  /** A leading icon, decorative (`aria-hidden`): the label carries the meaning. */
+  icon?: ReactNode;
+  /**
+   * Render onto the one child element (Radix `Slot`) rather than a `<button>`. The child
+   * keeps its own semantics — a link stays a link — so `type`, `disabled` and `loading` do
+   * not apply.
+   */
+  asChild?: boolean | undefined;
+}) {
+  const density = useDensity();
+  const resolved = size ?? byDensity(density, "md", "sm");
+
+  if (asChild) {
+    return (
+      <Slot
+        {...rest}
+        data-variant={variant}
+        className={buttonClasses({ variant, size: resolved, className })}
+      >
+        {icon && <ButtonIcon icon={icon} />}
+        <Slottable>{children}</Slottable>
+      </Slot>
+    );
+  }
+
+  return (
+    <button
+      type={type}
+      disabled={disabled || loading}
+      aria-busy={loading || undefined}
+      data-variant={variant}
+      data-loading={loading ? "" : undefined}
+      {...rest}
+      className={buttonClasses({ variant, size: resolved, className })}
+    >
+      {loading ? (
+        <Loader2 className="size-3.5 shrink-0 animate-spin" aria-hidden />
+      ) : (
+        icon && <ButtonIcon icon={icon} />
+      )}
+      {children}
+    </button>
+  );
+}
+
+/**
+ * A navigation that looks like a button: one `<a>`, styled by the same variants and density.
+ *
+ * The alternative every consumer reached for was `<Link><Button/></Link>` — a button inside
+ * an anchor, which is invalid HTML, gives a keyboard two tab stops for one action, and makes
+ * a screen reader announce a button that navigates. There is no `disabled` or `loading`:
+ * a link that cannot be followed should not be rendered as one, and a navigation has no
+ * pending state of its own.
+ *
+ * It renders a plain `<a href>`, and takes every `<a>` prop, `ref` included. For a router's
+ * link, pass it as the only child with `asChild` —
+ * `<ButtonLink asChild><Link to="/runs">Runs</Link></ButtonLink>` — so client-side
+ * navigation keeps working and this package still never imports a router.
+ */
+export function ButtonLink({
+  variant = "secondary",
+  size,
+  icon,
+  asChild = false,
+  className,
+  children,
+  ...rest
+}: ComponentProps<"a"> & {
+  /** What kind of action this is. Defaults to `secondary`. */
+  variant?: ButtonVariant | undefined;
+  /** Defaults to the density in force — `md` comfortable, `sm` compact. */
+  size?: ButtonSize | undefined;
+  /** A leading icon, decorative (`aria-hidden`): the label carries the meaning. */
+  icon?: ReactNode;
+  /** Render onto the one child element — a router's `<Link>` — instead of an `<a>`. */
+  asChild?: boolean | undefined;
+}) {
+  const density = useDensity();
+  const resolved = size ?? byDensity(density, "md", "sm");
+  const Comp = asChild ? Slot : "a";
+
+  return (
+    <Comp
+      {...rest}
+      data-variant={variant}
+      className={buttonClasses({ variant, size: resolved, className })}
+    >
+      {icon && <ButtonIcon icon={icon} />}
+      <Slottable>{children}</Slottable>
+    </Comp>
+  );
+}

package/src/components/ui/Density.tsx

@@ -0,0 +1,66 @@
+/*
+ * How much room the chrome takes, as one decision per region rather than per component.
+ *
+ * The default spacing is written for a page: a form you read through once, where generous
+ * padding is what makes it legible. An inspector column beside a canvas is the opposite
+ * problem — it is a permanent surface that accumulates tools, and there the same padding is
+ * simply less of the instrument on screen. Nesting compounds it: a panel body's `p-4`
+ * inside a section's `gap-3` inside a column's own padding is three margins deep before any
+ * control appears.
+ *
+ * `compact` is not "the same design, smaller". It drops the leading and the padding a
+ * reading surface needs and keeps the type sizes and hit targets a control needs, so a
+ * dense column stays clickable. Below this there is no honest saving left — the next step
+ * down is a control too small to hit.
+ *
+ * The default is `comfortable`, so a consumer that never mentions density gets exactly what
+ * it had.
+ */
+
+import { createContext, use } from "react";
+import type { ReactNode } from "react";
+
+/**
+ * How much room the chrome takes: `comfortable` (the default, for a page you read through)
+ * or `compact` (for a permanent tool surface such as an inspector column).
+ */
+export type Density = "comfortable" | "compact";
+
+const DensityContext = createContext<Density>("comfortable");
+
+/**
+ * The density in force here. Every primitive that has two spacings reads this.
+ *
+ * @returns The value of the nearest `DensityProvider`, or `comfortable` outside one.
+ */
+export function useDensity(): Density {
+  return use(DensityContext);
+}
+
+/**
+ * Pick one of two values by the density in force — the primitives' own idiom.
+ *
+ * @param density - The density in force, from `useDensity()`.
+ * @param comfortable - The value for `comfortable`.
+ * @param compact - The value for `compact`.
+ * @returns `compact` when the density is compact, else `comfortable`.
+ */
+export function byDensity<T>(density: Density, comfortable: T, compact: T): T {
+  return density === "compact" ? compact : comfortable;
+}
+
+/**
+ * Sets the density for a region: every primitive below it reads the value through
+ * `useDensity`. Nest providers to switch a sub-region back.
+ */
+export function DensityProvider({
+  value,
+  children,
+}: {
+  /** The density for everything below. */
+  value: Density;
+  /** The region. */
+  children: ReactNode;
+}) {
+  return <DensityContext value={value}>{children}</DensityContext>;
+}

package/src/components/ui/Dialog.tsx

@@ -0,0 +1,187 @@
+/*
+ * Confirmation for the things that cannot be undone, and a shell for the things that need
+ * a form.
+ *
+ * `Dialog` is a modal with no verdict of its own: a title, a body the caller fills, and a
+ * footer it chooses. `ConfirmDialog` is one arrangement of it -- the destructive-action
+ * confirmation every app in this family needs at least once (deleting a dataset, discarding
+ * an in-progress measurement session) -- rather than a second copy of the overlay, the
+ * centring and the width cap.
+ */
+
+import * as RadixDialog from "@radix-ui/react-dialog";
+import { useCallback, useState, type ReactNode } from "react";
+
+import { Button } from "./Button";
+import { cn, focusRingInset } from "./cn";
+
+/**
+ * Whether the body overflows its height cap, kept current as the dialog or its content
+ * resizes. A scrolling body has to be reachable by keyboard (so it can be scrolled without
+ * a pointer); a body that fits must not add a tab stop.
+ */
+function useOverflowing(): [
+  (node: HTMLDivElement | null) => (() => void) | undefined,
+  boolean,
+] {
+  const [overflowing, setOverflowing] = useState(false);
+  const ref = useCallback((node: HTMLDivElement | null) => {
+    if (node === null) return undefined;
+    const measure = () => setOverflowing(node.scrollHeight > node.clientHeight + 1);
+    measure();
+    if (typeof ResizeObserver === "undefined") return undefined;
+    const observer = new ResizeObserver(measure);
+    observer.observe(node);
+    // The body is capped, so once it hits the cap only the content keeps changing size.
+    if (node.firstElementChild) observer.observe(node.firstElementChild);
+    return () => observer.disconnect();
+  }, []);
+  return [ref, overflowing];
+}
+
+/**
+ * A modal: a title, a body the caller fills, and a footer it chooses.
+ *
+ * Controlled — the caller owns `open`. The body scrolls under a height cap so the footer
+ * stays on screen; while it overflows it is a keyboard tab stop (with the focus ring) and
+ * carries `data-overflowing`, so it can be scrolled without a pointer.
+ */
+export function Dialog({
+  open,
+  onOpenChange,
+  title,
+  description,
+  footer,
+  className,
+  children,
+}: {
+  /** Whether the dialog is shown. */
+  open: boolean;
+  /** Called with `false` on Escape, an overlay click or a `DialogClose`. */
+  onOpenChange: (open: boolean) => void;
+  /** Names the dialog (`aria-labelledby`). */
+  title: string;
+  /** Optional: what the reader needs before they can answer, not decoration. */
+  description?: ReactNode;
+  /** The action row, right-aligned below the body. */
+  footer?: ReactNode;
+  /** Merged with the dialog panel's own classes through `cn`. */
+  className?: string | undefined;
+  /** The body. */
+  children?: ReactNode;
+}) {
+  const [bodyRef, overflowing] = useOverflowing();
+
+  return (
+    <RadixDialog.Root open={open} onOpenChange={onOpenChange}>
+      <RadixDialog.Portal>
+        <RadixDialog.Overlay className="fixed inset-0 z-50 bg-black/50 backdrop-blur-[1px]" />
+        <RadixDialog.Content
+          className={cn(
+            "fixed top-1/2 left-1/2 z-50 w-[min(28rem,calc(100vw-2rem))] -translate-x-1/2 -translate-y-1/2",
+            // A ceiling and a column, so a dialog that lists things keeps its footer on
+            // screen and scrolls its body instead of growing past the viewport. Every
+            // short dialog is far below the cap and is unaffected. This is a scroller
+            // inside an overlay, not a second page scroller.
+            "flex max-h-[calc(100vh-4rem)] flex-col",
+            "rounded-panel border border-line bg-overlay p-5 shadow-xl shadow-black/40",
+            "focus:outline-none",
+            className,
+          )}
+        >
+          <RadixDialog.Title className="text-sm font-semibold tracking-tight text-fg">
+            {title}
+          </RadixDialog.Title>
+          {/* Radix warns when a dialog has no description; render an empty one rather than
+              inventing prose for a form whose fields already carry their own labels. */}
+          <RadixDialog.Description
+            className={cn(
+              "mt-2 text-sm leading-relaxed text-fg-muted",
+              description === undefined && "sr-only",
+            )}
+          >
+            {description ?? title}
+          </RadixDialog.Description>
+          <div
+            ref={bodyRef}
+            tabIndex={overflowing ? 0 : undefined}
+            data-overflowing={overflowing ? "" : undefined}
+            className={cn("min-h-0 overflow-y-auto", focusRingInset)}
+          >
+            <div>{children}</div>
+          </div>
+          {footer && <div className="mt-5 flex shrink-0 justify-end gap-2">{footer}</div>}
+        </RadixDialog.Content>
+      </RadixDialog.Portal>
+    </RadixDialog.Root>
+  );
+}
+
+/**
+ * The destructive-action confirmation: a `Dialog` whose footer is Cancel and one confirm
+ * button. Say in `description` what will actually happen.
+ */
+export function ConfirmDialog({
+  open,
+  onOpenChange,
+  title,
+  description,
+  confirmLabel,
+  onConfirm,
+  loading = false,
+  disabled = false,
+  destructive = false,
+  className,
+}: {
+  /** Whether the dialog is shown. */
+  open: boolean;
+  /** Called with `false` on Cancel, Escape or an overlay click. */
+  onOpenChange: (open: boolean) => void;
+  /** The question, e.g. "Delete dataset?". */
+  title: string;
+  /** Say what will actually happen, naming the thing by the name the reader gave it. */
+  description: ReactNode;
+  /** The confirm button's label: the verb, e.g. "Delete". */
+  confirmLabel: string;
+  /** Called on confirm. The dialog stays open; close it (or set `loading`) yourself. */
+  onConfirm: () => void;
+  /** Shows the confirm button's spinner and blocks it while the action runs. */
+  loading?: boolean;
+  /** Blocks the confirm button. */
+  disabled?: boolean;
+  /** Renders the confirm button as `danger` rather than `primary`. */
+  destructive?: boolean;
+  /** Merged with the dialog panel's own classes through `cn`. */
+  className?: string | undefined;
+}) {
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={onOpenChange}
+      title={title}
+      description={description}
+      className={className}
+      footer={
+        <>
+          <RadixDialog.Close asChild>
+            <Button variant="ghost">Cancel</Button>
+          </RadixDialog.Close>
+          <Button
+            variant={destructive ? "danger" : "primary"}
+            loading={loading}
+            disabled={disabled}
+            onClick={onConfirm}
+          >
+            {confirmLabel}
+          </Button>
+        </>
+      }
+    />
+  );
+}
+
+/**
+ * The dialog's own dismiss, for a footer the caller builds: wrap a button in it with
+ * `asChild` — `<DialogClose asChild><Button>Done</Button></DialogClose>`.
+ */
+export const DialogClose = RadixDialog.Close;

package/src/components/ui/Disclosure.tsx

@@ -0,0 +1,62 @@
+/*
+ * Content folded away, with a caret we draw ourselves.
+ *
+ * The base layer (`styles.css`) removes the native `<details>` marker; this supplies one
+ * that rotates with the element's own open state, so no JavaScript is involved in the
+ * animation.
+ *
+ * `<details>` rather than a headless package on purpose: the element already has the
+ * semantics, the keyboard behaviour and the find-in-page integration.
+ */
+
+import { ChevronRight } from "lucide-react";
+import type { ReactNode } from "react";
+
+import { cn } from "./cn";
+
+/**
+ * Content folded away behind a summary line, on a native `<details>`, with a caret that
+ * rotates with the element's own `open` state (no JavaScript involved).
+ *
+ * Uncontrolled: `defaultOpen` sets the initial state and the element owns it after that.
+ */
+export function Disclosure({
+  summary,
+  count,
+  defaultOpen = false,
+  className,
+  children,
+}: {
+  /** The always-visible line that toggles the content. */
+  summary: ReactNode;
+  /** How many things are inside, where the number is the reason to open it. */
+  count?: number;
+  /** Whether it starts open. */
+  defaultOpen?: boolean;
+  /** Merged with the `<details>` element's own classes through `cn`. */
+  className?: string | undefined;
+  /** The folded content. */
+  children: ReactNode;
+}) {
+  return (
+    <details open={defaultOpen} className={cn("group", className)}>
+      <summary
+        className={cn(
+          "flex cursor-pointer items-center gap-1.5 rounded-control py-1 text-xs font-medium text-fg-muted",
+          "transition-colors hover:text-fg",
+          "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-signal",
+        )}
+      >
+        <ChevronRight
+          className="size-3.5 shrink-0 transition-transform group-open:rotate-90"
+          aria-hidden
+        />
+        {summary}
+        {count !== undefined && (
+          <span className="font-mono text-fg-subtle tabular-nums">{count}</span>
+        )}
+      </summary>
+      <div className="pt-3">{children}</div>
+    </details>
+  );
+}