@vitavision/ui 0.6.0

package/src/components/ui/Feedback.tsx

@@ -0,0 +1,190 @@
+/*
+ * What the screen says when it has something other than data to show.
+ *
+ * An error explains what happened and what to do about it; it does not apologise and it is
+ * never vague. An empty state is an invitation to act, so it carries the action rather than
+ * describing it. And loading is a shape, not the word "Loading…" -- a skeleton or a
+ * progress bar keeps a slow request from looking identical to a broken one.
+ */
+
+import { AlertTriangle, CheckCircle2, Info, XCircle } from "lucide-react";
+import type { ReactNode } from "react";
+
+import { cn } from "./cn";
+
+/** A callout's kind: a fact (`info`), a caveat (`warning`), a failure (`error`) or `success`. */
+export type CalloutTone = "info" | "warning" | "error" | "success";
+
+const CALLOUT: Record<CalloutTone, { classes: string; Icon: typeof Info }> = {
+  info: { classes: "border-signal/30 bg-signal/8 text-fg", Icon: Info },
+  warning: { classes: "border-warn/30 bg-warn/8 text-fg", Icon: AlertTriangle },
+  error: { classes: "border-defect/30 bg-defect/8 text-fg", Icon: XCircle },
+  success: { classes: "border-normal/30 bg-normal/8 text-fg", Icon: CheckCircle2 },
+};
+
+const ICON_TONE: Record<CalloutTone, string> = {
+  info: "text-signal",
+  warning: "text-warn",
+  error: "text-defect",
+  success: "text-normal",
+};
+
+/**
+ * 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 function Callout({
+  tone = "info",
+  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;
+}) {
+  const { classes, Icon } = CALLOUT[tone];
+  return (
+    <div
+      role={tone === "error" ? "alert" : "status"}
+      data-tone={tone}
+      className={cn(
+        "flex items-start gap-2.5 rounded-control border px-3 py-2.5 text-sm leading-snug",
+        classes,
+        className,
+      )}
+    >
+      <Icon className={cn("mt-0.5 size-4 shrink-0", ICON_TONE[tone])} aria-hidden />
+      <div className="flex min-w-0 flex-1 flex-col gap-1">
+        {title && <p className="font-medium">{title}</p>}
+        <div className="min-w-0 text-fg-muted">{children}</div>
+        {actions && <div className="mt-1 flex flex-wrap items-center gap-2">{actions}</div>}
+      </div>
+    </div>
+  );
+}
+
+/** The common error shape: an `error` `Callout` with only a message. */
+export 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;
+}) {
+  return (
+    <Callout tone="error" className={className}>
+      {children}
+    </Callout>
+  );
+}
+
+/** An empty state: a sentence saying why there is nothing here, and the action that fixes it. */
+export 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;
+}) {
+  return (
+    <div className={cn("flex flex-col items-center gap-3 py-10 text-center", className)}>
+      <p className="text-sm text-fg-muted">{children}</p>
+      {action}
+    </div>
+  );
+}
+
+/** One placeholder bar for content on its way (`aria-hidden`; size it with `className`). */
+export function Skeleton({
+  className,
+}: {
+  /** Sets the bar's size; merged with its own classes through `cn`. */
+  className?: string | undefined;
+}) {
+  return <div aria-hidden className={cn("animate-pulse rounded-control bg-line", className)} />;
+}
+
+/** A stand-in for a panel's worth of content, so the layout does not jump when it lands. */
+export function SkeletonRows({
+  rows = 3,
+  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;
+}) {
+  return (
+    <div role="status" aria-label="Loading" className={cn("flex flex-col gap-2", className)}>
+      {Array.from({ length: rows }, (_, index) => (
+        <Skeleton key={index} className={cn("h-4", index === rows - 1 ? "w-2/3" : "w-full")} />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * 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 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;
+}) {
+  const percent = Math.round(Math.min(Math.max(fraction, 0), 1) * 100);
+  return (
+    <div className={cn("flex flex-col gap-1.5", className)}>
+      <div
+        role="progressbar"
+        aria-label={ariaLabel ?? label ?? "Progress"}
+        aria-valuenow={percent}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        data-complete={percent === 100 ? "" : undefined}
+        className="h-1.5 overflow-hidden rounded-full bg-line"
+      >
+        <div
+          className="h-full rounded-full bg-signal transition-[width] duration-300"
+          style={{ width: `${percent}%` }}
+        />
+      </div>
+      {label && (
+        <span className="font-mono text-xs text-fg-muted tabular-nums">
+          {percent}% · {label}
+        </span>
+      )}
+    </div>
+  );
+}

package/src/components/ui/Field.tsx

@@ -0,0 +1,149 @@
+/*
+ * A labelled control.
+ *
+ * Two things a naive label cannot express, both of which the schema form needs. A required
+ * field's marker is a separate span rather than text concatenated onto the label string, so
+ * it can be styled, read out as a marker, or dropped. And a field's description (and its
+ * error) is wired to the control through `aria-describedby`, so a screen reader connects
+ * the two.
+ *
+ * `as="group"` exists because a `<label>` cannot label a set of radios or a segmented
+ * control; that case needs a labelled group instead, and getting it wrong is the difference
+ * between a control that announces itself and one that announces nothing.
+ */
+
+import { createContext, use, useId, useMemo, type ReactNode } from "react";
+
+import { byDensity, useDensity } from "./Density";
+import { cn } from "./cn";
+
+/** What a `Field` tells the control inside it: the ids that describe it, and whether it is invalid. */
+interface FieldControl {
+  describedBy: string | undefined;
+  invalid: boolean;
+}
+
+const FieldContext = createContext<FieldControl>({ describedBy: undefined, invalid: false });
+
+/**
+ * The `aria-describedby` and `aria-invalid` a control inside a `Field` should carry, merged
+ * with the control's own `aria-describedby`. Used by this package's controls; not exported
+ * from the package.
+ */
+export function useFieldDescription(own?: string): {
+  "aria-describedby": string | undefined;
+  "aria-invalid": true | undefined;
+} {
+  const { describedBy, invalid } = use(FieldContext);
+  const ids = [own, describedBy].filter(Boolean).join(" ");
+  return { "aria-describedby": ids === "" ? undefined : ids, "aria-invalid": invalid || undefined };
+}
+
+/**
+ * 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 function Field({
+  label,
+  description,
+  error,
+  required = false,
+  annotation,
+  as = "label",
+  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;
+}) {
+  const descriptionId = useId();
+  const errorId = useId();
+  const density = useDensity();
+
+  const hasError = error !== undefined && error !== null && error !== false;
+  const describedBy =
+    [description ? descriptionId : undefined, hasError ? errorId : undefined]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  // A group carries the description itself; its controls would only repeat it.
+  const control = useMemo(
+    () => ({ describedBy: as === "label" ? describedBy : undefined, invalid: hasError }),
+    [as, describedBy, hasError],
+  );
+
+  const gap = byDensity(density, "gap-1.5", "gap-1");
+
+  const labelled = (
+    <>
+      <span className="flex items-baseline gap-2">
+        <span className={cn("font-medium text-fg", byDensity(density, "text-xs", "text-[11px]"))}>
+          {label}
+          {required && (
+            <span className="ml-0.5 text-defect" title="Required">
+              *
+            </span>
+          )}
+        </span>
+        {annotation && (
+          <span className="ml-auto font-mono text-[11px] text-fg-subtle">{annotation}</span>
+        )}
+      </span>
+      <FieldContext value={control}>{children}</FieldContext>
+    </>
+  );
+
+  return (
+    <div
+      className={cn("flex min-w-0 flex-col", gap, className)}
+      data-invalid={hasError ? "" : undefined}
+      data-required={required ? "" : undefined}
+      {...(as === "group"
+        ? { role: "group", "aria-label": label, "aria-describedby": describedBy }
+        : {})}
+    >
+      {/* The description and the error sit outside the <label>: inside it they would be read
+          as part of the control's name as well as its description. */}
+      {as === "label" ? (
+        <label className={cn("flex min-w-0 flex-col", gap)}>{labelled}</label>
+      ) : (
+        labelled
+      )}
+
+      {description && (
+        <span id={descriptionId} className="text-xs leading-snug text-fg-muted">
+          {description}
+        </span>
+      )}
+      {hasError && (
+        <span id={errorId} role="alert" className="text-xs leading-snug text-defect">
+          {error}
+        </span>
+      )}
+    </div>
+  );
+}

package/src/components/ui/Input.tsx

@@ -0,0 +1,100 @@
+/*
+ * Text entry.
+ *
+ * `controlClasses` is exported so a native control that isn't one of the wrapped ones below
+ * can still pick up the shared palette and focus treatment.
+ */
+
+import type { ComponentProps } from "react";
+
+import { byDensity, useDensity } from "./Density";
+import { useFieldDescription } from "./Field";
+import { cn, focusRingInset } from "./cn";
+
+/**
+ * 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 const controlClasses = cn(
+  "w-full rounded-control border border-line-strong bg-raised px-2.5 text-sm text-fg",
+  "placeholder:text-fg-subtle",
+  "transition-colors hover:border-fg-subtle",
+  "disabled:cursor-not-allowed disabled:opacity-50",
+  focusRingInset,
+);
+
+/**
+ * The former name of `controlClasses`, kept as an alias for existing consumers.
+ *
+ * @deprecated Use `Input`, `NumberInput`, `Textarea` or `Select`, or `controlClasses`.
+ */
+export const inputClasses = controlClasses;
+
+/**
+ * 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 function useControlHeight(): string {
+  return byDensity(useDensity(), "h-8", "h-7");
+}
+
+/**
+ * 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 function Input({ className, "aria-describedby": describedBy, ...rest }: ComponentProps<"input">) {
+  return (
+    <input
+      {...useFieldDescription(describedBy)}
+      {...rest}
+      className={cn(controlClasses, useControlHeight(), className)}
+    />
+  );
+}
+
+/**
+ * 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 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;
+}) {
+  return (
+    <input
+      {...useFieldDescription(describedBy)}
+      {...rest}
+      type="number"
+      inputMode="decimal"
+      className={cn(controlClasses, useControlHeight(), "font-mono tabular-nums", className)}
+    />
+  );
+}
+
+/**
+ * Multi-line text — set in mono, for JSON and lists. Takes every `<textarea>` prop, `ref`
+ * included.
+ */
+export function Textarea({
+  className,
+  "aria-describedby": describedBy,
+  ...rest
+}: ComponentProps<"textarea">) {
+  return (
+    <textarea
+      {...useFieldDescription(describedBy)}
+      {...rest}
+      className={cn(controlClasses, "py-1.5 font-mono", className)}
+    />
+  );
+}

package/src/components/ui/Panel.tsx

@@ -0,0 +1,248 @@
+/*
+ * The page furniture: what holds a screen together above the level of a single control.
+ *
+ * One heading size and one gap rule, defined once so every route in every consuming app
+ * agrees with the others by construction rather than by luck.
+ */
+
+import { Slot, Slottable } from "@radix-ui/react-slot";
+import { isValidElement, type ReactElement, type ReactNode } from "react";
+
+import { byDensity, useDensity } from "./Density";
+import { cn } from "./cn";
+
+/**
+ * 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 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;
+}) {
+  const density = useDensity();
+
+  return (
+    <section className={cn("rounded-panel border border-line bg-surface", className)}>
+      {(title || actions) && (
+        <header
+          className={cn(
+            "flex items-center justify-between gap-4 border-b border-line",
+            byDensity(density, "min-h-11 px-4 py-2.5", "min-h-8 px-2.5 py-1"),
+          )}
+        >
+          <h2
+            className={cn(
+              "truncate font-semibold text-fg",
+              byDensity(
+                density,
+                "text-sm tracking-tight",
+                "text-[11px] tracking-wider uppercase text-fg-muted",
+              ),
+            )}
+          >
+            {title}
+          </h2>
+          {actions && <div className="flex shrink-0 items-center gap-1.5">{actions}</div>}
+        </header>
+      )}
+      <div className={cn(byDensity(density, "p-4", "p-2.5"), bodyClassName)}>{children}</div>
+    </section>
+  );
+}
+
+/**
+ * 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 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;
+}) {
+  const density = useDensity();
+
+  return (
+    <section className={cn("flex flex-col", byDensity(density, "gap-3", "gap-1.5"), className)}>
+      <div className={cn("flex items-baseline", byDensity(density, "gap-2.5", "gap-2"))}>
+        {step !== undefined && (
+          <span
+            className="font-mono text-xs text-fg-subtle tabular-nums"
+            aria-hidden
+          >
+            {String(step).padStart(2, "0")}
+          </span>
+        )}
+        <h3 className="text-sm font-semibold tracking-tight text-fg">{title}</h3>
+        {hint && <p className="text-xs text-fg-muted">{hint}</p>}
+        {actions && <div className="ml-auto flex items-center gap-2">{actions}</div>}
+      </div>
+      {children}
+    </section>
+  );
+}
+
+/**
+ * Where `PageHeader`'s back link goes: `{ href, label }` for a plain URL, or the app's own
+ * link element (a router's `<Link>`).
+ */
+export type BackLink =
+  | { href: string; label: string }
+  /** A link element — typically a router's `<Link to="…">Label</Link>` — styled and prefixed with an arrow. */
+  | ReactElement;
+
+const BACK_CLASSES = "w-fit text-xs text-fg-muted transition-colors hover:text-signal";
+
+/**
+ * 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 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;
+}) {
+  return (
+    <header className={cn("flex flex-col gap-1.5", className)}>
+      {back &&
+        (isHrefLink(back) ? (
+          <a href={back.href} className={BACK_CLASSES}>
+            ← {back.label}
+          </a>
+        ) : (
+          <Slot className={BACK_CLASSES}>
+            {"← "}
+            <Slottable>{back}</Slottable>
+          </Slot>
+        ))}
+      <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
+        <h1 className="text-xl font-semibold tracking-tight text-fg">{title}</h1>
+        {actions && <div className="flex shrink-0 items-center gap-2">{actions}</div>}
+      </div>
+      {meta && <div className="flex flex-wrap items-center gap-2 text-xs text-fg-muted">{meta}</div>}
+    </header>
+  );
+}
+
+function isHrefLink(back: BackLink): back is { href: string; label: string } {
+  return !isValidElement(back);
+}
+
+/** One fact on a `ReadoutStrip`: a value, optionally labelled and optionally a link. */
+export 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;
+};
+
+const READOUT_LINK = "text-fg transition-colors hover:text-signal";
+
+/**
+ * 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 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;
+}) {
+  const shown = items.filter((item) => item.value !== null && item.value !== undefined);
+  if (shown.length === 0) return null;
+
+  return (
+    <ol
+      className={cn(
+        "flex flex-wrap items-center gap-x-2 gap-y-1 font-mono text-xs text-fg-muted",
+        className,
+      )}
+    >
+      {shown.map((item, index) => (
+        // The items are positional facts with no identity of their own (a label is optional
+        // and values repeat), so their place in the strip is the key.
+        // eslint-disable-next-line @eslint-react/no-array-index-key -- positional list, see above
+        <li key={index} className="flex items-center gap-2">
+          {index > 0 && (
+            <span className="text-fg-subtle" aria-hidden>
+              ·
+            </span>
+          )}
+          {item.label && <span className="text-fg-subtle">{item.label}</span>}
+          {item.link ? (
+            <Slot className={READOUT_LINK}>
+              <Slottable>{item.link}</Slottable>
+              {item.value}
+            </Slot>
+          ) : item.href ? (
+            <a href={item.href} className={READOUT_LINK}>
+              {item.value}
+            </a>
+          ) : (
+            <span className="text-fg">{item.value}</span>
+          )}
+        </li>
+      ))}
+    </ol>
+  );
+}