@vitavision/ui 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,883 @@
+import { LucideIcon } from "lucide-react";
+import { ComponentProps, KeyboardEvent, MouseEvent, ReactElement, ReactNode } from "react";
+import { ClassValue } from "clsx";
+import * as RadixDialog from "@radix-ui/react-dialog";
+//#region src/theme.d.ts
+/**
+ * A stored theme preference: a palette, or `system` to follow the OS
+ * (`prefers-color-scheme`) and keep following it.
+ */
+type ThemeChoice = "light" | "dark" | "system";
+/**
+ * The `localStorage` key a consumer's theme choice is kept under.
+ *
+ * Every function here takes it as an optional last argument and defaults to this constant,
+ * so a single app needs to pass nothing, while two apps sharing a browser profile -- or one
+ * app that wants a namespaced key -- can each choose their own without stepping on the
+ * other's stored preference.
+ */
+export declare const DEFAULT_THEME_STORAGE_KEY = "vitavision-theme";
+/**
+ * The stored preference.
+ *
+ * @param storageKey - The `localStorage` key. Defaults to `DEFAULT_THEME_STORAGE_KEY`.
+ * @returns The stored choice, or `system` when nothing valid is stored or storage cannot be
+ *   read (private browsing, the server).
+ */
+export declare function readThemeChoice(storageKey?: string): ThemeChoice;
+/**
+ * What `choice` actually resolves to right now.
+ *
+ * @param choice - The preference.
+ * @returns `choice` itself for `light`/`dark`; for `system`, the OS palette (`light` where
+ *   it cannot be queried).
+ */
+export declare function resolveTheme(choice: ThemeChoice): "light" | "dark";
+/**
+ * Store a preference and paint it (the `dark` class on `<html>`).
+ *
+ * @param choice - The new preference.
+ * @param storageKey - The `localStorage` key. Defaults to `DEFAULT_THEME_STORAGE_KEY`.
+ */
+export declare function setThemeChoice(choice: ThemeChoice, storageKey?: string): void;
+/**
+ * Paint the stored choice and keep following the OS while the choice is "system".
+ *
+ * @param storageKey - The `localStorage` key. Defaults to `DEFAULT_THEME_STORAGE_KEY`.
+ * @returns An unsubscribe, so a test can tear the listener down; a long-lived app never does.
+ */
+export declare function initTheme(storageKey?: string): () => void;
+//#endregion
+//#region src/tone.d.ts
+/**
+ * A paint for SVG overlays and charts: the accent (`signal`), a verdict colour, or `muted`.
+ *
+ * Named `MeasureTone` rather than `Tone` — `components/ui/Badge.tsx` already owns that name
+ * for the verdict-badge vocabulary (`neutral`/`normal`/`defect`/`unlabeled`/`warning`/
+ * `info`), and both are re-exported from the package root, where two types of the same name
+ * would collide.
+ */
+type MeasureTone = "signal" | "normal" | "defect" | "warn" | "muted";
+/**
+ * The CSS paint value for a tone — usable directly as a `stroke`, `fill` or `color`. It is a
+ * `var(--token)` reference, so it follows the theme without a re-render.
+ *
+ * @param tone - The tone; `undefined` falls back.
+ * @param fallback - The tone used when `tone` is `undefined`. Defaults to `signal`.
+ * @returns A `var(--…)` CSS value.
+ */
+export declare function toneColor(tone: MeasureTone | undefined, fallback?: MeasureTone): string;
+//#endregion
+//#region src/components/ThemeToggle.d.ts
+/**
+ * The palette switch: one button cycling system → light → dark, stored in `localStorage`
+ * under `storageKey` and painted as the `dark` class on `<html>`.
+ *
+ * Its `aria-label` (repeated in a tooltip) names the current state; it needs a
+ * `TooltipProvider` above it. The stored choice is read as an external store, so the server
+ * render and the hydrating first client render agree ("system") and the stored choice
+ * follows without a mismatch. The state is exposed as `data-theme-choice`.
+ */
+export declare function ThemeToggle({ storageKey, className }: {
+  /** The `localStorage` key; per app, so two apps sharing a profile keep their own choice. */
+  storageKey?: string | undefined;
+  /** Merged with the button's own classes through `cn`. */
+  className?: string | undefined;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/cn.d.ts
+/**
+ * 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 declare function cn(...inputs: ClassValue[]): string;
+/**
+ * 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 declare 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 declare const focusRingInset = "focus-visible:outline-2 focus-visible:outline-offset-0 focus-visible:outline-signal";
+//#endregion
+//#region src/components/ui/Badge.d.ts
+/**
+ * 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.
+ */
+type Tone = "neutral" | "normal" | "defect" | "unlabeled" | "warning" | "info";
+/**
+ * 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 declare function Badge({ tone, 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;
+}): import("react").JSX.Element;
+/**
+ * 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 declare 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;
+}): import("react").JSX.Element;
+/** Counts as a compact `12 normal · 9 defect` run of badges, skipping the zeroes. */
+export declare 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;
+}): 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,
+ * `secondary` for the rest, `ghost` for toolbar actions, `danger` for an action that
+ * destroys something.
+ */
+type ButtonVariant = "primary" | "secondary" | "ghost" | "danger";
+/** A button's height and padding. `md` is the comfortable density's size, `sm` the compact one's. */
+type ButtonSize = "sm" | "md";
+/**
+ * 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 declare function buttonClasses({ variant, size, className }?: {
+  variant?: ButtonVariant | undefined;
+  size?: ButtonSize | undefined;
+  className?: string | undefined;
+}): string;
+/**
+ * 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 declare function Button({ variant, size, type, loading, icon, asChild, 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;
+}): import("react").JSX.Element;
+/**
+ * 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 declare function ButtonLink({ variant, size, icon, asChild, 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;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/Density.d.ts
+/**
+ * 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).
+ */
+type Density = "comfortable" | "compact";
+/**
+ * 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 declare function useDensity(): Density;
+/**
+ * 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 declare function byDensity<T>(density: Density, comfortable: T, compact: T): T;
+/**
+ * Sets the density for a region: every primitive below it reads the value through
+ * `useDensity`. Nest providers to switch a sub-region back.
+ */
+export declare function DensityProvider({ value, children }: {
+  /** The density for everything below. */
+  value: Density;
+  /** The region. */
+  children: ReactNode;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/Dialog.d.ts
+/**
+ * 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 declare 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;
+}): import("react").JSX.Element;
+/**
+ * The destructive-action confirmation: a `Dialog` whose footer is Cancel and one confirm
+ * button. Say in `description` what will actually happen.
+ */
+export declare function ConfirmDialog({ open, onOpenChange, title, description, confirmLabel, onConfirm, loading, disabled, destructive, 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;
+}): import("react").JSX.Element;
+/**
+ * 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 declare const DialogClose: import("react").ForwardRefExoticComponent<RadixDialog.DialogCloseProps & import("react").RefAttributes<HTMLButtonElement>>;
+//#endregion
+//#region src/components/ui/Disclosure.d.ts
+/**
+ * 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 declare function Disclosure({ summary, count, defaultOpen, 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;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/Feedback.d.ts
+/** A callout's kind: a fact (`info`), a caveat (`warning`), a failure (`error`) or `success`. */
+type CalloutTone = "info" | "warning" | "error" | "success";
+/**
+ * A boxed message with a tone icon, an optional title and optional actions.
+ *
+ * An `error` callout is a `role="alert"` (announced at once); the others are
+ * `role="status"`. The tone is exposed as `data-tone`.
+ */
+export declare function Callout({ tone, title, actions, className, children }: {
+  /** Defaults to `info`. */
+  tone?: CalloutTone | undefined;
+  /** A one-line summary above the message. */
+  title?: ReactNode;
+  /** Buttons for what to do about it, below the message. */
+  actions?: ReactNode;
+  /** Merged with the callout's own classes through `cn`. */
+  className?: string | undefined;
+  /** The message: what happened and what to do about it. */
+  children: ReactNode;
+}): import("react").JSX.Element;
+/** The common error shape: an `error` `Callout` with only a message. */
+export declare function ErrorBox({ className, children }: {
+  /** Merged with the callout's own classes through `cn`. */
+  className?: string | undefined;
+  /** What went wrong and what to do about it. */
+  children: ReactNode;
+}): import("react").JSX.Element;
+/** An empty state: a sentence saying why there is nothing here, and the action that fixes it. */
+export declare function Empty({ action, className, children }: {
+  /** The action — usually a primary `Button` — rather than a description of it. */
+  action?: ReactNode;
+  /** Merged with the empty state's own classes through `cn`. */
+  className?: string | undefined;
+  /** Why there is nothing to show. */
+  children: ReactNode;
+}): import("react").JSX.Element;
+/** One placeholder bar for content on its way (`aria-hidden`; size it with `className`). */
+export declare function Skeleton({ className }: {
+  /** Sets the bar's size; merged with its own classes through `cn`. */
+  className?: string | undefined;
+}): import("react").JSX.Element;
+/** A stand-in for a panel's worth of content, so the layout does not jump when it lands. */
+export declare function SkeletonRows({ rows, className }: {
+  /** How many bars. Defaults to 3; the last is shorter. */
+  rows?: number | undefined;
+  /** Merged with the column's own classes through `cn`. */
+  className?: string | undefined;
+}): import("react").JSX.Element;
+/**
+ * A known fraction done, as a bar and (with `label`) a percentage line.
+ *
+ * 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.
+ */
+export declare function ProgressBar({ fraction, label, "aria-label": ariaLabel, className }: {
+  /** Done, from 0 to 1. Clamped. */
+  fraction: number;
+  /** What is progressing, printed after the percentage: "42 of 100 images". */
+  label?: string | undefined;
+  /** The bar's accessible name. Defaults to `label`, then to "Progress". */
+  "aria-label"?: string | undefined;
+  /** Merged with the wrapper's own classes through `cn`. */
+  className?: string | undefined;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/Field.d.ts
+/**
+ * A label, the control, and optionally a description, an error and a compact annotation.
+ *
+ * The label text and the annotation name the control (the `<label>` wraps them and the
+ * control); the description and the error are outside the label and wired into the
+ * control's `aria-describedby` instead (the error also sets `aria-invalid`): directly for
+ * this package's controls — `Input`, `NumberInput`, `Textarea`, `Select`, `Slider`,
+ * `SegmentedControl`, `Checkbox` — and, with `as="group"`, on the group itself. A control of your own inside a `label` field does not
+ * pick them up; give it `aria-describedby` yourself. State is exposed as `data-invalid` and
+ * `data-required`.
+ */
+export declare function Field({ label, description, error, required, annotation, as, className, children }: {
+  /** The field's name, shown above the control. */
+  label: string;
+  /** What the value means or does. Always visible, and read with the control. */
+  description?: ReactNode;
+  /** What is wrong with the current value. Shown in the verdict red, announced as an alert. */
+  error?: ReactNode;
+  /** Marks the field required (a `*` after the label). */
+  required?: boolean | undefined;
+  /** A compact fact about the accepted values -- a range, a unit -- kept out of the prose. */
+  annotation?: ReactNode;
+  /**
+   * `label` (the default) wraps the control in a `<label>`; `group` renders a
+   * `role="group"` named by `label`, for a set of radios or a segmented control.
+   */
+  as?: "label" | "group";
+  /** Merged with the field's own classes through `cn`. */
+  className?: string | undefined;
+  /** The control. */
+  children: ReactNode;
+}): 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
+ * focus — for a native control that is not one of `Input`, `NumberInput` or `Textarea`.
+ * Add the height with `useControlHeight()`.
+ */
+export declare const controlClasses: string;
+/**
+ * The former name of `controlClasses`, kept as an alias for existing consumers.
+ *
+ * @deprecated Use `Input`, `NumberInput`, `Textarea` or `Select`, or `controlClasses`.
+ */
+export declare const inputClasses: string;
+/**
+ * The control height in force — exported so an app's own native control can match.
+ *
+ * @returns A Tailwind height class: `h-8` comfortable, `h-7` compact.
+ */
+export declare function useControlHeight(): string;
+/**
+ * A single-line text input. Takes every `<input>` prop, `ref` included; inside a `Field` it
+ * is described by the field's description and error.
+ */
+export declare function Input({ className, "aria-describedby": describedBy, ...rest }: ComponentProps<"input">): import("react").JSX.Element;
+/**
+ * A number, with the schema's own bounds attached.
+ *
+ * `font-mono` because these are read as quantities and compared down a column. Takes every
+ * `<input>` prop, `ref` included (`type` is always `number`).
+ */
+export declare function NumberInput({ className, "aria-describedby": describedBy, ...rest }: Omit<ComponentProps<"input">, "min" | "max"> & {
+  /** The smallest accepted value. */
+  min?: number | undefined;
+  /** The largest accepted value. */
+  max?: number | undefined;
+}): 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/Panel.d.ts
+/**
+ * A bordered surface with an optional header (a title and actions) above a padded body.
+ * The header and the padding follow the density in force.
+ */
+export declare function Panel({ title, actions, className, bodyClassName, children }: {
+  /** The header's heading (an `<h2>`). */
+  title?: ReactNode;
+  /** Controls at the header's right end. */
+  actions?: ReactNode;
+  /** Merged with the panel's own classes through `cn`. */
+  className?: string | undefined;
+  /** Merged with the body's own classes (its padding) through `cn`. */
+  bodyClassName?: string | undefined;
+  /** The body. */
+  children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A numbered step inside a form.
+ *
+ * The number is not decoration: it marks a genuine ordering, where each choice narrows the
+ * next. Do not reach for this where the parts are merely adjacent.
+ */
+export declare function Section({ step, title, hint, actions, className, children }: {
+  /** The step's number, shown zero-padded before the title (decorative, `aria-hidden`). */
+  step?: number | undefined;
+  /** The step's heading (an `<h3>`). */
+  title: string;
+  /** A short line after the title. */
+  hint?: ReactNode;
+  /** Controls at the heading row's right end. */
+  actions?: ReactNode;
+  /** Merged with the section's own classes through `cn`. */
+  className?: string | undefined;
+  /** The step's content. */
+  children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Where `PageHeader`'s back link goes: `{ href, label }` for a plain URL, or the app's own
+ * link element (a router's `<Link>`).
+ */
+type BackLink = {
+  href: string;
+  label: string;
+} |
+/** A link element — typically a router's `<Link to="…">Label</Link>` — styled and prefixed with an arrow. */
+ReactElement;
+/**
+ * The top of a screen: an optional back link, the `<h1>` title with actions beside it, and
+ * a line of meta facts below. Links go through `back`, never a router import.
+ */
+export declare function PageHeader({ title, meta, actions, back, className }: {
+  /** The screen's heading (the `<h1>`). */
+  title: ReactNode;
+  /** Small facts under the title — an id, a date, a status badge. */
+  meta?: ReactNode;
+  /** The screen's actions, beside the title. */
+  actions?: ReactNode;
+  /**
+   * The way up. `{ href, label }` renders a plain `<a>`; for client-side navigation pass the
+   * router's own link — `back={<Link to="/experiments">Experiments</Link>}` — which is
+   * rendered with the back-link style and arrow, so this package never imports a router.
+   */
+  back?: BackLink | undefined;
+  /** Merged with the header's own classes through `cn`. */
+  className?: string | undefined;
+}): import("react").JSX.Element;
+/** One fact on a `ReadoutStrip`: a value, optionally labelled and optionally a link. */
+type ReadoutItem = {
+  /** A quiet prefix naming what the value is, where the value alone is ambiguous. */
+  label?: string | undefined;
+  /** The fact. An item whose value is `null` or `undefined` is skipped. */
+  value: ReactNode;
+  /** Makes the value a plain `<a href>`. */
+  href?: string | undefined;
+  /**
+   * Makes the value a link through the app's own element — a router's `<Link to="…" />`,
+   * given without children: the value becomes its content. Takes precedence over `href`.
+   */
+  link?: ReactElement | undefined;
+};
+/**
+ * The instrument's display line: the facts about what is on screen, in one fixed slot.
+ *
+ * Stated in the same place on every screen, in mono, the way a piece of measuring equipment
+ * has one readout rather than a label per panel. Rendered as a list because it is one.
+ */
+export declare function ReadoutStrip({ items, className }: {
+  /** The facts, in order. Items with no value are skipped. */
+  items: ReadoutItem[];
+  /** Merged with the list's own classes through `cn`. */
+  className?: string | undefined;
+}): import("react").JSX.Element | null;
+//#endregion
+//#region src/components/ui/SegmentedControl.d.ts
+/**
+ * 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 declare function SegmentedControl({ value, defaultValue, options, onValueChange, disabled, "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;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/Select.d.ts
+/** One entry of a `Select`'s list. */
+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 declare function Select({ value, onValueChange, options, placeholder, unsetLabel, disabled, "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;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/Slider.d.ts
+/**
+ * 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 declare function Slider({ value, onValueChange, onValueCommit, min, max, step, readout, disabled, "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;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/Table.d.ts
+/** One column of a `Table`: its header and how to render a row's cell. */
+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 declare function Table<Row>({ columns, rows, rowKey, empty, 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;
+}): 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").
+ * Always labelled; the label and the description sit beside the switch.
+ *
+ * Controlled. Radix exposes `data-state` (`checked`/`unchecked`) and `data-disabled`.
+ */
+export declare function Switch({ checked, onCheckedChange, label, description, disabled, 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;
+}): import("react").JSX.Element;
+/**
+ * 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 declare function Checkbox({ checked, onCheckedChange, onClick, label, description, disabled, "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;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/ToggleChip.d.ts
+/**
+ * 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 declare function ToggleChip({ checked, onCheckedChange, children, swatch, disabled, 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;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/ui/Tooltip.d.ts
+/**
+ * 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 declare function TooltipProvider({ children }: {
+  /** The app, or the region that uses tooltips. */
+  children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * 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 declare function Tooltip({ content, children }: {
+  /** The explanation. */
+  content: ReactNode;
+  /** The one element it explains. */
+  children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * 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 declare function InfoHint({ children, label, icon: Icon }: {
+  /** 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;
+}): import("react").JSX.Element;
+//#endregion
+//#region src/components/Tabs.d.ts
+/** One tab of a `Tabs` strip. */
+interface TabItem<Id extends string> {
+  /** Identifies the tab to `active` and `onSelect`. Unique within the strip. */
+  id: Id;
+  /** The tab's text, and its accessible name. */
+  label: string;
+  /** Shown after the label, for the chips that carry a row or override count. */
+  count?: number;
+  /** Shown but not selectable, and skipped by the arrow keys. */
+  disabled?: boolean;
+  /** Why this tab has nothing to show, for a reader wondering what they missed. */
+  title?: string;
+}
+/**
+ * A tab strip (`role="tablist"`): the caller renders the panel for the `active` tab.
+ *
+ * Keyboard: one tab stop for the whole strip (the active tab); ←/→ move to the previous or
+ * next enabled tab and select it, Home/End to the first and last. Each tab carries
+ * `data-state` (`active`/`inactive`). Pass `idPrefix` to wire the tabs to the panel: the tab
+ * for `id` gets the element id `<idPrefix>-tab-<id>` and the active tab gets
+ * `aria-controls="<idPrefix>-panel-<id>"`, so render the panel as a `role="tabpanel"` element
+ * with the id `<idPrefix>-panel-<active>` and `aria-labelledby="<idPrefix>-tab-<active>"`.
+ */
+export declare function Tabs<Id extends string>({ items, active, onSelect, label, idPrefix, className }: {
+  /** The tabs, in order. */
+  items: TabItem<Id>[];
+  /** The selected tab's id. */
+  active: Id;
+  /** Called with a tab's id when it is clicked or reached with the arrow keys. */
+  onSelect: (id: Id) => void;
+  /** Names the tab list. */
+  label: string;
+  /** Prefix for the tab and panel element ids; enables `aria-controls` (see above). */
+  idPrefix?: string | undefined;
+  /** Merged with the strip's own classes through `cn`. */
+  className?: string | undefined;
+}): import("react").JSX.Element;
+//#endregion
+export type { BackLink, ButtonSize, ButtonVariant, CalloutTone, Column, Density, MeasureTone, ReadoutItem, SelectOption, TabItem, ThemeChoice, Tone };
+//# sourceMappingURL=index.d.ts.map