@umriss-ui/dashboard 0.0.0-stage → 0.40.0

package/docs/llms-full.md

@@ -0,0 +1,964 @@
+# @umriss-ui/dashboard 0.40.0
+
+> React dashboard for data-dense applications - widgets a reader arranges, packed in order on twelve columns.
+
+Install with `npm install @umriss-ui/dashboard @umriss-ui/core`. This text is generated from the package's demo (https://romanhaendler.github.io/umriss-ui/dashboard/): 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/dashboard/llms.txt.
+
+## Scenarios
+
+Composed, realistic screens built from the package. A numbered mark on the screen is an element with `data-callout`.
+
+### Arrange the start screen
+
+A dispatcher at Ferrow Parcel opens the same start screen every day and wants the figure she looks at fifty times a day first. Four cases walk through what the screen does at other widths, while she rearranges it, when something goes wrong and what the application stays in charge of.
+
+1. The case: each one starts the dashboard anew, with the arrangement the application chose for the role.
+2. What the application does - the window it is opened in, a navigation away, a stored value from an old release, a lock - as buttons. What the reader does stands in the sentence beside them: the real controls are in the dashboard.
+3. What happened, in a sentence.
+4. The dashboard itself. It measures its own width, so the stage narrows and widens it without a window.
+5. What the application was told: once per "Done" that changed something, with the whole arrangement.
+
+Built from: Dashboard, Chart, SegmentedControl, Alert, Text.
+
+```tsx
+import { useRef, useState } from "react";
+import type { CSSProperties, ReactNode } from "react";
+import { useChart } from "@umriss-ui/charts";
+import { Alert, Button, SegmentedControl, Stack, Text } from "@umriss-ui/core";
+import { HeadingType, useDashboard } from "@umriss-ui/dashboard";
+import type { DashboardView, HeadingOptions } from "@umriss-ui/dashboard";
+
+/* Data from the logistics world, written out here so the example runs on its own. */
+
+type Verdict = "ok" | "warn" | "bad";
+
+const MARK: Record<Verdict, CSSProperties> = {
+  ok: { background: "var(--u-color-success)", borderRadius: "50%" },
+  warn: { background: "var(--u-color-warning)", borderRadius: 2 },
+  bad: { background: "var(--u-color-danger)", transform: "rotate(45deg)" },
+};
+
+const hairline = "1px solid var(--u-hairline)";
+
+/** A status mark whose shape says it too: circle, square, diamond. */
+function Dot({ verdict }: { verdict: Verdict }) {
+  return <span aria-hidden="true" style={{ flex: "none", width: 8, height: 8, ...MARK[verdict] }} />;
+}
+
+/** A figure: a large value with its unit, and a status line under it. */
+function Kz({ value, unit, verdict, note }: { value: string; unit?: string; verdict: Verdict; note: string }) {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", justifyContent: "center", gap: "var(--u-space-1)", height: "100%", minWidth: 0 }}>
+      <Text as="div" size="2xl" weight="semibold" leading="tight" style={{ fontVariantNumeric: "tabular-nums", whiteSpace: "nowrap" }}>
+        {value}
+        {unit && <Text as="span" size="sm" tone="muted" style={{ marginInlineStart: "var(--u-space-1)", fontWeight: "var(--u-weight-regular)" }}>{unit}</Text>}
+      </Text>
+      <Text as="div" size="xs" tone="secondary" style={{ display: "flex", alignItems: "center", gap: 6, whiteSpace: "nowrap" }}>
+        <Dot verdict={verdict} />
+        {note}
+      </Text>
+    </div>
+  );
+}
+
+/** The trend: this week as a line with a faint area, last week dashed and muted, on one scale; with `previous` the legend too. */
+function TrendChart({ data, previous, labels = ["this week", "last week"] }: { data: readonly number[]; previous?: readonly number[]; labels?: readonly [string, string] }) {
+  const rows = data.map((now, i) => ({ i, now, before: previous?.[i] ?? now }));
+  const { Chart, XAxis, YAxis, Line, Area } = useChart(rows);
+  const swatch = (color: string, dashed = false): CSSProperties => ({ display: "inline-block", width: 14, borderTop: `2px ${dashed ? "dashed" : "solid"} ${color}`, verticalAlign: "middle", marginInlineEnd: 5 });
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "var(--u-space-2)", height: "100%", minWidth: 0 }}>
+      {previous && (
+        <Text as="div" size="xs" tone="secondary" style={{ display: "flex", gap: 14 }}>
+          <span><i style={swatch("var(--u-color-accent)")} />{labels[0]}</span>
+          <span><i style={swatch("var(--u-color-text-muted)", true)} />{labels[1]}</span>
+        </Text>
+      )}
+      <div style={{ flex: "1 1 0", minHeight: 0 }}>
+        <Chart ariaLabel={previous ? `${labels[0]} and ${labels[1]}` : labels[0]} padding={4} style={{ minHeight: 0, height: "100%" }}>
+          <XAxis value="i" domain="data" grid={false} tickFormat={() => ""} />
+          <YAxis grid tickFormat={() => ""} />
+          {previous && <Line value="before" name={labels[1]} color="var(--u-color-text-muted)" strokeWidth={1.25} dash={[3, 3]} markers="never" />}
+          <Area value="now" name={labels[0]} color="var(--u-color-accent)" fillOpacity={0.09} strokeWidth={1.75} />
+        </Chart>
+      </div>
+    </div>
+  );
+}
+
+/** Rows under each other, a hairline between them: a mark, a text, what belongs to it at the end. */
+function Rows({ rows }: { rows: ReadonlyArray<{ verdict: Verdict; text: string; meta?: string }> }) {
+  return (
+    <ul style={{ listStyle: "none", margin: 0, padding: 0 }}>
+      {rows.map(({ verdict, text, meta }, i) => (
+        <li key={text} style={{ display: "flex", alignItems: "center", gap: "var(--u-space-3)", padding: "6px 0", borderTop: i ? hairline : undefined }}>
+          <Dot verdict={verdict} />
+          <Text as="span" size="sm" style={{ flex: "1 1 0", minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{text}</Text>
+          {meta && <Text as="span" size="xs" tone="muted" style={{ whiteSpace: "nowrap" }}>{meta}</Text>}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/** A table with a muted head and a hairline between the rows; `numeric` columns stand right. */
+function DataTable({ head, rows, numeric = [] }: { head: readonly string[]; rows: ReadonlyArray<readonly ReactNode[]>; numeric?: readonly number[] }) {
+  const align = (i: number): CSSProperties => ({ textAlign: numeric.includes(i) ? "right" : "left", paddingBlock: 5, paddingInline: "0 var(--u-space-2)", whiteSpace: "nowrap" });
+  return (
+    <table style={{ width: "100%", borderCollapse: "collapse", fontSize: "var(--u-text-sm)", fontVariantNumeric: "tabular-nums" }}>
+      <thead>
+        <tr>
+          {head.map((name, i) => (
+            <th key={name} style={{ ...align(i), color: "var(--u-color-text-muted)", fontSize: "var(--u-text-xs)", fontWeight: "var(--u-weight-medium)" }}>{name}</th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map((cells, r) => (
+          <tr key={r}>
+            {cells.map((cell, i) => (
+              <td key={i} style={{ ...align(i), borderTop: hairline }}>{cell}</td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+const FIGURES = {
+  Orders: { value: "1,284", unit: "per day", verdict: "ok", note: "+3.1% on last week" },
+  Utilisation: { value: "87.4", unit: "%", verdict: "ok", note: "on target" },
+  Complaints: { value: "2.9", unit: "%", verdict: "warn", note: "just above target" },
+  Backlog: { value: "38", unit: "", verdict: "bad", note: "target missed" },
+} as const satisfies Record<string, { value: string; unit: string; verdict: Verdict; note: string }>;
+type Figure = keyof typeof FIGURES;
+
+const TREND: Record<Figure, { now: readonly number[]; before: readonly number[] }> = {
+  Orders: { now: [58, 52, 55, 51, 49, 53, 47, 52, 56, 60, 57, 55, 56, 58, 54, 52, 52, 49, 46, 49, 52, 55, 62, 58, 61, 55, 57, 62], before: [56, 56, 50, 53, 53, 60, 66, 68, 66, 64, 56, 52, 49, 50, 48, 49, 47, 45, 42, 38, 36, 36, 32, 30, 28, 34, 34, 30] },
+  Utilisation: { now: [60, 62, 66, 64, 68, 70, 72, 71, 74, 73, 76, 78], before: [58, 59, 57, 60, 61, 60, 63, 62, 64, 63, 65, 66] },
+  Complaints: { now: [66, 72, 70, 62, 55, 62, 68, 54, 55, 58, 50, 52, 48, 51, 49, 47, 47, 47, 47, 58, 59, 52, 50, 53, 58, 60], before: [64, 66, 62, 60, 58, 56, 55, 53, 54, 52, 50, 49, 48, 47, 46, 46, 45, 45, 45, 46, 47, 47, 46, 46, 45, 45] },
+  Backlog: { now: [22, 25, 31, 29, 34, 36, 38], before: [30, 28, 27, 29, 26, 25, 24] },
+};
+
+const ALERTS = [
+  { verdict: "bad", text: "Tour 14 is 25 min late", meta: "12 min ago" },
+  { verdict: "warn", text: "Dock 3 is out of service", meta: "34 min ago" },
+  { verdict: "warn", text: "Call: Oakridge Pharmacy", meta: "1 h ago" },
+] as const satisfies ReadonlyArray<{ verdict: Verdict; text: string; meta: string }>;
+
+const ORDERS = [
+  ["A-2041", "Holloway Garden Supplies", "120", "Packed"],
+  ["A-2042", "Marlow & Finch Books", "490", "Picking"],
+  ["A-2043", "Brixley Cycles", "860", "Late"],
+];
+
+const heading = (id: string, text: string) => ({ id, type: "heading", size: "full" as const, options: { text } satisfies HeadingOptions });
+
+const DISPATCH: DashboardView = {
+  widgets: [
+    heading("h1", "Overview"),
+    { id: "f1", type: "figure", size: "small", options: { name: "Orders" } },
+    { id: "f2", type: "figure", size: "small", options: { name: "Utilisation" } },
+    { id: "f3", type: "figure", size: "small", options: { name: "Complaints" } },
+    { id: "f4", type: "figure", size: "small", options: { name: "Backlog" } },
+    heading("h2", "Trend"),
+    { id: "t1", type: "trend", size: "large", options: { name: "Orders" } },
+    { id: "a1", type: "alerts", size: "tall", options: {} },
+    heading("h3", "Work in hand"),
+    { id: "o1", type: "orders", size: "full", options: {} },
+  ],
+};
+
+const MANAGEMENT: DashboardView = {
+  widgets: [
+    heading("h1", "The week"),
+    { id: "t1", type: "trend", size: "wide", options: { name: "Utilisation" } },
+    { id: "t2", type: "trend", size: "wide", options: { name: "Complaints" } },
+    { id: "f1", type: "figure", size: "medium", options: { name: "Orders" } },
+  ],
+};
+
+const ROLES = { dispatch: DISPATCH, management: MANAGEMENT } as const;
+type Role = keyof typeof ROLES;
+
+/** What an older release stored: a widget type that is gone, and a size the trend no longer offers. */
+const OLD = {
+  widgets: [
+    { id: "f1", type: "figure", size: "small", options: { name: "Orders" } },
+    { id: "x1", type: "weather", size: "small", options: {} },
+    { id: "t1", type: "trend", size: "huge", options: { name: "Orders" } },
+    { id: "t2", type: "trend", size: "wide", options: { name: "Backlog" } },
+  ],
+} as unknown as DashboardView;
+
+const CASES = [
+  { value: "monitors", label: "Other monitors" },
+  { value: "rearranging", label: "Rearranging" },
+  { value: "wrong", label: "When something goes wrong" },
+  { value: "governs", label: "What the application governs" },
+] as const;
+type Case = (typeof CASES)[number]["value"];
+
+const INTRO: Record<Case, string> = {
+  monitors:
+    "The arrangement of the role has three sections, each with a heading across the width, and four figures in a row at the top. Open it on other screens and see whether every widget stays beside its neighbours.",
+  rearranging:
+    "Editing is a mode and a draft. A widget's head is the grip, and its menu does everything without a drag. After \"Edit\", try it yourself: drag a head, open a menu, or Tab to a head and press an arrow key. Undo goes back one step.",
+  wrong:
+    "A drag goes wrong, and a removed widget must not be lost. Undo takes one step back, \"Cancel\" all of them, and the application decides what happens when someone leaves with a draft open.",
+  governs:
+    "The arrangement is a value the application keeps and hands over. It owes the reader a lenient reading of an old value, a frame that outlives a widget that fails, a way back to its default and the choice to lock editing.",
+};
+
+function Stage({ shown }: { shown: Case }) {
+  const [said, setSaid] = useState("");
+  const [width, setWidth] = useState<number | null>(null);
+  const [role, setRole] = useState<Role>("dispatch");
+  const [locked, setLocked] = useState(false);
+  const [broken, setBroken] = useState(false);
+  const [leaving, setLeaving] = useState(false);
+  const [open, setOpen] = useState(false);
+  const [reports, setReports] = useState<string[]>([]);
+  const kept = useRef<Partial<Record<Role, DashboardView>>>({});
+
+  const parts = useDashboard({
+    defaultView: ROLES[role],
+    allowEdit: !locked,
+    onDraftChange: setOpen,
+    onViewChange: (view) => {
+      kept.current[role] = view;
+      setReports((all) => [...all, `${role === "dispatch" ? "Dispatch" : "Management"}: ${view.widgets.length} widgets`]);
+    },
+  });
+  const { Dashboard, WidgetType } = parts;
+  const edit = () => {
+    parts.edit();
+    setSaid("The frame, the label \"Editing\" and the changed heads show the mode. The widgets' content rests while it lasts.");
+  };
+
+  const buttons: Record<Case, ReactNode> = {
+    monitors: [1920, 2560, 820, 390].map((px) => (
+      <Button
+        key={px}
+        onClick={() => {
+          setWidth(px);
+          setSaid(
+            px >= 1920
+              ? "The dashboard stands at its maximum width, at the start. The room beside it belongs to the application."
+              : px > 400
+                ? "The same twelve columns, narrower. Every neighbour stands where it stood."
+                : "Below the width a column can be read at, the dashboard is a list, in the same order.",
+          );
+        }}
+      >
+        {`Open at ${px} px`}
+      </Button>
+    )),
+    rearranging: [
+      <Button key="edit" onClick={edit} disabled={parts.editing}>Edit</Button>,
+      <Button key="undo" onClick={() => { parts.undo(); setSaid("One step back, not all of them."); }} disabled={!parts.editing}>Undo</Button>,
+      <Button key="catalogue" onClick={() => { parts.catalogue(); setSaid("Every widget type with its name, a sentence and the room it takes. A new widget shows something at once and stands at the end."); }} disabled={!parts.editing}>Add a widget</Button>,
+      <Button key="done" onClick={() => { parts.done(); setSaid("Only now, and once, the application is told the whole arrangement."); }} disabled={!parts.editing}>Done</Button>,
+    ],
+    wrong: [
+      <Button key="edit" onClick={edit} disabled={parts.editing}>Edit</Button>,
+      <Button key="undo" onClick={() => { parts.undo(); setSaid("One step back; what you did before it stays."); }} disabled={!parts.editing}>Undo</Button>,
+      <Button key="cancel" onClick={() => { parts.cancel(); setSaid("Everything stands as before \"Edit\". Nothing was reported."); }} disabled={!parts.editing}>Cancel</Button>,
+      <Button
+        key="leave"
+        onClick={() => {
+          if (open) setLeaving(true);
+          else setSaid("The application navigates. Nothing was open.");
+        }}
+      >
+        Navigate away
+      </Button>,
+    ],
+    governs: [
+      <Button key="old" onClick={() => { parts.cancel(); parts.setView(OLD); setSaid("The stored value named a weather widget that is gone and a trend in a size it no longer offers: the one fell out, the other stands at its starting size, and the room beside it is free. Nothing broke."); }}>Load an old arrangement</Button>,
+      <Button key="crash" onClick={() => { setBroken(true); setSaid("A trend threw while drawing. Its frame, head and menu stand; everything else keeps working."); }}>Let a widget fail</Button>,
+      <Button key="reset" onClick={() => { parts.edit(); parts.reset(); setSaid("Back to the application's arrangement for this role - one more step of the draft: Undo brings yours back."); }} disabled={locked}>Reset to the default</Button>,
+      <Button key="lock" onClick={() => { parts.cancel(); setLocked(!locked); setSaid(locked ? "Editing is allowed." : "Without editing the dashboard is complete as it is: the same arrangement, no button, no mode."); }}>{locked ? "Allow editing" : "Lock editing"}</Button>,
+      <Button
+        key="role"
+        onClick={() => {
+          const next: Role = role === "dispatch" ? "management" : "dispatch";
+          parts.cancel();
+          setRole(next);
+          parts.setView(kept.current[next] ?? ROLES[next]);
+          setSaid("Another role, another default. Each role keeps its own value.");
+        }}
+      >
+        {role === "dispatch" ? "Sign in as management" : "Sign in as dispatch"}
+      </Button>,
+    ],
+  };
+
+  return (
+    <Stack gap={4}>
+      <Stack direction="row" gap={2} wrap data-callout="2">
+        {buttons[shown]}
+      </Stack>
+      <Text data-callout="3" tone="secondary" size="sm" aria-live="polite">{said || INTRO[shown]}</Text>
+      {leaving && (
+        <Alert
+          tone="warning"
+          title="Unsaved changes"
+          actions={
+            <Stack direction="row" gap={2}>
+              <Button size="sm" onClick={() => { setLeaving(false); setSaid("The draft is untouched."); }}>Keep editing</Button>
+              <Button size="sm" onClick={() => { parts.cancel(); setLeaving(false); setSaid("The draft is gone and the application navigates."); }}>Discard and leave</Button>
+            </Stack>
+          }
+        >
+          The library tells the application that a draft is open. What it makes of that is its own business; here it asks.
+        </Alert>
+      )}
+      <div data-callout="4" style={{ overflowX: "auto" }}>
+        <div style={{ width: width ?? "100%" }}>
+          <Dashboard aria-label="Dispatch, today">
+            <HeadingType />
+            <WidgetType
+              name="figure"
+              label="Figure"
+              sentence="One number."
+              sizes={{ small: { columns: 3, rows: 2 }, medium: { columns: 4, rows: 2 } }}
+              start="small"
+              defaultOptions={{ name: "Orders" as Figure }}
+              title={(options) => options.name}
+              form={({ options, change }) => (
+                <SegmentedControl
+                  aria-label="Figure"
+                  options={(Object.keys(FIGURES) as Figure[]).map((name) => ({ value: name, label: name }))}
+                  value={options.name}
+                  onChange={(name) => change({ name })}
+                />
+              )}
+            >
+              {({ options }) => {
+                return <Kz {...FIGURES[options.name]} />;
+              }}
+            </WidgetType>
+            <WidgetType
+              name="trend"
+              label="Trend"
+              sentence="A figure over the last seven days."
+              sizes={{ wide: { columns: 6, rows: 4 }, large: { columns: 8, rows: 4 } }}
+              start="wide"
+              defaultOptions={{ name: "Orders" as Figure }}
+              title={(options) => `${options.name}, last 7 days`}
+            >
+              {({ options, size }) => {
+                if (broken && options.name === "Orders") throw new Error("The trend could not be drawn");
+                return <TrendChart data={TREND[options.name].now} previous={size === "large" ? TREND[options.name].before : undefined} />;
+              }}
+            </WidgetType>
+            <WidgetType name="alerts" label="Open alerts" sentence="What needs attention now." sizes={{ tall: { columns: 4, rows: 4 } }} start="tall" defaultOptions={{}}>
+              {() => <Rows rows={ALERTS} />}
+            </WidgetType>
+            <WidgetType name="orders" label="Orders" sentence="The work in hand." sizes={{ full: { columns: 12, rows: 4 } }} start="full" defaultOptions={{}}>
+              {() => <DataTable head={["No.", "Customer", "Quantity", "Status"]} numeric={[2]} rows={ORDERS} />}
+            </WidgetType>
+          </Dashboard>
+        </div>
+      </div>
+      <Text data-callout="5" size="sm" tone="muted">
+        {reports.length === 0 ? "Told to the application: nothing yet." : `Told to the application: ${reports.join("; ")}.`}
+      </Text>
+    </Stack>
+  );
+}
+
+export default function ArrangeTheStartScreen() {
+  const [current, setCurrent] = useState<Case>("monitors");
+  return (
+    <Stack gap={4}>
+      <div data-callout="1">
+        <SegmentedControl aria-label="Case" options={CASES.map((one) => ({ value: one.value, label: one.label }))} value={current} onChange={setCurrent} />
+      </div>
+      <Stage key={current} shown={current} />
+    </Stack>
+  );
+}
+```
+
+## Getting started
+
+What a dashboard is for, and what an application sets up before the first one.
+
+### Dashboard
+
+Shows widgets a developer declares, in the order a view stores them, each at its size, packed on twelve columns: the start screen of a data-dense application, with the figures one role looks at first.
+
+```ts
+import { useDashboard, WidgetType, HeadingType } from "@umriss-ui/dashboard";
+```
+
+```sh
+npm install @umriss-ui/dashboard @umriss-ui/core
+```
+
+Demo page: https://romanhaendler.github.io/umriss-ui/dashboard/dashboard/
+
+The command brings the core package along, a peer dependency. React 19 or newer is a peer as well and stays the application's own. The stylesheet loads itself: the package imports it and marks CSS as a side effect.
+
+[`useDashboard`](#/api/useDashboard) takes the arrangement the application gives a reader and, optionally, the one the reader kept (`initialView`, read once). It hands back `Dashboard`, `WidgetType`, the view and `setView`.
+
+A widget type is declared as JSX: its name, a sentence, the sizes it offers with the columns and rows each takes, the size to start from, its default options and its content as a function of the size and the options. The options type is inferred from the default options.
+
+The widgets are packed in the stored order, each at the first place at or after the one before it where it fits; room left behind stays free. The columns never change in number, under a maximum width. Below the width at which a column would be too narrow to read, the dashboard is a list in the same order. The height follows the size and never the content.
+
+#### Examples
+
+##### The start screen of a dispatcher
+
+Declare each widget type once, hand over the arrangement for the role: the widgets stand in that order, each at its size.
+
+```tsx
+import { useState } from "react";
+import type { CSSProperties, ReactNode } from "react";
+import { useChart } from "@umriss-ui/charts";
+import { FormField, Select, Text } from "@umriss-ui/core";
+import { HeadingType, useDashboard } from "@umriss-ui/dashboard";
+import type { DashboardView, HeadingOptions } from "@umriss-ui/dashboard";
+
+type Verdict = "ok" | "warn" | "bad";
+
+const MARK: Record<Verdict, CSSProperties> = {
+  ok: { background: "var(--u-color-success)", borderRadius: "50%" },
+  warn: { background: "var(--u-color-warning)", borderRadius: 2 },
+  bad: { background: "var(--u-color-danger)", transform: "rotate(45deg)" },
+};
+
+const hairline = "1px solid var(--u-hairline)";
+
+/** A status mark whose shape says it too: circle, square, diamond. */
+function Dot({ verdict }: { verdict: Verdict }) {
+  return <span aria-hidden="true" style={{ flex: "none", width: 8, height: 8, ...MARK[verdict] }} />;
+}
+
+/** A figure: a large value with its unit, and a status line under it. */
+function Kz({ value, unit, verdict, note }: { value: string; unit?: string; verdict: Verdict; note: string }) {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", justifyContent: "center", gap: "var(--u-space-1)", height: "100%", minWidth: 0 }}>
+      <Text as="div" size="2xl" weight="semibold" leading="tight" style={{ fontVariantNumeric: "tabular-nums", whiteSpace: "nowrap" }}>
+        {value}
+        {unit && <Text as="span" size="sm" tone="muted" style={{ marginInlineStart: "var(--u-space-1)", fontWeight: "var(--u-weight-regular)" }}>{unit}</Text>}
+      </Text>
+      <Text as="div" size="xs" tone="secondary" style={{ display: "flex", alignItems: "center", gap: 6, whiteSpace: "nowrap" }}>
+        <Dot verdict={verdict} />
+        {note}
+      </Text>
+    </div>
+  );
+}
+
+/** The trend: this week as a line with a faint area, last week dashed and muted, on one scale; with `previous` the legend too. */
+function TrendChart({ data, previous, labels = ["this week", "last week"] }: { data: readonly number[]; previous?: readonly number[]; labels?: readonly [string, string] }) {
+  const rows = data.map((now, i) => ({ i, now, before: previous?.[i] ?? now }));
+  const { Chart, XAxis, YAxis, Line, Area } = useChart(rows);
+  const swatch = (color: string, dashed = false): CSSProperties => ({ display: "inline-block", width: 14, borderTop: `2px ${dashed ? "dashed" : "solid"} ${color}`, verticalAlign: "middle", marginInlineEnd: 5 });
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "var(--u-space-2)", height: "100%", minWidth: 0 }}>
+      {previous && (
+        <Text as="div" size="xs" tone="secondary" style={{ display: "flex", gap: 14 }}>
+          <span><i style={swatch("var(--u-color-accent)")} />{labels[0]}</span>
+          <span><i style={swatch("var(--u-color-text-muted)", true)} />{labels[1]}</span>
+        </Text>
+      )}
+      <div style={{ flex: "1 1 0", minHeight: 0 }}>
+        <Chart ariaLabel={previous ? `${labels[0]} and ${labels[1]}` : labels[0]} padding={4} style={{ minHeight: 0, height: "100%" }}>
+          <XAxis value="i" domain="data" grid={false} tickFormat={() => ""} />
+          <YAxis grid tickFormat={() => ""} />
+          {previous && <Line value="before" name={labels[1]} color="var(--u-color-text-muted)" strokeWidth={1.25} dash={[3, 3]} markers="never" />}
+          <Area value="now" name={labels[0]} color="var(--u-color-accent)" fillOpacity={0.09} strokeWidth={1.75} />
+        </Chart>
+      </div>
+    </div>
+  );
+}
+
+/** Rows under each other, a hairline between them: a mark, a text, what belongs to it at the end. */
+function Rows({ rows }: { rows: ReadonlyArray<{ verdict: Verdict; text: string; meta?: string }> }) {
+  return (
+    <ul style={{ listStyle: "none", margin: 0, padding: 0 }}>
+      {rows.map(({ verdict, text, meta }, i) => (
+        <li key={text} style={{ display: "flex", alignItems: "center", gap: "var(--u-space-3)", padding: "6px 0", borderTop: i ? hairline : undefined }}>
+          <Dot verdict={verdict} />
+          <Text as="span" size="sm" style={{ flex: "1 1 0", minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{text}</Text>
+          {meta && <Text as="span" size="xs" tone="muted" style={{ whiteSpace: "nowrap" }}>{meta}</Text>}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/** A table with a muted head and a hairline between the rows; `numeric` columns stand right. */
+function DataTable({ head, rows, numeric = [] }: { head: readonly string[]; rows: ReadonlyArray<readonly ReactNode[]>; numeric?: readonly number[] }) {
+  const align = (i: number): CSSProperties => ({ textAlign: numeric.includes(i) ? "right" : "left", paddingBlock: 5, paddingInline: "0 var(--u-space-2)", whiteSpace: "nowrap" });
+  return (
+    <table style={{ width: "100%", borderCollapse: "collapse", fontSize: "var(--u-text-sm)", fontVariantNumeric: "tabular-nums" }}>
+      <thead>
+        <tr>
+          {head.map((name, i) => (
+            <th key={name} style={{ ...align(i), color: "var(--u-color-text-muted)", fontSize: "var(--u-text-xs)", fontWeight: "var(--u-weight-medium)" }}>{name}</th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map((cells, r) => (
+          <tr key={r}>
+            {cells.map((cell, i) => (
+              <td key={i} style={{ ...align(i), borderTop: hairline }}>{cell}</td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+const FIGURES = {
+  Orders: { value: "1,284", unit: "per day", verdict: "ok", note: "+3.1% on last week" },
+  Utilisation: { value: "87.4", unit: "%", verdict: "ok", note: "on target" },
+  Complaints: { value: "2.9", unit: "%", verdict: "warn", note: "just above target" },
+  "On-time delivery": { value: "96.2", unit: "%", verdict: "ok", note: "on target" },
+} as const satisfies Record<string, { value: string; unit: string; verdict: Verdict; note: string }>;
+
+const TREND = {
+  Orders: { now: [58, 52, 55, 51, 49, 53, 47, 52, 56, 60, 57, 55, 56, 58, 54, 52, 52, 49, 46, 49, 52, 55, 62, 58, 61, 55, 57, 62], before: [56, 56, 50, 53, 53, 60, 66, 68, 66, 64, 56, 52, 49, 50, 48, 49, 47, 45, 42, 38, 36, 36, 32, 30, 28, 34, 34, 30] },
+  Complaints: { now: [66, 72, 70, 62, 55, 62, 68, 54, 55, 58, 50, 52, 48, 51, 49, 47, 47, 47, 47, 58, 59, 52, 50, 53, 58, 60], before: [64, 66, 62, 60, 58, 56, 55, 53, 54, 52, 50, 49, 48, 47, 46, 46, 45, 45, 45, 46, 47, 47, 46, 46, 45, 45] },
+} as const;
+
+const ALERTS = [
+  { verdict: "bad", text: "Tour 14 is 25 min late", meta: "12 min ago" },
+  { verdict: "warn", text: "Dock 3 is out of service", meta: "34 min ago" },
+  { verdict: "warn", text: "Call: Oakridge Pharmacy", meta: "1 h ago" },
+  { verdict: "ok", text: "Maintenance on line 3 finished", meta: "2 h ago" },
+] as const satisfies ReadonlyArray<{ verdict: Verdict; text: string; meta: string }>;
+
+const ORDERS = [
+  ["A-2041", "Holloway Garden Supplies", "120", "Oct 14", "Packed"],
+  ["A-2042", "Marlow & Finch Books", "490", "Oct 15", "Picking"],
+  ["A-2043", "Brixley Cycles", "860", "Oct 16", "Late"],
+  ["A-2044", "Ferrow Bakery", "75", "Oct 16", "Planned"],
+];
+
+const heading = (id: string, text: string) => ({ id, type: "heading", size: "full" as const, options: { text } satisfies HeadingOptions });
+
+const VIEW: DashboardView = {
+  widgets: [
+    heading("h1", "Overview"),
+    { id: "f1", type: "figure", size: "small", options: { name: "Orders" } },
+    { id: "f2", type: "figure", size: "small", options: { name: "Utilisation" } },
+    { id: "f3", type: "figure", size: "small", options: { name: "Complaints" } },
+    { id: "f4", type: "figure", size: "small", options: { name: "On-time delivery" } },
+    heading("h2", "Trend"),
+    { id: "t1", type: "trend", size: "large", options: { name: "Orders" } },
+    { id: "t2", type: "trend", size: "wide", options: { name: "Complaints" } },
+    heading("h3", "Work in hand"),
+    { id: "o1", type: "orders", size: "wide", options: {} },
+    { id: "a1", type: "alerts", size: "tall", options: {} },
+  ],
+};
+
+export default function Dispatcher() {
+  const [open, setOpen] = useState(false);
+  const [kept, setKept] = useState(0);
+  const { Dashboard, WidgetType } = useDashboard({
+    defaultView: VIEW,
+    allowEdit: true,
+    onDraftChange: setOpen,
+    onViewChange: () => setKept((count) => count + 1),
+  });
+  return (
+    <Dashboard aria-label="Dispatch, today" catalogue={["figure", "trend", "alerts"]} data-draft={open || undefined} data-kept={kept}>
+      <HeadingType />
+      <WidgetType
+        name="figure"
+        label="Figure"
+        sentence="One number with its verdict."
+        sizes={{ small: { columns: 3, rows: 2 }, medium: { columns: 4, rows: 2 } }}
+        start="small"
+        defaultOptions={{ name: "Orders" as keyof typeof FIGURES }}
+        title={(options) => options.name}
+        form={({ options, change }) => (
+          <FormField label="Figure">
+            <Select value={options.name} onChange={(event) => change({ name: event.target.value as keyof typeof FIGURES })}>
+              {Object.keys(FIGURES).map((name) => (
+                <option key={name}>{name}</option>
+              ))}
+            </Select>
+          </FormField>
+        )}
+      >
+        {({ options }) => <Kz {...FIGURES[options.name]} />}
+      </WidgetType>
+      <WidgetType
+        name="trend"
+        label="Trend"
+        sentence="A figure over the last weeks."
+        sizes={{ wide: { columns: 4, rows: 4 }, large: { columns: 8, rows: 4 } }}
+        start="wide"
+        defaultOptions={{ name: "Orders" as keyof typeof TREND }}
+        title={(options) => `${options.name} trend`}
+      >
+        {({ options, size }) => <TrendChart data={TREND[options.name].now} previous={size === "large" ? TREND[options.name].before : undefined} />}
+      </WidgetType>
+      <WidgetType name="alerts" label="Open alerts" sentence="What needs attention now." sizes={{ tall: { columns: 4, rows: 4 } }} start="tall" defaultOptions={{}}>
+        {() => <Rows rows={ALERTS} />}
+      </WidgetType>
+      <WidgetType name="orders" label="Orders" sentence="The work in hand." sizes={{ wide: { columns: 8, rows: 4 }, full: { columns: 12, rows: 4 } }} start="wide" defaultOptions={{}}>
+        {() => <DataTable head={["No.", "Customer", "Quantity", "Due", "Status"]} numeric={[2]} rows={ORDERS} />}
+      </WidgetType>
+    </Dashboard>
+  );
+}
+```
+
+##### Your own component as a widget
+
+A widget's content is any React component: a `WidgetType`'s children are a function of the size it stands at and its options, and return what the widget shows. Here the application's own list of tours shows more at a larger size, and its form chooses the depot.
+
+```tsx
+import { FormField, Select, Stack, Text } from "@umriss-ui/core";
+import { useDashboard } from "@umriss-ui/dashboard";
+import type { WidgetSize } from "@umriss-ui/dashboard";
+
+/* The application's own component - nothing in it knows the dashboard. */
+const TOURS = {
+  North: [
+    { tour: "Tour 12", stop: "Holloway Garden Supplies", eta: "10:40" },
+    { tour: "Tour 14", stop: "Brixley Cycles", eta: "11:05" },
+    { tour: "Tour 17", stop: "Ferrow Bakery", eta: "11:30" },
+    { tour: "Tour 19", stop: "Marlow & Finch Books", eta: "12:15" },
+  ],
+  South: [
+    { tour: "Tour 3", stop: "Oakridge Pharmacy", eta: "10:20" },
+    { tour: "Tour 5", stop: "Kestrel Hardware", eta: "11:50" },
+  ],
+};
+type Depot = keyof typeof TOURS;
+
+function ToursOnTheRoad({ depot, rows }: { depot: Depot; rows: number }) {
+  const tours = TOURS[depot];
+  return (
+    <Stack gap={1}>
+      <Text size="sm" tone="secondary">{`${tours.length} tours on the road from ${depot}`}</Text>
+      {tours.slice(0, rows).map((one) => (
+        <Text key={one.tour} size="sm">{`${one.tour} · ${one.stop} · ${one.eta}`}</Text>
+      ))}
+    </Stack>
+  );
+}
+
+/* How many lines each size has room for: the content is told its size. */
+const ROWS: Partial<Record<WidgetSize, number>> = { small: 1, wide: 4 };
+
+export default function YourOwnWidget() {
+  const { Dashboard, WidgetType } = useDashboard({
+    defaultView: {
+      widgets: [
+        { id: "north", type: "tours", size: "wide", options: { depot: "North" } },
+        { id: "south", type: "tours", size: "small", options: { depot: "South" } },
+      ],
+    },
+  });
+  return (
+    <Dashboard aria-label="Tours">
+      <WidgetType
+        name="tours"
+        label="Tours on the road"
+        sentence="The tours of one depot and their next stop."
+        sizes={{ small: { columns: 4, rows: 2 }, wide: { columns: 8, rows: 3 } }}
+        start="small"
+        defaultOptions={{ depot: "North" as Depot }}
+        title={(options) => `Tours, ${options.depot}`}
+        form={({ options, change }) => (
+          <FormField label="Depot">
+            <Select value={options.depot} onChange={(event) => change({ depot: event.target.value as Depot })}>
+              {Object.keys(TOURS).map((depot) => (
+                <option key={depot}>{depot}</option>
+              ))}
+            </Select>
+          </FormField>
+        )}
+      >
+        {({ size, options }) => <ToursOnTheRoad depot={options.depot} rows={ROWS[size] ?? 1} />}
+      </WidgetType>
+    </Dashboard>
+  );
+}
+```
+
+##### Headings that divide the dashboard
+
+The heading widget type is built in: one size across the full width, its text as its options, drawn as a title without a card. An application adds it to the dashboard when readers should be able to structure it.
+
+```tsx
+import { Text } from "@umriss-ui/core";
+import { HeadingType, useDashboard } from "@umriss-ui/dashboard";
+import type { DashboardView, HeadingOptions } from "@umriss-ui/dashboard";
+
+const VIEW: DashboardView = {
+  widgets: [
+    { id: "h1", type: "heading", size: "full", options: { text: "Today" } satisfies HeadingOptions },
+    { id: "n1", type: "note", size: "wide", options: {} },
+    { id: "n2", type: "note", size: "wide", options: {} },
+    { id: "h2", type: "heading", size: "full", options: { text: "This week" } satisfies HeadingOptions },
+    { id: "n3", type: "note", size: "wide", options: {} },
+  ],
+};
+
+export default function Sections() {
+  const { Dashboard, WidgetType } = useDashboard({ defaultView: VIEW });
+  return (
+    <Dashboard aria-label="Sections">
+      <HeadingType />
+      <WidgetType name="note" label="Note" sentence="A line of text." sizes={{ wide: { columns: 6, rows: 3 } }} start="wide" defaultOptions={{}}>
+        {() => <Text size="sm">Whatever the application puts in a widget.</Text>}
+      </WidgetType>
+    </Dashboard>
+  );
+}
+```
+
+##### A dashboard without widgets
+
+A dashboard that has no widgets says so, in the language of the surrounding provider.
+
+```tsx
+import { useDashboard } from "@umriss-ui/dashboard";
+
+export default function Empty() {
+  const { Dashboard } = useDashboard({ defaultView: { widgets: [] } });
+  return <Dashboard aria-label="Nothing yet" />;
+}
+```
+
+#### When to use something else
+
+- A layout the developer fixes, which the reader does not arrange → `Grid`, `Stack` and `Splitter` from @umriss-ui/core
+
+#### Keyboard
+
+| Key | Action |
+|---|---|
+| `Tab` | In the editing mode, moves to the next widget's head and its menu button. |
+| `Arrow keys` | On a focused head, move the widget one place earlier or later. |
+| `Home or End` | On a focused head, move the widget to the start or the end. |
+
+#### Accessibility
+
+The dashboard is a group named by its `aria-label`; every widget is a region named by its title. In the editing mode a widget's head is a tab stop named "<title>, place n of m", and its menu button "Actions for <title>".
+
+Every move, size, removal, addition, undo, redo, reset, "Done" and "Cancel" is announced through core's live region: "Orders: moved from place 1 to place 3 of 5". The words are core's wording, German under `@umriss-ui/core/wording/de`.
+
+#### API
+
+##### `DashboardOptions`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `defaultView` *required* | [`DashboardView`](#type-DashboardView) | — | The arrangement the application gives a reader who has none of their own.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 2 more |
+| `initialView` | [`DashboardView`](#type-DashboardView) | the `defaultView` | The reader's kept arrangement, read once when the hook first runs; a different value on a later render is ignored, as React ignores a changed `defaultValue`. To go to another, call `setView`. |
+| `allowEdit` | `boolean` | `true` | Whether the reader may edit. Without it no bar is drawn and the mode cannot be entered.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+
+###### Events
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onViewChange` | `(view: `[`DashboardView`](#type-DashboardView)`) => void` | — | Called once per "Done" that changed something, with the whole arrangement. Not called by `setView`.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `onDraftChange` | `(open: boolean) => void` | — | Called with `true` when a draft opens and with `false` when it closes - to warn before navigation.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+
+##### `DashboardParts`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `Dashboard` *required* | `(props: `[`DashboardProps`](#type-DashboardProps)`) => ReactNode` | — | The dashboard. One per `useDashboard`.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 2 more |
+| `WidgetType` *required* | `typeof WidgetType` | — | Declares a widget type inside `Dashboard`.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `view` *required* | [`DashboardView`](#type-DashboardView) | — | The arrangement in view: the draft while the mode is on. |
+| `setView` *required* | `(view: `[`DashboardView`](#type-DashboardView)`) => void` | — | Goes to a whole arrangement. Not reported.<br>Shown in: [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `editing` *required* | `boolean` | — | Whether the editing mode is on.<br>Shown in: [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `edit` *required* | `() => void` | — | Enters the editing mode. Does nothing where editing is not allowed.<br>Shown in: [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `done` *required* | `() => void` | — | Leaves the mode, keeps the changes and reports them once if there are any.<br>Shown in: [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `catalogue` *required* | `() => void` | — | Opens the catalogue. Does nothing outside the editing mode.<br>Shown in: [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `cancel` *required* | `() => void` | — | Leaves the mode and puts the arrangement back as it was before `edit`.<br>Shown in: [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `undo` *required* | `() => void` | — | Goes one step back in the draft. Does nothing at the first.<br>Shown in: [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `redo` *required* | `() => void` | — | Goes one step forward again. Does nothing at the last. |
+| `reset` *required* | `() => void` | — | Steps to the `defaultView`; `undo` brings the arrangement back.<br>Shown in: [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+
+##### `DashboardProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | The `WidgetType`s of this dashboard.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `catalogue` | `ReadonlyArray<string>` | every declared type | The `name`s of the widget types the catalogue lists.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher) |
+
+Also takes every attribute of `<div>`.
+
+##### `DashboardView`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `widgets` *required* | `ReadonlyArray<`[`DashboardWidget`](#type-DashboardWidget)`>` | — | The widgets, in the order they are drawn and read.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 2 more |
+
+##### `DashboardWidget`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `id` *required* | `string` | — | Unique within the view.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `type` *required* | `string` | — | The `name` of the widget type it is an instance of.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `size` *required* | [`WidgetSize`](#type-WidgetSize)<br>`"small" \| "medium" \| "wide" \| "tall" \| "large" \| "full"` | — | One of the sizes its type offers.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `options` *required* | `unknown` | — | The type's own options, typed through the hook.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+
+##### `WidgetSize`
+
+Declares no props of its own.
+
+##### `SizeSpan`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `columns` *required* | `number` | — | Columns of twelve.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `rows` *required* | `number` | — | Rows of the fixed row unit.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+
+##### `WidgetTypeProps<Options>`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `name` *required* | `string` | — | The name a view refers to this type by. Unique within the dashboard.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `label` *required* | `string` | — | The type's name for a reader, and the title of its frame unless `title` says otherwise.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `sentence` *required* | `string` | — | One sentence on what the type shows.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `sizes` *required* | `Partial<Record<`[`WidgetSize`](#type-WidgetSize)`, `[`SizeSpan`](#type-SizeSpan)`>>` | — | The sizes the type offers, each with the columns (of twelve) and rows it takes.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `start` *required* | [`WidgetSize`](#type-WidgetSize)<br>`"small" \| "medium" \| "wide" \| "tall" \| "large" \| "full"` | — | The size a new widget of this type starts at. One of `sizes`.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `defaultOptions` *required* | `Options` | — | The options a new widget starts with. Their type is the options type of `title` and of the content.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+| `title` | `(options: NoInfer<Options>) => string` | — | The title of a frame as a function of its options; the `label` without it.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `form` | `(props: `[`WidgetFormProps`](#type-WidgetFormProps)`<NoInfer<Options>>) => ReactNode` | — | The form for the options, opened from the widget's menu. Without it the menu has no options entry.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `children` *required* | `(content: `[`WidgetContent`](#type-WidgetContent)`<NoInfer<Options>>) => ReactNode` | — | The content, as a function of the size and the options.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Headings that divide the dashboard](#/dashboard/sections) and 1 more |
+
+##### `WidgetContent<Options>`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` *required* | [`WidgetSize`](#type-WidgetSize)<br>`"small" \| "medium" \| "wide" \| "tall" \| "large" \| "full"` | — | The size the widget stands at.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `options` *required* | `Options` | — | The widget's options.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+
+##### `WidgetFormProps<Options>`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `options` *required* | `Options` | — | The widget's current options.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+| `change` *required* | `(options: Options) => void` | — | Replaces the options; one step of the draft.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Your own component as a widget](#/dashboard/your-own-widget), [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+
+##### `HeadingOptions`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `text` *required* | `string` | — | The title across the full width.<br>Shown in: [The start screen of a dispatcher](#/dashboard/dispatcher), [Headings that divide the dashboard](#/dashboard/sections), [Arrange the start screen (Scenarios)](#/scenarios/a-dispatchers-day) |
+
+#### Known limits
+
+- A widget's height follows its size, never its content: what does not fit is cut, not grown.
+- Not yet: sections that wrap as a whole, dragging from the catalogue to a chosen place, a height that follows the content in the list form, hiding a widget that has nothing to show, locking one widget ([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)).
+- Never: stacks of widgets that share one place, coordinates and free placement, a layout per breakpoint, dense packing ([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)).
+- Where an arrangement is stored, which default a role gets, several dashboards and what stands in a widget are the application's.
+
+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/dashboard` exports, with its signature. A component's props stand on its own page.
+
+Demo page: https://romanhaendler.github.io/umriss-ui/dashboard/api/
+
+#### Components
+
+##### `HeadingType`
+
+The built-in heading widget type, to put inside `Dashboard` when the
+application wants readers to divide their dashboard: one size, `full`, one
+row, its text as its options, drawn as a title without a card.
+
+```ts
+function HeadingType(): null;
+```
+
+Used on [Scenarios](#/) and [Dashboard](#/dashboard).
+
+##### `WidgetType`
+
+[Dashboard](#/dashboard) – Declares one widget type inside a `Dashboard`. It draws nothing itself: the
+dashboard reads its props. The options type is inferred from `defaultOptions`.
+
+Used on [Scenarios](#/) and [Dashboard](#/dashboard).
+
+#### Hooks
+
+##### `useDashboard`
+
+Declares a dashboard: hands back `Dashboard`, `WidgetType`, the view in
+view, `setView` and the editing actions.
+
+```ts
+function useDashboard({ defaultView, initialView, allowEdit, onViewChange, onDraftChange }: DashboardOptions): DashboardParts;
+```
+
+Used on [Scenarios](#/) and [Dashboard](#/dashboard).
+
+#### Types
+
+##### `DashboardOptions`
+
+Its table stands on [Dashboard](#/dashboard/type-DashboardOptions).
+
+##### `DashboardParts`
+
+Its table stands on [Dashboard](#/dashboard/type-DashboardParts).
+
+##### `DashboardProps`
+
+Its table stands on [Dashboard](#/dashboard/type-DashboardProps).
+
+##### `DashboardView`
+
+Its table stands on [Dashboard](#/dashboard/type-DashboardView).
+
+Used on [Scenarios](#/) and [Dashboard](#/dashboard).
+
+##### `DashboardWidget`
+
+Its table stands on [Dashboard](#/dashboard/type-DashboardWidget).
+
+##### `HeadingOptions`
+
+Its table stands on [Dashboard](#/dashboard/type-HeadingOptions).
+
+Used on [Scenarios](#/) and [Dashboard](#/dashboard).
+
+##### `SizeSpan`
+
+Its table stands on [Dashboard](#/dashboard/type-SizeSpan).
+
+##### `WidgetContent`
+
+Its table stands on [Dashboard](#/dashboard/type-WidgetContent).
+
+##### `WidgetFormProps`
+
+Its table stands on [Dashboard](#/dashboard/type-WidgetFormProps).
+
+##### `WidgetSize`
+
+Its table stands on [Dashboard](#/dashboard/type-WidgetSize).
+
+Used on [Dashboard](#/dashboard).
+
+##### `WidgetTypeProps`
+
+Its table stands on [Dashboard](#/dashboard/type-WidgetTypeProps).