# @umriss-ui/core 0.40.0

> React component library for data-dense dashboards and tools - forms, date pickers, overlays, a tree view and a command palette. Precise, quiet, professional.

Install with `npm install @umriss-ui/core`. This text is generated from the package's demo (https://romanhaendler.github.io/umriss-ui/core/): every page with its import line, its examples - the source exactly as it runs, with the package name where the demo imports its own source - its props tables generated from the code, and what it deliberately does not do. The pages index stands in https://romanhaendler.github.io/umriss-ui/core/llms.txt.

## Scenarios

Composed, realistic screens built from the package. A numbered mark on the screen is an element with `data-callout`.

### Resolve an incident

The engineer on call at Quillmere works an open incident from this console: check the service has recovered, clear its alerts, and close it with a summary.

1. The stepper says where the incident stands, each step as a word; resolving it moves the stepper on.
2. The tiles read the latest five minutes against the service's objectives and say the verdict in a word, not only in colour.
3. The trend shows the half hour above the latency objective, and that it has held below it since 10:10.
4. The alerts that belong to the incident stand in the list; acknowledging one records who knew when.
5. Resolving asks for a cause and a summary, and a toast confirms it without covering the console.

Built from: Breadcrumb, Badge, Tag, Stepper, Stat, Tabs, Menu, Modal, FormField, Select, Textarea, Checkbox, Toast, Line, Table.

```tsx
import { useState } from "react";
import {
  Badge,
  Breadcrumb,
  Button,
  Card,
  CardBody,
  CardHeader,
  Checkbox,
  FormField,
  Grid,
  Heading,
  Menu,
  MenuItem,
  MenuSeparator,
  Modal,
  ModalBody,
  ModalFooter,
  ModalHeader,
  Select,
  Stack,
  Stat,
  Stepper,
  Tab,
  TabList,
  TabPanel,
  Tabs,
  Tag,
  TagGroup,
  Text,
  Textarea,
  ToastProvider,
  useToast,
} from "@umriss-ui/core";
import type { LimitSet } from "@umriss-ui/core";
import { LimitLine, Tooltip, useChart } from "@umriss-ui/charts";
import { useTable } from "@umriss-ui/table";

/* Data from the operations world, written out here so the example runs on its own. */
/** A small LCG - the same numbers on every computer. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

const at = (day: number, hours: number, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();
const MINUTE = 60_000;

/** Tuesday, 17 March 2026, 10:30 - the moment the screens are read at. */
const NOW = at(17, 10, 30);

interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface Engineer {
  id: string;
  name: string;
  team: string;
}

const ENGINEERS: readonly Engineer[] = [
  { id: "priya", name: "Priya Raman", team: "Payments" },
  { id: "jonas", name: "Jonas Keller", team: "Payments" },
  { id: "ada", name: "Ada Mwangi", team: "Identity" },
  { id: "tomasz", name: "Tomasz Nowak", team: "Discovery" },
  { id: "leila", name: "Leila Haddad", team: "Discovery" },
  { id: "sam", name: "Sam Okafor", team: "Messaging" },
  { id: "ines", name: "Ines Duarte", team: "Integrations" },
  { id: "felix", name: "Felix Brandt", team: "Insights" },
];

interface OnCall {
  id: string;
  engineer: string;
  rotation: "primary" | "secondary";
  from: number;
  to: number;
}

/** Monday 16 to Monday 23 March, handed over every morning at 09:00: the
    secondary of one day is the primary of the next. */
const ONCALL: readonly OnCall[] = Array.from({ length: 7 }, (_, day) => [
  { rotation: "primary" as const, engineer: ENGINEERS[day % ENGINEERS.length]!.id },
  { rotation: "secondary" as const, engineer: ENGINEERS[(day + 1) % ENGINEERS.length]!.id },
].map(({ rotation, engineer }) => ({
  id: `${rotation}-${16 + day}`,
  engineer,
  rotation,
  from: at(16 + day, 9),
  to: at(17 + day, 9),
}))).flat();

interface MetricPoint {
  t: number;
  /** Median and 95th percentile latency, in ms. */
  p50: number;
  p95: number;
  /** Failed requests, in per cent. */
  errorRate: number;
  /** Requests per minute. */
  requests: number;
}

/** Requests per minute at the busiest hour, by tier. */
const VOLUME = { 1: 900, 2: 400, 3: 120 } as const;

/** A service's latency and error rate every five minutes of today, from
    midnight up to now. Busy by day, quiet at night; Checkout's 95th percentile
    climbs well past its objective from 09:40 to 10:10, and its errors with it. */
function metrics(serviceId: string): MetricPoint[] {
  const index = SERVICES.findIndex((one) => one.id === serviceId);
  const service = SERVICES[index];
  if (service === undefined) throw new Error(`No service "${serviceId}".`);
  const r = random(1000 + index * 37);
  const points: MetricPoint[] = [];
  let drift = 0;
  for (let t = at(17, 0); t <= NOW; t += 5 * MINUTE) {
    const hour = (t - at(17, 0)) / (60 * MINUTE);
    const load = 0.35 + 0.65 * Math.max(0, Math.sin((Math.PI * (hour - 5)) / 16));
    drift = 0.8 * drift + (r() - 0.5) * 0.08;
    const base = service.latencySlo * (0.45 + 0.2 * load + drift);
    const surge = serviceId === "checkout" && t >= at(17, 9, 40) && t < at(17, 10, 10) ? 1.9 : 1;
    const p95 = Math.round(base * surge * (1 + r() * 0.08));
    points.push({
      t,
      p50: Math.round(p95 * (0.42 + r() * 0.06)),
      p95,
      errorRate: Math.round((0.05 + r() * 0.12 + (surge > 1 ? 2.4 + r() : 0)) * 100) / 100,
      requests: Math.round(VOLUME[service.tier] * load * (1 + (r() - 0.5) * 0.1)),
    });
  }
  return points;
}

interface Incident {
  id: string;
  title: string;
  service: string;
  severity: "SEV1" | "SEV2" | "SEV3";
  opened: number;
  acknowledged?: number;
  resolved?: number;
  /** An engineer's id. */
  assignee: string;
}

const INCIDENTS: readonly Incident[] = [
  { id: "INC-1048", title: "Checkout slow, card payments time out", service: "checkout", severity: "SEV1", opened: at(17, 9, 42), acknowledged: at(17, 9, 46), assignee: "jonas" },
  { id: "INC-1047", title: "Webhook deliveries delayed", service: "webhooks", severity: "SEV3", opened: at(17, 7, 15), acknowledged: at(17, 8, 2), assignee: "ines" },
  { id: "INC-1046", title: "Thumbnails missing for new uploads", service: "images", severity: "SEV2", opened: at(16, 22, 5), acknowledged: at(16, 22, 11), resolved: at(17, 0, 40), assignee: "tomasz" },
  { id: "INC-1045", title: "Sign-in codes arrive late", service: "sign-in", severity: "SEV2", opened: at(16, 14, 20), acknowledged: at(16, 14, 24), resolved: at(16, 15, 5), assignee: "ada" },
  { id: "INC-1044", title: "Monthly report export fails", service: "reports", severity: "SEV3", opened: at(15, 10, 0), acknowledged: at(16, 9, 12), resolved: at(16, 11, 30), assignee: "felix" },
  { id: "INC-1043", title: "Search returns no results for some regions", service: "search", severity: "SEV1", opened: at(14, 18, 30), acknowledged: at(14, 18, 33), resolved: at(14, 19, 55), assignee: "leila" },
  { id: "INC-1042", title: "Duplicate reminder e-mails", service: "notifications", severity: "SEV3", opened: at(13, 8, 45), acknowledged: at(13, 9, 30), resolved: at(13, 13, 0), assignee: "sam" },
  { id: "INC-1041", title: "Invoices generated twice", service: "billing", severity: "SEV2", opened: at(12, 16, 10), acknowledged: at(12, 16, 18), resolved: at(12, 18, 40), assignee: "priya" },
];

type Priority = "high" | "medium" | "low";

interface Alert {
  id: string;
  raised: number;
  priority: Priority;
  message: string;
  state: "Active" | "Resolved";
  acknowledgedAt?: number;
}

const TONE = { high: "danger", medium: "warning", low: "neutral" } as const;
const RANK = { high: 0, medium: 1, low: 2 } as const;

/** Worst first: by priority, then what nobody has acknowledged, then the newest. */
const WORST_FIRST = [
  { column: "priority", direction: "asc" },
  { column: "acknowledged", direction: "asc" },
  { column: "raised", direction: "desc" },
] as const;

/** The alerts as they stand at 10:30. */
const ALERTS: readonly Alert[] = [
  { id: "a-1", raised: at(17, 9, 41), priority: "high", message: "Checkout · p95 latency above 300 ms", state: "Active", acknowledgedAt: at(17, 9, 46) },
  { id: "a-2", raised: at(17, 9, 43), priority: "high", message: "Checkout · error rate above 2\u00a0%", state: "Resolved" },
];

const INCIDENT = INCIDENTS.find((one) => one.id === "INC-1048")!;
const SERVICE = SERVICES.find((one) => one.id === INCIDENT.service)!;
const nameOf = (id: string) => ENGINEERS.find((one) => one.id === id)?.name ?? id;
const time = (t: number) => new Date(t).toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" });

/* Who is on call right now: the rota hands over at 09:00. */
const onCall = (rotation: "primary" | "secondary") =>
  nameOf(ONCALL.find((one) => one.rotation === rotation && one.from <= NOW && NOW < one.to)!.engineer);

const LATENCY: LimitSet = {
  limits: [
    { value: SERVICE.latencySlo * 0.85, side: "upper", severity: "warning" },
    { value: SERVICE.latencySlo, side: "upper", severity: "alarm" },
  ],
};
const ERRORS: LimitSet = {
  limits: [
    { value: 1, side: "upper", severity: "warning" },
    { value: 2, side: "upper", severity: "alarm" },
  ],
};

/* From 08:00: enough before the incident to see what normal looks like. */
const TODAY = metrics(SERVICE.id).filter((one) => one.t >= NOW - 150 * 60_000);
const LATEST = TODAY[TODAY.length - 1]!;

const STEPS = [
  { label: "Detected", description: time(INCIDENT.opened) },
  { label: "Acknowledged", description: `${time(INCIDENT.acknowledged!)} by ${nameOf(INCIDENT.assignee)}` },
  { label: "Mitigated", description: "Rolled back the payment client, 10:08" },
  { label: "Resolved" },
];

function Content() {
  const { toast } = useToast();
  const { Chart, XAxis, YAxis, Line } = useChart(TODAY);
  const [alerts, setAlerts] = useState<readonly Alert[]>(ALERTS);
  const [resolved, setResolved] = useState<number | null>(null);
  const [resolving, setResolving] = useState(false);
  const [cause, setCause] = useState("");
  const [summary, setSummary] = useState("");
  const [tried, setTried] = useState(false);

  const t = useTable(alerts, { rowKey: (a) => a.id, defaultSort: WORST_FIRST });
  const { Table, Column } = t;

  const acknowledge = () => {
    setAlerts((before) => before.map((one) => (t.selection.selected.has(one.id) ? { ...one, acknowledgedAt: one.acknowledgedAt ?? NOW } : one)));
    t.selection.clear();
  };

  const resolve = () => {
    setTried(true);
    if (cause === "" || summary.trim() === "") return;
    setResolved(NOW);
    setResolving(false);
    toast({ title: `${INCIDENT.id} resolved`, description: "The status page and the incident channel have been told.", tone: "success" });
  };

  return (
    <Stack gap={4}>
      <Stack gap={2}>
        <Breadcrumb items={[{ label: "Incidents", href: "#/scenarios" }, { label: INCIDENT.id }]} />
        <Stack direction="row" gap={3} align="center" justify="space-between" wrap>
          <Stack direction="row" gap={2} align="center" wrap>
            <Badge tone="danger">{INCIDENT.severity}</Badge>
            <Heading level={2} size="lg">
              {INCIDENT.title}
            </Heading>
          </Stack>
          <Stack direction="row" gap={2}>
            <Menu
              align="end"
              trigger={
                <Button size="sm" variant="secondary">
                  More
                </Button>
              }
            >
              <MenuItem onSelect={() => toast({ title: `${onCall("secondary")} has been paged` })}>
                Page the secondary
              </MenuItem>
              <MenuItem onSelect={() => toast({ title: "Link to the incident copied" })}>Copy the link</MenuItem>
              <MenuSeparator />
              <MenuItem onSelect={() => toast({ title: "Raised to SEV1 already", tone: "warning" })}>
                Escalate
              </MenuItem>
            </Menu>
            <Button
              size="sm"
              variant="primary"
              data-callout="5"
              disabled={resolved !== null}
              onClick={() => setResolving(true)}
            >
              {resolved === null ? "Resolve" : "Resolved"}
            </Button>
          </Stack>
        </Stack>
        <TagGroup aria-label="Affected">
          <Tag>{SERVICE.name}</Tag>
          <Tag>Team {SERVICE.team}</Tag>
          <Tag>Tier {SERVICE.tier}</Tag>
        </TagGroup>
        <Text size="sm" tone="secondary">
          Assigned to {nameOf(INCIDENT.assignee)} · on call: {onCall("primary")}, secondary {onCall("secondary")}
        </Text>
      </Stack>

      <Stepper
        aria-label="Where the incident stands"
        data-callout="1"
        steps={STEPS.map((step, i) => (i === 3 && resolved !== null ? { ...step, description: time(resolved) } : step))}
        current={resolved === null ? 3 : 4}
      />

      <Grid minItemWidth="200px" gap={4} data-callout="2">
        <Stat
          label={`${SERVICE.name} · p95 latency`}
          value={LATEST.p95}
          unit="ms"
          decimals={0}
          limits={LATENCY}
          history={TODAY.map((one) => one.p95)}
        />
        <Stat
          label={`${SERVICE.name} · error rate`}
          value={LATEST.errorRate}
          unit="%"
          decimals={2}
          limits={ERRORS}
          history={TODAY.map((one) => one.errorRate)}
        />
        <Stat label="Requests" value={LATEST.requests} unit="/min" decimals={0} history={TODAY.map((one) => one.requests)} />
      </Grid>

      <Card data-callout="3">
        <CardHeader title="p95 latency since 08:00" />
        <CardBody>
          <Chart height={200} ariaLabel={`${SERVICE.name}, p95 latency since 08:00`}>
            <XAxis value="t" time />
            <YAxis domain={[0, 700]} label="ms" />
            <LimitLine value={SERVICE.latencySlo} severity="alarm" label="Objective" />
            <Line value="p95" name="p95" format={(v) => `${Math.round(v)} ms`} />
            <Tooltip mode="x" />
          </Chart>
        </CardBody>
      </Card>

      <Tabs defaultValue="alerts">
        <TabList aria-label="About the incident">
          <Tab value="alerts">Alerts</Tab>
          <Tab value="earlier">Earlier incidents</Tab>
        </TabList>
        <TabPanel value="alerts">
          <div data-callout="4">
            <Stack gap={2}>
              <Table selectable ariaLabel="Alerts of the incident">
                <Column value="raised" label="Raised">
                  {(raised) => time(raised)}
                </Column>
                <Column value="priority" label="Priority" sortValue={(priority) => RANK[priority]}>
                  {(priority) => <Badge tone={TONE[priority]}>{priority}</Badge>}
                </Column>
                <Column value="message" label="Alert" rowHeader />
                <Column value="state" label="State" />
                <Column id="acknowledged" label="Acknowledged" value={(a) => a.acknowledgedAt ?? 0}>
                  {(_, a) => (a.acknowledgedAt === undefined ? "No" : time(a.acknowledgedAt))}
                </Column>
              </Table>
              <div>
                <Button size="sm" disabled={t.selection.selected.size === 0} onClick={acknowledge}>
                  Acknowledge
                </Button>
              </div>
            </Stack>
          </div>
        </TabPanel>
        <TabPanel value="earlier">
          <Stack gap={2}>
            {INCIDENTS.filter((one) => one.resolved !== undefined).map((one) => (
              <Stack key={one.id} direction="row" gap={3} align="center">
                <Badge tone={one.severity === "SEV1" ? "danger" : one.severity === "SEV2" ? "warning" : "neutral"}>
                  {one.severity}
                </Badge>
                <Text size="sm" mono>
                  {one.id}
                </Text>
                <Text size="sm">{one.title}</Text>
              </Stack>
            ))}
          </Stack>
        </TabPanel>
      </Tabs>

      <Modal open={resolving} onClose={() => setResolving(false)}>
        <ModalHeader title={`Resolve ${INCIDENT.id}`} description="The summary goes to the status page and starts the review." />
        <ModalBody>
          <Stack gap={4}>
            <FormField label="Cause" required error={tried && cause === "" ? "Choose what caused it." : undefined}>
              <Select value={cause} onChange={(event) => setCause(event.target.value)}>
                <option value="" disabled>
                  Choose a cause
                </option>
                <option value="deploy">A deploy</option>
                <option value="dependency">A dependency</option>
                <option value="capacity">Capacity</option>
                <option value="config">A configuration change</option>
              </Select>
            </FormField>
            <FormField
              label="Summary"
              required
              error={tried && summary.trim() === "" ? "Say in a sentence what happened." : undefined}
            >
              <Textarea
                autoGrow
                maxRows={6}
                value={summary}
                onChange={(event) => setSummary(event.target.value)}
                placeholder="What happened, and what brought it back"
              />
            </FormField>
            <Checkbox label="Post to the status page" defaultChecked />
          </Stack>
        </ModalBody>
        <ModalFooter>
          <Button onClick={() => setResolving(false)}>Cancel</Button>
          <Button variant="primary" onClick={resolve}>
            Resolve
          </Button>
        </ModalFooter>
      </Modal>
    </Stack>
  );
}

/* `useToast` needs a `ToastProvider` above it; at the root of an application
   one provider serves every screen. */
export default function IncidentConsole() {
  return (
    <ToastProvider>
      <Content />
    </ToastProvider>
  );
}
```

### Dispatch a tour

A dispatcher at Ferrow Parcel puts together an afternoon tour for the parcels that could not be delivered this morning, and sends it out.

1. The depots and their vehicles stand in a tree; each vehicle says when it is back from its morning tour.
2. The driver list holds only the chosen vehicle's depot, and typing narrows it.
3. The parcels start with the morning's failed attempts; more can be added from the depot's open deliveries.
4. The payload bar turns amber past 90 per cent and red past the vehicle's capacity, with the weight beside it.
5. A departure before the vehicle is back and loaded is named in words, and the tour cannot be sent until it is resolved.

Built from: TreeView, Card, FormField, Combobox, DateTimePicker, MultiSelect, NumberInput, Meter, Switch, Alert, Toast.

```tsx
import { useState } from "react";
import {
  Alert,
  Button,
  Card,
  CardBody,
  CardHeader,
  Combobox,
  DateTimePicker,
  FormField,
  Grid,
  Meter,
  MultiSelect,
  NumberInput,
  Stack,
  Switch,
  Text,
  TreeView,
  useToast,
  useTree,
} from "@umriss-ui/core";
import type { NodeReader } from "@umriss-ui/core";

/* Data from the logistics world, written out here so the example runs on its own. */

/** A small LCG - the same numbers on every computer. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

const at = (hours: number, minutes = 0) => new Date(2026, 2, 17, hours, minutes).getTime();
const MINUTE = 60_000;

/** Tuesday, 17 March 2026, 10:30 - the moment the screens are read at. */
const NOW = at(10, 30);

const DEPOTS = [
  { id: "north", name: "North depot" },
  { id: "river", name: "Riverside depot" },
  { id: "east", name: "East Gate depot" },
] as const;

interface Vehicle {
  id: string;
  plate: string;
  type: "van" | "e-van" | "truck";
  /** Payload, in kg. */
  capacity: number;
  depot: string;
}

const VEHICLES: readonly Vehicle[] = [
  { id: "v1", plate: "FP 214 K", type: "van", capacity: 1200, depot: "north" },
  { id: "v2", plate: "FP 377 K", type: "e-van", capacity: 900, depot: "north" },
  { id: "v3", plate: "FP 118 R", type: "truck", capacity: 7500, depot: "north" },
  { id: "v4", plate: "FP 402 R", type: "van", capacity: 1200, depot: "river" },
  { id: "v5", plate: "FP 455 R", type: "e-van", capacity: 900, depot: "river" },
  { id: "v6", plate: "FP 290 E", type: "van", capacity: 1200, depot: "east" },
  { id: "v7", plate: "FP 311 E", type: "e-van", capacity: 900, depot: "east" },
  { id: "v8", plate: "FP 520 E", type: "truck", capacity: 7500, depot: "east" },
];

const DRIVERS = [
  { id: "d1", name: "Martin Hale", depot: "north" },
  { id: "d2", name: "Nadia Petrova", depot: "north" },
  { id: "d3", name: "Owen Carter", depot: "north" },
  { id: "d4", name: "Lucia Romero", depot: "river" },
  { id: "d5", name: "Ben Adeyemi", depot: "river" },
  { id: "d6", name: "Hanna Berg", depot: "east" },
  { id: "d7", name: "Yusuf Demir", depot: "east" },
  { id: "d8", name: "Clara Wendt", depot: "east" },
] as const;

const CUSTOMERS = [
  "Holloway Garden Supplies",
  "Marlow & Finch Books",
  "Oakridge Pharmacy",
  "Brixley Cycles",
  "Tamsin's Bakery",
  "Northfold Office",
  "Pellham Hardware",
  "Greywick Studio",
  "Juniper Lane Florist",
  "Ashcombe Dental",
] as const;

interface Stop {
  id: string;
  shipment: string;
  customer: string;
  /** The window the customer was promised, `[from, to]`. */
  window: readonly [number, number];
  /** When the tour plans to be there. */
  arrival: number;
}

interface Tour {
  id: string;
  vehicle: string;
  driver: string;
  depot: string;
  /** Leaves the depot, loaded; back at the depot. */
  from: number;
  to: number;
  /** Minutes of loading before `from`. */
  loading: number;
  km: number;
  stops: readonly Stop[];
}

/** One tour per vehicle. Stops every half hour or so, each with a two-hour
    window; every seventh arrival misses its window - the late ones a
    dispatcher looks for. */
function tour(index: number): Tour {
  const r = random(700 + index);
  const vehicle = VEHICLES[index]!;
  const truck = vehicle.type === "truck";
  const from = at(truck ? 6 : 7, index % 2 === 0 ? 0 : 30);
  const count = truck ? 5 : 8 + Math.floor(r() * 4);
  const stops: Stop[] = [];
  let arrival = from + (20 + Math.floor(r() * 15)) * MINUTE;
  for (let i = 0; i < count; i++) {
    const n = index * 20 + i;
    const slot = Math.floor((arrival - at(0)) / (2 * 60 * MINUTE)) * 2;
    /* A late stop's window closed half an hour or more before the arrival. */
    const late = i >= 2 && n % 7 === 3;
    const halfHour = 30 * MINUTE;
    const windowFrom = late ? Math.floor(arrival / halfHour) * halfHour - 5 * halfHour : at(slot);
    stops.push({
      id: `s-${index + 1}-${i + 1}`,
      shipment: `FP-${(1_004_210 + n * 13).toString()}`,
      customer: CUSTOMERS[(n * 3) % CUSTOMERS.length]!,
      window: [windowFrom, windowFrom + 2 * 60 * MINUTE],
      arrival,
    });
    arrival += (truck ? 45 : 22) * MINUTE + Math.floor(r() * 18) * MINUTE;
  }
  return {
    id: `T-${String(index + 1).padStart(2, "0")}`,
    vehicle: vehicle.id,
    driver: DRIVERS[index]!.id,
    depot: vehicle.depot,
    from,
    to: arrival + 30 * MINUTE,
    loading: truck ? 45 : 30,
    km: Math.round((truck ? 140 : 70) + r() * 40),
    stops,
  };
}

const TOURS: readonly Tour[] = VEHICLES.map((_, index) => tour(index));

interface Shipment {
  id: string;
  customer: string;
  /** In kg. */
  weight: number;
  status: "delivered" | "out for delivery" | "failed attempt";
  window: readonly [number, number];
  tour: string;
}

/** One shipment per stop. Before now, delivered - or a failed attempt, where
    nobody was in; after now, out for delivery. */
const SHIPMENTS: readonly Shipment[] = TOURS.flatMap((one) =>
  one.stops.map((stop) => {
    const n = Number(stop.shipment.slice(3));
    return {
      id: stop.shipment,
      customer: stop.customer,
      weight: Math.round((VEHICLES.find((v) => v.id === one.vehicle)!.type === "truck" ? 180 : 2) + ((n * 7919) % 230) / 10),
      status: stop.arrival > NOW ? "out for delivery" : n % 11 === 0 ? "failed attempt" : "delivered",
      window: stop.window,
      tour: one.id,
    } satisfies Shipment;
  }),
);

const time = (t: number) => new Date(t).toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" });
const kg = (n: number) => `${n.toLocaleString("en-GB")} kg`;

interface Place {
  id: string;
  name: string;
  children?: Place[];
}

/* Depot above its vehicles. A vehicle's line says what it is and when it is
   free again. */
const FLEET: Place[] = DEPOTS.map((depot) => ({
  id: depot.id,
  name: depot.name,
  children: VEHICLES.filter((one) => one.depot === depot.id).map((one) => {
    const back = TOURS.find((tour) => tour.vehicle === one.id)!.to;
    return { id: one.id, name: `${one.plate} · ${one.type}, back ${time(back)}` };
  }),
}));

const READER: NodeReader<Place> = {
  key: (node) => node.id,
  children: (node) => node.children,
  label: (node) => node.name,
};

const tourOf = (shipment: string) => TOURS.find((one) => one.id === SHIPMENTS.find((s) => s.id === shipment)!.tour)!;

/* This morning's failed attempts at a depot: where an afternoon tour starts. */
const failedAt = (depot: string | undefined) =>
  SHIPMENTS.filter((one) => one.status === "failed attempt" && tourOf(one.id).depot === depot).map((one) => one.id);

function Content() {
  const { toast } = useToast();
  const [vehicleId, setVehicleId] = useState<string | null>("v2");
  const [driver, setDriver] = useState<string | null>(null);
  const [departure, setDeparture] = useState<Date | null>(new Date(2026, 2, 17, 14, 0));
  const [loading, setLoading] = useState<number | null>(30);
  const [notify, setNotify] = useState(true);
  const [sent, setSent] = useState(false);

  const vehicle = VEHICLES.find((one) => one.id === vehicleId);
  const depot = vehicle?.depot;

  /* The depot's parcels that are still to go: the failed attempts first,
     then what is out on the morning tours. */
  const open = SHIPMENTS.filter((one) => one.status !== "delivered" && tourOf(one.id).depot === depot).sort(
    (a, b) => Number(b.status === "failed attempt") - Number(a.status === "failed attempt"),
  );
  const [parcels, setParcels] = useState<string[]>(() => failedAt("north"));

  const tree = useTree(FLEET, {
    reader: READER,
    defaultExpanded: DEPOTS.map((one) => one.id),
    active: vehicleId,
    onActive: (next) => {
      /* A depot is a heading, not a vehicle. */
      if (next === null || VEHICLES.some((one) => one.id === next)) {
        const nextDepot = VEHICLES.find((one) => one.id === next)?.depot;
        if (nextDepot !== depot) {
          setDriver(null);
          setParcels(failedAt(nextDepot));
        }
        setVehicleId(next);
        setSent(false);
      }
    },
  });

  const weight = parcels.reduce((sum, id) => sum + SHIPMENTS.find((one) => one.id === id)!.weight, 0);
  const load = vehicle === undefined ? 0 : weight / vehicle.capacity;
  const back = vehicle === undefined ? null : TOURS.find((one) => one.vehicle === vehicle.id)!.to;
  const ready = back === null ? null : back + (loading ?? 0) * MINUTE;
  const tooEarly = departure !== null && ready !== null && departure.getTime() < ready;
  const complete = vehicle !== undefined && driver !== null && departure !== null && parcels.length > 0;

  const dispatch = () => {
    setSent(true);
    toast({
      title: `Tour sent with ${vehicle!.plate}`,
      description: `${parcels.length} parcels, leaving ${time(departure!.getTime())}${notify ? "; customers get their new window by text" : ""}.`,
      tone: "success",
    });
  };

  return (
    <Stack direction="row" gap={4} align="flex-start" wrap>
      <Card style={{ flex: "1 1 240px", maxWidth: 320 }}>
        <CardHeader title="Fleet" />
        <CardBody>
          <div data-callout="1">
            <TreeView tree={tree} ariaLabel="Depots and vehicles">
              {(entry) => entry.node.name}
            </TreeView>
          </div>
        </CardBody>
      </Card>

      <Card style={{ flex: "3 1 420px" }}>
        <CardHeader
          title="Afternoon tour"
          actions={
            <Button variant="primary" size="sm" disabled={!complete || tooEarly || sent} onClick={dispatch}>
              {sent ? "Sent" : "Send the tour"}
            </Button>
          }
        />
        <CardBody>
          <Stack gap={4}>
            <Grid minItemWidth="220px" gap={4}>
              <FormField label="Vehicle">
                <Text size="sm">{vehicle === undefined ? "Choose one in the fleet" : `${vehicle.plate} · ${vehicle.type}, ${kg(vehicle.capacity)}`}</Text>
              </FormField>
              <FormField label="Driver" required data-callout="2">
                <Combobox
                  value={driver}
                  onChange={setDriver}
                  clearable
                  disabled={vehicle === undefined}
                  placeholder="Type a name"
                  options={DRIVERS.filter((one) => one.depot === depot).map((one) => ({ value: one.id, label: one.name }))}
                />
              </FormField>
              <FormField label="Departure" required>
                <DateTimePicker value={departure} onChange={setDeparture} />
              </FormField>
              <FormField label="Loading" hint="Minutes at the depot before departure.">
                <NumberInput value={loading} onChange={setLoading} min={0} step={5} decimals={0} suffix="min" />
              </FormField>
            </Grid>

            <FormField label="Parcels" hint="Failed attempts first, then the depot's open deliveries." data-callout="3">
              <MultiSelect
                value={parcels}
                onChange={setParcels}
                placeholder="Choose parcels"
                disabled={vehicle === undefined}
                options={open.map((one) => ({
                  value: one.id,
                  label: `${one.id} · ${one.customer}, ${kg(one.weight)}${one.status === "failed attempt" ? " (failed attempt)" : ""}`,
                }))}
              />
            </FormField>

            <Stack gap={1} data-callout="4">
              <Text size="xs" tone="muted">
                Payload: {kg(weight)} of {vehicle === undefined ? "-" : kg(vehicle.capacity)}
              </Text>
              <Meter
                value={load}
                tone={load > 1 ? "danger" : load > 0.9 ? "warning" : undefined}
                showLabel
                label="Payload against the vehicle's capacity"
              />
            </Stack>

            {tooEarly && (
              <div data-callout="5">
                <Alert tone="warning" title="The vehicle is not ready by then">
                  {vehicle!.plate} is back from its morning tour at {time(back!)} and needs {loading} minutes of loading: the
                  earliest departure is {time(ready!)}.
                </Alert>
              </div>
            )}

            <Switch label="Text customers their new delivery window" checked={notify} onChange={(event) => setNotify(event.target.checked)} />
          </Stack>
        </CardBody>
      </Card>
    </Stack>
  );
}

/* `useToast` needs a `ToastProvider` above it; at the root of an application
   one provider serves every screen. */
export default function DispatchATour() {
  return <Content />;
}
```

### Approve spending against a budget

The finance controller at Carrow & Lisle signs off incoming invoices, each read against what its cost centre has left for the quarter.

1. The queue holds the invoices waiting for finance; one still waiting for its cost centre stays visible but cannot be chosen.
2. The lines show quantity, price, discount and VAT, and add up to the totals below them.
3. The tiles read the quarter's spending against the budget, before and after this invoice, and say the verdict in a word.
4. The stepper shows who has signed and whose turn it is.
5. Approving asks once more, and says by how much the invoice takes the cost centre over its budget.
6. Rejecting needs a reason, which goes back to the cost centre's owner.

Built from: RadioGroup, Card, Badge, Stat, Stepper, ConfirmDialog, Modal, FormField, Textarea, Toast.

```tsx
import { useState } from "react";
import {
  Badge,
  Button,
  Card,
  CardBody,
  CardHeader,
  ConfirmDialog,
  FormField,
  Grid,
  Modal,
  ModalBody,
  ModalFooter,
  ModalHeader,
  RadioGroup,
  Stack,
  Stat,
  Stepper,
  Text,
  Textarea,
  ToastProvider,
  useToast,
} from "@umriss-ui/core";
import type { LimitSet } from "@umriss-ui/core";

/* Data from the controlling world, written out here so the example runs on its own. */
/** A small LCG - the same numbers on every computer. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

const on = (month: number, day: number) => new Date(2026, month - 1, day).getTime();

interface CostCentre {
  id: string;
  name: string;
  owner: string;
  /** The budget of one month. */
  monthlyBudget: number;
}

const COST_CENTRES: readonly CostCentre[] = [
  { id: "CC-1100", name: "Sales", owner: "Helen Marsh", monthlyBudget: 142_000 },
  { id: "CC-1200", name: "Marketing", owner: "Rafael Ortiz", monthlyBudget: 68_000 },
  { id: "CC-2100", name: "Engineering", owner: "Anika Sørensen", monthlyBudget: 188_000 },
  { id: "CC-2200", name: "Design", owner: "Paul Whitaker", monthlyBudget: 54_000 },
  { id: "CC-3100", name: "Customer service", owner: "Grace Obi", monthlyBudget: 61_000 },
  { id: "CC-4100", name: "Finance", owner: "Martina Vogel", monthlyBudget: 47_000 },
  { id: "CC-4200", name: "People", owner: "Daniel Frost", monthlyBudget: 39_000 },
  { id: "CC-4300", name: "IT", owner: "Kenji Arai", monthlyBudget: 83_000 },
  { id: "CC-4400", name: "Facilities", owner: "Olga Ivanova", monthlyBudget: 72_000 },
];

/** The year's months, as `"2026-01"` … `"2026-12"`. */
const MONTHS: readonly string[] = Array.from({ length: 12 }, (_, i) => `2026-${String(i + 1).padStart(2, "0")}`);

/** The months whose books are closed: they have an actual. */
const CLOSED_MONTHS = 2;

interface LedgerRow {
  costCentre: string;
  month: string;
  budget: number;
  /** `null` while the month is open. */
  actual: number | null;
  forecast: number;
}

/* Where a cost centre lands against its budget, as a factor: Marketing's
   spring campaign overspends, IT's delayed licences underspend. */
const TENDENCY: Readonly<Record<string, number>> = { "CC-1200": 1.14, "CC-4300": 0.88 };

/** Budget, actual and forecast of every cost centre in every month. */
const LEDGER: readonly LedgerRow[] = COST_CENTRES.flatMap((centre, c) => {
  const r = random(310 + c);
  const tendency = TENDENCY[centre.id] ?? 1;
  return MONTHS.map((month, m) => {
    /* December pays the bonuses, August is the quiet month. */
    const season = m === 11 ? 1.12 : m === 7 ? 0.9 : 1;
    const budget = Math.round(centre.monthlyBudget * season);
    const forecast = Math.round((budget * (tendency + (r() - 0.5) * 0.06)) / 100) * 100;
    const actual = m < CLOSED_MONTHS ? Math.round(forecast * (1 + (r() - 0.5) * 0.08)) : null;
    return { costCentre: centre.id, month, budget, actual, forecast };
  });
});

interface InvoiceLine {
  description: string;
  quantity: number;
  unitPrice: number;
  /** A fraction: 0.1 is ten per cent off. */
  discount: number;
  /** A fraction: 0.19 or 0.07, or 0 where no VAT is charged. */
  vatRate: number;
}

interface Invoice {
  id: string;
  supplier: string;
  costCentre: string;
  received: number;
  due: number;
  status: "awaiting approval" | "approved" | "paid" | "rejected";
  lines: readonly InvoiceLine[];
}

const INVOICES: readonly Invoice[] = [
  {
    id: "INV-26-0318", supplier: "Brandlow Office Supply", costCentre: "CC-4400", received: on(3, 16), due: on(4, 15), status: "awaiting approval",
    lines: [
      { description: "Desk lamps, LED", quantity: 24, unitPrice: 48.9, discount: 0.1, vatRate: 0.19 },
      { description: "Printer paper, box of 5 reams", quantity: 40, unitPrice: 21.5, discount: 0, vatRate: 0.19 },
      { description: "Delivery", quantity: 1, unitPrice: 35, discount: 0, vatRate: 0.19 },
    ],
  },
  {
    id: "INV-26-0317", supplier: "Kettering & Shaw Events", costCentre: "CC-1200", received: on(3, 13), due: on(4, 12), status: "awaiting approval",
    lines: [
      { description: "Trade fair stand, 3 days", quantity: 1, unitPrice: 12_400, discount: 0.05, vatRate: 0.19 },
      { description: "Catering, per guest", quantity: 180, unitPrice: 18.5, discount: 0, vatRate: 0.07 },
    ],
  },
  {
    id: "INV-26-0309", supplier: "Nimbrel Software", costCentre: "CC-4300", received: on(3, 9), due: on(4, 8), status: "approved",
    lines: [
      { description: "Design tool licences, annual", quantity: 12, unitPrice: 540, discount: 0.15, vatRate: 0.19 },
      { description: "Onboarding session", quantity: 2, unitPrice: 890, discount: 0, vatRate: 0.19 },
    ],
  },
  {
    id: "INV-26-0302", supplier: "Fenwright Legal", costCentre: "CC-4100", received: on(3, 2), due: on(3, 16), status: "paid",
    lines: [{ description: "Contract review, hours", quantity: 14.5, unitPrice: 260, discount: 0, vatRate: 0.19 }],
  },
  {
    id: "INV-26-0226", supplier: "Corrin Travel", costCentre: "CC-1100", received: on(2, 26), due: on(3, 12), status: "paid",
    lines: [
      { description: "Rail tickets, sales conference", quantity: 22, unitPrice: 139, discount: 0, vatRate: 0.07 },
      { description: "Hotel, nights", quantity: 44, unitPrice: 112, discount: 0.08, vatRate: 0.07 },
    ],
  },
  {
    id: "INV-26-0221", supplier: "Stellbrook Consulting", costCentre: "CC-2100", received: on(2, 21), due: on(3, 23), status: "rejected",
    lines: [{ description: "Architecture review, days", quantity: 6, unitPrice: 1450, discount: 0, vatRate: 0 }],
  },
];

interface Approval {
  invoice: string;
  step: "cost centre" | "finance";
  approver: string;
  decision: "approved" | "rejected" | "pending";
  at?: number;
  comment?: string;
}

/** Two signatures an invoice needs: its cost centre's owner, then finance. */
const APPROVALS: readonly Approval[] = [
  { invoice: "INV-26-0318", step: "cost centre", approver: "Olga Ivanova", decision: "pending" },
  { invoice: "INV-26-0317", step: "cost centre", approver: "Rafael Ortiz", decision: "approved", at: on(3, 16) },
  { invoice: "INV-26-0317", step: "finance", approver: "Martina Vogel", decision: "pending" },
  { invoice: "INV-26-0309", step: "cost centre", approver: "Kenji Arai", decision: "approved", at: on(3, 10) },
  { invoice: "INV-26-0309", step: "finance", approver: "Martina Vogel", decision: "approved", at: on(3, 11) },
  { invoice: "INV-26-0302", step: "cost centre", approver: "Martina Vogel", decision: "approved", at: on(3, 3) },
  { invoice: "INV-26-0302", step: "finance", approver: "Martina Vogel", decision: "approved", at: on(3, 3) },
  { invoice: "INV-26-0226", step: "cost centre", approver: "Helen Marsh", decision: "approved", at: on(2, 27) },
  { invoice: "INV-26-0226", step: "finance", approver: "Martina Vogel", decision: "approved", at: on(3, 2) },
  { invoice: "INV-26-0221", step: "cost centre", approver: "Anika Sørensen", decision: "rejected", at: on(2, 24), comment: "Not ordered - the review was cancelled in January." },
];

const ME = "Martina Vogel";
const QUARTER = ["2026-01", "2026-02", "2026-03"];

const euro = new Intl.NumberFormat("en-GB", { style: "currency", currency: "EUR" });
const day = (t: number) => new Date(t).toLocaleDateString("en-GB", { day: "numeric", month: "short" });

const net = (invoice: Invoice) =>
  invoice.lines.reduce((sum, line) => sum + line.quantity * line.unitPrice * (1 - line.discount), 0);
const vat = (invoice: Invoice) =>
  invoice.lines.reduce((sum, line) => sum + line.quantity * line.unitPrice * (1 - line.discount) * line.vatRate, 0);

/* The quarter so far: the closed months' actuals and March's forecast. */
function quarter(costCentre: string) {
  const rows = LEDGER.filter((row) => row.costCentre === costCentre && QUARTER.includes(row.month));
  return {
    budget: rows.reduce((sum, row) => sum + row.budget, 0),
    spent: rows.reduce((sum, row) => sum + (row.actual ?? row.forecast), 0),
  };
}

const AGAINST_BUDGET: LimitSet = {
  target: 100,
  limits: [
    { value: 100, side: "upper", severity: "warning" },
    { value: 110, side: "upper", severity: "alarm" },
  ],
};

const WAITING = INVOICES.filter((one) => one.status === "awaiting approval");

type Decision = "approved" | "rejected";

function Content() {
  const { toast } = useToast();
  const [chosen, setChosen] = useState("INV-26-0317");
  const [decisions, setDecisions] = useState<Readonly<Record<string, Decision>>>({});
  const [confirming, setConfirming] = useState(false);
  const [rejecting, setRejecting] = useState(false);
  const [reason, setReason] = useState("");
  const [tried, setTried] = useState(false);

  const invoice = INVOICES.find((one) => one.id === chosen)!;
  const centre = COST_CENTRES.find((one) => one.id === invoice.costCentre)!;
  const signatures = APPROVALS.filter((one) => one.invoice === invoice.id);
  const pending = signatures.find((one) => one.decision === "pending");
  const decided = decisions[invoice.id];
  const { budget, spent } = quarter(centre.id);
  const before = (spent / budget) * 100;
  const after = ((spent + net(invoice)) / budget) * 100;

  const decide = (decision: Decision) => {
    setDecisions((all) => ({ ...all, [invoice.id]: decision }));
    setConfirming(false);
    setRejecting(false);
    toast({
      title: `${invoice.id} ${decision}`,
      description: decision === "approved" ? "It goes to the next payment run." : `${centre.owner} has been told why.`,
      tone: decision === "approved" ? "success" : "neutral",
    });
  };

  const steps = [
    ...signatures.map((one) => ({
      label: one.step === "finance" ? "Finance" : "Cost centre",
      description: one.decision === "pending" ? (decided ? "You, today" : one.approver) : `${one.approver}, ${day(one.at!)}`,
      failed: one.decision === "rejected" || (one.decision === "pending" && decided === "rejected"),
    })),
    { label: "Payment", description: `Due ${day(invoice.due)}` },
  ];
  const current = decided === "approved" ? signatures.length : signatures.findIndex((one) => one.decision === "pending");

  return (
    <Stack direction="row" gap={4} align="flex-start" wrap>
      <Card style={{ flex: "1 1 240px", maxWidth: 340 }}>
        <CardHeader title="Waiting for finance" />
        <CardBody>
          <div data-callout="1">
            <RadioGroup
              aria-label="Invoices waiting for approval"
              value={chosen}
              onChange={setChosen}
              options={WAITING.map((one) => {
                const step = APPROVALS.find((a) => a.invoice === one.id && a.decision === "pending");
                const mine = step?.approver === ME;
                return {
                  value: one.id,
                  label: `${one.id} · ${one.supplier}`,
                  description: decisions[one.id]
                    ? `${decisions[one.id] === "approved" ? "Approved" : "Rejected"} by you`
                    : mine
                      ? `${euro.format(net(one))} net, due ${day(one.due)}`
                      : `Waiting for the cost centre, ${step?.approver}`,
                  disabled: !mine,
                };
              })}
            />
          </div>
        </CardBody>
      </Card>

      <Card style={{ flex: "3 1 420px" }}>
        <CardHeader
          eyebrow={`${centre.name} · ${centre.id}`}
          title={
            <Stack direction="row" gap={2} align="center">
              {invoice.supplier}
              {decided && <Badge tone={decided === "approved" ? "success" : "danger"}>{decided === "approved" ? "Approved" : "Rejected"}</Badge>}
            </Stack>
          }
          actions={
            <Stack direction="row" gap={2}>
              <Button size="sm" variant="secondary" data-callout="6" disabled={decided !== undefined || pending?.approver !== ME} onClick={() => setRejecting(true)}>
                Reject
              </Button>
              <Button size="sm" variant="primary" data-callout="5" disabled={decided !== undefined || pending?.approver !== ME} onClick={() => setConfirming(true)}>
                Approve
              </Button>
            </Stack>
          }
        />
        <CardBody>
          <Stack gap={4}>
            <Stepper aria-label="Signatures" data-callout="4" steps={steps} current={current} />

            <div data-callout="2" style={{ overflowX: "auto" }}>
              <table style={{ width: "100%", borderCollapse: "collapse", fontSize: "var(--u-text-sm)" }}>
                <thead>
                  <tr style={{ textAlign: "left", color: "var(--u-color-text-secondary)" }}>
                    <th style={{ fontWeight: 500, padding: "4px 8px 4px 0" }}>Line</th>
                    <th style={{ fontWeight: 500, padding: "4px 8px", textAlign: "right" }}>Qty</th>
                    <th style={{ fontWeight: 500, padding: "4px 8px", textAlign: "right" }}>Unit price</th>
                    <th style={{ fontWeight: 500, padding: "4px 8px", textAlign: "right" }}>Discount</th>
                    <th style={{ fontWeight: 500, padding: "4px 8px", textAlign: "right" }}>VAT</th>
                    <th style={{ fontWeight: 500, padding: "4px 0 4px 8px", textAlign: "right" }}>Net</th>
                  </tr>
                </thead>
                <tbody style={{ fontVariantNumeric: "tabular-nums" }}>
                  {invoice.lines.map((line) => (
                    <tr key={line.description} style={{ borderTop: "1px solid var(--u-hairline-strong)" }}>
                      <td style={{ padding: "6px 8px 6px 0" }}>{line.description}</td>
                      <td style={{ padding: "6px 8px", textAlign: "right" }}>{line.quantity}</td>
                      <td style={{ padding: "6px 8px", textAlign: "right" }}>{euro.format(line.unitPrice)}</td>
                      <td style={{ padding: "6px 8px", textAlign: "right" }}>{line.discount === 0 ? "-" : `${Math.round(line.discount * 100)}\u00a0%`}</td>
                      <td style={{ padding: "6px 8px", textAlign: "right" }}>{`${Math.round(line.vatRate * 100)}\u00a0%`}</td>
                      <td style={{ padding: "6px 0 6px 8px", textAlign: "right" }}>
                        {euro.format(line.quantity * line.unitPrice * (1 - line.discount))}
                      </td>
                    </tr>
                  ))}
                </tbody>
              </table>
              <Stack gap={1} align="flex-end" style={{ marginTop: 8 }}>
                <Text size="sm" tone="secondary">
                  Net {euro.format(net(invoice))} · VAT {euro.format(vat(invoice))}
                </Text>
                <Text weight="semibold">Total {euro.format(net(invoice) + vat(invoice))}</Text>
              </Stack>
            </div>

            <Grid minItemWidth="180px" gap={4} data-callout="3">
              <Stat label={`${centre.name} · Q1 so far`} value={before} unit="% of budget" decimals={1} limits={AGAINST_BUDGET} />
              <Stat label="With this invoice" value={after} unit="% of budget" decimals={1} limits={AGAINST_BUDGET} />
              <Stat label="Q1 budget" value={budget} unit="€" decimals={0} />
            </Grid>
          </Stack>
        </CardBody>
      </Card>

      <ConfirmDialog
        open={confirming}
        onClose={() => setConfirming(false)}
        onConfirm={() => decide("approved")}
        title={after > 100 ? `Approve ${invoice.id} over budget?` : `Approve ${invoice.id}?`}
        description={
          after > 100
            ? `${centre.name} stands at ${before.toFixed(1)} % of its first-quarter budget; this invoice takes it to ${after.toFixed(1)} %, ${euro.format(spent + net(invoice) - budget)} over.`
            : `${euro.format(net(invoice) + vat(invoice))} goes to the next payment run.`
        }
        confirmLabel="Approve"
      />

      <Modal open={rejecting} onClose={() => setRejecting(false)} size="sm">
        <ModalHeader title={`Reject ${invoice.id}`} description={`The reason goes to ${centre.owner}, who owns ${centre.name}.`} />
        <ModalBody>
          <FormField label="Reason" required error={tried && reason.trim() === "" ? "Say why, so the owner can act on it." : undefined}>
            <Textarea autoGrow maxRows={6} value={reason} onChange={(event) => setReason(event.target.value)} />
          </FormField>
        </ModalBody>
        <ModalFooter>
          <Button onClick={() => setRejecting(false)}>Cancel</Button>
          <Button
            variant="danger"
            onClick={() => {
              setTried(true);
              if (reason.trim() !== "") decide("rejected");
            }}
          >
            Reject
          </Button>
        </ModalFooter>
      </Modal>
    </Stack>
  );
}

/* `useToast` needs a `ToastProvider` above it; at the root of an application
   one provider serves every screen. */
export default function ApproveSpending() {
  return (
    <ToastProvider>
      <Content />
    </ToastProvider>
  );
}
```

### Set up a team

A team lead at Tidewell keeps the team's settings here: who is in it and for how many hours, how sprints run, and who hears about what.

1. The trail above says whose settings these are, and leads back to the other teams.
2. Each member's role and weekly hours are edited in place, and the team's total follows.
3. Removing someone asks once, and names what happens to their planned work.
4. The focus factor turns the team's hours into the hours a sprint can plan with, and says the result beside it.
5. The save bar says how many changes are not saved yet; Save and Discard act only then, and saving is confirmed by a toast.

Built from: Breadcrumb, Card, Select, NumberInput, Combobox, ConfirmDialog, RadioGroup, DatePicker, Checkbox, Slider, Switch, Toast.

```tsx
import { useState } from "react";
import {
  Breadcrumb,
  Button,
  Card,
  CardBody,
  CardHeader,
  Checkbox,
  Combobox,
  ConfirmDialog,
  DatePicker,
  FormField,
  Grid,
  Heading,
  NumberInput,
  RadioGroup,
  Select,
  Slider,
  Stack,
  Switch,
  Text,
  ToastProvider,
  useToast,
} from "@umriss-ui/core";

/* Data from the planning world, written out here so the example runs on its own. */
const at = (day: number, hours = 9, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();

interface Person {
  id: string;
  name: string;
  role: "Developer" | "Designer" | "Product manager" | "QA engineer";
  team: "Web" | "Apps";
  /** Hours a week they can be planned for. */
  capacity: number;
}

const PEOPLE: readonly Person[] = [
  { id: "maya", name: "Maya Lindgren", role: "Product manager", team: "Web", capacity: 32 },
  { id: "arjun", name: "Arjun Mehta", role: "Developer", team: "Web", capacity: 40 },
  { id: "chloe", name: "Chloe Durand", role: "Developer", team: "Web", capacity: 40 },
  { id: "noah", name: "Noah Fischer", role: "Designer", team: "Web", capacity: 24 },
  { id: "eva", name: "Eva Novak", role: "QA engineer", team: "Web", capacity: 40 },
  { id: "luis", name: "Luis Moreno", role: "Product manager", team: "Apps", capacity: 40 },
  { id: "hana", name: "Hana Sato", role: "Developer", team: "Apps", capacity: 40 },
  { id: "kofi", name: "Kofi Mensah", role: "Developer", team: "Apps", capacity: 32 },
  { id: "freya", name: "Freya Olsen", role: "Designer", team: "Apps", capacity: 40 },
  { id: "david", name: "David Kowalski", role: "QA engineer", team: "Apps", capacity: 20 },
];

interface Sprint {
  id: string;
  name: string;
  from: number;
  to: number;
  goal: string;
}

/** Two weeks each, Monday 09:00 to the second Friday 17:00. */
const SPRINTS: readonly Sprint[] = [
  { name: "Sprint 12", day: 9 - 28, goal: "Shop checkout on the new design" },
  { name: "Sprint 13", day: 9 - 14, goal: "Booking app in the stores' beta" },
  { name: "Sprint 14", day: 9, goal: "Member portal sign-in and profile" },
  { name: "Sprint 15", day: 23, goal: "Shop search and filters" },
  { name: "Sprint 16", day: 37, goal: "Booking reminders" },
].map(({ name, day, goal }) => ({ id: name.toLowerCase().replace(" ", "-"), name, from: at(day), to: at(day + 11, 17), goal }));

type Role = Person["role"];
type Member = Pick<Person, "id" | "name" | "role" | "capacity">;

const ROLES: readonly Role[] = ["Developer", "Designer", "Product manager", "QA engineer"];
const DAYS = ["Mon", "Tue", "Wed", "Thu", "Fri"] as const;
const NEXT = SPRINTS.find((one) => one.name === "Sprint 15")!;

interface Settings {
  members: readonly Member[];
  length: "1" | "2" | "3";
  start: number;
  days: readonly string[];
  focus: number;
  notify: { review: boolean; overbooked: boolean; leave: boolean };
}

const INITIAL: Settings = {
  members: PEOPLE.filter((one) => one.team === "Web").map(({ id, name, role, capacity }) => ({ id, name, role, capacity })),
  length: "2",
  start: NEXT.from,
  days: DAYS,
  focus: 70,
  notify: { review: true, overbooked: true, leave: false },
};

/* How many settings differ from the saved ones - what the save bar says. */
function changes(a: Settings, b: Settings): number {
  const keys = ["length", "start", "days", "focus", "notify"] as const;
  const members = new Set([...a.members, ...b.members].map((one) => one.id));
  const memberChanges = [...members].filter(
    (id) => JSON.stringify(a.members.find((m) => m.id === id)) !== JSON.stringify(b.members.find((m) => m.id === id)),
  ).length;
  return memberChanges + keys.filter((key) => JSON.stringify(a[key]) !== JSON.stringify(b[key])).length;
}

function Content() {
  const { toast } = useToast();
  const [saved, setSaved] = useState(INITIAL);
  const [draft, setDraft] = useState(INITIAL);
  const [removing, setRemoving] = useState<Member | null>(null);

  const set = <K extends keyof Settings>(key: K, value: Settings[K]) => setDraft((d) => ({ ...d, [key]: value }));
  const setMember = (id: string, patch: Partial<Member>) =>
    set("members", draft.members.map((one) => (one.id === id ? { ...one, ...patch } : one)));

  const hours = draft.members.reduce((sum, one) => sum + one.capacity, 0);
  const weeks = Number(draft.length);
  const plannable = Math.round((hours * weeks * draft.focus * draft.days.length) / 100 / 5);
  const pending = changes(saved, draft);
  const outside = PEOPLE.filter((one) => !draft.members.some((m) => m.id === one.id));

  return (
    <Stack gap={4}>
      <Stack gap={1} data-callout="1">
        <Breadcrumb items={[{ label: "Settings", href: "#/scenarios" }, { label: "Teams", href: "#/scenarios" }, { label: "Web" }]} />
        <Heading level={2} size="lg">
          Team Web
        </Heading>
      </Stack>

      <Card>
        <CardHeader title="Members" />
        <CardBody>
          {/* One row a person, which wraps on a narrow screen: the name above,
              role and then hours and Remove beneath it - a grid of four columns had
              scrolled its last two out of sight on a phone. */}
          <Text size="xs" tone="muted">
            Role and hours a week, per person
          </Text>
          <Stack gap={2} style={{ marginTop: "var(--u-space-2)" }}>
            {draft.members.map((one, i) => (
              <Stack key={one.id} direction="row" gap={3} align="center" wrap>
                <Text size="sm" style={{ flex: "1 1 8rem" }}>
                  {one.name}
                </Text>
                <Stack direction="row" gap={3} align="center" wrap style={{ flex: "1 1 18rem" }}>
                  <div style={{ flex: "1 1 10rem", minWidth: 0 }}>
                    <Select
                      size="sm"
                      aria-label={`Role of ${one.name}`}
                      data-callout={i === 0 ? "2" : undefined}
                      value={one.role}
                      onChange={(event) => setMember(one.id, { role: event.target.value as Role })}
                    >
                      {ROLES.map((role) => (
                        <option key={role} value={role}>
                          {role}
                        </option>
                      ))}
                    </Select>
                  </div>
                  <div style={{ flex: "none", width: "7.5rem" }}>
                    <NumberInput
                      size="sm"
                      aria-label={`Hours a week of ${one.name}`}
                      value={one.capacity}
                      onChange={(value) => setMember(one.id, { capacity: value ?? 0 })}
                      min={0}
                      max={40}
                      decimals={0}
                      suffix="h"
                    />
                  </div>
                  <Button size="sm" variant="ghost" data-callout={i === 0 ? "3" : undefined} onClick={() => setRemoving(one)}>
                    Remove
                  </Button>
                </Stack>
              </Stack>
            ))}
          </Stack>
          <Stack direction="row" gap={3} align="flex-end" justify="space-between" wrap style={{ marginTop: "var(--u-space-4)" }}>
            <FormField label="Add someone" style={{ flex: "0 1 280px" }}>
              <Combobox
                value={null}
                onChange={(id) => {
                  const person = PEOPLE.find((one) => one.id === id);
                  if (person) set("members", [...draft.members, { id: person.id, name: person.name, role: person.role, capacity: person.capacity }]);
                }}
                placeholder="Type a name"
                options={outside.map((one) => ({ value: one.id, label: `${one.name} · ${one.team}` }))}
              />
            </FormField>
            <Text size="sm" tone="secondary">
              {draft.members.length} people · {hours} hours a week
            </Text>
          </Stack>
        </CardBody>
      </Card>

      <Card>
        <CardHeader title="Sprints" />
        <CardBody>
          <Grid minItemWidth="260px" gap={5}>
            <FormField label="Sprint length">
              <RadioGroup
                value={draft.length}
                onChange={(value) => set("length", value)}
                options={[
                  { value: "1", label: "One week" },
                  { value: "2", label: "Two weeks", description: "Planning on the first Monday, review on the second Friday." },
                  { value: "3", label: "Three weeks" },
                ]}
              />
            </FormField>
            <Stack gap={4}>
              <FormField label="Next sprint starts" hint={`${NEXT.name}: ${NEXT.goal}.`}>
                <DatePicker value={new Date(draft.start)} onChange={(date) => date && set("start", date.getTime())} />
              </FormField>
              <FormField label="Working days">
                <Stack direction="row" gap={3} wrap>
                  {DAYS.map((d) => (
                    <Checkbox
                      key={d}
                      label={d}
                      checked={draft.days.includes(d)}
                      onChange={(event) =>
                        set("days", event.target.checked ? DAYS.filter((x) => x === d || draft.days.includes(x)) : draft.days.filter((x) => x !== d))
                      }
                    />
                  ))}
                </Stack>
              </FormField>
              <FormField
                label="Focus factor"
                hint={`${plannable} of ${Math.round((hours * weeks * draft.days.length) / 5)} hours a sprint can be planned.`}
                data-callout="4"
              >
                <Slider
                  value={draft.focus}
                  onChange={(value) => set("focus", value)}
                  min={40}
                  max={100}
                  step={5}
                  showValue
                  format={(value) => `${value} %`}
                />
              </FormField>
            </Stack>
          </Grid>
        </CardBody>
      </Card>

      <Card>
        <CardHeader title="Notifications" />
        <CardBody>
          <Stack gap={3}>
            <Switch
              label="Tell the team when work waits for review"
              checked={draft.notify.review}
              onChange={(event) => set("notify", { ...draft.notify, review: event.target.checked })}
            />
            <Switch
              label="Tell me when someone is planned beyond their hours"
              checked={draft.notify.overbooked}
              onChange={(event) => set("notify", { ...draft.notify, overbooked: event.target.checked })}
            />
            <Switch
              label="Tell me when leave overlaps planned work"
              checked={draft.notify.leave}
              onChange={(event) => set("notify", { ...draft.notify, leave: event.target.checked })}
            />
          </Stack>
        </CardBody>
      </Card>

      <Card data-callout="5">
        <CardBody>
          <Stack direction="row" gap={3} align="center" justify="space-between" wrap>
            <Text size="sm" tone={pending === 0 ? "muted" : "default"}>
              {pending === 0 ? "All changes saved" : pending === 1 ? "One change not saved yet" : `${pending} changes not saved yet`}
            </Text>
            <Stack direction="row" gap={2}>
              <Button size="sm" variant="ghost" disabled={pending === 0} onClick={() => setDraft(saved)}>
                Discard
              </Button>
              <Button
                size="sm"
                variant="primary"
                disabled={pending === 0}
                onClick={() => {
                  setSaved(draft);
                  toast({ title: "Team Web saved", tone: "success" });
                }}
              >
                Save
              </Button>
            </Stack>
          </Stack>
        </CardBody>
      </Card>

      <ConfirmDialog
        open={removing !== null}
        onClose={() => setRemoving(null)}
        onConfirm={() => {
          set("members", draft.members.filter((one) => one.id !== removing!.id));
          setRemoving(null);
        }}
        tone="danger"
        title={`Remove ${removing?.name ?? ""} from Web?`}
        description="Their planned work stays on the plan without a person, until someone else takes it."
        confirmLabel="Remove"
      />
    </Stack>
  );
}

/* `useToast` needs a `ToastProvider` above it; at the root of an application
   one provider serves every screen. */
export default function SetUpATeam() {
  return (
    <ToastProvider>
      <Content />
    </ToastProvider>
  );
}
```

### Watch a kiln line over a shift

A line lead at Brenholt Tile Works keeps this control room open through the shift to see the kiln, its alarms, the plan and the OEE at once.

1. The shift runs a minute per second; Pause stops it, and under reduced motion it starts stopped. The skip links reach each region by keyboard.
2. The tile reads zone 3 against its limits and says the verdict in a word. The minute the kiln crosses its alarm limit is the same minute in the trend and in the alarm table.
3. The trend draws the limits the tile reads, and its table view holds every reading for a screen reader.
4. The alarm the kiln raised stands in the table; acknowledging it records who knew when and changes nothing else on the screen.
5. Choosing a batch in the plan and opening its details shows what the kiln has fired of it so far, in a drawer.
6. The OEE shows its working, down to the counts it is made of, so the scrap from the excursion can be traced back.

Built from: Stat, Card, ProgressBar, Drawer, Line, ControlChart, Table, Schedule, Calculation.

```tsx
import { useEffect, useMemo, useState } from "react";
import type { MouseEvent, ReactNode } from "react";
import {
  Badge,
  Button,
  Card,
  CardBody,
  CardHeader,
  Drawer,
  Grid,
  Link,
  ModalBody,
  ModalFooter,
  ModalHeader,
  ProgressBar,
  Stack,
  Stat,
  Text,
} from "@umriss-ui/core";
import type { FreshnessAges, LimitSet } from "@umriss-ui/core";
import { ControlChart, DataTable, LimitBand, LimitLine, Tooltip, useChart } from "@umriss-ui/charts";
import { useTable } from "@umriss-ui/table";
import { useSchedule } from "@umriss-ui/schedule";
import type { Subtask, Task } from "@umriss-ui/schedule";
import { Calculation, Difference, Given, Product, Quotient, Ref } from "@umriss-ui/calculation";

/* Data from the plant world, written out here so the example runs on its own. */

/** An alarm's dead band. */
interface ReturnBand {
  direction: "upper" | "lower";
  limit: number;
  returnTo: number;
}

/** A kind of alarm. */
interface AlarmType {
  id: string;
  label: string;
  priority: "high" | "medium" | "low";
}

/** One alarm. */
interface Alarm {
  id: string;
  type: string;
  lifecycle: "active-unacknowledged" | "active-acknowledged" | "resolved-unacknowledged" | "resolved-acknowledged";
  raised: number;
  resolved?: number;
  acknowledgedAt?: number;
  availability?: "in-service" | "suppressed" | "disabled";
}

/** A small LCG - reproducible across runs and platforms. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

/** The early shift, 06:00 to 14:00. */
const SHIFT_MINUTES = 480;

/** The kiln's zone 3, in °C: the numbers every part reads it against, once.
    Between the two warnings lies the tolerance - a tile fired outside it is
    scrap; `returnTo` is the alarm's dead band. */
const KILN = { target: 1200, tolerance: [1185, 1215], alarm: 1230, returnTo: 1222 } as const;

/** The same numbers as the limit set the tile and the verdict read. */
const KILN_LIMITS: LimitSet = {
  target: KILN.target,
  limits: [
    { value: KILN.tolerance[1], side: "upper", severity: "warning" },
    { value: KILN.alarm, side: "upper", severity: "alarm" },
    { value: KILN.tolerance[0], side: "lower", severity: "warning" },
  ],
};

/** The kiln fires one tile every quarter of a minute when nothing holds it up -
    the ideal cycle time of the OEE's performance. */
const IDEAL_CYCLE_MINUTES = 0.25;

/** The kiln alarm's condition and its dead band. */
const KILN_RETURN: ReturnBand = { direction: "upper", limit: KILN.alarm, returnTo: KILN.returnTo };

/** What the four measuring points of the line can report. */
const ALARM_TYPES: readonly AlarmType[] = [
  {
    id: "kiln-high",
    label: "Kiln K1 · zone 3 above alarm limit",
    priority: "high",
  },
  { id: "exit-silent", label: "Kiln K1 · exit pyrometer sends nothing", priority: "medium" },
  { id: "belt-empty", label: "Kiln K1 · belt empty", priority: "medium" },
  { id: "dryer-fan", label: "Dryer D1 · fan vibration high", priority: "low" },
];

/** One minute of the line. */
interface Reading {
  /** Minutes since the start of the shift. */
  minute: number;
  /** Zone 3 of the kiln, in °C. */
  kiln: number;
  /** The exit pyrometer, in °C - `null` while it sends nothing. */
  exit: number | null;
  /** Whether the belt runs. */
  running: boolean;
  /** Tiles out of the kiln in this minute. */
  fired: number;
  /** Of them, the ones fired inside the tolerance. */
  good: number;
}

/** A tile taken off the belt and measured - one every ten minutes while it runs. */
interface Sample {
  minute: number;
  /** The tile's length after firing, in mm (nominal 600). */
  length: number;
}

/** A batch of tiles through the three stations. */
interface Batch {
  id: string;
  name: string;
  /** How many tiles the batch is planned for. */
  tiles: number;
  /** Minutes since the start of the shift, per station. */
  press: readonly [number, number];
  dryer: readonly [number, number];
  kiln: readonly [number, number];
}

interface Plant {
  readings: readonly Reading[];
  samples: readonly Sample[];
  batches: readonly Batch[];
}

/* When the exit pyrometer goes silent, and for how long. Fixed rather than
   seeded, so that a running control room shows its reading turn stale, then
   lost, and come back. */
const SILENT_FROM = 288;
const SILENT_FOR = 50;

/* The dryer's vibration sensor is under maintenance all shift: its alarm is
   active and disabled. */
const DRYER_FAN_RAISED = 20;

/** The shift, from a seed. */
function plant(seed: number): Plant {
  const r = random(seed);

  /* The one excursion: a burner overshoots somewhere between 02:30 and 03:30
     into the shift, for half an hour, peaking near 1242 °C. The operator stops
     the feed twenty-two minutes in, for eighteen minutes. The noise around it
     is too small to reach a warning on its own, so this is the only crossing -
     which is what the tests hold. */
  const surgeFrom = 150 + Math.floor(r() * 60);
  const surgeFor = 30;
  const stopFrom = surgeFrom + 22;
  const stopFor = 18;

  /* The plan: batches through the kiln one after another, each pressed an
     hour and dried half an hour before - the first ones during the night
     shift. Tiles come out of the kiln only while a batch is in it, so the
     OEE's count and the batches' counts are the same tiles. The plan is a
     plan: a stop of the belt does not move it. */
  const batches: Batch[] = [];
  for (let at = 0, i = 0; at < SHIFT_MINUTES; i++) {
    const length = 70 + Math.floor(r() * 25);
    batches.push({
      id: `b-${4121 + i}`,
      name: `B-${4121 + i}`,
      tiles: Math.round(length / IDEAL_CYCLE_MINUTES / 10) * 10,
      press: [at - 60, at - 60 + length],
      dryer: [at - 30, at - 30 + length],
      kiln: [at, at + length],
    });
    at += length + 5;
  }

  const readings: Reading[] = [];
  const samples: Sample[] = [];
  let drift = 0;
  for (let minute = 0; minute < SHIFT_MINUTES; minute++) {
    drift = 0.9 * drift + (r() - 0.5) * 3;
    const into = minute - surgeFrom;
    const surge = into >= 0 && into <= surgeFor ? 42 * Math.sin((Math.PI * into) / surgeFor) : 0;
    const kiln = Math.round((KILN.target + drift + surge) * 10) / 10;

    const running = !(minute >= stopFrom && minute < stopFrom + stopFor);
    const loaded = batches.some((batch) => batch.kiln[0] <= minute && minute < batch.kiln[1]);
    const jam = r() < 0.12;
    const fired = running && loaded ? (jam ? 3 : 4) : 0;
    const inTolerance = kiln >= KILN.tolerance[0] && kiln <= KILN.tolerance[1];
    const silent = minute >= SILENT_FROM && minute < SILENT_FROM + SILENT_FOR;
    const exit = silent ? null : Math.round((kiln - 380 + (r() - 0.5) * 4) * 10) / 10;

    readings.push({ minute, kiln, exit, running, fired, good: inTolerance ? fired : 0 });

    if (running && minute % 10 === 0) {
      /* Hotter shrinks more: the length follows the kiln, so the control
         chart sees the excursion the trend sees. */
      const length = 600 + (KILN.target - kiln) * 0.05 + (r() - 0.5) * 0.6;
      samples.push({ minute, length: Math.round(length * 100) / 100 });
    }
  }

  return { readings, samples, batches };
}

/** The readings up to and including the minute. */
function upTo<T extends { minute: number }>(series: readonly T[], minute: number): readonly T[] {
  return series.filter((one) => one.minute <= minute);
}

/** How long ago the exit pyrometer last reported, in minutes - `0` while it
    reports. What the tile's freshness is told. */
function exitSilence(p: Plant, minute: number): number {
  for (let m = minute; m >= 0; m--) {
    if (p.readings[m]?.exit !== null) return minute - m;
  }
  return minute;
}

/** When a condition held, as spans of minutes: `[from, to)`, `to` absent while
    it still holds at the minute. */
function spans(
  readings: readonly Reading[],
  minute: number,
  raise: (one: Reading) => boolean,
  clear: (one: Reading) => boolean,
): { from: number; to?: number }[] {
  const found: { from: number; to?: number }[] = [];
  let open: { from: number; to?: number } | null = null;
  for (const one of readings) {
    if (one.minute > minute) break;
    if (open === null && raise(one)) {
      open = { from: one.minute };
      found.push(open);
    } else if (open !== null && clear(one)) {
      open.to = one.minute;
      open = null;
    }
  }
  return found;
}

/**
 * The alarms of the shift as they stand at the minute: raised, resolved - and
 * acknowledged where the operator did, at the instant he did.
 *
 * `start` is the instant the shift began; the alarms carry instants.
 * The dead band applies: an alarm clears only below `returnTo`, not merely
 * below the limit, or a reading riding on the limit would raise one a minute.
 */
function alarmsAt(
  p: Plant,
  minute: number,
  start: number,
  acknowledged: ReadonlyMap<string, number> = new Map(),
): Alarm[] {
  const instant = (m: number) => start + m * 60_000;
  const alarms: Alarm[] = [];

  const add = (
    type: string,
    span: { from: number; to?: number },
    extra: { availability?: "suppressed" | "disabled" } = {},
  ) => {
    alarms.push({
      id: `${type}-${span.from}`,
      type,
      lifecycle: span.to === undefined ? "active-unacknowledged" : "resolved-unacknowledged",
      raised: instant(span.from),
      ...(span.to === undefined ? {} : { resolved: instant(span.to) }),
      ...extra,
    });
  };

  for (const span of spans(p.readings, minute, (one) => one.kiln > KILN_RETURN.limit, (one) => one.kiln <= KILN_RETURN.returnTo)) {
    add("kiln-high", span);
  }
  for (const span of spans(p.readings, minute, (one) => one.exit === null, (one) => one.exit !== null)) {
    add("exit-silent", span);
  }
  /* The belt runs empty because the operator stopped the feed: the plant's
     logic knows it, so the alarm is suppressed - there, and neutral. */
  for (const span of spans(p.readings, minute, (one) => !one.running, (one) => one.running)) {
    add("belt-empty", span, { availability: "suppressed" });
  }
  if (minute >= DRYER_FAN_RAISED) {
    add("dryer-fan", { from: DRYER_FAN_RAISED }, { availability: "disabled" });
  }

  return alarms.map((alarm) => {
    const at = acknowledged.get(alarm.id);
    if (at === undefined) return alarm;
    const lifecycle = alarm.resolved === undefined ? "active-acknowledged" : "resolved-acknowledged";
    return { ...alarm, lifecycle, acknowledgedAt: at };
  });
}

/** The shift's figures for the OEE, up to and including the minute. */
interface ShiftCount {
  /** Minutes of the shift so far. */
  planned: number;
  /** Minutes the belt stood. */
  downtime: number;
  /** Tiles out of the kiln. */
  total: number;
  /** Of them, inside the tolerance. */
  good: number;
}

function countAt(p: Plant, minute: number): ShiftCount {
  const so = upTo(p.readings, minute);
  return {
    planned: so.length,
    downtime: so.filter((one) => !one.running).length,
    total: so.reduce((sum, one) => sum + one.fired, 0),
    good: so.reduce((sum, one) => sum + one.good, 0),
  };
}

/* Every package on one page, fed by one plant. The kiln's excursion is the
   line above the limit in the trend, the alarm in the list, the scrap in the
   OEE and the points the control chart marks - because each reads the same
   minute, and none is told about the others.

   The shift runs: one plant minute per second, from a few minutes after the
   kiln crossed its alarm limit, while the alarm stands. It stands still under
   `prefers-reduced-motion`, and Pause stops it for everybody else - a page
   that updates on its own for minutes owes its reader a way to stop it.
   The clock advances by what the wall clock says has passed, so a page whose
   clock is frozen (the screenshot suite freezes it) stands still there and
   is the same picture on every run.

   Every part keeps its own keyboard model; the page adds a landmark per
   region and a row of skip links to reach each one. */

const SHIFT = plant(17);
const CROSSING = SHIFT.readings.find((one) => one.kiln > KILN.alarm)!.minute;
const LAST = SHIFT_MINUTES - 1;
const SECOND = 1000;
const MIN = 60_000;
/* The shift begins at 06:00 today; everything below counts from there. */
const START = new Date(new Date().setHours(6, 0, 0, 0)).getTime();
const at = (minute: number) => START + minute * MIN;

const AGES: FreshnessAges = { stale: 5 * MIN, lost: 30 * MIN };

const OEE_TARGET = 0.85;

/* The OEE is read against its own rule: a target, and two limits below it. */
const OEE_LIMITS = {
  target: OEE_TARGET * 100,
  limits: [
    { value: 75, side: "lower", severity: "warning" },
    { value: 65, side: "lower", severity: "alarm" },
  ],
} as const;

/* The tile's length after firing is specified at 600 ± 1.5 mm; the control
   limits come out of the first two hours, when the kiln demonstrably ran in
   control. */
const REFERENCE = { kind: "referenceWindow", from: 0, to: 12 } as const;

const LANES = [
  { id: "press", label: "Press P1" },
  { id: "dryer", label: "Dryer D1" },
  { id: "kiln", label: "Kiln K1" },
] as const;

/* Batches are drawn in one neutral colour: they differ by name, not by a hue
   that would have to mean something (ISA-101). */
const TASKS: readonly Task[] = SHIFT.batches.map((batch) => ({
  id: batch.id,
  name: batch.name,
  color: "var(--u-color-text-secondary)",
}));

const STEPS: readonly Subtask[] = SHIFT.batches.flatMap((batch) =>
  LANES.map((lane) => ({
    id: `${batch.id}-${lane.id}`,
    task: batch.id,
    lane: lane.id,
    from: at(batch[lane.id][0]),
    to: at(batch[lane.id][1]),
  })),
);

/* The batch number written into every bar, as the schedule's "Bar labels"
   example writes the order. */
const BATCH_NAMES = new Map(SHIFT.batches.map((batch) => [batch.id, batch.name]));

const PLAN_DOMAIN: readonly [number, number] = [at(-75), at(SHIFT_MINUTES + 30)];

type Point = { t: number; kiln: number };
type Measured = Sample & { t: number };

const inKiln = (minute: number): Batch | undefined =>
  SHIFT.batches.find((batch) => batch.kiln[0] <= minute && minute < batch.kiln[1]);

/* The room opens six minutes or so after the crossing, at the first minute a
   batch is in the kiln: the alarm stands, and there is a batch to look at. */
const FROM = SHIFT.readings.find((one) => one.minute >= CROSSING + 6 && inKiln(one.minute) !== undefined)!.minute;

/** The plant's clock: a minute per second while it runs, never past the end
    of the shift, and never on its own when the wall clock stands still. */
function usePlantMinute(): { minute: number; wall: number; running: boolean; setRunning: (running: boolean) => void } {
  /* The minute and the wall-clock instant it was reached at, together: a
     reading taken now is as old as the wall says, not as the plant does.
     Paused, no reading comes in, and the tiles age on the wall as they would
     at a plant whose data stopped. */
  const [{ minute, wall }, setClock] = useState(() => ({ minute: FROM, wall: Date.now() }));
  const [running, setRunning] = useState(
    () => !window.matchMedia("(prefers-reduced-motion: reduce)").matches,
  );

  useEffect(() => {
    if (!running) return;
    let last = Date.now();
    const timer = setInterval(() => {
      const steps = Math.floor((Date.now() - last) / SECOND);
      if (steps === 0) return;
      last += steps * SECOND;
      const reached = last;
      setClock((clock) => ({ minute: Math.min(LAST, clock.minute + steps), wall: reached }));
    }, SECOND / 4);
    return () => clearInterval(timer);
  }, [running]);

  return { minute, wall, running: running && minute < LAST, setRunning };
}

/** A region of the room: a landmark with its name, and the place a skip link
    lands. `quiet` keeps the name for the landmark and leaves the header out,
    where the content shows a heading of its own. */
function Region({
  id,
  title,
  quiet = false,
  actions,
  callout,
  children,
}: {
  id: string;
  title: string;
  quiet?: boolean;
  /** The numbered mark the scenarios page lays over the region. */
  callout?: string;
  actions?: ReactNode;
  children: ReactNode;
}) {
  /* Where a skip link landed shows the library's ring, over the card's own
     shadow - a card has no focus style of its own, being no control. */
  const [landed, setLanded] = useState(false);
  return (
    <Card
      id={id}
      data-callout={callout}
      aria-labelledby={quiet ? undefined : `${id}-title`}
      aria-label={quiet ? title : undefined}
      tabIndex={-1}
      onFocus={(event) => setLanded(event.target === event.currentTarget)}
      onBlur={() => setLanded(false)}
      style={{ outline: "none", boxShadow: landed ? "var(--u-focus-ring), var(--u-shadow-card)" : undefined }}
    >
      {!quiet && <CardHeader title={<span id={`${id}-title`}>{title}</span>} actions={actions} />}
      <CardBody>{children}</CardBody>
    </Card>
  );
}

const REGIONS = [
  { id: "room-status", title: "Line status" },
  { id: "room-trend", title: "Kiln trend" },
  { id: "room-alarms", title: "Alarms" },
  { id: "room-plan", title: "Plan" },
  { id: "room-quality", title: "Tile length" },
  { id: "room-oee", title: "OEE so far" },
] as const;

/* A skip link moves the focus and not the address: the demo keeps its page in
   the address, and a fragment there would leave it. */
function skipTo(event: MouseEvent<HTMLAnchorElement>, id: string) {
  event.preventDefault();
  const region = document.getElementById(id);
  region?.focus();
  region?.scrollIntoView({ block: "start" });
}

const clock = (t: number) => new Date(t).toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" });

const RANK = { high: 0, medium: 1, low: 2 } as const;

/** Worst first: by priority, then what nobody has acknowledged, then the newest. */
const WORST_FIRST = [
  { column: "priority", direction: "asc" },
  { column: "acknowledged", direction: "asc" },
  { column: "raised", direction: "desc" },
] as const;

export default function ControlRoom() {
  const { Schedule, Lane, Subtasks } = useSchedule({ initialView: { domain: PLAN_DOMAIN } });
  const { minute, wall, running, setRunning } = usePlantMinute();
  const now = at(minute);
  const reading = SHIFT.readings[minute]!;

  const [acknowledged, setAcknowledged] = useState<ReadonlyMap<string, number>>(new Map());
  const [batch, setBatch] = useState<string | null>(() => inKiln(FROM)?.id ?? null);
  const [details, setDetails] = useState(false);

  const trend = useMemo<Point[]>(
    () => upTo(SHIFT.readings, minute).map((one) => ({ t: at(one.minute), kiln: one.kiln })),
    [minute],
  );
  const measured = useMemo<Measured[]>(
    () => upTo(SHIFT.samples, minute).map((one) => ({ ...one, t: at(one.minute) })),
    [minute],
  );
  const kilnTrend = useChart(trend);
  const tileLength = useChart(measured);
  const alarms = useMemo(
    () =>
      alarmsAt(SHIFT, minute, START, acknowledged).map((one) => {
        const type = ALARM_TYPES.find((kind) => kind.id === one.type)!;
        const ended = one.resolved === undefined ? "Active" : "Resolved";
        return {
          id: one.id,
          raised: one.raised,
          priority: type.priority,
          message: type.label,
          state: one.availability === "suppressed" || one.availability === "disabled" ? `${ended}, ${one.availability}` : ended,
          acknowledgedAt: one.acknowledgedAt,
        };
      }),
    [minute, acknowledged],
  );
  const t = useTable(alarms, { rowKey: (a) => a.id, defaultSort: WORST_FIRST });
  const { Table, Column } = t;

  const count = countAt(SHIFT, minute);
  const oee = (IDEAL_CYCLE_MINUTES * count.good) / count.planned;
  const current = inKiln(minute);
  const inTheKiln = current === undefined ? "No batch in the kiln" : `${current.name} through the kiln`;
  const chosen = SHIFT.batches.find((one) => one.id === batch);

  /* The tile's freshness is told the plant's age of the reading, as the
     instant it was true on the wall clock: the plant's minutes run faster
     than the wall's, and a tile judges age against the wall. */
  const silence = exitSilence(SHIFT, minute);
  const exit = SHIFT.readings[minute - silence]?.exit ?? null;

  return (
    <Stack gap={4}>
      <Stack direction="row" gap={4} align="center" wrap>
        <Text mono>
          {new Date(now).toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" })}
        </Text>
        <Button size="sm" data-callout="1" disabled={minute === LAST} onClick={() => setRunning(!running)}>
          {running ? "Pause the shift" : "Run the shift"}
        </Button>
        <Text as="nav" size="sm" aria-label="Regions of the control room">
          <Stack direction="row" gap={3} wrap>
            {REGIONS.map((region) => (
              <Link key={region.id} size="sm" href={`#${region.id}`} onClick={(event) => skipTo(event, region.id)}>
                {region.title}
              </Link>
            ))}
          </Stack>
        </Text>
      </Stack>

      <Region id="room-status" title="Line status">
        <Grid minItemWidth="200px" gap={4}>
          <Stat
            data-callout="2"
            label="Kiln K1 · zone 3"
            value={reading.kiln}
            unit="°C"
            decimals={1}
            limits={KILN_LIMITS}
            history={trend.slice(-30).map((one) => one.kiln)}
            asOf={wall}
            ages={AGES}
          />
          <Stat
            label="Kiln K1 · exit"
            value={exit}
            unit="°C"
            decimals={1}
            asOf={wall - silence * MIN}
            ages={AGES}
          />
          <Stat label="OEE so far" value={oee * 100} unit="%" decimals={1} limits={OEE_LIMITS} />
          <Stack gap={2}>
            <Text size="sm" tone="muted">
              {inTheKiln}
            </Text>
            <ProgressBar
              label={inTheKiln}
              value={current === undefined ? 0 : (minute - current.kiln[0]) / (current.kiln[1] - current.kiln[0])}
              showLabel
            />
            <Text size="sm" tone="muted">
              The early shift, 06:00 to 14:00
            </Text>
            <ProgressBar label="The early shift" value={(minute + 1) / SHIFT_MINUTES} showLabel />
          </Stack>
        </Grid>
      </Region>

      <Region id="room-trend" title="Kiln trend" callout="3">
        <kilnTrend.Chart height={240} ariaLabel="Kiln K1, zone 3, over the shift">
          <kilnTrend.XAxis value="t" domain={[at(0), at(LAST)]} time />
          <kilnTrend.YAxis domain={[1170, 1250]} label="°C" />
          <LimitBand from={KILN.tolerance[0]} to={KILN.tolerance[1]} severity="warning" label="Tolerance" />
          <LimitLine value={KILN.alarm} severity="alarm" label="Alarm limit" />
          <kilnTrend.Line value="kiln" name="Zone 3" format={(v) => `${v.toFixed(1)} °C`} />
          <Tooltip mode="x" />
          <DataTable />
        </kilnTrend.Chart>
      </Region>

      <Region id="room-alarms" title="Alarms" quiet callout="4">
        <Stack gap={2}>
          <Table selectable ariaLabel="Alarms">
            <Column value="raised" label="Raised">
              {(raised) => clock(raised)}
            </Column>
            <Column value="priority" label="Priority" sortValue={(priority) => RANK[priority]}>
              {(priority) => <Badge tone={priority === "high" ? "danger" : priority === "medium" ? "warning" : "neutral"}>{priority}</Badge>}
            </Column>
            <Column value="message" label="Alarm" rowHeader />
            <Column value="state" label="State" />
            <Column id="acknowledged" label="Acknowledged" value={(a) => a.acknowledgedAt ?? 0}>
              {(_, a) => (a.acknowledgedAt === undefined ? "No" : clock(a.acknowledgedAt))}
            </Column>
          </Table>
          <div>
            <Button
              size="sm"
              disabled={t.selection.selected.size === 0}
              onClick={() => {
                setAcknowledged((before) => new Map([...before, ...[...t.selection.selected].map((id) => [String(id), now] as const)]));
                t.selection.clear();
              }}
            >
              Acknowledge
            </Button>
          </div>
        </Stack>
      </Region>

      <Region
        id="room-plan"
        title="Plan"
        callout="5"
        actions={
          <Button size="sm" disabled={chosen === undefined} onClick={() => setDetails(true)}>
            {chosen === undefined ? "Choose a batch" : `Details of ${chosen.name}`}
          </Button>
        }
      >
        <Schedule
          ariaLabel="Plan of the early shift: press, dryer and kiln"
          height={196}
          now={now}
          selectedTask={batch}
          onSelectedTaskChange={(task) => setBatch(task)}
          label={(subtask) => BATCH_NAMES.get(subtask.task) ?? subtask.task}
        >
          {LANES.map((lane) => (
            <Lane key={lane.id} id={lane.id} label={lane.label} />
          ))}
          <Subtasks data={STEPS} tasks={TASKS} />
        </Schedule>
      </Region>

      <Grid columns={2} gap={4}>
        <Region id="room-quality" title="Tile length">
          <tileLength.Chart ariaLabel="Tile length after firing, individuals chart">
            <tileLength.XAxis value="t" domain={[at(0), at(LAST)]} time />
            <tileLength.YAxis domain={[597, 602]} label="mm" />
            <LimitLine value={601.5} severity="alarm" label="USL" />
            <LimitLine value={598.5} severity="alarm" label="LSL" />
            <ControlChart
              value="length"
              data={measured}
              origin={REFERENCE}
              name="Length"
              labelUpper="UCL"
              labelLower="LCL"
              violationName="Length - rule violation"
            />
            <Tooltip mode="x" />
          </tileLength.Chart>
        </Region>

        <Region id="room-oee" title="OEE so far" callout="6">
          <Calculation aria-label="OEE of the shift so far">
            <Product label="OEE" format="percent" target={OEE_TARGET}>
              <Quotient label="Availability" format="percent">
                <Difference id="runtime" label="Run time" unit="min">
                  <Given id="planned" label="Planned production time" value={count.planned} unit="min" />
                  <Given label="Downtime" value={count.downtime} unit="min" />
                </Difference>
                <Ref to="planned" />
              </Quotient>
              <Quotient label="Performance" format="percent">
                <Product label="Ideal run time" unit="min">
                  <Given label="Ideal cycle time" value={IDEAL_CYCLE_MINUTES} unit="min/pc" />
                  <Given id="total" label="Total count" value={count.total} unit="pcs" />
                </Product>
                <Ref to="runtime" />
              </Quotient>
              <Quotient label="Quality" format="percent">
                <Given label="Good count" value={count.good} unit="pcs" />
                <Ref to="total" />
              </Quotient>
            </Product>
          </Calculation>
        </Region>
      </Grid>

      <Drawer open={details} onClose={() => setDetails(false)}>
        {chosen !== undefined && <BatchDetails batch={chosen} minute={minute} onClose={() => setDetails(false)} />}
      </Drawer>
    </Stack>
  );
}

/** A batch, as far as the kiln has fired it. */
function BatchDetails({ batch, minute, onClose }: { batch: Batch; minute: number; onClose: () => void }) {
  const fired = upTo(SHIFT.readings, minute).filter((one) => batch.kiln[0] <= one.minute && one.minute < batch.kiln[1]);
  const total = fired.reduce((sum, one) => sum + one.fired, 0);
  const good = fired.reduce((sum, one) => sum + one.good, 0);
  const time = (m: number) => new Date(at(m)).toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" });

  return (
    <>
      <ModalHeader
        title={`Batch ${batch.name}`}
        description={`In the kiln from ${time(batch.kiln[0])} to ${time(batch.kiln[1])}, ${batch.tiles} tiles planned.`}
      />
      <ModalBody>
        <Stack gap={3}>
          <ProgressBar label="Tiles fired" value={total / batch.tiles} showLabel />
          <Text>
            {total} fired, {good} inside the tolerance, {total - good} scrap.
          </Text>
        </Stack>
      </ModalBody>
      <ModalFooter>
        <Button onClick={onClose}>Close</Button>
      </ModalFooter>
    </>
  );
}
```

## Getting started

What an application sets up once, before the first component.

### Installation

What an application does once before its first component: install the package, choose the fonts and let light and dark follow the page. The styles load themselves, and no provider is needed.

```sh
npm install @umriss-ui/core
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/installation/

The command installs the package alone: React 19 or newer is its only peer and stays the application's own. Importing a component brings its stylesheet along; `@umriss-ui/core/styles.css` stays exported for setups that link stylesheets by hand. The styles touch nothing outside the components: no rule on `html`, `body` or `*` ([ADR-0021](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0021-the-styles-load-themselves-and-touch-nothing-else.md)).

Colours, sizes, fonts and light and dark are tokens, `--u-…` custom properties you override with ordinary CSS: [Theming](#/theming) lists them. The fonts are the application's: the tokens name Geist first and fall back to the system fonts, and nothing is loaded. For Geist, install `@fontsource/geist-sans` (400, 500, 600) and `@fontsource/geist-mono` (400).

#### Examples

##### First component

Once installed, import a component and render it – no stylesheet import, no provider.

```tsx
import { Button } from "@umriss-ui/core";

export default function FirstComponent() {
  return <Button variant="primary">Acknowledge the incident</Button>;
}
```

#### Keyboard

The keys of [Button](#/button/keyboard-button) apply here.

#### Props on this page

From `ButtonProps` — the full table stands on [Button](#/button/type-ButtonProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`variant`](#/button/ButtonProps-variant) | [`ButtonVariant`](#/button/type-ButtonVariant)<br>`"primary" \| "secondary" \| "ghost" \| "plain" \| "danger"` | `"secondary"` | How loud the button is. `primary` exactly once per surface - two main actions side by side are no longer a main action. `ghost` is quiet in the accent, `plain` quiet and neutral. |

#### Known limits

- No font is loaded or bundled.
- Chrome 123, Firefox 120 and Safari 17.5 or newer; an older browser discards the tokens and shows the components unstyled.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### UmrissProvider

Sets once, at the root, what an application shares: the density of its tables, where overlays open, how long toasts stay and where they stand, and the language. It is optional; every component works the same without it.

```ts
import { UmrissProvider } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/umrissprovider/

It holds these four settings and nothing else: no theme (see [Installation](#/installation)) and no defaults for a component's own props. It writes nothing onto the document.

Keep the objects you pass outside the component or memoised: a new object on every render is a new setting on every render.

#### Examples

##### At the root

Wrap the application once; here `toast` keeps every toast on screen for eight seconds unless the toast names its own duration.

```tsx
import { Button, ToastProvider, UmrissProvider, useToast, type ToastConfig } from "@umriss-ui/core";

type ToastFn = ReturnType<typeof useToast>["toast"];

const deploy = (toast: ToastFn) => toast({ title: "Checkout 4.12.0 deployed", description: "Rolled out to all regions.", tone: "success" });

function DeployButton() {
  const { toast } = useToast();
  return (
    <Button variant="primary" onClick={() => deploy(toast)}>
      Deploy Checkout
    </Button>
  );
}

/* Kept outside the component: a new object on every render would be a new
   setting on every render. */
const TOAST: ToastConfig = { duration: 8000 };

export default function AtTheRoot() {
  return (
    <UmrissProvider toast={TOAST}>
      <ToastProvider>
        <DeployButton />
      </ToastProvider>
    </UmrissProvider>
  );
}
```

##### Open overlays inside a full-screen panel

A full-screen element hides everything outside it, overlays included; point `portalTarget` at the element so menus and tooltips open inside it.

```tsx
import { useRef } from "react";
import { Button, Card, CardBody, CardHeader, Menu, MenuItem, Text, UmrissProvider } from "@umriss-ui/core";

export default function PortalTarget() {
  const panel = useRef<HTMLDivElement>(null);

  return (
    <div ref={panel} style={{ background: "var(--u-color-bg)" }}>
      {/* A function, because the element exists only after the first render. */}
      <UmrissProvider portalTarget={() => panel.current}>
        <Card>
          <CardHeader
            eyebrow="Sprint 14"
            title="Web team board"
            actions={
              <>
                <Button size="sm" onClick={() => void panel.current?.requestFullscreen?.()}>
                  Full screen
                </Button>
                <Menu trigger={<Button size="sm">Move card</Button>}>
                  <MenuItem onSelect={() => {}}>To review</MenuItem>
                  <MenuItem onSelect={() => {}}>To done</MenuItem>
                  <MenuItem onSelect={() => {}}>Back to the backlog</MenuItem>
                </Menu>
              </>
            }
          />
          <CardBody>
            <Text size="sm" tone="secondary">
              Checkout flow redesign · Chloe Durand · 5 points
            </Text>
          </CardBody>
        </Card>
      </UmrissProvider>
    </div>
  );
}
```

##### Set up an application

All four settings, as a root sets them: German wording and notation, compact tables, overlays in the application's element, short toasts.

```tsx
import { useRef, useState } from "react";
import { Button, DatePicker, FormField, Stack, ToastProvider, UmrissProvider, useToast } from "@umriss-ui/core";
import type { ToastConfig, UmrissProviderProps } from "@umriss-ui/core";
import { GERMAN_FORMATS, GERMAN_WORDING } from "@umriss-ui/core/wording/de";

const LANGUAGE: UmrissProviderProps["language"] = { wording: GERMAN_WORDING, formats: GERMAN_FORMATS };
const TOAST: ToastConfig = { duration: 3000 };

type ToastFn = ReturnType<typeof useToast>["toast"];

const rebook = (toast: ToastFn) => toast({ title: "Shipment SH-1042 rebooked" });

function DeliveryDate() {
  const { toast } = useToast();
  const rebookNow = () => rebook(toast);
  const [date, setDate] = useState<Date | null>(new Date(2026, 2, 18));
  return (
    <Stack gap={3} align="flex-start">
      <FormField label="Delivery date">
        <DatePicker value={date} onChange={setDate} clearable />
      </FormField>
      <Button size="sm" disabled={date === null} onClick={rebookNow}>
        Rebook
      </Button>
    </Stack>
  );
}

export default function EverythingAtOnce() {
  const root = useRef<HTMLDivElement>(null);

  return (
    <div ref={root}>
      <UmrissProvider density="compact" portalTarget={() => root.current} toast={TOAST} language={LANGUAGE}>
        <ToastProvider>
          <DeliveryDate />
        </ToastProvider>
      </UmrissProvider>
    </div>
  );
}
```

#### When to use something else

- Only the wording or the formats of one section differ → Language

#### Keyboard

The keys of [Button](#/button/keyboard-button), [Menu](#/menu/keyboard-menu) and [DatePicker](#/datepicker/keyboard-datepicker) apply here.

#### Accessibility

Where a `ToastProvider` stands inside it, the toasts' two live regions stand where the overlays go: in the `portalTarget` before the first message, so that it is heard there, and inside the topmost modal dialog while one is open. [Toast](#/toast) describes them.

#### API

##### `UmrissProviderProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `density` | [`Density`](#type-Density)<br>`"comfortable" \| "compact"` | none - a component keeps its own density | The default for the `density` of every component that reads it with `useDensityFor` - in `@umriss-ui/table` `Table`, in `@umriss-ui/calculation` `Calculation` ("comfortable" means "regular").<br>Shown in: [Set up an application](#/umrissprovider/everything-at-once) |
| `portalTarget` | [`PortalTarget`](#type-PortalTarget) | `null` | Where overlays portal to, unless an open dialog takes them. A function is evaluated on every opening - a target that only enters the tree later cannot be given otherwise; `null` means "as before". The callers' own rules take precedence: the popover seam portals into the nearest `<dialog>` ancestor, because a portal at the body does not reach the top layer, and the toasts follow the topmost modal dialog, because a toast outside it lies behind it and is inert.<br>Shown in: [Open overlays inside a full-screen panel](#/umrissprovider/portal-target), [Set up an application](#/umrissprovider/everything-at-once) |
| `toast` | [`ToastConfig`](#type-ToastConfig) | — | The setting for toasts: the display duration where the individual toast names none, where they stand, and how many stand at once.<br>Shown in: [At the root](#/umrissprovider/at-the-root), [Set up an application](#/umrissprovider/everything-at-once), [Where they stand (Toast)](#/toast/where-they-stand) and 1 more |
| `language` | [`LanguageOptions`](#/language/type-LanguageOptions) | none - the surrounding language holds, English at the root | Formats and wording, entry by entry - see [Language](#/language).<br>Shown in: [Set up an application](#/umrissprovider/everything-at-once) |
| `children` *required* | `ReactNode` | — | The subtree the settings apply to.<br>Shown in: [Open overlays inside a full-screen panel](#/umrissprovider/portal-target), [Set up an application](#/umrissprovider/everything-at-once) |

##### `ToastConfig`

| Prop | Type | Default | Description |
|---|---|---|---|
| `duration` | `number` | `5000` | Display duration in ms, where the individual toast names none.<br>Shown in: [At the root](#/umrissprovider/at-the-root), [Set up an application](#/umrissprovider/everything-at-once) |
| `position` | [`ToastPosition`](#type-ToastPosition)<br>`"top-start" \| "top-center" \| "top-end" \| "bottom-start" \| "bottom-center" \| "bottom-end"` | `"bottom-end"` | Where the toasts stand. There is no position per toast - toasts that stand in different places are not read as one.<br>Shown in: [Where they stand (Toast)](#/toast/where-they-stand) |
| `limit` | `number` | `3` | How many toasts that leave by themselves stand at once; the oldest of them gives way to a new one, as if it had been closed. A toast that stays (`duration: 0`) or is still at work (`loading`) neither counts nor gives way.<br>Shown in: [How many stand at once (Toast)](#/toast/how-many-stand) |

##### Types on this page

###### `Density`

How densely the library builds. A component with a density of its own
takes it through `useDensityFor` as the default for its `density` - in

```ts
type Density = "comfortable" | "compact";
```

###### `PortalTarget`

Where overlays portal to.

A function is evaluated on every opening - a target that only comes into the
tree later cannot be given otherwise. `null`, or a result of `null`, means
"as before".

```ts
type PortalTarget = HTMLElement | (() => HTMLElement | null) | null;
```

###### `ToastPosition`

Where the toasts stand: an edge of the window and a place along it. On a
phone they take the width of the window, and only the edge counts.

```ts
type ToastPosition = "top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end";
```

#### Known limits

- No theme and no default variants for components: a component is configured by its own props.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

## Customising

What every component shares and an application sets once: its colours, its size, its words.

### Theming

Make the components look like your product (theme, colours, dark mode, CSS variables). Every colour, size, shadow and duration they draw with is a token, a `--u-…` custom property, and the tokens are the whole styling API: override one with ordinary CSS, for the application or for one region. The table lists each with its light and dark value.

Demo page: https://romanhaendler.github.io/umriss-ui/core/theming/

The library writes its CSS in three cascade layers, `umriss.tokens`, `umriss.base` and `umriss.components`. CSS outside any layer wins over every layered rule, whatever its specificity and whatever order the stylesheets load in, so one unlayered `:root { --u-color-accent: … }` in your stylesheet is the whole override: no `!important`, no import order ([ADR-0021](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0021-the-styles-load-themselves-and-touch-nothing-else.md)). Inside a layer of your own it wins only if that layer was named after the library's.

Every token with two values is written `light-dark(<light>, <dark>)` and resolves against the `color-scheme` the element inherits. The library sets `color-scheme` nowhere: your `html.dark { color-scheme: dark }`, or your theme library's, switches the components, nothing set means light, and an element with its own `color-scheme` is a region in the other mode. An override written `light-dark(…)` follows the mode; a single colour holds in both.

Style through tokens only. The tokens in the table are the styling API and change only with an entry in the changelog; the `data-*` attributes and class names in the components' markup are internal and may change in any version ([ADR-0045](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0045-tokens-are-the-styling-api-data-attributes-are-not.md)). Where no token reaches what you want to change, ask for one: a selector on the markup breaks without warning.

#### Examples

##### Accent for the application

One rule on `:root`, outside any cascade layer, gives the whole application its own accent: it wins over the library's tokens whatever order the stylesheets load in. Set the accent's seven tokens together, each with a light and a dark value.

```tsx
import type { CSSProperties } from "react";
import { Badge, Button, Card, CardBody, CardHeader, Checkbox, Link, Stack, Switch, Text } from "@umriss-ui/core";

/* In an application this is one rule in its own stylesheet:

     :root {
       --u-color-accent: light-dark(#4338ca, #818cf8);
       --u-color-accent-hover: light-dark(#3730a3, #a5b4fc);
       --u-color-accent-subtle: light-dark(#eef0fb, #1e1f3d);
       --u-color-accent-subtle-pressed: light-dark(#dfe2f7, #282a52);
       --u-color-accent-text: light-dark(#4338ca, #a5b4fc);
       --u-color-on-accent: light-dark(#ffffff, #1e1b4b);
     }

   Here it is set on the example's root, so the rest of the page keeps the
   library's petrol. */
const INDIGO = {
  "--u-color-accent": "light-dark(#4338ca, #818cf8)",
  "--u-color-accent-hover": "light-dark(#3730a3, #a5b4fc)",
  "--u-color-accent-subtle": "light-dark(#eef0fb, #1e1f3d)",
  "--u-color-accent-subtle-pressed": "light-dark(#dfe2f7, #282a52)",
  "--u-color-accent-text": "light-dark(#4338ca, #a5b4fc)",
  "--u-color-on-accent": "light-dark(#ffffff, #1e1b4b)",
} as CSSProperties;

export default function AccentForTheApplication() {
  return (
    <div style={INDIGO}>
      <Card>
        <CardHeader
          eyebrow="Carrow & Lisle"
          title="Invoice INV-2026-0314"
          actions={<Badge tone="accent">Awaiting approval</Badge>}
        />
        <CardBody>
          <Stack gap={3} align="flex-start">
            <Text size="sm" tone="secondary">
              Marketing · 3 lines · due 31/03/2026 · <Link href="#/theming">Open the approval</Link>
            </Text>
            <Switch label="Remind the approver" defaultChecked />
            <Checkbox label="Copy the account owner" defaultChecked />
            <Button variant="ghost" size="sm">
              Approve
            </Button>
          </Stack>
        </CardBody>
      </Card>
    </div>
  );
}
```

##### A token for one region

A token is a custom property and cascades like one: set on a container, it holds for everything inside and nowhere else. The second card sets its own accent, with a light and a dark value.

```tsx
import type { CSSProperties } from "react";
import { Card, CardBody, CardHeader, Checkbox, Grid, Stack, Switch } from "@umriss-ui/core";

/* In an application this is one rule on the region's class:

     .billing {
       --u-color-accent: light-dark(#7a3e9d, #b98ad6);
     }                                                    */
const BILLING = { "--u-color-accent": "light-dark(#7a3e9d, #b98ad6)" } as CSSProperties;

function Settings({ title }: { title: string }) {
  return (
    <Card>
      <CardHeader title={title} />
      <CardBody>
        <Stack gap={3}>
          <Switch label="Send a weekly summary" defaultChecked />
          <Checkbox label="Copy the account owner" defaultChecked />
        </Stack>
      </CardBody>
    </Card>
  );
}

export default function TokenForOneRegion() {
  return (
    <Grid columns={2} gap={4}>
      <Settings title="Notifications" />
      <div style={BILLING}>
        <Settings title="Billing" />
      </div>
    </Grid>
  );
}
```

##### A dark region

The tokens follow the `color-scheme` an element inherits, and the library sets it nowhere: one element with `color-scheme: dark` makes everything inside it dark, on a light page too. The first tour follows the page; the second is always dark.

```tsx
import { Badge, Card, CardBody, CardHeader, Grid, Text } from "@umriss-ui/core";

/* The application's own switch is one CSS line, which its native controls
   need anyway:

     html.dark { color-scheme: dark; }
     :root { color-scheme: light dark; }  (or: follow the system)

   Nothing set means light. A region is the same line on its element:

     .dispatch-board { color-scheme: dark; background: var(--u-color-bg); } */
function Tour({ scheme }: { scheme?: "dark" }) {
  return (
    <div style={{ colorScheme: scheme, background: "var(--u-color-bg)", padding: 16, borderRadius: 8 }}>
      <Card>
        <CardHeader eyebrow="North depot" title="Tour T-03" actions={<Badge tone="warning">2 stops late</Badge>} />
        <CardBody>
          <Text size="sm" tone="secondary">
            FP 214 K · Martin Hale · 14 stops · 86 km
          </Text>
        </CardBody>
      </Card>
    </div>
  );
}

export default function ADarkRegion() {
  return (
    <Grid minItemWidth="240px" gap={4}>
      <Tour />
      <Tour scheme="dark" />
    </Grid>
  );
}
```

#### Tokens

Every token the components draw with, grouped as the stylesheet groups them. A swatch is drawn from the token itself, light in the light column and dark in the dark one; "same" means one value for both themes.

##### Neutral: Ink & Paper

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-color-bg` | `#fafafa` | `#0f0f10` | — |
| `--u-color-surface` | `#ffffff` | `#161618` | — |
| `--u-color-surface-sunken` | `#f4f4f5` | `#1e1e21` | — |
| `--u-color-surface-pressed` | `#e9e9eb` | `#28282c` | The pressed step of a quiet key: what sinks to the sunken surface under the pointer sinks once more while it is pressed (the interaction-state canon). The three `-pressed` surfaces exist because a hover for each ground needs something stronger. |
| `--u-color-text` | `#171717` | `#ededed` | — |
| `--u-color-text-secondary` | `#565656` | `#a5a5ab` | — |
| `--u-color-text-muted` | `#8b8b8b` | `#77777e` | — |

##### Edges as shadows (instead of borders)

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-edge-color` | `rgba(23, 23, 23, 0.08)` | `rgba(255, 255, 255, 0.10)` | — |
| `--u-edge-color-strong` | `rgba(23, 23, 23, 0.17)` | `rgba(255, 255, 255, 0.20)` | — |
| `--u-edge` | `0 0 0 1px var(`[--u-edge-color](#token-u-edge-color)`)` | same | — |
| `--u-edge-strong` | `0 0 0 1px var(`[--u-edge-color-strong](#token-u-edge-color-strong)`)` | same | — |
| `--u-hairline` | `rgba(23, 23, 23, 0.06)` | `rgba(255, 255, 255, 0.07)` | inner dividing lines |
| `--u-color-edge-hover` | `color-mix(in srgb, var(`[--u-color-text](#token-u-color-text)`) 30%, transparent)` | same | The edge of a field under the pointer. |
| `--u-hairline-strong` | `rgba(23, 23, 23, 0.12)` | `rgba(255, 255, 255, 0.14)` | e.g. under table heads |

##### Ink as interaction (the primary button)

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-color-primary-bg` | `#171717` | `#ededed` | — |
| `--u-color-primary-fg` | `#ffffff` | `#171717` | — |
| `--u-color-primary-hover` | `#2e2e2e` | `#ffffff` | — |
| `--u-color-primary-active` | `#000000` | `#d6d6d6` | — |

##### Accent (petrol) - interactive things only

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-color-accent` | `#0e7d72` | `#17a292` | — |
| `--u-color-accent-hover` | `#0a685f` | `#1cb5a3` | — |
| `--u-color-accent-subtle` | `#e9f4f2` | `#142e2b` | — |
| `--u-color-accent-subtle-pressed` | `#d5e9e6` | `#1b3d39` | — |
| `--u-color-accent-text` | `#0b6a61` | `#4cc4b5` | — |
| `--u-color-on-accent` | `#ffffff` | `#072522` | — |
| `--u-color-on-danger` | `#ffffff` | `#2b0f0d` | Type on the danger surface, a token so that a contrast check sees it. Dark: White measures only 3.68:1 on the lighter danger surface. The polarity turns as it does for the accent: dark type on a light ground. |

##### Semantics (muted)

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-color-success` | `#217a4b` | `#4fae7c` | — |
| `--u-color-success-subtle` | `#e8f2ec` | `#16241d` | — |
| `--u-color-warning` | `#8a5c00` | `#d0a24d` | Darkened from #9a6700, which reached only 4.24:1 on its own pale surface and so missed the 4.5:1 for normal text; this reaches 4.97:1. |
| `--u-color-warning-subtle` | `#f7efdb` | `#2b2415` | — |
| `--u-color-danger` | `#b13636` | `#d0655c` | — |
| `--u-color-danger-hover` | `#9a2c2c` | `#da7a72` | — |
| `--u-color-danger-active` | `color-mix(in srgb, var(`[--u-color-danger](#token-u-color-danger)`) 85%, #000000)` | `color-mix(in srgb, var(`[--u-color-danger](#token-u-color-danger)`) 85%, #ffffff)` | Pressed: darker in the light theme. As a mixture rather than a value, so that it follows the ground; the dark theme turns the direction round. |
| `--u-color-danger-subtle` | `#f8eaea` | `#2f1b1d` | — |
| `--u-color-danger-subtle-pressed` | `#f3dcdc` | `#351e21` | — |
| `--u-color-danger-text` | `#b13636` | `#d86f66` | Danger as type, beside the surface - the split the accent has with --u-color-accent-text. Dark: the surface value reached only 4.40:1 on the subtle danger surface; this one is lighter and holds 4.5:1 there and on every ground (tone-contrast). Light: the surface value already passes. |

##### Focus: a crisp accent edge, two pixels, no glow

One look for every component. A soft glow would read as a second, shadowy border. On a field the ring lies where its edge lies, so the edge seems to grow. `-danger` for an invalid field, which keeps its colour.

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-focus-ring` | `0 0 0 2px var(`[--u-color-accent](#token-u-color-accent)`)` | same | — |
| `--u-focus-ring-danger` | `0 0 0 2px var(`[--u-color-danger](#token-u-color-danger)`)` | same | — |

##### Typography

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-font-sans` | `"Geist Sans", "Geist", -apple-system, "Segoe UI", system-ui, sans-serif` | same | — |
| `--u-font-mono` | `"Geist Mono", ui-monospace, "Cascadia Mono", "Consolas", monospace` | same | — |
| `--u-text-xs` | `0.6875rem` | same | — |
| `--u-text-sm` | `0.8125rem` | same | — |
| `--u-text-md` | `0.875rem` | same | — |
| `--u-text-lg` | `1rem` | same | — |
| `--u-text-xl` | `1.1875rem` | same | — |
| `--u-text-2xl` | `1.5rem` | same | — |
| `--u-text-mono` | `0.75rem` | same | Figures in Geist Mono inside a control or a cell, beside --u-text-sm set in Sans. The mono cut runs wider and taller, so one step down reads as the same size. It serves as a role: the date picker's value, days and time fields, the numeric field and input, the table's numeric cells. |
| `--u-leading-none` | `1` | same | A box as tall as its type: a badge, a tag, a count, a glyph. The height comes from the control or the padding, and the line adds no leading. |
| `--u-leading-tight` | `1.3` | same | — |
| `--u-leading-normal` | `1.5` | same | — |
| `--u-weight-regular` | `400` | same | — |
| `--u-weight-medium` | `500` | same | — |
| `--u-weight-semibold` | `600` | same | — |
| `--u-tracking-caps` | `0.07em` | same | — |
| `--u-tracking-display` | `-0.022em` | same | large titles: slightly compressed |
| `--u-tracking-tight` | `-0.011em` | same | medium titles (cards, dialogs) |
| `--u-tracking-figures` | `-0.01em` | same | figures set in the mono face |

##### Spacing and shape

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-space-1` | `4px` | same | — |
| `--u-space-2` | `8px` | same | — |
| `--u-space-3` | `12px` | same | — |
| `--u-space-4` | `16px` | same | — |
| `--u-space-5` | `20px` | same | — |
| `--u-space-6` | `24px` | same | — |
| `--u-space-7` | `32px` | same | — |
| `--u-space-8` | `40px` | same | — |
| `--u-radius-xs` | `4px` | same | — |
| `--u-radius-sm` | `6px` | same | — |
| `--u-radius-md` | `8px` | same | — |
| `--u-radius-lg` | `12px` | same | — |
| `--u-radius-xl` | `18px` | same | One step above the card, for the command palette. It is meant to be a system window and not a form panel, and the radius plays its part in that. Both themes share it - shape is not a question of theme. The sequence 4-6-8-12-18 continues the factor of 1.5 of the steps above. |
| `--u-radius-full` | `999px` | same | — |
| `--u-control-height` | `32px` | same | — |
| `--u-control-height-sm` | `26px` | same | — |
| `--u-control-height-xs` | `18px` | same | The small control on a dense surface - a compact table's row draft and actions (`dense` in the shared own styles). |
| `--u-icon-size` | `14px` | same | The icon in a button, beside a label or alone (CONTEXT.md, "Icon"): the button decides its size, one step per control height. |
| `--u-icon-size-sm` | `12px` | same | — |
| `--u-button-padding` | `10px` | same | The room left and right of a button's label, one step per control height. What stands beside a quiet button and has to align with its word hangs out by exactly this much (the date pickers' foot, the MultiSelect's quick keys) - so they read it here instead of repeating the number. |
| `--u-button-padding-sm` | `6px` | same | — |
| `--u-drawer-width` | `400px` | same | The width of a drawer A token rather than a size prop: a detail beside a process picture wants one width across an application, and one drawer that needs another sets it in its `style`. |

##### Toast

How far the toasts stand from the window's top and bottom edge and from its sides - set it to keep them clear of a fixed header, a toolbar at the bottom or a navigation rail at the side - and how wide a toast is. The region hangs in `body`, so set them on `:root`; a media query of your own may set another value per width. The center positions stand in the middle of the window whatever the side tokens are.

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-toast-inset-top` | `var(`[--u-space-5](#token-u-space-5)`)` | same | for the three `top-*` positions; `var(--u-space-4)` up to 600 px wide |
| `--u-toast-inset-bottom` | `var(`[--u-space-5](#token-u-space-5)`)` | same | for the three `bottom-*` positions; `var(--u-space-4)` up to 600 px wide |
| `--u-toast-inset-start` | `var(`[--u-space-5](#token-u-space-5)`)` | same | for the `*-start` positions, and on a phone the room at the start side; `var(--u-space-4)` up to 600 px wide |
| `--u-toast-inset-end` | `var(`[--u-space-5](#token-u-space-5)`)` | same | for the `*-end` positions, and on a phone the room at the end side; `var(--u-space-4)` up to 600 px wide |
| `--u-toast-width` | `360px` | same | a plain length, read it to know whether the deck has room beside a surface; up to 600 px wide the toast takes the window's width less the side tokens instead |

##### Shadow stacks: every step has one job

Card: edge, contact with the ground, soft depth. Overlay: edge, near shadow, depth.

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-shadow-card` | `var(`[--u-edge](#token-u-edge)`), 0 1px 2px rgba(23, 23, 23, 0.04), 0 8px 24px -12px rgba(23, 23, 23, 0.14)` | `var(`[--u-edge](#token-u-edge)`), 0 1px 2px rgba(0, 0, 0, 0.4), 0 8px 24px -12px rgba(0, 0, 0, 0.6)` | — |
| `--u-shadow-overlay` | `var(`[--u-edge](#token-u-edge)`), 0 4px 8px rgba(23, 23, 23, 0.06), 0 24px 48px -16px rgba(23, 23, 23, 0.24)` | `var(`[--u-edge](#token-u-edge)`), 0 4px 8px rgba(0, 0, 0, 0.4), 0 24px 48px -16px rgba(0, 0, 0, 0.7)` | — |
| `--u-shadow-sticky` | `rgba(23, 23, 23, 0.09)` | `rgba(0, 0, 0, 0.5)` | The shadow a sticking part casts on what scrolls under it - a pinned column block, a stuck group header - as the colour its gradient starts from. Dark is black at a higher opacity: the text colour at 9 % read as a glow on the dark ground. |

##### Translucent material and scrim ([ADR-0012](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0012-a-translucent-material-needs-a-floor.md))

An overlay meant to be a window ABOVE the application and not a card WITHIN it needs two things: the page behind it must be sensed, and it must never stay readable.

The alpha value is a FLOOR and not a matter of taste: the opaque colour carries legibility on its own, the transparency delivers atmosphere and never contrast. A panel that looks prettier at 0.55 is one whose type is legible by luck. The floor is open upwards, and in the light theme it lies higher than strictly necessary - see below.

Three tokens, because there are three jobs: - `-fallback` is the opaque colour underneath. It is really painted where `backdrop-filter` is missing or switched off, and it is what the contrast test checks (see tests-unit/contrast.test.ts). - `--u-color-material` is the same colour with the floor alpha. - `--u-material-blur` softens what shows through. Decoration under the same rule: the blur does not make the type legible.

The scrim dims the page behind an overlay. Dark gets its own values, chosen by eye: inverting a light surface lands wrong, because light type over a dark blur tolerates far less transparency than the other way round.

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-color-material-fallback` | `#fdfdfe` | `#1f1f23` | The numbers were looked at, not calculated. In the light theme the scrim must dim less and the panel cover more: a scrim that presses the whole page to a middling grey leaves the panel a grey slab within it, legible but looking like a fault. The distance between the two carries the step. The dark theme needs no such correction: there the lightness already separates them. Dark: Chosen by eye, not derived from the light theme: the alpha floor lies higher here, because light type over a dark blur tolerates markedly less transparency. |
| `--u-color-material` | `rgba(253, 253, 254, 0.86)` | `rgba(31, 31, 35, 0.82)` | — |
| `--u-material-blur` | `24px` | same | — |
| `--u-color-scrim` | `rgba(23, 23, 23, 0.30)` | `rgba(0, 0, 0, 0.60)` | — |

##### Motion: explains a change of state, does not decorate

The names follow the distinctions the library makes (visuelle-wertigkeit 02); a motion that fits none of them wants a new name here, not a number in its module.

Micro or path. A colour, an edge or an opacity changes in place: that is `--u-transition`. Something moves, turns or unfolds: that is `--u-transition-path`, or `--u-duration-medium` with `--u-ease-out` for a long way. A press is shorter than either.

Entry or exit. A surface enters on `--u-ease-out` from its motion origin; it leaves faster, on a curve that starts at once, and does not retrace the way it came - a symmetrical exit makes a surface feel sluggish.

Continuous process. A spinner or a shimmer has no start and no end; it runs steadily and long.

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-ease-out` | `cubic-bezier(0.22, 1, 0.36, 1)` | same | decisive, landing softly: entries and paths |
| `--u-ease-exit` | `cubic-bezier(0.2, 0.6, 0.4, 1)` | same | leaves at once, no wind-up |
| `--u-transition` | `120ms var(`[--u-ease-out](#token-u-ease-out)`)` | same | micro: hover, colour. It carried the CSS keyword `ease-out` and so kept the curve above from three quarters of the library's transitions. **0ms under reduced motion.** |
| `--u-duration-press` | `80ms` | same | the press point of a button or glyph **0ms under reduced motion.** |
| `--u-transition-press` | `var(`[--u-duration-press](#token-u-duration-press)`) var(`[--u-ease-out](#token-u-ease-out)`)` | same | — |
| `--u-duration-fast` | `140ms` | same | entry of a panel; a short path **0ms under reduced motion.** |
| `--u-transition-path` | `var(`[--u-duration-fast](#token-u-duration-fast)`) var(`[--u-ease-out](#token-u-ease-out)`)` | same | a chevron turns, a thumb slides |
| `--u-duration-medium` | `240ms` | same | entry of a sheet; a layout change **0ms under reduced motion.** |
| `--u-duration-draw` | `320ms` | same | a stroke drawn slowly enough to watch: the tick **0ms under reduced motion.** |
| `--u-delay-draw` | `60ms` | same | the box fills first, then the tick is drawn **0ms under reduced motion.** |
| `--u-delay-stale` | `200ms` | same | content being reloaded dims only after this: a quick answer never flickers |
| `--u-duration-exit-fast` | `100ms` | same | Exits. The stylesheet drawing the movement and the code waiting for its end read the same tokens, so the two cannot drift apart. a panel or a tooltip goes **0ms under reduced motion.** |
| `--u-duration-exit` | `160ms` | same | a sheet takes its leave: modal **0ms under reduced motion.** |
| `--u-duration-exit-collapse` | `200ms` | same | a message goes and its place closes **0ms under reduced motion.** |
| `--u-duration-spin` | `700ms` | same | Continuous processes. They do NOT fall to zero under reduced motion - a spinner at 0ms says nothing; each module slows or stops its own. |
| `--u-duration-shimmer` | `1.6s` | same | — |
| `--u-duration-sweep` | `1.4s` | same | an indeterminate progress bar crosses its track |
| `--u-ease-steady` | `linear` | same | a turn with no start and no end |
| `--u-ease-swell` | `ease-in-out` | same | a shimmer that comes and goes |

##### Stacking order

Popovers portal into the nearest <dialog> ancestor, and this scale orders the rest. The toasts also move into the topmost modal dialog. Inside a dialog the toasts and the tooltips stand in the top layer, which orders by the moment of showing and not by these numbers: a tooltip is shown after the toasts and lies above them, as the scale has it; popovers stay under the toasts.

| Token | Light | Dark | Description |
|---|---|---|---|
| `--u-z-popover` | `900` | same | — |
| `--u-z-toast` | `1000` | same | — |
| `--u-z-tooltip` | `1100` | same | — |

#### @umriss-ui/charts

The charts' own tokens, set on a chart's root. A token whose value names a core token takes that token, so theming core themes the charts; where core is not loaded, or has no such token (`--u-chart-1` to `--u-chart-6`), the literal after it stands.

| Token | Light | Dark | Description |
|---|---|---|---|
| `--uc-color-axis` | `var(`[--u-edge-color-strong](#token-u-edge-color-strong)`, rgba(23, 23, 23, 0.17))` | same | — |
| `--uc-color-grid` | `var(`[--u-hairline](#token-u-hairline)`, rgba(23, 23, 23, 0.06))` | same | — |
| `--uc-color-text` | `var(`[--u-color-text-muted](#token-u-color-text-muted)`, #71717a)` | same | — |
| `--uc-color-bg` | `var(`[--u-color-surface](#token-u-color-surface)`, #ffffff)` | same | — |
| `--uc-font` | `var(`[--u-font-sans](#token-u-font-sans)`, "Geist Sans", "Geist", -apple-system, "Segoe UI", system-ui, sans-serif)` | same | — |
| `--uc-font-mono` | `var(`[--u-font-mono](#token-u-font-mono)`, "Geist Mono", ui-monospace, "Cascadia Mono", "Consolas", monospace)` | same | — |
| `--uc-color-warning` | `var(`[--u-color-warning](#token-u-color-warning)`, #8a5c00)` | same | The two limit severities. They fall back onto the same tokens with which @umriss-ui/core warns and alarms - a limit in the chart and a tile above it must not be differently red. |
| `--uc-color-alarm` | `var(`[--u-color-danger](#token-u-color-danger)`, #b13636)` | same | — |
| `--uc-color-ok` | `var(`[--u-color-success](#token-u-color-success)`, #217a4b)` | same | — |
| `--uc-series-1` | `var(--u-chart-1, #2563eb)` | same | — |
| `--uc-series-2` | `var(--u-chart-2, #db2777)` | same | — |
| `--uc-series-3` | `var(--u-chart-3, #059669)` | same | — |
| `--uc-series-4` | `var(--u-chart-4, #d97706)` | same | — |
| `--uc-series-5` | `var(--u-chart-5, #7c3aed)` | same | — |
| `--uc-series-6` | `var(--u-chart-6, #0891b2)` | same | — |
| `--uc-size-tick` | `11.5px` | same | — |
| `--uc-size-title` | `12px` | same | — |
| `--uc-size-legend` | `12.5px` | same | — |
| `--uc-size-tooltip` | `12px` | same | The tooltip's text; its head is an x value and takes the tick's size. |
| `--uc-leading-label` | `1.25` | same | A label on an axis stands tight to its tick; running text - the legend, the tooltip - gets a little more air. |
| `--uc-leading-text` | `1.35` | same | — |
| `--uc-radius` | `6px` | same | — |
| `--uc-radius-chip` | `2px` | same | The colour chips of legend and tooltip, and the legend entry's focus. |
| `--uc-shadow` | `0 1px 2px rgba(0, 0, 0, 0.06), 0 4px 12px rgba(0, 0, 0, 0.08)` | same | — |
| `--uc-focus-ring` | `var(`[--u-focus-ring](#token-u-focus-ring)`, 0 0 0 2px #0e7d72)` | same | — |
| `--uc-color-hover` | `var(`[--u-color-surface-sunken](#token-u-color-surface-sunken)`, #f4f4f5)` | same | A legend entry under the pointer and pressed: core's quiet surfaces, and core's motion for a change in place (the interaction-state canon). |
| `--uc-color-pressed` | `var(`[--u-color-surface-pressed](#token-u-color-surface-pressed)`, #e9e9eb)` | same | — |
| `--uc-transition-state` | `var(`[--u-transition](#token-u-transition)`, 120ms cubic-bezier(0.22, 1, 0.36, 1))` | same | — |
| `--uc-transition` | `80ms var(`[--u-ease-out](#token-u-ease-out)`, cubic-bezier(0.22, 1, 0.36, 1))` | same | The tooltip's fade: its own short duration - it follows the pointer and must not lag behind it - on core's curve where core is loaded. |
| `--uc-delay-stale` | `var(`[--u-delay-stale](#token-u-delay-stale)`, 200ms)` | same | A course being reloaded dims as the table's rows do ([ADR-0042](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0042-a-rows-height-never-follows-what-it-shows.md)): only after this delay, so that a quick answer never flickers. |
| `--uc-silhouette` | `color-mix(in srgb, var(`[--u-color-text](#token-u-color-text)`, #18181b) 10%, transparent)` | same | The shapes of the silhouette a chart shows while it waits for its rows (chart-loading 03): faint in the text colour, as the table's placeholders. |
| `--uc-ease-swell` | `var(`[--u-ease-swell](#token-u-ease-swell)`, ease-in-out)` | same | The easing of the band that sweeps the silhouette: it swells as the table's shimmer does. |
| `--uc-fade` | `var(`[--u-duration-medium](#token-u-duration-medium)`, 240ms) var(`[--u-ease-out](#token-u-ease-out)`, cubic-bezier(0.22, 1, 0.36, 1))` | same | The silhouette fading out and the course in, once the rows are there: core's motion for a layout change. |

#### Keyboard

The keys of [Button](#/button/keyboard-button), [Checkbox](#/checkbox/keyboard-checkbox), [Switch](#/switch/keyboard-switch) and [Typography](#/typography/keyboard-typography) apply here.

#### Props on this page

From `StackProps` — the full table stands on [Stack and Grid](#/stack-and-grid/type-StackProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`gap`](#/stack-and-grid/StackProps-gap) | [`SpaceStep`](#/stack-and-grid/type-SpaceStep)<br>`1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8` | `3` | Spacing as a step of the 4 px spacing steps (1–8). |
| [`align`](#/stack-and-grid/StackProps-align) | `CSSProperties["alignItems"]` | — | Alignment across the direction – `alignItems` unchanged. |

From `GridProps` — the full table stands on [Stack and Grid](#/stack-and-grid/type-GridProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`columns`](#/stack-and-grid/GridProps-columns) | `number \| readonly `[`GridColumnWidth`](#/stack-and-grid/type-GridColumnWidth)`[]` | `2` | How many columns, all of one width - or a list with one width per column: a number in pixels, or `"fill"` for a share of what is left. Overridden by minItemWidth. |
| [`minItemWidth`](#/stack-and-grid/GridProps-minItemWidth) | `string` | — | Responsive: as many columns as fit at this minimum width; wins over `columns`, a list included. |
| [`gap`](#/stack-and-grid/GridProps-gap) | [`SpaceStep`](#/stack-and-grid/type-SpaceStep)<br>`1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8` | `4` | Spacing as a step of the 4 px spacing steps (1–8); applies in both directions. |

From `CardHeaderProps` — the full table stands on [Card](#/card/type-CardHeaderProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`title`](#/card/CardHeaderProps-title) *required* | `ReactNode` | — | The heading of the card. A node and not merely text, so that an identifier with markup can stand in it too. |
| [`eyebrow`](#/card/CardHeaderProps-eyebrow) | `ReactNode` | — | Small all-caps label above the title, e.g. a category. |
| [`actions`](#/card/CardHeaderProps-actions) | `ReactNode` | — | Right-aligned area, e.g. buttons or badges. |

From `TextProps` — the full table stands on [Typography](#/typography/type-TextProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`size`](#/typography/TextProps-size) | [`TextSize`](#/typography/type-TextSize)<br>`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` | Type size from the token set. It is independent of the element: a `p` may be small without becoming a different element. |
| [`tone`](#/typography/TextProps-tone) | [`TextTone`](#/typography/type-TextTone)<br>`"default" \| "secondary" \| "muted"` | `"default"` | How loud the text is. `secondary` and `muted` step back without falling below the contrast threshold. |

From `ButtonProps` — the full table stands on [Button](#/button/type-ButtonProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`variant`](#/button/ButtonProps-variant) | [`ButtonVariant`](#/button/type-ButtonVariant)<br>`"primary" \| "secondary" \| "ghost" \| "plain" \| "danger"` | `"secondary"` | How loud the button is. `primary` exactly once per surface - two main actions side by side are no longer a main action. `ghost` is quiet in the accent, `plain` quiet and neutral. |
| [`size`](#/button/ButtonProps-size) | [`ButtonSize`](#/button/type-ButtonSize)<br>`"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for buttons in header bars and table rows, `md` otherwise. |

From `IconButtonProps` — the full table stands on [IconButton](#/iconbutton/type-IconButtonProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`size`](#/iconbutton/IconButtonProps-size) | [`ButtonSize`](#/iconbutton/type-ButtonSize)<br>`"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for buttons in header bars and table rows, `md` otherwise. From `ButtonProps`. |

From `CheckboxProps` — the full table stands on [Checkbox](#/checkbox/type-CheckboxProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`label`](#/checkbox/CheckboxProps-label) | `ReactNode` | — | Label to the right of the checkbox. |

From `SwitchProps` — the full table stands on [Switch](#/switch/type-SwitchProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`label`](#/switch/SwitchProps-label) | `ReactNode` | — | Label to the right of the switch. |

From `BadgeProps` — the full table stands on [Badge](#/badge/type-BadgeProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`tone`](#/badge/BadgeProps-tone) | [`BadgeTone`](#/badge/type-BadgeTone)<br>`"neutral" \| "accent" \| "success" \| "warning" \| "danger"` | `"neutral"` | What the badge stands for. There is always a word beside it: a colour on its own is not a statement. |

#### Known limits

- No theme object, no theme provider and no theme switch: a theme is a set of token overrides in your stylesheet, the mode is the page's `color-scheme` ([ADR-0021](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0021-the-styles-load-themselves-and-touch-nothing-else.md)).
- A token that names another resolves where it is declared: set `--u-color-accent` on a region, and `--u-focus-ring`, which names it on `:root`, still draws the application's accent there. Set the naming token in the region too.
- A panel opened in a portal - a popover, a tooltip, a toast - takes the tokens and the `color-scheme` of the place it lands, not of the region it was opened from; inside a dialog the toasts take the tokens of the dialog's place. Give [UmrissProvider](#/umrissprovider) a `portalTarget` inside the region, or override on `:root` - as for the toasts' distance from the window's edge and its sides, `--u-toast-inset-top`, `--u-toast-inset-bottom`, `--u-toast-inset-start` and `--u-toast-inset-end`.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Sizes

How wide and how tall a field is (width, height, field size). A field fills its place, holds still in a row whatever it shows, takes the width of its value with `chars`, and takes one size from the place it stands in.

```ts
import { ControlSizeProvider } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/sizes/

Width. Say nothing, and a field fills the place that gives it a width - a form's column, a grid's cell, a dialog. Where the place asks the field instead - a row, a toolbar, a column that lines up at the start - the field is its natural width: 16 characters of its own type for a text field, select and combobox, 20 for a multiselect (two chips and the counter), 10 for a number, 40 for a textarea, the longest value of its formats for a date picker. What it shows never moves it: not its value, not its options, not its chips ([ADR-0041](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0041-a-fields-width-never-follows-what-it-shows.md)).

`chars` gives the width in characters - the room for the value, with the field's padding, glyph, cross and steppers added. Given, the field is that wide in every place. Either way it is never wider than its place, and what does not fit ends in an ellipsis.

Height. Every control with two heights takes `size`, `sm` or `md`. `ControlSizeProvider` sets it for a place - a toolbar, a dense form; a control's own `size` wins, and a popover, dialog or tooltip opened from inside starts without it.

#### Examples

##### A field fills its place

Say nothing about width, and a field fills the place it is given - the card's column, a grid's cell. The form below has no width in it but the card's.

```tsx
import { Card, CardBody, FormField, Grid, Input, Select, Stack, Textarea } from "@umriss-ui/core";

export default function FillThePlace() {
  return (
    <Card style={{ maxWidth: 560 }}>
      <CardBody>
        <Stack gap={4}>
          <Grid columns={2} gap={4}>
            <FormField label="First name">
              <Input autoComplete="given-name" />
            </FormField>
            <FormField label="Last name">
              <Input autoComplete="family-name" />
            </FormField>
          </Grid>
          <FormField label="Delivery service">
            <Select defaultValue="standard">
              <option value="standard">Standard, two to three working days</option>
              <option value="express">Express, next working day before noon</option>
            </Select>
          </FormField>
          <FormField label="Note for the driver" hint="Where the parcel may be left if nobody is home.">
            <Textarea rows={2} />
          </FormField>
        </Stack>
      </CardBody>
    </Card>
  );
}
```

##### Sized to the value

Give `chars` the length of the value, and the field is that wide - a postcode five characters, an IBAN twenty-seven - in characters of its own type, with its padding, glyph and steppers added. In a column that lines its fields up at the start, every field shows its own width; a date picker without `chars` is as wide as its longest date. Type a short postcode: the message wraps under its field and moves nothing.

```tsx
import { useState } from "react";
import { DatePicker, FormField, Input, NumberInput, Stack } from "@umriss-ui/core";

export default function SizedToTheValue() {
  const [postcode, setPostcode] = useState("20457");
  const [amount, setAmount] = useState<number | null>(1280.5);
  const [due, setDue] = useState<Date | null>(new Date(2026, 2, 31));
  const wrong = postcode !== "" && !/^\d{5}$/.test(postcode);

  return (
    <Stack gap={4} align="start">
      <Stack direction="row" gap={3} wrap>
        <FormField label="Postcode" error={wrong ? "Five digits." : undefined}>
          <Input
            chars={5}
            inputMode="numeric"
            autoComplete="postal-code"
            value={postcode}
            onChange={(event) => setPostcode(event.target.value)}
          />
        </FormField>
        <FormField label="City">
          <Input autoComplete="address-level2" defaultValue="Hamburg" />
        </FormField>
      </Stack>
      <FormField label="IBAN">
        <Input chars={27} defaultValue="DE89 3704 0044 0532 0130 00" />
      </FormField>
      <FormField label="Amount">
        <NumberInput chars={9} value={amount} onChange={setAmount} decimals={2} suffix="€" />
      </FormField>
      <FormField label="Due">
        <DatePicker value={due} onChange={setDue} clearable />
      </FormField>
    </Stack>
  );
}
```

##### A row that holds still

In a row a field is its natural width - a count of characters of its own type - and never what it shows. Choose carriers, clear them one by one or all at once, pick the long status: nothing in the row moves. The chips that do not fit stand as "+N", and the figures below are the fields' widths, measured live.

```tsx
import { useLayoutEffect, useRef, useState } from "react";
import type { RefObject } from "react";
import { DateRangePicker, Input, MultiSelect, Select, Stack, Switch, Text } from "@umriss-ui/core";
import type { DateRange } from "@umriss-ui/core";

const CARRIERS = ["DHL", "UPS", "DPD", "GLS", "Hermes", "FedEx", "TNT", "DB Schenker", "Kühne + Nagel", "Dachser"].map(
  (name) => ({ value: name, label: name }),
);

/** The rendered width of an element, kept up to date. */
function useWidth(ref: RefObject<HTMLElement | null>) {
  const [width, setWidth] = useState(0);
  useLayoutEffect(() => {
    const element = ref.current;
    if (!element) return;
    const observer = new ResizeObserver(() => setWidth(Math.round(element.getBoundingClientRect().width)));
    observer.observe(element);
    return () => observer.disconnect();
  }, [ref]);
  return width;
}

export default function ARowThatHoldsStill() {
  const [search, setSearch] = useState("");
  const [carriers, setCarriers] = useState<string[]>(["DHL", "UPS", "GLS"]);
  const [period, setPeriod] = useState<DateRange | null>(null);
  const carriersRef = useRef<HTMLDivElement>(null);
  const statusRef = useRef<HTMLSelectElement>(null);
  const carriersWidth = useWidth(carriersRef);
  const statusWidth = useWidth(statusRef);

  return (
    <Stack gap={3}>
      <Stack direction="row" gap={2} align="center" wrap>
        <Input
          aria-label="Search shipments"
          placeholder="Search shipments"
          value={search}
          onChange={(event) => setSearch(event.target.value)}
          clearable
          onClear={() => setSearch("")}
        />
        <Select ref={statusRef} aria-label="Status" defaultValue="">
          <option value="">Every status</option>
          <option>Out for delivery</option>
          <option>Held at customs until the papers of origin are checked</option>
        </Select>
        <MultiSelect ref={carriersRef} aria-label="Carriers" placeholder="Every carrier" options={CARRIERS} value={carriers} onChange={setCarriers} clearable />
        <DateRangePicker aria-label="Shipped" value={period} onChange={setPeriod} clearable />
        <Switch label="Late only" />
      </Stack>
      <Text size="xs" tone="muted" mono>
        carriers: {carriers.length} chosen, {carriersWidth} px wide · status: {statusWidth} px wide
      </Text>
    </Stack>
  );
}
```

##### One size for a place

Wrap a dense place in `ControlSizeProvider size="sm"`, and every control in it is small without a word - fields, buttons, groups. A control's own `size` still wins, and a dialog opened from inside keeps a dialog's controls.

```tsx
import { useState } from "react";
import {
  Button,
  ButtonGroup,
  ControlSizeProvider,
  DatePicker,
  Input,
  Modal,
  ModalBody,
  ModalFooter,
  ModalHeader,
  Select,
  Stack,
} from "@umriss-ui/core";

export default function OneSizeForAPlace() {
  const [day, setDay] = useState<Date | null>(new Date(2026, 2, 17));
  const [open, setOpen] = useState(false);

  return (
    <ControlSizeProvider size="sm">
      <Stack direction="row" gap={2} align="center" wrap>
        <Input aria-label="Search tickets" placeholder="Search tickets" />
        <Select aria-label="Team" defaultValue="all">
          <option value="all">Every team</option>
          <option value="billing">Billing</option>
          <option value="accounts">Accounts</option>
        </Select>
        <DatePicker aria-label="Opened on" value={day} onChange={setDay} />
        <ButtonGroup aria-label="State">
          <Button>Open</Button>
          <Button>Waiting</Button>
          <Button>Solved</Button>
        </ButtonGroup>
        <Button variant="primary" onClick={() => setOpen(true)}>
          New ticket
        </Button>
      </Stack>
      <Modal open={open} onClose={() => setOpen(false)}>
        <ModalHeader title="New ticket" description="Opened from the small bar, it keeps a dialog's controls." />
        <ModalBody>
          <Input aria-label="Subject" placeholder="Subject" />
        </ModalBody>
        <ModalFooter>
          <Button onClick={() => setOpen(false)}>Cancel</Button>
          <Button variant="primary" onClick={() => setOpen(false)}>
            Save
          </Button>
        </ModalFooter>
      </Modal>
    </ControlSizeProvider>
  );
}
```

##### Narrow places

A field is never wider than its place - not with `chars={34}`, not with the longest range of instants. In a narrow card it shrinks with it, and what no longer fits ends in an ellipsis instead of pushing the page sideways.

```tsx
import { useState } from "react";
import { Card, CardBody, CardHeader, DateTimeRangePicker, FormField, Input, MultiSelect, Stack } from "@umriss-ui/core";
import type { DateRange } from "@umriss-ui/core";

const TEAM = ["Maya Lindgren", "Luis Moreno", "Ada Okafor", "Jun Park"].map((name) => ({ value: name, label: name }));

export default function NarrowPlaces() {
  const [slot, setSlot] = useState<DateRange | null>({
    from: new Date(2026, 2, 16, 6, 0),
    to: new Date(2026, 2, 20, 22, 0),
  });
  const [team, setTeam] = useState<string[]>(["Maya Lindgren", "Luis Moreno"]);

  return (
    <Card style={{ maxWidth: 280 }}>
      <CardHeader title="Maintenance window" />
      <CardBody>
        <Stack gap={3}>
          <FormField label="IBAN for the invoice">
            <Input chars={34} defaultValue="GB33 BUKB 2020 1555 5555 55" />
          </FormField>
          <FormField label="Window">
            <DateTimeRangePicker value={slot} onChange={setSlot} />
          </FormField>
          <FormField label="On call">
            <MultiSelect options={TEAM} value={team} onChange={setTeam} />
          </FormField>
        </Stack>
      </CardBody>
    </Card>
  );
}
```

##### A row of fields

Fields side by side share one line: their labels on one line, their boxes on one height, their words on the line the select's value stands on. A segmented control is as tall as a field; a horizontal radio group is as tall as a control, and so are a checkbox and a switch in a field, so their words stand on that line too - at either size.

```tsx
import { Checkbox, ControlSizeProvider, FormField, RadioGroup, SegmentedControl, Select, Stack, Switch } from "@umriss-ui/core";
import type { ControlSize } from "@umriss-ui/core";

function Row({ size }: { size: ControlSize }) {
  return (
    <Stack role="group" aria-label={size === "sm" ? "Small" : "Medium"} direction="row" gap={3} wrap>
      <FormField label="Caster">
        <Select defaultValue="" chars={12}>
          <option value="">Every caster</option>
          <option>Caster 1</option>
          <option>Caster 2</option>
        </Select>
      </FormField>
      <FormField label="Strand">
        <Select defaultValue="" chars={12}>
          <option value="">Every strand</option>
          <option>Strand 1</option>
          <option>Strand 2</option>
        </Select>
      </FormField>
      <FormField label="State of the data">
        <RadioGroup
          orientation="horizontal"
          defaultValue="raw"
          options={[
            { value: "raw", label: "Raw" },
            { value: "cleaned", label: "Cleaned" },
          ]}
        />
      </FormField>
      <FormField label="Values">
        <SegmentedControl
          defaultValue="measured"
          options={[
            { value: "measured", label: "Measured" },
            { value: "forecast", label: "Forecast" },
          ]}
        />
      </FormField>
      <FormField label="Archive">
        <Checkbox label="Show archived" />
      </FormField>
      <FormField label="Updates">
        <Switch label="Live" defaultChecked />
      </FormField>
    </Stack>
  );
}

export default function ARowOfFields() {
  return (
    <Stack gap={5}>
      <Row size="md" />
      <ControlSizeProvider size="sm">
        <Row size="sm" />
      </ControlSizeProvider>
    </Stack>
  );
}
```

##### A bar with a search

A field does not grow to fill a row; a bar of one's own says which one takes the rest. In a grid, a field fills its cell: the search is the "fill" column, the selects beside it keep a width of their own, and nothing is styled by hand.

```tsx
import { useState } from "react";
import { Grid, Input, Select, Stack, Text } from "@umriss-ui/core";

const ROWS = [
  { name: "Invoice 1042", status: "Open", region: "North" },
  { name: "Invoice 1043", status: "Paid", region: "South" },
  { name: "Invoice 1044", status: "Open", region: "South" },
  { name: "Invoice 1045", status: "Overdue", region: "North" },
];

export default function ABarWithASearch() {
  const [search, setSearch] = useState("");
  const [status, setStatus] = useState("");
  const [region, setRegion] = useState("");
  const shown = ROWS.filter(
    (row) =>
      row.name.toLowerCase().includes(search.trim().toLowerCase()) &&
      (!status || row.status === status) &&
      (!region || row.region === region),
  );
  return (
    <Stack gap={3}>
      <Grid columns={["fill", 180, 180]} gap={3}>
        <Input
          type="search"
          aria-label="Search"
          placeholder="Search invoices"
          value={search}
          onChange={(event) => setSearch(event.target.value)}
        />
        <Select aria-label="Status" value={status} onChange={(event) => setStatus(event.target.value)}>
          <option value="">Any status</option>
          <option>Open</option>
          <option>Paid</option>
          <option>Overdue</option>
        </Select>
        <Select aria-label="Region" value={region} onChange={(event) => setRegion(event.target.value)}>
          <option value="">Any region</option>
          <option>North</option>
          <option>South</option>
        </Select>
      </Grid>
      <Text size="sm" tone="secondary">
        {shown.length} of {ROWS.length} invoices: {shown.map((row) => row.name).join(", ") || "none"}
      </Text>
    </Stack>
  );
}
```

#### When to use something else

- A width the layout decides - two columns, a field beside a button → Stack and Grid
- A whole table's density, rows and controls together → UmrissProvider

#### Keyboard

The keys of [Button](#/button/keyboard-button), [ButtonGroup](#/buttongroup/keyboard-buttongroup), [Input](#/input/keyboard-input), [Textarea](#/textarea/keyboard-textarea), [NumberInput](#/numberinput/keyboard-numberinput), [Switch](#/switch/keyboard-switch), [Select](#/select/keyboard-select), [MultiSelect](#/multiselect/keyboard-multiselect), [DatePicker](#/datepicker/keyboard-datepicker), [DateRangePicker](#/daterangepicker/keyboard-daterangepicker), [DateTimeRangePicker](#/datetimerangepicker/keyboard-datetimerangepicker) and [Modal](#/modal/keyboard-modal) apply here.

#### API

##### `ControlSizeProviderProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `size` *required* | [`ControlSize`](#type-ControlSize)<br>`"sm" \| "md"` | — | The size of every control inside that does not say its own.<br>Shown in: [One size for a place](#/sizes/one-size-for-a-place), [A row of fields](#/sizes/a-row-of-fields), [Drawn as a field (SegmentedControl)](#/segmentedcontrol/drawn-as-a-field) |
| `children` *required* | `ReactNode` | — | The place the size holds for.<br>Shown in: [One size for a place](#/sizes/one-size-for-a-place), [A row of fields](#/sizes/a-row-of-fields), [Drawn as a field (SegmentedControl)](#/segmentedcontrol/drawn-as-a-field) |

##### Types on this page

###### `ControlSize`

The two heights of a control: `sm` for a toolbar and dense forms, `md`
otherwise.

```ts
type ControlSize = "sm" | "md";
```

#### Known limits

- No width in pixels: a width in characters scales with the type, under a finger too; a place's width is the layout's.
- `Slider` and `FileInput` take no `chars` - they show no text to count; their width is the place's, or their natural width where the place asks.
- A field does not grow to fill a row: give it room with the row's own layout (`flex: 1` on its FormField, or a grid).
- A place that sizes itself by its content and has no width to stop at - an `auto` grid track, an inline block, a row that does not wrap - gives a field at least its natural width, as it gives a native input its own; on a narrow screen let such a row wrap, or size the track with `minmax(0, auto)`.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Language

The words and the number and date notation the components write themselves: English by default, German in one import, and any single entry your own. Wording is a directory of named entries, not a translation call (also called i18n or localisation).

```ts
import { LanguageProvider, useWording, useFormats } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/language/

English needs nothing ([ADR-0018](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0018-everything-is-english.md)). German ships as the subpath `@umriss-ui/core/wording/de` with `GERMAN_WORDING` and `GERMAN_FORMATS`, the two halves of a language; take both in one import ([ADR-0019](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0019-two-wordings-ship-english-is-the-default.md), [ADR-0024](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0024-the-formats-are-english-german-is-freight.md)).

Pass them to the `language` of [UmrissProvider](#/umrissprovider) for the application, or to `LanguageProvider` for one section. Both merge entry by entry: what you leave out keeps its default. Every wording is typed `Wording`, so a whole language of your own misses no entry without a compile error.

#### Examples

##### German

Import both halves of German from `@umriss-ui/core/wording/de`; the components' own words and notation change, your labels stay as written.

```tsx
import { useState } from "react";
import { DatePicker, FormField, LanguageProvider, NumberInput, Stack } from "@umriss-ui/core";
import { GERMAN_FORMATS, GERMAN_WORDING } from "@umriss-ui/core/wording/de";

export default function German() {
  const [date, setDate] = useState<Date | null>(new Date(2026, 2, 18));
  const [weight, setWeight] = useState<number | null>(1284.5);

  return (
    <LanguageProvider wording={GERMAN_WORDING} formats={GERMAN_FORMATS}>
      <Stack direction="row" gap={3} wrap>
        <FormField label="Delivery date">
          <DatePicker value={date} onChange={setDate} clearable />
        </FormField>
        <FormField label="Weight">
          <NumberInput value={weight} onChange={setWeight} decimals={1} suffix="kg" />
        </FormField>
      </Stack>
    </LanguageProvider>
  );
}
```

##### English and German side by side

The same surface without a provider and under German: verdicts, placeholders and number notation move, the caller's labels and data stay.

```tsx
import { Combobox, FormField, Grid, LanguageProvider, Stack, Stat, Text } from "@umriss-ui/core";
import type { LimitSet } from "@umriss-ui/core";
import { GERMAN_FORMATS, GERMAN_WORDING } from "@umriss-ui/core/wording/de";

/* The p95 latency objective of the checkout service: 300 ms. */
const OBJECTIVE: LimitSet = {
  target: 250,
  limits: [
    { value: 270, side: "upper", severity: "warning" },
    { value: 300, side: "upper", severity: "alarm" },
  ],
};

const ENGINEERS = [
  { value: "priya", label: "Priya Raman" },
  { value: "jonas", label: "Jonas Keller" },
  { value: "ada", label: "Ada Mwangi" },
];

function Surface() {
  return (
    <Stack gap={3}>
      <Stat label="Checkout p95" value={312} unit="ms" limits={OBJECTIVE} />
      <Stat label="Search p95" value={null} unit="ms" limits={OBJECTIVE} />
      <Stat label="Requests today" value={1284311} decimals={0} />
      <FormField label="Assignee">
        <Combobox value={null} onChange={() => {}} clearable options={ENGINEERS} />
      </FormField>
    </Stack>
  );
}

export default function SideBySide() {
  return (
    <Grid minItemWidth="240px" gap={5}>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          Without a provider
        </Text>
        <Surface />
      </Stack>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          GERMAN_WORDING and GERMAN_FORMATS
        </Text>
        <LanguageProvider wording={GERMAN_WORDING} formats={GERMAN_FORMATS}>
          <Surface />
        </LanguageProvider>
      </Stack>
    </Grid>
  );
}
```

##### Replace single entries

Pass only the entries your application says differently; every entry you leave out keeps its default, never an empty text or a key.

```tsx
import { Grid, LanguageProvider, Stack, Stat, Text } from "@umriss-ui/core";
import type { LanguageOptions, LimitSet } from "@umriss-ui/core";

/* Outside the component, so the provider does not rebuild on every render. */
const WORDING: LanguageOptions["wording"] = {
  verdictOk: "Within objective",
  verdictWarning: "Objective at risk",
  verdictAlarm: "Objective breached",
};

const OBJECTIVE: LimitSet = {
  target: 250,
  limits: [
    { value: 270, side: "upper", severity: "warning" },
    { value: 300, side: "upper", severity: "alarm" },
  ],
};

function Surface() {
  return (
    <Stack gap={3}>
      <Stat label="Sign-in p95" value={184} unit="ms" limits={OBJECTIVE} />
      <Stat label="Search p95" value={276} unit="ms" limits={OBJECTIVE} />
      <Stat label="Checkout p95" value={312} unit="ms" limits={OBJECTIVE} />
      <Stat label="Billing p95" value={null} unit="ms" limits={OBJECTIVE} />
    </Stack>
  );
}

export default function SingleEntries() {
  return (
    <Grid minItemWidth="240px" gap={5}>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          The defaults
        </Text>
        <Surface />
      </Stack>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          Three entries replaced
        </Text>
        <LanguageProvider wording={WORDING}>
          <Surface />
        </LanguageProvider>
      </Stack>
    </Grid>
  );
}
```

##### Write numbers in your own notation

Formats are a register of their own: replace `number` and `count` for Swiss notation and every word stays English.

```tsx
import { Grid, LanguageProvider, Stack, Stat, Text } from "@umriss-ui/core";
import type { LanguageOptions } from "@umriss-ui/core";

/* Formatters are costly to build: one per number of decimals, made once. */
const swiss = new Map<number | undefined, Intl.NumberFormat>();
function number(n: number, decimals?: number) {
  let format = swiss.get(decimals);
  if (!format) {
    format = new Intl.NumberFormat("de-CH", { minimumFractionDigits: decimals, maximumFractionDigits: decimals ?? 10 });
    swiss.set(decimals, format);
  }
  return format.format(n);
}
const swissCount = new Intl.NumberFormat("de-CH");

const FORMATS: LanguageOptions["formats"] = {
  number,
  count: (n) => swissCount.format(n),
};

function Surface() {
  return (
    <Stack gap={3}>
      <Stat label="Engineering, actual March" value={196420.5} decimals={2} unit="CHF" />
      <Stat label="Invoices booked" value={1284} decimals={0} />
    </Stack>
  );
}

export default function OwnNotation() {
  return (
    <Grid minItemWidth="240px" gap={5}>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          The default notation
        </Text>
        <Surface />
      </Stack>
      <Stack gap={2}>
        <Text size="xs" tone="muted">
          Swiss notation, English words
        </Text>
        <LanguageProvider formats={FORMATS}>
          <Surface />
        </LanguageProvider>
      </Stack>
    </Grid>
  );
}
```

##### Use the language in your own components

Read [`useFormats`](#/api/useFormats) and [`useWording`](#/api/useWording) in a component of your own, and it writes dates and numbers like the library, under any provider.

```tsx
import { Button, Grid, LanguageProvider, Stack, Text, useFormats, useWording } from "@umriss-ui/core";
import { GERMAN_FORMATS, GERMAN_WORDING } from "@umriss-ui/core/wording/de";

const SPRINT_END = new Date(2026, 2, 27, 17, 0);

function SprintHeader() {
  const formats = useFormats();
  const wording = useWording();
  return (
    <Stack direction="row" gap={3} align="center" wrap>
      <Text size="sm">
        Sprint 14 ends <Text as="span" mono>{formats.dateTime(SPRINT_END, false)}</Text> ·{" "}
        <Text as="span" mono>{formats.count(1240)}</Text> points delivered this year
      </Text>
      <Button size="sm" variant="ghost">
        {wording.today}
      </Button>
    </Stack>
  );
}

export default function OwnComponents() {
  return (
    <Grid minItemWidth="280px" gap={5}>
      <SprintHeader />
      <LanguageProvider wording={GERMAN_WORDING} formats={GERMAN_FORMATS}>
        <SprintHeader />
      </LanguageProvider>
    </Grid>
  );
}
```

#### Wording

Every entry of `Wording`: the English of `DEFAULT_WORDING` beside the German of `GERMAN_WORDING`. A function entry receives the parameters its key names and returns the sentence beside it. Override any entry by its key; a `presets` entry inside `presets`.

##### Inputs

| Key | English | German | Description |
|---|---|---|---|
| `clearInput` | Clear input | Eingabe leeren | The cross in the text field. |
| `clearSelection` | Clear selection | Auswahl leeren | The cross in the select and in the combobox. |
| `decreaseValue` | Decrease value | Wert verringern | Stepper buttons of the number field. |
| `increaseValue` | Increase value | Wert erhöhen | — |

##### Combobox and multi-select

| Key | English | German | Description |
|---|---|---|---|
| `comboboxPlaceholder` | Search or select | Suchen oder wählen | — |
| `noMatches` | No matches | Keine Treffer | Empty state of both lists. |
| `multiSelectPlaceholder` | Select | Auswählen | — |
| `multiSelectSearchPlaceholder` | Search | Suchen | — |
| `searchOptions` | Search options | Optionen durchsuchen | — |
| `options` | Options | Optionen | Group name of the option list. |
| `optionScope` | View | Ansicht | Group name of the scope switch. |
| `optionScopeAll` | All | Alle | — |
| `optionScopeSelected(count)` | `` `Selected (${count})` `` | `` `Gewählte (${count})` `` | The second scope, with the count in the text. |
| `selectAll` | All | Alle | — |
| `selectNone` | None | Keine | — |
| `invertSelection` | Invert | Umkehren | — |
| `nothingSelected` | Nothing selected | Nichts ausgewählt | — |
| `removeSelectedValue(beschriftung)` | `` `Remove ${beschriftung}` `` | `` `${label} entfernen` `` | The cross on a selected value in the trigger. |
| `manageMoreSelected(count)` | `` `Manage all ${count} selected` `` | `` `Alle ${count} Gewählten verwalten` `` | The "+N" counter in the trigger. |
| `multiSelectSummary(gewaehlt, total)` | `` `${gewaehlt} / ${total}` `` | `` `${selected} / ${total}` `` | The summary in the panel: "3 / 12". The sentence structure belongs to the language, even where it is only a slash here. |
| `optionCount(count)` | `` (count === 1 ? "1 option" : `${count} options`) `` | `` (count === 1 ? "1 Option" : `${count} Optionen`) `` | How many options stand, when a list opens or its filter changes; never zero - an empty list says its own empty text. Named, like the three below, after the moment it is spoken in: an announcement labels no element. |
| `optionActive(label, state)` | `[label, group, selected && "selected", disabled && "unavailable"].filter(Boolean).join(", ")` | `[label, group, selected && "ausgewählt", disabled && "nicht verfügbar"].filter(Boolean).join(", ")` | The option the keys moved onto, with what VoiceOver leaves out. |
| `optionAdded(label)` | `` `${label} added` `` | `` `${label} hinzugefügt` `` | A value the multi-select took or gave away where no checkbox had the focus to say it - Enter in the search, a chip, Backspace. |
| `optionRemoved(label)` | `` `${label} removed` `` | `` `${label} entfernt` `` | — |

##### Command palette

| Key | English | German | Description |
|---|---|---|---|
| `palettePlaceholder` | Search … | Suchen … | What stands in the empty field. |
| `paletteField` | Search | Suchen | Accessible name of the field. Deliberately kept apart from the placeholder - whoever labels the field differently does not thereby rename the window. |
| `palettePanel` | Command palette | Befehlspalette | Accessible name of the window. |
| `paletteList` | Finds | Funde | Accessible name of the list of finds. |
| `paletteNoFinds` | Nothing found | Nichts gefunden | The one line when the query finds nothing. |
| `paletteFindCount(count)` | `` (count === 1 ? "1 find" : `${count} finds`) `` | `` (count === 1 ? "1 Fund" : `${count} Funde`) `` | What the screen reader hears when the number of finds changes. |
| `paletteMoreFinds(count)` | `` (count === 1 ? "1 more find" : `${count} more finds`) `` | `` (count === 1 ? "1 weiterer Fund" : `${count} weitere Funde`) `` | The last line when more finds exist than `maxFinds` lets stand. |
| `paletteHintMove` | select | wählen | The three key hints in the footer, each the text beside the key. |
| `paletteHintChoose` | open | öffnen | — |
| `paletteHintClose` | close | schließen | — |
| `paletteKeyEsc` | Esc | Esc | The legend on the Escape key. The arrows and the return key are glyphs and therefore do not stand here; "Esc" is a word and is called something else elsewhere. |

##### Date and time

| Key | English | German | Description |
|---|---|---|---|
| `datePlaceholder` | Select date | Datum wählen | — |
| `datePanel` | Select date | Datum wählen | Accessible name of the panel. Deliberately kept apart from the placeholder: whoever labels the field differently does not thereby rename the dialog. |
| `dateClear` | Clear date | Datum leeren | — |
| `dateTimePlaceholder` | Select date and time | Datum und Zeit wählen | — |
| `dateTimePanel` | Select date and time | Datum und Zeit wählen | — |
| `dateTimeClear` | Clear date and time | Datum und Zeit leeren | — |
| `dateRangePlaceholder` | Select range | Zeitraum wählen | — |
| `dateRangePanel` | Select range | Zeitraum wählen | — |
| `dateRangeClear` | Clear range | Zeitraum leeren | — |
| `dateTimeRangePanel` | Select range with time | Zeitraum mit Uhrzeit wählen | Accessible name of the panel in the range with time of day. |
| `dateTimeRangeClear` | Clear range with time | Zeitraum mit Uhrzeit leeren | The clearing x of the range with time - kept apart from the range without, so that an application can call the two differently. |
| `previousMonth` | Previous month | Voriger Monat | — |
| `nextMonth` | Next month | Nächster Monat | — |
| `quickSelect` | Quick select | Schnellwahl | Group name of the preset column. |
| `today` | Today | Heute | — |
| `now` | Now | Jetzt | — |
| `clear` | Clear | Leeren | — |
| `apply` | Apply | Übernehmen | — |
| `allDay` | All day | Ganztägig | — |
| `timeOfDay` | Time | Uhrzeit | — |
| `hour` | Hour | Stunde | — |
| `minute` | Minute | Minute | — |
| `second` | Second | Sekunde | — |
| `sideFrom` | From | Von | Header of the two time columns in the range with time of day. |
| `sideTo` | To | Bis | — |
| `startHour` | Start hour | Startstunde | Accessible name of the time fields, per side. |
| `startMinute` | Start minute | Startminute | — |
| `startSecond` | Start second | Startsekunde | — |
| `endHour` | End hour | Endstunde | — |
| `endMinute` | End minute | Endminute | — |
| `endSecond` | End second | Endsekunde | — |
| `timeFieldIncrease(feld)` | `` `Increase ${feld}` `` | `` `${field} erhöhen` `` | Stepper buttons of a time field; the label comes from above. |
| `timeFieldDecrease(feld)` | `` `Decrease ${feld}` `` | `` `${field} verringern` `` | — |
| `chooseStartDate` | Select start date | Startdatum wählen | Footer of the range panels. |
| `chooseEndDate` | Select end date – backwards is allowed | Enddatum wählen – rückwärts ist erlaubt | — |
| `days(count)` | `` `${count} ${count === 1 ? "day" : "days"}` `` | `` `${count} ${count === 1 ? "Tag" : "Tage"}` `` | "3 days" or "1 day" - the plural belongs to the language. |
| `daysSelected(count)` | `` `${count} ${count === 1 ? "day" : "days"} selected` `` | `` `${count} ${count === 1 ? "Tag" : "Tage"} gewählt` `` | "3 days selected" |
| `rangePreview(from, to, count)` | `` `${from} – ${to} · ${count} ${count === 1 ? "day" : "days"}` `` | `` `${from} – ${to}\u2009·\u2009${count} ${count === 1 ? "Tag" : "Tage"}` `` | "17.03. – 19.03. · 3 days" while dragging; the dates come from the formats. |
| `daysAllDay(count)` | `` `${count} ${count === 1 ? "day" : "days"} (all day)` `` | `` `${count} ${count === 1 ? "Tag" : "Tage"} (ganztägig)` `` | "3 days (all day)" |
| `duration(teile)` | `` `Duration: ${teile.join(" ")}` `` | `` `Dauer: ${parts.join(" ")}` `` | "Duration: 1 day 2 hrs 30 min" |
| `hoursShort(count)` | `` `${count} ${count === 1 ? "hr" : "hrs"}` `` | `` `${count} Std` `` | — |
| `minutesShort(count)` | `` `${count} min` `` | `` `${count} Min` `` | — |
| `timeMissingHint(timeOfDay)` | `` `This time does not exist on this day (start of daylight saving time). ${timeOfDay} is used instead.` `` | `` `Diese Uhrzeit existiert an diesem Tag nicht (Beginn der Sommerzeit). Es wird ${timeOfDay} Uhr verwendet.` `` | Daylight-saving change: the hour that does not exist. |
| `timeMissingHintSide(side, timeOfDay)` | `` `${side}: This time does not exist on this day (start of daylight saving time). ${timeOfDay} is used instead.` `` | `` `${side}: Diese Uhrzeit existiert an diesem Tag nicht (Beginn der Sommerzeit). Es wird ${timeOfDay} Uhr verwendet.` `` | The same, with the side put in front ("From"/"To"). |
| `timeAmbiguousHint` | This time occurs twice on this day (end of daylight saving time): | Diese Uhrzeit kommt an diesem Tag zweimal vor (Ende der Sommerzeit): | Daylight-saving change: the hour that occurs twice. |
| `timeAmbiguousHintSide(side)` | `` `${side}: This time occurs twice on this day (end of daylight saving time):` `` | `` `${side}: Diese Uhrzeit kommt an diesem Tag zweimal vor (Ende der Sommerzeit):` `` | — |
| `timeEarlier(versatz)` | `` `Earlier (${versatz})` `` | `` `Frühere (${offset})` `` | — |
| `timeLater(versatz)` | `` `Later (${versatz})` `` | `` `Spätere (${offset})` `` | — |
| `weekdays` | `["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]` | `["Mo", "Di", "Mi", "Do", "Fr", "Sa", "So"]` | The calendar's weekday headers, starting at Monday. |
| `presets.today` | Today | Heute | The quick-select ranges, in the order of PRESET_LABELS. |
| `presets.yesterday` | Yesterday | Gestern | The quick-select ranges, in the order of PRESET_LABELS. |
| `presets.last7Days` | Last 7 days | Letzte 7 Tage | The quick-select ranges, in the order of PRESET_LABELS. |
| `presets.last30Days` | Last 30 days | Letzte 30 Tage | The quick-select ranges, in the order of PRESET_LABELS. |
| `presets.thisMonth` | This month | Dieser Monat | The quick-select ranges, in the order of PRESET_LABELS. |
| `presets.previousMonth` | Previous month | Voriger Monat | The quick-select ranges, in the order of PRESET_LABELS. |
| `presets.thisQuarter` | This quarter | Dieses Quartal | The quick-select ranges, in the order of PRESET_LABELS. |
| `presets.thisYear` | This year | Dieses Jahr | The quick-select ranges, in the order of PRESET_LABELS. |

##### Table

| Key | English | German | Description |
|---|---|---|---|
| `pagination` | Pagination | Seitennavigation | — |
| `rows` | Rows | Zeilen | — |
| `rowsPerPage` | Rows per page | Zeilen pro Seite | — |
| `pageOfPages(page, total, formatted)` | `` `Page ${formatted?.page ?? page} of ${formatted?.total ?? total}` `` | `` `Seite ${formatted?.page ?? page} von ${formatted?.total ?? total}` `` | "Page 2 of 7". `formatted` carries both numbers in the provider's formats, where the caller has them - a table over a server has "Page 1 of 100,000". |
| `previousPage` | Back | Zurück | — |
| `nextPage` | Next | Weiter | — |
| `filterReset` | Reset | Zurücksetzen | The two buttons in the column filter's footer. |
| `filterDone` | Done | Fertig | — |

##### @umriss-ui/table

| Key | English | German | Description |
|---|---|---|---|
| `columns` | Columns | Spalten | The column menu's button. |
| `arrangeColumns` | Show, hide and arrange columns | Spalten ein- und ausblenden, anordnen | Accessible name of the list in the column menu. |
| `columnForward(column)` | `` `Move ${column} forward` `` | `` `${column} nach vorn` `` | The two buttons that move a column in the column menu. |
| `columnBackward(column)` | `` `Move ${column} backward` `` | `` `${column} nach hinten` `` | — |
| `pinColumnToStart(column)` | `` `Pin ${column} to start` `` | `` `${column} am Anfang fixieren` `` | The column menu's pin keys: to a side, and back when it is pinned there. |
| `pinColumnToEnd(column)` | `` `Pin ${column} to end` `` | `` `${column} am Ende fixieren` `` | — |
| `unpinColumn(column)` | `` `Unpin ${column}` `` | `` `Fixierung von ${column} lösen` `` | — |
| `columnForwardHint` | Move forward | Nach vorn | The tooltips over those four keys: short, without the column, which stands in the same line. The keys' names above keep it for a screen reader. |
| `columnBackwardHint` | Move backward | Nach hinten | — |
| `pinToStartHint` | Pin to start | Am Anfang fixieren | — |
| `pinToEndHint` | Pin to end | Am Ende fixieren | — |
| `unpinHint` | Unpin | Fixierung lösen | — |
| `exportLabel` | Export | Exportieren | The export button. |
| `exportPageLabel` | Export page | Seite exportieren | The export button of a table in server mode, which holds and writes one page. |
| `exportFileName` | table.csv | tabelle.csv | The export's file name, where the application names none. |
| `tableSearchPlaceholder` | Search … | Suchen … | Placeholder and accessible name of the search field. |
| `tableSearchLabel` | Search table | Tabelle durchsuchen | — |
| `filterColumn(column)` | `` `Filter ${column}` `` | `` `${column} filtern` `` | The filter button of a column: "Filter Region". |
| `filterHint` | Filter | Filtern | The tooltip over that button. |
| `selectRow(row)` | `` `Select ${row}` `` | `` `${row} auswählen` `` | The selection of one row, named after its row header. |
| `selectAllRows` | Select all | Alle auswählen | The selection of every row in the filtered set. |
| `selectAllOnPage` | Select all on this page | Alle auf dieser Seite auswählen | The same checkbox in server mode, where the table holds one page of a server's. |
| `expandRowNamed(row)` | `` `Expand ${row}` `` | `` `${row} aufklappen` `` | The expand button, named after the row header. |
| `collapseRowNamed(row)` | `` `Collapse ${row}` `` | `` `${row} zuklappen` `` | — |
| `rowActions` | Actions | Aktionen | Header of the actions column - for the screen reader, not visible. |
| `rowAction(aktion, row)` | `` `${aktion}: ${row}` `` | `` `${action}: ${row}` `` | One action on a row: "Open: A-2041". |
| `rowActionsMenu(row)` | `` `Actions: ${row}` `` | `` `Aktionen: ${row}` `` | The menu holding a row's actions. |
| `editCell(column, row)` | `` `Edit ${column}: ${row}` `` | `` `${column} bearbeiten: ${row}` `` | The editor of a cell in a table's grid mode, named after its column and its row: "Edit Budget: Marketing". |
| `newRow` | New row | Neue Zeile | The button above a grid that opens an empty row to fill in, and the name of that row while it has none ([ADR-0036](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0036-a-grid-edits-on-the-first-click-and-saves-rows-on-purpose.md)). |
| `saveRow` | Save | Speichern | A row draft's buttons, named with the row through `rowAction`. |
| `discardRow` | Discard | Verwerfen | — |
| `deleteRow` | Delete | Löschen | A row's delete button, and its question once pressed: Delete? Delete / Keep. |
| `deleteRowAsk` | Delete? | Löschen? | — |
| `keepRow` | Keep | Behalten | — |
| `saveOrDiscardFirst` | Save or discard this row first | Erst diese Zeile speichern oder verwerfen | Said where someone tries to leave a row draft unsaved. |
| `cellAbsentValue` | No value | Kein Wert | What the screen reader hears for an absent value. Visibly a muted dash stands there. |
| `booleanYes` | Yes | Ja | A boolean without a presentation of its own. |
| `booleanNo` | No | Nein | — |
| `footerSum` | Sum | Summe | The kind of a footer number, read out before the number. |
| `footerAverage` | Average | Durchschnitt | — |
| `footerMinimum` | Minimum | Minimum | — |
| `footerMaximum` | Maximum | Maximum | — |
| `footerRange` | Range | Spanne | — |
| `footerCount` | Count | Anzahl | — |
| `footerDistinct` | Distinct values | Verschiedene Werte | — |
| `footerAggregate` | Aggregate | Aggregat | An aggregate the application computes itself. |
| `grouping` | Grouping | Gruppierung | The grouping section of the column menu, and the menu entry per column. |
| `groupBy(label)` | `` `Group by ${label}` `` | `` `Nach ${label} gruppieren` `` | — |
| `groupedBy` | Grouped by | Gruppiert nach | The grouping's tag in the table toolbar: "Grouped by" Region › Customer. |
| `removeGrouping` | Remove grouping | Gruppierung aufheben | — |
| `removeGroupingLevel(label)` | `` `Stop grouping by ${label}` `` | `` `Nicht mehr nach ${label} gruppieren` `` | — |
| `foldAll` | Fold all | Alle zuklappen | — |
| `unfoldAll` | Unfold all | Alle aufklappen | — |
| `groupNoValue` | No value | Kein Wert | The group of rows without a value. |
| `groupContinued` | continued | Fortsetzung | Beside a group repeated at the top of a page that begins inside it. |
| `foldGroup(name, count)` | `` `Fold ${name}, ${count}` `` | `` `${name} zuklappen, ${count}` `` | The fold of a group, with its value and its count. |
| `unfoldGroup(name, count)` | `` `Unfold ${name}, ${count}` `` | `` `${name} aufklappen, ${count}` `` | — |
| `foldBranch(row)` | `` `Fold rows under ${row}` `` | `` `Zeilen unter ${row} zuklappen` `` | The fold of a branch in a table with tree rows, named after its row - not `expandRowNamed`, which names the row detail's expander on the same row. |
| `unfoldBranch(row)` | `` `Unfold rows under ${row}` `` | `` `Zeilen unter ${row} aufklappen` `` | — |
| `levelColumn` | Level | Ebene | The first column of a tree's export. |
| `pathRow` | on the path to a match | auf dem Weg zu einem Treffer | A row shown only because a descendant matches the search or a filter. |
| `footerTopLevel` | Top level only | Nur oberste Ebene | The footer of a tree: it sums the top level, since a parent holds its children. |
| `selectGroup(name)` | `` `Select ${name}` `` | `` `${name} auswählen` `` | The box that selects every row of a group. |
| `calendarWeek(week, year)` | `` `Week ${week}, ${year}` `` | `` `KW ${week}/${year}` `` | A group of the week key: "Week 42, 2026". |
| `entries(count, formatted)` | `` (count === 1 ? "1 entry" : `${formatted} entries`) `` | `` (count === 1 ? "1 Eintrag" : `${formatted} Einträge`) `` | "128 entries" in the pagination bar; the plural belongs to the language. |
| `selectedCount(count, formatted)` | `` `${formatted} selected` `` | `` `${formatted} ausgewählt` `` | "3 selected" in the pagination bar and the table toolbar. |
| `copiedRows(count, formatted)` | `` (count === 1 ? "1 row copied" : `${formatted} rows copied`) `` | `` (count === 1 ? "1 Zeile kopiert" : `${formatted} Zeilen kopiert`) `` | Said to a screen reader after Ctrl+C copied rows: "3 rows copied". |
| `copiedCell` | Cell copied | Zelle kopiert | Said after Ctrl+C copied the active cell of a grid. |
| `copyFailed` | Could not copy | Kopieren nicht möglich | Said when the clipboard refused or is not there. |
| `noEntries` | No entries | Keine Einträge | Empty because there are no rows. |
| `nothingMatchesFilters` | Nothing matches the search and filters | Nichts passt zu Suche und Filtern | Empty because search and filters leave nothing - something else. |
| `treeSearchPlaceholder` | Search the tree … | Im Baum suchen … | — |
| `treeNoMatches` | Nothing matches the search. | Nichts passt zur Suche. | — |
| `conditions` | Active filters | Aktive Filter | Group name of the conditions in the table toolbar. |
| `removeConditionNamed(label, value)` | `` `Remove ${label}: ${value}` `` | `` `${label}: ${value} entfernen` `` | The button that removes a condition: "Remove Region: EU, US". |
| `editConditionNamed(label, value)` | `` `Edit ${label}: ${value}` `` | `` `${label}: ${value} bearbeiten` `` | The condition itself, which opens its filter: "Edit Region: EU, US". |
| `moreValues(count, formatted)` | `` `+${formatted}` `` | `` `+${formatted}` `` | The remainder of a long list in a condition: "+1". |
| `filterFrom` | From | Von | The two fields of the range filter. |
| `filterTo` | To | Bis | — |
| `rangeFromTo(from, to)` | `` `${from}–${to}` `` | `` `${from}–${to}` `` | The condition of a range filter: "100–500", "from 100", "to 500". |
| `rangeFrom(from)` | `` `from ${from}` `` | `` `ab ${from}` `` | — |
| `rangeTo(to)` | `` `to ${to}` `` | `` `bis ${to}` `` | — |
| `rangeInvalid` | “From” lies after “To”. | „Von“ liegt hinter „Bis“. | When "From" lies behind "To". The condition stays the last valid one. |
| `resetAll` | Reset | Zurücksetzen | Clears search and conditions - in the table toolbar and in the empty body. |
| `filteredOfTotal(matches, total)` | `` `${matches} of ${total}` `` | `` `${matches} von ${total}` `` | "43 of 1.204" - the numbers come from the formats. |

##### Stat, verdict, freshness

| Key | English | German | Description |
|---|---|---|---|
| `verdictOk` | OK | In Ordnung | The four outcomes of an assessment, as a word beside the value. Colour alone carries no meaning - the word stands here for that reason. |
| `verdictWarning` | Warning limit exceeded | Warngrenze überschritten | — |
| `verdictAlarm` | Alarm limit exceeded | Alarmgrenze überschritten | — |
| `verdictUnknown` | No value | Kein Wert | — |
| `statAbsentValue` | — | — | What stands in the value field when there is no value. No dash, no zero: either could be a value. |
| `target` | Target | Ziel | — |
| `deviationAbove(betrag)` | `` `${betrag} above target` `` | `` `${amount} über Ziel` `` | "3,2 above target" or "1,5 below target" - the amount comes from the formats, which is where the comma is from. |
| `deviationBelow(betrag)` | `` `${betrag} below target` `` | `` `${amount} unter Ziel` `` | — |
| `deviationOnTarget` | on target | auf Ziel | — |
| `freshnessFresh` | Fresh | Aktuell | The three freshness states. They are a DIFFERENT axis from the verdict: a stale value keeps its verdict ([ADR-0010](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0010-a-stale-value-keeps-its-verdict.md)). |
| `freshnessStale` | Stale | Veraltet | — |
| `freshnessDisconnected` | No connection | Keine Verbindung | — |
| `asOfAgo(duration)` | `` `As of: ${duration}` `` | `` `Stand: ${duration}` `` | "As of: 3 minutes ago", where the duration comes from the formats. |

##### Overlays and states

| Key | English | German | Description |
|---|---|---|---|
| `close` | Close | Schließen | — |
| `closeToast` | Close message | Meldung schließen | — |
| `toastDeckCount(count)` | `` `${count} messages, show all` `` | `` `${count} Meldungen, alle zeigen` `` | The count on the front toast of a closed deck; pressing it shows them all. |
| `toastRegion` | Messages (Alt+T) | Meldungen (Alt+T) | The name of the toasts' region, which Alt+T moves the focus into. |
| `confirm` | Confirm | Bestätigen | — |
| `cancel` | Cancel | Abbrechen | — |
| `loading` | Loading | Wird geladen | — |
| `fillLevel` | Fill level | Füllstand | Generic name of a fill-level bar, where the caller names none. |
| `progress` | Progress | Fortschritt | Generic name of a progress bar, where the caller names none. |
| `breadcrumb` | Breadcrumb | Pfad | The accessible name of a breadcrumb's navigation landmark. |
| `breadcrumbFolded` | Show the levels in between | Ebenen dazwischen zeigen | The key that opens a breadcrumb's folded middle levels as a menu. |
| `splitter` | Resize the panes | Größe der Bereiche ändern | The separator between a splitter's panes, where the caller names none - a caller who can should name the first pane instead (APG). |
| `stepDone` | Done | Erledigt | A stepper's step that is behind it, said beside its label to a screen reader; the current step is `aria-current` and needs no word. |
| `stepUpcoming` | Upcoming | Ausstehend | A step still ahead. |
| `stepFailed` | Failed | Fehlgeschlagen | A step that failed - behind the current one or the current one itself. |
| `chooseFile` | Choose a file | Datei auswählen | The key of a file input that takes one file - and its name where no field names it. |
| `chooseFiles` | Choose files | Dateien auswählen | The same key where it takes several. |
| `dropFile` | or drop it here | oder hier ablegen | The words beside the key that say the zone takes a drop. |
| `dropFiles` | or drop them here | oder hier ablegen | — |
| `removeFile(name)` | `` `Remove ${name}` `` | `` `${name} entfernen` `` | The cross beside a chosen file. |
| `fileNotAccepted(name)` | `` `${name} is not an accepted type` `` | `` `${name} ist kein zugelassener Dateityp` `` | A dropped file the input's `accept` does not take. |
| `show` | Show | Einblenden | — |
| `hide` | Hide | Ausblenden | — |
| `moreActions` | More actions | Weitere Aktionen | — |
| `remove` | Remove | Entfernen | The cross on a tag without text content. |
| `removeTag(beschriftung)` | `` `Remove ${beschriftung}` `` | `` `${label} entfernen` `` | The cross on a tag with text content. |

##### @umriss-ui/schedule

| Key | English | German | Description |
|---|---|---|---|
| `scheduleOverlap` | Overlap | Überschneidung | The two findings, named on the ghost of a drag. |
| `scheduleViolatedDependency` | Violated dependency | Abhängigkeit verletzt | — |
| `scheduleGhostTimes(from, to)` | `` `${from}–${to}` `` | `` `${from}–${to}` `` | The new times on the ghost: "08:15–10:00" - the times come from the formats. |
| `scheduleLeadIn` | Lead-in | Vorlauf | The parts of a subtask and a dependency, named in the tooltip. |
| `scheduleLeadOut` | Lead-out | Nachlauf | — |
| `scheduleDependency` | Dependency | Abhängigkeit | — |
| `scheduleRoute(from, to)` | `` `${from} → ${to}` `` | `` `${from} → ${to}` `` | "A-2041-1 → A-2041-2": the two subtasks a dependency joins. |
| `scheduleOverlapWith(other)` | `` `Overlap with ${other}` `` | `` `Überschneidung mit ${other}` `` | "Overlap with A-2043-2" - the other subtask on the lane. |
| `scheduleViolatedBy(amount)` | `` `Violated dependency, ${amount} short` `` | `` `Abhängigkeit verletzt, ${amount} zu knapp` `` | "Violated dependency, 15 min short" - the amount from `minutesShort`. |
| `scheduleLaneRefused` | Not this lane | Nicht hierher | On the ghost of a drag over a lane the subtask may not go to. |
| `scheduleBlockedTime` | Blocked time | Sperrzeit | On the ghost of a drag held back from a lane's blocked time. |
| `scheduleInBlockedTime(label)` | `` (label === undefined ? "In blocked time" : `In blocked time (${label})`) `` | `` (label === undefined ? "In der Sperrzeit" : `In der Sperrzeit (${label})`) `` | "In blocked time (Leave)" - a subtask covering its lane's blocked time, with the blocked time's label where it has one. |
| `scheduleMilestone(name)` | `` `Milestone: ${name}` `` | `` `Meilenstein: ${name}` `` | "Milestone: Release" - a milestone named by its label (or id), so that the tooltip and the spoken readout say what kind of thing it is. |
| `scheduleFoldGroup` | Fold group | Gruppe einklappen | The chevron of a lane group's header, which folds it into one row and unfolds it again. The group's own label stands beside the button, so the name is what the ACTION is, not which group it acts on. |
| `scheduleUnfoldGroup` | Unfold group | Gruppe ausklappen | — |
| `scheduleLaneCount(count)` | `` (count === 1 ? "1 lane" : `${count} lanes`) `` | `` (count === 1 ? "1 Bahn" : `${count} Bahnen`) `` | How many lanes a group holds, beside its name in the header. |
| `scheduleRoleDescription` | schedule | Belegungsplan | What a screen reader calls the plot that takes the keys (`aria-roledescription`, schedule-a11y S1). |
| `scheduleSummary(summary)` | `` `${lanes === 1 ? "1 lane" : `${lanes} lanes`}, ${subtasks === 1 ? "1 subtask" : `${subtasks} subtasks`} in view from ${from} to ${to}. ` + `${overlaps === 1 ? "1 overlap" : `${overlaps} overlaps`}, ${violated === 1 ? "1 violated dependency" : `${violated} violated dependencies`}` + (blocked === 0 ? "." : `, ${blocked === 1 ? "1 subtask" : `${blocked} subtasks`} in blocked time.`) + (milestones === 0 ? "" : ` ${milestones === 1 ? "1 milestone" : `${milestones} milestones`}.`) `` | `` `${lanes === 1 ? "1 Bahn" : `${lanes} Bahnen`}, ${subtasks === 1 ? "1 Teilaufgabe" : `${subtasks} Teilaufgaben`} im Blick von ${from} bis ${to}. ` + `${overlaps === 1 ? "1 Überschneidung" : `${overlaps} Überschneidungen`}, ${violated === 1 ? "1 verletzte Abhängigkeit" : `${violated} verletzte Abhängigkeiten`}` + (blocked === 0 ? "." : `, ${blocked === 1 ? "1 Teilaufgabe in einer Sperrzeit" : `${blocked} Teilaufgaben in Sperrzeiten`}.`) + (milestones === 0 ? "" : ` ${milestones === 1 ? "1 Meilenstein" : `${milestones} Meilensteine`}.`) `` | The plot's description (S6): the lanes, the subtasks in view, the visible span with both ends formatted, and the findings of the plan by kind. |
| `scheduleKeyHelp` | Left and right arrows move along the lane, up and down change the lane, Home and End go to its first and last, Page Up and Page Down jump a tenth of the view. Right bracket or T follows a dependency out, left bracket or Shift and T goes back. Space or Enter selects. Alt with left or right proposes a move, Alt and Shift a new end. Escape clears. | Pfeil links und rechts gehen die Bahn entlang, Pfeil hoch und runter wechseln die Bahn, Pos1 und Ende springen zur ersten und letzten Teilaufgabe, Bild auf und Bild ab springen ein Zehntel der Ansicht. Schließende eckige Klammer oder T folgt einer Abhängigkeit hinaus, öffnende eckige Klammer oder Umschalt und T geht zurück. Leertaste oder Eingabe wählt aus. Alt mit Pfeil links oder rechts schlägt eine Verschiebung vor, Alt und Umschalt ein neues Ende. Escape lässt die aktive Teilaufgabe los. | The keys that walk the plot, select and edit - read after the summary. |

##### @umriss-ui/dashboard

| Key | English | German | Description |
|---|---|---|---|
| `dashboardEdit` | Edit | Bearbeiten | The editing bar's buttons and the label that says the mode is on. |
| `dashboardEditing` | Editing the dashboard | Dashboard wird bearbeitet | — |
| `dashboardCancel` | Cancel | Abbrechen | — |
| `dashboardDone` | Done | Fertig | — |
| `dashboardUndo` | Undo | Rückgängig | — |
| `dashboardRedo` | Redo | Wiederholen | — |
| `dashboardReset` | Reset | Zurücksetzen | — |
| `dashboardMenu(title)` | `` `Actions for ${title}` `` | `` `Aktionen für ${title}` `` | The name of a widget's menu button: the widget's title is the thing. |
| `dashboardPlace(place, of)` | `` `Place ${place} of ${of}` `` | `` `Platz ${place} von ${of}` `` | At the top of the menu, and in the name of a head the arrow keys move. |
| `dashboardHead(title, place, of)` | `` `${title}, place ${place} of ${of}` `` | `` `${title}, Platz ${place} von ${of}` `` | — |
| `dashboardMoveStart` | Move to start | An den Anfang | — |
| `dashboardMoveEarlier` | Move earlier | Weiter nach vorn | — |
| `dashboardMoveLater` | Move later | Weiter nach hinten | — |
| `dashboardMoveEnd` | Move to end | Ans Ende | — |
| `dashboardRemove` | Remove | Entfernen | — |
| `dashboardSizes.small` | Small | Klein | The closed set of size names, worded once for every widget type. |
| `dashboardSizes.medium` | Medium | Mittel | The closed set of size names, worded once for every widget type. |
| `dashboardSizes.wide` | Wide | Breit | The closed set of size names, worded once for every widget type. |
| `dashboardSizes.tall` | Tall | Hoch | The closed set of size names, worded once for every widget type. |
| `dashboardSizes.large` | Large | Groß | The closed set of size names, worded once for every widget type. |
| `dashboardSizes.full` | Full width | Volle Breite | The closed set of size names, worded once for every widget type. |
| `dashboardSizeEntry(size, share, current)` | `` `${current ? "✓ " : ""}${size}${share ? `, ${share} wide` : ""}` `` | `` `${current ? "✓ " : ""}${size}${share ? `, ${share} breit` : ""}` `` | A size's entry in a widget's menu: its name and its share of the width (`share` is "¼" or "5/12", empty for the whole width); `current` marks the size the widget stands at. |
| `dashboardHeadingLabel` | Heading | Überschrift | The built-in heading type: its name, its sentence in the catalogue, the text a new heading starts with and the label of its text field. |
| `dashboardHeadingSentence` | A title across the full width. | Ein Titel über die volle Breite. | — |
| `dashboardHeadingText` | New section | Neuer Abschnitt | — |
| `dashboardHeadingField` | Text | Text | — |
| `dashboardLeft` | Editing ended | Bearbeiten beendet | Said when "Done" leaves the mode and nothing was changed. |
| `dashboardMoved(title, from, to, of)` | `` `${title}: moved from place ${from} to place ${to} of ${of}` `` | `` `${title}: von Platz ${from} auf Platz ${to} von ${of} verschoben` `` | What is spoken after a change. |
| `dashboardDragCancelled(title)` | `` `${title}: move cancelled` `` | `` `${title}: Verschieben abgebrochen` `` | — |
| `dashboardResized(title, size)` | `` `${title}: size ${size}` `` | `` `${title}: Größe ${size}` `` | — |
| `dashboardRemoved(title)` | `` `${title} removed. Undo brings it back.` `` | `` `${title} entfernt. „Rückgängig“ holt es zurück.` `` | — |
| `dashboardKept` | Changes kept | Änderungen übernommen | — |
| `dashboardCancelled` | Changes discarded | Änderungen verworfen | — |
| `dashboardAddWidget` | Add widget | Widget hinzufügen | The catalogue and the options. |
| `dashboardCatalogue` | Add a widget | Widget hinzufügen | — |
| `dashboardCatalogueSentence` | Each widget is added at the end. | Jedes Widget wird am Ende eingefügt. | — |
| `dashboardAdd` | Add | Hinzufügen | — |
| `dashboardAddType(label)` | `` `Add ${label}` `` | `` `${label} hinzufügen` `` | — |
| `dashboardFootprint(columns, rows)` | `` `${columns} of 12 columns, ${rows} rows` `` | `` `${columns} von 12 Spalten, ${rows} Zeilen` `` | — |
| `dashboardAdded(title, place, of)` | `` `${title} added, place ${place} of ${of}` `` | `` `${title} hinzugefügt, Platz ${place} von ${of}` `` | — |
| `dashboardOptions` | Options | Optionen | — |
| `dashboardOptionsChanged(title)` | `` `${title}: options changed` `` | `` `${title}: Optionen geändert` `` | — |
| `dashboardEmpty` | This dashboard is empty. | Dieses Dashboard ist leer. | — |
| `dashboardEmptyEditing` | This dashboard is empty. Choose Add widget to begin. | Dieses Dashboard ist leer. Wählen Sie „Widget hinzufügen“, um zu beginnen. | — |
| `dashboardFailed` | This widget cannot show anything. | Dieses Widget kann nichts anzeigen. | — |
| `dashboardUndone` | Undone | Rückgängig gemacht | — |
| `dashboardRedone` | Redone | Wiederholt | — |
| `dashboardResetDone` | Reset to the default | Auf die Vorgabe zurückgesetzt | — |

##### @umriss-ui/calculation

| Key | English | German | Description |
|---|---|---|---|
| `calculationSumSymbol` | + | + | The four operators as symbols in a formula line. |
| `calculationDifferenceSymbol` | − | − | — |
| `calculationProductSymbol` | × | × | — |
| `calculationQuotientSymbol` | ÷ | ÷ | — |
| `calculationSumWord` | plus | plus | The same four as words, in the accessible sentence of a line. |
| `calculationDifferenceWord` | minus | minus | — |
| `calculationProductWord` | times | mal | — |
| `calculationQuotientWord` | divided by | geteilt durch | — |
| `calculationEquals` | equals | gleich | Between the parts of the sentence: "Availability equals ...". |
| `calculationApproximately` | approximately | ungefähr | Before a result marked "≈" in the sentence. |
| `calculationApproximateNote` | The rounded figures do not give this exactly; it is computed from the unrounded ones. | Die gerundeten Zahlen ergeben das nicht genau; gerechnet ist mit den ungerundeten. | Beside a result marked "≈": why the rounded operands do not give it. |
| `calculationPercent` | percent | Prozent | How a percentage is read out: "91.6 percent". |
| `calculationMissing(label)` | `` `${label} is missing` `` | `` `${label} fehlt` `` | Why a quantity has no number - the label is the given at the root of it, or the divisor that is zero. |
| `calculationDivisionByZero(label)` | `` `Division by zero: ${label} is 0` `` | `` `Division durch null: ${label} ist 0` `` | — |
| `calculationAboveTarget(target)` | `` `above target ${target}` `` | `` `über Ziel ${target}` `` | The target beside the result, with the target's number and unit. |
| `calculationBelowTarget(target)` | `` `below target ${target}` `` | `` `unter Ziel ${target}` `` | — |
| `calculationOnTarget(target)` | `` `on target ${target}` `` | `` `auf Ziel ${target}` `` | — |
| `calculationWorstInside(verdict)` | `` `Inside: ${verdict}` `` | `` `Darin: ${verdict}` `` | The quiet marker on a folded quantity whose derivation holds a worse verdict than its own; the verdict word comes from `verdict*`. |
| `calculationSource(source)` | `` `Source: ${source}` `` | `` `Quelle: ${source}` `` | Where a given number came from. |
| `calculationShowDerivation(label)` | `` `Show how ${label} is derived` `` | `` `Herleitung von ${label} zeigen` `` | The disclosure button of a derivation, named after the quantity. |
| `calculationHideDerivation(label)` | `` `Hide how ${label} is derived` `` | `` `Herleitung von ${label} verbergen` `` | — |
| `calculationOperandCount(count)` | `` `${count} operands` `` | `` `${count} Operanden` `` | On a folded line whose operator has more operands than are written out beneath it ([ADR-0028](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0028-a-calculation-is-a-tree-or-a-chain.md)): how many there are. |
| `calculationNoOperands` | no entries | keine Einträge | On the line of a sum with no operands, where its formula would stand ([ADR-0049](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0049-a-sum-takes-rows-from-data.md)). |

#### Charts wording

Every entry of `ChartsWording` from `@umriss-ui/charts`, which a chart takes through its `wording` prop: the English of `DEFAULT_CHARTS_WORDING` beside the German of `GERMAN_CHARTS_WORDING`, imported from `@umriss-ui/charts/wording/de`.

| Key | English | German | Description |
|---|---|---|---|
| `locale` | en-GB | de-DE | The BCP 47 tag every number and every date or time label of the chart is formatted in (`en-GB`, `de-DE`). The one input for the locale: the browser's language is not read. The clock stays 24-hour in both. |
| `roleDescription` | chart | Diagramm | What a screen reader calls the plot area that takes the keys (`aria-roledescription`). |
| `empty` | No data | Keine Daten | Shown in the plot area when no visible series has a point to show. |
| `seriesList(names)` | `` `${names.length === 1 ? "1 series" : `${names.length} series`}: ${names.join(", ")}.` `` | `` `${names.length === 1 ? "1 Serie" : `${names.length} Serien`}: ${names.join(", ")}.` `` | The summary's visible series, by name. |
| `visibleRange(from, to)` | `` `From ${from} to ${to}.` `` | `` `Von ${from} bis ${to}.` `` | The summary's visible stretch of the x axis, both ends formatted. |
| `seriesExtent(name, min, max)` | `` `${name} from ${min} to ${max}.` `` | `` `${name} von ${min} bis ${max}.` `` | The summary's lowest and highest value of one series in that stretch. |
| `limitList(limits)` | `` `Limits: ${limits.map((l) => `${l.name} ${l.value}`).join(", ")}.` `` | `` `Grenzen: ${limits.map((l) => `${l.name} ${l.value}`).join(", ")}.` `` | The summary's labelled limits, each with its value in its axis' format (a band's two edges as one value). |
| `readout(x, rows)` | `` [`${x}.`, ...rows.map((r) => `${r.name} ${r.value}${r.x === "" ? "" : ` at ${r.x}`}.`)].join(" ") `` | `` [`${x}.`, ...rows.map((r) => `${r.name} ${r.value}${r.x === "" ? "" : ` bei ${r.x}`}.`)].join(" ") `` | What is read after a key: the position, then each series with its value (and its own x where it stands on another x axis), the emphasised one first. |
| `stackTotal` | Total | Summe | The last row of a stack in the tooltip and the readout: the sum of its members at the point. |
| `percent(value)` | `` `${value}%` `` | `` `${value} %` `` | A share in a normalised stack, its number already formatted. |
| `walkHelp` | Left and right arrows move through the values, up and down change the series, Home and End go to the first and the last, Escape clears. | Pfeil links und rechts gehen durch die Werte, Pfeil hoch und runter wechseln die Serie, Pos1 und Ende springen zum ersten und letzten Wert, Escape hebt die Markierung auf. | The keys that walk the chart. |
| `selectHelp` | Enter chooses the point. | Enter wählt den Punkt. | The key that reports the Active point - only where `onSelect` is given. |
| `zoomHelp` | Plus and minus zoom, Shift with left or right pans, 0 goes back to the axis' own span. | Plus und Minus zoomen, Umschalt mit Pfeil links oder rechts verschiebt, 0 kehrt zum eigenen Bereich der Achse zurück. | The keys that zoom and pan it - only where the chart can be zoomed. |
| `legendHelp` | In the legend, Enter hides or shows a series, Shift+Enter shows only it. | In der Legende blendet Enter eine Serie aus oder ein, Umschalt+Enter zeigt nur sie. | The keys of the legend's entries - only where it has one to press. |
| `allShown` | Nothing would be left to see, so every series is shown. | Sonst wäre nichts mehr zu sehen, darum werden alle Serien gezeigt. | Read out where hiding would leave nothing to see, and every series is shown instead. |
| `showAll` | Show all | Alles zeigen | The control over a zoomed plot that brings every zoomed axis back to its own domain (component-view 04). |
| `showData` | Show data | Daten zeigen | The data table's disclosure key, closed and open. |
| `hideData` | Hide data | Daten verbergen | — |
| `positionColumn` | Position | Position | The heading of the table's x column where its axis has no `label`, and of a matrix' row column where its y axis has none. |
| `rowColumn` | Row | Zeile | — |
| `tableCaption(from, to)` | `` `Values from ${from} to ${to}.` `` | `` `Werte von ${from} bis ${to}.` `` | The table's caption: the visible stretch it lists, both ends formatted. |
| `upperWhisker` | Upper whisker | Oberer Whisker | A box's numbers, top to bottom as drawn: the tooltip's rows, the readout's parts and the data table's columns (box-plot B9). |
| `upperQuartile` | Upper quartile | Oberes Quartil | — |
| `median` | Median | Median | — |
| `lowerQuartile` | Lower quartile | Unteres Quartil | — |
| `lowerWhisker` | Lower whisker | Unterer Whisker | — |
| `outliers` | Outliers | Ausreißer | A box's outliers: the row's name, and the row's value - their count and the first few values, the rest counted (box-plot B9). |
| `mean` | Mean | Mittelwert | A box's optional readings: its mean, its notch's two bounds as one row, and how many values stand behind it. |
| `notch` | Notch | Notch | — |
| `count` | n | n | — |
| `outlierList(values, more)` | `` `${values.length + more}: ${values.join(", ")}${more > 0 ? ` and ${more} more` : ""}` `` | `` `${values.length + more}: ${values.join(", ")}${more > 0 ? ` und ${more} weitere` : ""}` `` | — |
| `downsampled(readings)` | `` `Downsampled from ${readings.toLocaleString("en-GB")} readings: the first, lowest, highest and last value of each stretch.` `` | `` `Ausgedünnt aus ${readings.toLocaleString("de-DE")} Messwerten: erster, kleinster, größter und letzter Wert je Abschnitt.` `` | Added to the caption where the table shows the downsampled course: how many readings its rows stand for. |

#### Formats

Every entry of `Formats`: `DEFAULT_FORMATS` beside `GERMAN_FORMATS`. Each set as it writes Tuesday, 17 March 2026 at 09:05:03 in Berlin (the time without seconds), the number 1204.5 to one decimal, the count 1204, the share 0.74, three minutes ago, and `Zebra`, `Émile` and `Apple` in order.

| Key | English | German | Description |
|---|---|---|---|
| `date(d)` | 17/03/2026 | 17.03.2026 | Date as displayed: 17/03/2026 |
| `dateShort(d)` | 17/03 | 17.03. | Short form without the year, in the range footer: 17/03 |
| `month(d)` | March 2026 | März 2026 | The calendar's month header: March 2026 |
| `dateLong(d)` | Tuesday, 17 March 2026 | Dienstag, 17. März 2026 | Accessible name of a calendar cell: Tuesday, 17 March 2026 |
| `time(d, withSeconds)` | 09:05 | 09:05 | Time of day, optionally with seconds: 09:05 or 09:05:03 |
| `dateTime(d, withSeconds)` | 17/03/2026, 09:05 | 17.03.2026, 09:05 | Date and time together: 17/03/2026, 09:05 |
| `offset(d)` | GMT+1 | GMT+1 | Short form of the UTC offset: GMT+2 |
| `number(n, decimals)` | 1,204.5 | 1.204,5 | A number in the set's notation. Without a digit count the value stands to the tenth decimal place; with one it is padded and rounded to exactly that many places. |
| `count(n)` | 1,204 | 1.204 | A count. Kept apart from `number` because it makes a different promise: a count is whole, and Intl's own rounding (at most three decimal places) is right for it and wrong for a measurement. |
| `percent(share)` | 74% | 74 % | A share from 0 to 1 as whole per cent: 74 % |
| `compareText(a, b)` | Apple, Émile, Zebra | Apple, Émile, Zebra | The ordering of two texts by the set's collation. |
| `relative(ms)` | 3 minutes ago | vor 3 Minuten | An elapsed duration as a phrase: "3 minutes ago". The amount comes in milliseconds, counted back from now. |

#### When to use something else

- The application also sets a density, a portal target or toasts → UmrissProvider

#### Keyboard

The keys of [Button](#/button/keyboard-button), [NumberInput](#/numberinput/keyboard-numberinput), [Combobox](#/combobox/keyboard-combobox) and [DatePicker](#/datepicker/keyboard-datepicker) apply here.

#### API

##### `LanguageOptions`

| Prop | Type | Default | Description |
|---|---|---|---|
| `formats` | `Partial<`[`Formats`](#type-Formats)`>` | — | How numbers, dates and durations are written. Overridden entry by entry; what is left out keeps writing as `DEFAULT_FORMATS` does - in English notation, whatever the wording says ([ADR-0024](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0024-the-formats-are-english-german-is-freight.md)).<br>Shown in: [German](#/language/german), [English and German side by side](#/language/side-by-side), [Write numbers in your own notation](#/language/own-notation) and 2 more |
| `wording` | `Partial<Omit<`[`Wording`](#type-Wording)`, "presets">> & { presets?: Partial<`[`Wording`](#type-Wording)`["presets"]> }` | — | The presets are a register of their own and are likewise overridden entry by entry.<br>Shown in: [German](#/language/german), [English and German side by side](#/language/side-by-side), [Replace single entries](#/language/single-entries) and 2 more |

##### Types on this page

###### `Formats`

Everything the library knows about formatting.

| Prop | Type | Default | Description |
|---|---|---|---|
| `date` *required* | `(d: Date) => string` | — | Date as displayed: 17/03/2026<br>Shown in: [A span of days (DateRangePicker)](#/daterangepicker/a-span-of-days) |
| `dateShort` *required* | `(d: Date) => string` | — | Short form without the year, in the range footer: 17/03 |
| `month` *required* | `(d: Date) => string` | — | The calendar's month header: March 2026 |
| `dateLong` *required* | `(d: Date) => string` | — | Accessible name of a calendar cell: Tuesday, 17 March 2026 |
| `time` *required* | `(d: Date, withSeconds: boolean) => string` | — | Time of day, optionally with seconds: 09:05 or 09:05:03 |
| `dateTime` *required* | `(d: Date, withSeconds: boolean) => string` | — | Date and time together: 17/03/2026, 09:05<br>Shown in: [Use the language in your own components](#/language/own-components), [Pick a day (DatePicker)](#/datepicker/pick-a-day), [Set an instant (DateTimePicker)](#/datetimepicker/set-an-instant) and 1 more |
| `offset` *required* | `(d: Date) => string` | — | Short form of the UTC offset: GMT+2<br>Shown in: [Set an instant (DateTimePicker)](#/datetimepicker/set-an-instant) |
| `number` *required* | `(n: number, decimals?: number) => string` | — | A number in the set's notation. Without a digit count the value stands to the tenth decimal place; with one it is padded and rounded to exactly that many places.<br>Shown in: [Write numbers in your own notation](#/language/own-notation), [Price an invoice line (NumberInput)](#/numberinput/price-an-invoice-line), [Split a budget (Slider)](#/slider/split-a-budget) |
| `count` *required* | `(n: number) => string` | — | A count. Kept apart from `number` because it makes a different promise: a count is whole, and Intl's own rounding (at most three decimal places) is right for it and wrong for a measurement.<br>Shown in: [Write numbers in your own notation](#/language/own-notation), [Use the language in your own components](#/language/own-components) |
| `percent` *required* | `(share: number) => string` | — | A share from 0 to 1 as whole per cent: 74 % |
| `compareText` *required* | `(a: string, b: string) => number` | — | The ordering of two texts by the set's collation. |
| `relative` *required* | `(ms: number) => string` | — | An elapsed duration as a phrase: "3 minutes ago". The amount comes in milliseconds, counted back from now. |

###### `Wording`

Everything the library puts out as text.

| Prop | Type | Default | Description |
|---|---|---|---|
| `clearInput` *required* | `string` | — | The cross in the text field. |
| `clearSelection` *required* | `string` | — | The cross in the select and in the combobox. |
| `decreaseValue` *required* | `string` | — | Stepper buttons of the number field. |
| `increaseValue` *required* | `string` | — |  |
| `comboboxPlaceholder` *required* | `string` | — |  |
| `noMatches` *required* | `string` | — | Empty state of both lists. |
| `multiSelectPlaceholder` *required* | `string` | — |  |
| `multiSelectSearchPlaceholder` *required* | `string` | — |  |
| `searchOptions` *required* | `string` | — |  |
| `options` *required* | `string` | — | Group name of the option list. |
| `optionScope` *required* | `string` | — | Group name of the scope switch. |
| `optionScopeAll` *required* | `string` | — |  |
| `optionScopeSelected` *required* | `(count: number) => string` | — | The second scope, with the count in the text. |
| `selectAll` *required* | `string` | — |  |
| `selectNone` *required* | `string` | — |  |
| `invertSelection` *required* | `string` | — |  |
| `nothingSelected` *required* | `string` | — |  |
| `removeSelectedValue` *required* | `(beschriftung: string) => string` | — | The cross on a selected value in the trigger. |
| `manageMoreSelected` *required* | `(count: number) => string` | — | The "+N" counter in the trigger. |
| `multiSelectSummary` *required* | `(gewaehlt: number, total: number) => string` | — | The summary in the panel: "3 / 12". The sentence structure belongs to the language, even where it is only a slash here. |
| `optionCount` *required* | `(count: number) => string` | — | How many options stand, when a list opens or its filter changes; never zero - an empty list says its own empty text. Named, like the three below, after the moment it is spoken in: an announcement labels no element. |
| `optionActive` *required* | `( label: string, state: { selected?: boolean; disabled?: boolean; group?: string }, ) => string` | — | The option the keys moved onto, with what VoiceOver leaves out. |
| `optionAdded` *required* | `(label: string) => string` | — | A value the multi-select took or gave away where no checkbox had the focus to say it - Enter in the search, a chip, Backspace. |
| `optionRemoved` *required* | `(label: string) => string` | — |  |
| `palettePlaceholder` *required* | `string` | — | What stands in the empty field. |
| `paletteField` *required* | `string` | — | Accessible name of the field. Deliberately kept apart from the placeholder - whoever labels the field differently does not thereby rename the window. |
| `palettePanel` *required* | `string` | — | Accessible name of the window. |
| `paletteList` *required* | `string` | — | Accessible name of the list of finds. |
| `paletteNoFinds` *required* | `string` | — | The one line when the query finds nothing. |
| `paletteFindCount` *required* | `(count: number) => string` | — | What the screen reader hears when the number of finds changes. |
| `paletteMoreFinds` *required* | `(count: number) => string` | — | The last line when more finds exist than `maxFinds` lets stand. |
| `paletteHintMove` *required* | `string` | — | The three key hints in the footer, each the text beside the key. |
| `paletteHintChoose` *required* | `string` | — |  |
| `paletteHintClose` *required* | `string` | — |  |
| `paletteKeyEsc` *required* | `string` | — | The legend on the Escape key. The arrows and the return key are glyphs and therefore do not stand here; "Esc" is a word and is called something else elsewhere. |
| `datePlaceholder` *required* | `string` | — |  |
| `datePanel` *required* | `string` | — | Accessible name of the panel. Deliberately kept apart from the placeholder: whoever labels the field differently does not thereby rename the dialog. |
| `dateClear` *required* | `string` | — |  |
| `dateTimePlaceholder` *required* | `string` | — |  |
| `dateTimePanel` *required* | `string` | — |  |
| `dateTimeClear` *required* | `string` | — |  |
| `dateRangePlaceholder` *required* | `string` | — |  |
| `dateRangePanel` *required* | `string` | — |  |
| `dateRangeClear` *required* | `string` | — |  |
| `dateTimeRangePanel` *required* | `string` | — | Accessible name of the panel in the range with time of day. |
| `dateTimeRangeClear` *required* | `string` | — | The clearing x of the range with time - kept apart from the range without, so that an application can call the two differently. |
| `previousMonth` *required* | `string` | — |  |
| `nextMonth` *required* | `string` | — |  |
| `quickSelect` *required* | `string` | — | Group name of the preset column. |
| `today` *required* | `string` | — | <br>Shown in: [Use the language in your own components](#/language/own-components) |
| `now` *required* | `string` | — |  |
| `clear` *required* | `string` | — |  |
| `apply` *required* | `string` | — |  |
| `allDay` *required* | `string` | — |  |
| `timeOfDay` *required* | `string` | — |  |
| `hour` *required* | `string` | — |  |
| `minute` *required* | `string` | — |  |
| `second` *required* | `string` | — |  |
| `sideFrom` *required* | `string` | — | Header of the two time columns in the range with time of day. |
| `sideTo` *required* | `string` | — |  |
| `startHour` *required* | `string` | — | Accessible name of the time fields, per side. |
| `startMinute` *required* | `string` | — |  |
| `startSecond` *required* | `string` | — |  |
| `endHour` *required* | `string` | — |  |
| `endMinute` *required* | `string` | — |  |
| `endSecond` *required* | `string` | — |  |
| `timeFieldIncrease` *required* | `(feld: string) => string` | — | Stepper buttons of a time field; the label comes from above. |
| `timeFieldDecrease` *required* | `(feld: string) => string` | — |  |
| `chooseStartDate` *required* | `string` | — | Footer of the range panels. |
| `chooseEndDate` *required* | `string` | — |  |
| `days` *required* | `(count: number) => string` | — | "3 days" or "1 day" - the plural belongs to the language. |
| `daysSelected` *required* | `(count: number) => string` | — | "3 days selected" |
| `rangePreview` *required* | `(from: string, to: string, count: number) => string` | — | "17.03. – 19.03. · 3 days" while dragging; the dates come from the formats. |
| `daysAllDay` *required* | `(count: number) => string` | — | "3 days (all day)" |
| `duration` *required* | `(teile: readonly string[]) => string` | — | "Duration: 1 day 2 hrs 30 min" |
| `hoursShort` *required* | `(count: number) => string` | — |  |
| `minutesShort` *required* | `(count: number) => string` | — |  |
| `timeMissingHint` *required* | `(timeOfDay: string) => string` | — | Daylight-saving change: the hour that does not exist. |
| `timeMissingHintSide` *required* | `(side: string, timeOfDay: string) => string` | — | The same, with the side put in front ("From"/"To"). |
| `timeAmbiguousHint` *required* | `string` | — | Daylight-saving change: the hour that occurs twice. |
| `timeAmbiguousHintSide` *required* | `(side: string) => string` | — |  |
| `timeEarlier` *required* | `(versatz: string) => string` | — |  |
| `timeLater` *required* | `(versatz: string) => string` | — |  |
| `weekdays` *required* | `readonly string[]` | — | The calendar's weekday headers, starting at Monday. |
| `presets` *required* | `{ today: string; yesterday: string; last7Days: string; last30Days: string; thisMonth: string; previousMonth: string; thisQuarter: string; thisYear: string; }` | — | The quick-select ranges, in the order of PRESET_LABELS. |
| `pagination` *required* | `string` | — |  |
| `rows` *required* | `string` | — |  |
| `rowsPerPage` *required* | `string` | — |  |
| `pageOfPages` *required* | `(page: number, total: number, formatted?: { page: string; total: string }) => string` | — | "Page 2 of 7". `formatted` carries both numbers in the provider's formats, where the caller has them - a table over a server has "Page 1 of 100,000". |
| `previousPage` *required* | `string` | — |  |
| `nextPage` *required* | `string` | — |  |
| `filterReset` *required* | `string` | — | The two buttons in the column filter's footer. |
| `filterDone` *required* | `string` | — |  |
| `columns` *required* | `string` | — | The column menu's button. |
| `arrangeColumns` *required* | `string` | — | Accessible name of the list in the column menu. |
| `columnForward` *required* | `(column: string) => string` | — | The two buttons that move a column in the column menu. |
| `columnBackward` *required* | `(column: string) => string` | — |  |
| `pinColumnToStart` *required* | `(column: string) => string` | — | The column menu's pin keys: to a side, and back when it is pinned there. |
| `pinColumnToEnd` *required* | `(column: string) => string` | — |  |
| `unpinColumn` *required* | `(column: string) => string` | — |  |
| `columnForwardHint` *required* | `string` | — | The tooltips over those four keys: short, without the column, which stands in the same line. The keys' names above keep it for a screen reader. |
| `columnBackwardHint` *required* | `string` | — |  |
| `pinToStartHint` *required* | `string` | — |  |
| `pinToEndHint` *required* | `string` | — |  |
| `unpinHint` *required* | `string` | — |  |
| `exportLabel` *required* | `string` | — | The export button. |
| `exportPageLabel` *required* | `string` | — | The export button of a table in server mode, which holds and writes one page. |
| `exportFileName` *required* | `string` | — | The export's file name, where the application names none. |
| `tableSearchPlaceholder` *required* | `string` | — | Placeholder and accessible name of the search field. |
| `tableSearchLabel` *required* | `string` | — |  |
| `filterColumn` *required* | `(column: string) => string` | — | The filter button of a column: "Filter Region". |
| `filterHint` *required* | `string` | — | The tooltip over that button. |
| `selectRow` *required* | `(row: string) => string` | — | The selection of one row, named after its row header. |
| `selectAllRows` *required* | `string` | — | The selection of every row in the filtered set. |
| `selectAllOnPage` *required* | `string` | — | The same checkbox in server mode, where the table holds one page of a server's. |
| `expandRowNamed` *required* | `(row: string) => string` | — | The expand button, named after the row header. |
| `collapseRowNamed` *required* | `(row: string) => string` | — |  |
| `rowActions` *required* | `string` | — | Header of the actions column - for the screen reader, not visible. |
| `rowAction` *required* | `(aktion: string, row: string) => string` | — | One action on a row: "Open: A-2041". |
| `rowActionsMenu` *required* | `(row: string) => string` | — | The menu holding a row's actions. |
| `editCell` *required* | `(column: string, row: string) => string` | — | The editor of a cell in a table's grid mode, named after its column and its row: "Edit Budget: Marketing". |
| `newRow` *required* | `string` | — | The button above a grid that opens an empty row to fill in, and the name of that row while it has none ([ADR-0036](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0036-a-grid-edits-on-the-first-click-and-saves-rows-on-purpose.md)). |
| `saveRow` *required* | `string` | — | A row draft's buttons, named with the row through `rowAction`. |
| `discardRow` *required* | `string` | — |  |
| `deleteRow` *required* | `string` | — | A row's delete button, and its question once pressed: Delete? Delete / Keep. |
| `deleteRowAsk` *required* | `string` | — |  |
| `keepRow` *required* | `string` | — |  |
| `saveOrDiscardFirst` *required* | `string` | — | Said where someone tries to leave a row draft unsaved. |
| `cellAbsentValue` *required* | `string` | — | What the screen reader hears for an absent value. Visibly a muted dash stands there. |
| `booleanYes` *required* | `string` | — | A boolean without a presentation of its own. |
| `booleanNo` *required* | `string` | — |  |
| `footerSum` *required* | `string` | — | The kind of a footer number, read out before the number. |
| `footerAverage` *required* | `string` | — |  |
| `footerMinimum` *required* | `string` | — |  |
| `footerMaximum` *required* | `string` | — |  |
| `footerRange` *required* | `string` | — |  |
| `footerCount` *required* | `string` | — |  |
| `footerDistinct` *required* | `string` | — |  |
| `footerAggregate` *required* | `string` | — | An aggregate the application computes itself. |
| `grouping` *required* | `string` | — | The grouping section of the column menu, and the menu entry per column. |
| `groupBy` *required* | `(label: string) => string` | — |  |
| `groupedBy` *required* | `string` | — | The grouping's tag in the table toolbar: "Grouped by" Region › Customer. |
| `removeGrouping` *required* | `string` | — |  |
| `removeGroupingLevel` *required* | `(label: string) => string` | — |  |
| `foldAll` *required* | `string` | — |  |
| `unfoldAll` *required* | `string` | — |  |
| `groupNoValue` *required* | `string` | — | The group of rows without a value. |
| `groupContinued` *required* | `string` | — | Beside a group repeated at the top of a page that begins inside it. |
| `foldGroup` *required* | `(name: string, count: string) => string` | — | The fold of a group, with its value and its count. |
| `unfoldGroup` *required* | `(name: string, count: string) => string` | — |  |
| `foldBranch` *required* | `(row: string) => string` | — | The fold of a branch in a table with tree rows, named after its row - not `expandRowNamed`, which names the row detail's expander on the same row. |
| `unfoldBranch` *required* | `(row: string) => string` | — |  |
| `levelColumn` *required* | `string` | — | The first column of a tree's export. |
| `pathRow` *required* | `string` | — | A row shown only because a descendant matches the search or a filter. |
| `footerTopLevel` *required* | `string` | — | The footer of a tree: it sums the top level, since a parent holds its children. |
| `selectGroup` *required* | `(name: string) => string` | — | The box that selects every row of a group. |
| `calendarWeek` *required* | `(week: number, year: number) => string` | — | A group of the week key: "Week 42, 2026". |
| `entries` *required* | `(count: number, formatted: string) => string` | — | "128 entries" in the pagination bar; the plural belongs to the language. |
| `selectedCount` *required* | `(count: number, formatted: string) => string` | — | "3 selected" in the pagination bar and the table toolbar. |
| `copiedRows` *required* | `(count: number, formatted: string) => string` | — | Said to a screen reader after Ctrl+C copied rows: "3 rows copied". |
| `copiedCell` *required* | `string` | — | Said after Ctrl+C copied the active cell of a grid. |
| `copyFailed` *required* | `string` | — | Said when the clipboard refused or is not there. |
| `noEntries` *required* | `string` | — | Empty because there are no rows. |
| `nothingMatchesFilters` *required* | `string` | — | Empty because search and filters leave nothing - something else. |
| `treeSearchPlaceholder` *required* | `string` | — |  |
| `treeNoMatches` *required* | `string` | — |  |
| `conditions` *required* | `string` | — | Group name of the conditions in the table toolbar. |
| `removeConditionNamed` *required* | `(label: string, value: string) => string` | — | The button that removes a condition: "Remove Region: EU, US". |
| `editConditionNamed` *required* | `(label: string, value: string) => string` | — | The condition itself, which opens its filter: "Edit Region: EU, US". |
| `moreValues` *required* | `(count: number, formatted: string) => string` | — | The remainder of a long list in a condition: "+1". |
| `filterFrom` *required* | `string` | — | The two fields of the range filter. |
| `filterTo` *required* | `string` | — |  |
| `rangeFromTo` *required* | `(from: string, to: string) => string` | — | The condition of a range filter: "100–500", "from 100", "to 500". |
| `rangeFrom` *required* | `(from: string) => string` | — |  |
| `rangeTo` *required* | `(to: string) => string` | — |  |
| `rangeInvalid` *required* | `string` | — | When "From" lies behind "To". The condition stays the last valid one. |
| `resetAll` *required* | `string` | — | Clears search and conditions - in the table toolbar and in the empty body. |
| `filteredOfTotal` *required* | `(matches: string, total: string) => string` | — | "43 of 1.204" - the numbers come from the formats. |
| `verdictOk` *required* | `string` | — | The four outcomes of an assessment, as a word beside the value. Colour alone carries no meaning - the word stands here for that reason.<br>Shown in: [Replace single entries](#/language/single-entries) |
| `verdictWarning` *required* | `string` | — | <br>Shown in: [Replace single entries](#/language/single-entries) |
| `verdictAlarm` *required* | `string` | — | <br>Shown in: [Replace single entries](#/language/single-entries) |
| `verdictUnknown` *required* | `string` | — |  |
| `statAbsentValue` *required* | `string` | — | What stands in the value field when there is no value. No dash, no zero: either could be a value. |
| `target` *required* | `string` | — |  |
| `deviationAbove` *required* | `(betrag: string) => string` | — | "3,2 above target" or "1,5 below target" - the amount comes from the formats, which is where the comma is from. |
| `deviationBelow` *required* | `(betrag: string) => string` | — |  |
| `deviationOnTarget` *required* | `string` | — |  |
| `freshnessFresh` *required* | `string` | — | The three freshness states. They are a DIFFERENT axis from the verdict: a stale value keeps its verdict ([ADR-0010](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0010-a-stale-value-keeps-its-verdict.md)). |
| `freshnessStale` *required* | `string` | — |  |
| `freshnessDisconnected` *required* | `string` | — |  |
| `asOfAgo` *required* | `(duration: string) => string` | — | "As of: 3 minutes ago", where the duration comes from the formats. |
| `close` *required* | `string` | — |  |
| `closeToast` *required* | `string` | — |  |
| `toastDeckCount` *required* | `(count: number) => string` | — | The count on the front toast of a closed deck; pressing it shows them all. |
| `toastRegion` *required* | `string` | — | The name of the toasts' region, which Alt+T moves the focus into. |
| `confirm` *required* | `string` | — |  |
| `cancel` *required* | `string` | — |  |
| `loading` *required* | `string` | — |  |
| `fillLevel` *required* | `string` | — | Generic name of a fill-level bar, where the caller names none. |
| `progress` *required* | `string` | — | Generic name of a progress bar, where the caller names none. |
| `breadcrumb` *required* | `string` | — | The accessible name of a breadcrumb's navigation landmark. |
| `breadcrumbFolded` *required* | `string` | — | The key that opens a breadcrumb's folded middle levels as a menu. |
| `splitter` *required* | `string` | — | The separator between a splitter's panes, where the caller names none - a caller who can should name the first pane instead (APG). |
| `stepDone` *required* | `string` | — | A stepper's step that is behind it, said beside its label to a screen reader; the current step is `aria-current` and needs no word. |
| `stepUpcoming` *required* | `string` | — | A step still ahead. |
| `stepFailed` *required* | `string` | — | A step that failed - behind the current one or the current one itself. |
| `chooseFile` *required* | `string` | — | The key of a file input that takes one file - and its name where no field names it. |
| `chooseFiles` *required* | `string` | — | The same key where it takes several. |
| `dropFile` *required* | `string` | — | The words beside the key that say the zone takes a drop. |
| `dropFiles` *required* | `string` | — |  |
| `removeFile` *required* | `(name: string) => string` | — | The cross beside a chosen file. |
| `fileNotAccepted` *required* | `(name: string) => string` | — | A dropped file the input's `accept` does not take. |
| `show` *required* | `string` | — |  |
| `hide` *required* | `string` | — |  |
| `moreActions` *required* | `string` | — |  |
| `remove` *required* | `string` | — | The cross on a tag without text content. |
| `removeTag` *required* | `(beschriftung: string) => string` | — | The cross on a tag with text content. |
| `scheduleOverlap` *required* | `string` | — | The two findings, named on the ghost of a drag. |
| `scheduleViolatedDependency` *required* | `string` | — |  |
| `scheduleGhostTimes` *required* | `(from: string, to: string) => string` | — | The new times on the ghost: "08:15–10:00" - the times come from the formats. |
| `scheduleLeadIn` *required* | `string` | — | The parts of a subtask and a dependency, named in the tooltip. |
| `scheduleLeadOut` *required* | `string` | — |  |
| `scheduleDependency` *required* | `string` | — |  |
| `scheduleRoute` *required* | `(from: string, to: string) => string` | — | "A-2041-1 → A-2041-2": the two subtasks a dependency joins. |
| `scheduleOverlapWith` *required* | `(other: string) => string` | — | "Overlap with A-2043-2" - the other subtask on the lane. |
| `scheduleViolatedBy` *required* | `(amount: string) => string` | — | "Violated dependency, 15 min short" - the amount from `minutesShort`. |
| `scheduleLaneRefused` *required* | `string` | — | On the ghost of a drag over a lane the subtask may not go to. |
| `scheduleBlockedTime` *required* | `string` | — | On the ghost of a drag held back from a lane's blocked time. |
| `scheduleInBlockedTime` *required* | `(label: string \| undefined) => string` | — | "In blocked time (Leave)" - a subtask covering its lane's blocked time, with the blocked time's label where it has one. |
| `scheduleMilestone` *required* | `(name: string) => string` | — | "Milestone: Release" - a milestone named by its label (or id), so that the tooltip and the spoken readout say what kind of thing it is. |
| `scheduleFoldGroup` *required* | `string` | — | The chevron of a lane group's header, which folds it into one row and unfolds it again. The group's own label stands beside the button, so the name is what the ACTION is, not which group it acts on. |
| `scheduleUnfoldGroup` *required* | `string` | — |  |
| `scheduleLaneCount` *required* | `(count: number) => string` | — | How many lanes a group holds, beside its name in the header. |
| `scheduleRoleDescription` *required* | `string` | — | What a screen reader calls the plot that takes the keys (`aria-roledescription`, schedule-a11y S1). |
| `scheduleSummary` *required* | `(summary: { lanes: number; subtasks: number; from: string; to: string; overlaps: number; violated: number; /** Subtasks in blocked time; said only where there are any. */ blocked: number; /** Milestones of the plan; said only where there are any. */ milestones: number; }) => string` | — | The plot's description (S6): the lanes, the subtasks in view, the visible span with both ends formatted, and the findings of the plan by kind. |
| `scheduleKeyHelp` *required* | `string` | — | The keys that walk the plot, select and edit - read after the summary. |
| `dashboardEdit` *required* | `string` | — | The editing bar's buttons and the label that says the mode is on. |
| `dashboardEditing` *required* | `string` | — |  |
| `dashboardCancel` *required* | `string` | — |  |
| `dashboardDone` *required* | `string` | — |  |
| `dashboardUndo` *required* | `string` | — |  |
| `dashboardRedo` *required* | `string` | — |  |
| `dashboardReset` *required* | `string` | — |  |
| `dashboardMenu` *required* | `(title: string) => string` | — | The name of a widget's menu button: the widget's title is the thing. |
| `dashboardPlace` *required* | `(place: number, of: number) => string` | — | At the top of the menu, and in the name of a head the arrow keys move. |
| `dashboardHead` *required* | `(title: string, place: number, of: number) => string` | — |  |
| `dashboardMoveStart` *required* | `string` | — |  |
| `dashboardMoveEarlier` *required* | `string` | — |  |
| `dashboardMoveLater` *required* | `string` | — |  |
| `dashboardMoveEnd` *required* | `string` | — |  |
| `dashboardRemove` *required* | `string` | — |  |
| `dashboardSizes` *required* | `{ small: string; medium: string; wide: string; tall: string; large: string; full: string }` | — | The closed set of size names, worded once for every widget type. |
| `dashboardSizeEntry` *required* | `(size: string, share: string, current: boolean) => string` | — | A size's entry in a widget's menu: its name and its share of the width (`share` is "¼" or "5/12", empty for the whole width); `current` marks the size the widget stands at. |
| `dashboardHeadingLabel` *required* | `string` | — | The built-in heading type: its name, its sentence in the catalogue, the text a new heading starts with and the label of its text field. |
| `dashboardHeadingSentence` *required* | `string` | — |  |
| `dashboardHeadingText` *required* | `string` | — |  |
| `dashboardHeadingField` *required* | `string` | — |  |
| `dashboardLeft` *required* | `string` | — | Said when "Done" leaves the mode and nothing was changed. |
| `dashboardMoved` *required* | `(title: string, from: number, to: number, of: number) => string` | — | What is spoken after a change. |
| `dashboardDragCancelled` *required* | `(title: string) => string` | — |  |
| `dashboardResized` *required* | `(title: string, size: string) => string` | — |  |
| `dashboardRemoved` *required* | `(title: string) => string` | — |  |
| `dashboardKept` *required* | `string` | — |  |
| `dashboardCancelled` *required* | `string` | — |  |
| `dashboardAddWidget` *required* | `string` | — | The catalogue and the options. |
| `dashboardCatalogue` *required* | `string` | — |  |
| `dashboardCatalogueSentence` *required* | `string` | — |  |
| `dashboardAdd` *required* | `string` | — |  |
| `dashboardAddType` *required* | `(label: string) => string` | — |  |
| `dashboardFootprint` *required* | `(columns: number, rows: number) => string` | — |  |
| `dashboardAdded` *required* | `(title: string, place: number, of: number) => string` | — |  |
| `dashboardOptions` *required* | `string` | — |  |
| `dashboardOptionsChanged` *required* | `(title: string) => string` | — |  |
| `dashboardEmpty` *required* | `string` | — |  |
| `dashboardEmptyEditing` *required* | `string` | — |  |
| `dashboardFailed` *required* | `string` | — |  |
| `dashboardUndone` *required* | `string` | — |  |
| `dashboardRedone` *required* | `string` | — |  |
| `dashboardResetDone` *required* | `string` | — |  |
| `calculationSumSymbol` *required* | `string` | — | The four operators as symbols in a formula line. |
| `calculationDifferenceSymbol` *required* | `string` | — |  |
| `calculationProductSymbol` *required* | `string` | — |  |
| `calculationQuotientSymbol` *required* | `string` | — |  |
| `calculationSumWord` *required* | `string` | — | The same four as words, in the accessible sentence of a line. |
| `calculationDifferenceWord` *required* | `string` | — |  |
| `calculationProductWord` *required* | `string` | — |  |
| `calculationQuotientWord` *required* | `string` | — |  |
| `calculationEquals` *required* | `string` | — | Between the parts of the sentence: "Availability equals ...". |
| `calculationApproximately` *required* | `string` | — | Before a result marked "≈" in the sentence. |
| `calculationApproximateNote` *required* | `string` | — | Beside a result marked "≈": why the rounded operands do not give it. |
| `calculationPercent` *required* | `string` | — | How a percentage is read out: "91.6 percent". |
| `calculationMissing` *required* | `(label: string) => string` | — | Why a quantity has no number - the label is the given at the root of it, or the divisor that is zero. |
| `calculationDivisionByZero` *required* | `(label: string) => string` | — |  |
| `calculationAboveTarget` *required* | `(target: string) => string` | — | The target beside the result, with the target's number and unit. |
| `calculationBelowTarget` *required* | `(target: string) => string` | — |  |
| `calculationOnTarget` *required* | `(target: string) => string` | — |  |
| `calculationWorstInside` *required* | `(verdict: string) => string` | — | The quiet marker on a folded quantity whose derivation holds a worse verdict than its own; the verdict word comes from `verdict*`. |
| `calculationSource` *required* | `(source: string) => string` | — | Where a given number came from. |
| `calculationShowDerivation` *required* | `(label: string) => string` | — | The disclosure button of a derivation, named after the quantity. |
| `calculationHideDerivation` *required* | `(label: string) => string` | — |  |
| `calculationOperandCount` *required* | `(count: number) => string` | — | On a folded line whose operator has more operands than are written out beneath it ([ADR-0028](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0028-a-calculation-is-a-tree-or-a-chain.md)): how many there are. |
| `calculationNoOperands` *required* | `string` | — | On the line of a sum with no operands, where its formula would stand ([ADR-0049](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0049-a-sum-takes-rows-from-data.md)). |

#### Known limits

- Two languages ship; a third is a `Wording` object of your own. No right-to-left ([ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/)).
- It holds only what the components say themselves; your labels, titles and data are yours to translate.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

## Layout

How a screen's parts are arranged, grouped and given room.

### Stack and Grid

Lay a screen's parts out in a column, a row or a grid, spaced by the library's spacing steps instead of pixel numbers (flex and grid layout). Reach for them before a wrapper with margins of its own.

```ts
import { Stack, Grid } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/stack-and-grid/

A gap is a step of the 4 px scale from 1 to 8, the same steps every component spaces itself by, so a screen keeps its proportions. `align` and `justify` pass `alignItems` and `justifyContent` through unchanged; for the rest of flexbox and grid, set `style`.

#### Examples

##### A column

Stack parts below one another and set the space between them with `gap`, a step of the 4 px scale.

```tsx
import { Stack, Text } from "@umriss-ui/core";

export default function AColumn() {
  return (
    <Stack gap={2}>
      <Text size="xs" tone="muted">
        INC-1048 · SEV1 · opened 09:42
      </Text>
      <Text weight="medium">Checkout slow, card payments time out</Text>
      <Text size="sm" tone="secondary">
        Assigned to Jonas Keller, acknowledged at 09:46.
      </Text>
    </Stack>
  );
}
```

##### A row

Set `direction` to `row` for parts beside one another; `align` and `justify` pass straight through to flexbox.

```tsx
import { Badge, Button, Stack, Text } from "@umriss-ui/core";

export default function ARow() {
  return (
    <Stack gap={4}>
      <Stack direction="row" gap={2} align="center">
        <Button size="sm" variant="primary">
          Acknowledge
        </Button>
        <Button size="sm">Assign</Button>
        <Button size="sm" variant="ghost">
          Resolve
        </Button>
      </Stack>
      <Stack direction="row" gap={3} align="center" justify="space-between">
        <Text weight="medium">Checkout</Text>
        <Badge tone="danger">SEV1 open</Badge>
      </Stack>
    </Stack>
  );
}
```

##### Gaps

Pick the smallest `gap` that still separates: 1 or 2 inside a group, 4 to 6 between groups.

```tsx
import { Badge, Stack, Text } from "@umriss-ui/core";

const TEAMS = ["Payments", "Identity", "Discovery"];

export default function Gaps() {
  return (
    <Stack gap={4}>
      {([1, 3, 6] as const).map((gap) => (
        <Stack key={gap} direction="row" gap={gap} align="center">
          <Text size="xs" tone="muted" style={{ width: 48, flex: "none", whiteSpace: "nowrap" }}>
            gap {gap}
          </Text>
          <Stack direction="row" gap={gap} align="center" wrap>
            {TEAMS.map((team) => (
              <Badge key={team}>{team}</Badge>
            ))}
          </Stack>
        </Stack>
      ))}
    </Stack>
  );
}
```

##### Wrapping

Set `wrap` where a row may hold more than fits, so a long run of labels breaks onto the next line.

```tsx
import { Card, CardBody, Stack, Tag } from "@umriss-ui/core";

const SERVICES = ["Checkout", "Billing", "Sign-in", "Search", "Image service", "Notifications", "Webhooks", "Reporting"];

export default function Wrapping() {
  return (
    <Card style={{ maxWidth: 320 }}>
      <CardBody>
        <Stack direction="row" gap={2} wrap>
          {SERVICES.map((name) => (
            <Tag key={name}>{name}</Tag>
          ))}
        </Stack>
      </CardBody>
    </Card>
  );
}
```

##### Fixed columns

Use `columns` where the layout decides the count, such as three figures that always stand side by side.

```tsx
import { Card, CardBody, Grid, Stack, Text } from "@umriss-ui/core";

const FIGURES = [
  { label: "Marketing budget, March", value: "68,000\u00a0€" },
  { label: "Forecast, March", value: "77,500\u00a0€" },
  { label: "Over budget", value: "9,500\u00a0€" },
];

export default function FixedColumns() {
  return (
    <Grid columns={3} gap={3}>
      {FIGURES.map((figure) => (
        <Card key={figure.label}>
          <CardBody>
            <Stack gap={1}>
              <Text size="xs" tone="muted">
                {figure.label}
              </Text>
              <Text weight="medium">{figure.value}</Text>
            </Stack>
          </CardBody>
        </Card>
      ))}
    </Grid>
  );
}
```

##### Columns by width

Set `minItemWidth` instead and the grid fits as many columns as stay readable; it wins over `columns`.

```tsx
import { Card, CardBody, Grid, Stack, Text } from "@umriss-ui/core";

/* Data from the controlling world, written out here so the example runs on its own. */
interface CostCentre {
  id: string;
  name: string;
  owner: string;
  /** The budget of one month. */
  monthlyBudget: number;
}

const COST_CENTRES: readonly CostCentre[] = [
  { id: "CC-1100", name: "Sales", owner: "Helen Marsh", monthlyBudget: 142_000 },
  { id: "CC-1200", name: "Marketing", owner: "Rafael Ortiz", monthlyBudget: 68_000 },
  { id: "CC-2100", name: "Engineering", owner: "Anika Sørensen", monthlyBudget: 188_000 },
  { id: "CC-2200", name: "Design", owner: "Paul Whitaker", monthlyBudget: 54_000 },
  { id: "CC-3100", name: "Customer service", owner: "Grace Obi", monthlyBudget: 61_000 },
  { id: "CC-4100", name: "Finance", owner: "Martina Vogel", monthlyBudget: 47_000 },
  { id: "CC-4200", name: "People", owner: "Daniel Frost", monthlyBudget: 39_000 },
  { id: "CC-4300", name: "IT", owner: "Kenji Arai", monthlyBudget: 83_000 },
  { id: "CC-4400", name: "Facilities", owner: "Olga Ivanova", monthlyBudget: 72_000 },
];

export default function ColumnsByWidth() {
  return (
    <Grid minItemWidth="200px" gap={3}>
      {COST_CENTRES.map((centre) => (
        <Card key={centre.id}>
          <CardBody>
            <Stack gap={1}>
              <Text size="xs" tone="muted">
                {centre.id} · {centre.owner}
              </Text>
              <Text weight="medium">{centre.name}</Text>
              <Text size="sm" tone="secondary">
                {centre.monthlyBudget.toLocaleString("en")} € a month
              </Text>
            </Stack>
          </CardBody>
        </Card>
      ))}
    </Grid>
  );
}
```

##### Columns of their own widths

```tsx
import { Card, CardBody, Grid, Text } from "@umriss-ui/core";

/* One cost centre's key figures, written out here so the example runs on its own. */
const FIGURES = [
  { label: "Cost centre", value: "CC-1200 · Marketing" },
  { label: "Owner", value: "Rafael Ortiz" },
  { label: "Monthly budget", value: "68,000\u00a0€" },
  { label: "Spent, March", value: "77,500\u00a0€, 9,500\u00a0€ over budget" },
  { label: "Approved by", value: "Helen Marsh, Sales" },
];

export default function ColumnsOfTheirOwnWidths() {
  return (
    <Card style={{ maxWidth: 480 }}>
      <CardBody>
        <Grid columns={[140, "fill"]} gap={3}>
          {FIGURES.flatMap((figure) => [
            <Text key={`${figure.label} label`} size="sm" tone="muted">
              {figure.label}
            </Text>,
            <Text key={`${figure.label} value`} size="sm">
              {figure.value}
            </Text>,
          ])}
        </Grid>
      </CardBody>
    </Card>
  );
}
```

##### A tour summary

Stacks and grids nest: a column holds a header row, a grid of key figures and a row of actions.

```tsx
import { Badge, Button, Card, CardBody, Divider, Grid, Heading, Stack, Text } from "@umriss-ui/core";

const FIGURES = [
  { label: "Vehicle", value: "FP 214 K · van" },
  { label: "Driver", value: "Martin Hale" },
  { label: "Stops", value: "11, two late" },
  { label: "Distance", value: "86 km" },
  { label: "Leaves", value: "07:00, North depot" },
  { label: "Back", value: "13:40" },
];

export default function ATourSummary() {
  return (
    <Card style={{ maxWidth: 640 }}>
      <CardBody>
        <Stack gap={4}>
          <Stack direction="row" gap={3} align="center" justify="space-between">
            <Heading level={3} size="lg">
              Tour T-01
            </Heading>
            <Badge tone="warning">2 stops late</Badge>
          </Stack>
          <Grid minItemWidth="160px" gap={4}>
            {FIGURES.map((figure) => (
              <Stack key={figure.label} gap={1}>
                <Text size="xs" tone="muted">
                  {figure.label}
                </Text>
                <Text size="sm">{figure.value}</Text>
              </Stack>
            ))}
          </Grid>
          <Divider />
          <Stack direction="row" gap={2} justify="flex-end">
            <Button size="sm" variant="ghost">
              Call the driver
            </Button>
            <Button size="sm" variant="primary">
              Reorder stops
            </Button>
          </Stack>
        </Stack>
      </CardBody>
    </Card>
  );
}
```

#### Keyboard

The keys of [Button](#/button/keyboard-button) apply here.

#### API

##### `StackProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `direction` | `"row" \| "column"` | `"column"` | Below one another or beside one another. Below is the direction content stands in anyway, without being asked.<br>Shown in: [A row](#/stack-and-grid/a-row), [Gaps](#/stack-and-grid/gaps), [Wrapping](#/stack-and-grid/wrapping) and 69 more |
| `gap` | [`SpaceStep`](#type-SpaceStep)<br>`1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8` | `3` | Spacing as a step of the 4 px spacing steps (1–8).<br>Shown in: [A column](#/stack-and-grid/a-column), [A row](#/stack-and-grid/a-row), [Gaps](#/stack-and-grid/gaps) and 164 more |
| `align` | `CSSProperties["alignItems"]` | — | Alignment across the direction – `alignItems` unchanged.<br>Shown in: [A row](#/stack-and-grid/a-row), [Gaps](#/stack-and-grid/gaps), [A tour summary](#/stack-and-grid/a-tour-summary) and 78 more |
| `justify` | `CSSProperties["justifyContent"]` | — | Distribution along the direction – `justifyContent` unchanged.<br>Shown in: [A row](#/stack-and-grid/a-row), [A tour summary](#/stack-and-grid/a-tour-summary), [Name the same action in every row (VisuallyHidden)](#/visuallyhidden/actions-in-rows) and 9 more |
| `wrap` | `boolean` | `false` | Lets the children wrap when the line does not suffice.<br>Shown in: [Gaps](#/stack-and-grid/gaps), [Wrapping](#/stack-and-grid/wrapping), [Sized to the value (Sizes)](#/sizes/sized-to-the-value) and 32 more |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>`.

##### `GridProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `columns` | `number \| readonly `[`GridColumnWidth`](#type-GridColumnWidth)`[]` | `2` | How many columns, all of one width - or a list with one width per column: a number in pixels, or `"fill"` for a share of what is left. Overridden by minItemWidth.<br>Shown in: [Fixed columns](#/stack-and-grid/fixed-columns), [Columns of their own widths](#/stack-and-grid/columns-of-their-own-widths), [A token for one region (Theming)](#/theming/a-token-for-one-region) and 5 more |
| `minItemWidth` | `string` | — | Responsive: as many columns as fit at this minimum width; wins over `columns`, a list included.<br>Shown in: [Columns by width](#/stack-and-grid/columns-by-width), [A tour summary](#/stack-and-grid/a-tour-summary), [A dark region (Theming)](#/theming/a-dark-region) and 51 more |
| `gap` | [`SpaceStep`](#type-SpaceStep)<br>`1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8` | `4` | Spacing as a step of the 4 px spacing steps (1–8); applies in both directions.<br>Shown in: [Fixed columns](#/stack-and-grid/fixed-columns), [Columns by width](#/stack-and-grid/columns-by-width), [Columns of their own widths](#/stack-and-grid/columns-of-their-own-widths) and 58 more |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>`.

##### Types on this page

###### `SpaceStep`

A step of the spacing scale, from 1 (4 px) to 8 (40 px) - the tokens
`--u-space-1` to `--u-space-8`.

```ts
type SpaceStep = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
```

###### `GridColumnWidth`

The width of one column in `Grid`'s list: a number in pixels, or
`"fill"` for a share of what the other columns leave.

```ts
type GridColumnWidth = number | "fill";
```

#### Known limits

- No breakpoints and no responsive props: a grid follows the width through `minItemWidth`, anything else is your stylesheet's.
- Tiles are not arranged by the user: for a dashboard the reader arranges, see `@umriss-ui/dashboard` ([ADR-0064](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0064-a-dashboard-a-user-arranges-is-a-sequence-on-fixed-columns.md)).

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Divider

A line between two groups of content, across or upright, that may name the part after it (also called a separator or rule).

```ts
import { Divider } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/divider/

#### Examples

##### A line

Put a `Divider` between two groups; without a label it is decoration and hidden from assistive technology.

```tsx
import { Divider, Stack, Text } from "@umriss-ui/core";

export default function ALine() {
  return (
    <Stack gap={3} style={{ maxWidth: 480 }}>
      <Text size="sm">Tour T-01 · FP 214 K · Martin Hale</Text>
      <Divider />
      <Text size="sm" tone="secondary">
        11 stops · 86 km · back at the North depot at 13:40
      </Text>
    </Stack>
  );
}
```

##### Strength and label

The fine line separates rows, `strong` marks a section boundary, and a `label` makes the line a named separator.

```tsx
import { Divider, Stack, Text } from "@umriss-ui/core";

export default function StrengthAndLabel() {
  return (
    <Stack gap={3} style={{ maxWidth: 480 }}>
      <Text size="sm">Stop 1 · Holloway Garden Supplies · 07:25</Text>
      <Divider />
      <Text size="sm">Stop 2 · Oakridge Pharmacy · 07:48</Text>
      <Divider strong />
      <Divider label="Afternoon" />
      <Text size="sm">Stop 8 · Pellham Hardware · 12:05</Text>
    </Stack>
  );
}
```

##### Upright in a bar

Set `orientation` to `vertical` between groups of buttons; it takes its height from a row `Stack`.

```tsx
import { Button, Divider, Stack } from "@umriss-ui/core";

export default function UprightInABar() {
  return (
    <Stack direction="row" gap={3} align="center" wrap>
      <Button size="sm" variant="ghost">
        This sprint
      </Button>
      <Button size="sm" variant="ghost">
        Next sprint
      </Button>
      <Divider orientation="vertical" />
      <Button size="sm" variant="ghost">
        By person
      </Button>
      <Button size="sm" variant="ghost">
        By project
      </Button>
      <Divider orientation="vertical" strong />
      <Button size="sm" variant="ghost">
        Export
      </Button>
    </Stack>
  );
}
```

#### When to use something else

- A group that needs a surface and a heading of its own → Card

#### Keyboard

The keys of [Button](#/button/keyboard-button) apply here.

#### API

##### `DividerProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Horizontally it separates rows, vertically it separates columns.<br>Shown in: [Configurator](#/divider/configurator-divider), [Upright in a bar](#/divider/upright-in-a-bar) |
| `strong` | `boolean` | `false` | A stronger line - for section boundaries rather than row separation.<br>Shown in: [Configurator](#/divider/configurator-divider), [Strength and label](#/divider/strength-and-label), [Upright in a bar](#/divider/upright-in-a-bar) |
| `label` | `ReactNode` | — | A label in the middle. It makes the line a named separator.<br>Shown in: [Configurator](#/divider/configurator-divider), [Strength and label](#/divider/strength-and-label) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>`.

### Card

A surface that holds one block of a screen together: a head with its title and actions, and a body (also called a panel or tile). Reach for it for each block of a dashboard or a detail view.

```ts
import { Card, CardHeader, CardBody } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/card/

The line under the head is not the normal case; whitespace carries the hierarchy. Set it where the body runs edge to edge, a table or a log, together with a flush body.

A collapsible card turns its head into the button for its body, with the state in the card or, controlled, in your application.

#### Examples

##### Head and body

A `CardHeader` names the block, a `CardBody` holds whatever belongs to it; the card knows nothing of its content.

```tsx
import { Card, CardBody, CardHeader, Text } from "@umriss-ui/core";

export default function HeadAndBody() {
  return (
    <Card style={{ maxWidth: 480 }}>
      <CardHeader title="Checkout" />
      <CardBody>
        <Text size="sm" tone="secondary">
          Payments team · tier 1 · 95th percentile below 300 ms, 99.95 % available a month.
        </Text>
      </CardBody>
    </Card>
  );
}
```

##### Eyebrow and actions

An `eyebrow` names the kind of thing above the title; `actions` stand on the right, a badge or a button or both.

```tsx
import { Badge, Button, Card, CardBody, CardHeader, Stack, Text } from "@umriss-ui/core";

export default function EyebrowAndActions() {
  return (
    <Card style={{ maxWidth: 520 }}>
      <CardHeader
        eyebrow="Invoice"
        title="INV-26-0318 · Brandlow Office Supply"
        actions={
          <Stack direction="row" gap={2} align="center">
            <Badge tone="warning">Awaiting approval</Badge>
            <Button size="sm" variant="primary">
              Approve
            </Button>
          </Stack>
        }
      />
      <CardBody>
        <Text size="sm" tone="secondary">
          Facilities, CC-4400 · received 16 March, due 15 April · 2,321.98 € gross.
        </Text>
      </CardBody>
    </Card>
  );
}
```

##### A flush body

Where the body runs edge to edge, like a log or a table, set `flush` on the body and `divider` on the head.

```tsx
import { Card, CardBody, CardHeader } from "@umriss-ui/core";

const LOG = `09:42:10  OPENED        INC-1048 by the latency alert on Checkout
09:46:02  ACKNOWLEDGED  Jonas Keller
09:58:37  NOTE          Card payments time out at the provider; retries doubled the load
10:11:05  MITIGATED     Retries capped at one, p95 back below 300 ms`;

export default function AFlushBody() {
  return (
    <Card style={{ maxWidth: 640 }}>
      <CardHeader divider eyebrow="INC-1048" title="Timeline" />
      <CardBody flush>
        <pre
          style={{
            margin: 0,
            padding: "var(--u-space-4)",
            overflowX: "auto",
            fontFamily: "var(--u-font-mono)",
            fontSize: "var(--u-text-xs)",
            lineHeight: 1.7,
            color: "var(--u-color-text-secondary)",
          }}
        >
          {LOG}
        </pre>
      </CardBody>
    </Card>
  );
}
```

##### Fold the body

Set `collapsible` and the head becomes the button for the body; `defaultCollapsed` starts it folded.

```tsx
import { Badge, Card, CardBody, CardHeader, Stack, Text } from "@umriss-ui/core";

const LATE = [
  { stop: "Stop 4 · Marlow & Finch Books", window: "08:00–10:00", arrival: "10:35" },
  { stop: "Stop 9 · Ashcombe Dental", window: "10:00–12:00", arrival: "12:40" },
];

export default function FoldTheBody() {
  return (
    <Card collapsible defaultCollapsed style={{ maxWidth: 520 }}>
      <CardHeader eyebrow="Tour T-01" title="Late stops" actions={<Badge pill>{LATE.length}</Badge>} />
      <CardBody>
        <Stack gap={2}>
          {LATE.map((late) => (
            <Text key={late.stop} size="sm">
              {late.stop} - window {late.window}, planned {late.arrival}
            </Text>
          ))}
        </Stack>
      </CardBody>
    </Card>
  );
}
```

##### Fold from outside

Control `collapsed` with `onCollapsedChange` when a toolbar folds every card at once, or an address keeps which stand open.

```tsx
import { useState } from "react";
import { Button, Card, CardBody, CardHeader, Stack, Text } from "@umriss-ui/core";

const PEOPLE = [
  { id: "arjun", name: "Arjun Mehta", work: "Member portal: sign-in form, 16 h left" },
  { id: "chloe", name: "Chloe Durand", work: "Member portal: profile page, 10 h left" },
  { id: "noah", name: "Noah Fischer", work: "Online shop: search results design, 6 h left" },
];

export default function FoldFromOutside() {
  const [folded, setFolded] = useState<ReadonlySet<string>>(() => new Set(["noah"]));
  const fold = (id: string, collapsed: boolean) =>
    setFolded((previous) => {
      const next = new Set(previous);
      if (collapsed) next.add(id);
      else next.delete(id);
      return next;
    });

  return (
    <Stack gap={3} style={{ maxWidth: 520 }}>
      <Stack direction="row" gap={2}>
        <Button size="sm" onClick={() => setFolded(new Set())}>
          Open all
        </Button>
        <Button size="sm" onClick={() => setFolded(new Set(PEOPLE.map((p) => p.id)))}>
          Fold all
        </Button>
      </Stack>
      {PEOPLE.map((person) => (
        <Card
          key={person.id}
          collapsible
          collapsed={folded.has(person.id)}
          onCollapsedChange={(collapsed) => fold(person.id, collapsed)}
        >
          <CardHeader eyebrow="Sprint 14" title={person.name} />
          <CardBody>
            <Text size="sm">{person.work}</Text>
          </CardBody>
        </Card>
      ))}
    </Stack>
  );
}
```

##### Cards on a dashboard

Each block of a dashboard is a card in a grid; a card with nothing to show says so with an `EmptyState`.

```tsx
import { Badge, Button, Card, CardBody, CardHeader, EmptyState, Grid, Stack, Text } from "@umriss-ui/core";

const INCIDENTS = [
  { id: "INC-1048", title: "Checkout slow, card payments time out", severity: "SEV1" },
  { id: "INC-1047", title: "Webhook deliveries delayed", severity: "SEV3" },
];

export default function CardsOnADashboard() {
  return (
    <Grid minItemWidth="240px" gap={4}>
      <Card>
        <CardHeader title="Open incidents" actions={<Badge tone="danger">{INCIDENTS.length}</Badge>} />
        <CardBody>
          <Stack gap={3}>
            {INCIDENTS.map((incident) => (
              <Stack key={incident.id} gap={1}>
                <Text size="xs" tone="muted">
                  {incident.id} · {incident.severity}
                </Text>
                <Text size="sm">{incident.title}</Text>
              </Stack>
            ))}
          </Stack>
        </CardBody>
      </Card>
      <Card>
        <CardHeader title="On call" />
        <CardBody>
          <Stack gap={2}>
            <Text size="sm">Primary: Jonas Keller</Text>
            <Text size="sm">Secondary: Ada Mwangi</Text>
            <Text size="xs" tone="muted">
              Handover tomorrow at 09:00
            </Text>
          </Stack>
        </CardBody>
      </Card>
      <Card>
        <CardHeader title="Snoozed alerts" />
        <CardBody>
          <EmptyState
            title="Nothing snoozed"
            description="Alerts you snooze wait here until they wake."
            action={<Button size="sm">Open the alert list</Button>}
          />
        </CardBody>
      </Card>
    </Grid>
  );
}
```

#### When to use something else

- Many sections of one long content, opened one or several at a time → Accordion
- A line between two groups without a surface → Divider

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Reaches the actions in the head and, in a collapsible card, its Show or Hide button; a folded body is inert and passed over. |
| `Enter / Space` | On Show or Hide, unfolds or folds the body. |

The keys of [Button](#/button/keyboard-button) apply here.

#### API

##### `CardProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `collapsible` | `boolean` | `false` | Allows collapsing and expanding the body through the header.<br>Shown in: [Fold the body](#/card/fold-the-body), [Fold from outside](#/card/fold-from-outside) |
| `defaultCollapsed` | `boolean` | `false` | Initial state of the collapse mechanism; afterwards it belongs to the card. Only effective together with `collapsible`.<br>Shown in: [Fold the body](#/card/fold-the-body) |
| `collapsed` | `boolean` | — | Controlled: whether the body is folded away - for a card folded from outside, or one whose state is kept in an address. Only effective together with `collapsible`.<br>Shown in: [Fold from outside](#/card/fold-from-outside) |
| `onCollapsedChange` | `(collapsed: boolean) => void` | — | Reports the wish of the header's button. Controlled, the card folds only once `collapsed` follows; uncontrolled it is merely a message.<br>Shown in: [Fold from outside](#/card/fold-from-outside) |
| `ref` | `Ref<HTMLElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of the rendered element.

##### `CardHeaderProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` *required* | `ReactNode` | — | The heading of the card. A node and not merely text, so that an identifier with markup can stand in it too.<br>Shown in: [Head and body](#/card/head-and-body), [Eyebrow and actions](#/card/eyebrow-and-actions), [A flush body](#/card/a-flush-body) and 27 more |
| `eyebrow` | `ReactNode` | — | Small all-caps label above the title, e.g. a category.<br>Shown in: [Eyebrow and actions](#/card/eyebrow-and-actions), [A flush body](#/card/a-flush-body), [Fold the body](#/card/fold-the-body) and 17 more |
| `actions` | `ReactNode` | — | Right-aligned area, e.g. buttons or badges.<br>Shown in: [Eyebrow and actions](#/card/eyebrow-and-actions), [Fold the body](#/card/fold-the-body), [Cards on a dashboard](#/card/cards-on-a-dashboard) and 13 more |
| `divider` | `boolean` | `false` | A dividing line below the head. Only set it where the body needs it - typically with flush data (flush tables, logs). With normal content the white space carries the hierarchy on its own.<br>Shown in: [A flush body](#/card/a-flush-body) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>` – without `title`.

##### `CardBodyProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `flush` | `boolean` | `false` | Removes the inner padding, e.g. for flush tables.<br>Shown in: [A flush body](#/card/a-flush-body) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>`.

### Splitter

Two panes with a draggable line between them (also called a split view or resizable panes). Use it when the user needs both at once and decides how much of each: a list beside its detail, a chart above its alerts.

```ts
import { Splitter } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/splitter/

A splitter divides the room it is given and does not size it: give its box a height. For three panes, nest a splitter in one of the two.

Name the separator after the pane it sizes, so a screen reader says "Services, 35" instead of the general name.

#### Examples

##### Two panes

Give the splitter a box with a height and two children; `defaultValue` is the first pane's starting share in per cent.

```tsx
import { Card, Splitter, Text } from "@umriss-ui/core";

export default function TwoPanes() {
  return (
    <Card style={{ height: 200 }}>
      <Splitter defaultValue={35} style={{ height: "100%" }}>
        <div style={{ padding: 16 }}>
          <Text size="sm">Today's tours</Text>
        </div>
        <div style={{ padding: 16 }}>
          <Text size="sm">The chosen tour's stops</Text>
        </div>
      </Splitter>
    </Card>
  );
}
```

##### One above the other

Set `orientation` to `vertical` for a chart above its events; `min` and `max` keep either pane from vanishing under a drag.

```tsx
import { Badge, Card, Sparkline, Splitter, Stack, Text } from "@umriss-ui/core";

/* Data from the operations world, written out here so the example runs on its own. */
/** A small LCG - the same numbers on every computer. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

const at = (day: number, hours: number, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();
const MINUTE = 60_000;

/** Tuesday, 17 March 2026, 10:30 - the moment the screens are read at. */
const NOW = at(17, 10, 30);

interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface MetricPoint {
  t: number;
  /** Median and 95th percentile latency, in ms. */
  p50: number;
  p95: number;
  /** Failed requests, in per cent. */
  errorRate: number;
  /** Requests per minute. */
  requests: number;
}

/** Requests per minute at the busiest hour, by tier. */
const VOLUME = { 1: 900, 2: 400, 3: 120 } as const;

/** A service's latency and error rate every five minutes of today, from
    midnight up to now. Busy by day, quiet at night; Checkout's 95th percentile
    climbs well past its objective from 09:40 to 10:10, and its errors with it. */
function metrics(serviceId: string): MetricPoint[] {
  const index = SERVICES.findIndex((one) => one.id === serviceId);
  const service = SERVICES[index];
  if (service === undefined) throw new Error(`No service "${serviceId}".`);
  const r = random(1000 + index * 37);
  const points: MetricPoint[] = [];
  let drift = 0;
  for (let t = at(17, 0); t <= NOW; t += 5 * MINUTE) {
    const hour = (t - at(17, 0)) / (60 * MINUTE);
    const load = 0.35 + 0.65 * Math.max(0, Math.sin((Math.PI * (hour - 5)) / 16));
    drift = 0.8 * drift + (r() - 0.5) * 0.08;
    const base = service.latencySlo * (0.45 + 0.2 * load + drift);
    const surge = serviceId === "checkout" && t >= at(17, 9, 40) && t < at(17, 10, 10) ? 1.9 : 1;
    const p95 = Math.round(base * surge * (1 + r() * 0.08));
    points.push({
      t,
      p50: Math.round(p95 * (0.42 + r() * 0.06)),
      p95,
      errorRate: Math.round((0.05 + r() * 0.12 + (surge > 1 ? 2.4 + r() : 0)) * 100) / 100,
      requests: Math.round(VOLUME[service.tier] * load * (1 + (r() - 0.5) * 0.1)),
    });
  }
  return points;
}

const P95 = metrics("checkout").map((point) => point.p95);

export default function OneAboveTheOther() {
  return (
    <Card style={{ height: 280, maxWidth: 560 }}>
      <Splitter orientation="vertical" defaultValue={60} min={20} max={75} separatorLabel="Latency" style={{ height: "100%" }}>
        <Stack gap={2} style={{ padding: 16, height: "100%" }}>
          <Text size="xs" tone="muted">
            Checkout · p95 latency today, ms
          </Text>
          <Sparkline data={P95} width={500} height={72} />
        </Stack>
        <Stack gap={2} style={{ padding: 16 }}>
          <Stack direction="row" gap={2} align="center">
            <Badge tone="danger">High</Badge>
            <Text size="sm">p95 latency above 300 ms since 09:41</Text>
          </Stack>
          <Stack direction="row" gap={2} align="center">
            <Badge>Resolved</Badge>
            <Text size="sm">Error rate above 2 %, 09:43 to 10:11</Text>
          </Stack>
        </Stack>
      </Splitter>
    </Card>
  );
}
```

##### Keep the share

Control `value` with `onChange` to keep the share in the user's settings, or to set it from a button. Focus the separator and the arrow keys move it by `step`, here ten per cent at a time.

```tsx
import { useState } from "react";
import { Button, Card, Splitter, Stack, Text } from "@umriss-ui/core";

export default function KeepTheShare() {
  const [share, setShare] = useState(50);

  return (
    <Stack gap={3} style={{ maxWidth: 560 }}>
      <Stack direction="row" gap={2} align="center">
        <Button size="sm" variant="secondary" onClick={() => setShare(30)}>
          Narrow list
        </Button>
        <Button size="sm" variant="secondary" onClick={() => setShare(50)}>
          Half and half
        </Button>
        <Text size="xs" tone="muted" style={{ fontVariantNumeric: "tabular-nums" }}>
          People: {share.toFixed(1)} %
        </Text>
      </Stack>
      <Card style={{ height: 180 }}>
        <Splitter value={share} onChange={setShare} min={20} max={80} step={10} separatorLabel="People" style={{ height: "100%" }}>
          <div style={{ padding: 16 }}>
            <Text size="sm">People of the Web team</Text>
          </div>
          <div style={{ padding: 16 }}>
            <Text size="sm">Chloe Durand · 40 h a week · 34 h planned in sprint 14</Text>
          </div>
        </Splitter>
      </Card>
    </Stack>
  );
}
```

##### Three panes

Nest a splitter in a pane for a list, its detail and the detail's alerts; name each separator after the pane it sizes.

```tsx
import { useState } from "react";
import { Badge, Button, Card, Grid, Sparkline, Splitter, Stack, Stat, Text } from "@umriss-ui/core";

/* Data from the operations world, written out here so the example runs on its own. */
/** A small LCG - the same numbers on every computer. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

const at = (day: number, hours: number, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();
const MINUTE = 60_000;

/** Tuesday, 17 March 2026, 10:30 - the moment the screens are read at. */
const NOW = at(17, 10, 30);

interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface MetricPoint {
  t: number;
  /** Median and 95th percentile latency, in ms. */
  p50: number;
  p95: number;
  /** Failed requests, in per cent. */
  errorRate: number;
  /** Requests per minute. */
  requests: number;
}

/** Requests per minute at the busiest hour, by tier. */
const VOLUME = { 1: 900, 2: 400, 3: 120 } as const;

/** A service's latency and error rate every five minutes of today, from
    midnight up to now. Busy by day, quiet at night; Checkout's 95th percentile
    climbs well past its objective from 09:40 to 10:10, and its errors with it. */
function metrics(serviceId: string): MetricPoint[] {
  const index = SERVICES.findIndex((one) => one.id === serviceId);
  const service = SERVICES[index];
  if (service === undefined) throw new Error(`No service "${serviceId}".`);
  const r = random(1000 + index * 37);
  const points: MetricPoint[] = [];
  let drift = 0;
  for (let t = at(17, 0); t <= NOW; t += 5 * MINUTE) {
    const hour = (t - at(17, 0)) / (60 * MINUTE);
    const load = 0.35 + 0.65 * Math.max(0, Math.sin((Math.PI * (hour - 5)) / 16));
    drift = 0.8 * drift + (r() - 0.5) * 0.08;
    const base = service.latencySlo * (0.45 + 0.2 * load + drift);
    const surge = serviceId === "checkout" && t >= at(17, 9, 40) && t < at(17, 10, 10) ? 1.9 : 1;
    const p95 = Math.round(base * surge * (1 + r() * 0.08));
    points.push({
      t,
      p50: Math.round(p95 * (0.42 + r() * 0.06)),
      p95,
      errorRate: Math.round((0.05 + r() * 0.12 + (surge > 1 ? 2.4 + r() : 0)) * 100) / 100,
      requests: Math.round(VOLUME[service.tier] * load * (1 + (r() - 0.5) * 0.1)),
    });
  }
  return points;
}

/** A kind of alert. */
interface AlertType {
  id: string;
  label: string;
  priority: "high" | "medium" | "low";
}

const ALERT_TYPES: readonly AlertType[] = [
  { id: "checkout-latency", label: "Checkout · p95 latency above 300 ms", priority: "high" },
  { id: "checkout-errors", label: "Checkout · error rate above 2\u00a0%", priority: "high" },
  { id: "webhooks-queue", label: "Webhooks · queue older than 5 min", priority: "medium" },
  { id: "search-latency", label: "Search · p95 latency above 250 ms", priority: "medium" },
  { id: "images-disk", label: "Image service · disk 85 % full", priority: "low" },
  { id: "reports-job", label: "Reporting · nightly job late", priority: "low" },
];

/** One alert. */
type Alert = {
  id: string;
  type: string;
  lifecycle: "active-unacknowledged" | "active-acknowledged" | "resolved-unacknowledged" | "resolved-acknowledged";
  raised: number;
  resolved?: number;
  acknowledgedAt?: number;
} & (
  | { availability?: "in-service" | "suppressed" | "disabled"; snooze?: undefined }
  | { availability: "snoozed"; snooze: { until: number; by: string } }
);

/** The alerts as they stand at 10:30. */
const ALERTS: readonly Alert[] = [
  { id: "a-1", type: "checkout-latency", lifecycle: "active-acknowledged", raised: at(17, 9, 41), acknowledgedAt: at(17, 9, 46) },
  { id: "a-2", type: "checkout-errors", lifecycle: "resolved-unacknowledged", raised: at(17, 9, 43), resolved: at(17, 10, 11) },
  { id: "a-3", type: "webhooks-queue", lifecycle: "active-acknowledged", raised: at(17, 7, 12), acknowledgedAt: at(17, 8, 2) },
  { id: "a-4", type: "search-latency", lifecycle: "active-unacknowledged", raised: at(17, 10, 24) },
  { id: "a-5", type: "search-latency", lifecycle: "resolved-acknowledged", raised: at(17, 8, 5), resolved: at(17, 8, 9), acknowledgedAt: at(17, 8, 6) },
  { id: "a-6", type: "images-disk", lifecycle: "active-unacknowledged", raised: at(17, 6, 0), availability: "snoozed", snooze: { until: at(17, 14), by: "Tomasz Nowak" } },
  { id: "a-7", type: "reports-job", lifecycle: "active-unacknowledged", raised: at(17, 4, 30), availability: "disabled" },
];

const TIER_ONE = SERVICES.filter((service) => service.tier === 1);

export default function ThreePanes() {
  const [chosen, setChosen] = useState("checkout");
  const service = TIER_ONE.find((s) => s.id === chosen) ?? TIER_ONE[0]!;
  const p95 = metrics(service.id).map((point) => point.p95);
  const alerts = ALERTS.filter(
    (alert) => alert.type.startsWith(`${service.id}-`) && alert.lifecycle.startsWith("active"),
  );

  return (
    <Card style={{ height: 340 }}>
      <Splitter defaultValue={26} min={20} max={45} separatorLabel="Services" style={{ height: "100%" }}>
        <Stack gap={1} style={{ padding: 12 }}>
          <Text size="xs" tone="muted" style={{ padding: "0 8px 4px" }}>
            Tier 1
          </Text>
          {TIER_ONE.map((s) => (
            <Button
              key={s.id}
              size="sm"
              variant={s.id === chosen ? "secondary" : "ghost"}
              aria-pressed={s.id === chosen}
              onClick={() => setChosen(s.id)}
            >
              {s.name}
            </Button>
          ))}
        </Stack>
        <Splitter orientation="vertical" defaultValue={62} min={30} max={75} separatorLabel={`${service.name} latency`} style={{ height: "100%" }}>
          <Grid minItemWidth="180px" gap={4} style={{ padding: 16 }}>
            <Stat
              label={`${service.name} · p95`}
              value={p95[p95.length - 1]}
              unit="ms"
              limits={{ limits: [{ value: service.latencySlo, side: "upper", severity: "warning" }] }}
            />
            <Stack gap={2}>
              <Text size="xs" tone="muted">
                Today
              </Text>
              <Sparkline data={p95} width={180} height={48} />
            </Stack>
          </Grid>
          <Stack gap={2} style={{ padding: 16 }}>
            {alerts.length > 0 ? (
              alerts.map((alert) => (
                <Stack key={alert.id} direction="row" gap={2} align="center">
                  <Badge tone="warning">Active</Badge>
                  <Text size="sm">{ALERT_TYPES.find((type) => type.id === alert.type)?.label}</Text>
                </Stack>
              ))
            ) : (
              <Text size="sm" tone="muted">
                No active alerts for {service.name}.
              </Text>
            )}
          </Stack>
        </Splitter>
      </Splitter>
    </Card>
  );
}
```

#### When to use something else

- Views the user switches between rather than sees together → Tabs

#### Keyboard

| Key | Action |
|---|---|
| `Arrow Left / Arrow Right` | Side by side: moves the line by one step, 5 % unless set otherwise. |
| `Arrow Up / Arrow Down` | One above the other: moves the line by one step. |
| `Home / End` | Moves the line to the smallest or the largest share. |
| `Enter` | Folds the first pane to its smallest share; again, brings it back. |

#### API

##### `SplitterProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | How the two panes stand: `horizontal` side by side, `vertical` one above the other - a trend above, its alarms below.<br>Shown in: [One above the other](#/splitter/one-above-the-other), [Three panes](#/splitter/three-panes) |
| `defaultValue` | `number` | `50` | Uncontrolled: the share to start at.<br>Shown in: [Two panes](#/splitter/two-panes), [One above the other](#/splitter/one-above-the-other), [Three panes](#/splitter/three-panes) |
| `value` | `number` | — | Controlled: the first pane's share of the room, in per cent.<br>Shown in: [Keep the share](#/splitter/keep-the-share) |
| `min` | `number` | `0` | The smallest share of the first pane, and where Enter collapses it to.<br>Shown in: [One above the other](#/splitter/one-above-the-other), [Keep the share](#/splitter/keep-the-share), [Three panes](#/splitter/three-panes) |
| `max` | `number` | `100` | The largest share of the first pane.<br>Shown in: [One above the other](#/splitter/one-above-the-other), [Keep the share](#/splitter/keep-the-share), [Three panes](#/splitter/three-panes) |
| `step` | `number` | `5` | How far an arrow key moves the separator, in per cent.<br>Shown in: [Keep the share](#/splitter/keep-the-share) |
| `separatorLabel` | `string` | the wording's "Resize the panes" | The separator's name. The APG names it after the first pane ("Trend").<br>Shown in: [One above the other](#/splitter/one-above-the-other), [Keep the share](#/splitter/keep-the-share), [Three panes](#/splitter/three-panes) |
| `children` *required* | `[ReactNode, ReactNode]` | — | The first pane and the second, in this order.<br>Shown in: [Two panes](#/splitter/two-panes), [One above the other](#/splitter/one-above-the-other), [Keep the share](#/splitter/keep-the-share) and 1 more |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` | `(value: number) => void` | — | Reports every move, by pointer or key, as the first pane's share.<br>Shown in: [Keep the share](#/splitter/keep-the-share) |

Also takes every attribute of `<div>` – without `children`, `defaultValue`, `onChange`.

#### Known limits

- Two panes per splitter, no more. Tiles are not arranged by the user: for a dashboard the reader arranges, see `@umriss-ui/dashboard` ([ADR-0064](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0064-a-dashboard-a-user-arranges-is-a-sequence-on-fixed-columns.md)).
- It does not remember the share beyond its own life; keep it in the user's settings through `value` and `onChange`.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

## Typography

The type a screen is set in.

### Typography

Sets paragraphs, headings and links on the library's type scale, so a screen of your own reads like the components around it. Reach for it wherever you would otherwise style text by hand.

```ts
import { Text, Heading, Link } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/typography/

A heading's outline level and its size are independent: choose the level for the page's structure, the size for the eye.

`Text` renders a `p`; inside a line, render it `as` a `span`.

#### Examples

##### Text, heading and link

A heading, a paragraph and a link in it, each at its default: the base of every surface.

```tsx
import { Heading, Link, Stack, Text } from "@umriss-ui/core";

export default function TextHeadingLink() {
  return (
    <Stack gap={2}>
      <Heading level={3}>Checkout</Heading>
      <Text>
        Takes card and wallet payments for every booking. Owned by the Payments team;{" "}
        <Link href="#/typography">see the on-call rota</Link>.
      </Text>
    </Stack>
  );
}
```

##### Sizes

Six steps from `xs` to `2xl`; `md` is body text, `sm` and `xs` carry dense tables, hints and timestamps.

```tsx
import { Stack, Text } from "@umriss-ui/core";

export default function Sizes() {
  return (
    <Stack gap={2}>
      <Text size="2xl">2xl · Q1 budget review</Text>
      <Text size="xl">xl · Marketing is 12 % over plan</Text>
      <Text size="lg">lg · Cost centre CC-1200</Text>
      <Text size="md">md · Actuals are booked until the end of February.</Text>
      <Text size="sm">sm · Forecast updated by Rafael Ortiz</Text>
      <Text size="xs">xs · Last booking 17/03/2026 10:30</Text>
    </Stack>
  );
}
```

##### Tones and weights

Step text back with `tone` rather than a colour of your own; `weight` has three steps, `medium` for emphasis inside a line. A `Heading` is semibold unless its `weight` says otherwise - `medium` for a quieter one.

```tsx
import { Heading, Stack, Text } from "@umriss-ui/core";

export default function TonesAndWeights() {
  return (
    <Stack gap={2}>
      <Heading level={3} size="md">
        Morning dispatch
      </Heading>
      <Heading level={4} size="md" weight="medium">
        Tours today
      </Heading>
      <Text weight="semibold">Tour T-03 · North depot</Text>
      <Text>
        14 stops, <Text as="span" weight="medium">2 running late</Text>
      </Text>
      <Text size="sm" tone="secondary">
        Driver Martin Hale · van FP 214 K
      </Text>
      <Text size="xs" tone="muted">
        Position reported 3 minutes ago
      </Text>
    </Stack>
  );
}
```

##### Numbers and identifiers

Set figures and codes `mono`: tabular digits keep amounts in a column aligned, and 0 and O stay apart.

```tsx
import { Grid, Text } from "@umriss-ui/core";

const ROWS = [
  { centre: "CC-1100 Sales", actual: "138,412.00" },
  { centre: "CC-1200 Marketing", actual: "76,190.50" },
  { centre: "CC-2100 Engineering", actual: "181,007.25" },
  { centre: "CC-4400 Facilities", actual: "9,880.00" },
];

export default function Numbers() {
  return (
    <Grid columns={2} gap={2} style={{ maxWidth: 360 }}>
      {ROWS.flatMap((row) => [
        <Text key={`${row.centre}-name`} size="sm">
          {row.centre}
        </Text>,
        <Text key={`${row.centre}-actual`} size="sm" mono style={{ textAlign: "right" }}>
          {row.actual}
        </Text>,
      ])}
    </Grid>
  );
}
```

##### Tracking and leading

Use `tracking="caps"` for small letter-spaced labels and `leading="tight"` for key figures and labels that run over two lines.

```tsx
import { Stack, Text } from "@umriss-ui/core";

export default function TrackingAndLeading() {
  return (
    <Stack gap={3} style={{ maxWidth: 280 }}>
      <Text size="xs" tracking="caps" tone="muted">
        Sprint 14 · Web team
      </Text>
      <Text size="2xl" tracking="display" leading="tight" weight="semibold">
        38 of 52 points
      </Text>
      <Text size="sm" leading="tight" tone="secondary">
        Checkout flow redesign and member portal sign-up, carried over from sprint 13
      </Text>
    </Stack>
  );
}
```

##### Choose the level apart from the size

Pick `level` for the page's outline and `size` for the eye; a small card title can still be a second-level heading.

```tsx
import { Heading, Stack, Text } from "@umriss-ui/core";

export default function LevelAndSize() {
  return (
    <Stack gap={3}>
      <Heading level={2} size="sm" tone="secondary">
        Open incidents
      </Heading>
      <Heading level={3} size="xl">
        INC-1048 · Checkout slow, card payments time out
      </Heading>
      <Text size="sm" tone="secondary">
        A screen reader lists "Open incidents" as the section and the incident inside it, whatever
        their sizes.
      </Text>
    </Stack>
  );
}
```

##### Link out of the application

Set `external` for a link that leaves the application: it opens a new tab and cuts the new page's access to this one.

```tsx
import { Link, Text } from "@umriss-ui/core";

export default function ExternalLink() {
  return (
    <Text size="sm">
      Card payments time out at the provider.{" "}
      <Link href="https://status.example.org" external>
        Provider status page
      </Link>{" "}
      · <Link href="#/typography">Incident INC-1048</Link>
    </Text>
  );
}
```

##### Handle long values

Text wraps and headings balance their lines; where one line is a must, clip it with CSS of your own and keep the whole value in `title`.

```tsx
import { Heading, Stack, Text } from "@umriss-ui/core";

const CUSTOMER = "Holloway Garden Supplies & Landscaping Wholesale, Unit 14, Riverside Trading Estate";
const REFERENCE = "SH-1042/FP214K/2026-03-17T10:30:00Z/attempt-2";

export default function LongValues() {
  return (
    <Stack gap={3} style={{ maxWidth: 320 }}>
      <Heading level={4}>{CUSTOMER}</Heading>
      <Text size="sm" mono style={{ overflowWrap: "anywhere" }}>
        {REFERENCE}
      </Text>
      <Text
        size="sm"
        tone="secondary"
        title={CUSTOMER}
        style={{ whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}
      >
        {CUSTOMER}
      </Text>
    </Stack>
  );
}
```

##### Set an incident summary

The pieces together in a detail panel: a caps label, a heading, mono identifiers and times, body text, a muted footnote and links.

```tsx
import { Badge, Card, CardBody, Heading, Link, Stack, Text } from "@umriss-ui/core";

/* Data from the operations world, written out here so the example runs on its own. */
const at = (day: number, hours: number, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();

interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface Engineer {
  id: string;
  name: string;
  team: string;
}

const ENGINEERS: readonly Engineer[] = [
  { id: "priya", name: "Priya Raman", team: "Payments" },
  { id: "jonas", name: "Jonas Keller", team: "Payments" },
  { id: "ada", name: "Ada Mwangi", team: "Identity" },
  { id: "tomasz", name: "Tomasz Nowak", team: "Discovery" },
  { id: "leila", name: "Leila Haddad", team: "Discovery" },
  { id: "sam", name: "Sam Okafor", team: "Messaging" },
  { id: "ines", name: "Ines Duarte", team: "Integrations" },
  { id: "felix", name: "Felix Brandt", team: "Insights" },
];

interface Incident {
  id: string;
  title: string;
  service: string;
  severity: "SEV1" | "SEV2" | "SEV3";
  opened: number;
  acknowledged?: number;
  resolved?: number;
  /** An engineer's id. */
  assignee: string;
}

const INCIDENTS: readonly Incident[] = [
  { id: "INC-1048", title: "Checkout slow, card payments time out", service: "checkout", severity: "SEV1", opened: at(17, 9, 42), acknowledged: at(17, 9, 46), assignee: "jonas" },
  { id: "INC-1047", title: "Webhook deliveries delayed", service: "webhooks", severity: "SEV3", opened: at(17, 7, 15), acknowledged: at(17, 8, 2), assignee: "ines" },
  { id: "INC-1046", title: "Thumbnails missing for new uploads", service: "images", severity: "SEV2", opened: at(16, 22, 5), acknowledged: at(16, 22, 11), resolved: at(17, 0, 40), assignee: "tomasz" },
  { id: "INC-1045", title: "Sign-in codes arrive late", service: "sign-in", severity: "SEV2", opened: at(16, 14, 20), acknowledged: at(16, 14, 24), resolved: at(16, 15, 5), assignee: "ada" },
  { id: "INC-1044", title: "Monthly report export fails", service: "reports", severity: "SEV3", opened: at(15, 10, 0), acknowledged: at(16, 9, 12), resolved: at(16, 11, 30), assignee: "felix" },
  { id: "INC-1043", title: "Search returns no results for some regions", service: "search", severity: "SEV1", opened: at(14, 18, 30), acknowledged: at(14, 18, 33), resolved: at(14, 19, 55), assignee: "leila" },
  { id: "INC-1042", title: "Duplicate reminder e-mails", service: "notifications", severity: "SEV3", opened: at(13, 8, 45), acknowledged: at(13, 9, 30), resolved: at(13, 13, 0), assignee: "sam" },
  { id: "INC-1041", title: "Invoices generated twice", service: "billing", severity: "SEV2", opened: at(12, 16, 10), acknowledged: at(12, 16, 18), resolved: at(12, 18, 40), assignee: "priya" },
];

const incident = INCIDENTS[0]!;
const service = SERVICES.find((s) => s.id === incident.service)!;
const assignee = ENGINEERS.find((e) => e.id === incident.assignee)!;
const time = (t: number) =>
  new Date(t).toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" });

export default function IncidentSummary() {
  return (
    <Card>
      <CardBody>
        <Stack gap={3}>
          <Stack direction="row" gap={2} align="center">
            <Text size="xs" tracking="caps" tone="muted">
              {service.team} · {service.name}
            </Text>
            <Badge tone="danger">{incident.severity}</Badge>
          </Stack>
          <Heading level={3} size="lg">
            {incident.title}
          </Heading>
          <Text size="sm">
            Opened <Text as="span" mono>{time(incident.opened)}</Text>, acknowledged{" "}
            <Text as="span" mono>{time(incident.acknowledged!)}</Text> by {assignee.name}. The p95
            latency is above its {service.latencySlo} ms objective since 09:40.
          </Text>
          <Text size="sm">
            <Link href="#/typography">Open the latency chart</Link> ·{" "}
            <Link href="https://status.example.org" external>
              Payment provider status
            </Link>
          </Text>
          <Text size="xs" tone="muted">
            <Text as="span" size="xs" mono>
              {incident.id}
            </Text>{" "}
            · still open
          </Text>
        </Stack>
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- Text only a screen reader should hear → VisuallyHidden
- A figure read against its limits, with unit and verdict → Stat
- A short status word in colour → Badge

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Reaches each `Link`; `Text` and `Heading` are not stops. |
| `Enter` | Follows the link; an `external` one opens in a new tab. |

#### API

##### `TextProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `as` | `ElementType` | `"p"` | Element to render as.<br>Shown in: [Tones and weights](#/typography/tones-and-weights), [Set an incident summary](#/typography/incident-summary), [Use the language in your own components (Language)](#/language/own-components) and 17 more |
| `size` | [`TextSize`](#type-TextSize)<br>`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` | Type size from the token set. It is independent of the element: a `p` may be small without becoming a different element.<br>Shown in: [Configurator](#/typography/configurator-typography), [Sizes](#/typography/sizes), [Tones and weights](#/typography/tones-and-weights) and 129 more |
| `weight` | [`TextWeight`](#type-TextWeight)<br>`"regular" \| "medium" \| "semibold"` | `"regular"` | Font weight from the token set.<br>Shown in: [Configurator](#/typography/configurator-typography), [Tones and weights](#/typography/tones-and-weights), [Tracking and leading](#/typography/tracking-and-leading) and 15 more |
| `tone` | [`TextTone`](#type-TextTone)<br>`"default" \| "secondary" \| "muted"` | `"default"` | How loud the text is. `secondary` and `muted` step back without falling below the contrast threshold.<br>Shown in: [Configurator](#/typography/configurator-typography), [Tones and weights](#/typography/tones-and-weights), [Tracking and leading](#/typography/tracking-and-leading) and 94 more |
| `mono` | `boolean` | `false` | Geist Mono with tabular figures – for numbers and identifiers.<br>Shown in: [Configurator](#/typography/configurator-typography), [Numbers and identifiers](#/typography/numbers), [Handle long values](#/typography/long-values) and 31 more |
| `tracking` | [`TextTracking`](#type-TextTracking)<br>`"normal" \| "tight" \| "display" \| "caps"` | `"normal"` | Letter spacing from the token set. `caps` belongs with letterspaced capitals.<br>Shown in: [Configurator](#/typography/configurator-typography), [Tracking and leading](#/typography/tracking-and-leading), [Set an incident summary](#/typography/incident-summary) |
| `leading` | [`TextLeading`](#type-TextLeading)<br>`"normal" \| "tight"` | `"normal"` | Line spacing. `tight` for multi-line headings and key figures, where the normal spacing lets the lines fall apart.<br>Shown in: [Configurator](#/typography/configurator-typography), [Tracking and leading](#/typography/tracking-and-leading) |
| `ref` | `Ref<HTMLElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of the rendered element.

##### `HeadingProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | The page's outline level (h1–h6).<br>Shown in: [Text, heading and link](#/typography/text-heading-link), [Tones and weights](#/typography/tones-and-weights), [Choose the level apart from the size](#/typography/level-and-size) and 6 more |
| `size` | [`TextSize`](#type-TextSize)<br>`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | the size matching the level | Optical size; independent of the level.<br>Shown in: [Tones and weights](#/typography/tones-and-weights), [Choose the level apart from the size](#/typography/level-and-size), [Set an incident summary](#/typography/incident-summary) and 4 more |
| `weight` | [`TextWeight`](#type-TextWeight)<br>`"regular" \| "medium" \| "semibold"` | `"semibold"` | Font weight from the token set.<br>Shown in: [Tones and weights](#/typography/tones-and-weights) |
| `tone` | [`TextTone`](#type-TextTone)<br>`"default" \| "secondary" \| "muted"` | `"default"` | How loud the heading is.<br>Shown in: [Choose the level apart from the size](#/typography/level-and-size) |
| `ref` | `Ref<HTMLHeadingElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of the heading.

##### `LinkProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `size` | [`TextSize`](#type-TextSize)<br>`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` | Size from the token set – a link has to match its body text.<br>Shown in: [Watch a kiln line over a shift (Scenarios)](#/scenarios/watch-a-kiln-line) |
| `external` | `boolean` | `false` | Opens in a new tab and sets the necessary protective attributes.<br>Shown in: [Link out of the application](#/typography/external-link), [Set an incident summary](#/typography/incident-summary) |
| `ref` | `Ref<HTMLAnchorElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<a>`.

##### Types on this page

###### `TextSize`

A type size of the token set.

```ts
type TextSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
```

###### `TextWeight`

A font weight of the token set.

```ts
type TextWeight = "regular" | "medium" | "semibold";
```

###### `TextTone`

How loud a text is; `secondary` and `muted` step back without falling below
the contrast threshold.

```ts
type TextTone = "default" | "secondary" | "muted";
```

###### `TextTracking`

The letter spacing of the token set.

```ts
type TextTracking = "normal" | "tight" | "display" | "caps";
```

###### `TextLeading`

The line height of the token set.

```ts
type TextLeading = "normal" | "tight";
```

#### Known limits

- No truncation and no line length: both depend on the column, which only the application knows.
- No prose styles for lists, quotes or rich text ([ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/)).
- `Link` renders a plain `a` and knows no router; pass it the address your router resolves.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### VisuallyHidden

Text a screen reader announces but the eye does not see (also called screen-reader-only or sr-only). Reach for it when a visible label is clear from its surroundings but not on its own, and for a skip link.

```ts
import { VisuallyHidden, announce } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/visuallyhidden/

#### Examples

##### Complete a label

The eye reads "Acknowledge" beside the incident; a screen reader hears which one.

```tsx
import { Button, VisuallyHidden } from "@umriss-ui/core";

export default function CompleteALabel() {
  return (
    <Button size="sm">
      Acknowledge
      <VisuallyHidden> incident INC-1048</VisuallyHidden>
    </Button>
  );
}
```

##### Add a skip link

Render it as a link with `focusable`: it is the first Tab stop on the page and shows itself only while it has focus.

```tsx
import { Stack, Text, VisuallyHidden } from "@umriss-ui/core";

export default function SkipLink() {
  return (
    <Stack gap={2} align="flex-start">
      <VisuallyHidden as="a" href="#shipments" focusable>
        Skip to the shipment list
      </VisuallyHidden>
      <Text size="sm" tone="secondary">
        Tab into this example: the link appears above this line.
      </Text>
    </Stack>
  );
}
```

##### Name the same action in every row

Twenty "Edit budget" buttons sound alike to a screen reader; append each row's name hidden and each says what it edits.

```tsx
import { Button, Stack, Text, VisuallyHidden } from "@umriss-ui/core";

/* Data from the controlling world, written out here so the example runs on its own. */
interface CostCentre {
  id: string;
  name: string;
  owner: string;
  /** The budget of one month. */
  monthlyBudget: number;
}

const COST_CENTRES: readonly CostCentre[] = [
  { id: "CC-1100", name: "Sales", owner: "Helen Marsh", monthlyBudget: 142_000 },
  { id: "CC-1200", name: "Marketing", owner: "Rafael Ortiz", monthlyBudget: 68_000 },
  { id: "CC-2100", name: "Engineering", owner: "Anika Sørensen", monthlyBudget: 188_000 },
  { id: "CC-2200", name: "Design", owner: "Paul Whitaker", monthlyBudget: 54_000 },
  { id: "CC-3100", name: "Customer service", owner: "Grace Obi", monthlyBudget: 61_000 },
  { id: "CC-4100", name: "Finance", owner: "Martina Vogel", monthlyBudget: 47_000 },
  { id: "CC-4200", name: "People", owner: "Daniel Frost", monthlyBudget: 39_000 },
  { id: "CC-4300", name: "IT", owner: "Kenji Arai", monthlyBudget: 83_000 },
  { id: "CC-4400", name: "Facilities", owner: "Olga Ivanova", monthlyBudget: 72_000 },
];

export default function ActionsInRows() {
  return (
    <Stack gap={2} style={{ maxWidth: 420 }}>
      {COST_CENTRES.slice(0, 4).map((centre) => (
        <Stack key={centre.id} direction="row" gap={3} align="center" justify="space-between">
          <Text size="sm">
            {centre.name} <Text as="span" size="xs" tone="muted">{centre.owner}</Text>
          </Text>
          <Button size="sm" variant="ghost">
            Edit budget
            <VisuallyHidden> of {centre.name}</VisuallyHidden>
          </Button>
        </Stack>
      ))}
    </Stack>
  );
}
```

#### When to use something else

- A hint every user should be able to see → Tooltip
- A button that shows only an icon → IconButton

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Reaches a `focusable` one and shows it while it has focus. |

#### API

##### `VisuallyHiddenProps<E extends ElementType = "span">`

| Prop | Type | Default | Description |
|---|---|---|---|
| `as` | `E` | `"span"` | Element to render as.<br>Shown in: [Add a skip link](#/visuallyhidden/skip-link) |
| `focusable` | `boolean` | `false` | Becomes visible as soon as the content receives the focus (skip link).<br>Shown in: [Add a skip link](#/visuallyhidden/skip-link) |
| `ref` | `Ref<HTMLElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of the chosen element – without `as`, `ref`.

#### Known limits

- It hides from the eye only; to hide something from everyone, do not render it.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

## Actions

What a user presses when something is to happen.

### Button

Starts one action when pressed: save, send, deploy, delete. Its variant says how much weight the action carries beside its neighbours, and while the action runs it shows that it is busy and cannot be pressed twice.

```ts
import { Button } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/button/

Use the primary variant once per surface, and danger only for what cannot be undone. `ghost` is quiet in the accent, `plain` quiet and neutral.

A loading button locks itself and tells assistive technology it is busy; it needs no `disabled` beside it. A button is `type="button"` unless you set another type, so it never sends a form by accident.

#### Examples

##### One action

A label that says what happens, and `onClick` for the action.

```tsx
import { useState } from "react";
import { Button } from "@umriss-ui/core";

export default function OneAction() {
  const [acknowledged, setAcknowledged] = useState(false);
  return (
    <Button disabled={acknowledged} onClick={() => setAcknowledged(true)}>
      {acknowledged ? "Acknowledged" : "Acknowledge"}
    </Button>
  );
}
```

##### Variants

Use `primary` once per surface – two main actions side by side are no longer a main action; `danger` only for what cannot be undone. `ghost` is quiet in the accent, `plain` quiet and neutral.

```tsx
import { Button, Stack } from "@umriss-ui/core";

export default function Variants() {
  return (
    <Stack direction="row" gap={3} wrap align="center">
      <Button variant="primary">Approve invoice</Button>
      <Button>Send back</Button>
      <Button variant="ghost">Add a note</Button>
      <Button variant="plain">Remind me later</Button>
      <Button variant="danger">Reject</Button>
    </Stack>
  );
}
```

##### Sizes

Use `sm` in header bars and table rows, the default `md` everywhere else.

```tsx
import { Button, Stack } from "@umriss-ui/core";

export default function Sizes() {
  return (
    <Stack direction="row" gap={3} wrap align="center">
      <Button variant="primary">Plan tour</Button>
      <Button>Print labels</Button>
      <Button size="sm" variant="primary">
        Plan tour
      </Button>
      <Button size="sm">Print labels</Button>
    </Stack>
  );
}
```

##### Loading and disabled

Set `loading` while the action runs – it locks the button by itself; `disabled` says the action is not possible here at all.

```tsx
import { useState } from "react";
import { Button, Stack } from "@umriss-ui/core";

export default function LoadingAndDisabled() {
  const [running, setRunning] = useState(false);

  const deploy = () => {
    setRunning(true);
    window.setTimeout(() => setRunning(false), 1200);
  };

  return (
    <Stack direction="row" gap={3} wrap align="center">
      <Button variant="primary" loading={running} onClick={deploy}>
        Deploy
      </Button>
      <Button loading>Rolling back</Button>
      <Button disabled>Promote to production</Button>
      <Button variant="primary" disabled>
        Deploy
      </Button>
    </Stack>
  );
}
```

##### Submit a form

A button is `type="button"` unless you say otherwise; set `type="submit"` on the one that sends the form, so Enter in a field sends it too.

```tsx
import { useState } from "react";
import type { FormEvent } from "react";
import { Button, FormField, Input, Stack } from "@umriss-ui/core";

export default function SubmitAForm() {
  const [name, setName] = useState("");
  const [saving, setSaving] = useState(false);

  const submit = (event: FormEvent) => {
    event.preventDefault();
    setSaving(true);
    window.setTimeout(() => setSaving(false), 1200);
  };

  return (
    <form onSubmit={submit}>
      <Stack direction="row" gap={3} align="flex-end" wrap>
        <FormField label="Project name">
          <Input value={name} onChange={(event) => setName(event.target.value)} />
        </FormField>
        <Button type="submit" variant="primary" loading={saving} disabled={name.trim() === ""}>
          Create project
        </Button>
      </Stack>
    </form>
  );
}
```

##### Add an icon

Put the icon before the label and hide it from screen readers; the button sets its size. A button with no label at all is an `IconButton`.

```tsx
import { Button, Stack } from "@umriss-ui/core";

function Download() {
  return (
    <svg viewBox="0 0 16 16" aria-hidden="true">
      <path d="M8 2v8m0 0 3-3m-3 3L5 7M3 13h10" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
    </svg>
  );
}

export default function WithAnIcon() {
  return (
    <Stack direction="row" gap={3} wrap align="center">
      <Button>
        <Download />
        Export CSV
      </Button>
      <Button size="sm" variant="ghost">
        <Download />
        Export CSV
      </Button>
    </Stack>
  );
}
```

##### Build an approval bar

One primary action, the alternatives quieter beside it, the destructive one set apart, and every button busy while its request runs.

```tsx
import { useState } from "react";
import { Button, Card, CardBody, CardHeader, Stack, Text } from "@umriss-ui/core";

/* Data from the controlling world, written out here so the example runs on its own. */
const on = (month: number, day: number) => new Date(2026, month - 1, day).getTime();

interface Approval {
  invoice: string;
  step: "cost centre" | "finance";
  approver: string;
  decision: "approved" | "rejected" | "pending";
  at?: number;
  comment?: string;
}

/** Two signatures an invoice needs: its cost centre's owner, then finance. */
const APPROVALS: readonly Approval[] = [
  { invoice: "INV-26-0318", step: "cost centre", approver: "Olga Ivanova", decision: "pending" },
  { invoice: "INV-26-0317", step: "cost centre", approver: "Rafael Ortiz", decision: "approved", at: on(3, 16) },
  { invoice: "INV-26-0317", step: "finance", approver: "Martina Vogel", decision: "pending" },
  { invoice: "INV-26-0309", step: "cost centre", approver: "Kenji Arai", decision: "approved", at: on(3, 10) },
  { invoice: "INV-26-0309", step: "finance", approver: "Martina Vogel", decision: "approved", at: on(3, 11) },
  { invoice: "INV-26-0302", step: "cost centre", approver: "Martina Vogel", decision: "approved", at: on(3, 3) },
  { invoice: "INV-26-0302", step: "finance", approver: "Martina Vogel", decision: "approved", at: on(3, 3) },
  { invoice: "INV-26-0226", step: "cost centre", approver: "Helen Marsh", decision: "approved", at: on(2, 27) },
  { invoice: "INV-26-0226", step: "finance", approver: "Martina Vogel", decision: "approved", at: on(3, 2) },
  { invoice: "INV-26-0221", step: "cost centre", approver: "Anika Sørensen", decision: "rejected", at: on(2, 24), comment: "Not ordered - the review was cancelled in January." },
];

type Decision = "approve" | "return" | "reject";

const DONE: Record<Decision, string> = {
  approve: "Approved - passed on to finance.",
  return: "Sent back to the requester.",
  reject: "Rejected.",
};

export default function ApprovalBar() {
  const approval = APPROVALS[0]!;
  const [running, setRunning] = useState<Decision | null>(null);
  const [decided, setDecided] = useState<Decision | null>(null);

  const decide = (decision: Decision) => {
    setRunning(decision);
    window.setTimeout(() => {
      setRunning(null);
      setDecided(decision);
    }, 1000);
  };

  const busy = running !== null || decided !== null;

  return (
    <Card>
      <CardHeader eyebrow="Approval" title={`Invoice ${approval.invoice}`} />
      <CardBody>
        <Stack gap={4}>
          <Text size="sm" tone="secondary">
            {decided === null ? `Waiting for ${approval.approver}, ${approval.step} step` : DONE[decided]}
          </Text>
          <Stack direction="row" gap={3} wrap align="center">
            <Button variant="primary" loading={running === "approve"} disabled={busy} onClick={() => decide("approve")}>
              Approve
            </Button>
            <Button loading={running === "return"} disabled={busy} onClick={() => decide("return")}>
              Send back
            </Button>
            <span style={{ flex: 1 }} />
            <Button variant="danger" loading={running === "reject"} disabled={busy} onClick={() => decide("reject")}>
              Reject
            </Button>
          </Stack>
        </Stack>
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- A button that shows only an icon → IconButton
- Several buttons that act on the same thing → ButtonGroup
- One main action with rarer variants → ButtonGroup
- Going to another page rather than doing something → Typography
- A setting that is on or off → Switch

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Reaches the button; a `disabled` or `loading` one is not a stop. |
| `Enter / Space` | Presses it. |

#### Accessibility

A native `button`, named by its label. While `loading` it is disabled and `aria-busy`, and the spinner inside it is a `status` named "Loading"; the label stays, so the name does not change.

Under forced colours every variant keeps an outline where its edge would lie, and the primary one's is twice as wide, so it still stands out among its neighbours. With reduced motion a pressed button does not give way; only its colour changes.

#### API

##### `ButtonProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `variant` | [`ButtonVariant`](#type-ButtonVariant)<br>`"primary" \| "secondary" \| "ghost" \| "plain" \| "danger"` | `"secondary"` | How loud the button is. `primary` exactly once per surface - two main actions side by side are no longer a main action. `ghost` is quiet in the accent, `plain` quiet and neutral.<br>Shown in: [Configurator](#/button/configurator-button), [Variants](#/button/variants), [Sizes](#/button/sizes) and 52 more |
| `size` | [`ButtonSize`](#type-ButtonSize)<br>`"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for buttons in header bars and table rows, `md` otherwise.<br>Shown in: [Configurator](#/button/configurator-button), [Sizes](#/button/sizes), [Add an icon](#/button/with-an-icon) and 57 more |
| `loading` | `boolean` | `false` | Shows a loading indicator and locks the button.<br>Shown in: [Configurator](#/button/configurator-button), [Loading and disabled](#/button/loading-and-disabled), [Submit a form](#/button/submit-a-form) and 4 more |
| `ref` | `Ref<HTMLButtonElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<button>`.

##### Types on this page

###### `ButtonVariant`

How loud a button is: `primary` for the one main action, `secondary` by
default, `ghost` quiet in the accent, `plain` quiet and neutral, `danger`
for a destructive action.

```ts
type ButtonVariant = "primary" | "secondary" | "ghost" | "plain" | "danger";
```

###### `ButtonSize`

A button's two heights - the controls' (`ControlSize`).

```ts
type ButtonSize = ControlSize;
```

Resolves to `"sm" | "md"`.

###### `ControlSize`

The two heights of a control: `sm` for a toolbar and dense forms, `md`
otherwise.

```ts
type ControlSize = "sm" | "md";
```

#### Known limits

- The label stays on one line; keep it short rather than let it wrap.
- No icon slot: an icon goes among the children, before the label, and the button sets its size.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### IconButton

A square button that shows only an icon (also called an icon-only button): refresh, export, close, the actions of a row. Reach for it where the icon is known well enough to stand alone; its name is required and shows as a tooltip.

```ts
import { IconButton } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/iconbutton/

Its `aria-label` is required, and it is the accessible name and the tooltip in one: a screen reader hears it once, and the eye reads it on hover or keyboard focus.

The icon is yours: an SVG, a glyph of the set, or an icon font's element. The button sets its size – 14 px, 12 px at `sm` – the size an SVG takes beside a label in a `Button` as well.

It is a `Button` underneath, with the same sizes, loading state and variants; the default is `plain`, quiet and neutral. As the trigger of a `Menu` it anchors the panel, and its tooltip gives way while the menu is open.

#### Examples

##### Name the icon

`aria-label` is required: it is the name a screen reader announces and the tooltip a sighted reader sees on hover or keyboard focus.

```tsx
import { IconButton } from "@umriss-ui/core";

function Refresh() {
  return (
    <svg viewBox="0 0 10 10" aria-hidden="true">
      <path d="M8.3 5.8A3.4 3.4 0 1 1 7.6 2.7M7.9 1.2v1.8H6.1" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
    </svg>
  );
}

export default function NameTheIcon() {
  return (
    <IconButton aria-label="Refresh the tours">
      <Refresh />
    </IconButton>
  );
}
```

##### Variants

`plain` is the default – quiet and neutral, for a bar or a row. `ghost` is quiet in the accent; the others mean what they mean on a `Button`.

```tsx
import { CrossGlyph, IconButton, PlusGlyph, Stack } from "@umriss-ui/core";

function Export() {
  return (
    <svg viewBox="0 0 10 10" aria-hidden="true">
      <path d="M5 1.5v5M2.8 4.3 5 6.5l2.2-2.2M1.8 8.5h6.4" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
    </svg>
  );
}

function Check() {
  return (
    <svg viewBox="0 0 10 10" aria-hidden="true">
      <path d="M1.8 5.3 4 7.5l4.2-5" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
    </svg>
  );
}

export default function Variants() {
  return (
    <Stack direction="row" gap={3} wrap align="center">
      <IconButton aria-label="Export the tour list">
        <Export />
      </IconButton>
      <IconButton variant="ghost" aria-label="Add a stop">
        <PlusGlyph />
      </IconButton>
      <IconButton variant="secondary" aria-label="Export the tour list">
        <Export />
      </IconButton>
      <IconButton variant="primary" aria-label="Release the tour">
        <Check />
      </IconButton>
      <IconButton variant="danger" aria-label="Cancel the tour">
        <CrossGlyph />
      </IconButton>
    </Stack>
  );
}
```

##### Sizes

The heights of `Button`, and the same icon size beside a label and alone: 14 px at `md`, 12 px at `sm`, in header bars and table rows.

```tsx
import { Button, IconButton, Stack } from "@umriss-ui/core";

function Export() {
  return (
    <svg viewBox="0 0 10 10" aria-hidden="true">
      <path d="M5 1.5v5M2.8 4.3 5 6.5l2.2-2.2M1.8 8.5h6.4" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
    </svg>
  );
}

export default function Sizes() {
  return (
    <Stack gap={3}>
      <Stack direction="row" gap={2} align="center">
        <Button>
          <Export />
          Export
        </Button>
        <IconButton variant="secondary" aria-label="Export the tour list">
          <Export />
        </IconButton>
      </Stack>
      <Stack direction="row" gap={2} align="center">
        <Button size="sm">
          <Export />
          Export
        </Button>
        <IconButton size="sm" variant="secondary" aria-label="Export the tour list">
          <Export />
        </IconButton>
      </Stack>
    </Stack>
  );
}
```

##### Bring your own icons

A glyph of the set, an SVG drawn for 24 px as lucide and Font Awesome ship theirs, a character the way an icon font sets it – the button gives each the same size.

```tsx
import { CrossGlyph, IconButton, Stack } from "@umriss-ui/core";

/* Drawn on a 24 grid with its own width and height, as icon sets ship them. */
function Printer() {
  return (
    <svg viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
      <path d="M6 9V2h12v7" />
      <path d="M6 18H4a2 2 0 0 1-2-2v-5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2h-2" />
      <path d="M6 14h12v8H6z" />
    </svg>
  );
}

export default function BringYourOwnIcons() {
  return (
    <Stack direction="row" gap={3} align="center">
      <IconButton variant="secondary" aria-label="Remove the filter">
        <CrossGlyph />
      </IconButton>
      <IconButton variant="secondary" aria-label="Print the delivery notes">
        <Printer />
      </IconButton>
      <IconButton variant="secondary" aria-label="Sort by departure">
        <span aria-hidden="true">⇅</span>
      </IconButton>
    </Stack>
  );
}
```

##### Loading and disabled

While its action runs, the spinner takes the icon's place and the button locks; disabled, it fades and keeps its name.

```tsx
import { useEffect, useState } from "react";
import { IconButton, Stack, Text } from "@umriss-ui/core";

function Refresh() {
  return (
    <svg viewBox="0 0 10 10" aria-hidden="true">
      <path d="M8.3 5.8A3.4 3.4 0 1 1 7.6 2.7M7.9 1.2v1.8H6.1" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
    </svg>
  );
}

function Export() {
  return (
    <svg viewBox="0 0 10 10" aria-hidden="true">
      <path d="M5 1.5v5M2.8 4.3 5 6.5l2.2-2.2M1.8 8.5h6.4" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
    </svg>
  );
}

export default function LoadingAndDisabled() {
  const [loading, setLoading] = useState(false);
  const [refreshed, setRefreshed] = useState("10:30");

  useEffect(() => {
    if (!loading) return;
    const timer = setTimeout(() => {
      setLoading(false);
      setRefreshed("10:31");
    }, 1500);
    return () => clearTimeout(timer);
  }, [loading]);

  return (
    <Stack direction="row" gap={2} align="center">
      <IconButton variant="secondary" aria-label="Refresh the tours" loading={loading} onClick={() => setLoading(true)}>
        <Refresh />
      </IconButton>
      <IconButton variant="secondary" aria-label="Export the tour list" disabled>
        <Export />
      </IconButton>
      <Text size="sm" tone="muted">
        Refreshed at {refreshed}
      </Text>
    </Stack>
  );
}
```

##### Build a toolbar

Plain buttons for the bar, a group for the pair that belongs together, a menu for the rest – every square the same size, every name a tooltip.

```tsx
import { useState } from "react";
import { ButtonGroup, IconButton, Menu, MenuItem, MenuSeparator, MinusGlyph, PlusGlyph, Stack, Text } from "@umriss-ui/core";

const ZOOM = [50, 75, 100, 150, 200];

function Refresh() {
  return (
    <svg viewBox="0 0 10 10" aria-hidden="true">
      <path d="M8.3 5.8A3.4 3.4 0 1 1 7.6 2.7M7.9 1.2v1.8H6.1" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
    </svg>
  );
}

function Export() {
  return (
    <svg viewBox="0 0 10 10" aria-hidden="true">
      <path d="M5 1.5v5M2.8 4.3 5 6.5l2.2-2.2M1.8 8.5h6.4" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
    </svg>
  );
}

export default function Toolbar() {
  const [zoom, setZoom] = useState(2);

  return (
    <Stack direction="row" gap={3} align="center" justify="space-between" wrap style={{ maxWidth: 620 }}>
      <Text size="sm" weight="semibold">
        Tours, Tuesday 17 March
      </Text>
      <Stack direction="row" gap={2} align="center">
        <ButtonGroup aria-label="Zoom the tour plan">
          <IconButton size="sm" variant="secondary" aria-label="Zoom out" disabled={zoom === 0} onClick={() => setZoom(zoom - 1)}>
            <MinusGlyph />
          </IconButton>
          <IconButton size="sm" variant="secondary" aria-label="Zoom in" disabled={zoom === ZOOM.length - 1} onClick={() => setZoom(zoom + 1)}>
            <PlusGlyph />
          </IconButton>
        </ButtonGroup>
        <Text as="span" size="xs" mono tone="muted" style={{ width: "4ch" }}>
          {ZOOM[zoom]}%
        </Text>
        <IconButton size="sm" aria-label="Refresh the tours">
          <Refresh />
        </IconButton>
        <IconButton size="sm" aria-label="Export the tour list">
          <Export />
        </IconButton>
        <Menu
          align="end"
          trigger={
            <IconButton size="sm" aria-label="More actions for the tours">
              ⋯
            </IconButton>
          }
        >
          <MenuItem>Print the delivery notes</MenuItem>
          <MenuItem>Copy the link</MenuItem>
          <MenuSeparator />
          <MenuItem tone="danger">Cancel every open tour</MenuItem>
        </Menu>
      </Stack>
    </Stack>
  );
}
```

#### When to use something else

- The action is clearer said than drawn → Button
- Icon buttons that act on the same thing → ButtonGroup

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Reaches the button and shows its name. |
| `Enter / Space` | Presses it. |
| `Escape` | Hides the name. |

#### API

##### `IconButtonProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` *required* | `ReactNode` | — | The icon: an SVG, a glyph of the set or an icon font's element. The button sets its size - `--u-icon-size`, `--u-icon-size-sm` at `sm`.<br>Shown in: [Configurator](#/iconbutton/configurator-iconbutton), [Name the icon](#/iconbutton/name-the-icon), [Variants](#/iconbutton/variants) and 5 more |
| `variant` | [`ButtonVariant`](#type-ButtonVariant)<br>`"primary" \| "secondary" \| "ghost" \| "plain" \| "danger"` | `"plain"` | How loud the button is; `plain` is quiet and neutral, and the rest mean what they mean on a `Button`.<br>Shown in: [Configurator](#/iconbutton/configurator-iconbutton), [Variants](#/iconbutton/variants), [Sizes](#/iconbutton/sizes) and 3 more |
| `size` | [`ButtonSize`](#type-ButtonSize)<br>`"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for buttons in header bars and table rows, `md` otherwise. From `ButtonProps`.<br>Shown in: [Configurator](#/iconbutton/configurator-iconbutton), [Sizes](#/iconbutton/sizes), [Build a toolbar](#/iconbutton/a-toolbar) and 57 more |
| `loading` | `boolean` | `false` | Shows a loading indicator and locks the button. From `ButtonProps`.<br>Shown in: [Configurator](#/iconbutton/configurator-iconbutton), [Loading and disabled](#/iconbutton/loading-and-disabled), [Configurator (Button)](#/button/configurator-button) and 4 more |
| `ref` | `Ref<HTMLButtonElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Accessibility

| Prop | Type | Default | Description |
|---|---|---|---|
| `aria-label` *required* | `string` | — | The name: what a screen reader announces and the tooltip shows. Required - an icon alone names nothing.<br>Shown in: [Configurator](#/iconbutton/configurator-iconbutton), [Name the icon](#/iconbutton/name-the-icon), [Variants](#/iconbutton/variants) and 5 more |

Also takes every attribute of `<button>`.

##### Types on this page

###### `ButtonVariant`

How loud a button is: `primary` for the one main action, `secondary` by
default, `ghost` quiet in the accent, `plain` quiet and neutral, `danger`
for a destructive action.

```ts
type ButtonVariant = "primary" | "secondary" | "ghost" | "plain" | "danger";
```

###### `ButtonSize`

A button's two heights - the controls' (`ControlSize`).

```ts
type ButtonSize = ControlSize;
```

Resolves to `"sm" | "md"`.

###### `ControlSize`

The two heights of a control: `sm` for a toolbar and dense forms, `md`
otherwise.

```ts
type ControlSize = "sm" | "md";
```

#### Known limits

- The tooltip always shows the name; a hint that says more than the name is a `Tooltip` around a `Button`.
- A touch screen shows no tooltip: choose icons whose meaning is common, or a `Button` with a label.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### ButtonGroup

Joins buttons that act on the same thing into one control. Its companion SplitButton runs one main action and keeps the rarer variants in a menu beside it (also called a dropdown or menu button).

```ts
import { ButtonGroup, SplitButton } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/buttongroup/

Name every group with an `aria-label`; a screen reader otherwise announces only "group". Each button in it stays its own Tab stop.

A group holds no selection: it does not remember which button was pressed.

#### Examples

##### A group

Buttons that act on the same thing, joined; `aria-label` names the group, which a screen reader otherwise calls just "group".

```tsx
import { Button, ButtonGroup } from "@umriss-ui/core";

export default function Group() {
  return (
    <ButtonGroup aria-label="Browse incidents">
      <Button>Previous incident</Button>
      <Button>Next incident</Button>
    </ButtonGroup>
  );
}
```

##### Variants and sizes

Give every button in a group the same `variant` and `size`; a group that mixes them no longer reads as one control. `size` on the group says it once for all of them.

```tsx
import { Button, ButtonGroup, Stack } from "@umriss-ui/core";

export default function VariantsAndSizes() {
  return (
    <Stack gap={3} align="flex-start">
      <ButtonGroup aria-label="Zoom the tour plan">
        <Button>Zoom out</Button>
        <Button>Zoom in</Button>
        <Button>Fit</Button>
      </ButtonGroup>
      <ButtonGroup aria-label="Tour T-03">
        <Button variant="primary">Dispatch</Button>
        <Button variant="primary">Print manifest</Button>
      </ButtonGroup>
      <ButtonGroup aria-label="Stops" size="sm">
        <Button variant="ghost">Move up</Button>
        <Button variant="ghost">Move down</Button>
        <Button variant="ghost">Remove</Button>
      </ButtonGroup>
    </Stack>
  );
}
```

##### Offer variants of the main action

A `SplitButton` runs its main action on a click and keeps the rarer variants in its `menu`, found but not hit by accident. This one stands at the start of its bar, so `align="start"` opens the menu along the bar rather than out over its edge.

```tsx
import { useState } from "react";
import { MenuItem, MenuSeparator, SplitButton, Stack, Text } from "@umriss-ui/core";

export default function SplitButtonExample() {
  const [last, setLast] = useState("nothing yet");

  return (
    <Stack gap={3} align="flex-start">
      <SplitButton
        variant="primary"
        align="start"
        onClick={() => setLast("labels for tour T-03")}
        menu={
          <>
            <MenuItem onSelect={() => setLast("the loading manifest")}>Print the loading manifest</MenuItem>
            <MenuItem onSelect={() => setLast("the delivery notes")}>Print delivery notes</MenuItem>
            <MenuSeparator />
            <MenuItem tone="danger" onSelect={() => setLast("nothing - print jobs cancelled")}>
              Cancel all print jobs
            </MenuItem>
          </>
        }
      >
        Print labels
      </SplitButton>
      <Text size="xs" tone="muted">
        Printed: {last}
      </Text>
    </Stack>
  );
}
```

##### Disable while nothing is selected

Set `disabled` on the split button and both halves lock: the main action and its menu wait for a selection.

```tsx
import { useState } from "react";
import { Checkbox, MenuItem, SplitButton, Stack } from "@umriss-ui/core";

const SHIPMENTS = [
  { id: "SH-1042", customer: "Holloway Garden Supplies" },
  { id: "SH-1043", customer: "Marlow & Finch Books" },
  { id: "SH-1044", customer: "Oakridge Pharmacy" },
];

export default function DisabledUntilSelected() {
  const [selected, setSelected] = useState<readonly string[]>([]);
  const toggle = (id: string) =>
    setSelected((now) => (now.includes(id) ? now.filter((one) => one !== id) : [...now, id]));

  return (
    <Stack gap={3} align="flex-start">
      {SHIPMENTS.map((shipment) => (
        <Checkbox
          key={shipment.id}
          label={`${shipment.id} · ${shipment.customer}`}
          checked={selected.includes(shipment.id)}
          onChange={() => toggle(shipment.id)}
        />
      ))}
      <SplitButton
        size="sm"
        disabled={selected.length === 0}
        onClick={() => setSelected([])}
        menu={
          <>
            <MenuItem onSelect={() => setSelected([])}>Reschedule for tomorrow</MenuItem>
            <MenuItem onSelect={() => setSelected([])}>Return to sender</MenuItem>
          </>
        }
      >
        {selected.length === 0 ? "Rebook" : `Rebook ${selected.length}`}
      </SplitButton>
    </Stack>
  );
}
```

##### Build an invoice toolbar

A group to page through the queue and a split button for the decision, as an approver's toolbar puts them.

```tsx
import { useState } from "react";
import { Button, ButtonGroup, MenuItem, MenuSeparator, SplitButton, Stack, Text } from "@umriss-ui/core";

/* Data from the controlling world, written out here so the example runs on its own. */
const on = (month: number, day: number) => new Date(2026, month - 1, day).getTime();

interface InvoiceLine {
  description: string;
  quantity: number;
  unitPrice: number;
  /** A fraction: 0.1 is ten per cent off. */
  discount: number;
  /** A fraction: 0.19 or 0.07, or 0 where no VAT is charged. */
  vatRate: number;
}

interface Invoice {
  id: string;
  supplier: string;
  costCentre: string;
  received: number;
  due: number;
  status: "awaiting approval" | "approved" | "paid" | "rejected";
  lines: readonly InvoiceLine[];
}

const INVOICES: readonly Invoice[] = [
  {
    id: "INV-26-0318", supplier: "Brandlow Office Supply", costCentre: "CC-4400", received: on(3, 16), due: on(4, 15), status: "awaiting approval",
    lines: [
      { description: "Desk lamps, LED", quantity: 24, unitPrice: 48.9, discount: 0.1, vatRate: 0.19 },
      { description: "Printer paper, box of 5 reams", quantity: 40, unitPrice: 21.5, discount: 0, vatRate: 0.19 },
      { description: "Delivery", quantity: 1, unitPrice: 35, discount: 0, vatRate: 0.19 },
    ],
  },
  {
    id: "INV-26-0317", supplier: "Kettering & Shaw Events", costCentre: "CC-1200", received: on(3, 13), due: on(4, 12), status: "awaiting approval",
    lines: [
      { description: "Trade fair stand, 3 days", quantity: 1, unitPrice: 12_400, discount: 0.05, vatRate: 0.19 },
      { description: "Catering, per guest", quantity: 180, unitPrice: 18.5, discount: 0, vatRate: 0.07 },
    ],
  },
  {
    id: "INV-26-0309", supplier: "Nimbrel Software", costCentre: "CC-4300", received: on(3, 9), due: on(4, 8), status: "approved",
    lines: [
      { description: "Design tool licences, annual", quantity: 12, unitPrice: 540, discount: 0.15, vatRate: 0.19 },
      { description: "Onboarding session", quantity: 2, unitPrice: 890, discount: 0, vatRate: 0.19 },
    ],
  },
  {
    id: "INV-26-0302", supplier: "Fenwright Legal", costCentre: "CC-4100", received: on(3, 2), due: on(3, 16), status: "paid",
    lines: [{ description: "Contract review, hours", quantity: 14.5, unitPrice: 260, discount: 0, vatRate: 0.19 }],
  },
  {
    id: "INV-26-0226", supplier: "Corrin Travel", costCentre: "CC-1100", received: on(2, 26), due: on(3, 12), status: "paid",
    lines: [
      { description: "Rail tickets, sales conference", quantity: 22, unitPrice: 139, discount: 0, vatRate: 0.07 },
      { description: "Hotel, nights", quantity: 44, unitPrice: 112, discount: 0.08, vatRate: 0.07 },
    ],
  },
  {
    id: "INV-26-0221", supplier: "Stellbrook Consulting", costCentre: "CC-2100", received: on(2, 21), due: on(3, 23), status: "rejected",
    lines: [{ description: "Architecture review, days", quantity: 6, unitPrice: 1450, discount: 0, vatRate: 0 }],
  },
];

const QUEUE = INVOICES.filter((invoice) => invoice.status === "awaiting approval");

export default function InvoiceToolbar() {
  const [index, setIndex] = useState(0);
  const [note, setNote] = useState("");
  const invoice = QUEUE[index]!;
  const decide = (what: string) => setNote(`${invoice.id}: ${what}`);

  return (
    <Stack gap={3}>
      <Stack direction="row" gap={3} align="center" justify="space-between" wrap>
        <Stack direction="row" gap={3} align="center" wrap>
          <ButtonGroup aria-label="Invoices awaiting approval">
            <Button size="sm" disabled={index === 0} onClick={() => setIndex(index - 1)}>
              Previous
            </Button>
            <Button size="sm" disabled={index === QUEUE.length - 1} onClick={() => setIndex(index + 1)}>
              Next
            </Button>
          </ButtonGroup>
          <Text size="sm">
            <Text as="span" size="sm" mono>
              {invoice.id}
            </Text>{" "}
            · {invoice.supplier} · {index + 1} of {QUEUE.length}
          </Text>
        </Stack>
        <SplitButton
          size="sm"
          variant="primary"
          onClick={() => decide("approved")}
          menu={
            <>
              <MenuItem onSelect={() => decide("approved with a comment")}>Approve with a comment</MenuItem>
              <MenuItem onSelect={() => decide("sent back to the requester")}>Send back</MenuItem>
              <MenuSeparator />
              <MenuItem tone="danger" onSelect={() => decide("rejected")}>
                Reject
              </MenuItem>
            </>
          }
        >
          Approve
        </SplitButton>
      </Stack>
      <Text size="xs" tone="muted">
        {note === "" ? "No decision yet" : note}
      </Text>
    </Stack>
  );
}
```

#### When to use something else

- One option out of a few that stays chosen → RadioGroup
- Several views of one place → Tabs
- Many actions and none of them the main one → Menu

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Moves to the next button; on a split button, from the main action to the menu trigger. |
| `Enter / Space` | Presses the focused button; on the trigger, opens the menu and focuses its first entry. |
| `↓ / ↑` | Moves through the open menu's entries. |
| `Home / End` | Jumps to the first or last entry. |
| `Escape` | Closes the menu and returns focus to the trigger. |

#### API

##### `ButtonGroupProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `size` | [`ButtonSize`](#type-ButtonSize)<br>`"sm" \| "md"` | the size around it, else `"md"` | The size of the buttons in it that do not say their own - one group, one height.<br>Shown in: [Variants and sizes](#/buttongroup/variants-and-sizes) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Accessibility

| Prop | Type | Default | Description |
|---|---|---|---|
| `aria-label` | `string` | — | Label of the group for the screen reader.<br>Shown in: [A group](#/buttongroup/group), [Variants and sizes](#/buttongroup/variants-and-sizes), [Build an invoice toolbar](#/buttongroup/invoice-toolbar) and 2 more |

Also takes every attribute of `<div>`.

##### `SplitButtonProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` *required* | `ReactNode` | — | Label of the main action.<br>Shown in: [Offer variants of the main action](#/buttongroup/split-button), [Disable while nothing is selected](#/buttongroup/disabled-until-selected), [Build an invoice toolbar](#/buttongroup/invoice-toolbar) |
| `menu` *required* | `ReactNode` | — | Entries of the menu - typically `MenuItem`.<br>Shown in: [Offer variants of the main action](#/buttongroup/split-button), [Disable while nothing is selected](#/buttongroup/disabled-until-selected), [Build an invoice toolbar](#/buttongroup/invoice-toolbar) |
| `variant` | [`ButtonVariant`](#type-ButtonVariant)<br>`"primary" \| "secondary" \| "ghost" \| "plain" \| "danger"` | `"secondary"` | How loud the main action is; the trigger beside it follows suit.<br>Shown in: [Offer variants of the main action](#/buttongroup/split-button), [Build an invoice toolbar](#/buttongroup/invoice-toolbar) |
| `size` | [`ButtonSize`](#type-ButtonSize)<br>`"sm" \| "md"` | the size around it, else `"md"` | `sm` for buttons in header bars and table rows, `md` otherwise.<br>Shown in: [Disable while nothing is selected](#/buttongroup/disabled-until-selected), [Build an invoice toolbar](#/buttongroup/invoice-toolbar) |
| `menuLabel` | `string` | the wording's "More actions" | Label of the trigger. |
| `align` | `"start" \| "end"` | `"end"` | Alignment of the menu relative to the trigger.<br>Shown in: [Offer variants of the main action](#/buttongroup/split-button) |
| `loading` | `boolean` | `false` | Shows a loading indicator and locks the button. From `ButtonProps`.<br>Shown in: [Configurator (Button)](#/button/configurator-button), [Loading and disabled (Button)](#/button/loading-and-disabled), [Submit a form (Button)](#/button/submit-a-form) and 4 more |
| `ref` | `Ref<HTMLButtonElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onClick` | [`ButtonProps`](#/button/type-ButtonProps)`["onClick"]` | — | The main action.<br>Shown in: [Offer variants of the main action](#/buttongroup/split-button), [Disable while nothing is selected](#/buttongroup/disabled-until-selected), [Build an invoice toolbar](#/buttongroup/invoice-toolbar) |

Also takes every attribute of `<button>`.

##### Types on this page

###### `ButtonSize`

A button's two heights - the controls' (`ControlSize`).

```ts
type ButtonSize = ControlSize;
```

Resolves to `"sm" | "md"`.

###### `ButtonVariant`

How loud a button is: `primary` for the one main action, `secondary` by
default, `ghost` quiet in the accent, `plain` quiet and neutral, `danger`
for a destructive action.

```ts
type ButtonVariant = "primary" | "secondary" | "ghost" | "plain" | "danger";
```

###### `ControlSize`

The two heights of a control: `sm` for a toolbar and dense forms, `md`
otherwise.

```ts
type ControlSize = "sm" | "md";
```

#### Known limits

- No toggle or segmented state; a choice that stays is a radio group.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

## Forms

Where a user types a value or sets one directly on the screen.

### Input

A single line of text (text field, text box): names, references, addresses, search terms. Reach for it whenever the answer is short free text; for numbers take a [NumberInput](#/numberinput).

```ts
import { Input } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/input/

Put it in a [FormField](#/formfield): the field brings the label, the hint, the error and the wiring a screen reader needs. Every attribute of the native input passes through.

It fills its place, or takes the width of its value with `chars` - a postcode `chars={5}`; in a row it is sixteen characters wide whatever it holds. How wide and how tall every field is stands on [Sizes](#/sizes).

#### Examples

##### Text field

Wrap the field in a `FormField` for its label; the field takes every attribute of the native input.

```tsx
import { FormField, Input } from "@umriss-ui/core";

export default function TextField() {
  return (
    <FormField label="Consignee" style={{ maxWidth: 360 }}>
      <Input placeholder="Company or person" autoComplete="organization" />
    </FormField>
  );
}
```

##### Sizes

Use `size="sm"` in dense forms and table rows, where the field stands beside small buttons.

```tsx
import { FormField, Grid, Input } from "@umriss-ui/core";

export default function Sizes() {
  return (
    <Grid minItemWidth="220px" gap={4}>
      <FormField label="Tour" hint="Medium, the default.">
        <Input defaultValue="T-01 North" />
      </FormField>
      <FormField label="Tour" hint="Small.">
        <Input size="sm" defaultValue="T-01 North" />
      </FormField>
    </Grid>
  );
}
```

##### States

An `error` on the `FormField` marks the field invalid; `disabled` and `readOnly` behave as on the native input.

```tsx
import { FormField, Grid, Input } from "@umriss-ui/core";

export default function States() {
  return (
    <Grid minItemWidth="240px" gap={4}>
      <FormField label="Street" required>
        <Input placeholder="Street and number" autoComplete="street-address" />
      </FormField>
      <FormField label="Postcode" error="A postcode here has five digits.">
        <Input defaultValue="2041" />
      </FormField>
      <FormField label="Depot" hint="Set by the tour, not editable.">
        <Input value="North depot" readOnly />
      </FormField>
      <FormField label="Vehicle" hint="Disabled until a tour is chosen.">
        <Input disabled placeholder="FP 000 X" />
      </FormField>
      <FormField label="Delivery instructions" hint="A long value scrolls inside the field.">
        <Input defaultValue="Holloway Garden Supplies, goods entrance at the rear, ring twice, ask for the warehouse lead on duty" />
      </FormField>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the field invalid by itself. Without one, set `invalid` and tie your message to the field with `aria-describedby`. Five digits clear it.

```tsx
import { useId, useState } from "react";
import { Input, Stack, Text } from "@umriss-ui/core";

export default function WithAnError() {
  const [postcode, setPostcode] = useState("2041");
  const messageId = useId();
  const error = /^\d{5}$/.test(postcode) ? undefined : "A postcode here has five digits.";

  return (
    <Stack gap={1} style={{ maxWidth: 360 }}>
      <Input
        aria-label="Postcode"
        value={postcode}
        onChange={(event) => setPostcode(event.target.value)}
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
        inputMode="numeric"
        autoComplete="postal-code"
      />
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

##### Clear the field

Set `clearable` on a controlled field with `onClear`; the cross appears only while there is content.

```tsx
import { useState } from "react";
import { FormField, Grid, Input } from "@umriss-ui/core";

export default function ClearTheField() {
  const [tracking, setTracking] = useState("FP-4471-2026-0317");
  const [search, setSearch] = useState("");

  return (
    <Grid minItemWidth="240px" gap={4}>
      <FormField label="Tracking number">
        <Input
          clearable
          value={tracking}
          onChange={(event) => setTracking(event.target.value)}
          onClear={() => setTracking("")}
        />
      </FormField>
      <FormField label="Search shipments" hint="Still empty, so no cross.">
        <Input
          clearable
          placeholder="Name, street or number"
          value={search}
          onChange={(event) => setSearch(event.target.value)}
          onClear={() => setSearch("")}
        />
      </FormField>
    </Grid>
  );
}
```

##### Align reference numbers

Set `numeric` where codes are compared digit by digit; the text stands right-aligned in tabular figures.

```tsx
import { FormField, Input, Stack } from "@umriss-ui/core";

export default function AlignReferenceNumbers() {
  return (
    <Stack gap={3} style={{ maxWidth: 280 }}>
      <FormField label="Shipment">
        <Input numeric defaultValue="100829" />
      </FormField>
      <FormField label="Return shipment">
        <Input numeric defaultValue="1011487" />
      </FormField>
    </Stack>
  );
}
```

##### Take a delivery address

Check the fields on submit and hand each message to its `FormField`; until then the fields stay uncontrolled.

```tsx
import { useState } from "react";
import type { FormEvent } from "react";
import { Button, FormField, Grid, Input, Stack, Text } from "@umriss-ui/core";

interface Errors {
  name?: string;
  street?: string;
  postcode?: string;
}

function check(data: FormData): Errors {
  const errors: Errors = {};
  if (String(data.get("name")).trim() === "") errors.name = "Name the consignee.";
  if (String(data.get("street")).trim() === "") errors.street = "Give a street and number.";
  if (!/^\d{5}$/.test(String(data.get("postcode")))) errors.postcode = "A postcode here has five digits.";
  return errors;
}

export default function TakeADeliveryAddress() {
  const [errors, setErrors] = useState<Errors>({});
  const [saved, setSaved] = useState(false);

  const submit = (event: FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    const next = check(new FormData(event.currentTarget));
    setErrors(next);
    setSaved(Object.keys(next).length === 0);
  };

  return (
    <form onSubmit={submit} noValidate style={{ maxWidth: 520 }}>
      <Stack gap={4}>
        <FormField label="Consignee" required error={errors.name}>
          <Input name="name" autoComplete="organization" defaultValue="Oakridge Pharmacy" />
        </FormField>
        <FormField label="Street" required error={errors.street}>
          <Input name="street" autoComplete="street-address" />
        </FormField>
        <Grid minItemWidth="160px" gap={4}>
          <FormField label="Postcode" required error={errors.postcode}>
            <Input name="postcode" numeric autoComplete="postal-code" defaultValue="204" />
          </FormField>
          <FormField label="Town">
            <Input name="town" autoComplete="address-level2" defaultValue="Ferrow" />
          </FormField>
        </Grid>
        <Stack direction="row" gap={3} align="center">
          <Button type="submit" variant="primary" size="sm">
            Save address
          </Button>
          {saved && (
            <Text size="sm" tone="muted">
              Saved to shipment 100829.
            </Text>
          )}
        </Stack>
      </Stack>
    </form>
  );
}
```

#### When to use something else

- A figure that is calculated with, with a unit and a range → NumberInput
- Text over several lines → Textarea
- One value out of a known list, found by typing → Combobox

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Moves into the field and on. The cross of a `clearable` field is not a stop: the keyboard clears the field by its own editing keys. |
| `Typing, arrows, Home / End` | The browser's own editing keys; the field adds none. |

#### API

##### `InputProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/input/configurator-input), [Sizes](#/input/sizes), [Open it with a shortcut (CommandPalette)](#/commandpalette/shortcut) and 3 more |
| `chars` | `number` | — | The width in characters - room for the value; the field adds its own padding and cross. Given, the field is that wide wherever it stands, and never wider than its place. Without it the field fills its place, and is 20 characters wide where the place asks - in a toolbar or a row.<br>Shown in: [Configurator](#/input/configurator-input), [Sized to the value (Sizes)](#/sizes/sized-to-the-value), [Narrow places (Sizes)](#/sizes/narrow-places) |
| `invalid` | `boolean` | — | Marks the field as invalid. `FormField` sets it itself as soon as it carries an `error` - by hand only necessary without `FormField`.<br>Shown in: [Configurator](#/input/configurator-input), [With an error](#/input/with-an-error), [With an error (TreeView)](#/treeview/with-an-error) |
| `numeric` | `boolean` | `false` | Right-aligned tabular figures in Geist Mono, e.g. for key figures.<br>Shown in: [Configurator](#/input/configurator-input), [Align reference numbers](#/input/align-reference-numbers), [Take a delivery address](#/input/take-a-delivery-address) and 2 more |
| `clearable` | `boolean` | `false` | Shows a gently appearing cross where there is content, which clears the input. Requires a controlled field (value) and onClear.<br>Shown in: [Clear the field](#/input/clear-the-field), [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still) |
| `ref` | `Ref<HTMLInputElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onClear` | `() => void` | — | Called by the cross. Clearing belongs to the caller: only it knows whether "empty" here is the empty text or no value at all.<br>Shown in: [Clear the field](#/input/clear-the-field), [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still) |

Also takes every attribute of `<input>` – without `size`.

#### Known limits

- No input masks or formatting while typing; check the value on leave or on submit.
- No validation of its own: the error is the application's, handed to the `FormField`.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### FormField

The frame around a field: its label, a hint below it and the error that replaces the hint. Wrap every field in one, so the question, the help and the problem are read out together.

```ts
import { FormField, useFormField } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/formfield/

Every field of Forms, Choosing and Dates and times reads its id, description, invalid and required state from the surrounding `FormField`; an `error` marks the field invalid by itself. A control of your own gets the same through [`useFormField`](#/api/useFormField).

`required` sets the mark and `aria-required`; it checks nothing. When and how a value is checked stays with the application.

#### Examples

##### Label and hint

Give every field a `label`; a `hint` below it says what the field expects and is read out with it.

```tsx
import { FormField, Input } from "@umriss-ui/core";

export default function LabelAndHint() {
  return (
    <FormField label="Cost centre" hint="As on the budget sheet, for example CC-2100." style={{ maxWidth: 360 }}>
      <Input placeholder="CC-0000" />
    </FormField>
  );
}
```

##### Show an error

Pass `error` once a value fails your check; it replaces the hint and marks the field invalid.

```tsx
import { FormField, Grid, Input } from "@umriss-ui/core";

export default function ShowAnError() {
  return (
    <Grid minItemWidth="240px" gap={4}>
      <FormField label="Cost centre" hint="As on the budget sheet, for example CC-2100.">
        <Input defaultValue="CC-2100" />
      </FormField>
      <FormField
        label="Cost centre"
        hint="As on the budget sheet, for example CC-2100."
        error="CC-2700 is not on the budget sheet."
      >
        <Input defaultValue="CC-2700" />
      </FormField>
      <FormField
        label="Reason for the overspend, as the budget owner will read it in the monthly review"
        error="Give a reason of at least ten characters, so the review can follow the decision without asking again."
      >
        <Input defaultValue="Events" />
      </FormField>
    </Grid>
  );
}
```

##### Mark a field as required

Set `required` for the mark on the label and `aria-required` on the field; checking the value stays yours.

```tsx
import { Checkbox, FormField, Grid, Input } from "@umriss-ui/core";

export default function MarkAFieldAsRequired() {
  return (
    <Grid minItemWidth="240px" gap={4}>
      <FormField label="Invoice number" required>
        <Input placeholder="INV-0000" />
      </FormField>
      <FormField label="Purchase order" hint="Optional.">
        <Input placeholder="PO-0000" />
      </FormField>
      <FormField label="Approval" required>
        <Checkbox label="I checked the amounts against the delivery note" />
      </FormField>
    </Grid>
  );
}
```

##### Check an invoice on submit

Hold the values, check them all on submit, and give each `FormField` its own message; the fields follow.

```tsx
import { useState } from "react";
import type { FormEvent } from "react";
import { Button, DatePicker, FormField, Grid, Input, NumberInput, Select, Stack, Text } from "@umriss-ui/core";

interface Invoice {
  number: string;
  centre: string;
  amount: number | null;
  due: Date | null;
}

type Errors = Partial<Record<keyof Invoice, string>>;

function check(invoice: Invoice): Errors {
  const errors: Errors = {};
  if (!/^INV-\d{4}$/.test(invoice.number)) errors.number = "An invoice number reads INV- and four digits.";
  if (invoice.centre === "") errors.centre = "Choose the cost centre the invoice is booked on.";
  if (invoice.amount === null || invoice.amount <= 0) errors.amount = "Give the net amount.";
  if (invoice.due === null) errors.due = "Give the due date from the invoice.";
  return errors;
}

export default function CheckAnInvoiceOnSubmit() {
  const [invoice, setInvoice] = useState<Invoice>({ number: "INV-31", centre: "", amount: 4860, due: null });
  const [errors, setErrors] = useState<Errors>({});
  const [booked, setBooked] = useState(false);
  const set = (patch: Partial<Invoice>) => setInvoice((previous) => ({ ...previous, ...patch }));

  const submit = (event: FormEvent) => {
    event.preventDefault();
    const next = check(invoice);
    setErrors(next);
    setBooked(Object.keys(next).length === 0);
  };

  return (
    <form onSubmit={submit} noValidate style={{ maxWidth: 560 }}>
      <Stack gap={4}>
        <Grid minItemWidth="220px" gap={4}>
          <FormField label="Invoice number" required error={errors.number}>
            <Input numeric value={invoice.number} onChange={(event) => set({ number: event.target.value })} />
          </FormField>
          <FormField label="Cost centre" required error={errors.centre}>
            <Select value={invoice.centre} onChange={(event) => set({ centre: event.target.value })}>
              <option value="" disabled>
                Choose a cost centre
              </option>
              <option value="CC-1200">CC-1200 Marketing</option>
              <option value="CC-2200">CC-2200 Design</option>
              <option value="CC-4300">CC-4300 IT</option>
            </Select>
          </FormField>
          <FormField label="Net amount" required error={errors.amount}>
            <NumberInput value={invoice.amount} onChange={(amount) => set({ amount })} min={0} decimals={2} suffix="€" />
          </FormField>
          <FormField label="Due" required error={errors.due}>
            <DatePicker value={invoice.due} onChange={(due) => set({ due })} clearable />
          </FormField>
        </Grid>
        <Stack direction="row" gap={3} align="center">
          <Button type="submit" variant="primary" size="sm">
            Book the invoice
          </Button>
          {booked && (
            <Text size="sm" tone="muted">
              {invoice.number} booked on {invoice.centre}.
            </Text>
          )}
        </Stack>
      </Stack>
    </form>
  );
}
```

#### Keyboard

The keys of [Input](#/input/keyboard-input), [NumberInput](#/numberinput/keyboard-numberinput), [Checkbox](#/checkbox/keyboard-checkbox), [Select](#/select/keyboard-select), [DatePicker](#/datepicker/keyboard-datepicker) and [Button](#/button/keyboard-button) apply here.

#### API

##### `FormFieldProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` *required* | `ReactNode` | — | The label of the field. It is mandatory: a field without a name is a field without a question for a screen reader.<br>Shown in: [Configurator](#/formfield/configurator-formfield), [Label and hint](#/formfield/label-and-hint), [Show an error](#/formfield/show-an-error) and 77 more |
| `hint` | `ReactNode` | — | Help text below the field. Replaced by `error`.<br>Shown in: [Configurator](#/formfield/configurator-formfield), [Label and hint](#/formfield/label-and-hint), [Show an error](#/formfield/show-an-error) and 33 more |
| `error` | `ReactNode` | — | Error message; it marks the field as invalid at the same time.<br>Shown in: [Configurator](#/formfield/configurator-formfield), [Show an error](#/formfield/show-an-error), [Check an invoice on submit](#/formfield/check-an-invoice-on-submit) and 22 more |
| `required` | `boolean` | `false` | Sets the required mark on the label and `aria-required` on the field - on Input, Select, Textarea, NumberInput, Combobox, RadioGroup and Checkbox. The triggers of the pickers and of the MultiSelect are buttons, on which `aria-required` is not a permitted attribute; there the mark carries it alone. It validates nothing - validation belongs to the caller ([ADR-0060](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0060-validation-and-a-layout-editor-are-never-time-zones-not-yet.md)).<br>Shown in: [Configurator](#/formfield/configurator-formfield), [Mark a field as required](#/formfield/mark-a-field-as-required), [Check an invoice on submit](#/formfield/check-an-invoice-on-submit) and 9 more |
| `fieldId` | `string` | — | Optional: a fixed id for the input element (instead of a generated one).<br>Shown in: [Sum up a form's errors (Alert)](#/alert/above-a-form) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>`.

#### Known limits

- No validation: the caller's form library decides; pass `error` ([ADR-0060](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0060-validation-and-a-layout-editor-are-never-time-zones-not-yet.md)). No form state and no submit handling either.
- One field per `FormField`; a group of fields that share one label is a fieldset of your own.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Textarea

Text over several lines (multi-line text field): a comment, a summary, a note to the driver. It can grow with its text and count the characters left.

```ts
import { Textarea } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/textarea/

#### Examples

##### Text area

Set `rows` for the height the text usually needs; the user can drag it taller.

```tsx
import { FormField, Textarea } from "@umriss-ui/core";

export default function TextArea() {
  return (
    <FormField label="Incident summary" style={{ maxWidth: 480 }}>
      <Textarea rows={3} placeholder="What happened, what customers saw, what is being done" />
    </FormField>
  );
}
```

##### States

Errors come from the `FormField`; `size="sm"` suits dense forms, and `disabled` text stays readable but fixed.

```tsx
import { FormField, Grid, Textarea } from "@umriss-ui/core";

export default function States() {
  return (
    <Grid minItemWidth="260px" gap={4}>
      <FormField label="Customer impact" hint="Fixed height, draggable downwards.">
        <Textarea
          rows={4}
          defaultValue={"Checkout answered slowly from 09:40 to 10:10.\nAbout one payment in twelve timed out and was retried by the customer."}
        />
      </FormField>
      <FormField label="Next update" hint="Small size.">
        <Textarea size="sm" rows={2} placeholder="When and where the next update goes out" />
      </FormField>
      <FormField label="Root cause" error="Give the root cause in at least ten characters.">
        <Textarea rows={2} defaultValue="Unknown" />
      </FormField>
      <FormField label="Timeline" hint="Written by the incident bot.">
        <Textarea rows={2} disabled defaultValue="09:41 Alert fired: Checkout p95 above 300 ms." />
      </FormField>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the field invalid by itself. Without one, set `invalid` and tie your message to the field with `aria-describedby`.

```tsx
import { useId, useState } from "react";
import { Stack, Text, Textarea } from "@umriss-ui/core";

export default function WithAnError() {
  const [rootCause, setRootCause] = useState("Unknown");
  const messageId = useId();
  const error = rootCause.trim().length < 10 ? "Give the root cause in at least ten characters." : undefined;

  return (
    <Stack gap={1} style={{ maxWidth: 420 }}>
      <Textarea
        aria-label="Root cause"
        rows={3}
        value={rootCause}
        onChange={(event) => setRootCause(event.target.value)}
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
      />
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

##### Grow with the text

Set `autoGrow` so the field grows with its text, and `maxRows` where it should start to scroll instead.

```tsx
import { useState } from "react";
import { Button, FormField, Stack, Textarea } from "@umriss-ui/core";

const LONG = Array.from({ length: 12 }, (_, i) => `10:${String(10 + i * 2).padStart(2, "0")} Update ${i + 1}: error rate back under 1 %.`).join("\n");

export default function GrowWithTheText() {
  const [notes, setNotes] = useState("09:41 Alert fired.\n09:44 Priya Raman acknowledged.\n09:52 Rolled back release 4.18.");

  return (
    <FormField label="Responder notes" hint="Grows to at most eight lines." style={{ maxWidth: 520 }}>
      <Stack gap={2}>
        <Textarea autoGrow maxRows={8} value={notes} onChange={(event) => setNotes(event.target.value)} />
        <Stack direction="row" gap={2}>
          <Button size="sm" onClick={() => setNotes(LONG)}>
            Paste a long log
          </Button>
          <Button size="sm" variant="ghost" onClick={() => setNotes("")}>
            Clear
          </Button>
        </Stack>
      </Stack>
    </FormField>
  );
}
```

##### Count the characters

Set `showCount` with a `maxLength` where a text goes somewhere short, such as a status page or a text message.

```tsx
import { useState } from "react";
import { FormField, Grid, Textarea } from "@umriss-ui/core";

export default function CountTheCharacters() {
  const [status, setStatus] = useState("Payments are slower than usual. We are on it.");
  const [sms, setSms] = useState(
    "Checkout is degraded since 09:40; release 4.18 rolled back, error rate falling, next update at 11:00 on the status page.",
  );

  return (
    <Grid minItemWidth="260px" gap={4}>
      <FormField label="Status page headline">
        <Textarea showCount maxLength={80} rows={2} value={status} onChange={(event) => setStatus(event.target.value)} />
      </FormField>
      <FormField label="Text message to on-call" hint="Set from outside, past the limit.">
        <Textarea showCount maxLength={100} rows={3} value={sms} onChange={(event) => setSms(event.target.value)} />
      </FormField>
    </Grid>
  );
}
```

#### When to use something else

- A short answer on one line → Input

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Moves into the field and on; it is never typed into the text. |
| `Enter` | Starts a new line; it does not send the form. |
| `Typing, arrows, Home / End` | The browser's own editing keys; the field adds none. |

#### Accessibility

A native `textarea`. Inside a [FormField](#/formfield) it takes the field's label, hint, required and invalid state; without one, give it an `aria-label`.

With `showCount` the characters left stand in a polite live region: a screen reader reads the count when it is free, not after every letter typed.

#### API

##### `TextareaProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/textarea/configurator-textarea), [States](#/textarea/states) |
| `chars` | `number` | — | The width in characters - the length of a line; the field adds its own padding. Given, the field is that wide wherever it stands, and never wider than its place. Without it the field fills its place, and is 40 characters wide where the place asks - in a row.<br>Shown in: [Configurator](#/textarea/configurator-textarea) |
| `invalid` | `boolean` | — | Marks the field as invalid. `FormField` sets it itself as soon as it carries an `error` – by hand only needed without `FormField`.<br>Shown in: [Configurator](#/textarea/configurator-textarea), [With an error](#/textarea/with-an-error) |
| `autoGrow` | `boolean` | `false` | Grows with its content instead of scrolling.<br>Shown in: [Configurator](#/textarea/configurator-textarea), [Grow with the text](#/textarea/grow-with-the-text), [Resolve an incident (Scenarios)](#/scenarios/resolve-an-incident) and 1 more |
| `maxRows` | `number` | — | Upper bound for `autoGrow` in rows; beyond it the field scrolls.<br>Shown in: [Grow with the text](#/textarea/grow-with-the-text), [Resolve an incident (Scenarios)](#/scenarios/resolve-an-incident), [Approve spending against a budget (Scenarios)](#/scenarios/approve-spending) |
| `showCount` | `boolean` | `false` | Shows at the bottom right how many characters still fit. Needs `maxLength`.<br>Shown in: [Count the characters](#/textarea/count-the-characters) |
| `resize` | `"none" \| "vertical"` | `"none"` while the field grows by itself, else `"vertical"` | Whether the browser's handle for dragging is offered.<br>Shown in: [Configurator](#/textarea/configurator-textarea) |
| `ref` | `Ref<HTMLTextAreaElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<textarea>` – without `cols`.

#### Known limits

- Plain text only: no formatting, mentions or rich text.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### NumberInput

A number typed exactly (numeric field, spin box): an amount, a weight, hours. It shows the unit inside the field, keeps the value in its range and steps with the arrow keys.

```ts
import { NumberInput } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/numberinput/

The value is a number or `null`. An empty field is `null`, not zero: a figure nobody gave is not a figure of zero.

It writes and reads the number in the notation of the formats, so German users get a decimal comma through `@umriss-ui/core/wording/de` ([ADR-0024](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0024-the-formats-are-english-german-is-freight.md)). Every value reported is already clamped to the range; the text in the field follows when it is left.

#### Examples

##### Number field

The value is a number or `null`; the field writes it in the formats' notation and reads it back.

```tsx
import { useState } from "react";
import { FormField, NumberInput } from "@umriss-ui/core";

export default function NumberField() {
  const [weight, setWeight] = useState<number | null>(18.5);

  return (
    <FormField label="Parcel weight" style={{ maxWidth: 240 }}>
      <NumberInput value={weight} onChange={setWeight} min={0} decimals={1} suffix="kg" />
    </FormField>
  );
}
```

##### Units and decimals

Put the unit in `prefix` or `suffix`, inside the field, and fix the places with `decimals`.

```tsx
import { useState } from "react";
import { FormField, Grid, NumberInput } from "@umriss-ui/core";

export default function UnitsAndDecimals() {
  const [budget, setBudget] = useState<number | null>(68000);
  const [discount, setDiscount] = useState<number | null>(2.5);
  const [variance, setVariance] = useState<number | null>(-4.25);

  return (
    <Grid minItemWidth="200px" gap={4}>
      <FormField label="Monthly budget" hint="Whole euros, step 500.">
        <NumberInput value={budget} onChange={setBudget} min={0} decimals={0} step={500} suffix="€" />
      </FormField>
      <FormField label="Early payment discount" hint="One decimal place.">
        <NumberInput value={discount} onChange={setDiscount} min={0} max={10} decimals={1} step={0.5} suffix="%" />
      </FormField>
      <FormField label="Forecast variance" hint="Negative allowed.">
        <NumberInput value={variance} onChange={setVariance} decimals={2} step={0.25} prefix="±" suffix="%" />
      </FormField>
    </Grid>
  );
}
```

##### States

An empty field reports `null`, not zero; errors come from the `FormField`, and `disabled` holds the figure fixed.

```tsx
import { useState } from "react";
import { FormField, Grid, NumberInput, Text } from "@umriss-ui/core";

export default function States() {
  const [actual, setActual] = useState<number | null>(null);
  const [quantity, setQuantity] = useState<number | null>(0);

  return (
    <Grid minItemWidth="220px" gap={4}>
      <FormField label="Actual, March" hint="Not booked yet.">
        <NumberInput value={actual} onChange={setActual} decimals={0} suffix="€" />
        <Text size="xs" tone="muted" mono>
          value: {actual === null ? "null" : actual}
        </Text>
      </FormField>
      <FormField label="Quantity" error="An invoice line needs at least one unit.">
        <NumberInput value={quantity} onChange={setQuantity} min={0} decimals={0} />
      </FormField>
      <FormField label="VAT rate" hint="Set by the tax code.">
        <NumberInput value={19} onChange={() => {}} disabled suffix="%" />
      </FormField>
      <FormField label="Annual budget, all cost centres" hint="Small size, a long figure.">
        <NumberInput size="sm" value={9_048_000.5} onChange={() => {}} decimals={2} suffix="€" />
      </FormField>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the field invalid by itself. Without one, set `invalid` and tie your message to the field with `aria-describedby`.

```tsx
import { useId, useState } from "react";
import { NumberInput, Stack, Text } from "@umriss-ui/core";

export default function WithAnError() {
  const [quantity, setQuantity] = useState<number | null>(0);
  const messageId = useId();
  const error = quantity === null || quantity < 1 ? "An invoice line needs at least one unit." : undefined;

  return (
    <Stack gap={1} style={{ maxWidth: 280 }}>
      <NumberInput
        aria-label="Quantity"
        value={quantity}
        onChange={setQuantity}
        min={0}
        decimals={0}
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
      />
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

##### Keep a value in range

Set `min` and `max`: what `onChange` reports is always clamped, and the text follows when the field is left.

```tsx
import { useState } from "react";
import { FormField, Grid, NumberInput } from "@umriss-ui/core";

export default function KeepAValueInRange() {
  const [capacity, setCapacity] = useState<number | null>(32);
  const [focus, setFocus] = useState<number | null>(60);

  return (
    <Grid minItemWidth="220px" gap={4}>
      <FormField label="Capacity, Kofi Mensah" hint="0 to 48 hours a week; arrows count, Shift ×10.">
        <NumberInput value={capacity} onChange={setCapacity} min={0} max={48} decimals={0} suffix="h" />
      </FormField>
      <FormField label="Share for project work" hint="0 to 100 %, step 5.">
        <NumberInput value={focus} onChange={setFocus} min={0} max={100} step={5} decimals={0} suffix="%" />
      </FormField>
    </Grid>
  );
}
```

##### Price an invoice line

Several number fields feed one derived figure; the total is computed from the values and never stored beside them.

```tsx
import { useState } from "react";
import { Card, CardBody, CardHeader, FormField, Grid, NumberInput, Stack, Text, useFormats } from "@umriss-ui/core";

export default function PriceAnInvoiceLine() {
  const formats = useFormats();
  const [quantity, setQuantity] = useState<number | null>(40);
  const [unitPrice, setUnitPrice] = useState<number | null>(12.9);
  const [discount, setDiscount] = useState<number | null>(5);

  const net = (quantity ?? 0) * (unitPrice ?? 0) * (1 - (discount ?? 0) / 100);

  return (
    <Card style={{ maxWidth: 560 }}>
      <CardHeader eyebrow="INV-2031, line 2" title="Printer paper, A4, 500 sheets" />
      <CardBody>
        <Stack gap={4}>
          <Grid minItemWidth="140px" gap={3}>
            <FormField label="Quantity">
              <NumberInput value={quantity} onChange={setQuantity} min={0} decimals={0} />
            </FormField>
            <FormField label="Unit price">
              <NumberInput value={unitPrice} onChange={setUnitPrice} min={0} decimals={2} step={0.1} suffix="€" />
            </FormField>
            <FormField label="Discount">
              <NumberInput value={discount} onChange={setDiscount} min={0} max={100} decimals={1} suffix="%" />
            </FormField>
          </Grid>
          <Text size="sm">
            Line total, net: <Text as="span" mono>{formats.number(net, 2)} €</Text>
          </Text>
        </Stack>
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- A value set roughly, where the position between two bounds matters more than the exact figure → Slider
- A code or reference that is never calculated with → Input

#### Keyboard

| Key | Action |
|---|---|
| `Arrow Up / Arrow Down` | Steps the value up or down by one step. |
| `Shift + Arrow Up / Down` | Steps by ten steps. |

#### API

##### `NumberInputProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `number \| null` | — | The number, or `null` for "not stated". An empty field is not zero: a quantity that was not measured is not a quantity of zero.<br>Shown in: [Configurator](#/numberinput/configurator-numberinput), [Number field](#/numberinput/number-field), [Units and decimals](#/numberinput/units-and-decimals) and 13 more |
| `min` | `number` | — | Lower bound. Every reported value is clamped; the text in the field follows on leaving.<br>Shown in: [Configurator](#/numberinput/configurator-numberinput), [Number field](#/numberinput/number-field), [Units and decimals](#/numberinput/units-and-decimals) and 11 more |
| `max` | `number` | — | Upper bound. Every reported value is clamped; the text in the field follows on leaving.<br>Shown in: [Configurator](#/numberinput/configurator-numberinput), [Units and decimals](#/numberinput/units-and-decimals), [Keep a value in range](#/numberinput/keep-a-value-in-range) and 5 more |
| `step` | `number` | `1` | Step size for the arrow keys; Shift multiplies it by ten.<br>Shown in: [Configurator](#/numberinput/configurator-numberinput), [Units and decimals](#/numberinput/units-and-decimals), [Keep a value in range](#/numberinput/keep-a-value-in-range) and 3 more |
| `decimals` | `number` | — | Fixed decimal places; 0 = whole numbers, undefined = free.<br>Shown in: [Configurator](#/numberinput/configurator-numberinput), [Number field](#/numberinput/number-field), [Units and decimals](#/numberinput/units-and-decimals) and 11 more |
| `prefix` | `ReactNode` | — | Adornment before the number, e.g. "±".<br>Shown in: [Units and decimals](#/numberinput/units-and-decimals) |
| `suffix` | `ReactNode` | — | Adornment after the number, e.g. "€" or "%".<br>Shown in: [Number field](#/numberinput/number-field), [Units and decimals](#/numberinput/units-and-decimals), [States](#/numberinput/states) and 9 more |
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/numberinput/configurator-numberinput), [States](#/numberinput/states), [Set up a team (Scenarios)](#/scenarios/set-up-a-team) |
| `chars` | `number` | — | The width in characters - room for the number; the field adds its own padding and steppers, and the room for a `prefix` and `suffix` given as text. Given, the field is that wide wherever it stands, and never wider than its place. Without it the field fills its place, and is 10 characters wide where the place asks - in a toolbar or a row.<br>Shown in: [Configurator](#/numberinput/configurator-numberinput), [Sized to the value (Sizes)](#/sizes/sized-to-the-value) |
| `invalid` | `boolean` | — | Marks the field as invalid. `FormField` sets it itself as soon as it carries an `error` – by hand only needed without `FormField`.<br>Shown in: [Configurator](#/numberinput/configurator-numberinput), [With an error](#/numberinput/with-an-error) |
| `ref` | `Ref<HTMLInputElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` *required* | `(value: number \| null) => void` | — | Runs on every valid input, with `null` for the emptied field – and always clamped: what goes out lies between `min` and `max`, by every route, while typing included. Only the text in the field may still stand outside while typing; on leaving it is set to the clamped value.<br>Shown in: [Configurator](#/numberinput/configurator-numberinput), [Number field](#/numberinput/number-field), [Units and decimals](#/numberinput/units-and-decimals) and 13 more |

Also takes every attribute of `<input>` – without `onChange`, `prefix`, `size`, `type`, `value`.

#### Known limits

- No expressions: “12*4” is not calculated.
- No currency conversion; the unit is a label.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Slider

A value set roughly between two bounds (range slider): a share of traffic, an alert threshold, weekly hours. The position on the track says as much as the figure.

```ts
import { Slider } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/slider/

`onChange` reports a number already on the step and inside the bounds, by pointer and by key alike. Pair it with a [NumberInput](#/numberinput) on the same state when the exact figure matters too.

#### Examples

##### Slider

Use a slider for a value set roughly between two bounds; `step` sets how finely it moves.

```tsx
import { FormField, Slider } from "@umriss-ui/core";

export default function CanaryTraffic() {
  return (
    <FormField label="Canary traffic, %" hint="Share of requests the new release receives." style={{ maxWidth: 360 }}>
      <Slider min={0} max={100} step={5} defaultValue={10} />
    </FormField>
  );
}
```

##### Units and marks

`format` writes the value for the readout and the screen reader; `marks` show reference values, with a word where one has a `label`.

```tsx
import { FormField, Grid, Slider } from "@umriss-ui/core";

export default function UnitsAndMarks() {
  return (
    <Grid minItemWidth="260px" gap={6}>
      <FormField label="Alert above error rate">
        <Slider
          min={0}
          max={5}
          step={0.1}
          defaultValue={1.5}
          format={(v) => `${v.toFixed(1)} %`}
          marks={[0, { value: 1, label: "Objective" }, 5]}
        />
      </FormField>
      <FormField label="Log retention" hint="30 days, fixed by the data protection policy.">
        <Slider min={7} max={90} defaultValue={30} disabled showValue={false} marks={[7, 30, 90]} />
      </FormField>
    </Grid>
  );
}
```

##### Set roughly, then exactly

Control it with `value` and `onChange` and put a `NumberInput` beside it on the same state for the exact figure.

```tsx
import { useState } from "react";
import { FormField, NumberInput, Slider, Stack } from "@umriss-ui/core";

export default function SetRoughlyThenExactly() {
  const [hours, setHours] = useState(32);

  return (
    <Stack gap={3} style={{ maxWidth: 420 }}>
      <FormField label="Weekly capacity, Kofi Mensah">
        <Slider
          min={0}
          max={48}
          value={hours}
          onChange={setHours}
          showValue={false}
          format={(v) => `${v} h`}
          marks={[{ value: 0, label: "0" }, { value: 40, label: "Full time" }, { value: 48, label: "48" }]}
        />
      </FormField>
      <FormField label="Exact hours">
        <NumberInput value={hours} onChange={(v) => setHours(v ?? 0)} min={0} max={48} decimals={0} suffix="h" />
      </FormField>
    </Stack>
  );
}
```

##### Split a budget

Several sliders share one whole; show the sum they make in words, since no single slider can say it.

```tsx
import { useState } from "react";
import { Badge, Card, CardBody, CardHeader, FormField, Slider, Stack, Text, useFormats } from "@umriss-ui/core";

const CHANNELS = [
  { id: "search", label: "Search ads", plan: 45 },
  { id: "events", label: "Events", plan: 30 },
  { id: "content", label: "Content", plan: 25 },
];

const BUDGET = 68_000;

export default function SplitABudget() {
  const formats = useFormats();
  const [shares, setShares] = useState<Record<string, number>>({ search: 45, events: 35, content: 25 });
  const sum = CHANNELS.reduce((total, c) => total + (shares[c.id] ?? 0), 0);

  return (
    <Card style={{ maxWidth: 560 }}>
      <CardHeader
        eyebrow="CC-1200 Marketing · April"
        title={`Budget ${formats.number(BUDGET, 0)} €`}
        actions={<Badge tone={sum === 100 ? "success" : "warning"}>{sum === 100 ? "Adds up to 100 %" : `Sum ${sum} %`}</Badge>}
      />
      <CardBody>
        <Stack gap={5}>
          {CHANNELS.map((c) => (
            <FormField key={c.id} label={c.label}>
              <Slider
                step={5}
                value={shares[c.id] ?? 0}
                onChange={(v) => setShares((previous) => ({ ...previous, [c.id]: v }))}
                format={(v) => `${v} % · ${formats.number((BUDGET * v) / 100, 0)} €`}
                marks={[0, 50, 100, { value: c.plan, label: "Plan" }]}
              />
            </FormField>
          ))}
          <Text size="xs" tone="muted">
            The plan was agreed in the March review.
          </Text>
        </Stack>
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- An exact figure, or a range without sensible bounds → NumberInput

#### Keyboard

| Key | Action |
|---|---|
| `Arrow Right / Arrow Up` | Increases the value by one step. |
| `Arrow Left / Arrow Down` | Decreases the value by one step. |
| `Page Up / Page Down` | Moves by a tenth of the range. |
| `Home / End` | Moves to the lower or upper bound. |

#### API

##### `SliderProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `defaultValue` | `number` | `min` | Uncontrolled: the value to start at.<br>Shown in: [Configurator](#/slider/configurator-slider), [Slider](#/slider/canary-traffic), [Units and marks](#/slider/units-and-marks) |
| `value` | `number` | — | Controlled: the value.<br>Shown in: [Set roughly, then exactly](#/slider/set-roughly-then-exactly), [Split a budget](#/slider/split-a-budget), [Browse down and back up (Breadcrumb)](#/breadcrumb/browse-down-and-back-up) and 2 more |
| `min` | `number` | `0` | The smallest value.<br>Shown in: [Configurator](#/slider/configurator-slider), [Slider](#/slider/canary-traffic), [Units and marks](#/slider/units-and-marks) and 4 more |
| `max` | `number` | `100` | The largest value.<br>Shown in: [Configurator](#/slider/configurator-slider), [Slider](#/slider/canary-traffic), [Units and marks](#/slider/units-and-marks) and 4 more |
| `step` | `number` | `1` | The step the value moves by, by pointer or key.<br>Shown in: [Configurator](#/slider/configurator-slider), [Slider](#/slider/canary-traffic), [Units and marks](#/slider/units-and-marks) and 3 more |
| `marks` | `readonly `[`SliderMark`](#type-SliderMark)`[]` | — | Values marked on the track; an object with a `label` writes the word beneath its mark. A mark shows a value, it does not catch the thumb.<br>Shown in: [Units and marks](#/slider/units-and-marks), [Set roughly, then exactly](#/slider/set-roughly-then-exactly), [Split a budget](#/slider/split-a-budget) and 1 more |
| `format` | `(value: number) => string` | the number in the formats' notation, with as many decimals as the step has | The value as text: for the readout and for the screen reader (`aria-valuetext`).<br>Shown in: [Units and marks](#/slider/units-and-marks), [Set roughly, then exactly](#/slider/set-roughly-then-exactly), [Split a budget](#/slider/split-a-budget) and 3 more |
| `showValue` | `boolean` | `true` | The value in mono beside the track.<br>Shown in: [Configurator](#/slider/configurator-slider), [Units and marks](#/slider/units-and-marks), [Set roughly, then exactly](#/slider/set-roughly-then-exactly) and 1 more |
| `ref` | `Ref<HTMLInputElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` | `(value: number) => void` | — | Reports every change, by pointer or key, as a number on the step.<br>Shown in: [Set roughly, then exactly](#/slider/set-roughly-then-exactly), [Split a budget](#/slider/split-a-budget), [Browse down and back up (Breadcrumb)](#/breadcrumb/browse-down-and-back-up) and 2 more |

Also takes every attribute of `<input>` – without `defaultValue`, `max`, `min`, `onChange`, `step`, `type`, `value`.

##### Types on this page

###### `SliderMark`

A mark on the track: a value, or a value with the word beneath it.

```ts
type SliderMark = number | { value: number; label?: ReactNode };
```

#### Known limits

- One thumb: no range with two ends.
- Marks show values; they do not catch the thumb.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Checkbox

A yes or no that counts when the form is saved (tick box). It also shows the mixed state of a parent whose children are partly checked.

```ts
import { Checkbox } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/checkbox/

The mixed state is derived, never stored: set it when some children are checked, and a click on the parent checks all or none.

#### Examples

##### Checkbox

A `label` beside the box makes the whole line clickable; the value counts when the form is saved.

```tsx
import { Checkbox } from "@umriss-ui/core";

export default function CheckboxExample() {
  return <Checkbox label="Signature required on delivery" defaultChecked />;
}
```

##### States

Unchecked, checked and mixed, each also `disabled`; an `error` on the surrounding `FormField` marks the box invalid.

```tsx
import { Checkbox, FormField, Grid, Stack } from "@umriss-ui/core";

export default function States() {
  return (
    <Grid minItemWidth="240px" gap={5}>
      <Stack gap={3}>
        <Checkbox label="Leave at the door" />
        <Checkbox label="Fragile" defaultChecked />
        <Checkbox label="All parcels of the tour" indeterminate />
      </Stack>
      <Stack gap={3}>
        <Checkbox label="Cash on delivery" disabled />
        <Checkbox label="Proof of delivery photo" disabled defaultChecked />
        <Checkbox label="Hazardous goods" disabled indeterminate />
      </Stack>
      <Stack gap={3}>
        <FormField label="Terms" error="Accept the carrier terms to book the pick-up.">
          <Checkbox label="I accept the carrier terms" />
        </FormField>
        <Checkbox label="Call the consignee thirty minutes before arrival, and again from the kerb if nobody answers the door on the first ring" />
      </Stack>
    </Grid>
  );
}
```

##### Select all with a mixed state

Derive `indeterminate` from the children when some are checked; a click on the parent checks all or none.

```tsx
import { useState } from "react";
import { Checkbox, Stack } from "@umriss-ui/core";

const TEAM = ["Maya Lindgren", "Arjun Mehta", "Chloe Durand", "Noah Fischer", "Eva Novak"];

export default function SelectAllWithAMixedState() {
  const [notified, setNotified] = useState([true, false, true, false, false]);
  const all = notified.every(Boolean);
  const none = notified.every((on) => !on);

  return (
    <Stack gap={3} align="flex-start">
      <Checkbox
        label="Tell team Web about my leave"
        checked={all}
        indeterminate={!all && !none}
        onChange={(event) => setNotified(notified.map(() => event.target.checked))}
      />
      <Stack gap={2} style={{ paddingLeft: "var(--u-space-6)" }}>
        {TEAM.map((name, i) => (
          <Checkbox
            key={name}
            label={name}
            checked={notified[i]}
            onChange={(event) =>
              setNotified((previous) => previous.map((on, j) => (i === j ? event.target.checked : on)))
            }
          />
        ))}
      </Stack>
    </Stack>
  );
}
```

#### When to use something else

- A setting that takes effect the moment it flips → Switch
- One choice out of a few that exclude each other → RadioGroup

#### Keyboard

| Key | Action |
|---|---|
| `Space` | Checks or unchecks the focused box. |

#### API

##### `CheckboxProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `ReactNode` | — | Label to the right of the checkbox.<br>Shown in: [Configurator](#/checkbox/configurator-checkbox), [Checkbox](#/checkbox/checkbox), [States](#/checkbox/states) and 10 more |
| `indeterminate` | `boolean` | `false` | Partially checked (e.g. "select all" with a mixed selection).<br>Shown in: [Configurator](#/checkbox/configurator-checkbox), [States](#/checkbox/states), [Select all with a mixed state](#/checkbox/select-all-with-a-mixed-state) |
| `ref` | `Ref<HTMLInputElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<input>` – without `size`, `type`.

### Switch

On or off, taking effect at once (toggle): paging at night, autoscaling, a feature for one service. A screen reader announces it as a switch, on or off.

```ts
import { Switch } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/switch/

#### Examples

##### On and off

Use a switch for a setting that takes effect the moment it flips; Space and a click on the label toggle it.

```tsx
import { Switch } from "@umriss-ui/core";

export default function OnAndOff() {
  return <Switch label="Page me at night" defaultChecked />;
}
```

##### States and sizes

Both sizes, off and on, each also `disabled`; an `error` on the surrounding `FormField` marks the switch invalid.

```tsx
import { FormField, Grid, Stack, Switch, Text } from "@umriss-ui/core";

export default function StatesAndSizes() {
  return (
    <Grid minItemWidth="220px" gap={5}>
      <Stack gap={3}>
        <Text size="xs" tone="muted">
          Medium
        </Text>
        <Switch label="Status page" />
        <Switch label="Error budget alerts" defaultChecked />
        <Switch label="Public API" disabled />
        <Switch label="Audit log" disabled defaultChecked />
      </Stack>
      <Stack gap={3}>
        <Text size="xs" tone="muted">
          Small
        </Text>
        <Switch size="sm" label="Status page" />
        <Switch size="sm" label="Error budget alerts" defaultChecked />
        <Switch size="sm" label="Public API" disabled />
        <Switch size="sm" label="Audit log" disabled defaultChecked />
      </Stack>
      <Stack gap={3}>
        <Text size="xs" tone="muted">
          Invalid, and a long label
        </Text>
        <FormField label="Paging" error="A tier 1 service has to page its on-call engineer.">
          <Switch label="Page on-call" />
        </FormField>
        <Switch label="Post every deployment of this service to the team channel, including the automatic rollbacks" defaultChecked />
      </Stack>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the switch invalid by itself. Without one, set `invalid` and tie your message to the switch with `aria-describedby`.

```tsx
import { useId, useState } from "react";
import { Stack, Switch, Text } from "@umriss-ui/core";

export default function WithAnError() {
  const [paging, setPaging] = useState(false);
  const messageId = useId();
  const error = paging ? undefined : "A tier 1 service has to page its on-call engineer.";

  return (
    <Stack gap={1}>
      <Switch
        label="Page on-call, Checkout (tier 1)"
        checked={paging}
        onChange={(event) => setPaging(event.target.checked)}
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
      />
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

##### Let the switch decide what follows

Control it with `checked` and `onChange` when other fields depend on it; here autoscaling takes the instance count away.

```tsx
import { useState } from "react";
import { FormField, NumberInput, Stack, Switch } from "@umriss-ui/core";

export default function LetTheSwitchDecide() {
  const [autoscaling, setAutoscaling] = useState(true);
  const [instances, setInstances] = useState<number | null>(6);

  return (
    <Stack gap={4} style={{ maxWidth: 320 }}>
      <Switch label="Autoscaling" checked={autoscaling} onChange={(event) => setAutoscaling(event.target.checked)} />
      <FormField label="Instances" hint={autoscaling ? "Set by autoscaling, between 2 and 24." : "Fixed by hand."}>
        <NumberInput value={instances} onChange={setInstances} min={1} max={24} decimals={0} disabled={autoscaling} />
      </FormField>
    </Stack>
  );
}
```

##### Settings of a service

Give each switch its sentence through `aria-describedby`, and say why when one is `disabled` for now.

```tsx
import { useId, useState } from "react";
import { Badge, Card, CardBody, CardHeader, Divider, Stack, Switch, Text } from "@umriss-ui/core";

interface Setting {
  id: string;
  label: string;
  description: string;
  lockedDuringIncident?: boolean;
}

const SETTINGS: Setting[] = [
  { id: "deploys", label: "Deployments", description: "Lets the pipeline release to production." },
  { id: "canary", label: "Canary releases", description: "Sends a new release to 5 % of traffic for 15 minutes first." },
  { id: "flags", label: "Feature flag changes", description: "Only while no incident is open on this service.", lockedDuringIncident: true },
  { id: "page", label: "Page on-call", description: "Pages the primary when the latency objective is breached." },
  { id: "digest", label: "Weekly digest", description: "Mails the team the week's latency and error budget." },
];

export default function SettingsOfAService() {
  const [on, setOn] = useState<Record<string, boolean>>({ deploys: true, canary: true, page: true });
  const incidentOpen = true;
  const base = useId();
  const count = SETTINGS.filter((s) => on[s.id]).length;

  return (
    <Card style={{ maxWidth: 520 }}>
      <CardHeader eyebrow="Checkout · Payments" title="Service settings" actions={<Badge pill>{count} on</Badge>} />
      <CardBody>
        <Stack gap={3}>
          {SETTINGS.map((s, i) => {
            const locked = s.lockedDuringIncident === true && incidentOpen;
            return (
              <Stack key={s.id} gap={3}>
                {i > 0 && <Divider />}
                <Stack gap={1}>
                  <Switch
                    label={s.label}
                    checked={on[s.id] === true}
                    disabled={locked}
                    aria-describedby={`${base}-${s.id}`}
                    onChange={(event) => setOn((previous) => ({ ...previous, [s.id]: event.target.checked }))}
                  />
                  <Text id={`${base}-${s.id}`} size="xs" tone="muted" style={{ paddingLeft: 36 }}>
                    {locked ? "Locked while INC-1048 is open. " : ""}
                    {s.description}
                  </Text>
                </Stack>
              </Stack>
            );
          })}
        </Stack>
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- A choice that only counts after a Save button → Checkbox

#### Keyboard

| Key | Action |
|---|---|
| `Space` | Turns the focused switch on or off. |

#### API

##### `SwitchProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` | `ReactNode` | — | Label to the right of the switch.<br>Shown in: [Configurator](#/switch/configurator-switch), [On and off](#/switch/on-and-off), [States and sizes](#/switch/states-and-sizes) and 13 more |
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/switch/configurator-switch), [States and sizes](#/switch/states-and-sizes) |
| `invalid` | `boolean` | — | Marks the switch as invalid. `FormField` sets it itself as soon as it carries an `error` - by hand only necessary without `FormField`.<br>Shown in: [Configurator](#/switch/configurator-switch), [With an error](#/switch/with-an-error) |
| `ref` | `Ref<HTMLInputElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<input>` – without `role`, `size`, `type`.

#### Known limits

- No pending or loading state; while your application applies the change, disable the switch or say so beside it.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### RadioGroup

One choice out of a few that all stay in view (radio buttons, option group). Each option may carry a sentence that explains it.

```ts
import { RadioGroup } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/radiogroup/

The group is one tab stop; the arrow keys move and choose at once, skipping disabled options, which stay visible.

#### Examples

##### Radio group

Pass the choices as `options`; the group takes one tab stop, and the arrow keys move and choose at once.

```tsx
import { useState } from "react";
import { FormField, RadioGroup } from "@umriss-ui/core";

export default function RadioGroupExample() {
  const [attempt, setAttempt] = useState("neighbour");

  return (
    <FormField label="If nobody is home">
      <RadioGroup
        value={attempt}
        onChange={setAttempt}
        options={[
          { value: "door", label: "Leave at the door" },
          { value: "neighbour", label: "Hand to a neighbour" },
          { value: "depot", label: "Take back to the depot" },
        ]}
      />
    </FormField>
  );
}
```

##### Descriptions

Give an option a `description` when the choice needs a sentence; a `disabled` option stays visible and is skipped.

```tsx
import { useState } from "react";
import { FormField, RadioGroup } from "@umriss-ui/core";

export default function Descriptions() {
  const [service, setService] = useState("standard");

  return (
    <FormField label="Delivery service" style={{ maxWidth: 480 }}>
      <RadioGroup
        value={service}
        onChange={setService}
        options={[
          { value: "standard", label: "Standard", description: "Within two working days, at no extra charge." },
          { value: "next-day", label: "Next day", description: "Booked before 14:00, delivered the next working day." },
          { value: "same-day", label: "Same day", description: "Booked before 10:00, delivered by 18:00 within the city." },
          { value: "pick-up", label: "Pick-up point", description: "No pick-up point within 2 km of this address.", disabled: true },
        ]}
      />
    </FormField>
  );
}
```

##### Side by side

Set `orientation="horizontal"` for a few short labels without descriptions.

```tsx
import { useState } from "react";
import { FormField, RadioGroup } from "@umriss-ui/core";

export default function SideBySide() {
  const [part, setPart] = useState("full");

  return (
    <FormField label="Leave on Friday, 20 March">
      <RadioGroup
        orientation="horizontal"
        value={part}
        onChange={setPart}
        options={[
          { value: "morning", label: "Morning" },
          { value: "afternoon", label: "Afternoon" },
          { value: "full", label: "Full day" },
        ]}
      />
    </FormField>
  );
}
```

##### States

With no `defaultValue` nothing is chosen yet; errors come from the `FormField`, and `disabled` on the group locks every option.

```tsx
import { FormField, Grid, RadioGroup } from "@umriss-ui/core";

const KINDS = [
  { value: "annual", label: "Annual leave" },
  { value: "sick", label: "Sick leave" },
  { value: "training", label: "Training, counted as working time but blocked for project work" },
];

export default function States() {
  return (
    <Grid minItemWidth="240px" gap={5}>
      <FormField label="Kind of absence" error="Choose the kind of absence.">
        <RadioGroup options={KINDS} />
      </FormField>
      <FormField label="Kind of absence" hint="Approved, no longer editable.">
        <RadioGroup options={KINDS} defaultValue="annual" disabled />
      </FormField>
      <FormField label="Kind of absence" hint="Small size.">
        <RadioGroup size="sm" options={KINDS} defaultValue="training" />
      </FormField>
    </Grid>
  );
}
```

#### When to use something else

- Two to four short options without explanations, standing among fields → SegmentedControl
- More than about five options, or options that need no explanation → Select
- A single yes or no → Checkbox
- Several options at once → MultiSelect

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Moves into the group, onto the chosen option, and out again. |
| `Arrow Down / Arrow Right` | Chooses the next option, wrapping at the end. |
| `Arrow Up / Arrow Left` | Chooses the previous option. |

#### API

##### `RadioGroupProps<T extends string>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `options` *required* | `readonly `[`RadioOption`](#type-RadioOption)`<T>[]` | — | The possibilities, in the order in which they are meant to stand.<br>Shown in: [Configurator](#/radiogroup/configurator-radiogroup), [Radio group](#/radiogroup/radio-group), [Descriptions](#/radiogroup/descriptions) and 5 more |
| `defaultValue` | `T \| null` | — | Initial value of an uncontrolled group. Not together with `value`.<br>Shown in: [Configurator](#/radiogroup/configurator-radiogroup), [States](#/radiogroup/states), [A row of fields (Sizes)](#/sizes/a-row-of-fields) |
| `value` | `T \| null` | — | The chosen possibility; `null` means: none yet. Together with `onChange` the group is controlled.<br>Shown in: [Radio group](#/radiogroup/radio-group), [Descriptions](#/radiogroup/descriptions), [Side by side](#/radiogroup/side-by-side) and 2 more |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Arrangement: one below the other, or side by side.<br>Shown in: [Configurator](#/radiogroup/configurator-radiogroup), [Side by side](#/radiogroup/side-by-side), [A row of fields (Sizes)](#/sizes/a-row-of-fields) |
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/radiogroup/configurator-radiogroup), [States](#/radiogroup/states) |
| `disabled` | `boolean` | `false` | Disables the whole group. `RadioOption` disables single possibilities.<br>Shown in: [Configurator](#/radiogroup/configurator-radiogroup), [States](#/radiogroup/states) |
| `name` | `string` | a generated one | Name of the radio group within the form. |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` | `(value: T) => void` | — | Runs on every choice – on the one made with the arrow keys as well.<br>Shown in: [Radio group](#/radiogroup/radio-group), [Descriptions](#/radiogroup/descriptions), [Side by side](#/radiogroup/side-by-side) and 2 more |

Also takes every attribute of `<div>` – without `defaultValue`, `onChange`.

##### `RadioOption<T extends string>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `T` | — | What comes back when this possibility is chosen.<br>Shown in: [Radio group](#/radiogroup/radio-group), [Descriptions](#/radiogroup/descriptions), [Side by side](#/radiogroup/side-by-side) and 3 more |
| `label` *required* | `ReactNode` | — | What stands beside it.<br>Shown in: [Radio group](#/radiogroup/radio-group), [Descriptions](#/radiogroup/descriptions), [Side by side](#/radiogroup/side-by-side) and 3 more |
| `description` | `ReactNode` | — | Line of explanation under the label; it is read out as well.<br>Shown in: [Descriptions](#/radiogroup/descriptions), [Approve spending against a budget (Scenarios)](#/scenarios/approve-spending), [Set up a team (Scenarios)](#/scenarios/set-up-a-team) |
| `disabled` | `boolean` | — | Takes the possibility out of the choice but leaves it visible: a choice that does not exist is a different statement from one that may not be made.<br>Shown in: [Descriptions](#/radiogroup/descriptions), [Approve spending against a budget (Scenarios)](#/scenarios/approve-spending) |

### SegmentedControl

One choice out of a few short possibilities, drawn as one control with a segment for each (segmented button, button toggle): a sunken track, the choice lifted out of it. As tall as a select, so it stands in a row of fields too.

```ts
import { SegmentedControl } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/segmentedcontrol/

A screen reader hears a radio group, each segment a radio with its position and whether it is chosen; the control is one tab stop, and the arrow keys move and choose at once, skipping disabled possibilities.

Each segment is as wide as its word, and the width never follows the choice. `fill` takes the width of the place instead and shares it equally; an option's `icon` stands before its word.

Two drawings: `inset`, the default - a sunken track with the choice lifted out of it; and `field` - a field's edge, the choice filled with ink, for a row whose fields it should match box for box. Both are a control's height with their words on a select's line, and the keys are the same.

#### Examples

##### Segmented control

Pass `options`, `value` and `onChange`; `value` is `null` until something is chosen.

```tsx
import { useState } from "react";
import { SegmentedControl, Text, Stack } from "@umriss-ui/core";

export default function SegmentedControlExample() {
  const [period, setPeriod] = useState<"hour" | "day" | "week" | null>("day");

  return (
    <Stack gap={3} align="flex-start">
      <SegmentedControl
        aria-label="Period"
        value={period}
        onChange={setPeriod}
        options={[
          { value: "hour", label: "Hour" },
          { value: "day", label: "Day" },
          { value: "week", label: "Week" },
        ]}
      />
      <Text size="xs" tone="muted" mono>
        period: {period ?? "none"}
      </Text>
    </Stack>
  );
}
```

##### In a field

Inside a `FormField` the control is named by the field's label and takes its hint or error, required and invalid state by itself.

```tsx
import { useState } from "react";
import { FormField, SegmentedControl } from "@umriss-ui/core";

export default function InAField() {
  const [state, setState] = useState<"raw" | "cleaned">("raw");

  return (
    <FormField
      label="State of the data"
      required
      error={state === "raw" ? "A report is drawn from cleaned data." : undefined}
    >
      <SegmentedControl
        value={state}
        onChange={setState}
        options={[
          { value: "raw", label: "Raw data" },
          { value: "cleaned", label: "Cleaned data" },
        ]}
      />
    </FormField>
  );
}
```

##### States and sizes

`size` is `md` or `sm`; a `ControlSizeProvider` sets it for a place. `disabled` closes the whole control, `disabled` on an option closes that possibility and leaves it in view - the arrow keys skip it.

```tsx
import { FormField, SegmentedControl, Stack } from "@umriss-ui/core";

const PERIODS = [
  { value: "hour", label: "Hour" },
  { value: "day", label: "Day" },
  { value: "week", label: "Week" },
] as const;

export default function StatesAndSizes() {
  return (
    <Stack direction="row" gap={5} wrap>
      <FormField label="Medium">
        <SegmentedControl defaultValue="day" options={PERIODS} />
      </FormField>
      <FormField label="Small">
        <SegmentedControl size="sm" defaultValue="day" options={PERIODS} />
      </FormField>
      <FormField label="Disabled">
        <SegmentedControl disabled defaultValue="day" options={PERIODS} />
      </FormField>
      <FormField label="One possibility closed" hint="No forecast for this line yet.">
        <SegmentedControl
          defaultValue="measured"
          options={[
            { value: "measured", label: "Measured" },
            { value: "forecast", label: "Forecast", disabled: true },
          ]}
        />
      </FormField>
    </Stack>
  );
}
```

##### Long words in a narrow place

The control is as wide as its words and never wider than its place: on a phone, words that do not fit end in an ellipsis. Short words are the form's strength - past three or four of them, a Select is the better choice.

```tsx
import { FormField, SegmentedControl } from "@umriss-ui/core";

export default function LongWordsInANarrowPlace() {
  return (
    <FormField label="Readings">
      <SegmentedControl
        defaultValue="raw"
        options={[
          { value: "raw", label: "Raw readings from the sensors" },
          { value: "cleaned", label: "Cleaned and validated readings" },
        ]}
      />
    </FormField>
  );
}
```

##### A theme switch

A choice that stands on its own, in a menu or a settings panel. `fill` takes the panel's width and shares it equally between the segments; an option's `icon` stands before its word, at the size the control gives it.

```tsx
import { Card, CardBody, FormField, SegmentedControl } from "@umriss-ui/core";

/* Icons from outside the set: any SVG, sized by the control. */
const stroke = { fill: "none", stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", strokeLinejoin: "round" } as const;

function Sun() {
  return (
    <svg viewBox="0 0 24 24" {...stroke}>
      <circle cx="12" cy="12" r="4" />
      <path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" />
    </svg>
  );
}

function Moon() {
  return (
    <svg viewBox="0 0 24 24" {...stroke}>
      <path d="M20 14.5A8 8 0 1 1 9.5 4a6.5 6.5 0 0 0 10.5 10.5z" />
    </svg>
  );
}

function Monitor() {
  return (
    <svg viewBox="0 0 24 24" {...stroke}>
      <rect x="3" y="4" width="18" height="12" rx="2" />
      <path d="M8 20h8M12 16v4" />
    </svg>
  );
}

export default function ThemeSwitch() {
  return (
    <Card style={{ maxWidth: 320 }}>
      <CardBody>
        <FormField label="Theme">
          <SegmentedControl
            fill
            defaultValue="system"
            options={[
              { value: "light", label: "Light", icon: <Sun /> },
              { value: "dark", label: "Dark", icon: <Moon /> },
              { value: "system", label: "System", icon: <Monitor /> },
            ]}
          />
        </FormField>
      </CardBody>
    </Card>
  );
}
```

##### Drawn as a field

`variant="field"` gives it a field's edge and fills the choice with ink, for a row whose fields it should match box for box. Inset or a field, it is a control's height and its words stand on the select's line - at either size.

```tsx
import { ControlSizeProvider, FormField, SegmentedControl, Select, Stack } from "@umriss-ui/core";
import type { ControlSize } from "@umriss-ui/core";

function Row({ size }: { size: ControlSize }) {
  return (
    <Stack role="group" aria-label={size === "sm" ? "Small" : "Medium"} direction="row" gap={3} wrap>
      <FormField label="Caster">
        <Select defaultValue="">
          <option value="">Every caster</option>
          <option>Caster 1</option>
        </Select>
      </FormField>
      <FormField label="Values">
        <SegmentedControl
          variant="field"
          defaultValue="measured"
          options={[
            { value: "measured", label: "Measured" },
            { value: "forecast", label: "Forecast" },
          ]}
        />
      </FormField>
    </Stack>
  );
}

export default function DrawnAsAField() {
  return (
    <Stack gap={5}>
      <Row size="md" />
      <ControlSizeProvider size="sm">
        <Row size="sm" />
      </ControlSizeProvider>
    </Stack>
  );
}
```

#### When to use something else

- Possibilities that need a line of explanation each → RadioGroup
- More than about four possibilities, or long ones → Select
- A single yes or no → Switch

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Moves into the control, onto the chosen segment, and out again. |
| `Arrow Right / Arrow Down` | Chooses the next segment, wrapping at the end. |
| `Arrow Left / Arrow Up` | Chooses the previous segment. |

#### API

##### `SegmentedControlProps<T extends string>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `options` *required* | `readonly `[`SegmentedOption`](#type-SegmentedOption)`<T>[]` | — | The possibilities, two to four, in the order in which they stand.<br>Shown in: [Configurator](#/segmentedcontrol/configurator-segmentedcontrol), [Segmented control](#/segmentedcontrol/segmented-control), [In a field](#/segmentedcontrol/in-a-field) and 5 more |
| `defaultValue` | `T \| null` | — | Initial value of an uncontrolled control. Not together with `value`.<br>Shown in: [Configurator](#/segmentedcontrol/configurator-segmentedcontrol), [States and sizes](#/segmentedcontrol/states-and-sizes), [Long words in a narrow place](#/segmentedcontrol/long-words-in-a-narrow-place) and 3 more |
| `value` | `T \| null` | — | The chosen possibility; `null` means: none yet. Together with `onChange` the control is controlled.<br>Shown in: [Segmented control](#/segmentedcontrol/segmented-control), [In a field](#/segmentedcontrol/in-a-field) |
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/segmentedcontrol/configurator-segmentedcontrol), [States and sizes](#/segmentedcontrol/states-and-sizes) |
| `variant` | `"field" \| "inset"` | `"inset"` | How it is drawn. `inset`: a sunken track without an edge, the choice a surface lifted out of it. `field`: a field's edge, the choice filled with ink - for a row whose fields it should match box for box.<br>Shown in: [Configurator](#/segmentedcontrol/configurator-segmentedcontrol), [Drawn as a field](#/segmentedcontrol/drawn-as-a-field) |
| `fill` | `boolean` | `false` | Takes the whole width its place gives it, as a field in a column does, and shares it equally between the segments. Without it the control is as wide as its words.<br>Shown in: [Configurator](#/segmentedcontrol/configurator-segmentedcontrol), [A theme switch](#/segmentedcontrol/a-theme-switch) |
| `disabled` | `boolean` | `false` | Disables the whole control. `SegmentedOption` disables single possibilities.<br>Shown in: [Configurator](#/segmentedcontrol/configurator-segmentedcontrol), [States and sizes](#/segmentedcontrol/states-and-sizes) |
| `name` | `string` | a generated one | Name of the radio group within the form. |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` | `(value: T) => void` | — | Runs on every choice – on the one made with the arrow keys as well.<br>Shown in: [Segmented control](#/segmentedcontrol/segmented-control), [In a field](#/segmentedcontrol/in-a-field) |

Also takes every attribute of `<div>` – without `defaultValue`, `onChange`.

##### `SegmentedOption<T extends string>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `T` | — | What comes back when this possibility is chosen.<br>Shown in: [Segmented control](#/segmentedcontrol/segmented-control), [In a field](#/segmentedcontrol/in-a-field), [States and sizes](#/segmentedcontrol/states-and-sizes) and 4 more |
| `label` *required* | `ReactNode` | — | The segment's word - a short one; a long label ends in an ellipsis.<br>Shown in: [Segmented control](#/segmentedcontrol/segmented-control), [In a field](#/segmentedcontrol/in-a-field), [States and sizes](#/segmentedcontrol/states-and-sizes) and 4 more |
| `icon` | `ReactNode` | — | An icon before the word: an SVG, a glyph of the set or an icon font's element. The control sets its size - `--u-icon-size`, `--u-icon-size-sm` at `sm` - and hides it from assistive technology: the word names the possibility.<br>Shown in: [A theme switch](#/segmentedcontrol/a-theme-switch) |
| `disabled` | `boolean` | — | Takes the possibility out of the choice but leaves it visible.<br>Shown in: [States and sizes](#/segmentedcontrol/states-and-sizes) |

#### Known limits

- Two to four short possibilities: a word that does not fit its place ends in an ellipsis.
- No icons and no line of explanation in a segment; several chosen at once is not this control.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### FileInput

Choose files from the system's dialog or drop them on the zone (file picker, upload field). The chosen files are listed with their size and can be removed one by one.

```ts
import { FileInput } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/fileinput/

`accept` holds for the dialog and for a drop alike; a dropped file it refuses is named below the list instead of vanishing.

It only chooses. Reading, checking and uploading the files are the application's.

#### Examples

##### One file

Set `accept` for the types you take; it holds for the system's dialog and for a file dropped on the zone.

```tsx
import { FileInput, FormField } from "@umriss-ui/core";

export default function OneFile() {
  return (
    <FormField label="Bank statement" hint="The CSV export from online banking." style={{ maxWidth: 420 }}>
      <FileInput accept=".csv" />
    </FormField>
  );
}
```

##### Several files

Set `multiple` to take several at once; pass `value` to start from files a record already carries.

```tsx
import { useState } from "react";
import { FileInput, FormField, Grid } from "@umriss-ui/core";

const ATTACHED = [
  new File([new Uint8Array(184_000)], "damaged-corner.jpg", { type: "image/jpeg" }),
  new File([new Uint8Array(1_320_000)], "delivery-note-100829-signed-by-the-consignee-at-the-rear-entrance.pdf", {
    type: "application/pdf",
  }),
];

export default function SeveralFiles() {
  const [attached, setAttached] = useState<File[]>(ATTACHED);

  return (
    <Grid minItemWidth="300px" gap={6}>
      <FormField label="Proof of delivery" hint="Photos or PDF.">
        <FileInput multiple accept="image/*,.pdf" />
      </FormField>
      <FormField label="Attachments" hint="Shipment 100829, failed attempt.">
        <FileInput multiple accept="image/*,.pdf" value={attached} onChange={setAttached} />
      </FormField>
    </Grid>
  );
}
```

##### States

An `error` on the `FormField` colours the zone and is read as its description; `disabled` takes neither dialog nor drop.

```tsx
import { FileInput, FormField, Grid } from "@umriss-ui/core";

export default function States() {
  return (
    <Grid minItemWidth="280px" gap={6}>
      <FormField label="Postmortem" error="Attach the postmortem before closing INC-1048.">
        <FileInput accept=".pdf,.md" />
      </FormField>
      <FormField label="Runbook" hint="Locked while the incident is open.">
        <FileInput accept=".pdf,.md" disabled />
      </FormField>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the zone invalid by itself. Without one, set `invalid` and tie your message to the input with `aria-describedby`.

```tsx
import { useId, useState } from "react";
import { FileInput, Stack, Text } from "@umriss-ui/core";

export default function WithAnError() {
  const [files, setFiles] = useState<File[]>([]);
  const messageId = useId();
  const error = files.length === 0 ? "Attach the postmortem before closing INC-1048." : undefined;

  return (
    <Stack gap={1} style={{ maxWidth: 420 }}>
      <FileInput
        aria-label="Postmortem"
        accept=".pdf,.md"
        value={files}
        onChange={setFiles}
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
      />
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

##### Require a file before sending

Hold the files with `value` and `onChange`, and turn an empty choice into the field's error on submit.

```tsx
import { useState } from "react";
import type { FormEvent } from "react";
import { Button, FileInput, FormField, Stack, Text } from "@umriss-ui/core";

export default function RequireAFileBeforeSending() {
  const [files, setFiles] = useState<File[]>([]);
  const [tried, setTried] = useState(false);
  const [sent, setSent] = useState<string | null>(null);

  const send = (event: FormEvent) => {
    event.preventDefault();
    setTried(true);
    if (files.length === 0) return;
    setSent(files.map((f) => f.name).join(", "));
  };

  return (
    <form onSubmit={send} noValidate style={{ maxWidth: 420 }}>
      <Stack gap={3}>
        <FormField label="Receipts" required error={tried && files.length === 0 ? "Attach at least one receipt." : undefined}>
          <FileInput multiple accept=".pdf,image/*" value={files} onChange={setFiles} name="receipts" />
        </FormField>
        <Stack direction="row" gap={3} align="center">
          <Button type="submit" size="sm" variant="primary">
            Submit expenses
          </Button>
          {sent && (
            <Text size="sm" tone="muted">
              Would send: {sent}
            </Text>
          )}
        </Stack>
      </Stack>
    </form>
  );
}
```

##### Import budgets

The input only chooses; reading the file with `File.text()`, checking it and importing it stay with your application.

```tsx
import { useState } from "react";
import { Alert, Button, Card, CardBody, CardHeader, FileInput, FormField, Stack, Stepper, Text } from "@umriss-ui/core";

interface Reading {
  name: string;
  rows: number;
}

export default function ImportBudgets() {
  const [files, setFiles] = useState<File[]>([]);
  const [reading, setReading] = useState<Reading | null>(null);
  const [imported, setImported] = useState(false);

  const choose = async (next: File[]) => {
    setFiles(next);
    setImported(false);
    const file = next[0];
    if (!file) return setReading(null);
    const lines = (await file.text()).split(/\r?\n/).filter((line) => line.trim() !== "");
    setReading({ name: file.name, rows: Math.max(0, lines.length - 1) }); // the first line is the head
  };

  const current = imported ? 3 : reading ? 1 : 0;
  const count = (rows: number) => (rows === 1 ? "1 cost centre" : `${rows} cost centres`);

  return (
    <Card style={{ maxWidth: 560 }}>
      <CardHeader eyebrow="Budget 2027" title="Import budgets" />
      <CardBody>
        <Stack gap={5}>
          <Stepper aria-label="Import" steps={[{ label: "Choose file" }, { label: "Check" }, { label: "Import" }]} current={current} />
          <FormField label="Budget sheet" hint="CSV, one cost centre per row, with a head line.">
            <FileInput accept=".csv" value={files} onChange={(next) => void choose(next)} />
          </FormField>
          {reading && !imported && (
            <Stack direction="row" gap={3} align="center">
              <Text size="sm">
                {count(reading.rows)} in {reading.name}
              </Text>
              <Button size="sm" variant="primary" disabled={reading.rows === 0} onClick={() => setImported(true)}>
                Import
              </Button>
            </Stack>
          )}
          {imported && reading && (
            <Alert tone="success" title="Imported">
              {count(reading.rows)} from {reading.name} now carry a 2027 budget.
            </Alert>
          )}
        </Stack>
      </CardBody>
    </Card>
  );
}
```

#### Keyboard

| Key | Action |
|---|---|
| `Space or Enter` | Opens the system's file dialog. |

#### API

##### `FileInputProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `readonly File[]` | — | Controlled: the chosen files. Uncontrolled, the input keeps its own and starts empty.<br>Shown in: [Several files](#/fileinput/several-files), [With an error](#/fileinput/with-an-error), [Require a file before sending](#/fileinput/require-a-file-before-sending) and 1 more |
| `invalid` | `boolean` | — | Marks the input as invalid. `FormField` sets it itself as soon as it carries an `error` - by hand only necessary without `FormField`.<br>Shown in: [With an error](#/fileinput/with-an-error) |
| `ref` | `Ref<HTMLInputElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` | `(files: File[]) => void` | — | Reports the files after a choice, a drop or a removal - only those `accept` takes, and one where the input takes one.<br>Shown in: [Several files](#/fileinput/several-files), [With an error](#/fileinput/with-an-error), [Require a file before sending](#/fileinput/require-a-file-before-sending) and 1 more |

Also takes every attribute of `<input>` – without `defaultValue`, `onChange`, `size`, `type`, `value`.

#### Known limits

- No upload, no progress and no size limit of its own; those belong to the application sending the files.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

## Choosing

Where a user chooses one value or several from a list that opens.

### Select

One choice from a short, known list (dropdown). Under a mouse and the keys it opens the Combobox's list; under a finger the system's picker, a wheel on the phone.

```ts
import { Select } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/select/

The field is a native `<select>`: it holds the value and the form, and `onChange` fires as it always did. Write the choices as `<option>` and `<optgroup>`; the list is drawn from them.

An option with the empty value is the placeholder: muted in the field, and never marked as the choice in the list.

#### Examples

##### Select

Write the choices as native `option` elements; a disabled empty option stands in for the placeholder.

```tsx
import { useState } from "react";
import { FormField, Select } from "@umriss-ui/core";

export default function SelectExample() {
  const [centre, setCentre] = useState("");

  return (
    <FormField label="Cost centre" style={{ maxWidth: 320 }}>
      <Select value={centre} onChange={(event) => setCentre(event.target.value)}>
        <option value="" disabled>
          Choose a cost centre
        </option>
        <option value="CC-1100">CC-1100 Sales</option>
        <option value="CC-1200">CC-1200 Marketing</option>
        <option value="CC-2100">CC-2100 Engineering</option>
        <option value="CC-2200">CC-2200 Design</option>
        <option value="CC-3100">CC-3100 Customer service</option>
      </Select>
    </FormField>
  );
}
```

##### States

`size="sm"` suits dense forms; errors come from the `FormField`, and a long option is cut at the field's edge.

```tsx
import { FormField, Grid, Select } from "@umriss-ui/core";

export default function States() {
  return (
    <Grid minItemWidth="220px" gap={4}>
      <FormField label="Month" hint="Small size.">
        <Select size="sm" defaultValue="2026-03">
          <option value="2026-01">January 2026</option>
          <option value="2026-02">February 2026</option>
          <option value="2026-03">March 2026</option>
        </Select>
      </FormField>
      <FormField label="VAT rate" error="Invoices from abroad are booked with reverse charge.">
        <Select defaultValue="19">
          <option value="19">19 %</option>
          <option value="7">7 %</option>
          <option value="0">Reverse charge</option>
        </Select>
      </FormField>
      <FormField label="Approver" hint="Set by the cost centre.">
        <Select disabled defaultValue="rafael">
          <option value="rafael">Rafael Ortiz</option>
        </Select>
      </FormField>
      <FormField label="Booking text">
        <Select defaultValue="long">
          <option value="long">Accrual for the annual audit fee, split over twelve months and released in December</option>
          <option value="short">Audit fee</option>
        </Select>
      </FormField>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the field invalid by itself. Without one, set `invalid` and tie your message to the field with `aria-describedby`.

```tsx
import { useId, useState } from "react";
import { Select, Stack, Text } from "@umriss-ui/core";

export default function WithAnError() {
  /* The supplier invoices from Austria, so only reverse charge is right. */
  const [rate, setRate] = useState("19");
  const messageId = useId();
  const error = rate === "0" ? undefined : "Invoices from abroad are booked with reverse charge.";

  return (
    <Stack gap={1} style={{ maxWidth: 360 }}>
      <Select
        aria-label="VAT rate, Alpenholz GmbH (Austria)"
        value={rate}
        onChange={(event) => setRate(event.target.value)}
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
      >
        <option value="19">19 %</option>
        <option value="7">7 %</option>
        <option value="0">Reverse charge</option>
      </Select>
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

##### Clear the choice

For an optional choice set `clearable` with `onClear`; the cross appears once something is chosen.

```tsx
import { useState } from "react";
import { FormField, Select, Stack, Text } from "@umriss-ui/core";

export default function ClearTheChoice() {
  const [owner, setOwner] = useState("helen");

  return (
    <Stack gap={3} style={{ maxWidth: 320 }}>
      <FormField label="Filter by budget owner">
        <Select clearable value={owner} onChange={(event) => setOwner(event.target.value)} onClear={() => setOwner("")}>
          <option value="" disabled>
            All owners
          </option>
          <option value="helen">Helen Marsh</option>
          <option value="rafael">Rafael Ortiz</option>
          <option value="anika">Anika Sørensen</option>
        </Select>
      </FormField>
      <Text size="xs" tone="muted" mono>
        value: "{owner}"
      </Text>
    </Stack>
  );
}
```

#### When to use something else

- A long list that is searched by typing → Combobox
- Several values at once → MultiSelect
- A few options that should all stay in view or need a sentence each → RadioGroup

#### Keyboard

| Key | Action |
|---|---|
| `Arrow Down / Arrow Up, Space, Alt + Arrow, F4` | Opens the list on the chosen option. Enter in a closed field is passed on, to a form or a grid. |
| `Arrow Up / Arrow Down, Home / End, Page Up / Page Down` | Moves in the open list. |
| `Typing a letter` | Jumps to the next option starting with it; in a closed field it changes the choice. |
| `Enter or Space` | Chooses the option the list stands on. |
| `Escape or Tab` | Closes the list. |

#### API

##### `SelectProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/select/configurator-select), [States](#/select/states), [Build a filter bar (Tag)](#/tag/a-filter-bar) and 1 more |
| `chars` | `number` | — | The width in characters - room for the chosen option; the field adds its own padding, chevron and cross. Given, the field is that wide wherever it stands, and never wider than its place. Without it the field fills its place, and is 20 characters wide where the place asks - never as wide as its longest option.<br>Shown in: [Configurator](#/select/configurator-select), [A row of fields (Sizes)](#/sizes/a-row-of-fields) |
| `invalid` | `boolean` | — | Marks the field as invalid. `FormField` sets it itself as soon as it carries an `error` – by hand only necessary without `FormField`.<br>Shown in: [Configurator](#/select/configurator-select), [With an error](#/select/with-an-error) |
| `clearable` | `boolean` | `false` | Shows a × once a selection has been made, which fades in on hover/focus and empties the selection. Requires a controlled field (value) and onClear; sensible for optional selects with a placeholder option.<br>Shown in: [Clear the choice](#/select/clear-the-choice) |
| `ref` | `Ref<HTMLSelectElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onClear` | `() => void` | — | Called by the ×; resets the selection to the placeholder option.<br>Shown in: [Clear the choice](#/select/clear-the-choice) |

Also takes every attribute of `<select>` – without `size`.

#### Known limits

- The list shows the options' text: no icons, descriptions or search inside it - the Combobox searches.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Combobox

One choice from a long list, found by typing (autocomplete, typeahead, searchable select): a driver, a service, an account. The list filters along while the value stays exactly one.

```ts
import { Combobox } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/combobox/

What is typed is a search term, not a value: the value changes only when a row is chosen or the field is cleared, and it is one option or `null`.

The list keeps its given order while it filters; sort the options before you pass them if you want an order.

#### Examples

##### Combobox

Typing filters the `options`; `onChange` runs only when a row is chosen or cleared, with one value or `null`.

```tsx
import { useState } from "react";
import { Combobox, FormField, Stack, Text } from "@umriss-ui/core";

const DRIVERS = [
  { value: "d1", label: "Martin Hale" },
  { value: "d2", label: "Nadia Petrova" },
  { value: "d3", label: "Owen Carter" },
  { value: "d4", label: "Lucia Romero" },
  { value: "d5", label: "Ben Adeyemi" },
  { value: "d6", label: "Hanna Berg" },
  { value: "d7", label: "Yusuf Demir" },
  { value: "d8", label: "Clara Wendt" },
];

export default function PickADriver() {
  const [driver, setDriver] = useState<string | null>(null);

  return (
    <Stack gap={3} style={{ maxWidth: 320 }}>
      <FormField label="Driver, tour T-04">
        <Combobox value={driver} onChange={setDriver} clearable options={DRIVERS} placeholder="Type a name" />
      </FormField>
      <Text size="xs" tone="muted" mono>
        value: {driver === null ? "null" : `"${driver}"`}
      </Text>
    </Stack>
  );
}
```

##### States

Set `emptyText` for a search that finds nothing; errors come from the `FormField`, and a `disabled` row stays in the list.

```tsx
import { Combobox, FormField, Grid, type ComboboxOption } from "@umriss-ui/core";

const VEHICLES: ComboboxOption[] = [
  { value: "v1", label: "FP 214 K, van, North depot" },
  { value: "v2", label: "FP 377 K, e-van, North depot" },
  { value: "v3", label: "FP 118 R, truck, North depot, in the workshop until Thursday", disabled: true },
  { value: "v4", label: "FP 402 R, van, Riverside depot" },
];

export default function States() {
  return (
    <Grid minItemWidth="240px" gap={4}>
      <FormField label="Vehicle" hint="Type “zz” to see the empty result.">
        <Combobox value={null} onChange={() => {}} options={VEHICLES} emptyText="No vehicle matches. Check the plate." />
      </FormField>
      <FormField label="Vehicle" error="Tour T-04 needs a vehicle before it can be released.">
        <Combobox value={null} onChange={() => {}} options={VEHICLES} placeholder="Choose a vehicle" />
      </FormField>
      <FormField label="Vehicle" hint="The tour is on the road.">
        <Combobox value="v2" onChange={() => {}} options={VEHICLES} disabled />
      </FormField>
      <FormField label="Vehicle" hint="A long label is cut at the field's edge.">
        <Combobox value="v3" onChange={() => {}} options={VEHICLES} />
      </FormField>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the field invalid by itself. Without one, set `invalid` and tie your message to the field with `aria-describedby`.

```tsx
import { useId, useState } from "react";
import { Combobox, Stack, Text } from "@umriss-ui/core";

const VEHICLES = [
  { value: "v1", label: "FP 214 K, van, North depot" },
  { value: "v2", label: "FP 377 K, e-van, North depot" },
  { value: "v4", label: "FP 402 R, van, Riverside depot" },
];

export default function WithAnError() {
  const [vehicle, setVehicle] = useState<string | null>(null);
  const messageId = useId();
  const error = vehicle === null ? "Tour T-04 needs a vehicle before it can be released." : undefined;

  return (
    <Stack gap={1} style={{ maxWidth: 360 }}>
      <Combobox
        aria-label="Vehicle"
        value={vehicle}
        onChange={setVehicle}
        options={VEHICLES}
        placeholder="Choose a vehicle"
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
      />
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

##### Assign an incident

Build `options` from your records, with the team in the label so typing finds either; one choice decides the next.

```tsx
import { useState } from "react";
import { Button, Card, CardBody, CardHeader, Combobox, FormField, Stack } from "@umriss-ui/core";

/* Data from the operations world, written out here so the example runs on its own. */
interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface Engineer {
  id: string;
  name: string;
  team: string;
}

const ENGINEERS: readonly Engineer[] = [
  { id: "priya", name: "Priya Raman", team: "Payments" },
  { id: "jonas", name: "Jonas Keller", team: "Payments" },
  { id: "ada", name: "Ada Mwangi", team: "Identity" },
  { id: "tomasz", name: "Tomasz Nowak", team: "Discovery" },
  { id: "leila", name: "Leila Haddad", team: "Discovery" },
  { id: "sam", name: "Sam Okafor", team: "Messaging" },
  { id: "ines", name: "Ines Duarte", team: "Integrations" },
  { id: "felix", name: "Felix Brandt", team: "Insights" },
];

export default function AssignAnIncident() {
  const [service, setService] = useState<string | null>("checkout");
  const [owner, setOwner] = useState<string | null>(null);
  const team = SERVICES.find((s) => s.id === service)?.team;

  return (
    <Card style={{ maxWidth: 480 }}>
      <CardHeader eyebrow="INC-1049 · SEV2" title="Assign the incident" />
      <CardBody>
        <Stack gap={4}>
          <FormField label="Service">
            <Combobox
              value={service}
              onChange={(next) => {
                setService(next);
                setOwner(null);
              }}
              options={SERVICES.map((s) => ({ value: s.id, label: `${s.name} · ${s.team}` }))}
            />
          </FormField>
          <FormField label="Incident lead" hint={team ? `Engineers of ${team} first.` : undefined}>
            <Combobox
              value={owner}
              onChange={setOwner}
              clearable
              placeholder="Type a name or team"
              options={[...ENGINEERS]
                .sort((a, b) => Number(b.team === team) - Number(a.team === team))
                .map((e) => ({ value: e.id, label: `${e.name} · ${e.team}` }))}
            />
          </FormField>
          <Button variant="primary" size="sm" disabled={owner === null} style={{ alignSelf: "flex-start" }}>
            Assign
          </Button>
        </Stack>
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- A short list that needs no search, with the system's picker under a finger → Select
- Several values at once → MultiSelect

#### Keyboard

| Key | Action |
|---|---|
| `Arrow Down / Arrow Up` | Opens the list, then moves through the rows. |
| `Enter` | Chooses the active row. |
| `Escape` | Closes the list. |

#### API

##### `ComboboxProps<T extends string = string>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `options` *required* | `readonly `[`ComboboxOption`](#type-ComboboxOption)`<T>[]` | — | The possibilities, in their natural order. Filtered while typing; never reordered.<br>Shown in: [Configurator](#/combobox/configurator-combobox), [Combobox](#/combobox/pick-a-driver), [States](#/combobox/states) and 5 more |
| `value` *required* | `T \| null` | — | The chosen value; `null` means none. Always controlled - the field keeps no second state beside the caller's.<br>Shown in: [Configurator](#/combobox/configurator-combobox), [Combobox](#/combobox/pick-a-driver), [States](#/combobox/states) and 5 more |
| `placeholder` | `string` | — | What stands in the empty field.<br>Shown in: [Combobox](#/combobox/pick-a-driver), [States](#/combobox/states), [With an error](#/combobox/with-an-error) and 3 more |
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/combobox/configurator-combobox) |
| `chars` | `number` | — | The width in characters - room for the typed text and the chosen option; the field adds its own padding, chevron and cross. Given, the field is that wide wherever it stands, and never wider than its place. Without it the field fills its place, and is 20 characters wide where the place asks - in a toolbar or a row. The panel is never narrower than the field.<br>Shown in: [Configurator](#/combobox/configurator-combobox) |
| `disabled` | `boolean` | `false` | Locks field and panel.<br>Shown in: [Configurator](#/combobox/configurator-combobox), [States](#/combobox/states), [Dispatch a tour (Scenarios)](#/scenarios/dispatch-a-tour) |
| `invalid` | `boolean` | — | Marks the field as invalid. `FormField` sets it itself as soon as it carries an `error` - by hand only necessary without `FormField`.<br>Shown in: [Configurator](#/combobox/configurator-combobox), [With an error](#/combobox/with-an-error) |
| `emptyText` | `string` | — | Text shown for an empty search result.<br>Shown in: [States](#/combobox/states) |
| `clearable` | `boolean` | `false` | Shows a cross on selection or input that clears field and selection.<br>Shown in: [Configurator](#/combobox/configurator-combobox), [Combobox](#/combobox/pick-a-driver), [Assign an incident](#/combobox/assign-an-incident) and 2 more |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` *required* | `(value: T \| null) => void` | — | Runs on choosing and on clearing (`null`). Not while typing: what is typed is a search term and not yet a value.<br>Shown in: [Configurator](#/combobox/configurator-combobox), [Combobox](#/combobox/pick-a-driver), [States](#/combobox/states) and 5 more |

Also takes every attribute of `<div>` – without `defaultValue`, `onChange`.

##### `ComboboxOption<T extends string = string>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `T` | — | What comes back when this row is chosen.<br>Shown in: [States](#/combobox/states), [Assign an incident](#/combobox/assign-an-incident), [Dispatch a tour (Scenarios)](#/scenarios/dispatch-a-tour) and 1 more |
| `label` *required* | `string` | — | What stands there - and what is filtered on. Text and not a node: what cannot be searched is something nobody finds in a combobox.<br>Shown in: [States](#/combobox/states), [Assign an incident](#/combobox/assign-an-incident), [Dispatch a tour (Scenarios)](#/scenarios/dispatch-a-tour) and 1 more |
| `disabled` | `boolean` | — | Shows the row but does not let it be chosen.<br>Shown in: [States](#/combobox/states) |

#### Known limits

- No free text as a value: only an option can be chosen.
- No loading of options from a server; filter your own list and pass it in.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### MultiSelect

Several values from a list (multi-select, tag picker): a project team, services to filter by. The chosen ones stand as chips in the field, with a view in the panel that shows only them.

```ts
import { MultiSelect } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/multiselect/

The field stays one line tall: as many chips as fit, the rest as a “+N” button that opens the panel on the chosen values.

Choosing never moves it: it fills its place, or in a row stands at twenty characters, or at its `chars`, and the chips follow its width ([Sizes](#/sizes)).

The panel has a search, select all, select none and invert for what the search found, and it never reorders the list.

#### Examples

##### Chips in the field

The chosen values stand as chips; what does not fit becomes a “+N” button that opens the chosen view.

```tsx
import { useState } from "react";
import { FormField, MultiSelect, Stack, Text } from "@umriss-ui/core";

const PEOPLE = [
  { value: "maya", label: "Maya Lindgren" },
  { value: "arjun", label: "Arjun Mehta" },
  { value: "chloe", label: "Chloe Durand" },
  { value: "noah", label: "Noah Fischer" },
  { value: "eva", label: "Eva Novak" },
  { value: "luis", label: "Luis Moreno" },
  { value: "hana", label: "Hana Sato" },
  { value: "kofi", label: "Kofi Mensah" },
];

export default function ChipsInTheField() {
  const [team, setTeam] = useState<string[]>(["arjun", "noah", "eva", "hana"]);

  return (
    <Stack gap={3} style={{ maxWidth: 360 }}>
      <FormField label="Project team">
        <MultiSelect value={team} onChange={setTeam} placeholder="Choose people" options={PEOPLE} />
      </FormField>
      <Text size="xs" tone="muted" mono>
        value: [{team.join(", ")}]
      </Text>
    </Stack>
  );
}
```

##### States

Set `emptyText` for a search that finds nothing; errors come from the `FormField`; `disabled` locks the field but keeps what is chosen visible, even on a `disabled` row.

```tsx
import { FormField, Grid, MultiSelect, type MultiSelectOption } from "@umriss-ui/core";

const SKILLS: MultiSelectOption[] = [
  { value: "react", label: "React" },
  { value: "ios", label: "iOS" },
  { value: "android", label: "Android" },
  { value: "design", label: "Interaction design" },
  { value: "a11y", label: "Accessibility audits" },
  { value: "qa", label: "Test automation", disabled: true },
];

export default function States() {
  return (
    <Grid minItemWidth="240px" gap={4}>
      <FormField label="Skills" hint="Search for “zz” to see the empty result.">
        <MultiSelect value={[]} onChange={() => {}} options={SKILLS} placeholder="Choose skills" emptyText="No skill matches. Ask the team lead to add it." />
      </FormField>
      <FormField label="Skills" error="Choose at least one skill for the sprint.">
        <MultiSelect value={[]} onChange={() => {}} options={SKILLS} placeholder="Choose skills" />
      </FormField>
      <FormField label="Skills" hint="Set by the team lead.">
        <MultiSelect value={["react", "qa"]} onChange={() => {}} options={SKILLS} disabled />
      </FormField>
      <FormField label="Skills" hint="More than fits: the rest as +N.">
        <MultiSelect value={["react", "ios", "android", "design", "a11y"]} onChange={() => {}} options={SKILLS} />
      </FormField>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the field invalid by itself. Without one, set `invalid` and tie your message to the field with `aria-describedby`.

```tsx
import { useId, useState } from "react";
import { MultiSelect, Stack, Text } from "@umriss-ui/core";

const SKILLS = [
  { value: "react", label: "React" },
  { value: "ios", label: "iOS" },
  { value: "android", label: "Android" },
  { value: "design", label: "Interaction design" },
];

export default function WithAnError() {
  const [skills, setSkills] = useState<string[]>([]);
  const messageId = useId();
  const error = skills.length === 0 ? "Choose at least one skill for the sprint." : undefined;

  return (
    <Stack gap={1} style={{ maxWidth: 360 }}>
      <MultiSelect
        aria-label="Skills"
        value={skills}
        onChange={setSkills}
        options={SKILLS}
        placeholder="Choose skills"
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
      />
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

##### Filter incidents by service

An empty value means no filter, and the cross takes the field back there in one click; the panel's search, select-all and chosen view help once the list is long.

```tsx
import { useState } from "react";
import { Badge, FormField, MultiSelect, Stack, Text } from "@umriss-ui/core";

/* Data from the operations world, written out here so the example runs on its own. */
const at = (day: number, hours: number, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();

interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface Incident {
  id: string;
  title: string;
  service: string;
  severity: "SEV1" | "SEV2" | "SEV3";
  opened: number;
  acknowledged?: number;
  resolved?: number;
  /** An engineer's id. */
  assignee: string;
}

const INCIDENTS: readonly Incident[] = [
  { id: "INC-1048", title: "Checkout slow, card payments time out", service: "checkout", severity: "SEV1", opened: at(17, 9, 42), acknowledged: at(17, 9, 46), assignee: "jonas" },
  { id: "INC-1047", title: "Webhook deliveries delayed", service: "webhooks", severity: "SEV3", opened: at(17, 7, 15), acknowledged: at(17, 8, 2), assignee: "ines" },
  { id: "INC-1046", title: "Thumbnails missing for new uploads", service: "images", severity: "SEV2", opened: at(16, 22, 5), acknowledged: at(16, 22, 11), resolved: at(17, 0, 40), assignee: "tomasz" },
  { id: "INC-1045", title: "Sign-in codes arrive late", service: "sign-in", severity: "SEV2", opened: at(16, 14, 20), acknowledged: at(16, 14, 24), resolved: at(16, 15, 5), assignee: "ada" },
  { id: "INC-1044", title: "Monthly report export fails", service: "reports", severity: "SEV3", opened: at(15, 10, 0), acknowledged: at(16, 9, 12), resolved: at(16, 11, 30), assignee: "felix" },
  { id: "INC-1043", title: "Search returns no results for some regions", service: "search", severity: "SEV1", opened: at(14, 18, 30), acknowledged: at(14, 18, 33), resolved: at(14, 19, 55), assignee: "leila" },
  { id: "INC-1042", title: "Duplicate reminder e-mails", service: "notifications", severity: "SEV3", opened: at(13, 8, 45), acknowledged: at(13, 9, 30), resolved: at(13, 13, 0), assignee: "sam" },
  { id: "INC-1041", title: "Invoices generated twice", service: "billing", severity: "SEV2", opened: at(12, 16, 10), acknowledged: at(12, 16, 18), resolved: at(12, 18, 40), assignee: "priya" },
];

export default function FilterIncidentsByService() {
  const [services, setServices] = useState<string[]>(["checkout", "billing"]);
  const shown = INCIDENTS.filter((i) => services.length === 0 || services.includes(i.service));

  return (
    <Stack gap={4} style={{ maxWidth: 520 }}>
      <FormField label="Services">
        <MultiSelect
          value={services}
          onChange={setServices}
          placeholder="All services"
          searchPlaceholder="Search services"
          options={SERVICES.map((s) => ({ value: s.id, label: s.name }))}
          clearable
        />
      </FormField>
      <Stack gap={2}>
        {shown.map((incident) => (
          <Stack key={incident.id} direction="row" gap={3} align="center">
            <Badge tone={incident.severity === "SEV1" ? "danger" : "warning"}>{incident.severity}</Badge>
            <Text size="sm" mono style={{ flex: "none" }}>
              {incident.id}
            </Text>
            <Text size="sm">{incident.title}</Text>
          </Stack>
        ))}
        {shown.length === 0 && (
          <Text size="sm" tone="muted">
            No incidents on these services this month.
          </Text>
        )}
      </Stack>
    </Stack>
  );
}
```

#### When to use something else

- Exactly one value → Combobox
- A few options that should all stay in view → Checkbox

#### Keyboard

| Key | Action |
|---|---|
| `Arrow Left / Arrow Right` | Moves across the chips and the “+N” button in the field. |
| `Backspace` | On the field, removes the last chosen value; on a chip, removes that chip (so does Delete). |
| `Arrow Down / Arrow Up` | In the panel, moves between the search and the rows. |
| `Enter` | In the search, ticks or unticks the first row found. |
| `Space` | Ticks or unticks the focused row. |
| `Escape` | Closes the panel. |

#### API

##### `MultiSelectProps<T extends string = string>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `options` *required* | `readonly `[`MultiSelectOption`](#type-MultiSelectOption)`<T>[]` | — | The possibilities, in their natural order. The list never re-sorts – not even in the "selected" scope.<br>Shown in: [Configurator](#/multiselect/configurator-multiselect), [Chips in the field](#/multiselect/chips-in-the-field), [States](#/multiselect/states) and 5 more |
| `value` *required* | `readonly T[]` | — | The chosen values. Always controlled.<br>Shown in: [Configurator](#/multiselect/configurator-multiselect), [Chips in the field](#/multiselect/chips-in-the-field), [States](#/multiselect/states) and 5 more |
| `placeholder` | `string` | — | What stands in the empty field.<br>Shown in: [Chips in the field](#/multiselect/chips-in-the-field), [States](#/multiselect/states), [With an error](#/multiselect/with-an-error) and 3 more |
| `searchPlaceholder` | `string` | — | What stands in the panel's search field.<br>Shown in: [Filter incidents by service](#/multiselect/filter-incidents-by-service) |
| `emptyText` | `string` | — | Text when the search finds nothing.<br>Shown in: [States](#/multiselect/states) |
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/multiselect/configurator-multiselect) |
| `chars` | `number` | — | The width in characters - room for the chips; the field adds its own padding and chevron. Given, the field is that wide wherever it stands, and never wider than its place. Without it the field fills its place, and is 20 characters wide where the place asks - in a toolbar or a row, room for two short chips and the counter. Either way, choosing and removing values never moves it: the chips that do not fit stand as "+N".<br>Shown in: [Configurator](#/multiselect/configurator-multiselect) |
| `disabled` | `boolean` | `false` | Locks field and panel.<br>Shown in: [Configurator](#/multiselect/configurator-multiselect), [States](#/multiselect/states), [Dispatch a tour (Scenarios)](#/scenarios/dispatch-a-tour) |
| `invalid` | `boolean` | — | Marks the field as invalid. `FormField` sets it itself as soon as it carries an `error` – by hand only necessary without `FormField`.<br>Shown in: [Configurator](#/multiselect/configurator-multiselect), [With an error](#/multiselect/with-an-error) |
| `clearable` | `boolean` | `false` | Shows a cross beside the chips that empties the selection, as "Select none" does: a chosen value whose option is disabled stays. The field keeps room for it, chosen values or none, so that it never moves.<br>Shown in: [Configurator](#/multiselect/configurator-multiselect), [Filter incidents by service](#/multiselect/filter-incidents-by-service), [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` *required* | `(value: T[]) => void` | — | Runs on every change of the selection, with the complete new list – not with the one value that moved.<br>Shown in: [Configurator](#/multiselect/configurator-multiselect), [Chips in the field](#/multiselect/chips-in-the-field), [States](#/multiselect/states) and 5 more |

Also takes every attribute of `<div>` – without `defaultValue`, `onChange`.

##### `MultiSelectOption<T extends string = string>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `T` | — | What stands in `value` when this row is ticked.<br>Shown in: [States](#/multiselect/states), [Filter incidents by service](#/multiselect/filter-incidents-by-service), [Dispatch a tour (Scenarios)](#/scenarios/dispatch-a-tour) |
| `label` *required* | `string` | — | What is shown – in the panel and as a chip in the field.<br>Shown in: [States](#/multiselect/states), [Filter incidents by service](#/multiselect/filter-incidents-by-service), [Dispatch a tour (Scenarios)](#/scenarios/dispatch-a-tour) |
| `disabled` | `boolean` | — | Shows the row but does not let it be ticked. A value already chosen stays chosen: disabled means "do not change", not "gone".<br>Shown in: [States](#/multiselect/states) |

## Dates and times

Where a user picks a day, a moment or a span of them from a calendar that opens.

### DatePicker

One day, picked in a calendar (date field): a delivery date, a due date. Weeks begin on Monday.

```ts
import { DatePicker } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/datepicker/

The value contract of the four pickers stands here. `DatePicker` hands out a `Date` at local midnight on every path and reports as soon as the day is chosen. [DateTimePicker](#/datetimepicker) hands out an instant and reports only on Apply, Now or Clear. [DateRangePicker](#/daterangepicker) gives both ends at local midnight, both inclusive. [DateTimeRangePicker](#/datetimerangepicker) sets an all-day end to the end of the day, not to its midnight.

`null` means no date, never 1 January 1970. A range never comes out backwards: ends picked in reverse are swapped, so there is no error state to handle. A time that falls into a clock change is named in the panel, never guessed: a skipped hour moves forward, and a doubled hour asks which of the two.

#### Examples

##### Pick a day

The value is a `Date` at local midnight or `null`; `onChange` runs as soon as a day is chosen.

```tsx
import { useState } from "react";
import { DatePicker, FormField, Stack, Text, useFormats } from "@umriss-ui/core";

export default function PickADay() {
  const formats = useFormats();
  const [delivery, setDelivery] = useState<Date | null>(null);

  return (
    <Stack gap={3} style={{ maxWidth: 320 }}>
      <FormField label="Delivery date">
        <DatePicker value={delivery} onChange={setDelivery} clearable />
      </FormField>
      <Text size="xs" tone="muted" mono>
        value: {delivery === null ? "null" : formats.dateTime(delivery, true)}
      </Text>
    </Stack>
  );
}
```

##### States

`size="sm"` suits dense forms; errors come from the `FormField`, and `disabled` locks field and calendar.

```tsx
import { useState } from "react";
import { DatePicker, FormField, Grid } from "@umriss-ui/core";

export default function States() {
  const [pickUp, setPickUp] = useState<Date | null>(new Date(2026, 2, 18));
  const [delivery, setDelivery] = useState<Date | null>(new Date(2026, 2, 16));

  return (
    <Grid minItemWidth="220px" gap={4}>
      <FormField label="Pick-up" hint="Small size.">
        <DatePicker size="sm" value={pickUp} onChange={setPickUp} clearable />
      </FormField>
      <FormField label="Delivery" error="The delivery date cannot lie before today.">
        <DatePicker value={delivery} onChange={setDelivery} clearable />
      </FormField>
      <FormField label="Delivered on" hint="Set by the driver's scan.">
        <DatePicker value={null} onChange={() => {}} disabled />
      </FormField>
      <FormField label="Return by" hint="Empty, with its own placeholder.">
        <DatePicker value={null} onChange={() => {}} placeholder="No return planned" />
      </FormField>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the field invalid by itself. Without one, set `invalid` and tie your message to the field with `aria-describedby`.

```tsx
import { useId, useState } from "react";
import { DatePicker, Stack, Text } from "@umriss-ui/core";

export default function WithAnError() {
  const [delivery, setDelivery] = useState<Date | null>(new Date(2026, 2, 16));
  const messageId = useId();
  const today = new Date();
  today.setHours(0, 0, 0, 0);
  const error = delivery !== null && delivery < today ? "The delivery date cannot lie before today." : undefined;

  return (
    <Stack gap={1} style={{ maxWidth: 280 }}>
      <DatePicker
        aria-label="Delivery"
        value={delivery}
        onChange={setDelivery}
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
      />
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

##### Check a due date

Compare two pickers' values as plain dates, since both lie at local midnight, and put the result in the `FormField`.

```tsx
import { useState } from "react";
import { DatePicker, FormField, Grid } from "@umriss-ui/core";

const DAY = 24 * 60 * 60 * 1000;

export default function CheckADueDate() {
  const [issued, setIssued] = useState<Date | null>(new Date(2026, 2, 2));
  const [due, setDue] = useState<Date | null>(new Date(2026, 1, 27));

  const term = issued && due ? Math.round((due.getTime() - issued.getTime()) / DAY) : null;
  const error = term !== null && term < 0 ? "The due date lies before the invoice date." : undefined;
  const hint = term !== null && term >= 0 ? `Payment term: ${term} days.` : undefined;

  return (
    <Grid minItemWidth="220px" gap={4} style={{ maxWidth: 520 }}>
      <FormField label="Invoice date">
        <DatePicker value={issued} onChange={setIssued} />
      </FormField>
      <FormField label="Due" hint={hint} error={error}>
        <DatePicker value={due} onChange={setDue} />
      </FormField>
    </Grid>
  );
}
```

#### When to use something else

- A day and a time of day → DateTimePicker
- A span of days → DateRangePicker
- A span with times at both ends → DateTimeRangePicker

#### Keyboard

| Key | Action |
|---|---|
| `Enter or Space` | On the field, opens the calendar; on a day, chooses it. |
| `Arrow keys` | Move a day left or right, a week up or down. |
| `Escape` | Closes the calendar and returns to the field. |

#### API

##### `DatePickerProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `Date \| null` | — | The day, as a `Date` on local midnight; `null` means none.<br>Shown in: [Configurator](#/datepicker/configurator-datepicker), [Pick a day](#/datepicker/pick-a-day), [States](#/datepicker/states) and 8 more |
| `placeholder` | `string` | — | What stands in the empty field.<br>Shown in: [States](#/datepicker/states) |
| `disabled` | `boolean` | `false` | Locks the field and the panel.<br>Shown in: [Configurator](#/datepicker/configurator-datepicker), [States](#/datepicker/states) |
| `invalid` | `boolean` | — | Marks the field as invalid. `FormField` sets it itself as soon as it carries an `error` - by hand only necessary without `FormField`.<br>Shown in: [Configurator](#/datepicker/configurator-datepicker), [With an error](#/datepicker/with-an-error) |
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/datepicker/configurator-datepicker), [States](#/datepicker/states) |
| `chars` | `number` | — | The width in characters - room for the value; the field adds its own padding, glyph and cross. Given, the field is that wide wherever it stands, and never wider than its place. Without it the field fills its place, and where the place asks - in a toolbar or a row - it is as wide as its longest value in the formats in use, so a date never truncates.<br>Shown in: [Configurator](#/datepicker/configurator-datepicker) |
| `clearable` | `boolean` | `false` | Shows a cross where a value is set, which fades in on hover/focus and clears the value.<br>Shown in: [Configurator](#/datepicker/configurator-datepicker), [Pick a day](#/datepicker/pick-a-day), [States](#/datepicker/states) and 4 more |
| `ref` | `Ref<HTMLSpanElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` *required* | `(date: Date \| null) => void` | — | Runs as soon as a day is settled - on a click in the grid, on "Today" and on clearing (`null`). Every one of these ways hands out local midnight; there is none that delivers a time along with it.<br>Shown in: [Configurator](#/datepicker/configurator-datepicker), [Pick a day](#/datepicker/pick-a-day), [States](#/datepicker/states) and 8 more |

Also takes every attribute of `<span>` – without `defaultValue`, `onChange`.

#### Known limits

- No typing of a date into the field.
- umriss shows the reader's time ([ADR-0060](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0060-validation-and-a-layout-editor-are-never-time-zones-not-yet.md)).

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### DateTimePicker

One moment, day and time of day in one field (date-time field): when an incident began, when an alert fired.

```ts
import { DateTimePicker } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/datetimepicker/

It reports only on Apply, Now or Clear, never with a day that has no time yet. The value contract of the pickers stands on [DatePicker](#/datepicker).

Around a clock change the panel names a skipped hour and asks which of a doubled hour is meant, for example 02:30 on 25 October 2026.

#### Examples

##### Set an instant

Choose the day, type the time, then Apply; `onChange` runs only then, never with a day that has no time.

```tsx
import { useState } from "react";
import { DateTimePicker, FormField, Stack, Text, useFormats } from "@umriss-ui/core";

export default function SetAnInstant() {
  const formats = useFormats();
  const [started, setStarted] = useState<Date | null>(null);

  return (
    <Stack gap={3} style={{ maxWidth: 320 }}>
      <FormField label="Customer impact began">
        <DateTimePicker value={started} onChange={setStarted} clearable />
      </FormField>
      <Text size="xs" tone="muted" mono>
        value: {started === null ? "null" : `${formats.dateTime(started, false)} ${formats.offset(started)}`}
      </Text>
    </Stack>
  );
}
```

##### With seconds

Set `withSeconds` where the second is part of the value, such as the moment an alert fired.

```tsx
import { useState } from "react";
import { DateTimePicker, FormField } from "@umriss-ui/core";

export default function WithSeconds() {
  const [fired, setFired] = useState<Date | null>(new Date(2026, 2, 17, 9, 41, 27));

  return (
    <FormField label="Alert fired" style={{ maxWidth: 320 }}>
      <DateTimePicker value={fired} onChange={setFired} withSeconds />
    </FormField>
  );
}
```

##### States

`size="sm"` suits dense forms; errors come from the `FormField`, and `disabled` locks field and panel.

```tsx
import { useState } from "react";
import { DateTimePicker, FormField, Grid } from "@umriss-ui/core";

export default function States() {
  const [acknowledged, setAcknowledged] = useState<Date | null>(new Date(2026, 2, 17, 9, 46));
  const [resolved, setResolved] = useState<Date | null>(new Date(2026, 2, 17, 9, 30));

  return (
    <Grid minItemWidth="240px" gap={4}>
      <FormField label="Acknowledged" hint="Small size.">
        <DateTimePicker size="sm" value={acknowledged} onChange={setAcknowledged} clearable />
      </FormField>
      <FormField label="Resolved" error="Resolved lies before the incident was opened at 09:42.">
        <DateTimePicker value={resolved} onChange={setResolved} clearable />
      </FormField>
      <FormField label="Closed" hint="Empty, with its own placeholder.">
        <DateTimePicker value={null} onChange={() => {}} placeholder="Still open" />
      </FormField>
      <FormField label="Opened" hint="Set by the alert.">
        <DateTimePicker value={new Date(2026, 2, 17, 9, 42)} onChange={() => {}} disabled />
      </FormField>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the field invalid by itself. Without one, set `invalid` and tie your message to the field with `aria-describedby`.

```tsx
import { useId, useState } from "react";
import { DateTimePicker, Stack, Text } from "@umriss-ui/core";

/* INC-1048 was opened by the alert at 09:42. */
const OPENED = new Date(2026, 2, 17, 9, 42);

export default function WithAnError() {
  const [resolved, setResolved] = useState<Date | null>(new Date(2026, 2, 17, 9, 30));
  const messageId = useId();
  const error = resolved !== null && resolved < OPENED ? "Resolved lies before the incident was opened at 09:42." : undefined;

  return (
    <Stack gap={1} style={{ maxWidth: 320 }}>
      <DateTimePicker
        aria-label="Resolved"
        value={resolved}
        onChange={setResolved}
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
      />
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

#### When to use something else

- A day without a time → DatePicker
- A span with times at both ends → DateTimeRangePicker

#### Keyboard

| Key | Action |
|---|---|
| `Arrow keys` | In the calendar, move a day or a week. |
| `Enter or Space` | On a day, chooses it and moves on to the hour. |
| `Arrow Up / Arrow Down` | In a time field, steps the hour, minute or second. |
| `Enter` | In a time field, applies the value. |
| `Escape` | Closes the panel without a change. |

#### API

##### `DateTimePickerProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `Date \| null` | — | The instant; `null` means none.<br>Shown in: [Configurator](#/datetimepicker/configurator-datetimepicker), [Set an instant](#/datetimepicker/set-an-instant), [With seconds](#/datetimepicker/with-seconds) and 3 more |
| `withSeconds` | `boolean` | `false` | Show the seconds field.<br>Shown in: [Configurator](#/datetimepicker/configurator-datetimepicker), [With seconds](#/datetimepicker/with-seconds) |
| `placeholder` | `string` | — | What stands in the empty field.<br>Shown in: [States](#/datetimepicker/states) |
| `disabled` | `boolean` | `false` | Locks the field and the panel.<br>Shown in: [Configurator](#/datetimepicker/configurator-datetimepicker), [States](#/datetimepicker/states) |
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/datetimepicker/configurator-datetimepicker), [States](#/datetimepicker/states) |
| `chars` | `number` | — | The width in characters - room for the value; the field adds its own padding, glyph and cross. Given, the field is that wide wherever it stands, and never wider than its place. Without it the field fills its place, and where the place asks - in a toolbar or a row - it is as wide as its longest value in the formats in use, so a date never truncates.<br>Shown in: [Configurator](#/datetimepicker/configurator-datetimepicker) |
| `invalid` | `boolean` | — | Marks the field as invalid. `FormField` sets it itself as soon as it carries an `error` - by hand only necessary without `FormField`.<br>Shown in: [Configurator](#/datetimepicker/configurator-datetimepicker), [With an error](#/datetimepicker/with-an-error) |
| `clearable` | `boolean` | `false` | Shows a cross where a value is set, which fades in on hover/focus and clears the value.<br>Shown in: [Configurator](#/datetimepicker/configurator-datetimepicker), [Set an instant](#/datetimepicker/set-an-instant), [States](#/datetimepicker/states) |
| `ref` | `Ref<HTMLSpanElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` *required* | `(date: Date \| null) => void` | — | Runs only on completion - "Apply", "Now" or "Clear" - and not already on the click on a day: a day without a time would be a half-set value here, and a half value is no value.<br>Shown in: [Configurator](#/datetimepicker/configurator-datetimepicker), [Set an instant](#/datetimepicker/set-an-instant), [With seconds](#/datetimepicker/with-seconds) and 3 more |

Also takes every attribute of `<span>` – without `defaultValue`, `onChange`.

#### Known limits

- umriss shows the reader's time ([ADR-0060](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0060-validation-and-a-layout-editor-are-never-time-zones-not-yet.md)).

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### DateRangePicker

A span of days, from one day to another (date range): leave, a sprint, a reporting period. Two months side by side, presets for the usual spans, and the days counted while the pointer moves.

```ts
import { DateRangePicker } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/daterangepicker/

Both ends lie at local midnight and both count. The value contract of the pickers stands on [DatePicker](#/datepicker).

The same `{ from, to }` shape is what `@umriss-ui/table` reads a date filter from.

#### Examples

##### A span of days

Two clicks set both ends, in either order; the value is `{ from, to }`, both inclusive, at local midnight.

```tsx
import { useState } from "react";
import { DateRangePicker, FormField, Stack, Text, rangeDays, useFormats } from "@umriss-ui/core";
import type { DateRange } from "@umriss-ui/core";

export default function ASpanOfDays() {
  const formats = useFormats();
  const [leave, setLeave] = useState<DateRange | null>(null);

  return (
    <Stack gap={3} style={{ maxWidth: 340 }}>
      <FormField label="Leave">
        <DateRangePicker value={leave} onChange={setLeave} clearable />
      </FormField>
      <Text size="xs" tone="muted" mono>
        {leave === null
          ? "value: null"
          : `${formats.date(leave.from)} to ${formats.date(leave.to)}, ${rangeDays(leave.from, leave.to)} days`}
      </Text>
    </Stack>
  );
}
```

##### Presets

Pass `presets` for the spans your users pick most; an empty list hides the column, and none gives the defaults.

```tsx
import { useState } from "react";
import { DateRangePicker, FormField, Grid } from "@umriss-ui/core";
import type { DateRange } from "@umriss-ui/core";

const fromToday = (days: number): DateRange => {
  const today = new Date();
  const from = new Date(today.getFullYear(), today.getMonth(), today.getDate());
  return { from, to: new Date(from.getFullYear(), from.getMonth(), from.getDate() + days - 1) };
};

export default function Presets() {
  const [sprint, setSprint] = useState<DateRange | null>(null);
  const [workshop, setWorkshop] = useState<DateRange | null>(null);
  const [report, setReport] = useState<DateRange | null>(null);

  return (
    <Grid minItemWidth="240px" gap={4}>
      <FormField label="Sprint" hint="Presets of your own.">
        <DateRangePicker
          value={sprint}
          onChange={setSprint}
          clearable
          placeholder="Choose a sprint"
          presets={[
            { label: "Next 2 weeks", range: () => fromToday(14) },
            { label: "Next 3 weeks", range: () => fromToday(21) },
          ]}
        />
      </FormField>
      <FormField label="Workshop" hint="No presets.">
        <DateRangePicker value={workshop} onChange={setWorkshop} presets={[]} />
      </FormField>
      <FormField label="Report" hint="The default presets.">
        <DateRangePicker value={report} onChange={setReport} />
      </FormField>
    </Grid>
  );
}
```

##### States

`size="sm"` suits dense forms; errors come from the `FormField`, and `disabled` locks field and calendar.

```tsx
import { useState } from "react";
import { DateRangePicker, FormField, Grid } from "@umriss-ui/core";
import type { DateRange } from "@umriss-ui/core";

export default function States() {
  const [training, setTraining] = useState<DateRange | null>({ from: new Date(2026, 3, 13), to: new Date(2026, 3, 14) });
  const [leave, setLeave] = useState<DateRange | null>({ from: new Date(2026, 2, 16), to: new Date(2026, 2, 27) });

  return (
    <Grid minItemWidth="240px" gap={4}>
      <FormField label="Training" hint="Small size.">
        <DateRangePicker size="sm" value={training} onChange={setTraining} clearable />
      </FormField>
      <FormField label="Leave" error="Chloe Durand is already on leave from 23 March.">
        <DateRangePicker value={leave} onChange={setLeave} clearable />
      </FormField>
      <FormField label="Sprint 14" hint="Set by the sprint plan.">
        <DateRangePicker value={{ from: new Date(2026, 2, 9), to: new Date(2026, 2, 20) }} onChange={() => {}} disabled />
      </FormField>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the field invalid by itself. Without one, set `invalid` and tie your message to the field with `aria-describedby`.

```tsx
import { useId, useState } from "react";
import { DateRangePicker, Stack, Text } from "@umriss-ui/core";
import type { DateRange } from "@umriss-ui/core";

/* Chloe Durand covers for Noah Fischer and is away herself from 23 March. */
const AWAY_FROM = new Date(2026, 2, 23);

export default function WithAnError() {
  const [leave, setLeave] = useState<DateRange | null>({ from: new Date(2026, 2, 16), to: new Date(2026, 2, 27) });
  const messageId = useId();
  const error = leave !== null && leave.to >= AWAY_FROM ? "Chloe Durand, who covers for you, is on leave from 23 March." : undefined;

  return (
    <Stack gap={1} style={{ maxWidth: 360 }}>
      <DateRangePicker
        aria-label="Leave, Noah Fischer"
        value={leave}
        onChange={setLeave}
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
      />
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

#### When to use something else

- A span with times at both ends → DateTimeRangePicker
- A single day → DatePicker

#### Keyboard

| Key | Action |
|---|---|
| `Arrow keys` | Move a day or a week, across both months. |
| `Enter or Space` | Sets the start, then the end. |
| `Escape` | Closes the panel. |

#### API

##### `DateRangePickerProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | [`DateRange`](#type-DateRange)` \| null` | — | The time span, both ends on local midnight and both inclusive; `null` means none.<br>Shown in: [Configurator](#/daterangepicker/configurator-daterangepicker), [A span of days](#/daterangepicker/a-span-of-days), [Presets](#/daterangepicker/presets) and 3 more |
| `placeholder` | `string` | — | What stands in the empty field.<br>Shown in: [Presets](#/daterangepicker/presets) |
| `disabled` | `boolean` | `false` | Locks the field and the panel.<br>Shown in: [Configurator](#/daterangepicker/configurator-daterangepicker), [States](#/daterangepicker/states) |
| `invalid` | `boolean` | — | Marks the field as invalid. `FormField` sets it itself as soon as it carries an `error` - by hand only necessary without `FormField`.<br>Shown in: [Configurator](#/daterangepicker/configurator-daterangepicker), [With an error](#/daterangepicker/with-an-error) |
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/daterangepicker/configurator-daterangepicker), [States](#/daterangepicker/states) |
| `chars` | `number` | — | The width in characters - room for the value; the field adds its own padding, glyph and cross. Given, the field is that wide wherever it stands, and never wider than its place. Without it the field fills its place, and where the place asks - in a toolbar or a row - it is as wide as its longest value in the formats in use, so a date never truncates.<br>Shown in: [Configurator](#/daterangepicker/configurator-daterangepicker) |
| `clearable` | `boolean` | `false` | Shows a cross where a value is set, which fades in on hover/focus and clears the value.<br>Shown in: [Configurator](#/daterangepicker/configurator-daterangepicker), [A span of days](#/daterangepicker/a-span-of-days), [Presets](#/daterangepicker/presets) and 2 more |
| `presets` | [`RangePreset`](#type-RangePreset)`[]` | `DEFAULT_PRESETS`, in the wording's labels | The quick-select column in the panel. An empty array hides the column.<br>Shown in: [Presets](#/daterangepicker/presets) |
| `ref` | `Ref<HTMLSpanElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` *required* | `(range: `[`DateRange`](#type-DateRange)` \| null) => void` | — | Runs as soon as both ends are settled - after the second click, on a preset and on clearing (`null`). Ends dragged backwards swap silently; there is no error state to handle.<br>Shown in: [Configurator](#/daterangepicker/configurator-daterangepicker), [A span of days](#/daterangepicker/a-span-of-days), [Presets](#/daterangepicker/presets) and 3 more |

Also takes every attribute of `<span>` – without `defaultValue`, `onChange`.

##### Types on this page

###### `DateRange`

A span between two dates, both ends included - the value of
`DateRangePicker` and `DateTimeRangePicker`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `from` *required* | `Date` | — | <br>Shown in: [A span of days](#/daterangepicker/a-span-of-days), [Presets](#/daterangepicker/presets), [States](#/daterangepicker/states) and 6 more |
| `to` *required* | `Date` | — | <br>Shown in: [A span of days](#/daterangepicker/a-span-of-days), [Presets](#/daterangepicker/presets), [States](#/daterangepicker/states) and 6 more |

###### `RangePreset`

A shortcut in a range picker's panel: its label, and a function that
computes the range when it is chosen - so that "Last 7 days" is counted from
the moment of the click.

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` *required* | `string` | — | <br>Shown in: [Presets](#/daterangepicker/presets) |
| `range` *required* | `() => `[`DateRange`](#type-DateRange) | — | <br>Shown in: [Presets](#/daterangepicker/presets) |

#### Known limits

- One span; no list of separate days.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### DateTimeRangePicker

A span with a time at each end (date-time range): a planned downtime, a release freeze, the minutes an objective was breached. The footer shows the duration while it is set.

```ts
import { DateTimeRangePicker } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/datetimerangepicker/

It starts on All day: two clicks set the days, from 00:00 to the end of the last day. Untick All day to type the times. It reports only on Apply. The value contract of the pickers stands on [DatePicker](#/datepicker).

A clock change is named for each end separately.

#### Examples

##### A downtime window

Click two days, untick All day, type both times, then Apply; the footer counts the duration as you go.

```tsx
import { useState } from "react";
import { DateTimeRangePicker, FormField, Stack, Text, useFormats } from "@umriss-ui/core";
import type { DateRange } from "@umriss-ui/core";

export default function ADowntimeWindow() {
  const formats = useFormats();
  const [downtime, setDowntime] = useState<DateRange | null>(null);

  return (
    <Stack gap={3} style={{ maxWidth: 360 }}>
      <FormField label="Planned downtime, Billing">
        <DateTimeRangePicker value={downtime} onChange={setDowntime} clearable />
      </FormField>
      <Text size="xs" tone="muted" mono>
        {downtime === null
          ? "value: null"
          : `${formats.dateTime(downtime.from, false)} to ${formats.dateTime(downtime.to, false)}`}
      </Text>
    </Stack>
  );
}
```

##### With seconds

Set `withSeconds` where the span is measured to the second; `presets={[]}` drops the column when no span repeats.

```tsx
import { useState } from "react";
import { DateTimeRangePicker, FormField } from "@umriss-ui/core";
import type { DateRange } from "@umriss-ui/core";

export default function WithSeconds() {
  const [breach, setBreach] = useState<DateRange | null>({
    from: new Date(2026, 2, 17, 9, 40, 12),
    to: new Date(2026, 2, 17, 10, 9, 48),
  });

  return (
    <FormField label="Objective breached, Checkout" style={{ maxWidth: 420 }}>
      <DateTimeRangePicker value={breach} onChange={setBreach} withSeconds presets={[]} />
    </FormField>
  );
}
```

##### States

`size="sm"` suits dense forms; errors come from the `FormField`, and `disabled` locks field and panel.

```tsx
import { useState } from "react";
import { DateTimeRangePicker, FormField, Grid } from "@umriss-ui/core";
import type { DateRange } from "@umriss-ui/core";

export default function States() {
  const [freeze, setFreeze] = useState<DateRange | null>(null);
  const [downtime, setDowntime] = useState<DateRange | null>({
    from: new Date(2026, 2, 21, 2, 0),
    to: new Date(2026, 2, 21, 6, 0),
  });

  return (
    <Grid minItemWidth="260px" gap={4}>
      <FormField label="Release freeze" hint="Small size.">
        <DateTimeRangePicker size="sm" value={freeze} onChange={setFreeze} clearable />
      </FormField>
      <FormField label="Planned downtime, Search" error="Overlaps the downtime of Checkout, 03:00 to 04:00.">
        <DateTimeRangePicker value={downtime} onChange={setDowntime} clearable />
      </FormField>
      <FormField label="Maintenance window, Payments" hint="Empty, with its own placeholder.">
        <DateTimeRangePicker value={null} onChange={() => {}} placeholder="Not scheduled yet" />
      </FormField>
      <FormField label="Downtime, last quarter" hint="Closed.">
        <DateTimeRangePicker
          value={{ from: new Date(2025, 11, 6, 1, 0), to: new Date(2025, 11, 6, 3, 30) }}
          onChange={() => {}}
          disabled
        />
      </FormField>
    </Grid>
  );
}
```

##### With an error

A `FormField` with an `error` marks the field invalid by itself. Without one, set `invalid` and tie your message to the field with `aria-describedby`.

```tsx
import { useId, useState } from "react";
import { DateTimeRangePicker, Stack, Text } from "@umriss-ui/core";
import type { DateRange } from "@umriss-ui/core";

/* Checkout is down from 03:00 to 04:00 that night; Search depends on it. */
const CHECKOUT = { from: new Date(2026, 2, 21, 3, 0), to: new Date(2026, 2, 21, 4, 0) };

export default function WithAnError() {
  const [downtime, setDowntime] = useState<DateRange | null>({
    from: new Date(2026, 2, 21, 2, 0),
    to: new Date(2026, 2, 21, 6, 0),
  });
  const messageId = useId();
  const overlaps = downtime !== null && downtime.from < CHECKOUT.to && downtime.to > CHECKOUT.from;
  const error = overlaps ? "Overlaps the downtime of Checkout, 03:00 to 04:00." : undefined;

  return (
    <Stack gap={1} style={{ maxWidth: 420 }}>
      <DateTimeRangePicker
        aria-label="Planned downtime, Search"
        value={downtime}
        onChange={setDowntime}
        invalid={error !== undefined}
        aria-describedby={error ? messageId : undefined}
      />
      {error && (
        <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
          {error}
        </Text>
      )}
    </Stack>
  );
}
```

#### When to use something else

- Whole days only → DateRangePicker
- A single moment → DateTimePicker

#### Keyboard

| Key | Action |
|---|---|
| `Arrow keys` | In the calendar, move a day or a week. |
| `Enter or Space` | Sets the start day, then the end day. |
| `Arrow Up / Arrow Down` | In a time field, steps its value. |
| `Enter` | In a time field, applies the span. |
| `Escape` | Closes the panel without a change. |

#### API

##### `DateTimeRangePickerProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | [`DateRange`](#type-DateRange)` \| null` | — | The time span with times at both ends; `null` means none.<br>Shown in: [Configurator](#/datetimerangepicker/configurator-datetimerangepicker), [A downtime window](#/datetimerangepicker/a-downtime-window), [With seconds](#/datetimerangepicker/with-seconds) and 3 more |
| `withSeconds` | `boolean` | `false` | Show the seconds fields.<br>Shown in: [Configurator](#/datetimerangepicker/configurator-datetimerangepicker), [With seconds](#/datetimerangepicker/with-seconds) |
| `placeholder` | `string` | — | What stands in the empty field.<br>Shown in: [States](#/datetimerangepicker/states) |
| `disabled` | `boolean` | `false` | Locks the field and the panel.<br>Shown in: [Configurator](#/datetimerangepicker/configurator-datetimerangepicker), [States](#/datetimerangepicker/states) |
| `invalid` | `boolean` | — | Marks the field as invalid. `FormField` sets it itself as soon as it carries an `error` - by hand only necessary without `FormField`.<br>Shown in: [Configurator](#/datetimerangepicker/configurator-datetimerangepicker), [With an error](#/datetimerangepicker/with-an-error) |
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise.<br>Shown in: [Configurator](#/datetimerangepicker/configurator-datetimerangepicker), [States](#/datetimerangepicker/states) |
| `chars` | `number` | — | The width in characters - room for the value; the field adds its own padding, glyph and cross. Given, the field is that wide wherever it stands, and never wider than its place. Without it the field fills its place, and where the place asks - in a toolbar or a row - it is as wide as its longest value in the formats in use, so a date never truncates.<br>Shown in: [Configurator](#/datetimerangepicker/configurator-datetimerangepicker) |
| `clearable` | `boolean` | `false` | Shows a cross where a value is set, which fades in on hover/focus and clears the value.<br>Shown in: [Configurator](#/datetimerangepicker/configurator-datetimerangepicker), [A downtime window](#/datetimerangepicker/a-downtime-window), [States](#/datetimerangepicker/states) |
| `presets` | [`RangePreset`](#type-RangePreset)`[]` | `DEFAULT_PRESETS`, in the wording's labels | The quick-select column in the panel; presets apply for the whole day and close immediately. An empty array hides the column.<br>Shown in: [With seconds](#/datetimerangepicker/with-seconds) |
| `ref` | `Ref<HTMLSpanElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` *required* | `(range: `[`DateRange`](#type-DateRange)` \| null) => void` | — | Runs only on "Apply" and on clearing (`null`), never between the two clicks. If the end lies before the start, both swap on applying - there is no error state.<br>Shown in: [Configurator](#/datetimerangepicker/configurator-datetimerangepicker), [A downtime window](#/datetimerangepicker/a-downtime-window), [With seconds](#/datetimerangepicker/with-seconds) and 3 more |

Also takes every attribute of `<span>` – without `defaultValue`, `onChange`.

##### Types on this page

###### `DateRange`

A span between two dates, both ends included - the value of
`DateRangePicker` and `DateTimeRangePicker`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `from` *required* | `Date` | — | <br>Shown in: [A downtime window](#/datetimerangepicker/a-downtime-window), [With seconds](#/datetimerangepicker/with-seconds), [States](#/datetimerangepicker/states) and 6 more |
| `to` *required* | `Date` | — | <br>Shown in: [A downtime window](#/datetimerangepicker/a-downtime-window), [With seconds](#/datetimerangepicker/with-seconds), [States](#/datetimerangepicker/states) and 6 more |

###### `RangePreset`

A shortcut in a range picker's panel: its label, and a function that
computes the range when it is chosen - so that "Last 7 days" is counted from
the moment of the click.

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` *required* | `string` | — | <br>Shown in: [Presets (DateRangePicker)](#/daterangepicker/presets) |
| `range` *required* | `() => `[`DateRange`](#type-DateRange) | — | <br>Shown in: [Presets (DateRangePicker)](#/daterangepicker/presets) |

#### Known limits

- umriss shows the reader's time ([ADR-0060](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0060-validation-and-a-layout-editor-are-never-time-zones-not-yet.md)).
- No recurring windows.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

## Feedback

What tells a user how things stand and that something is under way.

### Spinner

A turning circle that says something is running, without saying how far (also called a loading indicator). Reach for it for short waits whose length nobody knows, beside a word that says what runs.

```ts
import { Spinner } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/spinner/

It takes the colour of the text around it and announces itself as “Loading”; name it better with `aria-label` where the word beside it is not enough.

#### Examples

##### With a word beside it

A spinner says only that something runs; the words beside it say what.

```tsx
import { Spinner, Stack, Text } from "@umriss-ui/core";

export default function WithAWord() {
  return (
    <Stack direction="row" gap={2} align="center">
      <Spinner aria-label="Loading the tours" />
      <Text size="sm" tone="secondary">
        Loading the tours of North depot …
      </Text>
    </Stack>
  );
}
```

##### Sizes

`size` is the edge length in pixels; match it to the text it stands beside – 12 for small print, 14 for body text.

```tsx
import { Spinner, Stack } from "@umriss-ui/core";

export default function Sizes() {
  return (
    <Stack direction="row" gap={4} align="center">
      <Spinner size={12} />
      <Spinner size={14} />
      <Spinner size={20} />
      <Spinner size={32} />
    </Stack>
  );
}
```

##### Colour

It draws in `currentColor`, so it takes the colour of whatever it stands in and needs no tone of its own.

```tsx
import { Spinner, Stack, Text } from "@umriss-ui/core";

export default function Colour() {
  return (
    <Stack direction="row" gap={5} align="center" wrap>
      <Stack direction="row" gap={2} align="center">
        <Spinner size={14} />
        <Text size="sm">Refreshing</Text>
      </Stack>
      <Stack direction="row" gap={2} align="center" style={{ color: "var(--u-color-accent)" }}>
        <Spinner size={14} />
        <Text as="span" size="sm" style={{ color: "inherit" }}>
          Syncing the calendar
        </Text>
      </Stack>
    </Stack>
  );
}
```

##### Refresh a panel in place

While a panel reloads, the button that started it carries the spinner - `loading` on a `Button` - and the old figures stay readable below it. The button stays, so the head keeps its height.

```tsx
import { useEffect, useState } from "react";
import { Button, Card, CardBody, CardHeader, Stack, Text } from "@umriss-ui/core";

export default function APanelRefreshing() {
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (!loading) return;
    const timer = setTimeout(() => setLoading(false), 1500);
    return () => clearTimeout(timer);
  }, [loading]);

  return (
    <Card style={{ maxWidth: 420 }}>
      <CardHeader
        title="Open incidents"
        actions={
          <Button size="sm" variant="ghost" loading={loading} onClick={() => setLoading(true)}>
            Refresh
          </Button>
        }
      />
      <CardBody>
        <Stack gap={2}>
          <Text size="sm">INC-1048 · Checkout slow, card payments time out</Text>
          <Text size="sm">INC-1047 · Webhook deliveries delayed</Text>
        </Stack>
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- You know how far the job has come → ProgressBar
- You know the shape of the content that is coming → Skeleton
- A button waiting for the action it started → `loading` on [Button](#/button)

#### Keyboard

The keys of [Button](#/button/keyboard-button) apply here.

#### Accessibility

An `svg` with the role `status`, named "Loading" by the wording or by your `aria-label`; the role stays whatever you pass. It draws no text, so its name is all a screen reader hears of it. Where a word beside it already says what runs, as in a loading toast, hide it with `aria-hidden`.

With reduced motion it turns at less than half its speed instead of stopping, so it still says that something runs.

#### API

##### `SpinnerProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `size` | `number` | `14` | Edge length in pixels.<br>Shown in: [Sizes](#/spinner/sizes), [Colour](#/spinner/colour) |
| `ref` | `Ref<SVGSVGElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<svg>`.

#### Known limits

- One shape and no figure: for how far a job has come, use a [ProgressBar](#/progressbar).

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### ProgressBar

A bar that shows how far a job has come, or that it runs while nobody knows how far (also called a progress indicator). Reach for it for imports, uploads and anything else that counts towards an end.

```ts
import { ProgressBar } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/progressbar/

`value` runs from 0 to 1; values outside are clamped. A screen reader hears the percentage, or `valueText` where a count says it better.

It has no tone: progress is neither good nor bad, and a job at 90 % is not a warning.

#### Examples

##### How far a job has come

A `value` from 0 to 1 and a `label` naming what progresses; `showLabel` puts the percentage beside the bar.

```tsx
import { ProgressBar } from "@umriss-ui/core";

export default function HowFar() {
  return (
    <div style={{ maxWidth: 420 }}>
      <ProgressBar value={0.42} label="Import of the March invoices" showLabel />
    </div>
  );
}
```

##### Count instead of a share

Where a count says it better, pass it as `valueText`: a screen reader hears “5 of 12 parcels” instead of a percentage.

```tsx
import { ProgressBar, Stack, Text } from "@umriss-ui/core";

export default function ACount() {
  return (
    <Stack gap={2} style={{ maxWidth: 420 }}>
      <Text size="sm">5 of 12 parcels scanned onto FP 214 K</Text>
      <ProgressBar value={5 / 12} label="Loading of tour T-01" valueText="5 of 12 parcels" />
    </Stack>
  );
}
```

##### Run without a known end

Leave out `value` when nobody knows how far it is; the bar runs and shows no figure.

```tsx
import { ProgressBar, Stack, Text } from "@umriss-ui/core";

export default function WithoutAnEnd() {
  return (
    <Stack gap={2} style={{ maxWidth: 420 }}>
      <Text size="sm">Waiting for the payment provider to confirm …</Text>
      <ProgressBar label="Waiting for the payment provider" />
    </Stack>
  );
}
```

##### Follow a job through its steps

One bar per step and one for the whole, derived from the steps; the step waiting on a person runs without a figure.

```tsx
import { useState } from "react";
import { Badge, Button, Card, CardBody, CardHeader, Divider, ProgressBar, Stack, Text } from "@umriss-ui/core";

interface Step {
  name: string;
  /** Items to work through; 0 for a step that waits on someone. */
  items: number;
  unit: string;
}

const STEPS: Step[] = [
  { name: "Import the bank statements", items: 4, unit: "accounts" },
  { name: "Match payments to invoices", items: 312, unit: "payments" },
  { name: "Controller's sign-off", items: 0, unit: "" },
  { name: "Post to the ledger", items: 9, unit: "cost centres" },
];

/** The share done per step after `ticks` updates from the server. */
function sharesAfter(ticks: number): number[] {
  let left = ticks;
  return STEPS.map((step) => {
    const needed = step.items === 0 ? 2 : 4;
    const taken = Math.min(left, needed);
    left -= taken;
    return taken / needed;
  });
}

export default function ACloseInSteps() {
  const [ticks, setTicks] = useState(6);
  const shares = sharesAfter(ticks);
  const overall = shares.reduce((sum, share) => sum + share, 0) / STEPS.length;
  const running = shares.findIndex((share) => share < 1);

  return (
    <Card style={{ maxWidth: 560 }}>
      <CardHeader
        eyebrow="Month-end close"
        title="February 2026"
        actions={<Badge>{running === -1 ? "Done" : `Step ${running + 1} of ${STEPS.length}`}</Badge>}
      />
      <CardBody>
        <Stack gap={4}>
          <ProgressBar value={overall} label="The whole close" showLabel />
          <Divider />
          {STEPS.map((step, i) => {
            const share = shares[i]!;
            const waiting = step.items === 0 && i === running;
            return (
              <Stack key={step.name} gap={1}>
                <Text size="sm">{step.name}</Text>
                {waiting ? (
                  <ProgressBar label={step.name} />
                ) : (
                  <ProgressBar
                    value={share}
                    label={step.name}
                    showLabel
                    valueText={step.items > 0 ? `${Math.round(share * step.items)} of ${step.items} ${step.unit}` : undefined}
                  />
                )}
              </Stack>
            );
          })}
          <Stack direction="row" gap={2}>
            <Button onClick={() => setTicks((t) => Math.min(t + 1, 14))}>Advance</Button>
            <Button variant="ghost" onClick={() => setTicks(0)}>
              Start again
            </Button>
          </Stack>
        </Stack>
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- A measured share read against a bound: utilisation, budget used → Meter
- A short wait with nothing to count → Spinner

#### Keyboard

The keys of [Button](#/button/keyboard-button) apply here.

#### Accessibility

The role `progressbar`, named by `label` - "Progress" if you give none - or by your `aria-labelledby`. With a `value` it carries the whole percentage as `aria-valuenow`, and `valueText` as `aria-valuetext`; without one it carries no value, the state a screen reader knows as indeterminate.

It is no live region: a screen reader reads the value when it reaches the bar, and a job that finishes announces nothing. Say the end in words, in an [Alert](#/alert) or a [Toast](#/toast).

Under forced colours the track takes an edge and the fill the system's selection colour. With reduced motion the sweep of a bar without a value runs three times slower.

#### API

##### `ProgressBarProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` | `number` | — | How far the task has come, from 0 to 1. Left out, the bar is indeterminate: the task runs, and nobody knows how far it is.<br>Shown in: [Configurator](#/progressbar/configurator-progressbar), [How far a job has come](#/progressbar/how-far), [Count instead of a share](#/progressbar/a-count) and 3 more |
| `label` | `string` | the wording's "Progress" | What is progressing, e.g. "Import of the invoice records". A progress bar needs a name from the author.<br>Shown in: [How far a job has come](#/progressbar/how-far), [Count instead of a share](#/progressbar/a-count), [Run without a known end](#/progressbar/without-an-end) and 3 more |
| `valueText` | `string` | — | What a screen reader says instead of the percentage, where a count says it better - "3 of 12 files".<br>Shown in: [Count instead of a share](#/progressbar/a-count), [Follow a job through its steps](#/progressbar/a-close-in-steps), [A deployment (Stepper)](#/stepper/a-deployment) |
| `showLabel` | `boolean` | `false` | The percentage beside the bar (Geist Mono). Never for an indeterminate bar - it has no figure to show.<br>Shown in: [Configurator](#/progressbar/configurator-progressbar), [How far a job has come](#/progressbar/how-far), [Follow a job through its steps](#/progressbar/a-close-in-steps) and 1 more |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>`.

#### Known limits

- No colour of verdict and no steps of its own; for a job in steps, stack one bar per step.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Skeleton

Grey shapes that stand where content is still loading and hold the height it will have (also called a placeholder or shimmer). Reach for it when you know the layout of what is coming, so nothing jumps when it arrives.

```ts
import { Skeleton } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/skeleton/

A skeleton is hidden from screen readers. Mark the region that is loading with `aria-busy`, and say in words what loads where that matters.

#### Examples

##### Lines of text to come

A line per line of text, the last one shorter, so the placeholder has the height the text will have.

```tsx
import { Skeleton, Stack } from "@umriss-ui/core";

export default function Lines() {
  return (
    <Stack gap={2} style={{ maxWidth: 420 }}>
      <Skeleton />
      <Skeleton />
      <Skeleton width="60%" />
    </Stack>
  );
}
```

##### Shapes

`circle`, `width` and `height` give it the shape of what comes – an avatar, a name, a line beneath it.

```tsx
import { Skeleton, Stack } from "@umriss-ui/core";

export default function Shapes() {
  return (
    <Stack direction="row" gap={3} align="center" style={{ maxWidth: 420 }}>
      <Skeleton circle width={32} height={32} />
      <Stack gap={2} style={{ flex: 1 }}>
        <Skeleton width="55%" height={14} />
        <Skeleton width="35%" height={10} />
      </Stack>
    </Stack>
  );
}
```

##### Hold a list's place while it loads

The placeholder rows are as tall as the rows that replace them, so nothing below jumps when the data arrives.

```tsx
import { useState } from "react";
import { Button, Skeleton, Stack, Text } from "@umriss-ui/core";

const PEOPLE = [
  { name: "Maya Lindgren", role: "Product manager · Web" },
  { name: "Arjun Mehta", role: "Developer · Web" },
  { name: "Noah Fischer", role: "Designer · Web" },
];

function Avatar({ name }: { name: string }) {
  return (
    <span
      aria-hidden="true"
      style={{
        width: 32,
        height: 32,
        borderRadius: "50%",
        display: "grid",
        placeItems: "center",
        background: "var(--u-color-surface-sunken)",
        fontSize: "var(--u-text-xs)",
      }}
    >
      {name.split(" ").map((part) => part[0])}
    </span>
  );
}

export default function AListLoading() {
  const [loading, setLoading] = useState(true);

  return (
    <Stack gap={4} style={{ maxWidth: 420 }}>
      <Stack gap={3} aria-busy={loading}>
        {PEOPLE.map((person) => (
          <Stack key={person.name} direction="row" gap={3} align="center" style={{ minHeight: 36 }}>
            {loading ? (
              <>
                <Skeleton circle width={32} height={32} />
                <Stack gap={2} style={{ flex: 1 }}>
                  <Skeleton width="50%" height={14} />
                  <Skeleton width="35%" height={10} />
                </Stack>
              </>
            ) : (
              <>
                <Avatar name={person.name} />
                <Stack gap={1}>
                  <Text size="sm" weight="medium">
                    {person.name}
                  </Text>
                  <Text size="xs" tone="muted">
                    {person.role}
                  </Text>
                </Stack>
              </>
            )}
          </Stack>
        ))}
      </Stack>
      <Button size="sm" onClick={() => setLoading((l) => !l)} style={{ alignSelf: "flex-start" }}>
        {loading ? "Show the loaded rows" : "Show the placeholders"}
      </Button>
    </Stack>
  );
}
```

#### When to use something else

- The layout of what is coming is unknown → Spinner
- You can say how far the loading has come → ProgressBar

#### Keyboard

The keys of [Button](#/button/keyboard-button) apply here.

#### Accessibility

Every skeleton is `aria-hidden`: a screen reader meets nothing where it stands, and nothing is announced when the content replaces it. The region that loads carries `aria-busy` from you, and a word where the wait matters.

With reduced motion the shimmer stops, and the shape stands in a still, faint grey.

#### API

##### `SkeletonProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `width` | `string \| number` | `"100%"` | Width, e.g. "120px" or "60%".<br>Shown in: [Configurator](#/skeleton/configurator-skeleton), [Lines of text to come](#/skeleton/lines), [Shapes](#/skeleton/shapes) and 2 more |
| `height` | `string \| number` | `"12px"` | Height, e.g. "12px" or 16.<br>Shown in: [Configurator](#/skeleton/configurator-skeleton), [Shapes](#/skeleton/shapes), [Hold a list's place while it loads](#/skeleton/a-list-loading) |
| `circle` | `boolean` | `false` | Circular shape, e.g. for an avatar placeholder.<br>Shown in: [Configurator](#/skeleton/configurator-skeleton), [Shapes](#/skeleton/shapes), [Hold a list's place while it loads](#/skeleton/a-list-loading) |
| `ref` | `Ref<HTMLSpanElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<span>`.

#### Known limits

- It draws a shape and nothing else; the rows, cards and layout it stands in for are yours.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Alert

A message that stays in the page until its matter is settled (also called a banner or callout). Reach for it when the reader must notice something here: a failed import, an approval waiting, a form that did not save.

```ts
import { Alert } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/alert/

`warning` and `danger` interrupt a screen reader at once; `neutral`, `accent` and `success` are read out politely when the reader is free. Choose the tone by what the reader has to do, not by the colour you want.

Dismissing is reported through `onDismiss` and nothing more: whether and when the message comes back is your state.

#### Examples

##### A message

A title and a sentence or two, standing where the matter is – here above a sprint board.

```tsx
import { Alert } from "@umriss-ui/core";

export default function AMessage() {
  return (
    <Alert title="Sprint 14 ends on Friday">
      Items still in progress on Friday at 17:00 move to Sprint 15 with their remaining estimate.
    </Alert>
  );
}
```

##### Tones

Pick the `tone` by what the reader has to do; `warning` and `danger` also interrupt a screen reader at once.

```tsx
import { Alert, Stack } from "@umriss-ui/core";

export default function Tones() {
  return (
    <Stack gap={3}>
      <Alert tone="neutral" title="Maintenance window tonight">
        Search is read-only from 23:00 to 23:30 while the index is rebuilt.
      </Alert>
      <Alert tone="accent" title="New: latency by region">
        Each service's page now splits its 95th percentile by region.
      </Alert>
      <Alert tone="success" title="Billing is back within its objective">
        The 95th percentile has stayed below 400 ms for the last hour.
      </Alert>
      <Alert tone="warning" title="Webhook deliveries are delayed">
        The oldest message in the queue is seven minutes old. Deliveries still go out.
      </Alert>
      <Alert tone="danger" title="Checkout is failing card payments">
        About 3 % of payments have timed out since 09:42. INC-1048 is open.
      </Alert>
    </Stack>
  );
}
```

##### Offer the way forward

Put the next step in `actions`, under the text it belongs to, rather than somewhere else on the page.

```tsx
import { Alert, Button } from "@umriss-ui/core";

export default function WithActions() {
  return (
    <Alert
      tone="warning"
      title="Invoice INV-26-0318 is waiting for your approval"
      actions={
        <>
          <Button size="sm" variant="primary">
            Review the invoice
          </Button>
          <Button size="sm" variant="ghost">
            Pass it on
          </Button>
        </>
      }
    >
      It is due on 15 April and books € 1,965.84 to Facilities (CC-4400).
    </Alert>
  );
}
```

##### Let the reader dismiss it

`onDismiss` adds a close button and reports the click; whether the message ever comes back is your state.

```tsx
import { useState } from "react";
import { Alert, Button } from "@umriss-ui/core";

export default function Dismissible() {
  const [open, setOpen] = useState(true);

  return open ? (
    <Alert tone="accent" title="Tours now show their delivery windows" onDismiss={() => setOpen(false)}>
      Each stop carries the window the customer booked; late arrivals are marked in the tour list.
    </Alert>
  ) : (
    <Button size="sm" onClick={() => setOpen(true)}>
      Show the message again
    </Button>
  );
}
```

##### Sum up a form's errors

When a save fails, one `danger` alert above the form names every field that stops it and leads to the first.

```tsx
import { useState } from "react";
import { Alert, Button, FormField, Input, Stack } from "@umriss-ui/core";

export default function AboveAForm() {
  const [tried, setTried] = useState(false);
  const [owner, setOwner] = useState("");
  const [budget, setBudget] = useState("");
  const missing = [owner === "" ? "Owner" : null, budget === "" ? "Monthly budget" : null].filter((name) => name !== null);
  const showErrors = tried && missing.length > 0;

  return (
    <Stack gap={4} style={{ maxWidth: 440 }}>
      {showErrors && (
        <Alert
          tone="danger"
          title="The cost centre was not saved"
          actions={
            <Button size="sm" onClick={() => document.getElementById(owner === "" ? "cc-owner" : "cc-budget")?.focus()}>
              Go to the first field
            </Button>
          }
        >
          {missing.join(" and ")} {missing.length === 1 ? "is" : "are"} still empty.
        </Alert>
      )}
      <FormField label="Name">
        <Input defaultValue="Customer service" />
      </FormField>
      <FormField label="Owner" required fieldId="cc-owner" error={showErrors && owner === "" ? "Name the person responsible." : undefined}>
        <Input value={owner} onChange={(event) => setOwner(event.target.value)} />
      </FormField>
      <FormField label="Monthly budget (€)" required fieldId="cc-budget" error={showErrors && budget === "" ? "Enter an amount." : undefined}>
        <Input numeric value={budget} onChange={(event) => setBudget(event.target.value)} />
      </FormField>
      <Button variant="primary" onClick={() => setTried(true)} style={{ alignSelf: "flex-start" }}>
        Save the cost centre
      </Button>
    </Stack>
  );
}
```

#### When to use something else

- Confirming something that has already happened, which may pass unnoticed → Toast
- A question the user must answer before an action goes ahead → ConfirmDialog
- A list or panel with nothing in it → EmptyState

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Reaches the actions, then the dismiss cross. |
| `Enter / Space` | On the cross, calls `onDismiss`; the alert goes when you remove it. |

The keys of [Button](#/button/keyboard-button) apply here.

#### Accessibility

The role follows the tone: `warning` and `danger` are an `alert`, which interrupts a screen reader; `neutral`, `accent` and `success` are a polite `status`, read when the reader is free.

The title is a paragraph, not a heading, so an alert does not enter the page's outline. The dismiss cross is named "Close message", or by `dismissLabel`.

#### API

##### `AlertProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `tone` | [`AlertTone`](#type-AlertTone)<br>`"neutral" \| "accent" \| "success" \| "warning" \| "danger"` | `"neutral"` | How urgent the message is. Only `warning` and `danger` interrupt the screen reader - the other two report politely.<br>Shown in: [Configurator](#/alert/configurator-alert), [Tones](#/alert/tones), [Offer the way forward](#/alert/with-actions) and 5 more |
| `title` | `ReactNode` | — | Heading; without it the body text carries the message on its own.<br>Shown in: [A message](#/alert/a-message), [Tones](#/alert/tones), [Offer the way forward](#/alert/with-actions) and 5 more |
| `actions` | `ReactNode` | — | Actions below the text, e.g. "Try again".<br>Shown in: [Offer the way forward](#/alert/with-actions), [Sum up a form's errors](#/alert/above-a-form), [A deployment (Stepper)](#/stepper/a-deployment) |
| `dismissLabel` | `string` | the wording's "Close message" | Label of the dismiss cross. |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onDismiss` | `() => void` | — | Shows a dismiss cross and calls this.<br>Shown in: [Let the reader dismiss it](#/alert/dismissible) |

Also takes every attribute of `<div>` – without `title`.

##### Types on this page

###### `AlertTone`

How urgent an alert is; it also decides whether a screen reader is
interrupted.

```ts
type AlertTone = "neutral" | "accent" | "success" | "warning" | "danger";
```

#### Known limits

- No timer: an alert stays until you remove it. A message that goes by itself is a toast.
- No stack or queue of messages; place each alert where its matter is.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Toast

Short feedback in the corner of the window that interrupts nothing and goes away by itself (also called a snackbar or notification). Reach for it to confirm what has just happened: saved, exported, approved.

```ts
import { ToastProvider, useToast } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/toast/

[`useToast`](#/api/useToast) needs a `ToastProvider` around the application, once, at the root.

Toasts stand above an open modal dialog and can be used there: they are seen, pressed and heard, and stay where they were while a dialog opens or closes.

`held` on the `ToastProvider` holds them back while a surface they must not cover is open: none is seen or heard, their time stands still, and they come back with the time they had left, so nothing is lost.

A toast stays five seconds by default. Its clock stops while the deck is open – under the pointer, with the focus inside it – and runs on with the time that was left.

The title says what has happened, in about one line: “Invoice not sent”. Why, and what to do next, go in the description.

Nothing that must be read goes in a toast: whoever looked elsewhere has missed it. `duration: 0` keeps one until it is closed – for the rare message whose loss costs something, since a corner full of standing toasts stops being read.

Several toasts stand as a deck: the newest in front, a count on it, two edges behind it. It opens under the pointer, on the count, with the focus inside it, or with Alt+T; Escape gives the focus back.

At most three that leave by themselves stand at once (`toast.limit` in the [UmrissProvider](#/umrissprovider)); the oldest of them gives way to a new one, as if closed. A toast with `duration: 0` and a `loading` toast never give way and do not count.

#### Examples

##### Show a toast

Call `toast()` from [`useToast`](#/api/useToast) with what has happened; a `ToastProvider` at the root of the application holds them.

```tsx
import { Button, useToast } from "@umriss-ui/core";

function Content() {
  const { toast } = useToast();

  return (
    <Button onClick={() => toast({ title: "Export finished", description: "The project list is ready as a CSV." })}>
      Show a toast
    </Button>
  );
}

/* `useToast` needs a `ToastProvider` above it; at the root of an application
   one provider serves every screen. */
export default function ShowAToast() {
  return <Content />;
}
```

##### Tones

The `tone` says how it turned out; a symbol and the words say the same, so the colour is never alone.

```tsx
import { Button, Stack, useToast } from "@umriss-ui/core";

function Content() {
  const { toast } = useToast();

  return (
    <Stack direction="row" gap={3} wrap>
      <Button onClick={() => toast({ title: "Release 4.18 deployed", description: "Checkout and Billing run the new version.", tone: "success" })}>
        Success
      </Button>
      <Button onClick={() => toast({ title: "Connection lost", description: "Reconnecting to the metrics stream.", tone: "warning" })}>
        Warning
      </Button>
      <Button onClick={() => toast({ title: "Rollback failed", description: "Search still runs release 4.17.", tone: "danger" })}>
        Danger
      </Button>
    </Stack>
  );
}

/* `useToast` needs a `ToastProvider` above it; at the root of an application
   one provider serves every screen. */
export default function Tones() {
  return <Content />;
}
```

##### Undo

One `action` reverses what just happened; `onClose` says whether the time ran out, the toast was closed or the action was taken, and the line under the list reports which.

```tsx
import { useState } from "react";
import { Button, Stack, Text, useToast } from "@umriss-ui/core";
import type { ToastCloseReason } from "@umriss-ui/core";

const BOOKINGS = ["Room 2.14 · Tue 10:00 · Design review", "Room 3.02 · Tue 14:00 · Quarterly planning", "Room 1.05 · Wed 09:30 · Onboarding"];

const OUTCOME: Record<ToastCloseReason, string> = {
  timeout: "The time ran out: the cancellation stands.",
  dismiss: "The toast was closed: the cancellation stands.",
  action: "Undone: the booking is back.",
};

function Content() {
  const { toast } = useToast();
  const [bookings, setBookings] = useState(BOOKINGS);
  const [outcome, setOutcome] = useState<string | null>(null);

  const cancel = (booking: string) => {
    setBookings((list) => list.filter((entry) => entry !== booking));
    setOutcome(null);
    toast({
      title: "Booking cancelled",
      description: booking,
      action: {
        label: "Undo",
        /* Back in its place in the week, whatever went meanwhile. */
        onClick: () => setBookings((list) => BOOKINGS.filter((entry) => entry === booking || list.includes(entry))),
      },
      onClose: (reason) => setOutcome(OUTCOME[reason]),
    });
  };

  return (
    <Stack gap={2} style={{ maxWidth: 480 }}>
      {bookings.map((booking) => (
        <Stack key={booking} direction="row" gap={3} align="center" justify="space-between">
          <Text size="sm">{booking}</Text>
          <Button size="sm" variant="secondary" onClick={() => cancel(booking)}>
            Cancel
          </Button>
        </Stack>
      ))}
      <Text size="xs" tone="muted">
        {outcome ?? `${bookings.length} of ${BOOKINGS.length} rooms booked`}
      </Text>
    </Stack>
  );
}

/* `useToast` needs a `ToastProvider` above it; at the root of an application
   one provider serves every screen. */
export default function Undo() {
  return <Content />;
}
```

##### Keep it until it is closed

`duration: 0` keeps a toast until the reader closes it – for the rare message whose loss costs something.

```tsx
import { Button, useToast } from "@umriss-ui/core";

function Content() {
  const { toast } = useToast();

  return (
    <Button
      onClick={() =>
        toast({
          title: "Working offline",
          description: "Scans are kept on this device and sent when the connection is back.",
          tone: "warning",
          duration: 0,
        })
      }
    >
      Go offline
    </Button>
  );
}

/* `useToast` needs a `ToastProvider` above it; at the root of an application
   one provider serves every screen. */
export default function UntilClosed() {
  return <Content />;
}
```

##### Save, and say how it went

A `loading` toast shows a spinner, has no close button and does not leave by itself; `update` turns it into its outcome in place, and only then does its time begin.

```tsx
import { useEffect, useRef, useState } from "react";
import { Button, Stack, Switch, useToast } from "@umriss-ui/core";

function Content() {
  const { toast, update } = useToast();
  const [fail, setFail] = useState(false);
  /* Read when the answer comes, so that "Try again" follows the switch. */
  const failRef = useRef(fail);
  useEffect(() => {
    failRef.current = fail;
  }, [fail]);

  const publish = () => {
    const id = toast({ title: "Publishing release notes…", tone: "loading" });
    setTimeout(() => {
      if (failRef.current) {
        update(id, {
          title: "Release notes not published",
          description: "Two sections still have open review comments.",
          tone: "danger",
          action: { label: "Try again", onClick: publish },
        });
      } else {
        update(id, {
          title: "Release notes published",
          description: "All 214 subscribers were notified.",
          tone: "success",
        });
      }
    }, 1500);
  };

  return (
    <Stack direction="row" gap={4} align="center" wrap>
      <Button onClick={publish}>Publish release notes</Button>
      <Switch label="Let it fail" checked={fail} onChange={(event) => setFail(event.target.checked)} />
    </Stack>
  );
}

/* `useToast` needs a `ToastProvider` above it; at the root of an application
   one provider serves every screen. */
export default function SaveWithLoading() {
  return <Content />;
}
```

##### Confirm an action in a list

The row changes where the reader looks; the toast confirms it in passing, so a second approval never waits on the first. Approve all three: the toasts stand as a deck with a count on the front one, and open under the pointer, on the count or with Alt+T.

```tsx
import { useState } from "react";
import { Badge, Button, Stack, Text, useToast } from "@umriss-ui/core";

const INVOICES = [
  { id: "INV-26-0318", supplier: "Brandlow Office Supply", amount: "€ 1,965.84" },
  { id: "INV-26-0317", supplier: "Kettering & Shaw Events", amount: "€ 12,733.00" },
  { id: "INV-26-0316", supplier: "Northgate Cloud Services", amount: "€ 4,284.00" },
];

function Content() {
  const { toast } = useToast();
  const [approved, setApproved] = useState<string[]>([]);

  return (
    <Stack gap={2} style={{ maxWidth: 560 }}>
      {INVOICES.map((invoice) => {
        const done = approved.includes(invoice.id);
        return (
          <Stack key={invoice.id} direction="row" gap={3} align="center" justify="space-between">
            <Stack gap={1}>
              <Text size="sm" weight="medium">
                {invoice.supplier}
              </Text>
              <Text size="xs" tone="muted" mono>
                {invoice.id} · {invoice.amount}
              </Text>
            </Stack>
            {done ? (
              <Badge tone="success">Approved</Badge>
            ) : (
              <Button
                size="sm"
                onClick={() => {
                  setApproved((list) => [...list, invoice.id]);
                  toast({ title: `${invoice.id} approved`, description: "It goes to Finance for payment.", tone: "success" });
                }}
              >
                Approve
              </Button>
            )}
          </Stack>
        );
      })}
    </Stack>
  );
}

/* `useToast` needs a `ToastProvider` above it; at the root of an application
   one provider serves every screen. */
export default function AfterAnAction() {
  return <Content />;
}
```

##### Where they stand

`toast.position` in the `UmrissProvider` puts every toast of the application at one edge and one place along it; the deck grows away from that edge. On a phone they take the window's width, and only the edge counts. How far they stand from the edge is `--u-toast-inset-top` and `--u-toast-inset-bottom` on `:root` - below a fixed header, above a toolbar at the bottom; how far from the window's sides, `--u-toast-inset-start` and `--u-toast-inset-end` - beside a navigation rail, at the page's gutter.

```tsx
import { useMemo, useState } from "react";
import { Button, Stack, ToastProvider, UmrissProvider, useToast } from "@umriss-ui/core";
import type { ToastConfig, ToastPosition } from "@umriss-ui/core";

const POSITIONS: { position: ToastPosition; label: string }[] = [
  { position: "top-start", label: "Top start" },
  { position: "top-center", label: "Top center" },
  { position: "top-end", label: "Top end" },
  { position: "bottom-start", label: "Bottom start" },
  { position: "bottom-center", label: "Bottom center" },
  { position: "bottom-end", label: "Bottom end" },
];

function Buttons({ onPick }: { onPick: (position: ToastPosition) => void }) {
  const { toast } = useToast();
  return (
    <Stack direction="row" gap={2} wrap>
      {POSITIONS.map(({ position, label }) => (
        <Button
          key={position}
          size="sm"
          variant="secondary"
          onClick={() => {
            onPick(position);
            toast({ title: "Report exported", description: `Standing ${label.toLowerCase()}.`, tone: "success" });
          }}
        >
          {label}
        </Button>
      ))}
    </Stack>
  );
}

export default function WhereTheyStand() {
  const [position, setPosition] = useState<ToastPosition>("top-center");
  /* A new object is a new setting: kept until the position changes. */
  const config = useMemo<ToastConfig>(() => ({ position }), [position]);
  return (
    <UmrissProvider toast={config}>
      <ToastProvider>
        <Buttons onPick={setPosition} />
      </ToastProvider>
    </UmrissProvider>
  );
}
```

##### How many stand at once

`toast.limit` in the `UmrissProvider` caps the toasts that leave by themselves: here two stand, and each new one pushes out the oldest of them as if it had been closed. Scan four parcels in a row and only the last two remain.

```tsx
import { Button, ToastProvider, UmrissProvider, useToast, type ToastConfig } from "@umriss-ui/core";

type ToastFn = ReturnType<typeof useToast>["toast"];

const PARCELS = ["FP-2081", "FP-2082", "FP-2083", "FP-2084"];

function scan(toast: ToastFn) {
  PARCELS.forEach((parcel) => toast({ title: `Parcel ${parcel} scanned`, description: "Loaded onto tour T-03.", tone: "success" }));
}

function ScanButton() {
  const { toast } = useToast();
  return (
    <Button variant="primary" onClick={() => scan(toast)}>
      Scan four parcels
    </Button>
  );
}

/* Kept outside the component: a new object on every render would be a new
   setting on every render. */
const TOAST: ToastConfig = { limit: 2 };

export default function HowManyStand() {
  return (
    <UmrissProvider toast={TOAST}>
      <ToastProvider>
        <ScanButton />
      </ToastProvider>
    </UmrissProvider>
  );
}
```

##### Inside a modal

A toast stands above an open modal dialog and can be pressed there: the dialog's "Save" fails, and the toast carries "Retry" next to the form it belongs to.

```tsx
import { useState } from "react";
import { Button, FormField, Input, Modal, ModalBody, ModalFooter, ModalHeader, Select, Text, Tooltip, useToast } from "@umriss-ui/core";

function Content() {
  const { toast } = useToast();
  const [open, setOpen] = useState(false);

  const save = () =>
    toast({
      title: "Profile not saved",
      description: "The server did not answer.",
      tone: "danger",
      /* A failure stays until it is read. */
      duration: 0,
      action: { label: "Retry", onClick: save },
    });

  return (
    <>
      <Button onClick={() => setOpen(true)}>Edit the profile</Button>
      <Modal open={open} onClose={() => setOpen(false)} size="sm">
        <ModalHeader title="Edit the profile" description="Changes are saved to the account." />
        <ModalBody>
          <FormField label="Display name">
            <Input defaultValue="Maya Lindgren" />
          </FormField>
          <FormField label="Language">
            <Select defaultValue="en">
              <option value="en">English</option>
              <option value="de">Deutsch</option>
              <option value="fr">Français</option>
              <option value="es">Español</option>
            </Select>
          </FormField>
          <Tooltip content="Shows the profile as colleagues see it.">
            <Button size="sm" variant="secondary">
              Preview
            </Button>
          </Tooltip>
          <Text size="xs" tone="muted">
            Nothing is kept until it is saved.
          </Text>
        </ModalBody>
        <ModalFooter>
          <Button onClick={() => setOpen(false)}>Cancel</Button>
          <Button variant="primary" onClick={save}>
            Save
          </Button>
        </ModalFooter>
      </Modal>
    </>
  );
}

export default function InsideAModal() {
  return <Content />;
}
```

##### Hold the toasts

`held` on the `ToastProvider` keeps every toast out of sight and hearing while a surface is open that they must not cover and there is no room beside it. Their time stands still, a new one waits, and when the hold ends they come back with the time they had left: nothing is lost, as it would be by dismissing them.

```tsx
import { useState } from "react";
import { Button, Stack, Switch, ToastProvider, useToast } from "@umriss-ui/core";

function SendButton() {
  const { toast } = useToast();
  return (
    <Button onClick={() => toast({ title: "Route T-03 planned", description: "12 stops, back by 16:40.", tone: "success" })}>
      Send a toast
    </Button>
  );
}

export default function HoldTheToasts() {
  const [held, setHeld] = useState(false);
  return (
    <ToastProvider held={held}>
      <Stack direction="row" gap={4} align="center">
        <Switch label="Hold the toasts" checked={held} onChange={(event) => setHeld(event.target.checked)} />
        <SendButton />
      </Stack>
    </ToastProvider>
  );
}
```

#### When to use something else

- The reader must see it, or it stays true until something is done → Alert
- The reader must decide before going on → ConfirmDialog

#### Keyboard

| Key | Action |
|---|---|
| `Alt + T` | While a toast stands and is not held back, moves the focus into the messages and opens the deck. |
| `Tab / Shift + Tab` | Moves through the toasts' actions and close crosses; a keyboard focus inside opens the deck and holds every toast's clock. |
| `Enter / Space` | On an action, runs it and closes its toast; on a cross, closes the toast. |
| `Escape` | Closes the deck; after Alt + T, the focus goes back to where it was. |

The keys of [Button](#/button/keyboard-button) apply here.

#### Accessibility

Two live regions stand in the corner before the first message, since a region that arrives with its text is often not read: a neutral, success or loading toast goes into a polite `status`, a warning or danger one into an `alert` that interrupts, the table [Alert](#/alert) follows too. While a toast stands, the corner is a region named "Messages (Alt+T)".

The count on a deck of several is out of the tab order, since a focus on it would open the deck and take the count away; the keyboard opens the deck by Alt + T or by moving into it. A loading toast has no cross and does not leave by itself: `update` turns it into its outcome.

With reduced motion toasts appear, stack and leave without movement.

Inside a modal dialog the live regions move with the toasts, so a message is heard there as well as outside.

#### API

##### `ToastOptions`

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` *required* | `string` | — | What has happened – short, about one line (some 45 characters), in the perfect tense and not a request: "Invoice not sent". Why, and what to do next, belong in the description. A longer title wraps; it is never cut.<br>Shown in: [Show a toast](#/toast/show-a-toast), [Tones](#/toast/tones), [Undo](#/toast/undo) and 13 more |
| `description` | `string` | — | One more sentence where the title alone is too little. Nothing the reader MUST read: the toast goes away by itself.<br>Shown in: [Show a toast](#/toast/show-a-toast), [Tones](#/toast/tones), [Undo](#/toast/undo) and 11 more |
| `tone` | [`ToastTone`](#type-ToastTone)<br>`"neutral" \| "success" \| "warning" \| "danger" \| "loading"` | — | How the message turns out. The tone is never the only information – the glyph beside it and the text say the same thing once more. `loading` shows a spinner, has no close button and does not leave by itself: turn it into its outcome with `update`.<br>Shown in: [Tones](#/toast/tones), [Keep it until it is closed](#/toast/until-closed), [Save, and say how it went](#/toast/save-with-loading) and 10 more |
| `duration` | `number` | the provider's `duration`, else `5000` | Display duration in ms; 0 = stays until closed by hand.<br>Shown in: [Keep it until it is closed](#/toast/until-closed), [Inside a modal](#/toast/inside-a-modal) |
| `action` | [`ToastAction`](#type-ToastAction) | — | One action - "Undo". Never the only way to do what it offers: the toast leaves by itself, and not everybody reaches it in time. More than one action is a dialog.<br>Shown in: [Undo](#/toast/undo), [Save, and say how it went](#/toast/save-with-loading), [Inside a modal](#/toast/inside-a-modal) |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onClose` | `(reason: `[`ToastCloseReason`](#type-ToastCloseReason)`) => void` | — | Called once when the toast goes, with the reason.<br>Shown in: [Undo](#/toast/undo) |

##### `ToastAction`

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` *required* | `string` | — | A verb for what it does - "Undo", "Show".<br>Shown in: [Undo](#/toast/undo), [Save, and say how it went](#/toast/save-with-loading), [Inside a modal](#/toast/inside-a-modal) |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onClick` *required* | `() => void` | — | Runs, and the toast goes with the reason `action`.<br>Shown in: [Undo](#/toast/undo), [Save, and say how it went](#/toast/save-with-loading), [Inside a modal](#/toast/inside-a-modal) |

##### Types on this page

###### `ToastTone`

How the message turns out; `loading` is a toast still at work.

```ts
type ToastTone = "neutral" | "success" | "warning" | "danger" | "loading";
```

###### `ToastCloseReason`

Why a toast went: its time ran out, it was closed (or gave way to a newer
one), or its action was taken.

```ts
type ToastCloseReason = "timeout" | "dismiss" | "action";
```

#### Known limits

- One action at most, and never the only way to what it offers: the toast leaves by itself. What needs a decision needs an [Alert](#/alert) or a [ConfirmDialog](#/confirmdialog).
- One position for the whole application, set in the [UmrissProvider](#/umrissprovider); none per toast.
- One `ToastProvider` per application, at its root. A second one in the same document draws a second deck at the same place and the two lie on each other; in development it is reported on the console.
- No queue: a toast over the limit pushes the oldest timed one out rather than waiting. Lasting and `loading` toasts are not capped: the deck holds every one of them beside the timed ones.
- Without the Popover API the deck moves with a dialog that transforms itself: inside a dialog the toasts stand in the top layer only where the browser has it, and elsewhere they are a fixed box in the dialog.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### EmptyState

What stands where a list or panel has nothing to show: what is missing, why, and the way forward (also called a blank slate). Reach for it for a first use, a filter that found nothing, or a queue that is clear.

```ts
import { EmptyState } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/emptystate/

#### Examples

##### Nothing yet

The `title` says what is missing, the `description` what would bring it, and the `action` is the way there.

```tsx
import { Button, EmptyState } from "@umriss-ui/core";

export default function NothingYet() {
  return (
    <EmptyState
      title="No reports yet"
      description="Reports you save from the budget overview appear here."
      action={
        <Button variant="primary" size="sm">
          Open the budget overview
        </Button>
      }
    />
  );
}
```

##### Say why a filter found nothing

When filters empty a list, name them in the `description` and offer to clear them – the data is there, the view hides it.

```tsx
import { useState } from "react";
import { Button, EmptyState, Stack, Tag, TagGroup, Text } from "@umriss-ui/core";

/** Today's shipments from East Gate depot. */
const SHIPMENTS = [
  { id: "SH-1042", customer: "Harlow Bakery", status: "delivered" },
  { id: "SH-1043", customer: "Pine & Oak Florist", status: "out for delivery" },
  { id: "SH-1044", customer: "Moreau Optics", status: "delivered" },
];

export default function AFilterFoundNothing() {
  const [filters, setFilters] = useState(["Failed attempt", "East Gate depot"]);
  const shown = filters.includes("Failed attempt") ? [] : SHIPMENTS;

  return (
    <Stack gap={3}>
      <TagGroup aria-label="Active filters">
        {filters.map((filter) => (
          <Tag key={filter} tone="accent" onRemove={() => setFilters((all) => all.filter((f) => f !== filter))}>
            {filter}
          </Tag>
        ))}
      </TagGroup>
      {shown.length === 0 ? (
        <EmptyState
          title="No shipments match these filters"
          description={`Nothing today matches ${filters.map((f) => `“${f}”`).join(" and ")}.`}
          action={
            <Button size="sm" onClick={() => setFilters([])}>
              Clear the filters
            </Button>
          }
        />
      ) : (
        shown.map((shipment) => (
          <Text key={shipment.id} size="sm">
            {shipment.id} · {shipment.customer} · {shipment.status}
          </Text>
        ))
      )}
    </Stack>
  );
}
```

##### Mark good news in a panel

An empty panel can be the good case; an `icon` and a plain `title` say so, and no action is needed.

```tsx
import { Card, CardBody, CardHeader, EmptyState } from "@umriss-ui/core";

function Check() {
  return (
    <svg width="24" height="24" viewBox="0 0 24 24" fill="none" aria-hidden="true">
      <circle cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="1.5" />
      <path d="M7.5 12.5l3 3 6-6.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
    </svg>
  );
}

export default function InAPanel() {
  return (
    <Card style={{ maxWidth: 420 }}>
      <CardHeader eyebrow="Identity" title="Open incidents" />
      <CardBody>
        <EmptyState
          icon={<Check />}
          title="No open incidents"
          description="The last one, INC-1045, was resolved yesterday at 15:05."
        />
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- Something went wrong and the reader must act → Alert
- The content is still loading → Skeleton

#### Keyboard

The keys of [Button](#/button/keyboard-button) and [Tag](#/tag/keyboard-tag) apply here.

#### API

##### `EmptyStateProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` *required* | `ReactNode` | — | What is missing here - as a statement, not as an apology.<br>Shown in: [Nothing yet](#/emptystate/nothing-yet), [Say why a filter found nothing](#/emptystate/a-filter-found-nothing), [Mark good news in a panel](#/emptystate/in-a-panel) and 3 more |
| `description` | `ReactNode` | — | One sentence on why nothing is here and what would put something here.<br>Shown in: [Nothing yet](#/emptystate/nothing-yet), [Say why a filter found nothing](#/emptystate/a-filter-found-nothing), [Mark good news in a panel](#/emptystate/in-a-panel) and 3 more |
| `action` | `ReactNode` | — | The way into the next action, e.g. a button.<br>Shown in: [Nothing yet](#/emptystate/nothing-yet), [Say why a filter found nothing](#/emptystate/a-filter-found-nothing), [Cards on a dashboard (Card)](#/card/cards-on-a-dashboard) and 1 more |
| `icon` | `ReactNode` | — | Optional symbol above the title.<br>Shown in: [Mark good news in a panel](#/emptystate/in-a-panel) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>` – without `title`.

## Overlays

What opens above the screen and closes again.

### Tooltip

A sentence of explanation that appears while the pointer rests on an element or the keyboard focus is on it (also called a hint). Reach for it to explain an abbreviation or a control; an icon button names itself as an [IconButton](#/iconbutton).

```ts
import { Tooltip } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/tooltip/

It wraps exactly one element that can take focus and a ref; on text, give a `span` a `tabIndex` of 0.

Anything that stands only in a tooltip is lost on a touch screen. Keep it to a sentence that repeats or explains what is already there.

It shows for keyboard focus, not for the focus a click leaves behind, and a tooltip that repeats its element's `aria-label` does not describe the element a second time.

#### Examples

##### A tooltip

Wrap one focusable element; the `content` appears on pointer contact and on keyboard focus alike.

```tsx
import { Button, Tooltip } from "@umriss-ui/core";

export default function ATooltip() {
  return (
    <Tooltip content="Copies the board with its columns, not its cards.">
      <Button size="sm">Duplicate the board</Button>
    </Tooltip>
  );
}
```

##### Delay

`delay` is 300 ms by default so a passing pointer shows nothing; set it to 0 where the reader hovers on purpose.

```tsx
import { Button, Stack, Tooltip } from "@umriss-ui/core";

export default function Delay() {
  return (
    <Stack direction="row" gap={3}>
      <Tooltip content="Appears after 300 ms.">
        <Button size="sm">Default delay</Button>
      </Tooltip>
      <Tooltip content="Appears at once." delay={0}>
        <Button size="sm">Without a delay</Button>
      </Tooltip>
    </Stack>
  );
}
```

##### Explain an abbreviation

On text, make the element focusable with `tabIndex={0}` so a keyboard reader reaches the explanation too.

```tsx
import { Stack, Text, Tooltip } from "@umriss-ui/core";

/* Focusable text owes a visible focus: the library's ring, from its token. */
const STYLE = `
.abbreviation {
  text-decoration: underline dotted;
  cursor: help;
  border-radius: var(--u-radius-xs);
}
.abbreviation:focus-visible {
  outline: none;
  box-shadow: var(--u-focus-ring);
}
`;

export default function AnAbbreviation() {
  return (
    <Stack gap={1}>
      <style>{STYLE}</style>
      <Text size="xs" tone="muted">
        Checkout ·{" "}
        <Tooltip content="95th percentile: 95 of 100 requests were faster than this.">
          <span className="abbreviation" tabIndex={0}>
            p95
          </span>
        </Tooltip>{" "}
        latency
      </Text>
      <Text size="xl" mono>
        412 ms
      </Text>
    </Stack>
  );
}
```

##### Show how a figure came about

The content may be built from `Text`: inside a tooltip every tone turns round and reads on the tooltip's ground.

```tsx
import { Text, Tooltip } from "@umriss-ui/core";

/* Focusable text owes a visible focus: the library's ring, from its token. */
const STYLE = `
.figure {
  cursor: help;
  border-radius: var(--u-radius-xs);
}
.figure:focus-visible {
  outline: none;
  box-shadow: var(--u-focus-ring);
}
`;

export default function ACalculation() {
  return (
    <>
      <style>{STYLE}</style>
      <Tooltip
        content={
          <>
            <Text size="xs" mono>
              3 × 12.50 € = 37.50 €
            </Text>
            <Text size="xs" tone="muted">
              Quantity × unit price
            </Text>
          </>
        }
      >
        <Text as="span" size="xl" mono className="figure" tabIndex={0}>
          37.50 €
        </Text>
      </Tooltip>
    </>
  );
}
```

#### When to use something else

- The content has a link, a button or more than a sentence → Popover
- The reader must see it without hovering → Plain text beside the element

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Focusing the element shows its tooltip; moving focus away hides it. |
| `Escape` | Hides the tooltip. |

#### API

##### `TooltipProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `content` *required* | `ReactNode` | — | Short help text; no interaction, no long content.<br>Shown in: [A tooltip](#/tooltip/a-tooltip), [Delay](#/tooltip/delay), [Explain an abbreviation](#/tooltip/an-abbreviation) and 2 more |
| `children` *required* | `ReactElement<Record<string, unknown>>` | — | Exactly one element that triggers the tooltip (must accept refs). Its own ref keeps its element: the tooltip holds the same one beside it.<br>Shown in: [A tooltip](#/tooltip/a-tooltip), [Delay](#/tooltip/delay), [Explain an abbreviation](#/tooltip/an-abbreviation) and 2 more |
| `delay` | `number` | `300` | Delay in ms before the tooltip appears.<br>Shown in: [Delay](#/tooltip/delay) |

#### Known limits

- No interactive content and no rich layout inside: it is read, never used.
- No placement option: it stands above its element and flips below where there is no room.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Popover

A surface that hangs from a trigger and closes on Escape, an outside click or scrolling (also called a popup, flyout or dropdown panel). Reach for it for a small panel of your own: a filter, a detail, a short form.

```ts
import { Popover } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/popover/

It is controlled: you hold `open`, and `onOpenChange` reports each wish to close. Only you know whether it may close now, for instance with a half-filled form in it.

It places itself below its anchor, flips above where there is no room and stays inside the window. Inside a dialog it portals into that dialog, so it never lands behind it.

`Menu`, `Tooltip`, `Select`, `Combobox`, `MultiSelect` and the pickers stand on it, so they all place and dismiss the same way.

#### Examples

##### An anchored surface

You hold `open`, the popover hangs from `anchorRef` and reports every wish to close through `onOpenChange`.

```tsx
import { useRef, useState } from "react";
import { Button, Popover, Stack, Text } from "@umriss-ui/core";

export default function AnchoredSurface() {
  const anchor = useRef<HTMLButtonElement>(null);
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button ref={anchor} onClick={() => setOpen((o) => !o)} aria-expanded={open}>
        Sprint 14
      </Button>
      <Popover open={open} onOpenChange={setOpen} anchorRef={anchor} role="dialog" ariaLabel="Sprint 14" restoreFocus width={280}>
        <Stack gap={2} style={{ padding: "var(--u-space-4)" }}>
          <Text size="sm" weight="medium">
            Member portal sign-in and profile
          </Text>
          <Text size="sm" tone="secondary">
            9 to 20 March · 16 items · 334 hours planned
          </Text>
        </Stack>
      </Popover>
    </>
  );
}
```

##### Take the width of the trigger

`width` set to `anchor` makes the surface as wide as its trigger, as a list under a field needs; `minWidth` keeps it readable.

```tsx
import { useRef, useState } from "react";
import { Button, Popover, Stack, Text } from "@umriss-ui/core";

export default function WidthFromAnchor() {
  const anchor = useRef<HTMLButtonElement>(null);
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button ref={anchor} style={{ width: 240 }} onClick={() => setOpen((o) => !o)} aria-expanded={open}>
        Riverside depot · 2 vehicles
      </Button>
      <Popover
        open={open}
        onOpenChange={setOpen}
        anchorRef={anchor}
        role="dialog"
        ariaLabel="Vehicles at Riverside depot"
        width="anchor"
        minWidth={180}
        restoreFocus
      >
        <Stack gap={1} style={{ padding: "var(--u-space-3)" }}>
          <Text size="sm" mono>FP 402 R · van</Text>
          <Text size="sm" mono>FP 455 R · e-van</Text>
        </Stack>
      </Popover>
    </>
  );
}
```

##### Filter a list from a panel

A small form in a popover: it applies on the button, gives focus back to its trigger and leaves the list in view.

```tsx
import { useRef, useState } from "react";
import { Button, Checkbox, Popover, Stack, Text } from "@umriss-ui/core";

const DEPOTS = ["North depot", "Riverside depot", "East Gate depot"];

const SHIPMENTS = [
  { id: "SH-1042", customer: "Harlow Bakery", depot: "North depot" },
  { id: "SH-1051", customer: "Pine & Oak Florist", depot: "Riverside depot" },
  { id: "SH-1063", customer: "Moreau Optics", depot: "East Gate depot" },
  { id: "SH-1064", customer: "Quayside Books", depot: "East Gate depot" },
];

export default function AFilterPanel() {
  const anchor = useRef<HTMLButtonElement>(null);
  const [open, setOpen] = useState(false);
  const [applied, setApplied] = useState<string[]>(DEPOTS);
  const [draft, setDraft] = useState<string[]>(DEPOTS);

  const toggle = (depot: string) =>
    setDraft((current) => (current.includes(depot) ? current.filter((d) => d !== depot) : [...current, depot]));

  return (
    <Stack gap={3} align="flex-start">
      <Button
        ref={anchor}
        aria-expanded={open}
        onClick={() => {
          setDraft(applied);
          setOpen((o) => !o);
        }}
      >
        Depots: {applied.length === DEPOTS.length ? "all" : applied.length}
      </Button>
      <Popover open={open} onOpenChange={setOpen} anchorRef={anchor} role="dialog" ariaLabel="Filter by depot" restoreFocus width={260}>
        <Stack gap={3} style={{ padding: "var(--u-space-4)" }}>
          {DEPOTS.map((depot) => (
            <Checkbox key={depot} label={depot} checked={draft.includes(depot)} onChange={() => toggle(depot)} />
          ))}
          <Stack direction="row" gap={2} justify="flex-end">
            <Button size="sm" variant="ghost" onClick={() => setOpen(false)}>
              Cancel
            </Button>
            <Button
              size="sm"
              variant="primary"
              onClick={() => {
                setApplied(draft);
                setOpen(false);
              }}
            >
              Apply
            </Button>
          </Stack>
        </Stack>
      </Popover>
      <Stack gap={1}>
        {SHIPMENTS.filter((s) => applied.includes(s.depot)).map((s) => (
          <Text key={s.id} size="sm">
            {s.id} · {s.customer} · {s.depot}
          </Text>
        ))}
      </Stack>
    </Stack>
  );
}
```

##### A card at the right edge

A name at the end of a row opens its card `align="end"`, so the card grows back into the page; `offset` sets it a little further off the row, and `hideOnScroll` closes it when the page scrolls instead of letting it travel along.

```tsx
import { useRef, useState } from "react";
import { Button, Popover, Stack, Text } from "@umriss-ui/core";

export default function ACardAtTheEdge() {
  const anchor = useRef<HTMLButtonElement>(null);
  const [open, setOpen] = useState(false);

  return (
    <Stack direction="row" justify="space-between" align="center" gap={3}>
      <Text size="sm">INC-1048 · Checkout fails for card payments</Text>
      <Button ref={anchor} size="sm" variant="ghost" onClick={() => setOpen((o) => !o)} aria-expanded={open}>
        Maya Lindgren
      </Button>
      <Popover open={open} onOpenChange={setOpen} anchorRef={anchor} align="end" offset={8} hideOnScroll role="dialog" ariaLabel="Maya Lindgren" width={260}>
        <Stack gap={1} style={{ padding: "var(--u-space-4)" }}>
          <Text size="sm" weight="medium">
            Maya Lindgren
          </Text>
          <Text size="sm" tone="secondary">
            Incident lead · Payments team
          </Text>
          <Text size="xs" tone="muted">
            On call until Friday, 18:00
          </Text>
        </Stack>
      </Popover>
    </Stack>
  );
}
```

#### When to use something else

- A list of actions → Menu
- A sentence of explanation → Tooltip
- The user must answer before going on → Modal

#### Keyboard

| Key | Action |
|---|---|
| `Escape` | Asks to close; with `restoreFocus` the focus returns to the trigger. |

#### API

##### `PopoverProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` *required* | `boolean` | — | Whether the surface stands. Controlled: the popover never opens itself.<br>Shown in: [An anchored surface](#/popover/anchored-surface), [Take the width of the trigger](#/popover/width-from-anchor), [Filter a list from a panel](#/popover/a-filter-panel) and 1 more |
| `onOpenChange` *required* | `(open: boolean) => void` | — | Reports every wish to change the state – outside click, Escape, scrolling. Whether it closes as a result is the caller's decision.<br>Shown in: [An anchored surface](#/popover/anchored-surface), [Take the width of the trigger](#/popover/width-from-anchor), [Filter a list from a panel](#/popover/a-filter-panel) and 1 more |
| `anchorRef` *required* | `RefObject<HTMLElement \| null>` | — | Trigger the panel hangs from (the reference for the position).<br>Shown in: [An anchored surface](#/popover/anchored-surface), [Take the width of the trigger](#/popover/width-from-anchor), [Filter a list from a panel](#/popover/a-filter-panel) and 1 more |
| `focusRef` | `RefObject<HTMLElement \| null>` | `anchorRef` | Element that receives the focus on closing. Needed where the anchor is a non-focusable shell and the actual trigger sits inside it. |
| `insideRefs` | `ReadonlyArray<RefObject<HTMLElement \| null>>` | — | Further elements whose click does not count as an outside click (e.g. the clear ×). |
| `align` | [`Align`](#type-Align)<br>`"start" \| "end" \| "center"` | `"start"` | Where the surface points as long as there is room. Where there is none, it flips to the other side and clamps to the edge of the window.<br>Shown in: [A card at the right edge](#/popover/a-card-at-the-edge) |
| `offset` | `number` | — | Distance between trigger and surface, in pixels.<br>Shown in: [A card at the right edge](#/popover/a-card-at-the-edge) |
| `width` | `"anchor" \| "auto" \| number` | `"auto"` | "anchor" takes over the width of the trigger, a number fixes it.<br>Shown in: [An anchored surface](#/popover/anchored-surface), [Take the width of the trigger](#/popover/width-from-anchor), [Filter a list from a panel](#/popover/a-filter-panel) and 1 more |
| `minWidth` | `number` | — | Minimum width when the width comes from the anchor.<br>Shown in: [Take the width of the trigger](#/popover/width-from-anchor) |
| `restoreFocus` | `boolean` | `true` | Give the focus back to the trigger on closing.<br>Shown in: [An anchored surface](#/popover/anchored-surface), [Take the width of the trigger](#/popover/width-from-anchor), [Filter a list from a panel](#/popover/a-filter-panel) |
| `hideOnScroll` | `boolean` | `false` | Close on scrolling instead of travelling along – for tooltips.<br>Shown in: [A card at the right edge](#/popover/a-card-at-the-edge) |
| `id` | `string` | — | Fixed id of the surface – for `aria-controls` on the trigger. |
| `children` *required* | `ReactNode` | — | What stands in the surface.<br>Shown in: [An anchored surface](#/popover/anchored-surface), [Take the width of the trigger](#/popover/width-from-anchor), [Filter a list from a panel](#/popover/a-filter-panel) and 1 more |

###### Accessibility

| Prop | Type | Default | Description |
|---|---|---|---|
| `role` | `"dialog" \| "listbox" \| "menu" \| "tooltip"` | — | Role of the surface. Omit where an inner element carries it.<br>Shown in: [An anchored surface](#/popover/anchored-surface), [Take the width of the trigger](#/popover/width-from-anchor), [Filter a list from a panel](#/popover/a-filter-panel) and 1 more |
| `ariaLabel` | `string` | — | Accessible name of the surface. Needed as soon as it carries a `role`: a named role without a name is a riddle for a screen reader.<br>Shown in: [An anchored surface](#/popover/anchored-surface), [Take the width of the trigger](#/popover/width-from-anchor), [Filter a list from a panel](#/popover/a-filter-panel) and 1 more |

###### Styling

| Prop | Type | Default | Description |
|---|---|---|---|
| `className` | `string` | — | Additional class on the surface. |

##### Types on this page

###### `Align`

Where the panel lines up with its anchor along the side it stands on.

```ts
type Align = "start" | "end" | "center";
```

#### Known limits

- No padding and no inner layout: it brings the overlay's surface - ground, corners, shadow - and the rest is yours. A `className` restates the surface where one needs another.
- It does not trap focus; a surface the user must answer is a [Modal](#/modal).

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Menu

A list of actions that opens under a button (also called a dropdown menu). Reach for it when a place has more actions than room for buttons, or for the actions of each row in a list.

```ts
import { Menu, MenuItem, MenuSeparator } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/menu/

The entries are things that happen, not values that stay; choosing one runs it and closes the menu so the result is in view.

An [IconButton](#/iconbutton) makes the trigger for a row; its label says what it acts on, such as “Actions for INC-1048”.

#### Examples

##### Run actions from a trigger

Give `trigger` a button and the entries as `MenuItem`; each runs its `onSelect` and the menu closes.

```tsx
import { useState } from "react";
import { Button, Menu, MenuItem, MenuSeparator, Stack, Text } from "@umriss-ui/core";

export default function Actions() {
  const [last, setLast] = useState("-");

  return (
    <Stack gap={3} align="flex-start">
      <Menu trigger={<Button size="sm">Actions</Button>}>
        <MenuItem onSelect={() => setLast("Exported as CSV")}>Export as CSV</MenuItem>
        <MenuItem onSelect={() => setLast("Link copied")}>Copy the link</MenuItem>
        <MenuSeparator />
        <MenuItem tone="danger" onSelect={() => setLast("View removed")}>
          Remove the view
        </MenuItem>
      </Menu>
      <Text size="xs" tone="muted">
        Last: {last}
      </Text>
    </Stack>
  );
}
```

##### Align with the right edge

For a trigger at the right of a header, `align` set to `end` lines the panel up with the trigger's right edge.

```tsx
import { Button, Menu, MenuItem, Stack, Text } from "@umriss-ui/core";

export default function AlignEnd() {
  return (
    <Stack direction="row" justify="space-between" align="center" style={{ maxWidth: 520 }}>
      <Text weight="medium">Budget 2026 · Marketing</Text>
      <Menu align="end" trigger={<Button size="sm" variant="ghost">View</Button>}>
        <MenuItem>Show forecast</MenuItem>
        <MenuItem>Show last year</MenuItem>
        <MenuItem>Show in thousands</MenuItem>
      </Menu>
    </Stack>
  );
}
```

##### Disable an entry, mark a destructive one

A `disabled` entry keeps its place and is skipped by the arrow keys; the `danger` tone marks what destroys, after a separator.

```tsx
import { Button, Menu, MenuItem, MenuSeparator } from "@umriss-ui/core";

export default function DisabledAndDanger() {
  return (
    <Menu trigger={<Button size="sm">Invoice INV-26-0311</Button>}>
      <MenuItem>Open</MenuItem>
      <MenuItem disabled>Approve (already paid)</MenuItem>
      <MenuItem>Download as PDF</MenuItem>
      <MenuSeparator />
      <MenuItem tone="danger">Cancel the invoice</MenuItem>
    </Menu>
  );
}
```

##### Act on a row

One menu per row keeps a list quiet; the trigger's name says which row it acts on, since every button reads the same.

```tsx
import { useState } from "react";
import { Badge, IconButton, Menu, MenuItem, MenuSeparator, Stack, Text } from "@umriss-ui/core";

interface Incident {
  id: string;
  title: string;
  severity: "SEV1" | "SEV2" | "SEV3";
  state: "open" | "acknowledged" | "resolved";
}

const INCIDENTS: Incident[] = [
  { id: "INC-1048", title: "Checkout slow, card payments time out", severity: "SEV1", state: "acknowledged" },
  { id: "INC-1047", title: "Webhook deliveries delayed", severity: "SEV3", state: "open" },
  { id: "INC-1046", title: "Thumbnails missing for new uploads", severity: "SEV2", state: "resolved" },
];

const TONE = { SEV1: "danger", SEV2: "warning", SEV3: "neutral" } as const;

export default function PerRow() {
  const [incidents, setIncidents] = useState(INCIDENTS);
  const set = (id: string, state: Incident["state"]) =>
    setIncidents((all) => all.map((one) => (one.id === id ? { ...one, state } : one)));

  return (
    <Stack gap={2} style={{ maxWidth: 620 }}>
      {incidents.map((incident) => (
        <Stack key={incident.id} direction="row" gap={3} align="center">
          <Badge tone={TONE[incident.severity]}>{incident.severity}</Badge>
          <Text size="sm" style={{ flex: 1 }}>
            <Text as="span" size="sm" mono style={{ whiteSpace: "nowrap" }}>
              {incident.id}
            </Text>{" "}
            {incident.title}
          </Text>
          <Text as="span" size="xs" tone="muted">
            {incident.state}
          </Text>
          <Menu
            align="end"
            trigger={
              <IconButton size="sm" aria-label={`Actions for ${incident.id}`}>
                ⋯
              </IconButton>
            }
          >
            <MenuItem disabled={incident.state !== "open"} onSelect={() => set(incident.id, "acknowledged")}>
              Acknowledge
            </MenuItem>
            <MenuItem disabled={incident.state === "resolved"} onSelect={() => set(incident.id, "resolved")}>
              Resolve
            </MenuItem>
            <MenuItem>Copy the link</MenuItem>
            <MenuSeparator />
            <MenuItem tone="danger" onSelect={() => setIncidents((all) => all.filter((one) => one.id !== incident.id))}>
              Delete
            </MenuItem>
          </Menu>
        </Stack>
      ))}
    </Stack>
  );
}
```

#### When to use something else

- The user chooses a value that stays → Select
- The actions belong to a point or a row that is right-clicked → ContextMenu
- Two or three actions that fit as buttons → ButtonGroup
- Many commands across the application, found by typing → CommandPalette

#### Keyboard

| Key | Action |
|---|---|
| `Enter or Space` | On the trigger, opens the menu and moves focus to the first entry; on an entry, runs it and closes the menu. |
| `↓ / ↑` | Moves to the next or previous entry, wrapping at the ends; disabled entries are skipped. |
| `Home / End` | Moves to the first or last entry. |
| `Escape` | Closes the menu and returns focus to the trigger. |
| `Tab` | Closes the menu and moves on from the trigger. |

#### API

##### `MenuProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `trigger` *required* | `ReactElement<Record<string, unknown>>` | — | Trigger, e.g. a <Button>; must accept refs. Its own ref keeps its element: the menu holds the same one beside it.<br>Shown in: [Run actions from a trigger](#/menu/actions), [Align with the right edge](#/menu/align-end), [Disable an entry, mark a destructive one](#/menu/disabled-and-danger) and 4 more |
| `children` *required* | `ReactNode` | — | The entries – typically `MenuItem` and `MenuSeparator`.<br>Shown in: [Run actions from a trigger](#/menu/actions), [Align with the right edge](#/menu/align-end), [Disable an entry, mark a destructive one](#/menu/disabled-and-danger) and 4 more |
| `align` | `"start" \| "end"` | `"start"` | Alignment of the panel relative to the trigger.<br>Shown in: [Align with the right edge](#/menu/align-end), [Act on a row](#/menu/per-row), [Build a toolbar (IconButton)](#/iconbutton/a-toolbar) and 1 more |

##### `MenuItemProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `tone` | `"default" \| "danger"` | `"default"` | "danger" for destructive actions.<br>Shown in: [Run actions from a trigger](#/menu/actions), [Disable an entry, mark a destructive one](#/menu/disabled-and-danger), [Act on a row](#/menu/per-row) and 5 more |
| `ref` | `Ref<HTMLButtonElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onSelect` | `() => void` | — | What the entry does. The menu closes afterwards by itself: a menu that stays open after something has happened hides the result.<br>Shown in: [Run actions from a trigger](#/menu/actions), [Act on a row](#/menu/per-row), [Open overlays inside a full-screen panel (UmrissProvider)](#/umrissprovider/portal-target) and 6 more |

Also takes every attribute of `<button>` – without `onSelect`.

#### Known limits

- No submenus, no checkable entries and no type-ahead.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### ContextMenu

A menu that opens at a point, for a right-click on something that is not a button: a row, a canvas, a bar in a schedule (also called a right-click menu). The entries and the keyboard are those of the menu.

```ts
import { ContextMenu, MenuItem, MenuSeparator } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/contextmenu/

It is controlled: on `contextmenu` you keep the point and open it there, and `onOpenChange` reports the wish to close. Focus goes to the first entry and back to where it was on closing.

A right-click is invisible to a keyboard. Open the same menu on Shift+F10 or the menu key at the focused element, and keep the actions reachable some other way too.

#### Examples

##### Open it at the pointer

On `contextmenu`, keep the event's point and pass it as `position`; `ariaLabel` names what the menu acts on.

```tsx
import { useState } from "react";
import type { MouseEvent } from "react";
import { ContextMenu, MenuItem, MenuSeparator, Stack, Text } from "@umriss-ui/core";

export default function AtThePointer() {
  const [at, setAt] = useState<{ x: number; y: number } | null>(null);
  const [last, setLast] = useState("-");

  const openHere = (event: MouseEvent) => {
    event.preventDefault();
    setAt({ x: event.clientX, y: event.clientY });
  };

  return (
    <Stack gap={3} align="flex-start">
      <div
        onContextMenu={openHere}
        style={{
          width: "100%",
          maxWidth: 320,
          height: 120,
          display: "grid",
          placeItems: "center",
          border: "1px dashed var(--u-edge-color-strong)",
          borderRadius: "var(--u-radius-md)",
        }}
      >
        <Text size="sm" tone="muted">
          Right-click anywhere in here
        </Text>
      </div>
      <ContextMenu
        open={at !== null}
        position={at ?? { x: 0, y: 0 }}
        onOpenChange={(open) => {
          if (!open) setAt(null);
        }}
        ariaLabel="Actions for the surface"
      >
        <MenuItem onSelect={() => setLast("Split")}>Split here</MenuItem>
        <MenuItem onSelect={() => setLast("Note added")}>Add a note</MenuItem>
        <MenuSeparator />
        <MenuItem tone="danger" onSelect={() => setLast("Removed")}>
          Remove
        </MenuItem>
      </ContextMenu>
      <Text size="xs" tone="muted">
        Last: {last}
      </Text>
    </Stack>
  );
}
```

##### Open it on a row, by pointer or keyboard

Right-click opens it at the pointer; Shift+F10 or the menu key opens it at the focused row, so no reader is left out.

```tsx
import { useState } from "react";
import type { KeyboardEvent, MouseEvent } from "react";
import { ContextMenu, MenuItem, MenuSeparator, Stack, Text } from "@umriss-ui/core";

const SHIPMENTS = [
  { id: "SH-1042", customer: "Harlow Bakery", window: "09:00–11:00" },
  { id: "SH-1043", customer: "Pine & Oak Florist", window: "10:00–12:00" },
  { id: "SH-1044", customer: "Moreau Optics", window: "11:30–13:30" },
];

/* A focusable row owes a visible focus: the library's ring, from its token. */
const STYLE = `
.shipment-row:focus-visible {
  outline: none;
  box-shadow: var(--u-focus-ring);
}
`;

export default function OnARow() {
  const [menu, setMenu] = useState<{ id: string; x: number; y: number } | null>(null);
  const [last, setLast] = useState("-");

  const byPointer = (id: string) => (event: MouseEvent) => {
    event.preventDefault();
    setMenu({ id, x: event.clientX, y: event.clientY });
  };

  const byKey = (id: string) => (event: KeyboardEvent<HTMLElement>) => {
    if (event.key !== "ContextMenu" && !(event.shiftKey && event.key === "F10")) return;
    event.preventDefault();
    const box = event.currentTarget.getBoundingClientRect();
    setMenu({ id, x: box.left + 16, y: box.bottom });
  };

  const run = (what: string) => () => setLast(`${what} ${menu?.id ?? ""}`);

  return (
    <Stack gap={3} style={{ maxWidth: 480 }}>
      <style>{STYLE}</style>
      <div role="list" aria-label="Shipments">
        {SHIPMENTS.map((shipment) => (
          <div
            key={shipment.id}
            role="listitem"
            tabIndex={0}
            className="shipment-row"
            onContextMenu={byPointer(shipment.id)}
            onKeyDown={byKey(shipment.id)}
            style={{
              display: "flex",
              gap: "var(--u-space-3)",
              padding: "var(--u-space-2) var(--u-space-3)",
              borderBottom: "1px solid var(--u-edge-color)",
              background: menu?.id === shipment.id ? "var(--u-color-accent-subtle)" : undefined,
            }}
          >
            <Text as="span" size="sm" mono>
              {shipment.id}
            </Text>
            <Text as="span" size="sm" style={{ flex: 1 }}>
              {shipment.customer}
            </Text>
            <Text as="span" size="sm" tone="muted" mono>
              {shipment.window}
            </Text>
          </div>
        ))}
      </div>
      <ContextMenu
        open={menu !== null}
        position={menu ?? { x: 0, y: 0 }}
        onOpenChange={(open) => {
          if (!open) setMenu(null);
        }}
        ariaLabel={`Actions for shipment ${menu?.id ?? ""}`}
      >
        <MenuItem onSelect={run("Tracked")}>Track the shipment</MenuItem>
        <MenuItem onSelect={run("Rescheduled")}>Move to tomorrow</MenuItem>
        <MenuSeparator />
        <MenuItem tone="danger" onSelect={run("Returned")}>
          Return to sender
        </MenuItem>
      </ContextMenu>
      <Text size="xs" tone="muted">
        Last: {last}
      </Text>
    </Stack>
  );
}
```

#### When to use something else

- The actions have a visible trigger → Menu

#### Keyboard

| Key | Action |
|---|---|
| `↓ / ↑` | Moves to the next or previous entry, wrapping at the ends; disabled entries are skipped. |
| `Home / End` | Moves to the first or last entry. |
| `Escape` | Closes the menu and returns focus to where it was. |
| `Enter or Space` | Runs the focused entry and closes the menu. |
| `Shift+F10 or the menu key` | Opens the menu where you listen for them, as the row example does. |

#### API

##### `ContextMenuProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` *required* | `boolean` | — | Whether the menu stands. Controlled, like `Popover`: a right-click opens it only because the caller says so.<br>Shown in: [Open it at the pointer](#/contextmenu/at-the-pointer), [Open it on a row, by pointer or keyboard](#/contextmenu/on-a-row) |
| `onOpenChange` *required* | `(open: boolean) => void` | — | Reports every wish to change the state – an entry chosen, Escape, an outside click.<br>Shown in: [Open it at the pointer](#/contextmenu/at-the-pointer), [Open it on a row, by pointer or keyboard](#/contextmenu/on-a-row) |
| `position` *required* | `{ x: number; y: number }` | — | Where the menu opens, in client coordinates – typically `clientX` and `clientY` of the event that asked for it. At a window edge the panel flips and clamps as every popover does.<br>Shown in: [Open it at the pointer](#/contextmenu/at-the-pointer), [Open it on a row, by pointer or keyboard](#/contextmenu/on-a-row) |
| `children` *required* | `ReactNode` | — | The entries – `MenuItem` and `MenuSeparator`, as in `Menu`.<br>Shown in: [Open it at the pointer](#/contextmenu/at-the-pointer), [Open it on a row, by pointer or keyboard](#/contextmenu/on-a-row) |

###### Accessibility

| Prop | Type | Default | Description |
|---|---|---|---|
| `ariaLabel` *required* | `string` | — | Accessible name of the menu: what it acts on. A context menu has no trigger whose label could name it.<br>Shown in: [Open it at the pointer](#/contextmenu/at-the-pointer), [Open it on a row, by pointer or keyboard](#/contextmenu/on-a-row) |

#### Known limits

- It listens to no right-click itself: the element that is clicked is yours, and so is the point.
- No submenus, no checkable entries and no type-ahead, as in the menu.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Modal

A window above the page that holds the focus until it is answered or closed (also called a dialog). Reach for it for a short task that interrupts the page: create an item, edit its settings, read a policy.

```ts
import { Modal, ModalHeader, ModalBody, ModalFooter } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/modal/

It is controlled: you hold `open`, and `onClose` reports Escape, the cross and a click on the backdrop. Whether it closes is yours, so a window with unsaved edits can ask first.

The title in `ModalHeader` names the dialog for a screen reader. The height follows the content; where it does not fit, only `ModalBody` scrolls.

It is the browser's modal dialog: focus stays inside, the page behind cannot be scrolled, and focus returns to the opener on closing.

#### Examples

##### A window that holds focus

You hold `open`; `onClose` reports Escape, the cross and a click on the backdrop. The header's title names the dialog.

```tsx
import { useState } from "react";
import { Button, FormField, Grid, Input, Modal, ModalBody, ModalFooter, ModalHeader, Select } from "@umriss-ui/core";

export default function AWindow() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open the modal</Button>
      <Modal open={open} onClose={() => setOpen(false)}>
        <ModalHeader title="Create a project" description="The name, client and lead can be changed later." />
        <ModalBody>
          <Grid minItemWidth="200px" gap={4}>
            <FormField label="Project name" required>
              <Input placeholder="e.g. Member portal" />
            </FormField>
            <FormField label="Client">
              <Input placeholder="e.g. Rowan Credit Union" />
            </FormField>
            <FormField label="Lead">
              <Select defaultValue="">
                <option value="" disabled>
                  Choose a person
                </option>
                <option value="maya">Maya Lindgren</option>
                <option value="luis">Luis Moreno</option>
              </Select>
            </FormField>
          </Grid>
        </ModalBody>
        <ModalFooter>
          <Button onClick={() => setOpen(false)}>Cancel</Button>
          <Button variant="primary" onClick={() => setOpen(false)}>
            Create
          </Button>
        </ModalFooter>
      </Modal>
    </>
  );
}
```

##### Sizes

`size` sets the width – `sm` for a short question, `md` for a form, `lg` for a table or long text; the height follows the content.

```tsx
import { useState } from "react";
import { Button, Modal, ModalBody, ModalFooter, ModalHeader, Stack, Text } from "@umriss-ui/core";
import type { ModalSize } from "@umriss-ui/core";

export default function Sizes() {
  const [size, setSize] = useState<ModalSize | null>(null);

  return (
    <>
      <Stack direction="row" gap={3}>
        {(["sm", "md", "lg"] as const).map((one) => (
          <Button key={one} onClick={() => setSize(one)}>
            Open {one}
          </Button>
        ))}
      </Stack>
      <Modal open={size !== null} onClose={() => setSize(null)} size={size ?? "md"}>
        <ModalHeader title={`A ${size} window`} />
        <ModalBody>
          <Text>Sprint 15 starts on Monday 23 March with the shop's search and filters.</Text>
        </ModalBody>
        <ModalFooter>
          <Button onClick={() => setSize(null)}>Close</Button>
        </ModalFooter>
      </Modal>
    </>
  );
}
```

##### Scroll long content

When the content is taller than the window, only `ModalBody` scrolls; the header and the buttons stay in view.

```tsx
import { useState } from "react";
import { Button, Modal, ModalBody, ModalFooter, ModalHeader, Stack, Text } from "@umriss-ui/core";

const RULES = [
  "Travel is booked through the travel desk, at least two weeks ahead.",
  "Rail is preferred to air for journeys under four hours.",
  "Hotels are reimbursed up to € 140 a night; more needs the cost-centre owner's approval.",
  "Meals are paid at the daily allowance, not against receipts.",
  "Client entertainment is booked to Sales (CC-1100), whoever pays.",
  "Receipts are uploaded within 30 days, or the claim lapses.",
  "Equipment over € 800 is bought through IT (CC-4300), not claimed.",
  "Training needs the approval of People (CC-4200) before booking.",
  "Mileage is paid at € 0.30 a kilometre for a private car.",
  "Claims in another currency use the rate on the day of payment.",
  "Tips are reimbursed up to 10 % of the bill.",
  "A claim is signed off by the cost-centre owner, then by Finance.",
];

export default function LongContent() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Read the expense policy</Button>
      <Modal open={open} onClose={() => setOpen(false)} size="lg">
        <ModalHeader title="Expense policy" description="Valid from 1 January 2026." />
        <ModalBody>
          <Stack gap={4}>
            {RULES.map((rule, index) => (
              <Stack key={rule} gap={1}>
                <Text weight="semibold">§ {index + 1}</Text>
                <Text tone="secondary">{rule}</Text>
              </Stack>
            ))}
          </Stack>
        </ModalBody>
        <ModalFooter>
          <Button onClick={() => setOpen(false)}>Close</Button>
          <Button variant="primary" onClick={() => setOpen(false)}>
            I have read it
          </Button>
        </ModalFooter>
      </Modal>
    </>
  );
}
```

##### Guard unsaved changes

Because `onClose` only reports the wish, a window with edits can ask first instead of throwing them away.

```tsx
import { useState } from "react";
import {
  Button,
  ConfirmDialog,
  FormField,
  Modal,
  ModalBody,
  ModalFooter,
  ModalHeader,
  NumberInput,
  Stack,
  Text,
} from "@umriss-ui/core";

export default function UnsavedChanges() {
  const [open, setOpen] = useState(false);
  const [saved, setSaved] = useState(32);
  const [hours, setHours] = useState<number | null>(32);
  const [asking, setAsking] = useState(false);
  const dirty = hours !== saved;

  const close = () => {
    setOpen(false);
    setAsking(false);
    setHours(saved);
  };

  return (
    <Stack gap={3} align="flex-start">
      <Button
        onClick={() => {
          setHours(saved);
          setOpen(true);
        }}
      >
        Edit Maya's capacity
      </Button>
      <Text size="xs" tone="muted">
        Capacity: {saved} h a week
      </Text>
      <Modal open={open} onClose={() => (dirty ? setAsking(true) : close())} size="sm">
        <ModalHeader title="Maya Lindgren" description="Product manager · Web" />
        <ModalBody>
          <FormField label="Hours a week">
            <NumberInput value={hours} onChange={setHours} min={0} max={40} />
          </FormField>
        </ModalBody>
        <ModalFooter>
          <Button onClick={() => (dirty ? setAsking(true) : close())}>Cancel</Button>
          <Button
            variant="primary"
            onClick={() => {
              if (hours !== null) setSaved(hours);
              setOpen(false);
            }}
          >
            Save
          </Button>
        </ModalFooter>
      </Modal>
      <ConfirmDialog
        open={asking}
        onClose={() => setAsking(false)}
        onConfirm={close}
        tone="danger"
        title="Discard the change?"
        description={`The capacity stays at ${saved} h a week.`}
        confirmLabel="Discard"
        cancelLabel="Keep editing"
      />
    </Stack>
  );
}
```

##### A window that must be answered

`closeOnBackdrop={false}` lets a stray click beside the window pass, and `hideClose` takes the cross off the header: the footer's answers close it, and Escape still does. The same props hold for a `Drawer`.

```tsx
import { useState } from "react";
import { Button, Modal, ModalBody, ModalFooter, ModalHeader, Stack, Text } from "@umriss-ui/core";

export default function MustBeAnswered() {
  const [open, setOpen] = useState(false);
  const [answer, setAnswer] = useState("-");

  const answerWith = (text: string) => {
    setAnswer(text);
    setOpen(false);
  };

  return (
    <Stack gap={3} align="flex-start">
      <Button onClick={() => setOpen(true)}>End my on-call week</Button>
      <Text size="xs" tone="muted">
        Answer: {answer}
      </Text>
      <Modal open={open} onClose={() => setOpen(false)} size="sm" closeOnBackdrop={false}>
        <ModalHeader title="Hand over two open incidents?" hideClose />
        <ModalBody>
          <Text size="sm">INC-1048 and INC-1051 are still open. Luis Moreno is on call next.</Text>
        </ModalBody>
        <ModalFooter>
          <Button onClick={() => answerWith("stayed on call")}>Stay on call</Button>
          <Button variant="primary" onClick={() => answerWith("handed over to Luis Moreno")}>
            Hand over to Luis
          </Button>
        </ModalFooter>
      </Modal>
    </Stack>
  );
}
```

#### When to use something else

- A detail beside the list the user came from → Drawer
- One yes-or-no before something that cannot be undone → ConfirmDialog
- A small panel that should not block the page → Popover

#### Keyboard

| Key | Action |
|---|---|
| `Tab / Shift+Tab` | Moves between the controls inside; focus does not leave the window. |
| `Escape` | Asks to close: `onClose` is called, and the window goes when you close it. |

#### API

##### `ModalProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` *required* | `boolean` | — | Whether the window stands. Controlled: the opening is the caller's decision, and only the caller knows whether something may be open.<br>Shown in: [A window that holds focus](#/modal/a-window), [Sizes](#/modal/sizes), [Scroll long content](#/modal/long-content) and 10 more |
| `size` | [`ModalSize`](#type-ModalSize)<br>`"sm" \| "md" \| "lg"` | `"md"` | The width of the window. The height comes from the content; only the body scrolls, header and footer stand fast.<br>Shown in: [Sizes](#/modal/sizes), [Scroll long content](#/modal/long-content), [Guard unsaved changes](#/modal/unsaved-changes) and 3 more |
| `closeOnBackdrop` | `boolean` | `true` | Closes on a click on the backdrop.<br>Shown in: [A window that must be answered](#/modal/must-be-answered) |
| `ref` | `Ref<HTMLDialogElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onClose` *required* | `() => void` | — | Reports every wish to close – Escape, cross, backdrop click.<br>Shown in: [A window that holds focus](#/modal/a-window), [Sizes](#/modal/sizes), [Scroll long content](#/modal/long-content) and 10 more |

Also takes every attribute of `<dialog>` – without `onClose`.

##### `ModalHeaderProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` *required* | `ReactNode` | — | The heading of the window. It names it for the screen reader at the same time – a dialog without a name says only "dialog".<br>Shown in: [A window that holds focus](#/modal/a-window), [Sizes](#/modal/sizes), [Scroll long content](#/modal/long-content) and 10 more |
| `description` | `ReactNode` | — | One sentence below the heading: what is to be decided here.<br>Shown in: [A window that holds focus](#/modal/a-window), [Scroll long content](#/modal/long-content), [Guard unsaved changes](#/modal/unsaved-changes) and 8 more |
| `hideClose` | `boolean` | `false` | Hides the close button.<br>Shown in: [A window that must be answered](#/modal/must-be-answered) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>` – without `title`.

##### Types on this page

###### `ModalSize`

The width of a `Modal`.

```ts
type ModalSize = "sm" | "md" | "lg";
```

#### Known limits

- No non-modal window and no dragging or resizing: a panel that leaves the page usable is layout – a [Splitter](#/splitter).

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Drawer

A modal window that slides in from the left or right edge of the screen (also called a side sheet or side panel). Reach for it for the detail of something picked from a list, while the list stays in sight behind it.

```ts
import { Drawer, ModalHeader, ModalBody, ModalFooter } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/drawer/

Everything the modal promises holds: the focus stays inside, Escape and a click beside it ask to close, and the focus returns to the button that opened it. Header, body and footer are the modal's parts.

Its width is the token `--u-drawer-width`: set it once for the application, or in one drawer's `style` where it needs more room.

#### Examples

##### A detail from the edge

A `Drawer` is a `Modal` at the right edge, with the same header, body and footer and the same hold on focus.

```tsx
import { useState } from "react";
import { Button, Drawer, ModalBody, ModalFooter, ModalHeader, Text } from "@umriss-ui/core";

export default function ADetailFromTheEdge() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Show the shipment</Button>
      <Drawer open={open} onClose={() => setOpen(false)}>
        <ModalHeader title="Shipment SH-1042" description="Harlow Bakery · out for delivery on tour T-01" />
        <ModalBody>
          <Text>Two parcels, 14 kg in all, to be delivered between 09:00 and 11:00.</Text>
        </ModalBody>
        <ModalFooter>
          <Button onClick={() => setOpen(false)}>Close</Button>
        </ModalFooter>
      </Drawer>
    </>
  );
}
```

##### From the left, and wider

`side` set to `left` puts it at the other edge; one drawer that needs more room sets `--u-drawer-width` in its own `style`.

```tsx
import { useState } from "react";
import type { CSSProperties } from "react";
import { Button, Checkbox, Drawer, ModalBody, ModalFooter, ModalHeader, Stack, Text } from "@umriss-ui/core";

const TEAMS = ["Payments", "Identity", "Discovery", "Messaging", "Integrations", "Insights"];

export default function LeftAndWider() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Filter the alerts</Button>
      <Drawer open={open} onClose={() => setOpen(false)} side="left" style={{ "--u-drawer-width": "480px" } as CSSProperties}>
        <ModalHeader title="Filter" description="Which alerts the list shows." />
        <ModalBody>
          <Stack gap={3}>
            <Text size="sm" weight="medium">
              Owning team
            </Text>
            {TEAMS.map((team) => (
              <Checkbox key={team} label={team} defaultChecked={team === "Payments" || team === "Identity"} />
            ))}
            <Text size="sm" weight="medium">
              Priority
            </Text>
            <Checkbox label="High – pages the on-call engineer at any hour" defaultChecked />
            <Checkbox label="Medium – pages during working hours, otherwise waits" defaultChecked />
            <Checkbox label="Low – collected into the morning's summary" />
          </Stack>
        </ModalBody>
        <ModalFooter>
          <Button onClick={() => setOpen(false)}>Cancel</Button>
          <Button variant="primary" onClick={() => setOpen(false)}>
            Apply
          </Button>
        </ModalFooter>
      </Drawer>
    </>
  );
}
```

##### Open a service's detail from its list

The list stays in sight behind the backdrop; which service is open is your state, and the drawer only shows it.

```tsx
import { useState } from "react";
import { Badge, Button, Drawer, Grid, Meter, ModalBody, ModalFooter, ModalHeader, Stack, Stat, Switch, Text } from "@umriss-ui/core";
import type { LimitSet } from "@umriss-ui/core";

/* Data from the operations world, written out here so the example runs on its own. */
/** A small LCG - the same numbers on every computer. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

const at = (day: number, hours: number, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();
const MINUTE = 60_000;

/** Tuesday, 17 March 2026, 10:30 - the moment the screens are read at. */
const NOW = at(17, 10, 30);

interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface MetricPoint {
  t: number;
  /** Median and 95th percentile latency, in ms. */
  p50: number;
  p95: number;
  /** Failed requests, in per cent. */
  errorRate: number;
  /** Requests per minute. */
  requests: number;
}

/** Requests per minute at the busiest hour, by tier. */
const VOLUME = { 1: 900, 2: 400, 3: 120 } as const;

/** A service's latency and error rate every five minutes of today, from
    midnight up to now. Busy by day, quiet at night; Checkout's 95th percentile
    climbs well past its objective from 09:40 to 10:10, and its errors with it. */
function metrics(serviceId: string): MetricPoint[] {
  const index = SERVICES.findIndex((one) => one.id === serviceId);
  const service = SERVICES[index];
  if (service === undefined) throw new Error(`No service "${serviceId}".`);
  const r = random(1000 + index * 37);
  const points: MetricPoint[] = [];
  let drift = 0;
  for (let t = at(17, 0); t <= NOW; t += 5 * MINUTE) {
    const hour = (t - at(17, 0)) / (60 * MINUTE);
    const load = 0.35 + 0.65 * Math.max(0, Math.sin((Math.PI * (hour - 5)) / 16));
    drift = 0.8 * drift + (r() - 0.5) * 0.08;
    const base = service.latencySlo * (0.45 + 0.2 * load + drift);
    const surge = serviceId === "checkout" && t >= at(17, 9, 40) && t < at(17, 10, 10) ? 1.9 : 1;
    const p95 = Math.round(base * surge * (1 + r() * 0.08));
    points.push({
      t,
      p50: Math.round(p95 * (0.42 + r() * 0.06)),
      p95,
      errorRate: Math.round((0.05 + r() * 0.12 + (surge > 1 ? 2.4 + r() : 0)) * 100) / 100,
      requests: Math.round(VOLUME[service.tier] * load * (1 + (r() - 0.5) * 0.1)),
    });
  }
  return points;
}

/** The month so far: 1 March 00:00 to now, in minutes. */
const MONTH_MINUTES = (NOW - at(1, 0)) / MINUTE;

/** Minutes each service was down this month. With `MONTH_MINUTES` and the
    service's target, what an availability is worked out from. */
const DOWNTIME_MINUTES: Readonly<Record<string, number>> = {
  checkout: 34,
  billing: 18,
  "sign-in": 41,
  search: 85,
  images: 120,
  notifications: 12,
  webhooks: 210,
  reports: 95,
};

/** The latency objective as a rule: warn at 80 %, alarm at the objective itself. */
function latencyLimits(service: Service): LimitSet {
  return {
    limits: [
      { value: service.latencySlo * 0.8, side: "upper", severity: "warning" },
      { value: service.latencySlo, side: "upper", severity: "alarm" },
    ],
  };
}

/** How much of the month's allowed downtime is used up. */
function budgetUsed(service: Service): number {
  const allowed = MONTH_MINUTES * (1 - service.availabilityTarget / 100);
  return (DOWNTIME_MINUTES[service.id] ?? 0) / allowed;
}

export default function BesideAServiceList() {
  const [openId, setOpenId] = useState<string | null>(null);
  const service = SERVICES.find((one) => one.id === openId);
  const points = service ? metrics(service.id).slice(-24) : [];
  const used = service ? budgetUsed(service) : 0;

  return (
    <>
      <Grid minItemWidth="150px" gap={3}>
        {SERVICES.map((one) => (
          <Button key={one.id} onClick={() => setOpenId(one.id)}>
            {one.name}
          </Button>
        ))}
      </Grid>
      <Drawer open={service !== undefined} onClose={() => setOpenId(null)}>
        {service && (
          <>
            <ModalHeader title={service.name} description={`${service.team} · tier ${service.tier}`} />
            <ModalBody>
              <Stack gap={5}>
                <Stat
                  label="p95 latency, last two hours"
                  value={points.at(-1)?.p95}
                  unit="ms"
                  decimals={0}
                  limits={latencyLimits(service)}
                  history={points.map((point) => point.p95)}
                />
                <Stack gap={1}>
                  <Text size="xs" tone="muted">
                    Downtime budget used this month
                  </Text>
                  <Meter
                    value={used}
                    tone={used >= 1 ? "danger" : used >= 0.75 ? "warning" : "neutral"}
                    showLabel
                    label={`Downtime budget of ${service.name}`}
                  />
                  <Text size="xs" tone="muted">
                    {DOWNTIME_MINUTES[service.id]} min down, target {service.availabilityTarget} %
                  </Text>
                </Stack>
                <Stack gap={1} align="flex-start">
                  <Text size="xs" tone="muted">
                    Alerts
                  </Text>
                  <Badge tone={service.tier === 1 ? "accent" : "neutral"}>{service.tier === 1 ? "Pages at night" : "Waits for the morning"}</Badge>
                </Stack>
                <Switch label="Page the on-call engineer" defaultChecked={service.tier === 1} />
              </Stack>
            </ModalBody>
            <ModalFooter>
              <Button onClick={() => setOpenId(null)}>Close</Button>
              <Button variant="primary" onClick={() => setOpenId(null)}>
                Open the runbook
              </Button>
            </ModalFooter>
          </>
        )}
      </Drawer>
    </>
  );
}
```

#### When to use something else

- A task that has nothing to do with what lies behind it → Modal
- A side panel that stays open while the page is used → Splitter

#### Keyboard

| Key | Action |
|---|---|
| `Tab / Shift+Tab` | Moves between the controls inside; focus does not leave the window. |
| `Escape` | Asks to close: `onClose` is called, and the window goes when you close it. |

#### API

##### `DrawerProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `side` | `"right" \| "left"` | `"right"` | The edge the drawer stands at and enters from.<br>Shown in: [From the left, and wider](#/drawer/left-and-wider) |
| `open` *required* | `boolean` | — | Whether the window stands. Controlled: the opening is the caller's decision, and only the caller knows whether something may be open. From `ModalProps`.<br>Shown in: [A detail from the edge](#/drawer/a-detail-from-the-edge), [From the left, and wider](#/drawer/left-and-wider), [Open a service's detail from its list](#/drawer/beside-a-service-list) and 10 more |
| `closeOnBackdrop` | `boolean` | `true` | Closes on a click on the backdrop. From `ModalProps`.<br>Shown in: [A window that must be answered (Modal)](#/modal/must-be-answered) |
| `ref` | `Ref<HTMLDialogElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onClose` *required* | `() => void` | — | Reports every wish to close – Escape, cross, backdrop click. From `ModalProps`.<br>Shown in: [A detail from the edge](#/drawer/a-detail-from-the-edge), [From the left, and wider](#/drawer/left-and-wider), [Open a service's detail from its list](#/drawer/beside-a-service-list) and 10 more |

Also takes every attribute of `<dialog>` – without `onClose`.

#### Known limits

- Modal on purpose, with no non-modal mode: a panel beside a page the user keeps working in is layout, not an overlay.
- Only the left and right edges; nothing slides in from the top or bottom.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### ConfirmDialog

A small modal window with one question and two buttons, for the moment before something that cannot be undone (also called a confirmation). Reach for it before deleting, rejecting or closing for good.

```ts
import { ConfirmDialog } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/confirmdialog/

Use it only where the step cannot be taken back: a question before every action gets clicked away, and then it no longer protects the one that mattered.

It does not close itself on `onConfirm`, so you can show `loading` while the request runs. Cancelling, by Escape, the cross or the second button, calls `onClose`.

#### Examples

##### The one question

The `description` says what cannot be undone, and `confirmLabel` names the action – “Delete” says what happens, “OK” does not.

```tsx
import { useState } from "react";
import { Button, ConfirmDialog, Stack, Text } from "@umriss-ui/core";

export default function TheOneQuestion() {
  const [open, setOpen] = useState(false);
  const [state, setState] = useState("Draft invoice INV-26-0319 exists.");

  return (
    <Stack gap={3} align="flex-start">
      <Button variant="danger" onClick={() => setOpen(true)}>
        Delete the draft
      </Button>
      <Text size="xs" tone="muted">
        {state}
      </Text>
      <ConfirmDialog
        open={open}
        onClose={() => setOpen(false)}
        onConfirm={() => {
          setState("Draft invoice INV-26-0319 is deleted.");
          setOpen(false);
        }}
        tone="danger"
        title="Delete draft invoice INV-26-0319?"
        description="Its three lines and the attached delivery note go with it. This cannot be undone."
        confirmLabel="Delete"
      />
    </Stack>
  );
}
```

##### Ask before a commitment

Not every irreversible step destroys something: the `primary` tone asks before closing a month, which then accepts no postings.

```tsx
import { useState } from "react";
import { Button, ConfirmDialog, Stack, Text } from "@umriss-ui/core";

export default function ACommitment() {
  const [open, setOpen] = useState(false);
  const [closed, setClosed] = useState(false);

  return (
    <Stack gap={3} align="flex-start">
      <Button variant="primary" disabled={closed} onClick={() => setOpen(true)}>
        Close February
      </Button>
      <Text size="xs" tone="muted">
        February 2026 is {closed ? "closed" : "open for postings"}.
      </Text>
      <ConfirmDialog
        open={open}
        onClose={() => setOpen(false)}
        onConfirm={() => {
          setClosed(true);
          setOpen(false);
        }}
        tone="primary"
        title="Close February 2026?"
        description="Actuals for February can no longer be posted or corrected; late invoices go to March."
        confirmLabel="Close the month"
      />
    </Stack>
  );
}
```

##### Stay open while it runs

The dialog does not close itself on `onConfirm`; set `loading` while the request runs and close it when it is done.

```tsx
import { useEffect, useState } from "react";
import { Button, ConfirmDialog, Stack, Text } from "@umriss-ui/core";

export default function WhileItRuns() {
  const [open, setOpen] = useState(false);
  const [running, setRunning] = useState(false);
  const [rejected, setRejected] = useState(false);

  useEffect(() => {
    if (!running) return;
    const timer = setTimeout(() => {
      setRunning(false);
      setRejected(true);
      setOpen(false);
    }, 1500);
    return () => clearTimeout(timer);
  }, [running]);

  return (
    <Stack gap={3} align="flex-start">
      <Button variant="danger" disabled={rejected} onClick={() => setOpen(true)}>
        Reject the invoice
      </Button>
      <Text size="xs" tone="muted">
        INV-26-0317 from Kettering &amp; Shaw Events is {rejected ? "rejected" : "awaiting approval"}.
      </Text>
      <ConfirmDialog
        open={open}
        onClose={() => setOpen(false)}
        onConfirm={() => setRunning(true)}
        loading={running}
        tone="danger"
        title="Reject invoice INV-26-0317?"
        description="The supplier is told by e-mail and must send a new invoice."
        confirmLabel="Reject"
      />
    </Stack>
  );
}
```

#### When to use something else

- The user fills in fields before confirming → Modal
- The action can be undone afterwards → Do it, and confirm it with a [Toast](#/toast)

#### Keyboard

| Key | Action |
|---|---|
| `Tab / Shift+Tab` | Moves between the controls inside; focus does not leave the window. |
| `Escape` | Asks to close: `onClose` is called, and the window goes when you close it. |
| `Enter or Space` | Presses the focused button. |

#### API

##### `ConfirmDialogProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` *required* | `boolean` | — | Whether the query stands.<br>Shown in: [The one question](#/confirmdialog/the-one-question), [Ask before a commitment](#/confirmdialog/a-commitment), [Stay open while it runs](#/confirmdialog/while-it-runs) and 3 more |
| `title` *required* | `ReactNode` | — | The question, as a statement: "Delete invoice 2041?".<br>Shown in: [The one question](#/confirmdialog/the-one-question), [Ask before a commitment](#/confirmdialog/a-commitment), [Stay open while it runs](#/confirmdialog/while-it-runs) and 3 more |
| `description` | `ReactNode` | — | What about it cannot be taken back. The most important line of the dialog.<br>Shown in: [The one question](#/confirmdialog/the-one-question), [Ask before a commitment](#/confirmdialog/a-commitment), [Stay open while it runs](#/confirmdialog/while-it-runs) and 3 more |
| `confirmLabel` | `string` | the wording's "Confirm" | Label of the agreeing button. Better is the verb of the action: "Delete" says what is about to happen.<br>Shown in: [The one question](#/confirmdialog/the-one-question), [Ask before a commitment](#/confirmdialog/a-commitment), [Stay open while it runs](#/confirmdialog/while-it-runs) and 3 more |
| `cancelLabel` | `string` | the wording's "Cancel" | Label of the cancelling button.<br>Shown in: [Guard unsaved changes (Modal)](#/modal/unsaved-changes) |
| `tone` | `"primary" \| "danger"` | `"primary"` | "danger" for destructive actions.<br>Shown in: [The one question](#/confirmdialog/the-one-question), [Ask before a commitment](#/confirmdialog/a-commitment), [Stay open while it runs](#/confirmdialog/while-it-runs) and 2 more |
| `loading` | `boolean` | `false` | Locks the actions while the confirmation is running.<br>Shown in: [Stay open while it runs](#/confirmdialog/while-it-runs) |
| `ref` | `Ref<HTMLDialogElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onClose` *required* | `() => void` | — | Cancelling: Escape, cross, backdrop or the second button.<br>Shown in: [The one question](#/confirmdialog/the-one-question), [Ask before a commitment](#/confirmdialog/a-commitment), [Stay open while it runs](#/confirmdialog/while-it-runs) and 3 more |
| `onConfirm` *required* | `() => void` | — | Agreeing. The dialog does not close itself from that – whoever wants to show a confirmation in progress still needs it.<br>Shown in: [The one question](#/confirmdialog/the-one-question), [Ask before a commitment](#/confirmdialog/a-commitment), [Stay open while it runs](#/confirmdialog/while-it-runs) and 3 more |

Also takes every attribute of `<dialog>` – without `children`, `onClose`, `open`, `title`.

#### Known limits

- A title, a description and two buttons, nothing more: fields belong in a [Modal](#/modal).

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### CommandPalette

A search field above the page that finds commands and places as you type (also called a command menu or quick switcher). Reach for it when an application has more actions and pages than any menu can show.

```ts
import { CommandPalette, useCommandPaletteShortcut } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/commandpalette/

It matches by subsequence, not by substring: “ack” finds “Acknowledge the alert”, and the matched letters are marked so an unexpected find explains itself. A candidate's group is searched too.

A candidate is an id, a label and a group; what happens on choosing is yours, so pages and commands live in one list.

Without `restingItems` the empty palette is only the field. The library keeps no memory: pass recent choices as `restingItems` and rank them with `weight`.

#### Examples

##### Run a command

Typing finds candidates by subsequence – “ack” finds “Acknowledge the alert”; `onChoose` reports the id and you decide what happens.

```tsx
import { useState } from "react";
import { Button, CommandPalette, Stack, Text } from "@umriss-ui/core";

const COMMANDS = [
  { id: "ack", label: "Acknowledge the alert", group: "Incident INC-1048" },
  { id: "page", label: "Page the secondary on call", group: "Incident INC-1048" },
  { id: "status", label: "Post a status update", group: "Incident INC-1048" },
  { id: "resolve", label: "Resolve the incident", group: "Incident INC-1048" },
  { id: "checkout", label: "Open Checkout", group: "Services" },
  { id: "billing", label: "Open Billing", group: "Services" },
  { id: "rota", label: "Show this week's on-call rota", group: "People" },
];

export default function Commands() {
  const [open, setOpen] = useState(false);
  const [last, setLast] = useState("-");

  return (
    <Stack gap={3} align="flex-start">
      <Button onClick={() => setOpen(true)}>Open the palette</Button>
      <Text size="xs" tone="muted">
        Last run: {last}
      </Text>
      <CommandPalette
        open={open}
        onClose={() => setOpen(false)}
        items={COMMANDS}
        restingItems={COMMANDS}
        onChoose={(id) => {
          setOpen(false);
          setLast(COMMANDS.find((c) => c.id === id)?.label ?? id);
        }}
      />
    </Stack>
  );
}
```

##### Show recent choices first

`restingItems` fills the empty palette with the last three choices, and a `weight` ranks them higher while typing; the memory is yours.

```tsx
import { useState } from "react";
import { Button, CommandPalette, Stack, Text } from "@umriss-ui/core";
import type { CommandPaletteItem } from "@umriss-ui/core";

const PLACES: CommandPaletteItem[] = [
  { id: "CC-1100", label: "Sales", group: "Cost centres" },
  { id: "CC-1200", label: "Marketing", group: "Cost centres" },
  { id: "CC-2100", label: "Engineering", group: "Cost centres" },
  { id: "CC-3100", label: "Customer service", group: "Cost centres" },
  { id: "CC-4300", label: "IT", group: "Cost centres" },
  { id: "INV-26-0318", label: "INV-26-0318 Brandlow Office Supply", group: "Invoices" },
  { id: "INV-26-0317", label: "INV-26-0317 Kettering & Shaw Events", group: "Invoices" },
];

export default function RecentFirst() {
  const [open, setOpen] = useState(false);
  const [recent, setRecent] = useState<string[]>(["CC-1200", "INV-26-0317"]);

  const items = PLACES.map((place) => (recent.includes(place.id) ? { ...place, weight: 2 } : place));
  const resting = recent.map((id) => items.find((item) => item.id === id)!).map((item) => ({ ...item, group: "Recent" }));

  return (
    <Stack gap={3} align="flex-start">
      <Button onClick={() => setOpen(true)}>Go to …</Button>
      <Text size="xs" tone="muted">
        Recent: {recent.join(", ")}
      </Text>
      <CommandPalette
        open={open}
        onClose={() => setOpen(false)}
        items={items}
        restingItems={resting}
        onChoose={(id) => {
          setOpen(false);
          setRecent((list) => [id, ...list.filter((one) => one !== id)].slice(0, 3));
        }}
      />
    </Stack>
  );
}
```

##### Open it with a shortcut

[`useCommandPaletteShortcut`](#/api/useCommandPaletteShortcut) binds Cmd-K or Ctrl-K and “/” – except inside a text field, where a slash stays a slash.

```tsx
import { useCallback, useState } from "react";
import { CommandPalette, Input, Stack, Text, useCommandPaletteShortcut } from "@umriss-ui/core";

const PROJECTS = [
  { id: "shop", label: "Online shop relaunch", group: "Pembury Home" },
  { id: "booking", label: "Booking app", group: "Saltmarsh Clinics" },
  { id: "portal", label: "Member portal", group: "Rowan Credit Union" },
  { id: "intranet", label: "Intranet", group: "Tidewell (internal)" },
];

export default function Shortcut() {
  const [open, setOpen] = useState(false);
  const [text, setText] = useState("");
  const [project, setProject] = useState("-");

  useCommandPaletteShortcut(useCallback(() => setOpen(true), []));

  return (
    <Stack gap={3} align="flex-start">
      <Text size="sm" tone="secondary">
        Press Cmd-K, Ctrl-K or “/” to jump to a project. Current: {project}
      </Text>
      <Input
        size="sm"
        aria-label="Here a slash stays a slash"
        value={text}
        onChange={(event) => setText(event.target.value)}
        placeholder="Type “/” here"
      />
      <CommandPalette
        open={open}
        onClose={() => setOpen(false)}
        items={PROJECTS}
        onChoose={(id) => {
          setOpen(false);
          setProject(PROJECTS.find((p) => p.id === id)?.label ?? id);
        }}
      />
    </Stack>
  );
}
```

##### Find a command by its synonyms

`keywords` lets “snooze” find “Mute the alert for an hour”: they are searched after the label and the group, as a run of three letters or more, and their finds stand last and unmarked.

```tsx
import { useState } from "react";
import { Button, CommandPalette, Stack, Text } from "@umriss-ui/core";
import type { CommandPaletteItem } from "@umriss-ui/core";

const COMMANDS: CommandPaletteItem[] = [
  { id: "mute", label: "Mute the alert for an hour", group: "Incident INC-1048", keywords: ["snooze", "silence"] },
  { id: "page", label: "Page the secondary on call", group: "Incident INC-1048", keywords: ["escalate", "notify"] },
  { id: "status", label: "Post a status update", group: "Incident INC-1048", keywords: ["announce", "broadcast"] },
  { id: "resolve", label: "Resolve the incident", group: "Incident INC-1048", keywords: ["close", "done"] },
];

export default function Synonyms() {
  const [open, setOpen] = useState(false);
  const [last, setLast] = useState("-");

  return (
    <Stack gap={3} align="flex-start">
      <Button onClick={() => setOpen(true)}>Find a command</Button>
      <Text size="xs" tone="muted">
        Try “snooze”, “escalate” or “close”. Last run: {last}
      </Text>
      <CommandPalette
        open={open}
        onClose={() => setOpen(false)}
        items={COMMANDS}
        onChoose={(id) => {
          setOpen(false);
          setLast(COMMANDS.find((c) => c.id === id)?.label ?? id);
        }}
      />
    </Stack>
  );
}
```

##### Search hundreds of pages

A row's `icon` tells a page from an example. `searchedGroup` searches only “Inputs” of “core · Inputs”, so typing “core” does not find every candidate, and `maxFinds` draws the first fifty finds and says how many more there are - type “s” to see the line.

```tsx
import { useState } from "react";
import { AngleGlyph, Button, CommandPalette, GridGlyph, Stack, Text, type CommandPaletteItem } from "@umriss-ui/core";

const PAGES: Record<string, string[]> = {
  "core · Inputs": ["Button", "Input", "Textarea", "Select", "Combobox", "MultiSelect", "Checkbox", "Switch", "Slider", "NumberInput"],
  "core · Overlays": ["Modal", "Drawer", "Popover", "Tooltip", "Menu", "Toast", "CommandPalette"],
  "core · Layout": ["Stack", "Grid", "Card", "Splitter", "Tabs", "Accordion", "Divider"],
  "charts · Series": ["Line", "Area", "Bar", "Scatter", "BoxPlot", "Matrix"],
  "table · Features": ["Sorting", "Filter", "Grouping", "Selection", "Pagination", "Export"],
};
const EXAMPLES = ["A first one", "Sizes", "States", "With an error", "In a form"];

/* Every page and five examples each: some two hundred candidates. */
const ITEMS = Object.entries(PAGES).flatMap(([group, pages]) => {
  const searchedGroup = group.slice(group.indexOf(" · ") + 3);
  return pages.flatMap((page): CommandPaletteItem[] => [
    { id: page, label: page, group, searchedGroup, icon: <GridGlyph /> },
    ...EXAMPLES.map((example) => ({ id: `${page}/${example}`, label: `${page}: ${example}`, group, searchedGroup, icon: <AngleGlyph /> })),
  ]);
});

export default function SearchHundredsOfPages() {
  const [open, setOpen] = useState(false);
  const [last, setLast] = useState("-");

  return (
    <Stack gap={3} align="flex-start">
      <Button onClick={() => setOpen(true)}>Search the docs</Button>
      <Text size="xs" tone="muted">
        {ITEMS.length} candidates · last opened: {last}
      </Text>
      <CommandPalette
        open={open}
        onClose={() => setOpen(false)}
        items={ITEMS}
        maxFinds={50}
        onChoose={(id) => {
          setOpen(false);
          setLast(id);
        }}
      />
    </Stack>
  );
}
```

#### When to use something else

- A value for a form field, chosen from a list → Combobox
- A few actions under one button → Menu

#### Keyboard

| Key | Action |
|---|---|
| `Cmd+K / Ctrl+K` | Opens the palette, with [`useCommandPaletteShortcut`](#/api/useCommandPaletteShortcut). |
| `/` | Opens the palette too, except while typing in a text field. |
| `↓ / ↑` | Moves through the finds while the field keeps the focus. |
| `Enter` | Chooses the marked find. |
| `Escape` | Closes the palette. |

#### API

##### `CommandPaletteProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `open` *required* | `boolean` | — | Controlled like the modal: opening is the caller's decision.<br>Shown in: [Run a command](#/commandpalette/commands), [Show recent choices first](#/commandpalette/recent-first), [Open it with a shortcut](#/commandpalette/shortcut) and 2 more |
| `items` *required* | `readonly `[`CommandPaletteItem`](#type-CommandPaletteItem)`[]` | — | The candidates that are searched. They belong to the caller: the palette keeps no memory and does not reorder them.<br>Shown in: [Run a command](#/commandpalette/commands), [Show recent choices first](#/commandpalette/recent-first), [Open it with a shortcut](#/commandpalette/shortcut) and 2 more |
| `restingItems` | `readonly `[`CommandPaletteItem`](#type-CommandPaletteItem)`[]` | — | What stands there as long as nothing is typed. Without a value: nothing, and the window is only the field. A LIST and not a switch, because the interesting question is not "all or none" but "which". Whoever really wants to show everything passes `restingItems={items}`; whoever wants to show the five most recently used passes those - and a switch cannot do that. With long lists "all" is also exactly the state this component did away with: a list that is already full can only shrink. The rows stand in THIS order and without marks: without a query there is no rank and nothing to mark. Rank and weight therefore play no part here; the order belongs to the caller.<br>Shown in: [Run a command](#/commandpalette/commands), [Show recent choices first](#/commandpalette/recent-first) |
| `maxFinds` | `number` | every find | The most finds that stand at once - the best by rank. A last line says how many more there are, and typing on narrows them. For a long list of candidates, where a single letter finds hundreds and drawing them all would make every keystroke wait.<br>Shown in: [Search hundreds of pages](#/commandpalette/search-hundreds-of-pages) |
| `ref` | `Ref<HTMLDialogElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onClose` *required* | `() => void` | — | Reports every wish to close - Escape, an outside click, a choice.<br>Shown in: [Run a command](#/commandpalette/commands), [Show recent choices first](#/commandpalette/recent-first), [Open it with a shortcut](#/commandpalette/shortcut) and 2 more |
| `onChoose` *required* | `(id: string) => void` | — | Reports the `id` of the chosen candidate. What happens next is the caller's decision - that is exactly what keeps places and commands together.<br>Shown in: [Run a command](#/commandpalette/commands), [Show recent choices first](#/commandpalette/recent-first), [Open it with a shortcut](#/commandpalette/shortcut) and 2 more |

Also takes every attribute of `<dialog>` – without `children`, `onClose`, `open`.

##### `CommandPaletteItem`

| Prop | Type | Default | Description |
|---|---|---|---|
| `id` *required* | `string` | — | What is reported on choosing.<br>Shown in: [Show recent choices first](#/commandpalette/recent-first), [Find a command by its synonyms](#/commandpalette/synonyms), [Search hundreds of pages](#/commandpalette/search-hundreds-of-pages) |
| `label` *required* | `string` | — | What is searched and displayed.<br>Shown in: [Show recent choices first](#/commandpalette/recent-first), [Find a command by its synonyms](#/commandpalette/synonyms), [Search hundreds of pages](#/commandpalette/search-hundreds-of-pages) |
| `group` | `string` | — | The heading the candidate stands under. It is searched as well.<br>Shown in: [Show recent choices first](#/commandpalette/recent-first), [Find a command by its synonyms](#/commandpalette/synonyms), [Search hundreds of pages](#/commandpalette/search-hundreds-of-pages) |
| `searchedGroup` | `string` | the whole `group` | The part of `group` that is searched, where not all of it should be: a prefix every candidate of a set shares - `core · ` before `core · Inputs` - would otherwise let its few letters find the whole set.<br>Shown in: [Search hundreds of pages](#/commandpalette/search-hundreds-of-pages) |
| `icon` | `ReactNode` | — | Optional glyph on the left of the row.<br>Shown in: [Search hundreds of pages](#/commandpalette/search-hundreds-of-pages) |
| `weight` | `number` | — | Added to the rank. With it frequency or recency can be expressed - the library deliberately keeps no memory for that.<br>Shown in: [Show recent choices first](#/commandpalette/recent-first) |
| `keywords` | `readonly string[]` | — | More words the candidate is found by, such as synonyms - searched but never shown. Only when neither `label` nor `group` matched, only for a query of three characters or more, and as a contiguous run, not as a subsequence. A find through them stands behind every find in a label or a group and marks nothing.<br>Shown in: [Find a command by its synonyms](#/commandpalette/synonyms) |

#### Known limits

- No memory of past choices and no ranking of its own beyond the match: recency and frequency are weights you keep.
- No nested steps or arguments: a command that needs input opens your own form after it is chosen.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

## Navigation

How a user finds their way through a screen and between screens.

### Breadcrumb

Shows where the current page sits in a hierarchy and leads back up to any level above it (also called a trail or path). Where the trail runs out of room, its middle levels fold into a menu.

```ts
import { Breadcrumb } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/breadcrumb/

The last level is the current page: marked as such and not a link. Routing is yours: a level with an `href` alone is followed by the browser, one with `onSelect` runs your router instead.

#### Examples

##### A trail

Pass the `items` from the top down; the last is the current page, marked as such and not a link.

```tsx
import { Breadcrumb } from "@umriss-ui/core";

export default function ATrail() {
  return (
    <Breadcrumb
      items={[
        { label: "Finance", href: "#/breadcrumb" },
        { label: "Cost centres", href: "#/breadcrumb" },
        { label: "Marketing, CC-1200" },
      ]}
    />
  );
}
```

##### Route it yourself

Give a level `onSelect` and your router runs instead of the browser; with an `href` beside it, a middle click still opens a tab.

```tsx
import { useState } from "react";
import { Breadcrumb, Button, Stack, Text } from "@umriss-ui/core";

const PATH = ["North depot", "Tour T-01", "Stop 4", "Shipment FP-1004249"];

export default function RouteItYourself() {
  const [depth, setDepth] = useState(PATH.length);
  const trail = PATH.slice(0, depth);

  return (
    <Stack gap={3} align="flex-start">
      <Breadcrumb
        items={trail.map((label, i) => ({ label, onSelect: () => setDepth(i + 1) }))}
        style={{ alignSelf: "stretch" }}
      />
      <Text size="xs" tone="muted">
        Page: {trail[trail.length - 1]}
      </Text>
      <Button size="sm" disabled={depth === PATH.length} onClick={() => setDepth(PATH.length)}>
        Back to the shipment
      </Button>
    </Stack>
  );
}
```

##### Fold when narrow

A long trail in a narrow place folds its middle levels into a menu, measured, keeping the first level and the current page.

```tsx
import { Breadcrumb, Card, CardBody, Stack, Text } from "@umriss-ui/core";

const TRAIL = [
  { label: "Quillmere", href: "#/breadcrumb" },
  { label: "Services", href: "#/breadcrumb" },
  { label: "Payments", href: "#/breadcrumb" },
  { label: "Checkout", href: "#/breadcrumb" },
  { label: "Incidents", href: "#/breadcrumb" },
  { label: "INC-1048", href: "#/breadcrumb" },
  { label: "Timeline" },
];

export default function FoldWhenNarrow() {
  return (
    <Stack gap={4}>
      {[300, 480].map((width) => (
        <Card key={width} style={{ width: "100%", maxWidth: width }}>
          <CardBody>
            <Stack gap={2}>
              <Text size="xs" tone="muted">
                Up to {width} pixels
              </Text>
              <Breadcrumb items={TRAIL} />
            </Stack>
          </CardBody>
        </Card>
      ))}
    </Stack>
  );
}
```

##### Browse down and back up

Each level opens the next and the trail is the way back; narrow it with the slider to watch the fold measure itself.

```tsx
import { useState } from "react";
import { Breadcrumb, Button, Card, CardBody, FormField, Grid, Heading, Slider, Stack, Text } from "@umriss-ui/core";

/* Data from the controlling world, written out here so the example runs on its own. */
const on = (month: number, day: number) => new Date(2026, month - 1, day).getTime();

interface CostCentre {
  id: string;
  name: string;
  owner: string;
  /** The budget of one month. */
  monthlyBudget: number;
}

const COST_CENTRES: readonly CostCentre[] = [
  { id: "CC-1100", name: "Sales", owner: "Helen Marsh", monthlyBudget: 142_000 },
  { id: "CC-1200", name: "Marketing", owner: "Rafael Ortiz", monthlyBudget: 68_000 },
  { id: "CC-2100", name: "Engineering", owner: "Anika Sørensen", monthlyBudget: 188_000 },
  { id: "CC-2200", name: "Design", owner: "Paul Whitaker", monthlyBudget: 54_000 },
  { id: "CC-3100", name: "Customer service", owner: "Grace Obi", monthlyBudget: 61_000 },
  { id: "CC-4100", name: "Finance", owner: "Martina Vogel", monthlyBudget: 47_000 },
  { id: "CC-4200", name: "People", owner: "Daniel Frost", monthlyBudget: 39_000 },
  { id: "CC-4300", name: "IT", owner: "Kenji Arai", monthlyBudget: 83_000 },
  { id: "CC-4400", name: "Facilities", owner: "Olga Ivanova", monthlyBudget: 72_000 },
];

interface InvoiceLine {
  description: string;
  quantity: number;
  unitPrice: number;
  /** A fraction: 0.1 is ten per cent off. */
  discount: number;
  /** A fraction: 0.19 or 0.07, or 0 where no VAT is charged. */
  vatRate: number;
}

interface Invoice {
  id: string;
  supplier: string;
  costCentre: string;
  received: number;
  due: number;
  status: "awaiting approval" | "approved" | "paid" | "rejected";
  lines: readonly InvoiceLine[];
}

const INVOICES: readonly Invoice[] = [
  {
    id: "INV-26-0318", supplier: "Brandlow Office Supply", costCentre: "CC-4400", received: on(3, 16), due: on(4, 15), status: "awaiting approval",
    lines: [
      { description: "Desk lamps, LED", quantity: 24, unitPrice: 48.9, discount: 0.1, vatRate: 0.19 },
      { description: "Printer paper, box of 5 reams", quantity: 40, unitPrice: 21.5, discount: 0, vatRate: 0.19 },
      { description: "Delivery", quantity: 1, unitPrice: 35, discount: 0, vatRate: 0.19 },
    ],
  },
  {
    id: "INV-26-0317", supplier: "Kettering & Shaw Events", costCentre: "CC-1200", received: on(3, 13), due: on(4, 12), status: "awaiting approval",
    lines: [
      { description: "Trade fair stand, 3 days", quantity: 1, unitPrice: 12_400, discount: 0.05, vatRate: 0.19 },
      { description: "Catering, per guest", quantity: 180, unitPrice: 18.5, discount: 0, vatRate: 0.07 },
    ],
  },
  {
    id: "INV-26-0309", supplier: "Nimbrel Software", costCentre: "CC-4300", received: on(3, 9), due: on(4, 8), status: "approved",
    lines: [
      { description: "Design tool licences, annual", quantity: 12, unitPrice: 540, discount: 0.15, vatRate: 0.19 },
      { description: "Onboarding session", quantity: 2, unitPrice: 890, discount: 0, vatRate: 0.19 },
    ],
  },
  {
    id: "INV-26-0302", supplier: "Fenwright Legal", costCentre: "CC-4100", received: on(3, 2), due: on(3, 16), status: "paid",
    lines: [{ description: "Contract review, hours", quantity: 14.5, unitPrice: 260, discount: 0, vatRate: 0.19 }],
  },
  {
    id: "INV-26-0226", supplier: "Corrin Travel", costCentre: "CC-1100", received: on(2, 26), due: on(3, 12), status: "paid",
    lines: [
      { description: "Rail tickets, sales conference", quantity: 22, unitPrice: 139, discount: 0, vatRate: 0.07 },
      { description: "Hotel, nights", quantity: 44, unitPrice: 112, discount: 0.08, vatRate: 0.07 },
    ],
  },
  {
    id: "INV-26-0221", supplier: "Stellbrook Consulting", costCentre: "CC-2100", received: on(2, 21), due: on(3, 23), status: "rejected",
    lines: [{ description: "Architecture review, days", quantity: 6, unitPrice: 1450, discount: 0, vatRate: 0 }],
  },
];

interface Place {
  name: string;
  children?: Place[];
}

const DIVISIONS = [
  { prefix: "CC-1", name: "Commercial" },
  { prefix: "CC-2", name: "Product" },
  { prefix: "CC-3", name: "Service" },
  { prefix: "CC-4", name: "Administration" },
];

/* The company, its divisions, their cost centres, each centre's invoices and
   each invoice's lines. */
const COMPANY: Place = {
  name: "Carrow & Lisle",
  children: DIVISIONS.map((division) => ({
    name: division.name,
    children: COST_CENTRES.filter((centre) => centre.id.startsWith(division.prefix)).map((centre) => ({
      name: `${centre.name}, ${centre.id}`,
      children: INVOICES.filter((invoice) => invoice.costCentre === centre.id).map((invoice) => ({
        name: `${invoice.id} · ${invoice.supplier}`,
        children: invoice.lines.map((line) => ({ name: line.description })),
      })),
    })),
  })),
};

/** The places from the company down to the first one of this name. */
function pathTo(name: string, path: Place[]): Place[] | undefined {
  const here = path[path.length - 1]!;
  if (here.name === name) return path;
  for (const child of here.children ?? []) {
    const found = pathTo(name, [...path, child]);
    if (found) return found;
  }
  return undefined;
}

export default function BrowseDownAndBackUp() {
  const [path, setPath] = useState<Place[]>(() => pathTo("Desk lamps, LED", [COMPANY]) ?? [COMPANY]);
  const [width, setWidth] = useState(640);
  const here = path[path.length - 1]!;

  return (
    <Stack gap={4}>
      <FormField label="Width of the trail" style={{ maxWidth: 360 }}>
        <Slider min={200} max={640} step={20} value={width} onChange={setWidth} format={(v) => `${v} px`} />
      </FormField>
      <Card>
        <CardBody>
          <Stack gap={4}>
            <div style={{ width, maxWidth: "100%" }}>
              <Breadcrumb
                items={path.map((place, i) => ({ label: place.name, onSelect: () => setPath(path.slice(0, i + 1)) }))}
              />
            </div>
            <Heading level={3} size="lg">
              {here.name}
            </Heading>
            {here.children && here.children.length > 0 ? (
              <Grid minItemWidth="180px" gap={2}>
                {here.children.map((child) => (
                  <Button key={child.name} onClick={() => setPath([...path, child])}>
                    {child.name}
                  </Button>
                ))}
              </Grid>
            ) : (
              <Text size="sm" tone="muted">
                Nothing further below {here.name}.
              </Text>
            )}
          </Stack>
        </CardBody>
      </Card>
    </Stack>
  );
}
```

#### When to use something else

- The steps of a procedure, not places in a hierarchy → Stepper
- The whole hierarchy to browse, not the path to one place → TreeView

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Moves through the levels, and to the button of the folded ones. |
| `Enter` | Follows a level; on the button, opens the menu of folded levels. |
| `Arrow Down / Arrow Up` | Walks the menu of folded levels. |
| `Escape` | Closes the menu and returns the focus to its button. |

#### API

##### `BreadcrumbProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `items` *required* | `readonly `[`BreadcrumbEntry`](#type-BreadcrumbEntry)`[]` | — | The trail from the root to the current page; the last is the page.<br>Shown in: [A trail](#/breadcrumb/a-trail), [Route it yourself](#/breadcrumb/route-it-yourself), [Fold when narrow](#/breadcrumb/fold-when-narrow) and 3 more |
| `ref` | `Ref<HTMLElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of the rendered element.

##### `BreadcrumbEntry`

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` *required* | `ReactNode` | — | The level's name, as the trail and the menu of folded levels show it.<br>Shown in: [A trail](#/breadcrumb/a-trail), [Route it yourself](#/breadcrumb/route-it-yourself), [Browse down and back up](#/breadcrumb/browse-down-and-back-up) and 2 more |
| `href` | `string` | — | The level's address. Alone, the browser follows it.<br>Shown in: [A trail](#/breadcrumb/a-trail), [Resolve an incident (Scenarios)](#/scenarios/resolve-an-incident), [Set up a team (Scenarios)](#/scenarios/set-up-a-team) |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onSelect` | `() => void` | — | Routing is the caller's: given, it runs instead of the browser's navigation - on the link and in the menu of folded levels. A level with `onSelect` and no `href` is a button. In the menu a level is a menu entry, not a link: an `href` alone is followed there by `location.assign`, without a new tab or a middle click - whoever needs those routes through `onSelect`.<br>Shown in: [Route it yourself](#/breadcrumb/route-it-yourself), [Browse down and back up](#/breadcrumb/browse-down-and-back-up) |

#### Known limits

- It neither routes nor reads the address: the trail is what you pass.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Tabs

Several views of one thing in one place, exactly one of them visible (also called a tab bar). Reach for tabs when the views are alternatives the user switches between, not content to compare side by side.

```ts
import { Tabs, TabList, Tab, TabPanel } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/tabs/

Only the visible panel stands in the document; a hidden panel keeps no focus, scroll position or live region.

Uncontrolled, the tabs keep the choice themselves. Controlled, they remember nothing, so the visible tab can come from the address.

#### Examples

##### One view at a time

Give each `Tab` and its `TabPanel` the same `value`; `defaultValue` picks the first, and the tabs keep the choice.

```tsx
import { Tab, TabList, TabPanel, Tabs, Text } from "@umriss-ui/core";

export default function OneViewAtATime() {
  return (
    <Tabs defaultValue="overview">
      <TabList aria-label="Checkout">
        <Tab value="overview">Overview</Tab>
        <Tab value="incidents">Incidents</Tab>
        <Tab value="on-call">On call</Tab>
      </TabList>
      <TabPanel value="overview">
        <Text size="sm" tone="secondary">
          Payments team · tier 1 · p95 objective 300 ms · 99.95 % a month.
        </Text>
      </TabPanel>
      <TabPanel value="incidents">
        <Text size="sm" tone="secondary">
          INC-1048, SEV1, open since 09:42: card payments time out.
        </Text>
      </TabPanel>
      <TabPanel value="on-call">
        <Text size="sm" tone="secondary">
          Primary Jonas Keller, secondary Ada Mwangi, until tomorrow 09:00.
        </Text>
      </TabPanel>
    </Tabs>
  );
}
```

##### Keep the tab in the address

Control `value` with `onChange` when the visible tab belongs in the address, so a link or a reload opens the same view.

```tsx
import { useState } from "react";
import { Stack, Tab, TabList, TabPanel, Tabs, Text } from "@umriss-ui/core";

export default function KeepTheTabInTheAddress() {
  const [tab, setTab] = useState("stops");

  return (
    <Stack gap={3}>
      <Tabs value={tab} onChange={setTab}>
        <TabList aria-label="Tour T-01">
          <Tab value="stops">Stops</Tab>
          <Tab value="vehicle">Vehicle</Tab>
          <Tab value="costs">Costs</Tab>
        </TabList>
        <TabPanel value="stops">
          <Text size="sm" tone="secondary">
            11 stops, two of them outside their window.
          </Text>
        </TabPanel>
        <TabPanel value="vehicle">
          <Text size="sm" tone="secondary">
            FP 214 K, a van with 1,200 kg payload, from the North depot.
          </Text>
        </TabPanel>
        <TabPanel value="costs">
          <Text size="sm" tone="secondary">
            86 km and 6 h 40 min of driving time.
          </Text>
        </TabPanel>
      </Tabs>
      <Text size="xs" tone="muted">
        Address: <code>#/tours/T-01/{tab}</code>
      </Text>
    </Stack>
  );
}
```

##### Loading and empty panels

A panel still loading shows a `Skeleton`, an empty one an `EmptyState`; the tab itself stays and says what would be there.

```tsx
import { EmptyState, Skeleton, Stack, Tab, TabList, TabPanel, Tabs, Text } from "@umriss-ui/core";

export default function LoadingAndEmptyPanels() {
  return (
    <Tabs defaultValue="work">
      <TabList aria-label="Hana Sato">
        <Tab value="work">Work</Tab>
        <Tab value="leave">Leave</Tab>
        <Tab value="profile">Profile</Tab>
      </TabList>
      <TabPanel value="work">
        <Stack gap={2} style={{ maxWidth: 320 }}>
          <Skeleton />
          <Skeleton width="80%" />
          <Skeleton width="60%" />
        </Stack>
      </TabPanel>
      <TabPanel value="leave">
        <EmptyState title="No leave planned" description="Holidays, sick days and training appear here once they are entered." />
      </TabPanel>
      <TabPanel value="profile">
        <Text size="sm" tone="secondary">
          Developer in the Apps team, 40 h a week.
        </Text>
      </TabPanel>
    </Tabs>
  );
}
```

##### An invoice in tabs

Tabs split one record into views of different shape; a count in the tab's label says what waits behind it.

```tsx
import { Badge, Card, CardBody, CardHeader, Grid, Stack, Stepper, Tab, TabList, TabPanel, Tabs, Text } from "@umriss-ui/core";

/* Data from the controlling world, written out here so the example runs on its own. */
const on = (month: number, day: number) => new Date(2026, month - 1, day).getTime();

interface InvoiceLine {
  description: string;
  quantity: number;
  unitPrice: number;
  /** A fraction: 0.1 is ten per cent off. */
  discount: number;
  /** A fraction: 0.19 or 0.07, or 0 where no VAT is charged. */
  vatRate: number;
}

interface Invoice {
  id: string;
  supplier: string;
  costCentre: string;
  received: number;
  due: number;
  status: "awaiting approval" | "approved" | "paid" | "rejected";
  lines: readonly InvoiceLine[];
}

const INVOICES: readonly Invoice[] = [
  {
    id: "INV-26-0318", supplier: "Brandlow Office Supply", costCentre: "CC-4400", received: on(3, 16), due: on(4, 15), status: "awaiting approval",
    lines: [
      { description: "Desk lamps, LED", quantity: 24, unitPrice: 48.9, discount: 0.1, vatRate: 0.19 },
      { description: "Printer paper, box of 5 reams", quantity: 40, unitPrice: 21.5, discount: 0, vatRate: 0.19 },
      { description: "Delivery", quantity: 1, unitPrice: 35, discount: 0, vatRate: 0.19 },
    ],
  },
  {
    id: "INV-26-0317", supplier: "Kettering & Shaw Events", costCentre: "CC-1200", received: on(3, 13), due: on(4, 12), status: "awaiting approval",
    lines: [
      { description: "Trade fair stand, 3 days", quantity: 1, unitPrice: 12_400, discount: 0.05, vatRate: 0.19 },
      { description: "Catering, per guest", quantity: 180, unitPrice: 18.5, discount: 0, vatRate: 0.07 },
    ],
  },
  {
    id: "INV-26-0309", supplier: "Nimbrel Software", costCentre: "CC-4300", received: on(3, 9), due: on(4, 8), status: "approved",
    lines: [
      { description: "Design tool licences, annual", quantity: 12, unitPrice: 540, discount: 0.15, vatRate: 0.19 },
      { description: "Onboarding session", quantity: 2, unitPrice: 890, discount: 0, vatRate: 0.19 },
    ],
  },
  {
    id: "INV-26-0302", supplier: "Fenwright Legal", costCentre: "CC-4100", received: on(3, 2), due: on(3, 16), status: "paid",
    lines: [{ description: "Contract review, hours", quantity: 14.5, unitPrice: 260, discount: 0, vatRate: 0.19 }],
  },
  {
    id: "INV-26-0226", supplier: "Corrin Travel", costCentre: "CC-1100", received: on(2, 26), due: on(3, 12), status: "paid",
    lines: [
      { description: "Rail tickets, sales conference", quantity: 22, unitPrice: 139, discount: 0, vatRate: 0.07 },
      { description: "Hotel, nights", quantity: 44, unitPrice: 112, discount: 0.08, vatRate: 0.07 },
    ],
  },
  {
    id: "INV-26-0221", supplier: "Stellbrook Consulting", costCentre: "CC-2100", received: on(2, 21), due: on(3, 23), status: "rejected",
    lines: [{ description: "Architecture review, days", quantity: 6, unitPrice: 1450, discount: 0, vatRate: 0 }],
  },
];

interface Approval {
  invoice: string;
  step: "cost centre" | "finance";
  approver: string;
  decision: "approved" | "rejected" | "pending";
  at?: number;
  comment?: string;
}

/** Two signatures an invoice needs: its cost centre's owner, then finance. */
const APPROVALS: readonly Approval[] = [
  { invoice: "INV-26-0318", step: "cost centre", approver: "Olga Ivanova", decision: "pending" },
  { invoice: "INV-26-0317", step: "cost centre", approver: "Rafael Ortiz", decision: "approved", at: on(3, 16) },
  { invoice: "INV-26-0317", step: "finance", approver: "Martina Vogel", decision: "pending" },
  { invoice: "INV-26-0309", step: "cost centre", approver: "Kenji Arai", decision: "approved", at: on(3, 10) },
  { invoice: "INV-26-0309", step: "finance", approver: "Martina Vogel", decision: "approved", at: on(3, 11) },
  { invoice: "INV-26-0302", step: "cost centre", approver: "Martina Vogel", decision: "approved", at: on(3, 3) },
  { invoice: "INV-26-0302", step: "finance", approver: "Martina Vogel", decision: "approved", at: on(3, 3) },
  { invoice: "INV-26-0226", step: "cost centre", approver: "Helen Marsh", decision: "approved", at: on(2, 27) },
  { invoice: "INV-26-0226", step: "finance", approver: "Martina Vogel", decision: "approved", at: on(3, 2) },
  { invoice: "INV-26-0221", step: "cost centre", approver: "Anika Sørensen", decision: "rejected", at: on(2, 24), comment: "Not ordered - the review was cancelled in January." },
];

const INVOICE = INVOICES.find((invoice) => invoice.id === "INV-26-0317")!;
const SIGNATURES = APPROVALS.filter((approval) => approval.invoice === INVOICE.id);
const euro = (amount: number) => amount.toLocaleString("en", { style: "currency", currency: "EUR" });
const net = (line: (typeof INVOICE.lines)[number]) => line.quantity * line.unitPrice * (1 - line.discount);
const day = (time: number) => new Date(time).toLocaleDateString("en-GB", { day: "numeric", month: "long" });

export default function AnInvoiceInTabs() {
  const pending = SIGNATURES.findIndex((approval) => approval.decision === "pending");

  return (
    <Card style={{ maxWidth: 640 }}>
      <CardHeader
        eyebrow={`Invoice ${INVOICE.id}`}
        title={INVOICE.supplier}
        actions={<Badge tone="warning">Awaiting approval</Badge>}
      />
      <CardBody>
        <Tabs defaultValue="lines">
          <TabList aria-label={`Invoice ${INVOICE.id}`}>
            <Tab value="lines">Lines ({INVOICE.lines.length})</Tab>
            <Tab value="approvals">Approvals ({SIGNATURES.length})</Tab>
            <Tab value="payment">Payment</Tab>
          </TabList>
          <TabPanel value="lines">
            <Stack gap={2} style={{ paddingTop: 12 }}>
              {INVOICE.lines.map((line) => (
                <Grid key={line.description} columns={3} gap={3}>
                  <Text size="sm">{line.description}</Text>
                  <Text size="sm" tone="secondary">
                    {line.quantity} × {euro(line.unitPrice)}
                    {line.discount > 0 ? `, ${line.discount * 100} % off` : ""}
                  </Text>
                  <Text size="sm" style={{ textAlign: "right", fontVariantNumeric: "tabular-nums" }}>
                    {euro(net(line))}
                  </Text>
                </Grid>
              ))}
            </Stack>
          </TabPanel>
          <TabPanel value="approvals">
            <Stepper
              aria-label="Approvals"
              orientation="vertical"
              style={{ paddingTop: 12 }}
              steps={SIGNATURES.map((approval) => ({
                label: `${approval.step === "finance" ? "Finance" : "Cost centre"}: ${approval.approver}`,
                description: approval.at === undefined ? "Waiting" : `${approval.decision}, ${day(approval.at)}`,
                failed: approval.decision === "rejected",
              }))}
              current={pending === -1 ? SIGNATURES.length : pending}
            />
          </TabPanel>
          <TabPanel value="payment">
            <Text size="sm" tone="secondary" style={{ paddingTop: 12 }}>
              Received {day(INVOICE.received)}, due {day(INVOICE.due)}, from cost centre {INVOICE.costCentre}.
            </Text>
          </TabPanel>
        </Tabs>
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- Sections a reader may open several of at once → Accordion
- Two views the user needs side by side → Splitter

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Moves onto the visible tab, then on into its panel. |
| `Arrow Right / Arrow Left` | Shows the next or previous tab, wrapping at the ends. |
| `Home / End` | Shows the first or the last tab. |

#### API

##### `TabsProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `defaultValue` | `string` | — | Uncontrolled: the tab that stands first. Afterwards the choice belongs to the tabs - for a switch no address and no handler needs to know.<br>Shown in: [One view at a time](#/tabs/one-view-at-a-time), [Loading and empty panels](#/tabs/loading-and-empty-panels), [An invoice in tabs](#/tabs/an-invoice-in-tabs) and 1 more |
| `value` | `string` | — | The value of the visible tab. Controlled, `Tabs` remember nothing, so that the tab can come out of an address.<br>Shown in: [Keep the tab in the address](#/tabs/keep-the-tab-in-the-address) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` | `(value: string) => void` | — | Receives the value of the chosen tab. Controlled, the tab switches only once `value` follows; uncontrolled it is merely a message.<br>Shown in: [Keep the tab in the address](#/tabs/keep-the-tab-in-the-address) |

Also takes every attribute of `<div>` – without `defaultValue`, `onChange`.

##### `TabProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `string` | — | The value this tab reports – and under which its panel stands.<br>Shown in: [One view at a time](#/tabs/one-view-at-a-time), [Keep the tab in the address](#/tabs/keep-the-tab-in-the-address), [Loading and empty panels](#/tabs/loading-and-empty-panels) and 2 more |
| `ref` | `Ref<HTMLButtonElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<button>`.

##### `TabPanelProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `string` | — | The value of the tab this panel belongs to. Only the matching panel stands in the document – a hidden panel would keep focus, scroll position and live regions that nobody sees.<br>Shown in: [One view at a time](#/tabs/one-view-at-a-time), [Keep the tab in the address](#/tabs/keep-the-tab-in-the-address), [Loading and empty panels](#/tabs/loading-and-empty-panels) and 2 more |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>`.

#### Known limits

- No scrolling or overflow menu for more tabs than fit, and no closing or reordering of tabs: keep the list short and fixed.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Accordion

Long content in sections behind headers the user opens one or several at a time (also called collapsible sections or a disclosure). Reach for it where a reader needs a few of many sections, such as settings, a runbook or a report.

```ts
import { Accordion, AccordionItem } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/accordion/

Each header is a button inside a heading; set the heading level that fits the page's outline. A folded section keeps its content and its fields' values, hidden and inert.

#### Examples

##### One section at a time

By default opening one section folds the other; `defaultValue` names the sections open at the start.

```tsx
import { Accordion, AccordionItem } from "@umriss-ui/core";

export default function OneSectionAtATime() {
  return (
    <Accordion defaultValue={["goal"]} style={{ maxWidth: 520 }}>
      <AccordionItem value="goal" title="Sprint goal">
        Member portal sign-in and profile, ready for Rowan Credit Union's review on Friday.
      </AccordionItem>
      <AccordionItem value="finished" title="Finished work">
        Sign-in form, password reset and the profile page's layout: 46 of 120 hours.
      </AccordionItem>
      <AccordionItem value="carried" title="Carried over">
        Two-factor codes by text message, waiting for the provider's contract.
      </AccordionItem>
    </Accordion>
  );
}
```

##### Several open, one locked

Set `type` to `multiple` for a reader who compares, `disabled` on a section that cannot open now, and `headingLevel` to fit the page.

```tsx
import { Accordion, AccordionItem, Card, CardBody, CardHeader } from "@umriss-ui/core";

export default function SeveralOpen() {
  return (
    <Card style={{ maxWidth: 560 }}>
      <CardHeader title="Checkout · runbook" />
      <CardBody>
        <Accordion type="multiple" defaultValue={["symptoms", "first-steps"]} headingLevel={4}>
          <AccordionItem value="symptoms" title="Symptoms">
            p95 latency above 300 ms, card payments failing with a timeout at the provider.
          </AccordionItem>
          <AccordionItem value="first-steps" title="First steps">
            Cap payment retries at one, then check the provider's status page.
          </AccordionItem>
          <AccordionItem value="audit" title="Audit trail" disabled>
            Only for the Payments team's leads.
          </AccordionItem>
          <AccordionItem value="escalation" title="Escalation">
            After 30 minutes page the secondary; after an hour, the head of engineering.
          </AccordionItem>
        </Accordion>
      </CardBody>
    </Card>
  );
}
```

##### Open and fold all

Control `value` with `onChange` when a toolbar opens every section at once, or an address keeps which stand open.

```tsx
import { useState } from "react";
import { Accordion, AccordionItem, Button, Stack, Text } from "@umriss-ui/core";

const SECTIONS = [
  { value: "vehicle", title: "Vehicle", text: "FP 377 K, an e-van with 900 kg payload, charged to 92 %." },
  { value: "driver", title: "Driver", text: "Nadia Petrova, on the road since 07:30, break due at 11:45." },
  { value: "stops", title: "Stops", text: "10 stops, 6 delivered, 1 failed attempt, 3 to go." },
];

export default function OpenAndFoldAll() {
  const [open, setOpen] = useState<string[]>(["stops"]);

  return (
    <Stack gap={3} style={{ maxWidth: 520 }}>
      <Stack direction="row" gap={2} align="center">
        <Button size="sm" onClick={() => setOpen(SECTIONS.map((s) => s.value))}>
          Open all
        </Button>
        <Button size="sm" onClick={() => setOpen([])}>
          Fold all
        </Button>
        <Text size="xs" tone="muted">
          {open.length} of {SECTIONS.length} open
        </Text>
      </Stack>
      <Accordion type="multiple" value={open} onChange={setOpen}>
        {SECTIONS.map((s) => (
          <AccordionItem key={s.value} value={s.value} title={s.title}>
            {s.text}
          </AccordionItem>
        ))}
      </Accordion>
    </Stack>
  );
}
```

##### Long settings in sections

Name what each section holds in its header; fields inside keep their own keys, and a folded section keeps its values.

```tsx
import { useState } from "react";
import {
  Accordion,
  AccordionItem,
  Badge,
  Card,
  CardBody,
  CardHeader,
  FormField,
  Input,
  NumberInput,
  Select,
  Slider,
  Stack,
  Switch,
} from "@umriss-ui/core";

export default function LongSettingsInSections() {
  const [limit, setLimit] = useState<number | null>(5000);
  const [reminder, setReminder] = useState(3);

  return (
    <Card style={{ maxWidth: 600 }}>
      <CardHeader eyebrow="Finance" title="Approval rules" actions={<Badge>Carrow & Lisle</Badge>} />
      <CardBody>
        <Accordion type="multiple" defaultValue={["thresholds"]} headingLevel={4}>
          <AccordionItem value="general" title="General - name, cost centre">
            <Stack gap={3}>
              <FormField label="Name">
                <Input defaultValue="Incoming invoices" />
              </FormField>
              <FormField label="Applies to">
                <Select defaultValue="all">
                  <option value="all">All cost centres</option>
                  <option value="CC-1200">Marketing, CC-1200</option>
                  <option value="CC-4300">IT, CC-4300</option>
                </Select>
              </FormField>
            </Stack>
          </AccordionItem>
          <AccordionItem value="thresholds" title="Thresholds - second signature, reminders">
            <Stack gap={4}>
              <FormField label="Finance signs from" hint="Net amount; below it the cost centre's owner signs alone.">
                <NumberInput value={limit} onChange={setLimit} min={0} step={500} suffix="€" />
              </FormField>
              <FormField label="Remind the approver after">
                <Slider
                  min={1}
                  max={10}
                  value={reminder}
                  onChange={setReminder}
                  format={(v) => `${v} working days`}
                  marks={[{ value: 3, label: "Default" }]}
                />
              </FormField>
            </Stack>
          </AccordionItem>
          <AccordionItem value="payment" title="Payment - run, early payment discount">
            <Stack gap={3}>
              <FormField label="Payment run">
                <Select defaultValue="tue-fri">
                  <option value="tue-fri">Tuesday and Friday</option>
                  <option value="daily">Every working day</option>
                </Select>
              </FormField>
              <Switch label="Pay early where the supplier grants a discount" defaultChecked />
            </Stack>
          </AccordionItem>
          <AccordionItem value="archive" title="Archive - retention">
            <Stack gap={3}>
              <FormField label="Keep invoices for">
                <NumberInput value={10} onChange={() => undefined} suffix="years" />
              </FormField>
              <Switch label="Archive rejected invoices as well" />
            </Stack>
          </AccordionItem>
        </Accordion>
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- Alternative views of which exactly one shows → Tabs
- One block that folds on its own → Card

#### Keyboard

| Key | Action |
|---|---|
| `Arrow Down / Arrow Up` | Moves to the next or previous header, wrapping and passing disabled ones. |
| `Home / End` | Moves to the first or the last header. |
| `Enter or Space` | Opens or folds the section. |
| `Tab` | Moves into an open section's content; its fields keep their own keys. |

#### API

##### `AccordionProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `type` | `"single" \| "multiple"` | `"single"` | `single` keeps at most one section open, `multiple` any number.<br>Shown in: [Several open, one locked](#/accordion/several-open), [Open and fold all](#/accordion/open-and-fold-all), [Long settings in sections](#/accordion/long-settings-in-sections) |
| `defaultValue` | `readonly string[]` | `[]` | Uncontrolled: the sections open at the start.<br>Shown in: [One section at a time](#/accordion/one-section-at-a-time), [Several open, one locked](#/accordion/several-open), [Long settings in sections](#/accordion/long-settings-in-sections) |
| `value` | `readonly string[]` | — | Controlled: the values of the open sections. A list for both types, so that switching the type changes nothing else.<br>Shown in: [Open and fold all](#/accordion/open-and-fold-all) |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `3` | The level of the heading each header stands in - the one that fits the page's outline.<br>Shown in: [Several open, one locked](#/accordion/several-open), [Long settings in sections](#/accordion/long-settings-in-sections) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onChange` | `(value: string[]) => void` | — | Reports the open sections after a header's click. Controlled, the accordion follows once `value` does; uncontrolled it is a message.<br>Shown in: [Open and fold all](#/accordion/open-and-fold-all) |

Also takes every attribute of `<div>` – without `defaultValue`, `onChange`.

##### `AccordionItemProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `string` | — | What names the section in the accordion's `value`.<br>Shown in: [One section at a time](#/accordion/one-section-at-a-time), [Several open, one locked](#/accordion/several-open), [Open and fold all](#/accordion/open-and-fold-all) and 1 more |
| `title` *required* | `ReactNode` | — | The header's text. It names the section's region too.<br>Shown in: [One section at a time](#/accordion/one-section-at-a-time), [Several open, one locked](#/accordion/several-open), [Open and fold all](#/accordion/open-and-fold-all) and 1 more |
| `disabled` | `boolean` | `false` | A section that cannot be opened now; its header stays in the list.<br>Shown in: [Several open, one locked](#/accordion/several-open) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>` – without `title`.

#### Known limits

- A folded section's content stays rendered; for heavy content, render it only while its section is open.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Stepper

Shows how far a procedure has come: which steps are done, which one is being worked on, which lie ahead and which failed (also called a progress tracker). Reach for it for approvals, rollouts and closing routines.

```ts
import { Stepper } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/stepper/

Each state is said as a word as well as drawn, so a screen reader hears "done", "current step", "upcoming" or "failed". A failed step stays failed when the procedure moves past it; past the last step, every step is done.

#### Examples

##### Where a procedure stands

Pass the `steps` in order and the index of the `current` one; the steps before it read as done, the ones after as upcoming.

```tsx
import { Stepper } from "@umriss-ui/core";

export default function WhereAProcedureStands() {
  return (
    <Stepper
      aria-label="Incident INC-1048"
      steps={[{ label: "Detect" }, { label: "Acknowledge" }, { label: "Mitigate" }, { label: "Resolve" }, { label: "Review" }]}
      current={2}
      style={{ maxWidth: 720 }}
    />
  );
}
```

##### Steps in a column

Set `orientation` to `vertical` where each step needs a `description` beneath its label, such as a deadline.

```tsx
import { Stepper } from "@umriss-ui/core";

const CLOSE = [
  { label: "Post all invoices", description: "Until Tuesday, 3 March" },
  { label: "Reconcile accounts", description: "Bank, payables, receivables" },
  { label: "Book accruals", description: "Bonuses and open orders" },
  { label: "Report to the board", description: "Friday, 6 March" },
];

export default function StepsInAColumn() {
  return <Stepper aria-label="Closing February" orientation="vertical" steps={CLOSE} current={2} style={{ maxWidth: 360 }} />;
}
```

##### A failed step

Mark a step `failed` and it shows a cross and says "failed"; it stays failed when the procedure has moved past it.

```tsx
import { Stepper } from "@umriss-ui/core";

export default function AFailedStep() {
  return (
    <Stepper
      aria-label="Shipment FP-1004249"
      orientation="vertical"
      steps={[
        { label: "Loaded", description: "North depot, 06:40" },
        { label: "Out for delivery", description: "Tour T-01" },
        { label: "First attempt", description: "10:35, nobody at the door", failed: true },
        { label: "Second attempt", description: "Tomorrow, 08:00–10:00" },
        { label: "Delivered" },
      ]}
      current={3}
      style={{ maxWidth: 360 }}
    />
  );
}
```

##### Move on yourself

The stepper has no keys of its own: your application sets `current` after its own check, here behind two buttons.

```tsx
import { useState } from "react";
import { Button, Stack, Stepper } from "@umriss-ui/core";

const STEPS = [{ label: "Choose people" }, { label: "Set capacity" }, { label: "Plan leave" }, { label: "Confirm" }];

export default function MoveOnYourself() {
  const [current, setCurrent] = useState(1);

  return (
    <Stack gap={4} style={{ maxWidth: 560 }}>
      <Stepper aria-label="Set up sprint 15" steps={STEPS} current={current} />
      <Stack direction="row" gap={2}>
        <Button size="sm" variant="secondary" disabled={current === 0} onClick={() => setCurrent(current - 1)}>
          Back
        </Button>
        <Button size="sm" variant="primary" disabled={current === STEPS.length} onClick={() => setCurrent(current + 1)}>
          {current >= STEPS.length - 1 ? "Start the sprint" : "Next"}
        </Button>
      </Stack>
    </Stack>
  );
}
```

##### A deployment

At a card's head the stepper shows where a rollout stands; a failed step is marked in place and an alert offers the way on.

```tsx
import { useState } from "react";
import { Alert, Button, Card, CardBody, CardHeader, ProgressBar, Stack, Stepper, Text } from "@umriss-ui/core";

const STEPS = [
  { label: "Build" },
  { label: "Test" },
  { label: "Canary", description: "5 % of traffic, 15 minutes" },
  { label: "Roll out", description: "All regions" },
  { label: "Verify" },
];

export default function ADeployment() {
  const [failed, setFailed] = useState(false);
  const current = 2;
  const steps = STEPS.map((step, index) => (index === current && failed ? { ...step, failed: true } : step));

  return (
    <Card style={{ maxWidth: 720 }}>
      <CardHeader
        eyebrow="Checkout · release 2026.03.17-2"
        title="Cap payment retries at one"
        actions={
          <Button size="sm" variant="ghost" onClick={() => setFailed(true)} disabled={failed}>
            Fail the canary
          </Button>
        }
      />
      <CardBody>
        <Stack gap={5}>
          <Stepper aria-label="Deployment" steps={steps} current={current} />
          {failed ? (
            <Alert
              tone="danger"
              title="Canary stopped"
              actions={
                <Button size="sm" variant="secondary" onClick={() => setFailed(false)}>
                  Retry the canary
                </Button>
              }
            >
              The error rate on the canary rose to 2.4 %, above the 1 % the rollout allows.
            </Alert>
          ) : (
            <Stack gap={2}>
              <Text size="sm">Canary on 5 % of traffic - 6 of 15 minutes</Text>
              <ProgressBar value={0.4} label="Canary" valueText="6 of 15 minutes" />
            </Stack>
          )}
        </Stack>
      </CardBody>
    </Card>
  );
}
```

#### When to use something else

- Progress as a share of a known amount, without named steps → ProgressBar
- Where a page sits in a hierarchy → Breadcrumb

#### Keyboard

The keys of [Button](#/button/keyboard-button) apply here.

#### Accessibility

An ordered list, so a screen reader says how many steps there are and which one it reads. The current step carries `aria-current="step"`; every other step's state follows its label as a word only a screen reader hears, and the drawn number, tick or cross is hidden from it.

It announces nothing when `current` moves on: a reader hears the new state where it reads the list. A step that must be heard as it fails is said in an [Alert](#/alert); a share of a step's work stands in a [ProgressBar](#/progressbar), as in the deployment.

Under forced colours the lines between the steps take the system's text colour, and the current step's marker an outline in the selection colour.

#### API

##### `StepperProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `steps` *required* | `readonly `[`StepperStep`](#type-StepperStep)`[]` | — | The steps in the order they are walked.<br>Shown in: [Where a procedure stands](#/stepper/where-a-procedure-stands), [Steps in a column](#/stepper/steps-in-a-column), [A failed step](#/stepper/a-failed-step) and 6 more |
| `current` *required* | `number` | — | The index of the step being worked on. The steps before it are done, the ones after it upcoming; past the last step, every step is done.<br>Shown in: [Where a procedure stands](#/stepper/where-a-procedure-stands), [Steps in a column](#/stepper/steps-in-a-column), [A failed step](#/stepper/a-failed-step) and 6 more |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `horizontal` in a row, `vertical` in a column for steps with longer descriptions.<br>Shown in: [Steps in a column](#/stepper/steps-in-a-column), [A failed step](#/stepper/a-failed-step), [An invoice in tabs (Tabs)](#/tabs/an-invoice-in-tabs) |
| `ref` | `Ref<HTMLOListElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of the rendered element.

##### `StepperStep`

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` *required* | `ReactNode` | — | What the step is called - a verb for what happens in it.<br>Shown in: [Where a procedure stands](#/stepper/where-a-procedure-stands), [A failed step](#/stepper/a-failed-step), [Import budgets (FileInput)](#/fileinput/import-budgets) and 1 more |
| `description` | `ReactNode` | — | A line beneath the label - how long the step takes, what it needs.<br>Shown in: [A failed step](#/stepper/a-failed-step), [An invoice in tabs (Tabs)](#/tabs/an-invoice-in-tabs) |
| `failed` | `boolean` | — | The step failed. It says so whether it is behind the current step or is the current one: a failed step is not done.<br>Shown in: [A failed step](#/stepper/a-failed-step), [An invoice in tabs (Tabs)](#/tabs/an-invoice-in-tabs) |

#### Known limits

- The steps are read, not navigated: no keys, no clicks, and no next or back of its own. Moving on is your application's decision.
- No branching or optional steps; pass the steps that apply.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### TreeView

A hierarchy the user expands, walks with the keys and optionally ticks (also called a tree or outline). Reach for it for folders, teams and cost-centre structures; large trees stay quick because only the visible rows are drawn.

```ts
import { TreeView, TreeSearch, useTree } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/treeview/

[`useTree`](#/api/useTree) takes your data and a reader that says how to get a key, a label and the children; the tree owns only the view state over your data.

The active node, where the keys are, and the checked nodes are two states, never one. A tick cascades down, a partly ticked branch shows as mixed, and a disabled node stays visible and walkable but is never ticked ([ADR-0003](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0003-an-active-node-is-not-a-selection.md), [ADR-0005](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0005-what-cannot-be-checked.md)).

Loading is yours: an unloaded branch reports that it was opened and shows that it is loading, and cascades and searches leave it alone until your data brings its children.

#### Examples

##### A tree

Hand your data and a `reader` to [`useTree`](#/api/useTree); the reader says how to get a node's key, label and children.

```tsx
import { TreeView, useTree } from "@umriss-ui/core";
import type { NodeReader } from "@umriss-ui/core";

interface Unit {
  id: string;
  name: string;
  children?: Unit[];
}

const COMPANY: Unit[] = [
  {
    id: "commercial",
    name: "Commercial",
    children: [
      { id: "CC-1100", name: "Sales, CC-1100" },
      { id: "CC-1200", name: "Marketing, CC-1200" },
    ],
  },
  {
    id: "product",
    name: "Product",
    children: [
      { id: "CC-2100", name: "Engineering, CC-2100" },
      { id: "CC-2200", name: "Design, CC-2200" },
    ],
  },
  { id: "CC-3100", name: "Customer service, CC-3100" },
];

const READER: NodeReader<Unit> = {
  key: (unit) => unit.id,
  children: (unit) => unit.children,
  label: (unit) => unit.name,
};

export default function ATree() {
  const tree = useTree(COMPANY, { reader: READER, defaultExpanded: ["commercial"], defaultActive: "CC-1200" });

  return (
    <TreeView tree={tree} ariaLabel="Cost centres">
      {(entry) => entry.node.name}
    </TreeView>
  );
}
```

##### Tick a selection

Set `checkable` and keep the `checked` keys; a tick cascades down, and a partly ticked team shows as mixed.

```tsx
import { useState } from "react";
import { Stack, Text, TreeView, useTree } from "@umriss-ui/core";
import type { NodeReader } from "@umriss-ui/core";

interface Member {
  id: string;
  name: string;
  children?: Member[];
}

const TEAMS: Member[] = [
  {
    id: "web",
    name: "Web",
    children: [
      { id: "arjun", name: "Arjun Mehta" },
      { id: "chloe", name: "Chloe Durand" },
      { id: "noah", name: "Noah Fischer" },
    ],
  },
  {
    id: "apps",
    name: "Apps",
    children: [
      { id: "hana", name: "Hana Sato" },
      { id: "kofi", name: "Kofi Mensah" },
    ],
  },
];

const READER: NodeReader<Member> = { key: (m) => m.id, children: (m) => m.children, label: (m) => m.name };

export default function TickASelection() {
  const [checked, setChecked] = useState<ReadonlySet<string>>(() => new Set(["arjun", "chloe"]));
  const tree = useTree(TEAMS, { reader: READER, checked, onChecked: setChecked, defaultExpanded: ["web"] });

  return (
    <Stack gap={2}>
      <TreeView tree={tree} ariaLabel="People for sprint 15" checkable>
        {(entry) => entry.node.name}
      </TreeView>
      <Text size="xs" tone="muted">
        Checked: {[...checked].sort().join(", ") || "nobody"}
      </Text>
    </Stack>
  );
}
```

##### Load branches on demand

Mark a branch `unloaded` in the reader and fetch in `onLoadChildren`; the branch shows it is loading until your data brings its children.

```tsx
import { useState } from "react";
import { TreeView, useTree } from "@umriss-ui/core";
import type { NodeReader } from "@umriss-ui/core";

interface Place {
  id: string;
  name: string;
  children?: Place[];
  unloaded?: boolean;
}

const DEPOTS: Place[] = [
  { id: "north", name: "North depot", unloaded: true },
  { id: "river", name: "Riverside depot", unloaded: true },
  { id: "east", name: "East Gate depot", unloaded: true },
];

/** What the server would answer, after a while. */
const TOURS: Record<string, string[]> = {
  north: ["T-01 · FP 214 K", "T-02 · FP 377 K", "T-03 · FP 118 R"],
  river: ["T-04 · FP 402 R", "T-05 · FP 455 R"],
  east: ["T-06 · FP 290 E", "T-07 · FP 311 E", "T-08 · FP 520 E"],
};

const READER: NodeReader<Place> = {
  key: (p) => p.id,
  children: (p) => p.children,
  label: (p) => p.name,
  unloaded: (p) => p.unloaded === true,
};

export default function LoadBranchesOnDemand() {
  const [depots, setDepots] = useState(DEPOTS);
  const load = (depot: Place) => {
    window.setTimeout(() => {
      setDepots((previous) =>
        previous.map((p) =>
          p.id === depot.id
            ? { ...p, unloaded: false, children: TOURS[p.id]!.map((name) => ({ id: `${p.id}/${name}`, name })) }
            : p,
        ),
      );
    }, 800);
  };
  const tree = useTree(depots, { reader: READER, onLoadChildren: load });

  return (
    <TreeView tree={tree} ariaLabel="Today's tours by depot">
      {(entry) => entry.node.name}
    </TreeView>
  );
}
```

##### Search with the path

Put a `TreeSearch` beside the tree: each find keeps the dimmed path above it, and a search without finds says so.

```tsx
import { useState } from "react";
import { Stack, TreeSearch, TreeView, useTree } from "@umriss-ui/core";
import type { NodeReader } from "@umriss-ui/core";

/* Data from the operations world, written out here so the example runs on its own. */
interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface Node {
  id: string;
  name: string;
  children?: Node[];
}

const TEAMS: Node[] = [...new Set(SERVICES.map((service) => service.team))].map((team) => ({
  id: team,
  name: team,
  children: SERVICES.filter((service) => service.team === team).map((service) => ({ id: service.id, name: service.name })),
}));

const READER: NodeReader<Node> = { key: (n) => n.id, children: (n) => n.children, label: (n) => n.name };

export default function SearchWithThePath() {
  const [term, setTerm] = useState("check");
  const tree = useTree(TEAMS, { reader: READER, search: term, onSearch: setTerm });

  return (
    <Stack gap={2} style={{ maxWidth: 320 }}>
      <TreeSearch tree={tree} aria-label="Search the services" size="sm" />
      <TreeView tree={tree} ariaLabel="Services by team">
        {(entry) => entry.node.name}
      </TreeView>
    </Stack>
  );
}
```

##### With an error

A `FormField` with an `error` marks the `TreeSearch` invalid by itself. Without one, set `invalid` and tie your message to the field with `aria-describedby`. Tick a service to clear it.

```tsx
import { useId, useState } from "react";
import { Stack, Text, TreeSearch, TreeView, useTree } from "@umriss-ui/core";
import type { NodeReader } from "@umriss-ui/core";

interface Node {
  id: string;
  name: string;
  children?: Node[];
}

const TEAMS: Node[] = [
  {
    id: "payments",
    name: "Payments",
    children: [
      { id: "checkout", name: "Checkout" },
      { id: "billing", name: "Billing" },
    ],
  },
  {
    id: "discovery",
    name: "Discovery",
    children: [
      { id: "search", name: "Search" },
      { id: "images", name: "Image service" },
    ],
  },
];

const READER: NodeReader<Node> = { key: (n) => n.id, children: (n) => n.children, label: (n) => n.name };

export default function WithAnError() {
  const [checked, setChecked] = useState<ReadonlySet<string>>(() => new Set());
  const tree = useTree(TEAMS, { reader: READER, checked, onChecked: setChecked, defaultExpanded: ["payments"] });
  const messageId = useId();
  const error = checked.size === 0 ? "Tick at least one service, or the alert rule watches nothing." : undefined;

  return (
    <Stack gap={2} style={{ maxWidth: 360 }}>
      <Stack gap={1}>
        <TreeSearch
          tree={tree}
          size="sm"
          aria-label="Search the services the alert rule watches"
          invalid={error !== undefined}
          aria-describedby={error ? messageId : undefined}
        />
        {error && (
          <Text id={messageId} size="xs" style={{ color: "var(--u-color-danger-text)" }}>
            {error}
          </Text>
        )}
      </Stack>
      <TreeView tree={tree} ariaLabel="Services by team" checkable>
        {(entry) => entry.node.name}
      </TreeView>
    </Stack>
  );
}
```

##### Search, check and reveal in a large tree

In a company's filing, checks cascade, a search keeps the path, locked years stay unchecked, and `revealNode` finds any of 240 nodes.

```tsx
/* Four trees over one filing, because the component's parts are one
   behaviour: the keys run on the flat list, and virtualisation shows only a
   window of it. The active node and the checks are two states (ADR-0003); the
   tree with checks and the one with an active node only show both.

   `data-role` is a selector the interaction suite reads. */

import { useMemo, useState } from "react";
import { Button, Grid, Stack, Text, TreeSearch, TreeView, useTree } from "@umriss-ui/core";
import type { NodeReader } from "@umriss-ui/core";

interface TreeNode {
  id: string;
  name: string;
  children?: TreeNode[];
  /** May be seen but not chosen - a closed financial year, say. */
  locked?: boolean;
  /** The children have not been loaded yet. */
  unloaded?: boolean;
}

const FILING: TreeNode[] = [
  {
    id: "contracts",
    name: "Contracts",
    children: [
      {
        id: "framework",
        name: "Framework contracts",
        children: [
          { id: "fc-brandlow", name: "Brandlow Office Supply" },
          { id: "fc-nimbrel", name: "Nimbrel Software" },
          { id: "fc-corrin", name: "Corrin Travel" },
        ],
      },
      {
        id: "single",
        name: "Single orders",
        children: [
          { id: "so-4711", name: "Order 4711" },
          { id: "so-4712", name: "Order 4712" },
        ],
      },
      { id: "terminations", name: "Terminations", children: [] },
      { id: "external", name: "External mandates", locked: true },
    ],
  },
  {
    id: "documents",
    name: "Documents",
    children: [
      {
        id: "2026",
        name: "2026",
        children: [
          { id: "d-q1", name: "Quarter 1" },
          { id: "d-q2", name: "Quarter 2" },
        ],
      },
      { id: "2025", name: "2025", children: [{ id: "d-2025", name: "Annual accounts" }] },
      { id: "2024", name: "2024 (closed)", locked: true },
    ],
  },
  { id: "statutes", name: "Articles of association.pdf" },
  { id: "inbox", name: "Inbox", unloaded: true },
];

/* A large body for the reach: large enough that only a window of it stands in
   the document, and deep enough that "reveal" has to expand something. */
const MANY: TreeNode[] = Array.from({ length: 40 }, (_, i) => ({
  id: `f${i}`,
  name: `Folder ${i}`,
  children: Array.from({ length: 5 }, (_, k) => ({ id: `f${i}-${k}`, name: `Sheet ${i}.${k}` })),
}));

const READER: NodeReader<TreeNode> = {
  key: (e) => e.id,
  children: (e) => e.children,
  label: (e) => e.name,
  disabled: (e) => e.locked === true,
  unloaded: (e) => e.unloaded === true,
};

export default function SearchCheckAndReveal() {
  /* All three framework contracts: the branch above them is thereby fully
     checked, the branch above that only partly. Both states at a glance. */
  /* Loading belongs to the caller: the tree reports only that an unloaded
     branch was opened. Here a delay is simulated and the own copy of the data
     is then extended - the tree re-renders, and `unloaded` falls away with the
     data. */
  const [filing, setFiling] = useState<TreeNode[]>(FILING);
  const load = (node: TreeNode) => {
    if (node.id !== "inbox") return;
    window.setTimeout(() => {
      setFiling((previous) =>
        previous.map((n) =>
          n.id === "inbox"
            ? {
                ...n,
                unloaded: false,
                children: [
                  { id: "in-1", name: "Invoice INV-26-0318" },
                  { id: "in-2", name: "Query from Brandlow Office Supply" },
                  { id: "in-3", name: "Reminder from Fenwright Legal" },
                ],
              }
            : n,
        ),
      );
    }, 700);
  };

  const [checked, setChecked] = useState<ReadonlySet<string>>(
    () => new Set(["fc-brandlow", "fc-nimbrel", "fc-corrin", "framework"]),
  );

  const withChecks = useTree(filing, {
    reader: READER,
    checked,
    onChecked: setChecked,
    onLoadChildren: load,
    defaultExpanded: ["contracts", "framework", "documents"],
    defaultActive: "fc-nimbrel",
  });

  const activeOnly = useTree(filing, {
    reader: READER,
    defaultExpanded: ["documents", "2026"],
    defaultActive: "d-q2",
  });

  /* The same body, narrowed by a term: the find appears with the path that
     leads to it, and the path is dimmed. */
  const [term, setTerm] = useState("quarter");
  const searched = useTree(filing, {
    reader: READER,
    search: term,
    onSearch: setTerm,
  });

  const chosen = useMemo(() => [...checked].sort().join(", "), [checked]);

  const large = useTree(MANY, { reader: READER, virtual: { rowHeight: 26 } });
  const [last, setLast] = useState("-");

  return (
    <Stack gap={4}>
      <Grid minItemWidth="260px" gap={4}>
          <Stack gap={2}>
            <Text size="xs" tone="muted">
              With checks and a search
            </Text>
            <TreeSearch tree={withChecks} aria-label="Search the filing" size="sm" />
            <TreeView tree={withChecks} ariaLabel="Filing with a selection" checkable>
              {(e) => e.node.name}
            </TreeView>
            <Text size="xs" tone="muted">
              Checked: {chosen || "nothing"}
            </Text>
          </Stack>

          <Stack gap={2}>
            <Text size="xs" tone="muted">
              A search with the path
            </Text>
            <TreeSearch tree={searched} aria-label="Search the filing" size="sm" />
            <TreeView tree={searched} ariaLabel="Filing, searched">
              {(e) => e.node.name}
            </TreeView>
          </Stack>

          <Stack gap={2}>
            <Text size="xs" tone="muted">
              Reach: 40 folders of 5 sheets each, virtualised
            </Text>
            <Stack direction="row" gap={2} wrap>
              <Button size="sm" variant="ghost" onClick={() => large.expandAll()}>
                Expand all
              </Button>
              <Button size="sm" variant="ghost" onClick={() => large.collapseAll()}>
                Collapse all
              </Button>
              <Button
                size="sm"
                variant="ghost"
                data-role="reveal-deep"
                onClick={() => setLast(String(large.revealNode("f33-2") ?? "not found"))}
              >
                Reveal sheet 33.2
              </Button>
            </Stack>
            <TreeView tree={large} ariaLabel="Large body" style={{ height: 240 }}>
              {(e) => e.node.name}
            </TreeView>
            <Text size="xs" tone="muted">
              Last revealed: {last}
            </Text>
          </Stack>

          <Stack gap={2}>
            <Text size="xs" tone="muted">
              Active node only
            </Text>
            <TreeView tree={activeOnly} ariaLabel="Filing for navigation">
              {(e) => e.node.name}
            </TreeView>
            <Text size="xs" tone="muted">
              Active: {activeOnly.active ?? "nothing"}
            </Text>
          </Stack>
      </Grid>
    </Stack>
  );
}
```

#### When to use something else

- Only the path to the current place → Breadcrumb
- Rows with columns, grouped under headings → `Table` with grouping from @umriss-ui/table

#### Keyboard

| Key | Action |
|---|---|
| `Arrow Down / Arrow Up` | Moves to the next or previous visible node. |
| `Arrow Right` | Expands the node; on an expanded one, moves to its first child. |
| `Arrow Left` | Collapses the node; on a collapsed one, moves to its parent. |
| `Home / End` | Moves to the first or the last visible node. |
| `Enter` | Activates the node. |
| `Space` | With checks: ticks or unticks the node. |
| `Shift + Space` | With checks: ticks from the last ticked node to this one. |
| `Shift + Arrow Down / Up` | With checks: moves and ticks in one gesture. |
| `Ctrl + A` | With checks: ticks everything, or nothing if everything is ticked. |
| `A letter` | Moves to the next node whose label starts with what was typed. |

#### API

##### `TreeViewProps<K, S extends Key = string>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `tree` *required* | [`Tree`](#type-Tree)`<K, S>` | — | The tree from `useTree`. It is the whole state: flattening, active node, checks, anchor. The view holds nothing beside it.<br>Shown in: [A tree](#/treeview/a-tree), [Tick a selection](#/treeview/tick-a-selection), [Load branches on demand](#/treeview/load-branches-on-demand) and 5 more |
| `checkable` | `boolean` | `false` | Show ticks. Without them a tree remains that knows only an active node - and no space is kept free for them.<br>Shown in: [Tick a selection](#/treeview/tick-a-selection), [With an error](#/treeview/with-an-error), [Search, check and reveal in a large tree](#/treeview/search-check-and-reveal) |
| `children` *required* | `(entry: `[`FlatteningEntry`](#type-FlatteningEntry)`<K, S>) => ReactNode` | — | What the node says.<br>Shown in: [A tree](#/treeview/a-tree), [Tick a selection](#/treeview/tick-a-selection), [Load branches on demand](#/treeview/load-branches-on-demand) and 5 more |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Accessibility

| Prop | Type | Default | Description |
|---|---|---|---|
| `ariaLabel` *required* | `string` | — | Required: the tree is a structure of its own and needs a name.<br>Shown in: [A tree](#/treeview/a-tree), [Tick a selection](#/treeview/tick-a-selection), [Load branches on demand](#/treeview/load-branches-on-demand) and 5 more |

Also takes every attribute of `<div>` – without `children`.

##### `TreeSearchProps<K, S extends Key = string>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `tree` *required* | [`Tree`](#type-Tree)`<K, S>` | — | The same tree as the view's. The field does not hold the text itself – it belongs to the tree, because the flattening depends on it.<br>Shown in: [Search with the path](#/treeview/search-with-the-path), [With an error](#/treeview/with-an-error), [Search, check and reveal in a large tree](#/treeview/search-check-and-reveal) |
| `size` | `"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for a toolbar and dense forms, `md` otherwise. From `InputProps`.<br>Shown in: [Search with the path](#/treeview/search-with-the-path), [With an error](#/treeview/with-an-error), [Search, check and reveal in a large tree](#/treeview/search-check-and-reveal) and 3 more |
| `chars` | `number` | — | The width in characters - room for the value; the field adds its own padding and cross. Given, the field is that wide wherever it stands, and never wider than its place. Without it the field fills its place, and is 20 characters wide where the place asks - in a toolbar or a row. From `InputProps`.<br>Shown in: [Sized to the value (Sizes)](#/sizes/sized-to-the-value), [Narrow places (Sizes)](#/sizes/narrow-places), [Configurator (Input)](#/input/configurator-input) |
| `invalid` | `boolean` | — | Marks the field as invalid. `FormField` sets it itself as soon as it carries an `error` - by hand only necessary without `FormField`. From `InputProps`.<br>Shown in: [With an error](#/treeview/with-an-error), [Configurator (Input)](#/input/configurator-input), [With an error (Input)](#/input/with-an-error) |
| `numeric` | `boolean` | `false` | Right-aligned tabular figures in Geist Mono, e.g. for key figures. From `InputProps`.<br>Shown in: [Configurator (Input)](#/input/configurator-input), [Align reference numbers (Input)](#/input/align-reference-numbers), [Take a delivery address (Input)](#/input/take-a-delivery-address) and 2 more |
| `clearable` | `boolean` | `false` | Shows a gently appearing cross where there is content, which clears the input. Requires a controlled field (value) and onClear. From `InputProps`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [Clear the field (Input)](#/input/clear-the-field) |
| `ref` | `Ref<HTMLInputElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onClear` | `() => void` | — | Called by the cross. Clearing belongs to the caller: only it knows whether "empty" here is the empty text or no value at all. From `InputProps`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [Clear the field (Input)](#/input/clear-the-field) |

Also takes every attribute of `<input>` – without `size`.

##### Types on this page

###### `Tree<K, S extends Key = string>`

What `useTree` returns: the visible nodes and the gestures on them. Hand it
to `TreeView` and `TreeSearch`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `flattening` *required* | `readonly `[`FlatteningEntry`](#type-FlatteningEntry)`<K, S>[]` | — | The visible nodes – complete, even where only a window of them is rendered. Positions and sibling counts come from here and never from what stands in the document ([ADR-0004](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0004-a-flat-accessibility-tree.md)). |
| `active` *required* | `S \| null` | — | <br>Shown in: [Search, check and reveal in a large tree](#/treeview/search-check-and-reveal) |
| `search` *required* | `string` | — |  |
| `toggleExpanded` *required* | `(key: S) => void` | — |  |
| `toggleCheck` *required* | `(key: S) => void` | — |  |
| `activate` *required* | `(key: S) => void` | — |  |
| `move` *required* | `(direction: `[`Direction`](#type-Direction)`) => void` | — |  |
| `setSearch` *required* | `(text: string) => void` | — |  |
| `revealNode` *required* | `(key: S) => S \| null` | — | Expands the ancestors, brings the row into view and sets the active node. Returns the key, or null if it does not exist in the data.<br>Shown in: [Search, check and reveal in a large tree](#/treeview/search-check-and-reveal) |
| `revealPath` *required* | `(path: readonly S[]) => S \| null` | — | Like revealNode, but with a path the caller knows and the data does not yet - from a deep link, say. Returns the deepest key reached; if the run gets stuck at an unloaded branch, that is its key, and it has been expanded in the process. Loading and calling again is the caller's business. |
| `expandAll` *required* | `() => void` | — | <br>Shown in: [Search, check and reveal in a large tree](#/treeview/search-check-and-reveal) |
| `collapseAll` *required* | `() => void` | — | <br>Shown in: [Search, check and reveal in a large tree](#/treeview/search-check-and-reveal) |
| `typeahead` *required* | `(prefix: string) => void` | — | Moves the active node to the next one whose label starts like this. Changes nothing else – not the expanding, not the checks, not the search. |
| `checkTo` *required* | `(to: S) => void` | — | Checks the range from the anchor up to this node. |
| `moveAndCheck` *required* | `(direction: `[`Direction`](#type-Direction)`) => void` | — | Moves the active node **and** toggles the new one – one gesture, one report. Separate from move(), so that plain movement checks nothing; to be called instead of move(), not in addition to it. |
| `toggleAll` *required* | `() => void` | — | Checks everything checkable – or empties, if everything is on already. |
| `revealCount` *required* | `number` | — | Counts up every explicit request "show me this node". Otherwise the presentation follows the focus to the active node only where it already lies inside the tree - otherwise a state change from outside would tear the focus away. An explicit request, however, is exactly the opposite of an incidental change, and for that it needs a sign. |
| `virtual` | [`VirtualRows`](#type-VirtualRows) | — | Set where virtualisation runs; goes to `<TreeView virtual={…}>`. |

###### `FlatteningEntry<K, S extends Key = string>`

One visible node of a tree, with everything a row needs to be drawn and
read out: level, branch or leaf, check state, search state and position
among its siblings.

| Prop | Type | Default | Description |
|---|---|---|---|
| `node` *required* | `K` | — | <br>Shown in: [A tree](#/treeview/a-tree), [Tick a selection](#/treeview/tick-a-selection), [Load branches on demand](#/treeview/load-branches-on-demand) and 5 more |
| `key` *required* | `S` | — |  |
| `level` *required* | `number` | — | Roots stand at 0. Drives the indentation and what is read out. |
| `label` *required* | `string` | — | The node's text; here, so that typeahead can be a pure function over the flattening and needs no reader. |
| `branch` *required* | `boolean` | — |  |
| `empty` *required* | `boolean` | — | Branch without content: expanding it showed nothing. An unloaded branch is not empty - it could have children. |
| `disabled` *required* | `boolean` | — | May not be checked ([ADR-0005](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0005-what-cannot-be-checked.md)). It stays navigable. |
| `unloaded` *required* | `boolean` | — | Could have children that are not present. For checking exactly the same as disabled: whatever has to reach its descendants may not act on it. |
| `expanded` *required* | `boolean` | — |  |
| `checked` *required* | `boolean` | — |  |
| `indeterminate` *required* | `boolean` | — | Derived: not checked itself, but at least one descendant is. |
| `active` *required* | `boolean` | — |  |
| `matches` *required* | `boolean` | — | Matched the search itself. Without a search text every entry matches, so that the surface needs no special case. |
| `pathOnly` *required* | `boolean` | — | Stands there only because a descendant matches - a signpost. The surface dims these and only these. A child under a matching branch is neither a match nor a signpost but context: it stays normal. |
| `position` *required* | `number` | — | 1-based, among the siblings that survive the filter. |
| `siblings` *required* | `number` | — |  |

###### `Direction`

Where the active node moves: up and down the visible rows, in and out of a
branch, to the first or the last row.

```ts
type Direction = "up" | "down" | "in" | "out" | "start" | "end";
```

###### `VirtualRows`

What `useVirtual` returns: the ref for the scroll area, the window of rows
to render and the heights of the filler rows around it.

| Prop | Type | Default | Description |
|---|---|---|---|
| `scrollRef` *required* | `RefObject<HTMLDivElement \| null>` | — | Goes on the scroll area - in |
| `from` *required* | `number` | — | Index of the first rendered row within the filtered set. |
| `to` *required* | `number` | — |  |
| `fillerBefore` *required* | `number` | — | Height of the upper filler row, in pixels. |
| `fillerAfter` *required* | `number` | — | Height of the lower filler row, in pixels. |
| `count` *required* | `number` | — | Rows in total - the filler rows carry the rest. |
| `showRow` *required* | `(index: number) => void` | — | Brings a row into view; for the keyboard. |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onScroll` *required* | `() => void` | — | Reports a new scroll position to the container. Internal. |

#### Known limits

- No dragging nodes to rearrange them.
- It fetches nothing and handles no loading errors: retries and messages stay in your application ([ADR-0005](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0005-what-cannot-be-checked.md)).

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Benchmark

A large virtualised tree, measured in this browser rather than claimed: the first render, a walk down it with the arrow keys and a scroll.

```ts
import { useVirtual } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/benchmark/

The figures in `packages/core/docs/capabilities-tree.md` come from here. The page adds nothing to the tree; it times it from outside.

#### Examples

##### Measure a large tree

Set a node count and press the buttons: the first render, a walk down the tree with the arrow keys and a scroll are timed in this browser.

```tsx
/* What a large virtualised tree costs, measured from outside: the first render,
   a walk of the Active node with the arrow keys, and a scroll. Nothing here is
   a prop of the tree. Not photographed: it measures the moment it runs.

   The scripted runs start from a button and are driven by the page itself, so
   a person and a script read the same figures. `data-role` names every control
   and every figure; `status` reads idle, running or done.

   What a figure covers: script, React's commit and a forced layout - the
   clock stops after two macrotasks and a layout read, not at the paint, so
   that frame quantisation does not enter the figure. */

import { useCallback, useEffect, useRef, useState } from "react";
import { Button, Text, TreeView, useTree } from "@umriss-ui/core";
import type { NodeReader } from "@umriss-ui/core";

interface Unit {
  id: string;
  name: string;
  children?: Unit[];
}

const SIZES = [10_000, 50_000, 100_000] as const;
const ROW = 26;
const KEYS = 200;
const SCROLLS = 100;
/* Rows per scroll step: far enough to replace the window every time. */
const SCROLL_ROWS = 10;

/** A forest of folders (6 groups of 7 leaves each, 49 nodes per root) cut off at
    `count` nodes; every folder is open, so the visible rows are the nodes. */
function build(count: number): { roots: Unit[]; open: string[] } {
  const roots: Unit[] = [];
  const open: string[] = [];
  let made = 0;
  const node = (id: string, children?: Unit[]): Unit => ({ id, name: `Node ${id}`, children });
  for (let r = 0; made < count; r++) {
    const groups: Unit[] = [];
    open.push(`r${r}`);
    made++;
    for (let g = 0; g < 6 && made < count; g++) {
      const leaves: Unit[] = [];
      made++;
      open.push(`r${r}-${g}`);
      for (let l = 0; l < 7 && made < count; l++) {
        leaves.push(node(`r${r}-${g}-${l}`));
        made++;
      }
      groups.push(node(`r${r}-${g}`, leaves));
    }
    roots.push(node(`r${r}`, groups));
  }
  return { roots, open };
}

const READER: NodeReader<Unit> = {
  key: (unit) => unit.id,
  children: (unit) => unit.children,
  label: (unit) => unit.name,
};

type Status = "idle" | "running" | "done";
type Figures = { firstRender: number | null; perKey: number | null; perScroll: number | null };

/** Two macrotasks, then a layout read: React has committed by then. */
function settled(): Promise<void> {
  const tick = () =>
    new Promise<void>((resolve) => {
      const channel = new MessageChannel();
      channel.port1.onmessage = () => resolve();
      channel.port2.postMessage(null);
    });
  return tick()
    .then(tick)
    .then(() => void document.body.offsetHeight);
}

function Body({ built, onShown }: { built: { roots: Unit[]; open: string[] }; onShown: () => void }) {
  const tree = useTree(built.roots, {
    reader: READER,
    defaultExpanded: built.open,
    defaultActive: built.roots[0]?.id ?? null,
    virtual: { rowHeight: ROW },
  });
  useEffect(onShown, [onShown]);
  return (
    <TreeView tree={tree} ariaLabel="Benchmark tree" style={{ height: 320 }}>
      {(entry) => entry.node.name}
    </TreeView>
  );
}

/** The clock, behind a function so that it is read in handlers only. */
const now = () => performance.now();

const show = (ms: number | null) => (ms === null ? "-" : ms.toFixed(2));

export default function Benchmark() {
  const [size, setSize] = useState<(typeof SIZES)[number]>(SIZES[0]);
  const [built, setBuilt] = useState(() => build(SIZES[0]));
  const [status, setStatus] = useState<Status>("idle");
  const [figures, setFigures] = useState<Figures>({ firstRender: null, perKey: null, perScroll: null });
  const [run, setRun] = useState(0);
  const started = useRef<number | null>(null);
  const host = useRef<HTMLDivElement>(null);

  const choose = (n: (typeof SIZES)[number]) => {
    if (status === "running") return;
    const next = build(n);
    setStatus("running");
    setFigures({ firstRender: null, perKey: null, perScroll: null });
    started.current = now();
    setSize(n);
    setBuilt(next);
    setRun((r) => r + 1);
  };

  /* Stable between renders: the body's effect runs on mount only, which is
     the first render of a run (the body is keyed by the run, so the
     same size again renders anew). */
  const onShown = useCallback(() => {
    const from = started.current;
    if (from === null) return;
    started.current = null;
    void settled().then(() => {
      setFigures((f) => ({ ...f, firstRender: performance.now() - from }));
      setStatus("done");
    });
  }, []);

  const tree = () => host.current?.querySelector<HTMLElement>('[role="tree"]') ?? null;

  const walk = async () => {
    const root = tree();
    const active = root?.querySelector<HTMLElement>('[role="treeitem"][tabindex="0"]');
    if (status === "running" || !root || !active) return;
    setStatus("running");
    active.focus();
    await settled();
    let total = 0;
    for (let i = 0; i < KEYS; i++) {
      const target = document.activeElement ?? root;
      const from = performance.now();
      target.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true, cancelable: true }));
      await settled();
      total += performance.now() - from;
    }
    setFigures((f) => ({ ...f, perKey: total / KEYS }));
    setStatus("done");
  };

  const scroll = async () => {
    const root = tree();
    if (status === "running" || !root) return;
    setStatus("running");
    root.scrollTop = 0;
    await settled();
    let from = 0;
    /* A capture listener on the window runs before React's own at the root, so
       the clock starts as the scroll event is dispatched. */
    const start = () => {
      from = performance.now();
    };
    window.addEventListener("scroll", start, { capture: true });
    let total = 0;
    for (let i = 0; i < SCROLLS; i++) {
      /* A step that moves nothing fires no event; the run goes on after a
         moment instead of waiting for one that never comes. */
      const fired = new Promise<void>((resolve) => {
        root.addEventListener("scroll", () => resolve(), { once: true });
        setTimeout(resolve, 500);
      });
      from = performance.now();
      root.scrollTop += SCROLL_ROWS * ROW;
      await fired;
      await settled();
      total += performance.now() - from;
    }
    window.removeEventListener("scroll", start, { capture: true });
    setFigures((f) => ({ ...f, perScroll: total / SCROLLS }));
    setStatus("done");
  };

  return (
    <>
      <div style={{ display: "flex", flexWrap: "wrap", gap: "0.5rem" }}>
        {SIZES.map((n) => (
          <Button key={n} size="sm" data-role={`size-${n}`} aria-pressed={n === size} onClick={() => choose(n)}>
            {n.toLocaleString("en-US")} nodes
          </Button>
        ))}
        <Button size="sm" data-role="walk" onClick={walk}>
          Walk {KEYS} keys
        </Button>
        <Button size="sm" data-role="scroll" onClick={scroll}>
          Scroll {SCROLLS} steps
        </Button>
      </div>
      <dl style={{ display: "flex", flexWrap: "wrap", gap: "1.5rem", margin: 0 }}>
        <div>
          <Text as="dt">Status</Text>
          <Text as="dd" mono style={{ margin: 0 }} data-role="status">{status}</Text>
        </div>
        <div>
          <Text as="dt">Nodes</Text>
          <Text as="dd" mono style={{ margin: 0 }} data-role="nodes">{size}</Text>
        </div>
        <div>
          <Text as="dt">First render (ms)</Text>
          <Text as="dd" mono style={{ margin: 0 }} data-role="first-render">{show(figures.firstRender)}</Text>
        </div>
        <div>
          <Text as="dt">Per key (ms)</Text>
          <Text as="dd" mono style={{ margin: 0 }} data-role="per-key">{show(figures.perKey)}</Text>
        </div>
        <div>
          <Text as="dt">Per scroll event (ms)</Text>
          <Text as="dd" mono style={{ margin: 0 }} data-role="per-scroll">{show(figures.perScroll)}</Text>
        </div>
      </dl>
      <div ref={host}>
        <Body key={run} built={built} onShown={onShown} />
      </div>
    </>
  );
}
```

#### Keyboard

The keys of [TreeView](#/treeview/keyboard-treeview) apply here.

#### Props on this page

From `TextProps` — the full table stands on [Typography](#/typography/type-TextProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`as`](#/typography/TextProps-as) | `ElementType` | `"p"` | Element to render as. |
| [`mono`](#/typography/TextProps-mono) | `boolean` | `false` | Geist Mono with tabular figures – for numbers and identifiers. |

From `ButtonProps` — the full table stands on [Button](#/button/type-ButtonProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`size`](#/button/ButtonProps-size) | [`ButtonSize`](#/button/type-ButtonSize)<br>`"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for buttons in header bars and table rows, `md` otherwise. |

From `IconButtonProps` — the full table stands on [IconButton](#/iconbutton/type-IconButtonProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`size`](#/iconbutton/IconButtonProps-size) | [`ButtonSize`](#/iconbutton/type-ButtonSize)<br>`"sm" \| "md"` | the size of a `ControlSizeProvider` around it, else `"md"` | `sm` for buttons in header bars and table rows, `md` otherwise. From `ButtonProps`. |

From `TreeViewProps` — the full table stands on [TreeView](#/treeview/type-TreeViewProps).

| Prop | Type | Default | Description |
|---|---|---|---|
| [`tree`](#/treeview/TreeViewProps-tree) *required* | [`Tree`](#/treeview/type-Tree)`<K, S>` | — | The tree from `useTree`. It is the whole state: flattening, active node, checks, anchor. The view holds nothing beside it. |
| [`children`](#/treeview/TreeViewProps-children) *required* | `(entry: `[`FlatteningEntry`](#/treeview/type-FlatteningEntry)`<K, S>) => ReactNode` | — | What the node says. |

###### Accessibility

| Prop | Type | Default | Description |
|---|---|---|---|
| [`ariaLabel`](#/treeview/TreeViewProps-ariaLabel) *required* | `string` | — | Required: the tree is a structure of its own and needs a name. |

## Data display

Single values and labels, read at a glance.

### Badge

A small word or number at the edge of something else: a status, a count (also called a label or chip). Reach for it to mark the state of a row, or how many items wait behind a button.

```ts
import { Badge } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/badge/

It is never the only place a state is said: the word inside carries the meaning, and the tone repeats it for the eye.

#### Examples

##### A badge

A short word at the edge of what it describes; it repeats a state the text around it could also carry.

```tsx
import { Badge, Text } from "@umriss-ui/core";

export default function ABadge() {
  return (
    <Text size="sm">
      Profile page <Badge>In progress</Badge>
    </Text>
  );
}
```

##### Tones

Give each state one `tone` and keep it across the application; the word inside always says the same as the colour.

```tsx
import { Badge, Stack } from "@umriss-ui/core";

export default function Tones() {
  return (
    <Stack direction="row" gap={2} wrap align="center">
      <Badge>To do</Badge>
      <Badge tone="accent">In progress</Badge>
      <Badge tone="warning">In review</Badge>
      <Badge tone="success">Done</Badge>
      <Badge tone="danger">Blocked</Badge>
    </Stack>
  );
}
```

##### Counters

`pill` is the shape for numbers: a number in it reads as a quantity. Cap long counts yourself, as in “99+”.

```tsx
import { Badge, Button, Stack } from "@umriss-ui/core";

function capped(count: number) {
  return count > 99 ? "99+" : String(count);
}

export default function Counters() {
  return (
    <Stack direction="row" gap={3} wrap align="center">
      <Button size="sm">
        Open incidents <Badge pill tone="danger">{capped(2)}</Badge>
      </Button>
      <Button size="sm">
        Alerts <Badge pill tone="accent">{capped(7)}</Badge>
      </Button>
      <Button size="sm">
        Resolved this month <Badge pill>{capped(148)}</Badge>
      </Button>
    </Stack>
  );
}
```

##### Mark the state of each row

In a list the badges line up in one column, so the eye runs down the states without reading every title.

```tsx
import { Badge, Stack, Text } from "@umriss-ui/core";
import type { BadgeTone } from "@umriss-ui/core";

/* Data from the planning world, written out here so the example runs on its own. */
const at = (day: number, hours = 9, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();

/** A work item, shaped as `@umriss-ui/schedule`'s `Subtask`. */
interface WorkItem {
  id: string;
  /** The project. */
  task: string;
  /** The person. */
  lane: string;
  from: number;
  to: number;
  name: string;
  sprint: string;
  /** Hours, as estimated at planning. */
  estimate: number;
  status: "to do" | "in progress" | "in review" | "done";
}

const item = (id: string, task: string, lane: string, from: number, to: number, name: string, estimate: number, status: WorkItem["status"]): WorkItem =>
  ({ id, task, lane, from, to, name, sprint: "sprint-14", estimate, status });

const WORK: readonly WorkItem[] = [
  item("w-101", "portal", "arjun", at(9), at(11, 17), "Sign-in with e-mail code", 18, "done"),
  item("w-102", "portal", "arjun", at(12), at(17, 17), "Profile page", 26, "in progress"),
  item("w-103", "portal", "chloe", at(9), at(10, 17), "Session handling", 12, "done"),
  item("w-104", "shop", "chloe", at(11), at(13, 17), "Basket keeps items across devices", 20, "in review"),
  item("w-105", "portal", "chloe", at(16), at(19, 17), "Change of address form", 24, "in progress"),
  item("w-106", "portal", "noah", at(9), at(12, 13), "Profile page design", 14, "done"),
  item("w-107", "shop", "noah", at(16), at(18, 17), "Search results layout", 12, "to do"),
  item("w-108", "portal", "eva", at(12), at(13, 17), "Test plan for sign-in", 10, "done"),
  item("w-109", "portal", "eva", at(17), at(20, 17), "Regression run", 20, "to do"),
  item("w-110", "booking", "hana", at(9), at(13, 17), "Reminder scheduling service", 32, "done"),
  item("w-111", "booking", "hana", at(16), at(20, 17), "Push notifications", 30, "in progress"),
  item("w-112", "booking", "kofi", at(10), at(12, 17), "Calendar sync", 18, "done"),
  item("w-113", "intranet", "kofi", at(16), at(18, 17), "News feed", 16, "in progress"),
  item("w-114", "booking", "freya", at(9), at(11, 17), "Reminder settings screen", 16, "done"),
  item("w-115", "booking", "freya", at(18), at(20, 17), "Store screenshots", 12, "to do"),
  item("w-116", "booking", "david", at(16), at(19, 13), "Device test matrix", 14, "to do"),
];

const TONE: Record<WorkItem["status"], BadgeTone> = {
  "to do": "neutral",
  "in progress": "accent",
  "in review": "warning",
  done: "success",
};

export default function InAList() {
  return (
    <Stack gap={2} style={{ maxWidth: 520 }}>
      {WORK.filter((item) => item.task === "portal").map((item) => (
        <Stack key={item.id} direction="row" gap={3} align="center">
          <Text as="span" size="sm" mono tone="muted">
            {item.id}
          </Text>
          <Text as="span" size="sm" style={{ flex: 1 }}>
            {item.name}
          </Text>
          <Badge tone={TONE[item.status]}>{item.status}</Badge>
        </Stack>
      ))}
    </Stack>
  );
}
```

#### When to use something else

- The user can remove it, or it stands for a chosen filter → Tag
- A figure read against limits → Stat

#### Keyboard

The keys of [Button](#/button/keyboard-button) apply here.

#### API

##### `BadgeProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `tone` | [`BadgeTone`](#type-BadgeTone)<br>`"neutral" \| "accent" \| "success" \| "warning" \| "danger"` | `"neutral"` | What the badge stands for. There is always a word beside it: a colour on its own is not a statement.<br>Shown in: [Configurator](#/badge/configurator-badge), [Tones](#/badge/tones), [Counters](#/badge/counters) and 19 more |
| `pill` | `boolean` | `false` | Fully rounded pill shape - for counters and key figures. The default is the slightly rounded badge shape for status labels.<br>Shown in: [Configurator](#/badge/configurator-badge), [Counters](#/badge/counters), [Fold the body (Card)](#/card/fold-the-body) and 1 more |
| `ref` | `Ref<HTMLSpanElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<span>`.

##### Types on this page

###### `BadgeTone`

What a badge stands for - never the only statement, a word stands beside
it.

```ts
type BadgeTone = "neutral" | "accent" | "success" | "warning" | "danger";
```

#### Known limits

- It cannot be clicked or removed; a label the user acts on is a [Tag](#/tag).
- It counts nothing itself: capping at “99+” is yours.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Tag

A short label on content that the user can remove where you allow it (also called a chip). Reach for it for active filters, chosen values and assignments.

```ts
import { Tag, TagGroup } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/tag/

`onRemove` turns the label into a control. In a `TagGroup` the whole group is one tab stop, and focus moves to the neighbour after a removal instead of falling to the top of the page.

A `disabled` tag keeps its place and loses its remove button: disabled speaks about the button, not the label. Every tone keeps its contrast in both themes, and the word carries the meaning.

#### Examples

##### A tag

A short label on content – here the depot a vehicle belongs to.

```tsx
import { Tag } from "@umriss-ui/core";

export default function ATag() {
  return <Tag>North depot</Tag>;
}
```

##### Tones

Every `tone` keeps its contrast in both themes, and the word beside the colour carries the meaning on its own.

```tsx
import { Stack, Tag } from "@umriss-ui/core";

export default function Tones() {
  return (
    <Stack direction="row" gap={2} wrap align="center">
      <Tag>Van</Tag>
      <Tag tone="accent">E-van</Tag>
      <Tag tone="success">On time</Tag>
      <Tag tone="warning">Window at risk</Tag>
      <Tag tone="danger">Failed attempt</Tag>
    </Stack>
  );
}
```

##### Remove tags from a group

`onRemove` adds a remove button; in a `TagGroup` the arrow keys move between tags and focus lands on the neighbour after a removal. A tag whose content is more than text - the on-call mark - needs `removeLabel`, as no name for its button can be read from markup.

```tsx
import { useState } from "react";
import { Button, Stack, Tag, TagGroup, Text } from "@umriss-ui/core";

const INITIAL = ["Martin Hale", "Nadia Petrova", "Owen Carter"];

export default function Removable() {
  const [drivers, setDrivers] = useState(INITIAL);
  const [standby, setStandby] = useState(true);

  return (
    <Stack gap={3} align="flex-start">
      <TagGroup aria-label="Drivers on the early tours">
        {drivers.map((driver) => (
          <Tag key={driver} tone="accent" onRemove={() => setDrivers((all) => all.filter((d) => d !== driver))}>
            {driver}
          </Tag>
        ))}
        {standby && (
          <Tag tone="accent" removeLabel="Remove Sven Berg (on call)" onRemove={() => setStandby(false)}>
            <Text as="span" size="xs" weight="semibold">
              On call
            </Text>{" "}
            Sven Berg
          </Tag>
        )}
        <Tag disabled onRemove={() => {}}>
          Lucia Romero (lead)
        </Tag>
      </TagGroup>
      {(drivers.length < INITIAL.length || !standby) && (
        <Button
          size="sm"
          onClick={() => {
            setDrivers(INITIAL);
            setStandby(true);
          }}
        >
          Reset
        </Button>
      )}
    </Stack>
  );
}
```

##### Build a filter bar

Each active filter is a removable tag; the list below follows them, and an empty result offers to clear them all.

```tsx
import { useState } from "react";
import { Button, EmptyState, Select, Stack, Tag, TagGroup, Text } from "@umriss-ui/core";

interface Shipment {
  id: string;
  customer: string;
  depot: string;
  status: "delivered" | "out for delivery" | "failed attempt";
}

const SHIPMENTS: Shipment[] = [
  { id: "SH-1042", customer: "Harlow Bakery", depot: "North depot", status: "delivered" },
  { id: "SH-1043", customer: "Pine & Oak Florist", depot: "North depot", status: "out for delivery" },
  { id: "SH-1051", customer: "Quayside Books", depot: "Riverside depot", status: "failed attempt" },
  { id: "SH-1052", customer: "Moreau Optics", depot: "Riverside depot", status: "out for delivery" },
  { id: "SH-1063", customer: "Linden Dental", depot: "East Gate depot", status: "delivered" },
];

type Filter = { key: "depot" | "status"; value: string };

const OPTIONS: Filter[] = [
  ...["North depot", "Riverside depot", "East Gate depot"].map((value) => ({ key: "depot" as const, value })),
  ...["delivered", "out for delivery", "failed attempt"].map((value) => ({ key: "status" as const, value })),
];

export default function AFilterBar() {
  const [filters, setFilters] = useState<Filter[]>([{ key: "depot", value: "North depot" }]);

  const shown = SHIPMENTS.filter((shipment) =>
    (["depot", "status"] as const).every((key) => {
      const wanted = filters.filter((f) => f.key === key).map((f) => f.value);
      return wanted.length === 0 || wanted.includes(shipment[key]);
    }),
  );

  return (
    <Stack gap={3} style={{ maxWidth: 560 }}>
      <Stack direction="row" gap={3} align="center" wrap>
        <div style={{ width: 200 }}>
          <Select
            size="sm"
            aria-label="Add a filter"
            value=""
            onChange={(event) => {
              const picked = OPTIONS[Number(event.target.value)];
              if (picked && !filters.some((f) => f.value === picked.value)) setFilters([...filters, picked]);
            }}
          >
            <option value="" disabled>
              Add a filter …
            </option>
            {OPTIONS.map((option, i) => (
              <option key={option.value} value={i}>
                {option.key === "depot" ? "Depot" : "Status"}: {option.value}
              </option>
            ))}
          </Select>
        </div>
        <TagGroup aria-label="Active filters">
          {filters.map((filter) => (
            <Tag key={filter.value} tone="accent" onRemove={() => setFilters(filters.filter((f) => f !== filter))}>
              {filter.value}
            </Tag>
          ))}
        </TagGroup>
        {filters.length > 0 && (
          <Button size="sm" variant="ghost" onClick={() => setFilters([])}>
            Clear all
          </Button>
        )}
      </Stack>
      {shown.length === 0 ? (
        <EmptyState
          title="No shipments match"
          description="Remove a filter to see more."
          action={
            <Button size="sm" onClick={() => setFilters([])}>
              Clear the filters
            </Button>
          }
        />
      ) : (
        shown.map((shipment) => (
          <Stack key={shipment.id} direction="row" gap={3}>
            <Text as="span" size="sm" mono>
              {shipment.id}
            </Text>
            <Text as="span" size="sm" style={{ flex: 1 }}>
              {shipment.customer}
            </Text>
            <Text as="span" size="sm" tone="muted">
              {shipment.status}
            </Text>
          </Stack>
        ))
      )}
    </Stack>
  );
}
```

#### When to use something else

- A status that cannot be acted on → Badge
- The user picks several values from a list → MultiSelect

#### Keyboard

| Key | Action |
|---|---|
| `Tab` | Enters the group on one tag and leaves it on the next Tab. |
| `← / → or ↑ / ↓` | Moves to the previous or next tag in the group. |
| `Home / End` | Moves to the first or last tag. |
| `Delete or Backspace` | Removes the focused tag and moves focus to its neighbour. |

#### API

##### `TagProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `tone` | [`TagTone`](#type-TagTone)<br>`"neutral" \| "accent" \| "success" \| "warning" \| "danger"` | `"neutral"` | What the label stands for. The tone is never the only information: the text beside it says the same thing once more.<br>Shown in: [Configurator](#/tag/configurator-tag), [Tones](#/tag/tones), [Remove tags from a group](#/tag/removable) and 2 more |
| `children` *required* | `ReactNode` | — | The text of the label – short enough to stand on one line.<br>Shown in: [Configurator](#/tag/configurator-tag), [A tag](#/tag/a-tag), [Tones](#/tag/tones) and 5 more |
| `removeLabel` | `string` | — | Label of the remove key. Needed as soon as the content is not text – no sentence can be formed out of a node.<br>Shown in: [Remove tags from a group](#/tag/removable) |
| `disabled` | `boolean` | `false` | Takes the remove key away from the tag without hiding it: disabled is a statement about the key and not about the label.<br>Shown in: [Configurator](#/tag/configurator-tag), [Remove tags from a group](#/tag/removable) |
| `ref` | `Ref<HTMLSpanElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onRemove` | `() => void` | — | Makes the tag removable. Without this it is a pure label.<br>Shown in: [Remove tags from a group](#/tag/removable), [Build a filter bar](#/tag/a-filter-bar), [Say why a filter found nothing (EmptyState)](#/emptystate/a-filter-found-nothing) |

Also takes every attribute of `<span>` – without `onRemove`.

##### `TagGroupProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

###### Accessibility

| Prop | Type | Default | Description |
|---|---|---|---|
| `aria-label` *required* | `string` | — | Label of the group for the screen reader.<br>Shown in: [Remove tags from a group](#/tag/removable), [Build a filter bar](#/tag/a-filter-bar), [Say why a filter found nothing (EmptyState)](#/emptystate/a-filter-found-nothing) and 1 more |

Also takes every attribute of `<div>`.

##### Types on this page

###### `TagTone`

What a tag stands for - never the only statement, its text says it too.

```ts
type TagTone = "neutral" | "accent" | "success" | "warning" | "danger";
```

#### Known limits

- No field for typing new tags: a tag input is a [MultiSelect](#/multiselect).
- Tags are not toggles: a set of choices to switch on and off is a group of [Checkbox](#/checkbox) or a [ButtonGroup](#/buttongroup).

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Stat

A single figure with its verdict: read against limits, with the history before it, the deviation from its target and how fresh it is (also called a KPI tile or metric card). Reach for it for the few numbers a screen is watched for.

```ts
import { Stat, useFreshness } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/stat/

The tile gets a rule, not a colour: `limits` are values with a side and a severity, and the colour and the verdict word follow from them. The same limit model drives the charts' limit lines ([ADR-0006](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0006-the-limit-model-lives-in-both-packages.md)).

Four verdicts, in order: in order, unknown, warning, alarm. A missing or non-finite value is unknown, never in order. A `target` is missed by an amount and shown as a signed deviation; it is never a limit.

Freshness is a separate axis: with `asOf` and `ages` the tile says when its value is stale or lost and keeps its verdict, since the last value is the best one there is ([ADR-0010](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0010-a-stale-value-keeps-its-verdict.md)). [`useFreshness`](#/api/useFreshness) gives the same reading for your own parts.

#### Examples

##### A figure

A `label`, a `value` and its `unit`; without limits the figure is neutral, as it should be for a number nobody judged.

```tsx
import { Stat } from "@umriss-ui/core";

export default function AFigure() {
  return (
    <div style={{ maxWidth: 240 }}>
      <Stat label="Requests per minute · Checkout" value={812} decimals={0} />
    </div>
  );
}
```

##### Read a value against its limits

Pass `limits` – a value, a side and a severity each – and the tile takes its colour and its verdict word from them.

```tsx
import { Grid, Stat } from "@umriss-ui/core";
import type { LimitSet } from "@umriss-ui/core";

/** Checkout's latency objective: warn from 240 ms, alarm from 300 ms. */
const CHECKOUT_P95: LimitSet = {
  limits: [
    { value: 240, side: "upper", severity: "warning" },
    { value: 300, side: "upper", severity: "alarm" },
  ],
};

export default function AgainstLimits() {
  return (
    <Grid minItemWidth="200px" gap={4}>
      <Stat label="p95 latency at 08:00" value={187} unit="ms" decimals={0} limits={CHECKOUT_P95} />
      <Stat label="p95 latency at 09:35" value={262} unit="ms" decimals={0} limits={CHECKOUT_P95} />
      <Stat label="p95 latency at 09:50" value={498} unit="ms" decimals={0} limits={CHECKOUT_P95} />
    </Grid>
  );
}
```

##### Show a value nobody has

A `null`, missing or non-finite value is judged unknown and says so – never a zero, never “in order”.

```tsx
import { Grid, Stat } from "@umriss-ui/core";
import type { LimitSet } from "@umriss-ui/core";

const ERROR_RATE: LimitSet = {
  limits: [
    { value: 1, side: "upper", severity: "warning" },
    { value: 2, side: "upper", severity: "alarm" },
  ],
};

export default function Unknown() {
  return (
    <Grid minItemWidth="200px" gap={4}>
      <Stat label="Error rate · Sign-in · no data" value={null} unit="%" limits={ERROR_RATE} />
      <Stat label="Error rate · Search · not reported" value={undefined} unit="%" limits={ERROR_RATE} />
      <Stat label="Error rate · Reporting · no requests" value={0 / 0} unit="%" limits={ERROR_RATE} />
    </Grid>
  );
}
```

##### Add a history

`history` draws the values before it as a line across the tile - under the figure, or beside it where the tile is wide: the shape of the last hours, not a trend arrow.

```tsx
import { Stat } from "@umriss-ui/core";
import type { LimitSet } from "@umriss-ui/core";

/* Data from the operations world, written out here so the example runs on its own. */
/** A small LCG - the same numbers on every computer. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

const at = (day: number, hours: number, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();
const MINUTE = 60_000;

/** Tuesday, 17 March 2026, 10:30 - the moment the screens are read at. */
const NOW = at(17, 10, 30);

interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface MetricPoint {
  t: number;
  /** Median and 95th percentile latency, in ms. */
  p50: number;
  p95: number;
  /** Failed requests, in per cent. */
  errorRate: number;
  /** Requests per minute. */
  requests: number;
}

/** Requests per minute at the busiest hour, by tier. */
const VOLUME = { 1: 900, 2: 400, 3: 120 } as const;

/** A service's latency and error rate every five minutes of today, from
    midnight up to now. Busy by day, quiet at night; Checkout's 95th percentile
    climbs well past its objective from 09:40 to 10:10, and its errors with it. */
function metrics(serviceId: string): MetricPoint[] {
  const index = SERVICES.findIndex((one) => one.id === serviceId);
  const service = SERVICES[index];
  if (service === undefined) throw new Error(`No service "${serviceId}".`);
  const r = random(1000 + index * 37);
  const points: MetricPoint[] = [];
  let drift = 0;
  for (let t = at(17, 0); t <= NOW; t += 5 * MINUTE) {
    const hour = (t - at(17, 0)) / (60 * MINUTE);
    const load = 0.35 + 0.65 * Math.max(0, Math.sin((Math.PI * (hour - 5)) / 16));
    drift = 0.8 * drift + (r() - 0.5) * 0.08;
    const base = service.latencySlo * (0.45 + 0.2 * load + drift);
    const surge = serviceId === "checkout" && t >= at(17, 9, 40) && t < at(17, 10, 10) ? 1.9 : 1;
    const p95 = Math.round(base * surge * (1 + r() * 0.08));
    points.push({
      t,
      p50: Math.round(p95 * (0.42 + r() * 0.06)),
      p95,
      errorRate: Math.round((0.05 + r() * 0.12 + (surge > 1 ? 2.4 + r() : 0)) * 100) / 100,
      requests: Math.round(VOLUME[service.tier] * load * (1 + (r() - 0.5) * 0.1)),
    });
  }
  return points;
}

const CHECKOUT_P95: LimitSet = {
  limits: [
    { value: 240, side: "upper", severity: "warning" },
    { value: 300, side: "upper", severity: "alarm" },
  ],
};

/** The last two hours, every five minutes. */
const LAST = metrics("checkout").slice(-24);

export default function History() {
  return (
    <div style={{ maxWidth: 260 }}>
      <Stat
        label="p95 latency · Checkout"
        value={LAST.at(-1)?.p95}
        unit="ms"
        decimals={0}
        limits={CHECKOUT_P95}
        history={LAST.map((point) => point.p95)}
      />
    </div>
  );
}
```

##### Give the history room

A tile of 380 px and more puts its history beside the figures, as high as they are; a narrower one keeps it beneath. The tile decides by its own width.

```tsx
import { Grid, Stat } from "@umriss-ui/core";
import type { LimitSet } from "@umriss-ui/core";

/* Data from the operations world, written out here so the example runs on its own. */
/** A small LCG - the same numbers on every computer. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

const at = (day: number, hours: number, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();
const MINUTE = 60_000;

/** Tuesday, 17 March 2026, 10:30 - the moment the screens are read at. */
const NOW = at(17, 10, 30);

interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface MetricPoint {
  t: number;
  /** Median and 95th percentile latency, in ms. */
  p50: number;
  p95: number;
  /** Failed requests, in per cent. */
  errorRate: number;
  /** Requests per minute. */
  requests: number;
}

/** Requests per minute at the busiest hour, by tier. */
const VOLUME = { 1: 900, 2: 400, 3: 120 } as const;

/** A service's latency and error rate every five minutes of today, from
    midnight up to now. Busy by day, quiet at night; Checkout's 95th percentile
    climbs well past its objective from 09:40 to 10:10, and its errors with it. */
function metrics(serviceId: string): MetricPoint[] {
  const index = SERVICES.findIndex((one) => one.id === serviceId);
  const service = SERVICES[index];
  if (service === undefined) throw new Error(`No service "${serviceId}".`);
  const r = random(1000 + index * 37);
  const points: MetricPoint[] = [];
  let drift = 0;
  for (let t = at(17, 0); t <= NOW; t += 5 * MINUTE) {
    const hour = (t - at(17, 0)) / (60 * MINUTE);
    const load = 0.35 + 0.65 * Math.max(0, Math.sin((Math.PI * (hour - 5)) / 16));
    drift = 0.8 * drift + (r() - 0.5) * 0.08;
    const base = service.latencySlo * (0.45 + 0.2 * load + drift);
    const surge = serviceId === "checkout" && t >= at(17, 9, 40) && t < at(17, 10, 10) ? 1.9 : 1;
    const p95 = Math.round(base * surge * (1 + r() * 0.08));
    points.push({
      t,
      p50: Math.round(p95 * (0.42 + r() * 0.06)),
      p95,
      errorRate: Math.round((0.05 + r() * 0.12 + (surge > 1 ? 2.4 + r() : 0)) * 100) / 100,
      requests: Math.round(VOLUME[service.tier] * load * (1 + (r() - 0.5) * 0.1)),
    });
  }
  return points;
}

const P95: LimitSet = {
  limits: [
    { value: 240, side: "upper", severity: "warning" },
    { value: 300, side: "upper", severity: "alarm" },
  ],
};

const ERRORS: LimitSet = {
  limits: [
    { value: 1, side: "upper", severity: "warning" },
    { value: 2, side: "upper", severity: "alarm" },
  ],
};

/** Checkout since six this morning, every five minutes. */
const MORNING = metrics("checkout").slice(-54);

export default function GiveTheHistoryRoom() {
  return (
    <Grid minItemWidth="380px" gap={4}>
      <Stat
        label="p95 latency · Checkout · since 06:00"
        value={MORNING.at(-1)?.p95}
        unit="ms"
        decimals={0}
        limits={P95}
        history={MORNING.map((point) => point.p95)}
      />
      <Stat
        label="Error rate · Checkout · since 06:00"
        value={MORNING.at(-1)?.errorRate}
        unit="%"
        decimals={2}
        limits={ERRORS}
        history={MORNING.map((point) => point.errorRate)}
      />
    </Grid>
  );
}
```

##### Measure against a target

A `target` is missed by an amount, never violated: the tile shows the signed deviation beside its verdict from the limits.

```tsx
import { Grid, Stat } from "@umriss-ui/core";
import type { LimitSet } from "@umriss-ui/core";

/** February's spend in k€, against each centre's monthly budget as target; over by 5 % warns, by 15 % alarms. */
function budget(monthly: number): LimitSet {
  return {
    target: monthly,
    limits: [
      { value: monthly * 1.05, side: "upper", severity: "warning" },
      { value: monthly * 1.15, side: "upper", severity: "alarm" },
    ],
  };
}

export default function ATarget() {
  return (
    <Grid minItemWidth="200px" gap={4}>
      <Stat label="Sales · February" value={138.9} unit="k€" decimals={1} limits={budget(142)} />
      <Stat label="Marketing · February" value={74.3} unit="k€" decimals={1} limits={budget(68)} />
      <Stat label="IT · February" value={96.1} unit="k€" decimals={1} limits={budget(83)} />
    </Grid>
  );
}
```

##### Show how fresh a value is

With `asOf` and `ages` the tile says when its value turns stale or lost – and keeps its verdict, since the last value is still the best one.

```tsx
import { Grid, Stack, Stat, Text, useFreshness } from "@umriss-ui/core";
import type { FreshnessAges, LimitSet } from "@umriss-ui/core";

/* Distances from the moment the page loaded, so the three always read the same. */
const LOADED = Date.now();
const MIN = 60_000;

/** Stale after two minutes without a new value, lost after ten. */
const AGES: FreshnessAges = { stale: 2 * MIN, lost: 10 * MIN };

const CHECKOUT_P95: LimitSet = {
  limits: [
    { value: 240, side: "upper", severity: "warning" },
    { value: 300, side: "upper", severity: "alarm" },
  ],
};

function Caption({ asOf }: { asOf: number }) {
  const { freshness } = useFreshness(asOf, AGES);
  return (
    <Text size="xs" tone="muted">
      Feed: {freshness}
    </Text>
  );
}

export default function Freshness() {
  return (
    <Grid minItemWidth="200px" gap={4}>
      {[
        { name: "live", asOf: LOADED - 20_000 },
        { name: "delayed", asOf: LOADED - 4 * MIN },
        { name: "cut off", asOf: LOADED - 25 * MIN },
      ].map((feed) => (
        <Stack key={feed.name} gap={2}>
          <Stat label={`p95 latency · ${feed.name}`} value={318} unit="ms" decimals={0} limits={CHECKOUT_P95} asOf={feed.asOf} ages={AGES} />
          <Caption asOf={feed.asOf} />
        </Stack>
      ))}
    </Grid>
  );
}
```

##### Watch a kiln zone

One limit set with a target and limits on both sides: the tolerance band between the warnings is derived, never passed.

```tsx
import { Grid, Stat } from "@umriss-ui/core";
import type { LimitSet } from "@umriss-ui/core";

/* Data from the plant world, written out here so the example runs on its own. */

/** A small LCG - reproducible across runs and platforms. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

/** The early shift, 06:00 to 14:00. */
const SHIFT_MINUTES = 480;

/** The kiln's zone 3, in °C: the numbers every part reads it against, once.
    Between the two warnings lies the tolerance - a tile fired outside it is
    scrap; `returnTo` is the alarm's dead band. */
const KILN = { target: 1200, tolerance: [1185, 1215], alarm: 1230, returnTo: 1222 } as const;

/** The same numbers as the limit set the tile and the verdict read. */
const KILN_LIMITS: LimitSet = {
  target: KILN.target,
  limits: [
    { value: KILN.tolerance[1], side: "upper", severity: "warning" },
    { value: KILN.alarm, side: "upper", severity: "alarm" },
    { value: KILN.tolerance[0], side: "lower", severity: "warning" },
  ],
};

/** The kiln fires one tile every quarter of a minute when nothing holds it up -
    the ideal cycle time of the OEE's performance. */
const IDEAL_CYCLE_MINUTES = 0.25;

/** One minute of the line. */
interface Reading {
  /** Minutes since the start of the shift. */
  minute: number;
  /** Zone 3 of the kiln, in °C. */
  kiln: number;
  /** The exit pyrometer, in °C - `null` while it sends nothing. */
  exit: number | null;
  /** Whether the belt runs. */
  running: boolean;
  /** Tiles out of the kiln in this minute. */
  fired: number;
  /** Of them, the ones fired inside the tolerance. */
  good: number;
}

/** A tile taken off the belt and measured - one every ten minutes while it runs. */
interface Sample {
  minute: number;
  /** The tile's length after firing, in mm (nominal 600). */
  length: number;
}

/** A batch of tiles through the three stations. */
interface Batch {
  id: string;
  name: string;
  /** How many tiles the batch is planned for. */
  tiles: number;
  /** Minutes since the start of the shift, per station. */
  press: readonly [number, number];
  dryer: readonly [number, number];
  kiln: readonly [number, number];
}

interface Plant {
  readings: readonly Reading[];
  samples: readonly Sample[];
  batches: readonly Batch[];
}

/* When the exit pyrometer goes silent, and for how long. Fixed rather than
   seeded, so that a running control room shows its reading turn stale, then
   lost, and come back. */
const SILENT_FROM = 288;
const SILENT_FOR = 50;

/** The shift, from a seed. */
function plant(seed: number): Plant {
  const r = random(seed);

  /* The one excursion: a burner overshoots somewhere between 02:30 and 03:30
     into the shift, for half an hour, peaking near 1242 °C. The operator stops
     the feed twenty-two minutes in, for eighteen minutes. The noise around it
     is too small to reach a warning on its own, so this is the only crossing -
     which is what the tests hold. */
  const surgeFrom = 150 + Math.floor(r() * 60);
  const surgeFor = 30;
  const stopFrom = surgeFrom + 22;
  const stopFor = 18;

  /* The plan: batches through the kiln one after another, each pressed an
     hour and dried half an hour before - the first ones during the night
     shift. Tiles come out of the kiln only while a batch is in it, so the
     OEE's count and the batches' counts are the same tiles. The plan is a
     plan: a stop of the belt does not move it. */
  const batches: Batch[] = [];
  for (let at = 0, i = 0; at < SHIFT_MINUTES; i++) {
    const length = 70 + Math.floor(r() * 25);
    batches.push({
      id: `b-${4121 + i}`,
      name: `B-${4121 + i}`,
      tiles: Math.round(length / IDEAL_CYCLE_MINUTES / 10) * 10,
      press: [at - 60, at - 60 + length],
      dryer: [at - 30, at - 30 + length],
      kiln: [at, at + length],
    });
    at += length + 5;
  }

  const readings: Reading[] = [];
  const samples: Sample[] = [];
  let drift = 0;
  for (let minute = 0; minute < SHIFT_MINUTES; minute++) {
    drift = 0.9 * drift + (r() - 0.5) * 3;
    const into = minute - surgeFrom;
    const surge = into >= 0 && into <= surgeFor ? 42 * Math.sin((Math.PI * into) / surgeFor) : 0;
    const kiln = Math.round((KILN.target + drift + surge) * 10) / 10;

    const running = !(minute >= stopFrom && minute < stopFrom + stopFor);
    const loaded = batches.some((batch) => batch.kiln[0] <= minute && minute < batch.kiln[1]);
    const jam = r() < 0.12;
    const fired = running && loaded ? (jam ? 3 : 4) : 0;
    const inTolerance = kiln >= KILN.tolerance[0] && kiln <= KILN.tolerance[1];
    const silent = minute >= SILENT_FROM && minute < SILENT_FROM + SILENT_FOR;
    const exit = silent ? null : Math.round((kiln - 380 + (r() - 0.5) * 4) * 10) / 10;

    readings.push({ minute, kiln, exit, running, fired, good: inTolerance ? fired : 0 });

    if (running && minute % 10 === 0) {
      /* Hotter shrinks more: the length follows the kiln, so the control
         chart sees the excursion the trend sees. */
      const length = 600 + (KILN.target - kiln) * 0.05 + (r() - 0.5) * 0.6;
      samples.push({ minute, length: Math.round(length * 100) / 100 });
    }
  }

  return { readings, samples, batches };
}

const { readings } = plant(17);

/** The last hour of the shift so far, minute by minute. */
function lastHour(until: number) {
  return readings.filter((one) => one.minute > until - 60 && one.minute <= until).map((one) => one.kiln);
}

export default function AKilnZone() {
  return (
    <Grid minItemWidth="220px" gap={4}>
      {[120, 170, 180].map((minute) => {
        const hour = lastHour(minute);
        return (
          <Stat
            key={minute}
            label={`Kiln K1 · zone 3 · ${String(6 + Math.floor(minute / 60)).padStart(2, "0")}:${String(minute % 60).padStart(2, "0")}`}
            value={hour.at(-1)}
            unit="°C"
            decimals={0}
            limits={KILN_LIMITS}
            history={hour}
          />
        );
      })}
    </Grid>
  );
}
```

##### Watch the services that page at night

A row of tiles per service, each read against its own objective, with the last two hours beneath and a freshness for the feed.

```tsx
import { Card, CardBody, CardHeader, Grid, Stat } from "@umriss-ui/core";
import type { FreshnessAges, LimitSet } from "@umriss-ui/core";

/* Data from the operations world, written out here so the example runs on its own. */
/** A small LCG - the same numbers on every computer. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

const at = (day: number, hours: number, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();
const MINUTE = 60_000;

/** Tuesday, 17 March 2026, 10:30 - the moment the screens are read at. */
const NOW = at(17, 10, 30);

interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface MetricPoint {
  t: number;
  /** Median and 95th percentile latency, in ms. */
  p50: number;
  p95: number;
  /** Failed requests, in per cent. */
  errorRate: number;
  /** Requests per minute. */
  requests: number;
}

/** Requests per minute at the busiest hour, by tier. */
const VOLUME = { 1: 900, 2: 400, 3: 120 } as const;

/** A service's latency and error rate every five minutes of today, from
    midnight up to now. Busy by day, quiet at night; Checkout's 95th percentile
    climbs well past its objective from 09:40 to 10:10, and its errors with it. */
function metrics(serviceId: string): MetricPoint[] {
  const index = SERVICES.findIndex((one) => one.id === serviceId);
  const service = SERVICES[index];
  if (service === undefined) throw new Error(`No service "${serviceId}".`);
  const r = random(1000 + index * 37);
  const points: MetricPoint[] = [];
  let drift = 0;
  for (let t = at(17, 0); t <= NOW; t += 5 * MINUTE) {
    const hour = (t - at(17, 0)) / (60 * MINUTE);
    const load = 0.35 + 0.65 * Math.max(0, Math.sin((Math.PI * (hour - 5)) / 16));
    drift = 0.8 * drift + (r() - 0.5) * 0.08;
    const base = service.latencySlo * (0.45 + 0.2 * load + drift);
    const surge = serviceId === "checkout" && t >= at(17, 9, 40) && t < at(17, 10, 10) ? 1.9 : 1;
    const p95 = Math.round(base * surge * (1 + r() * 0.08));
    points.push({
      t,
      p50: Math.round(p95 * (0.42 + r() * 0.06)),
      p95,
      errorRate: Math.round((0.05 + r() * 0.12 + (surge > 1 ? 2.4 + r() : 0)) * 100) / 100,
      requests: Math.round(VOLUME[service.tier] * load * (1 + (r() - 0.5) * 0.1)),
    });
  }
  return points;
}

const LOADED = Date.now();
const AGES: FreshnessAges = { stale: 2 * 60_000, lost: 10 * 60_000 };

/** Warn at 80 % of the latency objective, alarm at the objective. */
function latency(service: Service): LimitSet {
  return {
    limits: [
      { value: service.latencySlo * 0.8, side: "upper", severity: "warning" },
      { value: service.latencySlo, side: "upper", severity: "alarm" },
    ],
  };
}

const ERRORS: LimitSet = {
  limits: [
    { value: 1, side: "upper", severity: "warning" },
    { value: 2, side: "upper", severity: "alarm" },
  ],
};

export default function AServiceOverview() {
  return (
    <Grid minItemWidth="320px" gap={4}>
      {SERVICES.filter((service) => service.tier === 1).map((service) => {
        const last = metrics(service.id).slice(-24);
        const now = last.at(-1);
        return (
          <Card key={service.id}>
            <CardHeader eyebrow={service.team} title={service.name} />
            <CardBody>
              <Grid minItemWidth="130px" gap={3}>
                <Stat
                  label="p95 latency"
                  value={now?.p95}
                  unit="ms"
                  decimals={0}
                  limits={latency(service)}
                  history={last.map((point) => point.p95)}
                  asOf={LOADED - 40_000}
                  ages={AGES}
                />
                <Stat
                  label="Error rate"
                  value={now?.errorRate}
                  unit="%"
                  decimals={2}
                  limits={ERRORS}
                  history={last.map((point) => point.errorRate)}
                  asOf={LOADED - 40_000}
                  ages={AGES}
                />
              </Grid>
            </CardBody>
          </Card>
        );
      })}
    </Grid>
  );
}
```

#### When to use something else

- A share of a whole, drawn as a bar → Meter
- Only the shape of a history, in a row or a cell → Sparkline
- A value over time with axes and limit lines → `Line` and `LimitLine` from @umriss-ui/charts

#### Accessibility

A `group` whose name says what the tile shows: the label, the value with its unit, and where the verdict is not OK its words, as in "p95 latency at 09:50: 498 ms, Alarm limit exceeded". A missing value is named "No value". The verdict also stands in the tile as a word, so the colour is never alone; the history line is hidden from screen readers.

It announces nothing: a value that changes or a verdict that turns is read when a reader reaches the tile. Where a change must be heard at once, say it in an [Alert](#/alert).

#### API

##### `StatProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` *required* | `string` | — | What is being measured.<br>Shown in: [Configurator](#/stat/configurator-stat), [A figure](#/stat/a-figure), [Read a value against its limits](#/stat/against-limits) and 15 more |
| `value` *required* | `number \| null \| undefined` | — | The measured value. Absent or non-finite gives the verdict `unknown` – and the tile says so, instead of showing a zero or an empty bar.<br>Shown in: [Configurator](#/stat/configurator-stat), [A figure](#/stat/a-figure), [Read a value against its limits](#/stat/against-limits) and 15 more |
| `unit` | `string` | — | The unit as it stands behind the value – „ms", „%", „GB".<br>Shown in: [Configurator](#/stat/configurator-stat), [Read a value against its limits](#/stat/against-limits), [Show a value nobody has](#/stat/unknown) and 14 more |
| `decimals` | `number` | — | Fixed number of decimal places. Without it the notation decides; a metric whose number of digits jumps reads as a jump in the value.<br>Shown in: [Configurator](#/stat/configurator-stat), [A figure](#/stat/a-figure), [Read a value against its limits](#/stat/against-limits) and 12 more |
| `limits` | [`LimitSet`](#type-LimitSet) | — | The rule the value is read against. Without it the tile is neutral – the honest display of a number for which nobody has named a rule.<br>Shown in: [Read a value against its limits](#/stat/against-limits), [Show a value nobody has](#/stat/unknown), [Add a history](#/stat/history) and 12 more |
| `history` | `readonly number[]` | — | Values in chronological order; yields the history line, across the tile beneath the figures, or beside them in a tile of 380 px and more.<br>Shown in: [Add a history](#/stat/history), [Give the history room](#/stat/give-the-history-room), [Watch a kiln zone](#/stat/a-kiln-zone) and 4 more |
| `asOf` | `Date \| number \| null` | — | When the value was true – not when it was fetched.<br>Shown in: [Show how fresh a value is](#/stat/freshness), [Watch the services that page at night](#/stat/a-service-overview), [Watch a kiln line over a shift (Scenarios)](#/scenarios/watch-a-kiln-line) |
| `ages` | [`FreshnessAges`](#type-FreshnessAges) | — | Without ages there is no freshness display and no cadence.<br>Shown in: [Show how fresh a value is](#/stat/freshness), [Watch the services that page at night](#/stat/a-service-overview), [Watch a kiln line over a shift (Scenarios)](#/scenarios/watch-a-kiln-line) |
| `ref` | `Ref<HTMLDivElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<div>` – without `children`.

##### Types on this page

###### `LimitSet`

The set a value is read against.

The target stands beside the limits and is not one: it is missed, never
violated, and it is never the edge of a region.

| Prop | Type | Default | Description |
|---|---|---|---|
| `limits` | `readonly `[`Limit`](#type-Limit)`[]` | — | In any order; none, one or several.<br>Shown in: [Read a value against its limits](#/stat/against-limits), [Show a value nobody has](#/stat/unknown), [Add a history](#/stat/history) and 12 more |
| `target` | `number` | — | <br>Shown in: [Measure against a target](#/stat/a-target), [Watch a kiln zone](#/stat/a-kiln-zone), [English and German side by side (Language)](#/language/side-by-side) and 3 more |

###### `FreshnessAges`

The two ages at which a value changes its state, in milliseconds. Both
bounds belong to the older state: exactly five minutes old is already
`stale`.

`alt <= lost` is the sensible order. Stated the other way round, the
harder statement still wins - the middle state simply falls away.

| Prop | Type | Default | Description |
|---|---|---|---|
| `stale` *required* | `number` | — | From this age on the value counts as stale, but keeps its verdict.<br>Shown in: [Show how fresh a value is](#/stat/freshness), [Watch the services that page at night](#/stat/a-service-overview), [Watch a kiln line over a shift (Scenarios)](#/scenarios/watch-a-kiln-line) |
| `lost` *required* | `number` | — | From this age on the connection counts as disconnected.<br>Shown in: [Show how fresh a value is](#/stat/freshness), [Watch the services that page at night](#/stat/a-service-overview), [Watch a kiln line over a shift (Scenarios)](#/scenarios/watch-a-kiln-line) |

###### `Limit`

A bound: a value, a side, a severity.

No tolerance band as input. A band is derived - two limits of equal
severity on opposite sides enclose one - and as an input type it would
force a `null` on one edge in the one-sided case.

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `number` | — | <br>Shown in: [Read a value against its limits](#/stat/against-limits), [Show a value nobody has](#/stat/unknown), [Add a history](#/stat/history) and 12 more |
| `side` *required* | [`Side`](#type-Side)<br>`"upper" \| "lower"` | — | <br>Shown in: [Read a value against its limits](#/stat/against-limits), [Show a value nobody has](#/stat/unknown), [Add a history](#/stat/history) and 12 more |
| `severity` *required* | [`Severity`](#type-Severity)<br>`"warning" \| "alarm"` | — | <br>Shown in: [Read a value against its limits](#/stat/against-limits), [Show a value nobody has](#/stat/unknown), [Add a history](#/stat/history) and 12 more |

###### `Side`

Whether a limit is an upper or a lower bound.

```ts
type Side = "upper" | "lower";
```

###### `Severity`

How seriously a violation weighs: one severity that advises and one that
calls for action. Exactly two; for a third distinction one sets a
second limit.

```ts
type Severity = "warning" | "alarm";
```

#### Known limits

- No trend arrow: a direction from two noisy points is read as information it does not carry; the history line shows the shape.
- It fetches and polls nothing: freshness is judged from the `asOf` you give it.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Meter

A bar that shows a measured share, such as capacity booked or budget used, coloured by your verdict on it (also called a gauge bar or level indicator). Reach for it in lists and tables where a percentage alone is hard to compare.

```ts
import { Meter } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/meter/

`value` runs from 0 to 1 and is clamped outside; say the true figure beside the bar where it can pass 100 %.

The `tone` is your assessment, since only you know whether 90 % is good or bad; the bar never colours itself by height. Keep the number or a word beside it so the colour is never alone.

The role `meter` needs a name from you: `label` says what is measured, and neither the percentage nor a column heading counts as one.

#### Examples

##### A share

A `value` from 0 to 1, a `label` naming what is measured, and `showLabel` for the percentage beside the bar.

```tsx
import { Meter } from "@umriss-ui/core";

export default function AShare() {
  return (
    <div style={{ maxWidth: 320 }}>
      <Meter value={0.8} label="Capacity booked, Arjun Mehta" showLabel />
    </div>
  );
}
```

##### Tones

The `tone` is your verdict on the value, not its height; the figure beside it says the same for whoever cannot see colour.

```tsx
import { Grid, Meter, Stack, Text } from "@umriss-ui/core";

const CENTRES = [
  { name: "Sales", used: 0.62, tone: "neutral", note: "62 % of March's budget" },
  { name: "IT", used: 0.91, tone: "warning", note: "91 % – with a third of March left" },
  { name: "Marketing", used: 1.07, tone: "danger", note: "107 % – over budget" },
] as const;

export default function Tones() {
  return (
    <Grid minItemWidth="220px" gap={4}>
      {CENTRES.map((centre) => (
        <Stack key={centre.name} gap={2}>
          <Text size="sm" weight="medium">
            {centre.name}
          </Text>
          <Meter value={centre.used} tone={centre.tone} label={`Budget used, ${centre.name}`} />
          <Text size="xs" tone="muted">
            {centre.note}
          </Text>
        </Stack>
      ))}
    </Grid>
  );
}
```

##### Compare a team's capacity

In a table, one rule turns each share into a tone, and the hours beside the bar carry the value in words.

```tsx
import { Meter, Text } from "@umriss-ui/core";
import type { MeterTone } from "@umriss-ui/core";

/** The rule: fully booked is fine, over 100 % warns, over 120 % is a problem. */
function toneOf(share: number): MeterTone {
  if (share > 1.2) return "danger";
  if (share > 1) return "warning";
  return "neutral";
}

/** This week, 16 to 20 March: hours booked against hours available after leave. */
const ROWS = [
  { name: "Arjun Mehta", booked: 26, available: 16 },
  { name: "Chloe Durand", booked: 38, available: 40 },
  { name: "Noah Fischer", booked: 22, available: 24 },
  { name: "Hana Sato", booked: 44, available: 40 },
  { name: "Kofi Mensah", booked: 20, available: 32 },
  { name: "Freya Olsen", booked: 12, available: 24 },
].map((row) => ({ ...row, share: row.booked / row.available }));

const CELL = { padding: "var(--u-space-2) var(--u-space-3)", borderBottom: "1px solid var(--u-edge-color)" };

export default function TeamCapacity() {
  return (
    <table style={{ borderCollapse: "collapse", width: "100%", maxWidth: 560 }}>
      <thead>
        <tr>
          <th style={{ ...CELL, textAlign: "left" }}>
            <Text as="span" size="xs" tone="muted">Person</Text>
          </th>
          <th style={{ ...CELL, textAlign: "left", width: "45%" }}>
            <Text as="span" size="xs" tone="muted">Booked this week</Text>
          </th>
          <th style={{ ...CELL, textAlign: "right" }}>
            <Text as="span" size="xs" tone="muted">Hours</Text>
          </th>
        </tr>
      </thead>
      <tbody>
        {ROWS.map(({ name, booked, available, share }) => (
          <tr key={name}>
            <td style={CELL}>
              <Text as="span" size="sm">{name}</Text>
            </td>
            <td style={CELL}>
              <Meter value={share} tone={toneOf(share)} showLabel label={`Capacity booked, ${name}`} />
            </td>
            <td style={{ ...CELL, textAlign: "right", whiteSpace: "nowrap" }}>
              <Text as="span" size="sm" mono>
                {booked} / {available}
              </Text>
            </td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}
```

#### When to use something else

- How far a job has come towards its end → ProgressBar
- One figure read against limits, with its history → Stat

#### Accessibility

The role `meter`, from 0 to 100, with the whole percentage as its value. It is named by `label`, or by your `aria-labelledby`; without either it is named "Fill level", which says nothing about what is measured. The tone is not read out: say the verdict in a word beside the bar.

It is no live region: a new value is read when a reader reaches the bar. Under forced colours the track takes an edge and the fill the system's selection colour, whatever its tone.

#### API

##### `MeterProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `number` | — | Fill level from 0 to 1.<br>Shown in: [Configurator](#/meter/configurator-meter), [A share](#/meter/a-share), [Tones](#/meter/tones) and 3 more |
| `tone` | [`MeterTone`](#type-MeterTone)<br>`"neutral" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | The colour of the bar. It comes from an assessment and not from taste: beside the bar there is always the number or a word, so that the colour is never the only statement.<br>Shown in: [Configurator](#/meter/configurator-meter), [Tones](#/meter/tones), [Compare a team's capacity](#/meter/team-capacity) and 2 more |
| `showLabel` | `boolean` | `true` | The percentage to the right of the bar (Geist Mono).<br>Shown in: [Configurator](#/meter/configurator-meter), [A share](#/meter/a-share), [Compare a team's capacity](#/meter/team-capacity) and 2 more |
| `label` | `string` | the wording's "Fill level" | What is being measured, e.g. "Utilisation". A role of `meter` needs a name from the author - the visible percentage inside it does not count for that, and neither does the column heading beside it. Whoever knows what the bar measures says it better than the general term.<br>Shown in: [A share](#/meter/a-share), [Tones](#/meter/tones), [Compare a team's capacity](#/meter/team-capacity) and 2 more |
| `ref` | `Ref<HTMLSpanElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<span>`.

##### Types on this page

###### `MeterTone`

The colour of a meter's bar - an assessment, never the only statement.

```ts
type MeterTone = "neutral" | "accent" | "success" | "warning" | "danger";
```

#### Known limits

- No limit marks, target tick or scale on the bar; for a value against limits use a [Stat](#/stat).

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

### Sparkline

A small line of a history, at the height of a line of text, without axes or labels (also called a micro chart). Reach for it beside a value or in a table cell, where the shape of the last hours tells more than the figure alone.

```ts
import { Sparkline } from "@umriss-ui/core";
```

Demo page: https://romanhaendler.github.io/umriss-ui/core/sparkline/

It needs at least two values; with fewer it draws nothing. The line is ink, not meaning: the `accent` tone is for picking out one line among several, never for a verdict.

#### Examples

##### Beside a value

Pass the values in time order as `data`; the line shows their shape and the figure beside it gives the value.

```tsx
import { Sparkline, Stack, Text } from "@umriss-ui/core";

export default function BesideAValue() {
  return (
    <Stack direction="row" gap={3} align="center">
      <Text as="span" size="sm">
        Parcels delivered per hour
      </Text>
      <Sparkline data={[42, 58, 71, 66, 80, 74, 88]} />
      <Text as="span" size="sm" mono>
        88
      </Text>
    </Stack>
  );
}
```

##### Size and tone

`width` and `height` default to a table row; the `accent` tone picks out the one line among several that matters.

```tsx
import { Sparkline, Stack } from "@umriss-ui/core";

const WEEK = [18, 22, 21, 30, 27, 35, 33];

export default function SizeAndTone() {
  return (
    <Stack direction="row" gap={5} align="center" wrap>
      <Sparkline data={WEEK} />
      <Sparkline data={WEEK} width={160} height={40} />
      <Sparkline data={WEEK} width={160} height={40} tone="accent" />
    </Stack>
  );
}
```

##### Handle too little history

With fewer than two values there is no shape, so it draws nothing; say in words why the space is empty.

```tsx
import { Sparkline, Stack, Text } from "@umriss-ui/core";

const SERVICES = [
  { name: "Checkout", history: [212, 230, 498, 305, 221] },
  { name: "Payouts (new)", history: [140] },
];

export default function TooLittleHistory() {
  return (
    <Stack gap={2}>
      {SERVICES.map((service) => (
        <Stack key={service.name} direction="row" gap={3} align="center">
          <Text as="span" size="sm" style={{ width: 120 }}>
            {service.name}
          </Text>
          {service.history.length >= 2 ? (
            <Sparkline data={service.history} />
          ) : (
            <Text as="span" size="xs" tone="muted" style={{ width: 96 }}>
              no history yet
            </Text>
          )}
          <Text as="span" size="sm" mono>
            {service.history.at(-1)} ms
          </Text>
        </Stack>
      ))}
    </Stack>
  );
}
```

##### Show a history per row

In a table each row gets its line at row height, with the value and the objective in columns of their own.

```tsx
import { Sparkline, Text } from "@umriss-ui/core";

/* Data from the operations world, written out here so the example runs on its own. */
/** A small LCG - the same numbers on every computer. */
function random(seed: number): () => number {
  let s = seed >>> 0;
  return () => {
    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
    return s / 4294967296;
  };
}

const at = (day: number, hours: number, minutes = 0) => new Date(2026, 2, day, hours, minutes).getTime();
const MINUTE = 60_000;

/** Tuesday, 17 March 2026, 10:30 - the moment the screens are read at. */
const NOW = at(17, 10, 30);

interface Service {
  id: string;
  name: string;
  team: string;
  /** 1 is customer-facing and pages at night; 3 waits for the morning. */
  tier: 1 | 2 | 3;
  /** The latency objective: the 95th percentile stays below this, in ms. */
  latencySlo: number;
  /** The availability promised for a month, in per cent. */
  availabilityTarget: number;
}

const SERVICES: readonly Service[] = [
  { id: "checkout", name: "Checkout", team: "Payments", tier: 1, latencySlo: 300, availabilityTarget: 99.95 },
  { id: "billing", name: "Billing", team: "Payments", tier: 1, latencySlo: 400, availabilityTarget: 99.9 },
  { id: "sign-in", name: "Sign-in", team: "Identity", tier: 1, latencySlo: 200, availabilityTarget: 99.95 },
  { id: "search", name: "Search", team: "Discovery", tier: 1, latencySlo: 250, availabilityTarget: 99.9 },
  { id: "images", name: "Image service", team: "Discovery", tier: 2, latencySlo: 500, availabilityTarget: 99.5 },
  { id: "notifications", name: "Notifications", team: "Messaging", tier: 2, latencySlo: 800, availabilityTarget: 99.5 },
  { id: "webhooks", name: "Webhooks", team: "Integrations", tier: 2, latencySlo: 1000, availabilityTarget: 99.5 },
  { id: "reports", name: "Reporting", team: "Insights", tier: 3, latencySlo: 2000, availabilityTarget: 99 },
];

interface MetricPoint {
  t: number;
  /** Median and 95th percentile latency, in ms. */
  p50: number;
  p95: number;
  /** Failed requests, in per cent. */
  errorRate: number;
  /** Requests per minute. */
  requests: number;
}

/** Requests per minute at the busiest hour, by tier. */
const VOLUME = { 1: 900, 2: 400, 3: 120 } as const;

/** A service's latency and error rate every five minutes of today, from
    midnight up to now. Busy by day, quiet at night; Checkout's 95th percentile
    climbs well past its objective from 09:40 to 10:10, and its errors with it. */
function metrics(serviceId: string): MetricPoint[] {
  const index = SERVICES.findIndex((one) => one.id === serviceId);
  const service = SERVICES[index];
  if (service === undefined) throw new Error(`No service "${serviceId}".`);
  const r = random(1000 + index * 37);
  const points: MetricPoint[] = [];
  let drift = 0;
  for (let t = at(17, 0); t <= NOW; t += 5 * MINUTE) {
    const hour = (t - at(17, 0)) / (60 * MINUTE);
    const load = 0.35 + 0.65 * Math.max(0, Math.sin((Math.PI * (hour - 5)) / 16));
    drift = 0.8 * drift + (r() - 0.5) * 0.08;
    const base = service.latencySlo * (0.45 + 0.2 * load + drift);
    const surge = serviceId === "checkout" && t >= at(17, 9, 40) && t < at(17, 10, 10) ? 1.9 : 1;
    const p95 = Math.round(base * surge * (1 + r() * 0.08));
    points.push({
      t,
      p50: Math.round(p95 * (0.42 + r() * 0.06)),
      p95,
      errorRate: Math.round((0.05 + r() * 0.12 + (surge > 1 ? 2.4 + r() : 0)) * 100) / 100,
      requests: Math.round(VOLUME[service.tier] * load * (1 + (r() - 0.5) * 0.1)),
    });
  }
  return points;
}

const ROWS = SERVICES.map((service) => {
  const p95 = metrics(service.id)
    .slice(-24)
    .map((point) => point.p95);
  return { service, p95, now: p95.at(-1)! };
});

const CELL = { padding: "var(--u-space-1) var(--u-space-3)", borderBottom: "1px solid var(--u-edge-color)" };

export default function InATable() {
  return (
    <div style={{ overflowX: "auto" }}>
      <table style={{ borderCollapse: "collapse", maxWidth: 560, width: "100%" }}>
        <thead>
          <tr>
            {["Service", "p95, last 2 h", "Now", "Objective"].map((head, i) => (
              <th key={head} style={{ ...CELL, textAlign: i >= 2 ? "right" : "left", whiteSpace: "nowrap" }}>
                <Text as="span" size="xs" tone="muted">
                  {head}
                </Text>
              </th>
            ))}
          </tr>
        </thead>
        <tbody>
          {ROWS.map(({ service, p95, now }) => (
            <tr key={service.id}>
              <td style={CELL}>
                <Text as="span" size="sm">
                  {service.name}
                </Text>
              </td>
              <td style={CELL}>
                <Sparkline data={p95} />
              </td>
              <td style={{ ...CELL, textAlign: "right", whiteSpace: "nowrap" }}>
                <Text as="span" size="sm" mono>
                  {now} ms
                </Text>
              </td>
              <td style={{ ...CELL, textAlign: "right", whiteSpace: "nowrap" }}>
                <Text as="span" size="sm" mono tone="muted">
                  {service.latencySlo} ms
                </Text>
              </td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}
```

#### When to use something else

- A figure with its verdict and a history beneath → Stat
- Axes, values, limits or several series → `Line` from @umriss-ui/charts

#### API

##### `SparklineProps`

| Prop | Type | Default | Description |
|---|---|---|---|
| `data` *required* | `readonly number[]` | — | Values in chronological order; at least two.<br>Shown in: [Configurator](#/sparkline/configurator-sparkline), [Beside a value](#/sparkline/beside-a-value), [Size and tone](#/sparkline/size-and-tone) and 4 more |
| `width` | `number \| "fill"` | `96` | Width in pixels; the default is a row width, not a chart width. `"fill"` takes the width of its container, as a tile's history does; the line keeps its stroke and the end point stays round.<br>Shown in: [Configurator](#/sparkline/configurator-sparkline), [Size and tone](#/sparkline/size-and-tone), [One above the other (Splitter)](#/splitter/one-above-the-other) and 1 more |
| `height` | `number` | `28` | Height in pixels; the default is as high as a table row. With `width` `"fill"` a stylesheet may set the height instead: the drawing follows its box.<br>Shown in: [Configurator](#/sparkline/configurator-sparkline), [Size and tone](#/sparkline/size-and-tone), [One above the other (Splitter)](#/splitter/one-above-the-other) and 1 more |
| `tone` | `"ink" \| "accent"` | `"ink"` | The line is ink, not meaning: `accent` only where exactly one line among several is to be emphasised.<br>Shown in: [Configurator](#/sparkline/configurator-sparkline), [Size and tone](#/sparkline/size-and-tone) |
| `ref` | `Ref<HTMLSpanElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<span>`.

#### Known limits

- No axes, labels, tooltip or points to hover: the value stands beside it.

What umriss deliberately does not build, and why: [ADR-0032](https://romanhaendler.github.io/umriss-ui/what-umriss-ui-is-not/).

## API index

Every name the package exports, in one place.

### API index

Everything `@umriss-ui/core` exports, with its signature. A component's props stand on its own page.

Demo page: https://romanhaendler.github.io/umriss-ui/core/api/

#### Components

##### `Accordion`

[Accordion](#/accordion) – Long content in sections behind headers the user opens one or several at a time (also called collapsible sections or a disclosure). Reach for it where a reader needs a few of many sections, such as settings, a runbook or a report.

Used on [CommandPalette](#/commandpalette) and [Accordion](#/accordion).

##### `AccordionItem`

[Accordion](#/accordion) – One section of an `Accordion`: its header and the content it opens.

Used on [Accordion](#/accordion).

##### `Alert`

[Alert](#/alert) – A message that stays in the page until its matter is settled (also called a banner or callout). Reach for it when the reader must notice something here: a failed import, an approval waiting, a form that did not save.

Used on [Scenarios](#/), [Splitter](#/splitter), [Textarea](#/textarea), [Slider](#/slider), [FileInput](#/fileinput), [DateTimePicker](#/datetimepicker), [Alert](#/alert) and [Stepper](#/stepper).

##### `AngleGlyph`

The chevron that expands and collapses a branch. Drawn pointing right;
rotate it by 90 degrees for an open branch.

```ts
function AngleGlyph({ ref, size, ...rest }: GlyphProps): import("react").JSX.Element;
```

Used on [CommandPalette](#/commandpalette).

##### `Badge`

[Badge](#/badge) – A small word or number at the edge of something else: a status, a count (also called a label or chip). Reach for it to mark the state of a row, or how many items wait behind a button.

Used on [Scenarios](#/), [Theming](#/theming), [Stack and Grid](#/stack-and-grid), [Card](#/card), [Splitter](#/splitter), [Typography](#/typography), [Slider](#/slider), [Switch](#/switch), [MultiSelect](#/multiselect), [ProgressBar](#/progressbar), [Toast](#/toast), [Menu](#/menu), [Drawer](#/drawer), [Tabs](#/tabs), [Accordion](#/accordion) and [Badge](#/badge).

##### `Breadcrumb`

[Breadcrumb](#/breadcrumb) – Shows where the current page sits in a hierarchy and leads back up to any level above it (also called a trail or path). Where the trail runs out of room, its middle levels fold into a menu.

Used on [Scenarios](#/) and [Breadcrumb](#/breadcrumb).

##### `Button`

[Button](#/button) – Starts one action when pressed: save, send, deploy, delete. Its variant says how much weight the action carries beside its neighbours, and while the action runs it shows that it is busy and cannot be pressed twice.

Used on [Scenarios](#/), [Installation](#/installation), [UmrissProvider](#/umrissprovider), [Theming](#/theming), [Sizes](#/sizes), [Language](#/language), [Stack and Grid](#/stack-and-grid), [Divider](#/divider), [Card](#/card), [Splitter](#/splitter), [VisuallyHidden](#/visuallyhidden), [Button](#/button), [IconButton](#/iconbutton), [ButtonGroup](#/buttongroup), [Input](#/input), [FormField](#/formfield), [Textarea](#/textarea), [FileInput](#/fileinput), [Combobox](#/combobox), [Spinner](#/spinner), [ProgressBar](#/progressbar), [Skeleton](#/skeleton), [Alert](#/alert), [Toast](#/toast), [EmptyState](#/emptystate), [Tooltip](#/tooltip), [Popover](#/popover), [Menu](#/menu), [Modal](#/modal), [Drawer](#/drawer), [ConfirmDialog](#/confirmdialog), [CommandPalette](#/commandpalette), [Breadcrumb](#/breadcrumb), [Accordion](#/accordion), [Stepper](#/stepper), [TreeView](#/treeview), [Benchmark](#/benchmark), [Badge](#/badge) and [Tag](#/tag).

##### `ButtonGroup`

[ButtonGroup](#/buttongroup) – Joins buttons that act on the same thing into one control. Its companion SplitButton runs one main action and keeps the rarer variants in a menu beside it (also called a dropdown or menu button).

Used on [Sizes](#/sizes), [IconButton](#/iconbutton) and [ButtonGroup](#/buttongroup).

##### `CalendarGlyph`

A calendar leaf: a sheet with its header and two rings. With `range`, a
bar across the sheet stands for the span a range picker chooses.

```ts
function CalendarGlyph({ ref, size, range, ...rest }: GlyphProps & {
    range?: boolean;
}): import("react").JSX.Element;
```

##### `Card`

[Card](#/card) – A surface that holds one block of a screen together: a head with its title and actions, and a body (also called a panel or tile). Reach for it for each block of a dashboard or a detail view.

Used on [Scenarios](#/), [UmrissProvider](#/umrissprovider), [Theming](#/theming), [Sizes](#/sizes), [Stack and Grid](#/stack-and-grid), [Card](#/card), [Splitter](#/splitter), [Typography](#/typography), [Button](#/button), [NumberInput](#/numberinput), [Slider](#/slider), [Switch](#/switch), [SegmentedControl](#/segmentedcontrol), [FileInput](#/fileinput), [Combobox](#/combobox), [Spinner](#/spinner), [ProgressBar](#/progressbar), [EmptyState](#/emptystate), [CommandPalette](#/commandpalette), [Breadcrumb](#/breadcrumb), [Tabs](#/tabs), [Accordion](#/accordion), [Stepper](#/stepper) and [Stat](#/stat).

##### `CardBody`

[Card](#/card) – The content of a `Card`; the part that folds away in a collapsible card.
`flush` removes the padding for a table or a log.

Used on [Scenarios](#/), [UmrissProvider](#/umrissprovider), [Theming](#/theming), [Sizes](#/sizes), [Stack and Grid](#/stack-and-grid), [Card](#/card), [Typography](#/typography), [Button](#/button), [NumberInput](#/numberinput), [Slider](#/slider), [Switch](#/switch), [SegmentedControl](#/segmentedcontrol), [FileInput](#/fileinput), [Combobox](#/combobox), [Spinner](#/spinner), [ProgressBar](#/progressbar), [EmptyState](#/emptystate), [Breadcrumb](#/breadcrumb), [Tabs](#/tabs), [Accordion](#/accordion), [Stepper](#/stepper) and [Stat](#/stat).

##### `CardHeader`

[Card](#/card) – The head of a `Card`: title, an optional eyebrow and actions on the right.
In a collapsible card it carries the fold key.

Used on [Scenarios](#/), [UmrissProvider](#/umrissprovider), [Theming](#/theming), [Sizes](#/sizes), [Card](#/card), [Button](#/button), [NumberInput](#/numberinput), [Slider](#/slider), [Switch](#/switch), [FileInput](#/fileinput), [Combobox](#/combobox), [Spinner](#/spinner), [ProgressBar](#/progressbar), [EmptyState](#/emptystate), [Tabs](#/tabs), [Accordion](#/accordion), [Stepper](#/stepper) and [Stat](#/stat).

##### `Checkbox`

[Checkbox](#/checkbox) – A yes or no that counts when the form is saved (tick box). It also shows the mixed state of a parent whose children are partly checked.

Used on [Scenarios](#/), [Theming](#/theming), [Sizes](#/sizes), [ButtonGroup](#/buttongroup), [FormField](#/formfield), [Checkbox](#/checkbox), [Popover](#/popover), [Drawer](#/drawer) and [CommandPalette](#/commandpalette).

##### `ClockGlyph`

A clock face at a quarter past - the time pickers' character.

```ts
function ClockGlyph({ ref, size, ...rest }: GlyphProps): import("react").JSX.Element;
```

##### `Combobox`

[Combobox](#/combobox) – One choice from a long list, found by typing (autocomplete, typeahead, searchable select): a driver, a service, an account. The list filters along while the value stays exactly one.

Used on [Scenarios](#/), [Language](#/language), [Combobox](#/combobox), [Popover](#/popover) and [CommandPalette](#/commandpalette).

##### `CommandPalette`

[CommandPalette](#/commandpalette) – A search field above the page that finds commands and places as you type (also called a command menu or quick switcher). Reach for it when an application has more actions and pages than any menu can show.

Used on [CommandPalette](#/commandpalette).

##### `ConfirmDialog`

[ConfirmDialog](#/confirmdialog) – A small modal window with one question and two buttons, for the moment before something that cannot be undone (also called a confirmation). Reach for it before deleting, rejecting or closing for good.

Used on [Scenarios](#/), [Modal](#/modal) and [ConfirmDialog](#/confirmdialog).

##### `ContextMenu`

[ContextMenu](#/contextmenu) – A menu that opens at a point, for a right-click on something that is not a button: a row, a canvas, a bar in a schedule (also called a right-click menu). The entries and the keyboard are those of the menu.

Used on [ContextMenu](#/contextmenu).

##### `ControlSizeProvider`

[Sizes](#/sizes) – Sets the size of the controls inside it - every control with `size` takes
it unless it says its own. A popover, dialog or tooltip opened from inside
starts without it.

Used on [Sizes](#/sizes) and [SegmentedControl](#/segmentedcontrol).

##### `CrossGlyph`

The cross that clears a field, removes a tag or a chip, and closes a
dialog, a toast or an alert - one drawing at the size of its place.

```ts
function CrossGlyph({ ref, size, ...rest }: GlyphProps): import("react").JSX.Element;
```

Used on [IconButton](#/iconbutton).

##### `DatePicker`

[DatePicker](#/datepicker) – One day, picked in a calendar (date field): a delivery date, a due date. Weeks begin on Monday.

Used on [Scenarios](#/), [UmrissProvider](#/umrissprovider), [Sizes](#/sizes), [Language](#/language), [FormField](#/formfield) and [DatePicker](#/datepicker).

##### `DateRangePicker`

[DateRangePicker](#/daterangepicker) – A span of days, from one day to another (date range): leave, a sprint, a reporting period. Two months side by side, presets for the usual spans, and the days counted while the pointer moves.

Used on [Sizes](#/sizes) and [DateRangePicker](#/daterangepicker).

##### `DateTimePicker`

[DateTimePicker](#/datetimepicker) – One moment, day and time of day in one field (date-time field): when an incident began, when an alert fired.

Used on [Scenarios](#/) and [DateTimePicker](#/datetimepicker).

##### `DateTimeRangePicker`

[DateTimeRangePicker](#/datetimerangepicker) – A span with a time at each end (date-time range): a planned downtime, a release freeze, the minutes an objective was breached. The footer shows the duration while it is set.

Used on [Sizes](#/sizes) and [DateTimeRangePicker](#/datetimerangepicker).

##### `Divider`

[Divider](#/divider) – A line between two groups of content, across or upright, that may name the part after it (also called a separator or rule).

Used on [Stack and Grid](#/stack-and-grid), [Divider](#/divider), [Switch](#/switch), [ProgressBar](#/progressbar) and [CommandPalette](#/commandpalette).

##### `Drawer`

[Drawer](#/drawer) – A modal window that slides in from the left or right edge of the screen (also called a side sheet or side panel). Reach for it for the detail of something picked from a list, while the list stays in sight behind it.

Used on [Scenarios](#/), [Modal](#/modal), [Drawer](#/drawer) and [CommandPalette](#/commandpalette).

##### `EmptyState`

[EmptyState](#/emptystate) – What stands where a list or panel has nothing to show: what is missing, why, and the way forward (also called a blank slate). Reach for it for a first use, a filter that found nothing, or a queue that is clear.

Used on [Card](#/card), [EmptyState](#/emptystate), [Tabs](#/tabs) and [Tag](#/tag).

##### `FileInput`

[FileInput](#/fileinput) – Choose files from the system's dialog or drop them on the zone (file picker, upload field). The chosen files are listed with their size and can be removed one by one.

Used on [Sizes](#/sizes) and [FileInput](#/fileinput).

##### `FormField`

[FormField](#/formfield) – The frame around a field: its label, a hint below it and the error that replaces the hint. Wrap every field in one, so the question, the help and the problem are read out together.

Used on [Scenarios](#/), [UmrissProvider](#/umrissprovider), [Sizes](#/sizes), [Language](#/language), [Button](#/button), [Input](#/input), [FormField](#/formfield), [Textarea](#/textarea), [NumberInput](#/numberinput), [Slider](#/slider), [Checkbox](#/checkbox), [Switch](#/switch), [RadioGroup](#/radiogroup), [SegmentedControl](#/segmentedcontrol), [FileInput](#/fileinput), [Select](#/select), [Combobox](#/combobox), [MultiSelect](#/multiselect), [DatePicker](#/datepicker), [DateTimePicker](#/datetimepicker), [DateRangePicker](#/daterangepicker), [DateTimeRangePicker](#/datetimerangepicker), [Alert](#/alert), [Toast](#/toast), [Modal](#/modal), [Breadcrumb](#/breadcrumb), [Accordion](#/accordion) and [TreeView](#/treeview).

##### `FormFieldBoundary`

Resets the FormField context. For the innards of panels (search field,
option checkboxes) that are rendered through a portal inside a FormField:
without a boundary they inherit its field id - a click on an option label
then activates the field's trigger through htmlFor and closes the panel
again immediately.

```ts
function FormFieldBoundary({ children }: {
    children: ReactNode;
}): import("react").JSX.Element;
```

##### `Grid`

[Stack and Grid](#/stack-and-grid) – Children in a grid: a fixed number of columns, a list of column widths,
or as many columns as fit at `minItemWidth`.

Used on [Scenarios](#/), [Theming](#/theming), [Sizes](#/sizes), [Language](#/language), [Stack and Grid](#/stack-and-grid), [Card](#/card), [Splitter](#/splitter), [Typography](#/typography), [Input](#/input), [FormField](#/formfield), [Textarea](#/textarea), [NumberInput](#/numberinput), [Slider](#/slider), [Checkbox](#/checkbox), [Switch](#/switch), [RadioGroup](#/radiogroup), [FileInput](#/fileinput), [Select](#/select), [Combobox](#/combobox), [MultiSelect](#/multiselect), [DatePicker](#/datepicker), [DateTimePicker](#/datetimepicker), [DateRangePicker](#/daterangepicker), [DateTimeRangePicker](#/datetimerangepicker), [Modal](#/modal), [Drawer](#/drawer), [CommandPalette](#/commandpalette), [Breadcrumb](#/breadcrumb), [Tabs](#/tabs), [TreeView](#/treeview), [Stat](#/stat) and [Meter](#/meter).

##### `GridGlyph`

The grid laid over an area. Two by two lines; the frame is missing on
purpose, otherwise it would be a window.

```ts
function GridGlyph({ ref, size, ...rest }: GlyphProps): import("react").JSX.Element;
```

Used on [CommandPalette](#/commandpalette).

##### `GripGlyph`

The grip a drag is taken by: two grooves. Dots are fill, and point 4 of
the specification draws with the stroke.

```ts
function GripGlyph({ ref, size, ...rest }: GlyphProps): import("react").JSX.Element;
```

##### `Heading`

[Typography](#/typography) – A heading whose level and size are independent: a small heading can still
be the second level of the page.

Used on [Scenarios](#/), [Stack and Grid](#/stack-and-grid), [Typography](#/typography) and [Breadcrumb](#/breadcrumb).

##### `IconButton`

[IconButton](#/iconbutton) – A square button that shows only an icon (also called an icon-only button): refresh, export, close, the actions of a row. Reach for it where the icon is known well enough to stand alone; its name is required and shows as a tooltip.

Used on [Button](#/button), [IconButton](#/iconbutton) and [Menu](#/menu).

##### `Input`

[Input](#/input) – A single line of text (text field, text box): names, references, addresses, search terms. Reach for it whenever the answer is short free text; for numbers take a [NumberInput](#/numberinput).

Used on [Sizes](#/sizes), [Button](#/button), [Input](#/input), [FormField](#/formfield), [Alert](#/alert), [Toast](#/toast), [Modal](#/modal), [CommandPalette](#/commandpalette) and [Accordion](#/accordion).

##### `LanguageProvider`

Sets formatting and wording for the subtree below. Used by the root provider,
and usable directly for a section as well.

```ts
function LanguageProvider({ formats, wording, children }: LanguageProviderProps): import("react").JSX.Element;
```

Used on [Language](#/language).

##### `Link`

[Typography](#/typography) – A link in the size of its text; `external` opens it in a new tab with the
protective attributes set.

Used on [Scenarios](#/), [Theming](#/theming), [Typography](#/typography) and [Menu](#/menu).

##### `MeasureGlyph`

Measuring: a line with two end marks. Not a ruler with a scale: the teeth
would be a grey stripe at ten nominal units.

```ts
function MeasureGlyph({ ref, size, ...rest }: GlyphProps): import("react").JSX.Element;
```

##### `Menu`

[Menu](#/menu) – A list of actions that opens under a button (also called a dropdown menu). Reach for it when a place has more actions than room for buttons, or for the actions of each row in a list.

Used on [Scenarios](#/), [UmrissProvider](#/umrissprovider), [IconButton](#/iconbutton), [Popover](#/popover), [Menu](#/menu) and [CommandPalette](#/commandpalette).

##### `MenuItem`

[Menu](#/menu) – An entry of a `Menu` or a `ContextMenu`. It runs `onSelect` and closes the
menu.

Used on [Scenarios](#/), [UmrissProvider](#/umrissprovider), [IconButton](#/iconbutton), [ButtonGroup](#/buttongroup), [Menu](#/menu) and [ContextMenu](#/contextmenu).

##### `MenuSeparator`

Fine dividing line between groups of menu entries.

```ts
function MenuSeparator({ ref, className, ...rest }: HTMLAttributes<HTMLDivElement> & RefProp<HTMLDivElement>): import("react").JSX.Element;
```

Used on [Scenarios](#/), [IconButton](#/iconbutton), [ButtonGroup](#/buttongroup), [Menu](#/menu) and [ContextMenu](#/contextmenu).

##### `Meter`

[Meter](#/meter) – A bar that shows a measured share, such as capacity booked or budget used, coloured by your verdict on it (also called a gauge bar or level indicator). Reach for it in lists and tables where a percentage alone is hard to compare.

Used on [Scenarios](#/), [Drawer](#/drawer) and [Meter](#/meter).

##### `MinusGlyph`

The minus of `NumberInput`'s step buttons.

```ts
function MinusGlyph({ ref, size, ...rest }: GlyphProps): import("react").JSX.Element;
```

Used on [IconButton](#/iconbutton).

##### `Modal`

[Modal](#/modal) – A window above the page that holds the focus until it is answered or closed (also called a dialog). Reach for it for a short task that interrupts the page: create an item, edit its settings, read a policy.

Used on [Scenarios](#/), [Sizes](#/sizes), [Toast](#/toast), [Modal](#/modal), [Drawer](#/drawer) and [CommandPalette](#/commandpalette).

##### `ModalBody`

The content of a `Modal` or `Drawer` - the part that scrolls while head and
foot stand fast.

```ts
function ModalBody({ ref, className, children, ...rest }: HTMLAttributes<HTMLDivElement> & RefProp<HTMLDivElement>): import("react").JSX.Element;
```

Used on [Scenarios](#/), [Sizes](#/sizes), [Toast](#/toast), [Modal](#/modal) and [Drawer](#/drawer).

##### `ModalFooter`

The foot of a `Modal` or `Drawer`, for its buttons; they stand at the end.

```ts
function ModalFooter({ ref, className, children, ...rest }: HTMLAttributes<HTMLDivElement> & RefProp<HTMLDivElement>): import("react").JSX.Element;
```

Used on [Scenarios](#/), [Sizes](#/sizes), [Toast](#/toast), [Modal](#/modal) and [Drawer](#/drawer).

##### `ModalHeader`

[Modal](#/modal) – The head of a `Modal` or `Drawer`: its title, which names the dialog for a
screen reader, an optional sentence below it, and the close cross.

Used on [Scenarios](#/), [Sizes](#/sizes), [Toast](#/toast), [Modal](#/modal) and [Drawer](#/drawer).

##### `MultiSelect`

[MultiSelect](#/multiselect) – Several values from a list (multi-select, tag picker): a project team, services to filter by. The chosen ones stand as chips in the field, with a view in the panel that shows only them.

Used on [Scenarios](#/), [Sizes](#/sizes), [MultiSelect](#/multiselect), [Popover](#/popover) and [CommandPalette](#/commandpalette).

##### `NumberInput`

[NumberInput](#/numberinput) – A number typed exactly (numeric field, spin box): an amount, a weight, hours. It shows the unit inside the field, keeps the value in its range and steps with the arrow keys.

Used on [Scenarios](#/), [Sizes](#/sizes), [Language](#/language), [FormField](#/formfield), [NumberInput](#/numberinput), [Slider](#/slider), [Switch](#/switch), [Modal](#/modal), [CommandPalette](#/commandpalette) and [Accordion](#/accordion).

##### `PlusGlyph`

The plus of `NumberInput`'s step buttons.

```ts
function PlusGlyph({ ref, size, ...rest }: GlyphProps): import("react").JSX.Element;
```

Used on [IconButton](#/iconbutton).

##### `Popover`

[Popover](#/popover) – A surface that hangs from a trigger and closes on Escape, an outside click or scrolling (also called a popup, flyout or dropdown panel). Reach for it for a small panel of your own: a filter, a detail, a short form.

Used on [Popover](#/popover) and [CommandPalette](#/commandpalette).

##### `ProgressBar`

[ProgressBar](#/progressbar) – A bar that shows how far a job has come, or that it runs while nobody knows how far (also called a progress indicator). Reach for it for imports, uploads and anything else that counts towards an end.

Used on [Scenarios](#/), [ProgressBar](#/progressbar) and [Stepper](#/stepper).

##### `RadioGroup`

[RadioGroup](#/radiogroup) – One choice out of a few that all stay in view (radio buttons, option group). Each option may carry a sentence that explains it.

Used on [Scenarios](#/), [Sizes](#/sizes) and [RadioGroup](#/radiogroup).

##### `SegmentedControl`

[SegmentedControl](#/segmentedcontrol) – One choice out of a few short possibilities, drawn as one control with a segment for each (segmented button, button toggle): a sunken track, the choice lifted out of it. As tall as a select, so it stands in a row of fields too.

Used on [Sizes](#/sizes) and [SegmentedControl](#/segmentedcontrol).

##### `Select`

[Select](#/select) – One choice from a short, known list (dropdown). Under a mouse and the keys it opens the Combobox's list; under a finger the system's picker, a wheel on the phone.

Used on [Scenarios](#/), [Sizes](#/sizes), [FormField](#/formfield), [SegmentedControl](#/segmentedcontrol), [Select](#/select), [Toast](#/toast), [Popover](#/popover), [Modal](#/modal), [CommandPalette](#/commandpalette), [Accordion](#/accordion) and [Tag](#/tag).

##### `Skeleton`

[Skeleton](#/skeleton) – Grey shapes that stand where content is still loading and hold the height it will have (also called a placeholder or shimmer). Reach for it when you know the layout of what is coming, so nothing jumps when it arrives.

Used on [Skeleton](#/skeleton) and [Tabs](#/tabs).

##### `Slider`

[Slider](#/slider) – A value set roughly between two bounds (range slider): a share of traffic, an alert threshold, weekly hours. The position on the track says as much as the figure.

Used on [Scenarios](#/), [Sizes](#/sizes), [Slider](#/slider), [CommandPalette](#/commandpalette), [Breadcrumb](#/breadcrumb) and [Accordion](#/accordion).

##### `Sparkline`

[Sparkline](#/sparkline) – A small line of a history, at the height of a line of text, without axes or labels (also called a micro chart). Reach for it beside a value or in a table cell, where the shape of the last hours tells more than the figure alone.

Used on [Splitter](#/splitter) and [Sparkline](#/sparkline).

##### `Spinner`

[Spinner](#/spinner) – A turning circle that says something is running, without saying how far (also called a loading indicator). Reach for it for short waits whose length nobody knows, beside a word that says what runs.

Used on [Spinner](#/spinner).

##### `SplitButton`

[ButtonGroup](#/buttongroup) – A main action with a menu of its variants: the button on the left runs
`onClick`, the arrow on the right opens `menu`. The ref goes to the main
button.

Used on [ButtonGroup](#/buttongroup).

##### `Splitter`

[Splitter](#/splitter) – Two panes with a draggable line between them (also called a split view or resizable panes). Use it when the user needs both at once and decides how much of each: a list beside its detail, a chart above its alerts.

Used on [Splitter](#/splitter) and [CommandPalette](#/commandpalette).

##### `Stack`

[Stack and Grid](#/stack-and-grid) – Children below or beside one another, spaced by a step of the spacing
scale.

Used on [Scenarios](#/), [UmrissProvider](#/umrissprovider), [Theming](#/theming), [Sizes](#/sizes), [Language](#/language), [Stack and Grid](#/stack-and-grid), [Divider](#/divider), [Card](#/card), [Splitter](#/splitter), [Typography](#/typography), [VisuallyHidden](#/visuallyhidden), [Button](#/button), [IconButton](#/iconbutton), [ButtonGroup](#/buttongroup), [Input](#/input), [FormField](#/formfield), [Textarea](#/textarea), [NumberInput](#/numberinput), [Slider](#/slider), [Checkbox](#/checkbox), [Switch](#/switch), [SegmentedControl](#/segmentedcontrol), [FileInput](#/fileinput), [Select](#/select), [Combobox](#/combobox), [MultiSelect](#/multiselect), [DatePicker](#/datepicker), [DateTimePicker](#/datetimepicker), [DateRangePicker](#/daterangepicker), [DateTimeRangePicker](#/datetimerangepicker), [Spinner](#/spinner), [ProgressBar](#/progressbar), [Skeleton](#/skeleton), [Alert](#/alert), [Toast](#/toast), [EmptyState](#/emptystate), [Tooltip](#/tooltip), [Popover](#/popover), [Menu](#/menu), [ContextMenu](#/contextmenu), [Modal](#/modal), [Drawer](#/drawer), [ConfirmDialog](#/confirmdialog), [CommandPalette](#/commandpalette), [Breadcrumb](#/breadcrumb), [Tabs](#/tabs), [Accordion](#/accordion), [Stepper](#/stepper), [TreeView](#/treeview), [Badge](#/badge), [Tag](#/tag), [Stat](#/stat), [Meter](#/meter) and [Sparkline](#/sparkline).

##### `Stat`

[Stat](#/stat) – A single figure with its verdict: read against limits, with the history before it, the deviation from its target and how fresh it is (also called a KPI tile or metric card). Reach for it for the few numbers a screen is watched for.

Used on [Scenarios](#/), [Language](#/language), [Splitter](#/splitter), [Drawer](#/drawer) and [Stat](#/stat).

##### `Stepper`

[Stepper](#/stepper) – Shows how far a procedure has come: which steps are done, which one is being worked on, which lie ahead and which failed (also called a progress tracker). Reach for it for approvals, rollouts and closing routines.

Used on [Scenarios](#/), [FileInput](#/fileinput), [Tabs](#/tabs) and [Stepper](#/stepper).

##### `Switch`

[Switch](#/switch) – On or off, taking effect at once (toggle): paging at night, autoscaling, a feature for one service. A screen reader announces it as a switch, on or off.

Used on [Scenarios](#/), [Theming](#/theming), [Sizes](#/sizes), [Switch](#/switch), [Toast](#/toast), [Drawer](#/drawer), [CommandPalette](#/commandpalette) and [Accordion](#/accordion).

##### `Tab`

[Tabs](#/tabs) – One tab of a `TabList`; choosing it shows the `TabPanel` of the same
`value`.

Used on [Scenarios](#/), [Card](#/card), [Typography](#/typography), [VisuallyHidden](#/visuallyhidden), [Button](#/button), [IconButton](#/iconbutton), [ButtonGroup](#/buttongroup), [Input](#/input), [Textarea](#/textarea), [RadioGroup](#/radiogroup), [SegmentedControl](#/segmentedcontrol), [Select](#/select), [Alert](#/alert), [Toast](#/toast), [Tooltip](#/tooltip), [Menu](#/menu), [Modal](#/modal), [Drawer](#/drawer), [ConfirmDialog](#/confirmdialog), [Breadcrumb](#/breadcrumb), [Tabs](#/tabs), [Accordion](#/accordion) and [Tag](#/tag).

##### `TabList`

The row of `Tab`s inside `Tabs`. The arrow keys, Home and End move
between the tabs and choose them.

```ts
function TabList({ ref, className, children, onKeyDown, ...rest }: HTMLAttributes<HTMLDivElement> & RefProp<HTMLDivElement>): import("react").JSX.Element;
```

Used on [Scenarios](#/) and [Tabs](#/tabs).

##### `TabPanel`

[Tabs](#/tabs) – The content of one tab. Only the panel whose `value` is chosen stands in
the document.

Used on [Scenarios](#/) and [Tabs](#/tabs).

##### `Tabs`

[Tabs](#/tabs) – Several views of one thing in one place, exactly one of them visible (also called a tab bar). Reach for tabs when the views are alternatives the user switches between, not content to compare side by side.

Used on [Scenarios](#/), [CommandPalette](#/commandpalette) and [Tabs](#/tabs).

##### `Tag`

[Tag](#/tag) – A short label on content that the user can remove where you allow it (also called a chip). Reach for it for active filters, chosen values and assignments.

Used on [Scenarios](#/), [Stack and Grid](#/stack-and-grid), [EmptyState](#/emptystate) and [Tag](#/tag).

##### `TagGroup`

[Tag](#/tag) – A list of `Tag`s with one tab stop: the arrow keys move between them, and
the focus stays in the group when one is removed.

Used on [Scenarios](#/), [EmptyState](#/emptystate) and [Tag](#/tag).

##### `Text`

[Typography](#/typography) – Body text from the token set; `as` chooses the element, independent of the
size.

Used on [Scenarios](#/), [UmrissProvider](#/umrissprovider), [Theming](#/theming), [Sizes](#/sizes), [Language](#/language), [Stack and Grid](#/stack-and-grid), [Divider](#/divider), [Card](#/card), [Splitter](#/splitter), [Typography](#/typography), [VisuallyHidden](#/visuallyhidden), [Button](#/button), [IconButton](#/iconbutton), [ButtonGroup](#/buttongroup), [Input](#/input), [FormField](#/formfield), [Textarea](#/textarea), [NumberInput](#/numberinput), [Slider](#/slider), [Switch](#/switch), [SegmentedControl](#/segmentedcontrol), [FileInput](#/fileinput), [Select](#/select), [Combobox](#/combobox), [MultiSelect](#/multiselect), [DatePicker](#/datepicker), [DateTimePicker](#/datetimepicker), [DateRangePicker](#/daterangepicker), [DateTimeRangePicker](#/datetimerangepicker), [Spinner](#/spinner), [ProgressBar](#/progressbar), [Skeleton](#/skeleton), [Toast](#/toast), [EmptyState](#/emptystate), [Tooltip](#/tooltip), [Popover](#/popover), [Menu](#/menu), [ContextMenu](#/contextmenu), [Modal](#/modal), [Drawer](#/drawer), [ConfirmDialog](#/confirmdialog), [CommandPalette](#/commandpalette), [Breadcrumb](#/breadcrumb), [Tabs](#/tabs), [Accordion](#/accordion), [Stepper](#/stepper), [TreeView](#/treeview), [Benchmark](#/benchmark), [Badge](#/badge), [Tag](#/tag), [Stat](#/stat), [Meter](#/meter) and [Sparkline](#/sparkline).

##### `Textarea`

[Textarea](#/textarea) – Text over several lines (multi-line text field): a comment, a summary, a note to the driver. It can grow with its text and count the characters left.

Used on [Scenarios](#/), [Sizes](#/sizes), [Textarea](#/textarea) and [CommandPalette](#/commandpalette).

##### `ToastProvider`

Holds the toasts and draws them; [`useToast`](#/api/useToast) works only below it. Put it
once at the root of the application: a second one draws a second deck at
the same place, and the two lie on each other. Duration, position and limit
come from `UmrissProvider`'s `toast` where one stands around it.

```ts
function ToastProvider({ children, held }: ToastProviderProps): import("react").JSX.Element;
```

Used on [Scenarios](#/), [UmrissProvider](#/umrissprovider) and [Toast](#/toast).

##### `Tooltip`

[Tooltip](#/tooltip) – A sentence of explanation that appears while the pointer rests on an element or the keyboard focus is on it (also called a hint). Reach for it to explain an abbreviation or a control; an icon button names itself as an [IconButton](#/iconbutton).

Used on [Scenarios](#/), [IconButton](#/iconbutton), [Toast](#/toast), [Tooltip](#/tooltip), [Popover](#/popover) and [CommandPalette](#/commandpalette).

##### `TreeSearch`

[TreeView](#/treeview) – The search field of a tree: an `Input` that writes into the tree's search
text, so that the `TreeView` filters on it.

Used on [TreeView](#/treeview).

##### `TreeView`

[TreeView](#/treeview) – A hierarchy the user expands, walks with the keys and optionally ticks (also called a tree or outline). Reach for it for folders, teams and cost-centre structures; large trees stay quick because only the visible rows are drawn.

Used on [Scenarios](#/), [TreeView](#/treeview) and [Benchmark](#/benchmark).

##### `UmrissProvider`

[UmrissProvider](#/umrissprovider) – Sets once, at the root, what an application shares: the density of its tables, where overlays open, how long toasts stay and where they stand, and the language. It is optional; every component works the same without it.

Used on [UmrissProvider](#/umrissprovider) and [Toast](#/toast).

##### `VisuallyHidden`

[VisuallyHidden](#/visuallyhidden) – Text a screen reader announces but the eye does not see (also called screen-reader-only or sr-only). Reach for it when a visible label is clear from its surroundings but not on its own, and for a skip link.

Used on [VisuallyHidden](#/visuallyhidden).

#### Hooks

##### `useCommandPaletteShortcut`

Binds Cmd+K/Ctrl+K and "/" to the opening of a palette.

`onOpen` may be new on every render: the hook remembers the current version
rather than unsubscribing and resubscribing the listener each time.

```ts
function useCommandPaletteShortcut(onOpen: () => void): void;
```

Used on [CommandPalette](#/commandpalette).

##### `useDensity`

The configured density; without a provider, "comfortable".

```ts
const useDensity: () => Density;
```

##### `useDensityFor`

A component's `density`: its own value, else the density the provider
explicitly configured, else its own default.

"comfortable" means "regular" here. A compact set of tokens does not exist.

```ts
function useDensityFor(own: "regular" | "compact" | undefined, fallback: "regular" | "compact"): "regular" | "compact";
```

##### `useFormats`

Only the formatting.

```ts
const useFormats: () => Formats;
```

Used on [Language](#/language), [NumberInput](#/numberinput), [Slider](#/slider), [DatePicker](#/datepicker), [DateTimePicker](#/datetimepicker), [DateRangePicker](#/daterangepicker) and [DateTimeRangePicker](#/datetimerangepicker).

##### `useFormField`

Used by Input, Select and Checkbox to wire up id and aria automatically.

```ts
function useFormField(): FormFieldContextValue | null;
```

Used on [FormField](#/formfield).

##### `useFreshness`

Judges a value's as-of time continuously and causes a redraw when it changes
state.

The caller gives the ages; there is deliberately no default, because "stale"
on a live latency panel means something other than "stale" on a monthly
budget overview.

```ts
function useFreshness(asOf: Date | number | null | undefined, ages: FreshnessAges): FreshnessReading;
```

Used on [Stat](#/stat).

##### `useLanguage`

Formatting and wording together; without a provider, the defaults.

```ts
const useLanguage: () => Language;
```

##### `usePortalTarget`

Resolves the configured portal target.

`null` means expressly "no statement" and not "to the body": the callers have
rules of their own that take precedence - the popover seam portals into the
nearest `<dialog>` ancestor, because a portal at the body does not reach the
top layer. That rule beats the setting; otherwise a panel inside a modal
would be invisible.

```ts
function usePortalTarget(): () => HTMLElement | null;
```

##### `useToast`

Access to `toast()`, `update()` and `dismiss()`; requires a ToastProvider.

```ts
function useToast(): ToastContextValue;
```

Used on [Scenarios](#/), [UmrissProvider](#/umrissprovider) and [Toast](#/toast).

##### `useToastConfig`

The setting for toasts; without a provider, empty.

```ts
const useToastConfig: () => ToastConfig;
```

##### `useTree`

The state of a tree - which branches are open, which nodes are checked,
the active node, the anchor and the search text - and the gestures on it.
Each of these can be controlled from outside, so that a tree can be
restored from a link.

- `roots` – The top-level nodes, in your own type.
- `options` – How a node is read, and the initial or controlled state with its change handlers.
- Returns The tree to hand to `TreeView` and `TreeSearch`.

```ts
function useTree<K, S extends Key = string>(roots: readonly K[], options: TreeOptions<K, S>): Tree<K, S>;
```

Used on [Scenarios](#/), [TreeView](#/treeview) and [Benchmark](#/benchmark).

##### `useUmriss`

The whole configuration; without a provider, the defaults.

```ts
const useUmriss: () => UmrissConfig;
```

##### `useVirtual`

Holds the scroll position and the measured heights and derives the window
from them.

It is measured on the first rendered row rather than taken from the caller's
value: row height depends on density, font size and zoom, and a small error
adds up over many rows to a scrollbar that lies.

```ts
function useVirtual(count: number, options: VirtualOptions): VirtualRows;
```

Used on [Benchmark](#/benchmark).

##### `useWording`

Only the wording.

```ts
const useWording: () => Wording;
```

Used on [Language](#/language).

#### Functions

##### `age`

The age of an as-of time at the reference time, in milliseconds.

Never negative: an as-of time in the future is real - the clocks of source
and screen drift apart - and does not mean that a value is about to become
true, but that it is true right now. It counts as zero old.

`null` where there is no computable age: without an as-of time there is
none.

```ts
function age(asOf: Instant, now: Instant): number | null;
```

Used on [Scenarios](#/).

##### `allBranches`

Every loaded branch with content. Empty ones stay out because expanding
them showed nothing; unloaded ones stay out because one click would
otherwise trigger a thousand requests ([ADR-0005](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0005-what-cannot-be-checked.md)).

```ts
function allBranches<K, S extends Key = string>(roots: readonly K[], reader: NodeReader<K, S>): S[];
```

##### `announce`

The library's one voice: says `text` in a polite live region, for what
happened without a visible change in the place a reader is at - a copy made,
a count after a filter. Use it instead of a region of your own: there is one
region, so two announcements never speak over each other.

Says `text` once announcements have rested for `ANNOUNCE_REST`; a later call
within the rest replaces an earlier one.

`at` is the element that speaks. Inside a modal `<dialog>` everything else
is inert and a region there is silent, so the region is the dialog's own -
the portal target's rule, without the provider's setting: that decides where
a surface is laid out, and a region is laid out nowhere.

```ts
function announce(text: string, at?: Element | null): void;
```

Used on [VisuallyHidden](#/visuallyhidden) and [CommandPalette](#/commandpalette).

##### `assess`

What the value is, given the limit set. A pure function of the two.

A missing or non-finite value yields `unknown` - and nothing else: nobody
knows the deviation of a value nobody has.

Where several bounds are violated the most severe wins, and among equally
severe ones the one with the greatest excess. A warning must not hide an
alarm, even where the value lies further beyond the warning.

No hysteresis: that would need the previous state, and a function of a
single value has none.

```ts
function assess(value: number | null | undefined, set?: LimitSet): Assessment;
```

##### `cadence`

The cadence at which a display has to re-judge itself, in milliseconds -
derived from the ages, not from a fixed second. A tile that goes stale after
five minutes must not look sixty times a minute.

A tenth of the smaller age: the change then appears late by at most ten per
cent of that age. Clamped to at most once a second and at least once a
minute.

Where no age ever takes effect - infinite, not a number - or where both took
effect at once, the state no longer changes by itself; the slowest cadence
is then enough.

```ts
function cadence(ages: FreshnessAges): number;
```

##### `duplicateKey`

The first key that occurs twice, otherwise null. Two nodes with the same
key break the cascade and the active node silently - [`useTree`](#/api/useTree) reports
that during development.

```ts
function duplicateKey<K, S extends Key = string>(roots: readonly K[], reader: NodeReader<K, S>): S | null;
```

##### `freshness`

The freshness of a value: its as-of time, measured against a reference time,
placed against the two ages.

A missing as-of time yields `lost`, and that is decided rather than
computed: `stale` presupposes that we know the age. Where we do not know it,
nothing covers the value, and that is the same statement as a broken
connection. The check therefore stands before any arithmetic and not inside
it.

What the value means - good, critical, whatever - is not at issue here and
is not touched by this function.

```ts
function freshness(asOf: Instant, now: Instant, ages: FreshnessAges): Freshness;
```

Used on [Scenarios](#/) and [Stat](#/stat).

##### `mergeLanguage`

Builds a complete instance from the default and a partial value.

```ts
function mergeLanguage(options: LanguageOptions | undefined): Language;
```

##### `rangeDays`

The number of days in the range, both ends included. It is calculated on day
boundaries and rounded, so that the 23 and 25 hour days of the daylight
saving change do not shift the result.

```ts
const rangeDays: (from: Date, to: Date) => number;
```

Used on [DateRangePicker](#/daterangepicker).

##### `scrollForRow`

The scroll position at which a row is visible - or null where it already is.

This is the arithmetic the keyboard handling hangs on: without it the focus
moves into a row that is not rendered.

The sticky header counts against the upper edge: a row standing exactly at
`scrollTop` lies behind it.

```ts
function scrollForRow(index: number, { rowHeight, scrollTop, viewportHeight, headerHeight }: RowPlacement): number | null;
```

##### `separatorsOf`

The separators a set of formats writes, read off the formats themselves.

A field that formats a number must be able to read its own output back, and
an application may have replaced `number` with anything. So the
separators are measured: one number with one decimal place, digits struck
out, and what remains is the notation's own punctuation.

```ts
function separatorsOf(formats: Formats): Separators;
```

##### `treeModel`

The visible nodes in reading order.

While a search runs: a node survives if it matches itself or a descendant
matches - so a match always appears together with the path that leads to it.
A branch that stands there only because of its descendant is treated as if
it were open, **without the expanded state being written**: if the search
text falls away, the tree stands exactly as it did before. A branch that
matches itself brings its whole subtree along, but only visibly so if it is
actually expanded.

```ts
function treeModel<K, S extends Key = string>(roots: readonly K[], reader: NodeReader<K, S>, snapshot: TreeSnapshot<S>): readonly FlatteningEntry<K, S>[];
```

##### `verdictWeight`

How heavily a verdict weighs - for sorting and comparing, as when a matrix
brings the worst tile to the top. It stands here so that the order is not
reinvented at every call site.

```ts
function verdictWeight(verdict: Verdict): number;
```

##### `visibleWindow`

The window for the current scroll position.

`before + rendered + after` always adds up to the full height of all rows.
That is the promise the scrollbar hangs on: it must not jump while scrolling
because the rendered set changed.

```ts
function visibleWindow({ count, rowHeight, scrollTop, viewportHeight, overscan, }: WindowInput): RowWindow;
```

#### Constants

##### `DEFAULT_FORMATS`

The instance shipped by default: English notation on a 24-hour clock
([ADR-0024](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0024-the-formats-are-english-german-is-freight.md)). German is `GERMAN_FORMATS` in `@umriss-ui/core/wording/de`.

Every entry, with its value, stands in the table [Formats](#/language/format) on the Language page.

```ts
const DEFAULT_FORMATS: Formats;
```

##### `DEFAULT_LANGUAGE`

English formats and English wording - what every component uses without a
`LanguageProvider`.

```ts
const DEFAULT_LANGUAGE: Language;
```

##### `DEFAULT_PRESETS`

The same time spans with the preset labels.

```ts
const DEFAULT_PRESETS: RangePreset[];
```

##### `DEFAULT_SEPARATORS`

The separators of the default notation.

```ts
const DEFAULT_SEPARATORS: Separators;
```

##### `DEFAULT_WORDING`

The instance shipped by default. English; German is `GERMAN_WORDING` in
`@umriss-ui/core/wording/de` ([ADR-0019](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0019-two-wordings-ship-english-is-the-default.md)).

Every entry, with its value, stands in the table [Wording](#/language/wording) on the Language page.

```ts
const DEFAULT_WORDING: Wording;
```

#### Types

##### `AccordionItemProps`

Its table stands on [Accordion](#/accordion/type-AccordionItemProps).

##### `AccordionProps`

Its table stands on [Accordion](#/accordion/type-AccordionProps).

##### `AlertProps`

Its table stands on [Alert](#/alert/type-AlertProps).

##### `AlertTone`

How urgent an alert is; it also decides whether a screen reader is
interrupted.

```ts
type AlertTone = "neutral" | "accent" | "success" | "warning" | "danger";
```

##### `Align`

Where the panel lines up with its anchor along the side it stands on.

```ts
type Align = "start" | "end" | "center";
```

##### `Assessment`

The verdict and what led to it.

| Prop | Type | Default | Description |
|---|---|---|---|
| `verdict` *required* | [`Verdict`](#type-Verdict)<br>`"ok" \| "unknown" \| "warning" \| "alarm"` | — |  |
| `limit` | [`Limit`](#type-Limit) | — | The violated limit - the same object the caller passed in. Absent where none is violated. |
| `excess` | `number` | — | The amount beyond the bound, always positive. Absent where none is violated. |
| `deviation` | `number` | — | The signed distance from the target. Absent where none is set: no target means no deviation, not a deviation of zero. |

##### `BadgeProps`

Its table stands on [Badge](#/badge/type-BadgeProps).

##### `BadgeTone`

What a badge stands for - never the only statement, a word stands beside
it.

```ts
type BadgeTone = "neutral" | "accent" | "success" | "warning" | "danger";
```

Used on [Badge](#/badge).

##### `BreadcrumbEntry`

Its table stands on [Breadcrumb](#/breadcrumb/type-BreadcrumbEntry).

##### `BreadcrumbProps`

Its table stands on [Breadcrumb](#/breadcrumb/type-BreadcrumbProps).

##### `ButtonGroupProps`

Its table stands on [ButtonGroup](#/buttongroup/type-ButtonGroupProps).

##### `ButtonProps`

Its table stands on [Button](#/button/type-ButtonProps).

##### `ButtonSize`

A button's two heights - the controls' (`ControlSize`).

```ts
type ButtonSize = ControlSize;
```

Resolves to `"sm" | "md"`.

##### `ButtonVariant`

How loud a button is: `primary` for the one main action, `secondary` by
default, `ghost` quiet in the accent, `plain` quiet and neutral, `danger`
for a destructive action.

```ts
type ButtonVariant = "primary" | "secondary" | "ghost" | "plain" | "danger";
```

##### `CardBodyProps`

Its table stands on [Card](#/card/type-CardBodyProps).

##### `CardHeaderProps`

Its table stands on [Card](#/card/type-CardHeaderProps).

##### `CardProps`

Its table stands on [Card](#/card/type-CardProps).

##### `CheckboxProps`

Its table stands on [Checkbox](#/checkbox/type-CheckboxProps).

##### `ComboboxOption`

Its table stands on [Combobox](#/combobox/type-ComboboxOption).

Used on [Combobox](#/combobox).

##### `ComboboxProps`

Its table stands on [Combobox](#/combobox/type-ComboboxProps).

##### `CommandPaletteItem`

Its table stands on [CommandPalette](#/commandpalette/type-CommandPaletteItem).

Used on [CommandPalette](#/commandpalette).

##### `CommandPaletteProps`

Its table stands on [CommandPalette](#/commandpalette/type-CommandPaletteProps).

##### `ConfirmDialogProps`

Its table stands on [ConfirmDialog](#/confirmdialog/type-ConfirmDialogProps).

##### `ContextMenuProps`

Its table stands on [ContextMenu](#/contextmenu/type-ContextMenuProps).

##### `ControlSize`

The two heights of a control: `sm` for a toolbar and dense forms, `md`
otherwise.

```ts
type ControlSize = "sm" | "md";
```

Used on [Sizes](#/sizes) and [SegmentedControl](#/segmentedcontrol).

##### `ControlSizeProviderProps`

Its table stands on [Sizes](#/sizes/type-ControlSizeProviderProps).

##### `DatePickerProps`

Its table stands on [DatePicker](#/datepicker/type-DatePickerProps).

##### `DateRange`

A span between two dates, both ends included - the value of
`DateRangePicker` and `DateTimeRangePicker`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `from` *required* | `Date` | — | <br>Shown in: [Narrow places (Sizes)](#/sizes/narrow-places), [A span of days (DateRangePicker)](#/daterangepicker/a-span-of-days), [Presets (DateRangePicker)](#/daterangepicker/presets) and 6 more |
| `to` *required* | `Date` | — | <br>Shown in: [Narrow places (Sizes)](#/sizes/narrow-places), [A span of days (DateRangePicker)](#/daterangepicker/a-span-of-days), [Presets (DateRangePicker)](#/daterangepicker/presets) and 6 more |

Used on [Sizes](#/sizes), [DateRangePicker](#/daterangepicker) and [DateTimeRangePicker](#/datetimerangepicker).

##### `DateRangePickerProps`

Its table stands on [DateRangePicker](#/daterangepicker/type-DateRangePickerProps).

##### `DateTimePickerProps`

Its table stands on [DateTimePicker](#/datetimepicker/type-DateTimePickerProps).

##### `DateTimeRangePickerProps`

Its table stands on [DateTimeRangePicker](#/datetimerangepicker/type-DateTimeRangePickerProps).

##### `Density`

How densely the library builds. A component with a density of its own
takes it through `useDensityFor` as the default for its `density` - in

```ts
type Density = "comfortable" | "compact";
```

##### `Direction`

Where the active node moves: up and down the visible rows, in and out of a
branch, to the first or the last row.

```ts
type Direction = "up" | "down" | "in" | "out" | "start" | "end";
```

##### `DividerProps`

Its table stands on [Divider](#/divider/type-DividerProps).

##### `DrawerProps`

Its table stands on [Drawer](#/drawer/type-DrawerProps).

##### `EmptyStateProps`

Its table stands on [EmptyState](#/emptystate/type-EmptyStateProps).

##### `FileInputProps`

Its table stands on [FileInput](#/fileinput/type-FileInputProps).

##### `FlatteningEntry<K, S extends Key = string>`

One visible node of a tree, with everything a row needs to be drawn and
read out: level, branch or leaf, check state, search state and position
among its siblings.

| Prop | Type | Default | Description |
|---|---|---|---|
| `node` *required* | `K` | — | <br>Shown in: [A tree (TreeView)](#/treeview/a-tree), [Tick a selection (TreeView)](#/treeview/tick-a-selection), [Load branches on demand (TreeView)](#/treeview/load-branches-on-demand) and 5 more |
| `key` *required* | `S` | — |  |
| `level` *required* | `number` | — | Roots stand at 0. Drives the indentation and what is read out. |
| `label` *required* | `string` | — | The node's text; here, so that typeahead can be a pure function over the flattening and needs no reader. |
| `branch` *required* | `boolean` | — |  |
| `empty` *required* | `boolean` | — | Branch without content: expanding it showed nothing. An unloaded branch is not empty - it could have children. |
| `disabled` *required* | `boolean` | — | May not be checked ([ADR-0005](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0005-what-cannot-be-checked.md)). It stays navigable. |
| `unloaded` *required* | `boolean` | — | Could have children that are not present. For checking exactly the same as disabled: whatever has to reach its descendants may not act on it. |
| `expanded` *required* | `boolean` | — |  |
| `checked` *required* | `boolean` | — |  |
| `indeterminate` *required* | `boolean` | — | Derived: not checked itself, but at least one descendant is. |
| `active` *required* | `boolean` | — |  |
| `matches` *required* | `boolean` | — | Matched the search itself. Without a search text every entry matches, so that the surface needs no special case. |
| `pathOnly` *required* | `boolean` | — | Stands there only because a descendant matches - a signpost. The surface dims these and only these. A child under a matching branch is neither a match nor a signpost but context: it stays normal. |
| `position` *required* | `number` | — | 1-based, among the siblings that survive the filter. |
| `siblings` *required* | `number` | — |  |

##### `Formats`

Everything the library knows about formatting.

| Prop | Type | Default | Description |
|---|---|---|---|
| `date` *required* | `(d: Date) => string` | — | Date as displayed: 17/03/2026<br>Shown in: [A span of days (DateRangePicker)](#/daterangepicker/a-span-of-days) |
| `dateShort` *required* | `(d: Date) => string` | — | Short form without the year, in the range footer: 17/03 |
| `month` *required* | `(d: Date) => string` | — | The calendar's month header: March 2026 |
| `dateLong` *required* | `(d: Date) => string` | — | Accessible name of a calendar cell: Tuesday, 17 March 2026 |
| `time` *required* | `(d: Date, withSeconds: boolean) => string` | — | Time of day, optionally with seconds: 09:05 or 09:05:03 |
| `dateTime` *required* | `(d: Date, withSeconds: boolean) => string` | — | Date and time together: 17/03/2026, 09:05<br>Shown in: [Use the language in your own components (Language)](#/language/own-components), [Pick a day (DatePicker)](#/datepicker/pick-a-day), [Set an instant (DateTimePicker)](#/datetimepicker/set-an-instant) and 1 more |
| `offset` *required* | `(d: Date) => string` | — | Short form of the UTC offset: GMT+2<br>Shown in: [Set an instant (DateTimePicker)](#/datetimepicker/set-an-instant) |
| `number` *required* | `(n: number, decimals?: number) => string` | — | A number in the set's notation. Without a digit count the value stands to the tenth decimal place; with one it is padded and rounded to exactly that many places.<br>Shown in: [Write numbers in your own notation (Language)](#/language/own-notation), [Price an invoice line (NumberInput)](#/numberinput/price-an-invoice-line), [Split a budget (Slider)](#/slider/split-a-budget) |
| `count` *required* | `(n: number) => string` | — | A count. Kept apart from `number` because it makes a different promise: a count is whole, and Intl's own rounding (at most three decimal places) is right for it and wrong for a measurement.<br>Shown in: [Write numbers in your own notation (Language)](#/language/own-notation), [Use the language in your own components (Language)](#/language/own-components) |
| `percent` *required* | `(share: number) => string` | — | A share from 0 to 1 as whole per cent: 74 % |
| `compareText` *required* | `(a: string, b: string) => number` | — | The ordering of two texts by the set's collation. |
| `relative` *required* | `(ms: number) => string` | — | An elapsed duration as a phrase: "3 minutes ago". The amount comes in milliseconds, counted back from now. |

##### `FormFieldProps`

Its table stands on [FormField](#/formfield/type-FormFieldProps).

##### `Freshness`

How much a value can be relied on right now - independently of how it is judged.

```ts
type Freshness = "fresh" | "stale" | "lost";
```

Used on [Stat](#/stat).

##### `FreshnessAges`

The two ages at which a value changes its state, in milliseconds. Both
bounds belong to the older state: exactly five minutes old is already
`stale`.

`alt <= lost` is the sensible order. Stated the other way round, the
harder statement still wins - the middle state simply falls away.

| Prop | Type | Default | Description |
|---|---|---|---|
| `stale` *required* | `number` | — | From this age on the value counts as stale, but keeps its verdict.<br>Shown in: [Show how fresh a value is (Stat)](#/stat/freshness), [Watch the services that page at night (Stat)](#/stat/a-service-overview), [Watch a kiln line over a shift (Scenarios)](#/scenarios/watch-a-kiln-line) |
| `lost` *required* | `number` | — | From this age on the connection counts as disconnected.<br>Shown in: [Show how fresh a value is (Stat)](#/stat/freshness), [Watch the services that page at night (Stat)](#/stat/a-service-overview), [Watch a kiln line over a shift (Scenarios)](#/scenarios/watch-a-kiln-line) |

Used on [Scenarios](#/) and [Stat](#/stat).

##### `FreshnessReading`

What `useFreshness` returns: how fresh the value is, how old, and the time
the reading was taken at.

| Prop | Type | Default | Description |
|---|---|---|---|
| `freshness` *required* | [`Freshness`](#type-Freshness)<br>`"fresh" \| "stale" \| "lost"` | — | `fresh`, `stale` or `lost` - never a verdict.<br>Shown in: [Show how fresh a value is (Stat)](#/stat/freshness) |
| `age` *required* | `number \| null` | — | Age in milliseconds, never negative; `null` without an as-of time. For the wording. |
| `now` *required* | `number` | — | The reference time of this reading, in milliseconds since the epoch. |

##### `GlyphProps`

The props of a glyph: an SVG's attributes and its edge length.

| Prop | Type | Default | Description |
|---|---|---|---|
| `size` | `number` | `12` | Edge length in pixels. The default is the size the glyph is drawn at in the components. |
| `ref` | `Ref<SVGSVGElement>` | — | Receives the component's root element. From `RefProp`.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

Also takes every attribute of `<svg>` – without `children`, `viewBox`.

##### `GridColumnWidth`

The width of one column in `Grid`'s list: a number in pixels, or
`"fill"` for a share of what the other columns leave.

```ts
type GridColumnWidth = number | "fill";
```

##### `GridProps`

Its table stands on [Stack and Grid](#/stack-and-grid/type-GridProps).

##### `HeadingProps`

Its table stands on [Typography](#/typography/type-HeadingProps).

##### `IconButtonProps`

Its table stands on [IconButton](#/iconbutton/type-IconButtonProps).

##### `InputProps`

Its table stands on [Input](#/input/type-InputProps).

##### `Key`

A node's key, as `reader.key` returns it.

```ts
type Key = string | number;
```

##### `Language`

A complete language: the formats for numbers and dates, and the wording.

| Prop | Type | Default | Description |
|---|---|---|---|
| `formats` *required* | [`Formats`](#type-Formats) | — |  |
| `wording` *required* | [`Wording`](#type-Wording) | — |  |

Used on [Toast](#/toast).

##### `LanguageOptions`

Its table stands on [Language](#/language/type-LanguageOptions).

Used on [Language](#/language).

##### `LanguageProviderProps`

The props of `LanguageProvider`: the parts of the formats and the wording
that differ from the default.

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` *required* | `ReactNode` | — | <br>Shown in: [German (Language)](#/language/german), [English and German side by side (Language)](#/language/side-by-side), [Replace single entries (Language)](#/language/single-entries) and 2 more |
| `formats` | `Partial<`[`Formats`](#type-Formats)`>` | — | How numbers, dates and durations are written. Overridden entry by entry; what is left out keeps writing as `DEFAULT_FORMATS` does - in English notation, whatever the wording says ([ADR-0024](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0024-the-formats-are-english-german-is-freight.md)). From `LanguageOptions`.<br>Shown in: [Set up an application (UmrissProvider)](#/umrissprovider/everything-at-once), [German (Language)](#/language/german), [English and German side by side (Language)](#/language/side-by-side) and 2 more |
| `wording` | `Partial<Omit<`[`Wording`](#type-Wording)`, "presets">> & { presets?: Partial<`[`Wording`](#type-Wording)`["presets"]> }` | — | The presets are a register of their own and are likewise overridden entry by entry. From `LanguageOptions`.<br>Shown in: [Set up an application (UmrissProvider)](#/umrissprovider/everything-at-once), [German (Language)](#/language/german), [English and German side by side (Language)](#/language/side-by-side) and 2 more |

##### `Limit`

A bound: a value, a side, a severity.

No tolerance band as input. A band is derived - two limits of equal
severity on opposite sides enclose one - and as an input type it would
force a `null` on one edge in the one-sided case.

| Prop | Type | Default | Description |
|---|---|---|---|
| `value` *required* | `number` | — | <br>Shown in: [English and German side by side (Language)](#/language/side-by-side), [Replace single entries (Language)](#/language/single-entries), [Three panes (Splitter)](#/splitter/three-panes) and 12 more |
| `side` *required* | [`Side`](#type-Side)<br>`"upper" \| "lower"` | — | <br>Shown in: [English and German side by side (Language)](#/language/side-by-side), [Replace single entries (Language)](#/language/single-entries), [Three panes (Splitter)](#/splitter/three-panes) and 12 more |
| `severity` *required* | [`Severity`](#type-Severity)<br>`"warning" \| "alarm"` | — | <br>Shown in: [English and German side by side (Language)](#/language/side-by-side), [Replace single entries (Language)](#/language/single-entries), [Three panes (Splitter)](#/splitter/three-panes) and 12 more |

##### `LimitSet`

The set a value is read against.

The target stands beside the limits and is not one: it is missed, never
violated, and it is never the edge of a region.

| Prop | Type | Default | Description |
|---|---|---|---|
| `limits` | `readonly `[`Limit`](#type-Limit)`[]` | — | In any order; none, one or several.<br>Shown in: [English and German side by side (Language)](#/language/side-by-side), [Replace single entries (Language)](#/language/single-entries), [Three panes (Splitter)](#/splitter/three-panes) and 12 more |
| `target` | `number` | — | <br>Shown in: [English and German side by side (Language)](#/language/side-by-side), [Replace single entries (Language)](#/language/single-entries), [Measure against a target (Stat)](#/stat/a-target) and 3 more |

Used on [Scenarios](#/), [Language](#/language), [Drawer](#/drawer) and [Stat](#/stat).

##### `LinkProps`

Its table stands on [Typography](#/typography/type-LinkProps).

##### `MenuItemProps`

Its table stands on [Menu](#/menu/type-MenuItemProps).

##### `MenuProps`

Its table stands on [Menu](#/menu/type-MenuProps).

##### `MeterProps`

Its table stands on [Meter](#/meter/type-MeterProps).

##### `MeterTone`

The colour of a meter's bar - an assessment, never the only statement.

```ts
type MeterTone = "neutral" | "accent" | "success" | "warning" | "danger";
```

Used on [Meter](#/meter).

##### `ModalHeaderProps`

Its table stands on [Modal](#/modal/type-ModalHeaderProps).

##### `ModalProps`

Its table stands on [Modal](#/modal/type-ModalProps).

##### `ModalSize`

The width of a `Modal`.

```ts
type ModalSize = "sm" | "md" | "lg";
```

Used on [Modal](#/modal).

##### `MultiSelectOption`

Its table stands on [MultiSelect](#/multiselect/type-MultiSelectOption).

Used on [MultiSelect](#/multiselect).

##### `MultiSelectProps`

Its table stands on [MultiSelect](#/multiselect/type-MultiSelectProps).

##### `NodeReader<K, S extends Key = string>`

How a node is read - handed over once, not per node. The node's own type
thereby stays entirely the caller's.

| Prop | Type | Default | Description |
|---|---|---|---|
| `key` *required* | `(node: K) => S` | — | <br>Shown in: [A tree (TreeView)](#/treeview/a-tree), [Tick a selection (TreeView)](#/treeview/tick-a-selection), [Load branches on demand (TreeView)](#/treeview/load-branches-on-demand) and 5 more |
| `children` *required* | `(node: K) => readonly K[] \| undefined` | — | `undefined` means leaf, an empty list means empty branch - the difference is visible and intended.<br>Shown in: [A tree (TreeView)](#/treeview/a-tree), [Tick a selection (TreeView)](#/treeview/tick-a-selection), [Load branches on demand (TreeView)](#/treeview/load-branches-on-demand) and 5 more |
| `label` *required* | `(node: K) => string` | — | Text the search checks against.<br>Shown in: [A tree (TreeView)](#/treeview/a-tree), [Tick a selection (TreeView)](#/treeview/tick-a-selection), [Load branches on demand (TreeView)](#/treeview/load-branches-on-demand) and 5 more |
| `disabled` | `(node: K) => boolean` | — | May this node be checked? Without an answer: everyone may. Disabled is a statement about the checkbox, not about the node - it stays navigable ([ADR-0005](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0005-what-cannot-be-checked.md)).<br>Shown in: [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal) |
| `unloaded` | `(node: K) => boolean` | — | Can this branch have children that are not present? Without an answer: no.<br>Shown in: [Load branches on demand (TreeView)](#/treeview/load-branches-on-demand), [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal) |
| `matches` | `(node: K) => boolean` | — | Does this node match? Given, it filters instead of the search text, which is then not read - a table matches by its columns and filters, not by one label. The path rule stays the same. |

Used on [Scenarios](#/), [TreeView](#/treeview) and [Benchmark](#/benchmark).

##### `NumberInputProps`

Its table stands on [NumberInput](#/numberinput/type-NumberInputProps).

##### `PopoverProps`

Its table stands on [Popover](#/popover/type-PopoverProps).

##### `PortalTarget`

Where overlays portal to.

A function is evaluated on every opening - a target that only comes into the
tree later cannot be given otherwise. `null`, or a result of `null`, means
"as before".

```ts
type PortalTarget = HTMLElement | (() => HTMLElement | null) | null;
```

Used on [UmrissProvider](#/umrissprovider).

##### `ProgressBarProps`

Its table stands on [ProgressBar](#/progressbar/type-ProgressBarProps).

##### `RadioGroupProps`

Its table stands on [RadioGroup](#/radiogroup/type-RadioGroupProps).

##### `RadioOption`

Its table stands on [RadioGroup](#/radiogroup/type-RadioOption).

##### `RangePreset`

A shortcut in a range picker's panel: its label, and a function that
computes the range when it is chosen - so that "Last 7 days" is counted from
the moment of the click.

| Prop | Type | Default | Description |
|---|---|---|---|
| `label` *required* | `string` | — | <br>Shown in: [Presets (DateRangePicker)](#/daterangepicker/presets) |
| `range` *required* | `() => `[`DateRange`](#type-DateRange) | — | <br>Shown in: [Presets (DateRangePicker)](#/daterangepicker/presets) |

##### `RefProp<E extends Element>`

The `ref` of a component: the element it renders at its root.

| Prop | Type | Default | Description |
|---|---|---|---|
| `ref` | `Ref<E>` | — | Receives the component's root element.<br>Shown in: [A row that holds still (Sizes)](#/sizes/a-row-that-holds-still), [An anchored surface (Popover)](#/popover/anchored-surface), [Take the width of the trigger (Popover)](#/popover/width-from-anchor) and 2 more |

##### `RowPlacement`

What `scrollForRow` needs to know about a scroll area.

| Prop | Type | Default | Description |
|---|---|---|---|
| `rowHeight` *required* | `number` | — |  |
| `scrollTop` *required* | `number` | — |  |
| `viewportHeight` *required* | `number` | — |  |
| `headerHeight` | `number` | — | Height of the sticky header; it covers the upper edge. |

##### `RowWindow`

The rows to render - `from` up to, not including, `to` - and the heights
of the filler rows that stand for the rest.

| Prop | Type | Default | Description |
|---|---|---|---|
| `from` *required* | `number` | — | First rendered index. |
| `to` *required* | `number` | — | First index no longer rendered (exclusive). |
| `before` *required* | `number` | — | Height of the filler row above, in pixels. |
| `after` *required* | `number` | — | Height of the filler row below, in pixels. |

##### `SegmentedControlProps`

Its table stands on [SegmentedControl](#/segmentedcontrol/type-SegmentedControlProps).

##### `SegmentedOption`

Its table stands on [SegmentedControl](#/segmentedcontrol/type-SegmentedOption).

##### `SelectProps`

Its table stands on [Select](#/select/type-SelectProps).

##### `Separators`

The two characters a notation separates with.

| Prop | Type | Default | Description |
|---|---|---|---|
| `group` *required* | `string` | — | Between thousands: "," in English, "." in German, empty where a notation does not group. |
| `decimal` *required* | `string` | — | Before the decimals: "." in English, "," in German. |

##### `Severity`

How seriously a violation weighs: one severity that advises and one that
calls for action. Exactly two; for a third distinction one sets a
second limit.

```ts
type Severity = "warning" | "alarm";
```

##### `Side`

Whether a limit is an upper or a lower bound.

```ts
type Side = "upper" | "lower";
```

##### `SkeletonProps`

Its table stands on [Skeleton](#/skeleton/type-SkeletonProps).

##### `SliderMark`

A mark on the track: a value, or a value with the word beneath it.

```ts
type SliderMark = number | { value: number; label?: ReactNode };
```

##### `SliderProps`

Its table stands on [Slider](#/slider/type-SliderProps).

##### `SpaceStep`

A step of the spacing scale, from 1 (4 px) to 8 (40 px) - the tokens
`--u-space-1` to `--u-space-8`.

```ts
type SpaceStep = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
```

##### `SparklineProps`

Its table stands on [Sparkline](#/sparkline/type-SparklineProps).

##### `SpinnerProps`

Its table stands on [Spinner](#/spinner/type-SpinnerProps).

##### `SplitButtonProps`

Its table stands on [ButtonGroup](#/buttongroup/type-SplitButtonProps).

##### `SplitterProps`

Its table stands on [Splitter](#/splitter/type-SplitterProps).

##### `StackProps`

Its table stands on [Stack and Grid](#/stack-and-grid/type-StackProps).

##### `StatProps`

Its table stands on [Stat](#/stat/type-StatProps).

##### `StepperProps`

Its table stands on [Stepper](#/stepper/type-StepperProps).

##### `StepperStep`

Its table stands on [Stepper](#/stepper/type-StepperStep).

##### `SwitchProps`

Its table stands on [Switch](#/switch/type-SwitchProps).

##### `TabPanelProps`

Its table stands on [Tabs](#/tabs/type-TabPanelProps).

##### `TabProps`

Its table stands on [Tabs](#/tabs/type-TabProps).

##### `TabsProps`

Its table stands on [Tabs](#/tabs/type-TabsProps).

##### `TagGroupProps`

Its table stands on [Tag](#/tag/type-TagGroupProps).

##### `TagProps`

Its table stands on [Tag](#/tag/type-TagProps).

##### `TagTone`

What a tag stands for - never the only statement, its text says it too.

```ts
type TagTone = "neutral" | "accent" | "success" | "warning" | "danger";
```

##### `TextareaProps`

Its table stands on [Textarea](#/textarea/type-TextareaProps).

##### `TextLeading`

The line height of the token set.

```ts
type TextLeading = "normal" | "tight";
```

##### `TextProps`

Its table stands on [Typography](#/typography/type-TextProps).

##### `TextSize`

A type size of the token set.

```ts
type TextSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
```

##### `TextTone`

How loud a text is; `secondary` and `muted` step back without falling below
the contrast threshold.

```ts
type TextTone = "default" | "secondary" | "muted";
```

##### `TextTracking`

The letter spacing of the token set.

```ts
type TextTracking = "normal" | "tight" | "display" | "caps";
```

##### `TextWeight`

A font weight of the token set.

```ts
type TextWeight = "regular" | "medium" | "semibold";
```

##### `ToastAction`

Its table stands on [Toast](#/toast/type-ToastAction).

##### `ToastCloseReason`

Why a toast went: its time ran out, it was closed (or gave way to a newer
one), or its action was taken.

```ts
type ToastCloseReason = "timeout" | "dismiss" | "action";
```

Used on [Toast](#/toast).

##### `ToastConfig`

Its table stands on [UmrissProvider](#/umrissprovider/type-ToastConfig).

Used on [UmrissProvider](#/umrissprovider) and [Toast](#/toast).

##### `ToastOptions`

Its table stands on [Toast](#/toast/type-ToastOptions).

##### `ToastPosition`

Where the toasts stand: an edge of the window and a place along it. On a
phone they take the width of the window, and only the edge counts.

```ts
type ToastPosition = "top-start" | "top-center" | "top-end" | "bottom-start" | "bottom-center" | "bottom-end";
```

Used on [Toast](#/toast).

##### `ToastProviderProps`

The props of `ToastProvider`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `children` *required* | `ReactNode` | — | <br>Shown in: [Resolve an incident (Scenarios)](#/scenarios/resolve-an-incident), [Approve spending against a budget (Scenarios)](#/scenarios/approve-spending), [Set up a team (Scenarios)](#/scenarios/set-up-a-team) |
| `held` | `boolean` | `false` | While true, the toasts are held back: none is seen or heard, no time runs out, and a new one waits. When false again they come back with the time they had left. For a surface the toasts must not cover for a while, where there is no room beside it: nothing is lost, as it would be by dismissing.<br>Shown in: [Hold the toasts (Toast)](#/toast/hold-the-toasts) |

##### `ToastTone`

How the message turns out; `loading` is a toast still at work.

```ts
type ToastTone = "neutral" | "success" | "warning" | "danger" | "loading";
```

##### `TooltipProps`

Its table stands on [Tooltip](#/tooltip/type-TooltipProps).

##### `Tree<K, S extends Key = string>`

What `useTree` returns: the visible nodes and the gestures on them. Hand it
to `TreeView` and `TreeSearch`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `flattening` *required* | `readonly `[`FlatteningEntry`](#type-FlatteningEntry)`<K, S>[]` | — | The visible nodes – complete, even where only a window of them is rendered. Positions and sibling counts come from here and never from what stands in the document ([ADR-0004](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0004-a-flat-accessibility-tree.md)). |
| `active` *required* | `S \| null` | — | <br>Shown in: [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal) |
| `search` *required* | `string` | — |  |
| `toggleExpanded` *required* | `(key: S) => void` | — |  |
| `toggleCheck` *required* | `(key: S) => void` | — |  |
| `activate` *required* | `(key: S) => void` | — |  |
| `move` *required* | `(direction: `[`Direction`](#type-Direction)`) => void` | — |  |
| `setSearch` *required* | `(text: string) => void` | — |  |
| `revealNode` *required* | `(key: S) => S \| null` | — | Expands the ancestors, brings the row into view and sets the active node. Returns the key, or null if it does not exist in the data.<br>Shown in: [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal) |
| `revealPath` *required* | `(path: readonly S[]) => S \| null` | — | Like revealNode, but with a path the caller knows and the data does not yet - from a deep link, say. Returns the deepest key reached; if the run gets stuck at an unloaded branch, that is its key, and it has been expanded in the process. Loading and calling again is the caller's business. |
| `expandAll` *required* | `() => void` | — | <br>Shown in: [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal) |
| `collapseAll` *required* | `() => void` | — | <br>Shown in: [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal) |
| `typeahead` *required* | `(prefix: string) => void` | — | Moves the active node to the next one whose label starts like this. Changes nothing else – not the expanding, not the checks, not the search. |
| `checkTo` *required* | `(to: S) => void` | — | Checks the range from the anchor up to this node. |
| `moveAndCheck` *required* | `(direction: `[`Direction`](#type-Direction)`) => void` | — | Moves the active node **and** toggles the new one – one gesture, one report. Separate from move(), so that plain movement checks nothing; to be called instead of move(), not in addition to it. |
| `toggleAll` *required* | `() => void` | — | Checks everything checkable – or empties, if everything is on already. |
| `revealCount` *required* | `number` | — | Counts up every explicit request "show me this node". Otherwise the presentation follows the focus to the active node only where it already lies inside the tree - otherwise a state change from outside would tear the focus away. An explicit request, however, is exactly the opposite of an incidental change, and for that it needs a sign. |
| `virtual` | [`VirtualRows`](#type-VirtualRows) | — | Set where virtualisation runs; goes to `<TreeView virtual={…}>`. |

##### `TreeOptions<K, S extends Key = string>`

The options of `useTree`: how a node is read, and each of its values
either uncontrolled (`default…`) or controlled with its `on…` handler.

| Prop | Type | Default | Description |
|---|---|---|---|
| `reader` *required* | [`NodeReader`](#type-NodeReader)`<K, S>` | — | <br>Shown in: [A tree (TreeView)](#/treeview/a-tree), [Tick a selection (TreeView)](#/treeview/tick-a-selection), [Load branches on demand (TreeView)](#/treeview/load-branches-on-demand) and 5 more |
| `defaultExpanded` | `Iterable<S>` | — | Initial values, where the tree holds its own state.<br>Shown in: [A tree (TreeView)](#/treeview/a-tree), [Tick a selection (TreeView)](#/treeview/tick-a-selection), [With an error (TreeView)](#/treeview/with-an-error) and 3 more |
| `expanded` | `ReadonlySet<S>` | — | Controlled from outside; where set, it wins over the tree's own state. |
| `defaultChecked` | `Iterable<S>` | — |  |
| `checked` | `ReadonlySet<S>` | — | <br>Shown in: [Tick a selection (TreeView)](#/treeview/tick-a-selection), [With an error (TreeView)](#/treeview/with-an-error), [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal) |
| `defaultActive` | `S \| null` | — | <br>Shown in: [A tree (TreeView)](#/treeview/a-tree), [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal), [Measure a large tree (Benchmark)](#/benchmark/benchmark) |
| `active` | `S \| null` | — | <br>Shown in: [Dispatch a tour (Scenarios)](#/scenarios/dispatch-a-tour) |
| `anchor` | `S \| null` | — | Where a range gesture spans from. Steerable from outside like the other four values, so that a range is repeatable. |
| `search` | `string` | — | <br>Shown in: [Search with the path (TreeView)](#/treeview/search-with-the-path), [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal) |
| `virtual` | [`VirtualOptions`](#type-VirtualOptions) | — | Render only what stands in the scroll area. Optional: without it every row is rendered and no row height is needed.<br>Shown in: [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal), [Measure a large tree (Benchmark)](#/benchmark/benchmark) |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onExpanded` | `(next: ReadonlySet<S>) => void` | — |  |
| `onChecked` | `(next: ReadonlySet<S>) => void` | — | <br>Shown in: [Tick a selection (TreeView)](#/treeview/tick-a-selection), [With an error (TreeView)](#/treeview/with-an-error), [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal) |
| `onActive` | `(next: S \| null) => void` | — | <br>Shown in: [Dispatch a tour (Scenarios)](#/scenarios/dispatch-a-tour) |
| `onAnchor` | `(next: S \| null) => void` | — |  |
| `onSearch` | `(text: string) => void` | — | <br>Shown in: [Search with the path (TreeView)](#/treeview/search-with-the-path), [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal) |
| `onActivate` | `(node: K) => void` | — | Enter on a node, or a click on its label. |
| `onLoadChildren` | `(node: K) => void` | — | An unloaded branch has been expanded: now would be the moment to fetch its children. The tree fetches nothing – it is driven by nested data, and whoever adds to them sees it render anew. Concurrency, errors and cancellation thereby stay outside ([ADR-0005](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0005-what-cannot-be-checked.md)).<br>Shown in: [Load branches on demand (TreeView)](#/treeview/load-branches-on-demand), [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal) |

##### `TreeSearchProps`

Its table stands on [TreeView](#/treeview/type-TreeSearchProps).

##### `TreeSnapshot<S extends Key = string>`

The whole state of a tree, as plain values: the open branches, the checked
nodes, the active node, the anchor and the search text. The transitions take
one and return the next.

| Prop | Type | Default | Description |
|---|---|---|---|
| `expanded` *required* | `ReadonlySet<S>` | — |  |
| `checked` *required* | `ReadonlySet<S>` | — |  |
| `active` *required* | `S \| null` | — |  |
| `anchor` *required* | `S \| null` | — | Where a range selection spans from: the node checked last on its own. Neither the active one nor part of the checked set - it stands in the snapshot so that a range is repeatable and steerable from outside. |
| `search` *required* | `string` | — |  |

##### `TreeViewProps`

Its table stands on [TreeView](#/treeview/type-TreeViewProps).

##### `UmrissConfig`

The settings of `UmrissProvider` as the components read them, every value
filled in.

| Prop | Type | Default | Description |
|---|---|---|---|
| `density` *required* | [`Density`](#type-Density)<br>`"comfortable" \| "compact"` | — |  |
| `portalTarget` *required* | [`PortalTarget`](#type-PortalTarget) | — |  |
| `toast` *required* | [`ToastConfig`](#/umrissprovider/type-ToastConfig) | — |  |

##### `UmrissProviderProps`

Its table stands on [UmrissProvider](#/umrissprovider/type-UmrissProviderProps).

Used on [UmrissProvider](#/umrissprovider).

##### `Verdict`

What a value is. Four outcomes, ordered by severity, `unknown` between
`ok` and `warning`: a value nobody has is a reason to look.

The fourth outcome is not a `null`, which would invite `?? "ok"` at the
call site: a dead data source would look like a healthy service.

```ts
type Verdict = "ok" | "unknown" | "warning" | "alarm";
```

##### `VirtualOptions`

The options of `useVirtual`.

| Prop | Type | Default | Description |
|---|---|---|---|
| `rowHeight` *required* | `number` | — | Expected row height in pixels. It is re-measured on a real row after the first render; the value given is the starting point, so that the first window is not empty.<br>Shown in: [Search, check and reveal in a large tree (TreeView)](#/treeview/search-check-and-reveal), [Measure a large tree (Benchmark)](#/benchmark/benchmark) |
| `overscan` | `number` | `4` | Rows above and below the visible area. |

##### `VirtualRows`

What `useVirtual` returns: the ref for the scroll area, the window of rows
to render and the heights of the filler rows around it.

| Prop | Type | Default | Description |
|---|---|---|---|
| `scrollRef` *required* | `RefObject<HTMLDivElement \| null>` | — | Goes on the scroll area - in |
| `from` *required* | `number` | — | Index of the first rendered row within the filtered set. |
| `to` *required* | `number` | — |  |
| `fillerBefore` *required* | `number` | — | Height of the upper filler row, in pixels. |
| `fillerAfter` *required* | `number` | — | Height of the lower filler row, in pixels. |
| `count` *required* | `number` | — | Rows in total - the filler rows carry the rest. |
| `showRow` *required* | `(index: number) => void` | — | Brings a row into view; for the keyboard. |

###### Events

| Prop | Type | Default | Description |
|---|---|---|---|
| `onScroll` *required* | `() => void` | — | Reports a new scroll position to the container. Internal. |

##### `VisuallyHiddenProps`

Its table stands on [VisuallyHidden](#/visuallyhidden/type-VisuallyHiddenProps).

##### `WindowInput`

What `visibleWindow` needs to know about a scroll area and its rows.

| Prop | Type | Default | Description |
|---|---|---|---|
| `count` *required* | `number` | — | Rows in total, not only the rendered ones. |
| `rowHeight` *required* | `number` | — | Measured height of one row, in pixels. |
| `scrollTop` *required* | `number` | — | The container's current scroll position. |
| `viewportHeight` *required* | `number` | — | Visible height of the scroll area. |
| `overscan` | `number` | `4` | Rows rendered along above and below the visible area. Without an overscan a blank area appears briefly during fast scrolling, because rendering trails the scrolling by a frame. |

##### `Wording`

Everything the library puts out as text.

| Prop | Type | Default | Description |
|---|---|---|---|
| `clearInput` *required* | `string` | — | The cross in the text field. |
| `clearSelection` *required* | `string` | — | The cross in the select and in the combobox. |
| `decreaseValue` *required* | `string` | — | Stepper buttons of the number field. |
| `increaseValue` *required* | `string` | — |  |
| `comboboxPlaceholder` *required* | `string` | — |  |
| `noMatches` *required* | `string` | — | Empty state of both lists. |
| `multiSelectPlaceholder` *required* | `string` | — |  |
| `multiSelectSearchPlaceholder` *required* | `string` | — |  |
| `searchOptions` *required* | `string` | — |  |
| `options` *required* | `string` | — | Group name of the option list. |
| `optionScope` *required* | `string` | — | Group name of the scope switch. |
| `optionScopeAll` *required* | `string` | — |  |
| `optionScopeSelected` *required* | `(count: number) => string` | — | The second scope, with the count in the text. |
| `selectAll` *required* | `string` | — |  |
| `selectNone` *required* | `string` | — |  |
| `invertSelection` *required* | `string` | — |  |
| `nothingSelected` *required* | `string` | — |  |
| `removeSelectedValue` *required* | `(beschriftung: string) => string` | — | The cross on a selected value in the trigger. |
| `manageMoreSelected` *required* | `(count: number) => string` | — | The "+N" counter in the trigger. |
| `multiSelectSummary` *required* | `(gewaehlt: number, total: number) => string` | — | The summary in the panel: "3 / 12". The sentence structure belongs to the language, even where it is only a slash here. |
| `optionCount` *required* | `(count: number) => string` | — | How many options stand, when a list opens or its filter changes; never zero - an empty list says its own empty text. Named, like the three below, after the moment it is spoken in: an announcement labels no element. |
| `optionActive` *required* | `( label: string, state: { selected?: boolean; disabled?: boolean; group?: string }, ) => string` | — | The option the keys moved onto, with what VoiceOver leaves out. |
| `optionAdded` *required* | `(label: string) => string` | — | A value the multi-select took or gave away where no checkbox had the focus to say it - Enter in the search, a chip, Backspace. |
| `optionRemoved` *required* | `(label: string) => string` | — |  |
| `palettePlaceholder` *required* | `string` | — | What stands in the empty field. |
| `paletteField` *required* | `string` | — | Accessible name of the field. Deliberately kept apart from the placeholder - whoever labels the field differently does not thereby rename the window. |
| `palettePanel` *required* | `string` | — | Accessible name of the window. |
| `paletteList` *required* | `string` | — | Accessible name of the list of finds. |
| `paletteNoFinds` *required* | `string` | — | The one line when the query finds nothing. |
| `paletteFindCount` *required* | `(count: number) => string` | — | What the screen reader hears when the number of finds changes. |
| `paletteMoreFinds` *required* | `(count: number) => string` | — | The last line when more finds exist than `maxFinds` lets stand. |
| `paletteHintMove` *required* | `string` | — | The three key hints in the footer, each the text beside the key. |
| `paletteHintChoose` *required* | `string` | — |  |
| `paletteHintClose` *required* | `string` | — |  |
| `paletteKeyEsc` *required* | `string` | — | The legend on the Escape key. The arrows and the return key are glyphs and therefore do not stand here; "Esc" is a word and is called something else elsewhere. |
| `datePlaceholder` *required* | `string` | — |  |
| `datePanel` *required* | `string` | — | Accessible name of the panel. Deliberately kept apart from the placeholder: whoever labels the field differently does not thereby rename the dialog. |
| `dateClear` *required* | `string` | — |  |
| `dateTimePlaceholder` *required* | `string` | — |  |
| `dateTimePanel` *required* | `string` | — |  |
| `dateTimeClear` *required* | `string` | — |  |
| `dateRangePlaceholder` *required* | `string` | — |  |
| `dateRangePanel` *required* | `string` | — |  |
| `dateRangeClear` *required* | `string` | — |  |
| `dateTimeRangePanel` *required* | `string` | — | Accessible name of the panel in the range with time of day. |
| `dateTimeRangeClear` *required* | `string` | — | The clearing x of the range with time - kept apart from the range without, so that an application can call the two differently. |
| `previousMonth` *required* | `string` | — |  |
| `nextMonth` *required* | `string` | — |  |
| `quickSelect` *required* | `string` | — | Group name of the preset column. |
| `today` *required* | `string` | — | <br>Shown in: [Use the language in your own components (Language)](#/language/own-components) |
| `now` *required* | `string` | — |  |
| `clear` *required* | `string` | — |  |
| `apply` *required* | `string` | — |  |
| `allDay` *required* | `string` | — |  |
| `timeOfDay` *required* | `string` | — |  |
| `hour` *required* | `string` | — |  |
| `minute` *required* | `string` | — |  |
| `second` *required* | `string` | — |  |
| `sideFrom` *required* | `string` | — | Header of the two time columns in the range with time of day. |
| `sideTo` *required* | `string` | — |  |
| `startHour` *required* | `string` | — | Accessible name of the time fields, per side. |
| `startMinute` *required* | `string` | — |  |
| `startSecond` *required* | `string` | — |  |
| `endHour` *required* | `string` | — |  |
| `endMinute` *required* | `string` | — |  |
| `endSecond` *required* | `string` | — |  |
| `timeFieldIncrease` *required* | `(feld: string) => string` | — | Stepper buttons of a time field; the label comes from above. |
| `timeFieldDecrease` *required* | `(feld: string) => string` | — |  |
| `chooseStartDate` *required* | `string` | — | Footer of the range panels. |
| `chooseEndDate` *required* | `string` | — |  |
| `days` *required* | `(count: number) => string` | — | "3 days" or "1 day" - the plural belongs to the language. |
| `daysSelected` *required* | `(count: number) => string` | — | "3 days selected" |
| `rangePreview` *required* | `(from: string, to: string, count: number) => string` | — | "17.03. – 19.03. · 3 days" while dragging; the dates come from the formats. |
| `daysAllDay` *required* | `(count: number) => string` | — | "3 days (all day)" |
| `duration` *required* | `(teile: readonly string[]) => string` | — | "Duration: 1 day 2 hrs 30 min" |
| `hoursShort` *required* | `(count: number) => string` | — |  |
| `minutesShort` *required* | `(count: number) => string` | — |  |
| `timeMissingHint` *required* | `(timeOfDay: string) => string` | — | Daylight-saving change: the hour that does not exist. |
| `timeMissingHintSide` *required* | `(side: string, timeOfDay: string) => string` | — | The same, with the side put in front ("From"/"To"). |
| `timeAmbiguousHint` *required* | `string` | — | Daylight-saving change: the hour that occurs twice. |
| `timeAmbiguousHintSide` *required* | `(side: string) => string` | — |  |
| `timeEarlier` *required* | `(versatz: string) => string` | — |  |
| `timeLater` *required* | `(versatz: string) => string` | — |  |
| `weekdays` *required* | `readonly string[]` | — | The calendar's weekday headers, starting at Monday. |
| `presets` *required* | `{ today: string; yesterday: string; last7Days: string; last30Days: string; thisMonth: string; previousMonth: string; thisQuarter: string; thisYear: string; }` | — | The quick-select ranges, in the order of PRESET_LABELS. |
| `pagination` *required* | `string` | — |  |
| `rows` *required* | `string` | — |  |
| `rowsPerPage` *required* | `string` | — |  |
| `pageOfPages` *required* | `(page: number, total: number, formatted?: { page: string; total: string }) => string` | — | "Page 2 of 7". `formatted` carries both numbers in the provider's formats, where the caller has them - a table over a server has "Page 1 of 100,000". |
| `previousPage` *required* | `string` | — |  |
| `nextPage` *required* | `string` | — |  |
| `filterReset` *required* | `string` | — | The two buttons in the column filter's footer. |
| `filterDone` *required* | `string` | — |  |
| `columns` *required* | `string` | — | The column menu's button. |
| `arrangeColumns` *required* | `string` | — | Accessible name of the list in the column menu. |
| `columnForward` *required* | `(column: string) => string` | — | The two buttons that move a column in the column menu. |
| `columnBackward` *required* | `(column: string) => string` | — |  |
| `pinColumnToStart` *required* | `(column: string) => string` | — | The column menu's pin keys: to a side, and back when it is pinned there. |
| `pinColumnToEnd` *required* | `(column: string) => string` | — |  |
| `unpinColumn` *required* | `(column: string) => string` | — |  |
| `columnForwardHint` *required* | `string` | — | The tooltips over those four keys: short, without the column, which stands in the same line. The keys' names above keep it for a screen reader. |
| `columnBackwardHint` *required* | `string` | — |  |
| `pinToStartHint` *required* | `string` | — |  |
| `pinToEndHint` *required* | `string` | — |  |
| `unpinHint` *required* | `string` | — |  |
| `exportLabel` *required* | `string` | — | The export button. |
| `exportPageLabel` *required* | `string` | — | The export button of a table in server mode, which holds and writes one page. |
| `exportFileName` *required* | `string` | — | The export's file name, where the application names none. |
| `tableSearchPlaceholder` *required* | `string` | — | Placeholder and accessible name of the search field. |
| `tableSearchLabel` *required* | `string` | — |  |
| `filterColumn` *required* | `(column: string) => string` | — | The filter button of a column: "Filter Region". |
| `filterHint` *required* | `string` | — | The tooltip over that button. |
| `selectRow` *required* | `(row: string) => string` | — | The selection of one row, named after its row header. |
| `selectAllRows` *required* | `string` | — | The selection of every row in the filtered set. |
| `selectAllOnPage` *required* | `string` | — | The same checkbox in server mode, where the table holds one page of a server's. |
| `expandRowNamed` *required* | `(row: string) => string` | — | The expand button, named after the row header. |
| `collapseRowNamed` *required* | `(row: string) => string` | — |  |
| `rowActions` *required* | `string` | — | Header of the actions column - for the screen reader, not visible. |
| `rowAction` *required* | `(aktion: string, row: string) => string` | — | One action on a row: "Open: A-2041". |
| `rowActionsMenu` *required* | `(row: string) => string` | — | The menu holding a row's actions. |
| `editCell` *required* | `(column: string, row: string) => string` | — | The editor of a cell in a table's grid mode, named after its column and its row: "Edit Budget: Marketing". |
| `newRow` *required* | `string` | — | The button above a grid that opens an empty row to fill in, and the name of that row while it has none ([ADR-0036](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0036-a-grid-edits-on-the-first-click-and-saves-rows-on-purpose.md)). |
| `saveRow` *required* | `string` | — | A row draft's buttons, named with the row through `rowAction`. |
| `discardRow` *required* | `string` | — |  |
| `deleteRow` *required* | `string` | — | A row's delete button, and its question once pressed: Delete? Delete / Keep. |
| `deleteRowAsk` *required* | `string` | — |  |
| `keepRow` *required* | `string` | — |  |
| `saveOrDiscardFirst` *required* | `string` | — | Said where someone tries to leave a row draft unsaved. |
| `cellAbsentValue` *required* | `string` | — | What the screen reader hears for an absent value. Visibly a muted dash stands there. |
| `booleanYes` *required* | `string` | — | A boolean without a presentation of its own. |
| `booleanNo` *required* | `string` | — |  |
| `footerSum` *required* | `string` | — | The kind of a footer number, read out before the number. |
| `footerAverage` *required* | `string` | — |  |
| `footerMinimum` *required* | `string` | — |  |
| `footerMaximum` *required* | `string` | — |  |
| `footerRange` *required* | `string` | — |  |
| `footerCount` *required* | `string` | — |  |
| `footerDistinct` *required* | `string` | — |  |
| `footerAggregate` *required* | `string` | — | An aggregate the application computes itself. |
| `grouping` *required* | `string` | — | The grouping section of the column menu, and the menu entry per column. |
| `groupBy` *required* | `(label: string) => string` | — |  |
| `groupedBy` *required* | `string` | — | The grouping's tag in the table toolbar: "Grouped by" Region › Customer. |
| `removeGrouping` *required* | `string` | — |  |
| `removeGroupingLevel` *required* | `(label: string) => string` | — |  |
| `foldAll` *required* | `string` | — |  |
| `unfoldAll` *required* | `string` | — |  |
| `groupNoValue` *required* | `string` | — | The group of rows without a value. |
| `groupContinued` *required* | `string` | — | Beside a group repeated at the top of a page that begins inside it. |
| `foldGroup` *required* | `(name: string, count: string) => string` | — | The fold of a group, with its value and its count. |
| `unfoldGroup` *required* | `(name: string, count: string) => string` | — |  |
| `foldBranch` *required* | `(row: string) => string` | — | The fold of a branch in a table with tree rows, named after its row - not `expandRowNamed`, which names the row detail's expander on the same row. |
| `unfoldBranch` *required* | `(row: string) => string` | — |  |
| `levelColumn` *required* | `string` | — | The first column of a tree's export. |
| `pathRow` *required* | `string` | — | A row shown only because a descendant matches the search or a filter. |
| `footerTopLevel` *required* | `string` | — | The footer of a tree: it sums the top level, since a parent holds its children. |
| `selectGroup` *required* | `(name: string) => string` | — | The box that selects every row of a group. |
| `calendarWeek` *required* | `(week: number, year: number) => string` | — | A group of the week key: "Week 42, 2026". |
| `entries` *required* | `(count: number, formatted: string) => string` | — | "128 entries" in the pagination bar; the plural belongs to the language. |
| `selectedCount` *required* | `(count: number, formatted: string) => string` | — | "3 selected" in the pagination bar and the table toolbar. |
| `copiedRows` *required* | `(count: number, formatted: string) => string` | — | Said to a screen reader after Ctrl+C copied rows: "3 rows copied". |
| `copiedCell` *required* | `string` | — | Said after Ctrl+C copied the active cell of a grid. |
| `copyFailed` *required* | `string` | — | Said when the clipboard refused or is not there. |
| `noEntries` *required* | `string` | — | Empty because there are no rows. |
| `nothingMatchesFilters` *required* | `string` | — | Empty because search and filters leave nothing - something else. |
| `treeSearchPlaceholder` *required* | `string` | — |  |
| `treeNoMatches` *required* | `string` | — |  |
| `conditions` *required* | `string` | — | Group name of the conditions in the table toolbar. |
| `removeConditionNamed` *required* | `(label: string, value: string) => string` | — | The button that removes a condition: "Remove Region: EU, US". |
| `editConditionNamed` *required* | `(label: string, value: string) => string` | — | The condition itself, which opens its filter: "Edit Region: EU, US". |
| `moreValues` *required* | `(count: number, formatted: string) => string` | — | The remainder of a long list in a condition: "+1". |
| `filterFrom` *required* | `string` | — | The two fields of the range filter. |
| `filterTo` *required* | `string` | — |  |
| `rangeFromTo` *required* | `(from: string, to: string) => string` | — | The condition of a range filter: "100–500", "from 100", "to 500". |
| `rangeFrom` *required* | `(from: string) => string` | — |  |
| `rangeTo` *required* | `(to: string) => string` | — |  |
| `rangeInvalid` *required* | `string` | — | When "From" lies behind "To". The condition stays the last valid one. |
| `resetAll` *required* | `string` | — | Clears search and conditions - in the table toolbar and in the empty body. |
| `filteredOfTotal` *required* | `(matches: string, total: string) => string` | — | "43 of 1.204" - the numbers come from the formats. |
| `verdictOk` *required* | `string` | — | The four outcomes of an assessment, as a word beside the value. Colour alone carries no meaning - the word stands here for that reason.<br>Shown in: [Replace single entries (Language)](#/language/single-entries) |
| `verdictWarning` *required* | `string` | — | <br>Shown in: [Replace single entries (Language)](#/language/single-entries) |
| `verdictAlarm` *required* | `string` | — | <br>Shown in: [Replace single entries (Language)](#/language/single-entries) |
| `verdictUnknown` *required* | `string` | — |  |
| `statAbsentValue` *required* | `string` | — | What stands in the value field when there is no value. No dash, no zero: either could be a value. |
| `target` *required* | `string` | — |  |
| `deviationAbove` *required* | `(betrag: string) => string` | — | "3,2 above target" or "1,5 below target" - the amount comes from the formats, which is where the comma is from. |
| `deviationBelow` *required* | `(betrag: string) => string` | — |  |
| `deviationOnTarget` *required* | `string` | — |  |
| `freshnessFresh` *required* | `string` | — | The three freshness states. They are a DIFFERENT axis from the verdict: a stale value keeps its verdict ([ADR-0010](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0010-a-stale-value-keeps-its-verdict.md)). |
| `freshnessStale` *required* | `string` | — |  |
| `freshnessDisconnected` *required* | `string` | — |  |
| `asOfAgo` *required* | `(duration: string) => string` | — | "As of: 3 minutes ago", where the duration comes from the formats. |
| `close` *required* | `string` | — |  |
| `closeToast` *required* | `string` | — |  |
| `toastDeckCount` *required* | `(count: number) => string` | — | The count on the front toast of a closed deck; pressing it shows them all. |
| `toastRegion` *required* | `string` | — | The name of the toasts' region, which Alt+T moves the focus into. |
| `confirm` *required* | `string` | — |  |
| `cancel` *required* | `string` | — |  |
| `loading` *required* | `string` | — |  |
| `fillLevel` *required* | `string` | — | Generic name of a fill-level bar, where the caller names none. |
| `progress` *required* | `string` | — | Generic name of a progress bar, where the caller names none. |
| `breadcrumb` *required* | `string` | — | The accessible name of a breadcrumb's navigation landmark. |
| `breadcrumbFolded` *required* | `string` | — | The key that opens a breadcrumb's folded middle levels as a menu. |
| `splitter` *required* | `string` | — | The separator between a splitter's panes, where the caller names none - a caller who can should name the first pane instead (APG). |
| `stepDone` *required* | `string` | — | A stepper's step that is behind it, said beside its label to a screen reader; the current step is `aria-current` and needs no word. |
| `stepUpcoming` *required* | `string` | — | A step still ahead. |
| `stepFailed` *required* | `string` | — | A step that failed - behind the current one or the current one itself. |
| `chooseFile` *required* | `string` | — | The key of a file input that takes one file - and its name where no field names it. |
| `chooseFiles` *required* | `string` | — | The same key where it takes several. |
| `dropFile` *required* | `string` | — | The words beside the key that say the zone takes a drop. |
| `dropFiles` *required* | `string` | — |  |
| `removeFile` *required* | `(name: string) => string` | — | The cross beside a chosen file. |
| `fileNotAccepted` *required* | `(name: string) => string` | — | A dropped file the input's `accept` does not take. |
| `show` *required* | `string` | — |  |
| `hide` *required* | `string` | — |  |
| `moreActions` *required* | `string` | — |  |
| `remove` *required* | `string` | — | The cross on a tag without text content. |
| `removeTag` *required* | `(beschriftung: string) => string` | — | The cross on a tag with text content. |
| `scheduleOverlap` *required* | `string` | — | The two findings, named on the ghost of a drag. |
| `scheduleViolatedDependency` *required* | `string` | — |  |
| `scheduleGhostTimes` *required* | `(from: string, to: string) => string` | — | The new times on the ghost: "08:15–10:00" - the times come from the formats. |
| `scheduleLeadIn` *required* | `string` | — | The parts of a subtask and a dependency, named in the tooltip. |
| `scheduleLeadOut` *required* | `string` | — |  |
| `scheduleDependency` *required* | `string` | — |  |
| `scheduleRoute` *required* | `(from: string, to: string) => string` | — | "A-2041-1 → A-2041-2": the two subtasks a dependency joins. |
| `scheduleOverlapWith` *required* | `(other: string) => string` | — | "Overlap with A-2043-2" - the other subtask on the lane. |
| `scheduleViolatedBy` *required* | `(amount: string) => string` | — | "Violated dependency, 15 min short" - the amount from `minutesShort`. |
| `scheduleLaneRefused` *required* | `string` | — | On the ghost of a drag over a lane the subtask may not go to. |
| `scheduleBlockedTime` *required* | `string` | — | On the ghost of a drag held back from a lane's blocked time. |
| `scheduleInBlockedTime` *required* | `(label: string \| undefined) => string` | — | "In blocked time (Leave)" - a subtask covering its lane's blocked time, with the blocked time's label where it has one. |
| `scheduleMilestone` *required* | `(name: string) => string` | — | "Milestone: Release" - a milestone named by its label (or id), so that the tooltip and the spoken readout say what kind of thing it is. |
| `scheduleFoldGroup` *required* | `string` | — | The chevron of a lane group's header, which folds it into one row and unfolds it again. The group's own label stands beside the button, so the name is what the ACTION is, not which group it acts on. |
| `scheduleUnfoldGroup` *required* | `string` | — |  |
| `scheduleLaneCount` *required* | `(count: number) => string` | — | How many lanes a group holds, beside its name in the header. |
| `scheduleRoleDescription` *required* | `string` | — | What a screen reader calls the plot that takes the keys (`aria-roledescription`, schedule-a11y S1). |
| `scheduleSummary` *required* | `(summary: { lanes: number; subtasks: number; from: string; to: string; overlaps: number; violated: number; /** Subtasks in blocked time; said only where there are any. */ blocked: number; /** Milestones of the plan; said only where there are any. */ milestones: number; }) => string` | — | The plot's description (S6): the lanes, the subtasks in view, the visible span with both ends formatted, and the findings of the plan by kind. |
| `scheduleKeyHelp` *required* | `string` | — | The keys that walk the plot, select and edit - read after the summary. |
| `dashboardEdit` *required* | `string` | — | The editing bar's buttons and the label that says the mode is on. |
| `dashboardEditing` *required* | `string` | — |  |
| `dashboardCancel` *required* | `string` | — |  |
| `dashboardDone` *required* | `string` | — |  |
| `dashboardUndo` *required* | `string` | — |  |
| `dashboardRedo` *required* | `string` | — |  |
| `dashboardReset` *required* | `string` | — |  |
| `dashboardMenu` *required* | `(title: string) => string` | — | The name of a widget's menu button: the widget's title is the thing. |
| `dashboardPlace` *required* | `(place: number, of: number) => string` | — | At the top of the menu, and in the name of a head the arrow keys move. |
| `dashboardHead` *required* | `(title: string, place: number, of: number) => string` | — |  |
| `dashboardMoveStart` *required* | `string` | — |  |
| `dashboardMoveEarlier` *required* | `string` | — |  |
| `dashboardMoveLater` *required* | `string` | — |  |
| `dashboardMoveEnd` *required* | `string` | — |  |
| `dashboardRemove` *required* | `string` | — |  |
| `dashboardSizes` *required* | `{ small: string; medium: string; wide: string; tall: string; large: string; full: string }` | — | The closed set of size names, worded once for every widget type. |
| `dashboardSizeEntry` *required* | `(size: string, share: string, current: boolean) => string` | — | A size's entry in a widget's menu: its name and its share of the width (`share` is "¼" or "5/12", empty for the whole width); `current` marks the size the widget stands at. |
| `dashboardHeadingLabel` *required* | `string` | — | The built-in heading type: its name, its sentence in the catalogue, the text a new heading starts with and the label of its text field. |
| `dashboardHeadingSentence` *required* | `string` | — |  |
| `dashboardHeadingText` *required* | `string` | — |  |
| `dashboardHeadingField` *required* | `string` | — |  |
| `dashboardLeft` *required* | `string` | — | Said when "Done" leaves the mode and nothing was changed. |
| `dashboardMoved` *required* | `(title: string, from: number, to: number, of: number) => string` | — | What is spoken after a change. |
| `dashboardDragCancelled` *required* | `(title: string) => string` | — |  |
| `dashboardResized` *required* | `(title: string, size: string) => string` | — |  |
| `dashboardRemoved` *required* | `(title: string) => string` | — |  |
| `dashboardKept` *required* | `string` | — |  |
| `dashboardCancelled` *required* | `string` | — |  |
| `dashboardAddWidget` *required* | `string` | — | The catalogue and the options. |
| `dashboardCatalogue` *required* | `string` | — |  |
| `dashboardCatalogueSentence` *required* | `string` | — |  |
| `dashboardAdd` *required* | `string` | — |  |
| `dashboardAddType` *required* | `(label: string) => string` | — |  |
| `dashboardFootprint` *required* | `(columns: number, rows: number) => string` | — |  |
| `dashboardAdded` *required* | `(title: string, place: number, of: number) => string` | — |  |
| `dashboardOptions` *required* | `string` | — |  |
| `dashboardOptionsChanged` *required* | `(title: string) => string` | — |  |
| `dashboardEmpty` *required* | `string` | — |  |
| `dashboardEmptyEditing` *required* | `string` | — |  |
| `dashboardFailed` *required* | `string` | — |  |
| `dashboardUndone` *required* | `string` | — |  |
| `dashboardRedone` *required* | `string` | — |  |
| `dashboardResetDone` *required* | `string` | — |  |
| `calculationSumSymbol` *required* | `string` | — | The four operators as symbols in a formula line. |
| `calculationDifferenceSymbol` *required* | `string` | — |  |
| `calculationProductSymbol` *required* | `string` | — |  |
| `calculationQuotientSymbol` *required* | `string` | — |  |
| `calculationSumWord` *required* | `string` | — | The same four as words, in the accessible sentence of a line. |
| `calculationDifferenceWord` *required* | `string` | — |  |
| `calculationProductWord` *required* | `string` | — |  |
| `calculationQuotientWord` *required* | `string` | — |  |
| `calculationEquals` *required* | `string` | — | Between the parts of the sentence: "Availability equals ...". |
| `calculationApproximately` *required* | `string` | — | Before a result marked "≈" in the sentence. |
| `calculationApproximateNote` *required* | `string` | — | Beside a result marked "≈": why the rounded operands do not give it. |
| `calculationPercent` *required* | `string` | — | How a percentage is read out: "91.6 percent". |
| `calculationMissing` *required* | `(label: string) => string` | — | Why a quantity has no number - the label is the given at the root of it, or the divisor that is zero. |
| `calculationDivisionByZero` *required* | `(label: string) => string` | — |  |
| `calculationAboveTarget` *required* | `(target: string) => string` | — | The target beside the result, with the target's number and unit. |
| `calculationBelowTarget` *required* | `(target: string) => string` | — |  |
| `calculationOnTarget` *required* | `(target: string) => string` | — |  |
| `calculationWorstInside` *required* | `(verdict: string) => string` | — | The quiet marker on a folded quantity whose derivation holds a worse verdict than its own; the verdict word comes from `verdict*`. |
| `calculationSource` *required* | `(source: string) => string` | — | Where a given number came from. |
| `calculationShowDerivation` *required* | `(label: string) => string` | — | The disclosure button of a derivation, named after the quantity. |
| `calculationHideDerivation` *required* | `(label: string) => string` | — |  |
| `calculationOperandCount` *required* | `(count: number) => string` | — | On a folded line whose operator has more operands than are written out beneath it ([ADR-0028](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0028-a-calculation-is-a-tree-or-a-chain.md)): how many there are. |
| `calculationNoOperands` *required* | `string` | — | On the line of a sum with no operands, where its formula would stand ([ADR-0049](https://github.com/romanhaendler/umriss-ui/blob/main/docs/adr/0049-a-sum-takes-rows-from-data.md)). |

Used on [Language](#/language).

#### @umriss-ui/core/wording/de

##### `GERMAN_FORMATS`

The German notation: 17.03.2026, 09:05, 1.204,5, "vor 3 Minuten" - and
German collation, which files Ä with A. The clock is 24-hour here as it is
in the default; that never was a question of language.

Every entry, with its value, stands in the table [Formats](#/language/format) on the Language page.

```ts
const GERMAN_FORMATS: Formats;
```

Used on [UmrissProvider](#/umrissprovider) and [Language](#/language).

##### `GERMAN_WORDING`

The German instance. Complete, because it is typed `Wording`.

Every entry, with its value, stands in the table [Wording](#/language/wording) on the Language page.

```ts
const GERMAN_WORDING: Wording;
```

Used on [UmrissProvider](#/umrissprovider) and [Language](#/language).

#### Types on this page

##### `FormFieldContextValue`

| Prop | Type | Default | Description |
|---|---|---|---|
| `id` *required* | `string` | — |  |
| `labelId` *required* | `string` | — | The label's own id. `label htmlFor` names only what HTML can label - an input, a select, a button; a group (`role="radiogroup"`) is named through `aria-labelledby` with this. |
| `describedBy` | `string` | — |  |
| `invalid` *required* | `boolean` | — |  |
| `required` *required* | `boolean` | — | A required field. Every field whose role carries it turns this into `aria-required` - just as it does with `aria-describedby` and `aria-invalid`. |

##### `ToastContextValue`

| Prop | Type | Default | Description |
|---|---|---|---|
| `toast` *required* | `(options: `[`ToastOptions`](#/toast/type-ToastOptions)`) => number` | — | Shows a toast and returns its id.<br>Shown in: [Show a toast (Toast)](#/toast/show-a-toast), [Tones (Toast)](#/toast/tones), [Undo (Toast)](#/toast/undo) and 10 more |
| `update` *required* | `(id: number, options: Partial<`[`ToastOptions`](#/toast/type-ToastOptions)`>) => void` | — | Changes a standing toast. A new tone or a new `duration` starts its time afresh - so a `loading` toast turned into `success` begins to count then. An id that no longer stands is ignored: a timed toast that gave way to newer ones has said so through `onClose`. A `loading` toast turned into its outcome counts toward the limit from the next arrival on; `update` itself pushes nothing out.<br>Shown in: [Save, and say how it went (Toast)](#/toast/save-with-loading) |
| `dismiss` *required* | `(id: number) => void` | — | Closes a toast, with the reason `dismiss`. |

##### `Instant`

What may come in as an as-of time or a reference time.

```ts
type Instant = Date | number | null | undefined;
```