@umriss-ui/dashboard 0.45.0 → 0.47.0

package/dist/index.d.ts

@@ -55,6 +55,11 @@ export declare interface DashboardProps extends HTMLAttributes<HTMLDivElement>,
     /** The `name`s of the widget types the catalogue lists.
      @default every declared type */
     catalogue?: ReadonlyArray<string>;
+    /** The level of the heading the heading widgets stand in - the one that fits the
+     page's outline. A widget's title stands one level below it when the dashboard
+     holds a heading widget, and at this level when not; never deeper than 6.
+     @default 2 */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
 }
 
 /** The arrangement of a dashboard: which widgets, in what order, at which
@@ -74,6 +79,9 @@ export declare interface DashboardWidget {
     size: WidgetSize;
     /** The type's own options, typed through the hook. */
     options: unknown;
+    /** Set by the application, never by the dashboard: the reader can move the widget but not
+     resize it, change its options or remove it. Only `true` locks. Kept through every edit. */
+    locked?: boolean;
 }
 
 /** The options of the heading widget type. */
@@ -135,7 +143,7 @@ export declare interface WidgetTypeProps<Options> {
     sizes: Partial<Record<WidgetSize, SizeSpan>>;
     /** The size a new widget of this type starts at. One of `sizes`. */
     start: WidgetSize;
-    /** The options a new widget starts with. Their type is the options type of `title` and of the content. */
+    /** The options a new widget starts with, and the ones a stored widget's missing keys are read from: stored plain options are spread over them, one level deep. Their type is the options type of `title` and of the content. */
     defaultOptions: Options;
     /** The title of a frame as a function of its options; the `label` without it. */
     title?: (options: NoInfer<Options>) => string;

package/docs/llms-full.md

@@ -1,4 +1,4 @@
-# @umriss-ui/dashboard 0.45.0
+# @umriss-ui/dashboard 0.47.0
 
 > React dashboard for data-dense applications - widgets a reader arranges, packed in order on twelve columns.
 
@@ -277,7 +277,7 @@ function Stage({ shown }: { shown: Case }) {
       </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="old" onClick={() => { parts.cancel(); parts.setView(OLD); setSaid("The stored value named a weather widget whose type is not declared and a trend in a size it no longer offers: the weather widget is not drawn and stays in the stored value, the trend 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>,
@@ -318,7 +318,7 @@ function Stage({ shown }: { shown: Case }) {
       )}
       <div data-callout="4" style={{ overflowX: "auto" }}>
         <div style={{ width: width ?? "100%" }}>
-          <Dashboard aria-label="Dispatch, today">
+          <Dashboard headingLevel={3} aria-label="Dispatch, today">
             <HeadingType />
             <WidgetType
               name="figure"
@@ -578,7 +578,7 @@ export default function Dispatcher() {
     onViewChange: () => setKept((count) => count + 1),
   });
   return (
-    <Dashboard aria-label="Dispatch, today" catalogue={["figure", "trend", "alerts"]} data-draft={open || undefined} data-kept={kept}>
+    <Dashboard headingLevel={4} aria-label="Dispatch, today" catalogue={["figure", "trend", "alerts"]} data-draft={open || undefined} data-kept={kept}>
       <HeadingType />
       <WidgetType
         name="figure"
@@ -671,7 +671,7 @@ export default function YourOwnWidget() {
     },
   });
   return (
-    <Dashboard aria-label="Tours">
+    <Dashboard headingLevel={4} aria-label="Tours">
       <WidgetType
         name="tours"
         label="Tours on the road"
@@ -719,7 +719,7 @@ const VIEW: DashboardView = {
 export default function Sections() {
   const { Dashboard, WidgetType } = useDashboard({ defaultView: VIEW });
   return (
-    <Dashboard aria-label="Sections">
+    <Dashboard headingLevel={4} 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>}
@@ -738,7 +738,294 @@ import { useDashboard } from "@umriss-ui/dashboard";
 
 export default function Empty() {
   const { Dashboard } = useDashboard({ defaultView: { widgets: [] } });
-  return <Dashboard aria-label="Nothing yet" />;
+  return <Dashboard headingLevel={4} aria-label="Nothing yet" />;
+}
+```
+
+##### A widget for one role
+
+A widget type is declared only for the role that may see it. The other role does not draw the widget and does not lose it: the stored arrangement keeps it, and "Done" keeps it after the widgets that are drawn, so it comes back at the end.
+
+```tsx
+import { useState } from "react";
+import { Button, Text } from "@umriss-ui/core";
+import { useDashboard } from "@umriss-ui/dashboard";
+import type { DashboardView } from "@umriss-ui/dashboard";
+
+type Role = "controller" | "dispatcher";
+
+const VIEW: DashboardView = {
+  widgets: [
+    { id: "s1", type: "stock", size: "small", options: { name: "Pallets" } },
+    { id: "c1", type: "cost", size: "small", options: {} },
+    { id: "s2", type: "stock", size: "small", options: { name: "Drivers" } },
+  ],
+};
+
+export default function OneRole() {
+  const [role, setRole] = useState<Role>("controller");
+  const [told, setTold] = useState<string>();
+  const { Dashboard, WidgetType } = useDashboard({
+    defaultView: VIEW,
+    allowEdit: true,
+    onViewChange: (view) => setTold(view.widgets.map((widget) => `${widget.type} ${widget.id}`).join(", ")),
+  });
+  return (
+    <>
+      <Button variant={role === "controller" ? "primary" : "secondary"} onClick={() => setRole("controller")}>Controller</Button>{" "}
+      <Button variant={role === "dispatcher" ? "primary" : "secondary"} onClick={() => setRole("dispatcher")}>Dispatcher</Button>
+      <Dashboard headingLevel={4} aria-label="Dispatch, by role">
+        <WidgetType name="stock" label="Stock" sentence="A stock on hand." sizes={{ small: { columns: 4, rows: 2 } }} start="small" defaultOptions={{ name: "Pallets" }} title={(options) => options.name}>
+          {({ options }) => <Text size="sm">{`${options.name} on hand`}</Text>}
+        </WidgetType>
+        {role === "controller" && (
+          <WidgetType name="cost" label="Cost" sentence="What the week costs." sizes={{ small: { columns: 4, rows: 2 } }} start="small" defaultOptions={{}}>
+            {() => <Text size="sm">Cost this week: 4,820 EUR</Text>}
+          </WidgetType>
+        )}
+      </Dashboard>
+      <Text as="p" size="sm" tone="secondary">
+        {told ? `Told to the application, in this order: ${told}. ` : "The application was told nothing yet. "}
+        {"A widget of a type this role does not declare is not drawn, and \"Done\" keeps it after the drawn widgets, so it comes back at the end."}
+      </Text>
+    </>
+  );
+}
+```
+
+##### An arrangement from an older release
+
+The application keeps its own `{ version, view }` and migrates an older value with a plain function before the dashboard reads it. Three things need no migration of the application's: a type's new option takes its default, a size the type no longer offers falls back to its starting size, and a type that is gone stays in the stored view, not drawn.
+
+```tsx
+import { useState } from "react";
+import { Text } from "@umriss-ui/core";
+import { useDashboard } from "@umriss-ui/dashboard";
+import type { DashboardView, WidgetSize } from "@umriss-ui/dashboard";
+
+/** What an older release stored: its own shape, with the figure's name as `label`. */
+interface StoredV1 {
+  version: 1;
+  cards: ReadonlyArray<{ id: string; kind: string; size: WidgetSize; label?: string }>;
+}
+
+/** What the application keeps now. */
+interface StoredV2 {
+  version: 2;
+  view: DashboardView;
+}
+
+/* The value as version 1 stored it: the trend is larger than it is offered now, the weather type is gone,
+   and no figure has the unit option that the type has since gained. */
+const STORED: StoredV1 = {
+  version: 1,
+  cards: [
+    { id: "a", kind: "figure", size: "small", label: "Orders" },
+    { id: "b", kind: "trend", size: "large" },
+    { id: "c", kind: "weather", size: "small" },
+    { id: "d", kind: "figure", size: "medium", label: "Utilisation" },
+  ],
+};
+
+/** One older value in, the current one out. Nothing else needs to change. */
+function migrate(stored: StoredV1 | StoredV2): StoredV2 {
+  if (stored.version === 2) return stored;
+  return {
+    version: 2,
+    view: { widgets: stored.cards.map((card) => ({ id: card.id, type: card.kind, size: card.size, options: card.label === undefined ? {} : { name: card.label } })) },
+  };
+}
+
+export default function OlderRelease() {
+  const [kept, setKept] = useState<StoredV2>(() => migrate(STORED));
+  const { Dashboard, WidgetType } = useDashboard({
+    defaultView: { widgets: [] },
+    initialView: kept.view,
+    onViewChange: (view) => setKept({ version: 2, view }),
+  });
+  return (
+    <>
+      <Dashboard headingLevel={4} aria-label="Orders and utilisation">
+        <WidgetType
+          name="figure"
+          label="Figure"
+          sentence="One number with its unit."
+          sizes={{ small: { columns: 3, rows: 2 }, medium: { columns: 4, rows: 2 } }}
+          start="small"
+          defaultOptions={{ name: "Orders", unit: "per day" }}
+          title={(options) => options.name}
+        >
+          {({ options }) => <Text size="sm">{`${options.name}, ${options.unit}`}</Text>}
+        </WidgetType>
+        <WidgetType name="trend" label="Trend" sentence="A figure over the last weeks." sizes={{ wide: { columns: 6, rows: 3 } }} start="wide" defaultOptions={{}}>
+          {() => <Text size="sm">Trend over the last weeks</Text>}
+        </WidgetType>
+      </Dashboard>
+      <Text as="p" size="sm" tone="secondary">
+        {`The application keeps version ${kept.version}: ${kept.view.widgets.map((widget) => widget.id).join(", ")}, in that order. A "Done" writes it back in version 2.`}
+      </Text>
+    </>
+  );
+}
+```
+
+##### Controls of a widget's own
+
+A widget's content can start with the application's own controls: a period switch above a chart that fills the rest of the body. The head takes no controls, because it is the grip, it takes the arrow keys and it carries the one menu. The row rests with the content in the editing mode, so arranging is never mistaken for using.
+
+```tsx
+import { useState } from "react";
+import { useChart } from "@umriss-ui/charts";
+import { Button, ButtonGroup } from "@umriss-ui/core";
+import { useDashboard } from "@umriss-ui/dashboard";
+
+/* The values of each period: this week's days and the last month's weeks. */
+const SERIES = {
+  week: [58, 52, 55, 51, 49, 53, 47],
+  month: [56, 58, 52, 55, 51, 49, 53, 47, 52, 56, 60, 57],
+} as const;
+
+type Period = keyof typeof SERIES;
+
+/** A row of the application's controls at the top, the chart in the room left: the content is a column at the body's full height. */
+function Orders() {
+  const [period, setPeriod] = useState<Period>("week");
+  const rows = SERIES[period].map((now, i) => ({ i, now }));
+  const { Chart, XAxis, YAxis, Area } = useChart(rows);
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "var(--u-space-2)", height: "100%", minWidth: 0 }}>
+      <div style={{ flex: "none" }}>
+        <ButtonGroup aria-label="Period" size="sm">
+          <Button variant={period === "week" ? "primary" : "secondary"} onClick={() => setPeriod("week")}>This week</Button>
+          <Button variant={period === "month" ? "primary" : "secondary"} onClick={() => setPeriod("month")}>Last month</Button>
+        </ButtonGroup>
+      </div>
+      <div style={{ flex: "1 1 0", minHeight: 0 }}>
+        <Chart aria-label={`Orders, ${period === "week" ? "this week" : "last month"}`} padding={4} style={{ minHeight: 0, height: "100%" }}>
+          <XAxis value="i" domain="data" grid={false} tickFormat={() => ""} />
+          <YAxis grid tickFormat={() => ""} />
+          <Area value="now" name="Orders" color="var(--u-color-accent)" fillOpacity={0.09} strokeWidth={1.75} />
+        </Chart>
+      </div>
+    </div>
+  );
+}
+
+export default function ControlsInAWidget() {
+  const { Dashboard, WidgetType } = useDashboard({
+    defaultView: { widgets: [{ id: "o1", type: "orders", size: "wide", options: {} }] },
+  });
+  return (
+    <Dashboard headingLevel={4} aria-label="Orders, by period">
+      <WidgetType
+        name="orders"
+        label="Orders by period"
+        sentence="The orders of the week or the month."
+        sizes={{ wide: { columns: 6, rows: 4 }, full: { columns: 12, rows: 4 } }}
+        start="wide"
+        defaultOptions={{}}
+      >
+        {() => <Orders />}
+      </WidgetType>
+    </Dashboard>
+  );
+}
+```
+
+##### A widget every reader keeps
+
+The application marks a widget of the default view as locked. In the editing mode the reader moves it like any other, but cannot remove it, resize it or change its options, and its menu says why. A lock lives in the view, so an arrangement a reader kept before the lock lacks it. The library does not merge the lock in: only the application knows whether a widget a kept view lacks was removed before the lock or must come back. Its function below sets the lock and puts a missing widget back at the start. A size the reader chose before the lock stays, since a lock keeps a size and does not choose one.
+
+```tsx
+import { useState } from "react";
+import { FormField, Select, Stack, Text } from "@umriss-ui/core";
+import { useDashboard } from "@umriss-ui/dashboard";
+import type { DashboardView, WidgetSize } from "@umriss-ui/dashboard";
+
+const SUMMARY = "safety";
+
+/* The figure type, declared once: a summary the kept view lacks starts with the type's starting size and default options. */
+const FIGURE_DEFAULTS = { name: "Figure", value: "0", note: "" };
+const FIGURE = { start: "small" as WidgetSize, defaultOptions: FIGURE_DEFAULTS };
+
+const VIEW: DashboardView = {
+  widgets: [
+    { id: SUMMARY, type: "figure", size: "wide", options: { name: "Safety", value: "0 incidents", note: "Last 30 days" }, locked: true },
+    { id: "orders", type: "figure", size: "small", options: { name: "Orders", value: "128", note: "Today" } },
+    { id: "late", type: "figure", size: "small", options: { name: "Late tours", value: "3", note: "Of 41" } },
+  ],
+};
+
+/* Kept before the lock: the summary is there, unlocked, at a small size, between the other two. */
+const KEPT_BEFORE_LOCK: DashboardView = {
+  widgets: [
+    { id: "orders", type: "figure", size: "small", options: { name: "Orders", value: "128", note: "Today" } },
+    { id: SUMMARY, type: "figure", size: "small", options: { name: "Safety", value: "0 incidents", note: "Last 30 days" } },
+    { id: "late", type: "figure", size: "small", options: { name: "Late tours", value: "3", note: "Of 41" } },
+  ],
+};
+
+/* Kept without the summary at all: it was removed before the lock. */
+const KEPT_WITHOUT_SUMMARY: DashboardView = {
+  widgets: [
+    { id: "orders", type: "figure", size: "small", options: { name: "Orders", value: "128", note: "Today" } },
+    { id: "late", type: "figure", size: "small", options: { name: "Late tours", value: "3", note: "Of 41" } },
+  ],
+};
+
+const KEPT = { "The default view": VIEW, "Kept before the lock": KEPT_BEFORE_LOCK, "Kept without the summary": KEPT_WITHOUT_SUMMARY };
+type Kept = keyof typeof KEPT;
+
+/* The application's function, run before `initialView`: the summary is locked wherever the kept view has it, and a view that lacks it gets it back at the start. */
+function withLock(kept: DashboardView): DashboardView {
+  const widgets = kept.widgets.map((widget) => (widget.id === SUMMARY ? { ...widget, locked: true } : widget));
+  if (widgets.some((widget) => widget.id === SUMMARY)) return { widgets };
+  return { widgets: [{ id: SUMMARY, type: "figure", size: FIGURE.start, options: FIGURE.defaultOptions, locked: true }, ...widgets] };
+}
+
+/* A new dashboard per kept arrangement: `initialView` is read once, so the choice remounts it. */
+function Start({ kept }: { kept: DashboardView }) {
+  const { Dashboard, WidgetType, view } = useDashboard({ defaultView: VIEW, initialView: withLock(kept) });
+  const summary = view.widgets.find((widget) => widget.id === SUMMARY);
+  return (
+    <Stack gap={2}>
+      <Dashboard aria-label="Start" headingLevel={4}>
+        <WidgetType
+          name="figure"
+          label="Figure"
+          sentence="One number with a note."
+          sizes={{ small: { columns: 3, rows: 2 }, wide: { columns: 6, rows: 2 } }}
+          start={FIGURE.start}
+          defaultOptions={FIGURE.defaultOptions}
+          title={(options: { name: string }) => options.name}
+        >
+          {({ options }: { options: { value: string; note: string } }) => (
+            <Stack gap={1}>
+              <Text as="div" size="2xl" weight="semibold">{options.value}</Text>
+              <Text size="sm" tone="secondary">{options.note}</Text>
+            </Stack>
+          )}
+        </WidgetType>
+      </Dashboard>
+      <Text size="sm" tone="secondary">{summary?.locked ? "The summary is locked." : "The summary is not locked."}</Text>
+    </Stack>
+  );
+}
+
+export default function Locked() {
+  const [choice, setChoice] = useState<Kept>("The default view");
+  return (
+    <Stack gap={4}>
+      <FormField label="The arrangement the reader kept">
+        <Select value={choice} onChange={(event) => setChoice(event.target.value as Kept)}>
+          {(Object.keys(KEPT) as Kept[]).map((name) => (
+            <option key={name}>{name}</option>
+          ))}
+        </Select>
+      </FormField>
+      <Start key={choice} kept={KEPT[choice]} />
+    </Stack>
+  );
 }
 ```
 
@@ -766,24 +1053,24 @@ Every move, size, removal, addition, undo, redo, reset, "Done" and "Cancel" is a
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `defaultView` *required* | `DashboardView` | — | The arrangement the application gives a reader who has none of their own.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 2 more |
-| `initialView` | `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), [Arrange the start screen (Scenarios)](#arrange-the-start-screen) |
+| `defaultView` *required* | `DashboardView` | — | The arrangement the application gives a reader who has none of their own.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 6 more |
+| `initialView` | `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`.<br>Shown in: [An arrangement from an older release](#dashboard), [A widget every reader keeps](#dashboard) |
+| `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), [A widget for one role](#dashboard), [Arrange the start screen (Scenarios)](#arrange-the-start-screen) |
 
 ###### Events
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `onViewChange` | `(view: ``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), [Arrange the start screen (Scenarios)](#arrange-the-start-screen) |
+| `onViewChange` | `(view: ``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), [A widget for one role](#dashboard), [An arrangement from an older release](#dashboard) and 1 more |
 | `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), [Arrange the start screen (Scenarios)](#arrange-the-start-screen) |
 
 ##### `DashboardParts`
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `Dashboard` *required* | `(props: ``DashboardProps``) => ReactNode` | — | The dashboard. One per `useDashboard`.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 2 more |
-| `WidgetType` *required* | `typeof WidgetType` | — | Declares a widget type inside `Dashboard`.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 1 more |
-| `view` *required* | `DashboardView` | — | The arrangement in view: the draft while the mode is on. |
+| `Dashboard` *required* | `(props: ``DashboardProps``) => ReactNode` | — | The dashboard. One per `useDashboard`.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 6 more |
+| `WidgetType` *required* | `typeof WidgetType` | — | Declares a widget type inside `Dashboard`.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 more |
+| `view` *required* | `DashboardView` | — | The arrangement in view: the draft while the mode is on.<br>Shown in: [A widget every reader keeps](#dashboard) |
 | `setView` *required* | `(view: ``DashboardView``) => void` | — | Goes to a whole arrangement. Not reported.<br>Shown in: [Arrange the start screen (Scenarios)](#arrange-the-start-screen) |
 | `editing` *required* | `boolean` | — | Whether the editing mode is on.<br>Shown in: [Arrange the start screen (Scenarios)](#arrange-the-start-screen) |
 | `edit` *required* | `() => void` | — | Enters the editing mode. Does nothing where editing is not allowed.<br>Shown in: [Arrange the start screen (Scenarios)](#arrange-the-start-screen) |
@@ -798,8 +1085,9 @@ Every move, size, removal, addition, undo, redo, reset, "Done" and "Cancel" is a
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — | The `WidgetType`s of this dashboard.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 1 more |
+| `children` | `ReactNode` | — | The `WidgetType`s of this dashboard.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 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) |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` | The level of the heading the heading widgets stand in - the one that fits the page's outline. A widget's title stands one level below it when the dashboard holds a heading widget, and at this level when not; never deeper than 6.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 6 more |
 | `ref` | `Ref<HTMLDivElement> \| undefined` | — | Receives the component's root element. From `RefProp`. |
 
 Also takes every attribute of `<div>`.
@@ -808,16 +1096,17 @@ Also takes every attribute of `<div>`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `widgets` *required* | `ReadonlyArray<``DashboardWidget``>` | — | The widgets, in the order they are drawn and read.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 2 more |
+| `widgets` *required* | `ReadonlyArray<``DashboardWidget``>` | — | The widgets, in the order they are drawn and read.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 6 more |
 
 ##### `DashboardWidget`
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `id` *required* | `string` | — | Unique within the view.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) 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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 1 more |
-| `size` *required* | `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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) 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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 1 more |
+| `id` *required* | `string` | — | Unique within the view.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 more |
+| `size` *required* | `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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 more |
+| `options` *required* | `unknown` | — | The type's own options, typed through the hook.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 more |
+| `locked` | `boolean` | — | Set by the application, never by the dashboard: the reader can move the widget but not resize it, change its options or remove it. Only `true` locks. Kept through every edit.<br>Shown in: [A widget every reader keeps](#dashboard) |
 
 ##### `WidgetSize`
 
@@ -827,29 +1116,29 @@ Declares no props of its own.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `columns` *required* | `number` | — | Columns of twelve.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 1 more |
-| `rows` *required* | `number` | — | Rows of the fixed row unit.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 1 more |
+| `columns` *required* | `number` | — | Columns of twelve.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 more |
+| `rows` *required* | `number` | — | Rows of the fixed row unit.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) 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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 1 more |
-| `sentence` *required* | `string` | — | One sentence on what the type shows.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 1 more |
-| `sizes` *required* | `Partial<Record<``WidgetSize``, ``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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 1 more |
-| `start` *required* | `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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) 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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) 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), [Your own component as a widget](#dashboard), [Arrange the start screen (Scenarios)](#arrange-the-start-screen) |
+| `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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 more |
+| `sentence` *required* | `string` | — | One sentence on what the type shows.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 more |
+| `sizes` *required* | `Partial<Record<``WidgetSize``, ``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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 more |
+| `start` *required* | `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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 more |
+| `defaultOptions` *required* | `Options` | — | The options a new widget starts with, and the ones a stored widget's missing keys are read from: stored plain options are spread over them, one level deep. Their type is the options type of `title` and of the content.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 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), [Your own component as a widget](#dashboard), [A widget for one role](#dashboard) and 3 more |
 | `form` | `(props: ``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), [Your own component as a widget](#dashboard), [Arrange the start screen (Scenarios)](#arrange-the-start-screen) |
-| `children` *required* | `(content: ``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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 1 more |
+| `children` *required* | `(content: ``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), [Your own component as a widget](#dashboard), [Headings that divide the dashboard](#dashboard) and 5 more |
 
 ##### `WidgetContent<Options>`
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `size` *required* | `WidgetSize`<br>`"small" \| "medium" \| "wide" \| "tall" \| "large" \| "full"` | — | The size the widget stands at.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Arrange the start screen (Scenarios)](#arrange-the-start-screen) |
-| `options` *required* | `Options` | — | The widget's options.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [Arrange the start screen (Scenarios)](#arrange-the-start-screen) |
+| `options` *required* | `Options` | — | The widget's options.<br>Shown in: [The start screen of a dispatcher](#dashboard), [Your own component as a widget](#dashboard), [A widget for one role](#dashboard) and 2 more |
 
 ##### `WidgetFormProps<Options>`
 
@@ -867,11 +1156,11 @@ Declares no props of its own.
 #### 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)).
+- Not yet: sections that wrap as a whole, a height that follows the content in the list form, hiding a widget that has nothing to show ([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, dragging from the catalogue to a chosen place ([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://github.com/romanhaendler/umriss-ui/blob/dashboard-v0.45.0/docs/adr/0032-what-umriss-is-not.md).
+What umriss deliberately does not build, and why: [ADR-0032](https://github.com/romanhaendler/umriss-ui/blob/dashboard-v0.47.0/docs/adr/0032-what-umriss-is-not.md).
 
 ## API index
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umriss-ui/dashboard",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "description": "React dashboard for data-dense applications - widgets a reader arranges, packed in order on twelve columns.",
   "license": "MIT",
   "author": "Roman Händler",
@@ -54,7 +54,7 @@
     }
   },
   "peerDependencies": {
-    "@umriss-ui/core": "^0.45.0",
+    "@umriss-ui/core": "^0.47.0",
     "react": ">=19",
     "react-dom": ">=19"
   },
@@ -70,7 +70,7 @@
     "typescript": "^5.6.3",
     "vite": "^6.0.0",
     "vite-plugin-dts": "^4.3.0",
-    "@umriss-ui/core": "0.45.0",
+    "@umriss-ui/core": "0.47.0",
     "@umriss-ui/demo": "0.0.0"
   },
   "scripts": {