@elaraai/east-codex-plugin 0.0.0-stage → 1.0.89

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,2260 @@
1
+ ---
2
+ name: e3-ui
3
+ description: "e3 + UI bridge — build interactive, reactive decision surfaces as e3 tasks, authored as JSX. Use when: (1) Declaring UI tasks with ui() (e3 tasks of kind 'ui' producing a UIComponentType), (2) Binding reactive workspace data with Data.bind (read/write/has/commit/discard/status against e3.input / task defs) inside a (Reactive){$ =) …}(/Reactive) block, (3) Staged vs direct edit modes and reviewing pending changes with the (Diff) tag, (4) Graph/ontology editing with the (Ontology) tag, (5) Calling named package functions (e3.function) RPC-style with Func.bind (call/read/status/error/pending/cancel), (6) Wiring a manifest (reads/writes + bound functions auto-derived from a UI task's IR), (7) Interactive causal-experiment surfaces ('did X change Y?') with the (Experiment) tag, generic over a bound dataset's row and driven by e3.function estimators, (8) The Decide loop — Decision.bind unions reasoning-task decision outputs into… See the detailed scope below."
4
+ ---
5
+
6
+ ## Detailed skill scope
7
+
8
+ e3 + UI bridge — build interactive, reactive decision surfaces as e3 tasks, authored as JSX. Use when: (1) Declaring UI tasks with ui() (e3 tasks of kind 'ui' producing a UIComponentType), (2) Binding reactive workspace data with Data.bind (read/write/has/commit/discard/status against e3.input / task defs) inside a <Reactive>{$ => …}</Reactive> block, (3) Staged vs direct edit modes and reviewing pending changes with the <Diff> tag, (4) Graph/ontology editing with the <Ontology> tag, (5) Calling named package functions (e3.function) RPC-style with Func.bind (call/read/status/error/pending/cancel), (6) Wiring a manifest (reads/writes + bound functions auto-derived from a UI task's IR), (7) Interactive causal-experiment surfaces ('did X change Y?') with the <Experiment> tag, generic over a bound dataset's row and driven by e3.function estimators, (8) The Decide loop — Decision.bind unions reasoning-task decision outputs into one handle (shared selection + commit gate), <DecisionQueue> (urgency-sorted queue with evidence/options/judgement/modify facets, Apply/Reject, grouping, an author-bound Slice scope) and <DecisionJournal> (the resolved read-back), (9) The Studio — Studio.component declares a self-contained East UI function (written exactly like a ui() body) with what the palette shows; the pages operators build are one record of Studio.Types.Pages with one patch write; <Studio.Builder> is the builder — the open page's canvas under one toolbar (its status, the history, Desktop · Tablet, Save as template, Preview and Publish), the palette of the listed components and the project's pages before it, the inspector of the selected placement after it, and the publish preview in its place — every gesture a draft, Save one patch on the page, and a publish stamping each placement with the code it goes live with; <Studio.Library> is a project's templates and pages and where new pages start, opening pages in the builder; <Studio.Page> draws one page's live or draft layout with no chrome, (10) Rendering deployed surfaces in a React app with @elaraai/e3-ui-components — <E3Provider> (E3Config: apiUrl, repo, workspace, token, fetch), <ReactiveDatasetProvider> and <UITaskPreview> — over a server, or over an e3 running in the page (e3-web's createWebE3 and its e3.fetch), (11) Queries — operators build typed jq queries over the datasets a surface binds and save them to one record of Query.Types.Saved with one patch write; <Query.Builder> edits the open query as plain-word steps or as jq, checks it as it is edited, runs it on e3 as a one-shot call — or as a split call over the pieces of a dataset larger than one piece, its plan explained — and shows the result as a Table or a tree; <Query.Library> is the saved queries as a gallery of wireframes and where new queries start, opening them in the builder, (12) The Plan — <Plan>, the one planning canvas, always in its builder frame — one toolbar holding every control it has, the banners, the canvas, the footer's counts: heterogeneous rows on ONE shared { time | number | ordinal } axis from three sources — event kinds over records (Schedule.events placed on Schedule.resources, the kinds a Calendar takes), rows laid out by a series list over local data or a Data.bindPaged source and nested from the data's own structure, and read-only rows (Plan.over a dataset, hand-built rows) — its panes optional props — a library (every event kind's templates, the backlog by when it is due, the series a viewer shows and hides, and cards of the author's own whose drop sets a Schedule.patch) and an inspector of what is selected (one event, several, a row at a bucket, or the window's counts; an event kind's own inspector in place of its form) — with key search, links between runs or events, and an editing session — dropped cards and moved or resized runs, chips, tiles and marks as drafts with Undo / Redo and one checked Save — its authoring vocabulary on `Plan` (Plan.axis, Plan.series.*, Plan.over, Plan.eventRef, Plan.library.*, the value builders), (13) The Sheet — <Sheet>, the one planning spreadsheet, always in its builder frame — one toolbar holding every control it has, the banners, the grid with its docked strip, the footer — its panes optional props: a library (templates, columns, the author's cards) and an inspector of the selected row's every field or the author's own; its rows from an e3 record bound with its patch door (the record's entries, one entry's rows or groups with loose rows between them, or a large record a window at a time — Save one patch commit through the record) or the host's (an array, a bind handle, a Data.bindPaged source with a key search); typed columns (dates, quantities with units, register lookups, a directed link between register members, stamped codes), a blank tail that invites the next row, an East-function copilot that fills cells and proposes rows, a slice lens with saved-view tabs, groups with loose rows between them and read-only sub rows, drag and drop, Excel round-trip, and an editing session — drafts checked as they are made, Undo / Redo and one checked Save — its authoring vocabulary on `Sheet` (Sheet.column.*, Sheet.register.*, Sheet.driver, Sheet.group, Sheet.subRows, Sheet.library.*, Sheet.field, Sheet.apply). (14) Calendar — the record-backed scheduling builder in e3-ui: Calendar, Resources and Timeline layouts, bound resource and template records, the event record’s unscheduled backlog, shared Toolbar/Slice/Library/FieldForm/EditSession behavior, and explicit agenda/card actions below 480px. BuilderFrame remains internal. (15) Roster — weekly staffing over bound records, Shifts and People layouts, pure coverage/rules, bounded week reads, shared Slice/Library/Session, atomic Save/Publish and explicit mobile actions. (16) The Flowchart — <Flowchart>, the state-transition flowchart, always in its builder frame — one toolbar (find state, LR · TD, the freshness chip, the slice's rail, and where it edits the history item), the canvas filling main, the footer's counts: states as nodes in ordered phase lanes (the layout derived, no coordinates), H/V-routed transitions, decision triggers and evidence-weighted links, over an e3 record of flows by name (Flowchart.Types.Flows, its value written with Flowchart.values and checked at build — a lone flow is a record of one entry) or the host's flows or one flow (data, the value's type picking the arm — Flowchart.over builds one flow from the host's own tables with row mappers); its library pane's Flows tab (Flowchart.library.flows()) lists the flows by name and opens one, the open flow kept under the flowchart's name, and '+ New flow' starts one, beside state and transition templates (Flowchart.library.states / transitions) and the author's own cards (Flowchart.library.tab), each tab its own bound rows and each card dropped on the canvas — a state template onto a lane, a transition template onto a transition, an author's card where its drop's type says, ⏎ on a card onto the selection; every gesture on the canvas — '+ LANE', a lane renamed (a double-click on its header) or deleted, a state added, edited, moved or deleted, a handle dragged to connect, Del on the selection — one transaction of the open flow's editing session, each flow keeping its own drafts, with Undo / Redo and one checked Save through the record's patch mutation or the host's onApply; its inspector pane, on by default (inspector={false} takes it away) — Details for the state, transition, decision, lane (a click on its header) or several states selected, or the open flow, each through the shared form, a state's or a transition's own Details in its place with inspector={{ state, transition }}, and Issues, each selecting what it names; with selection and path tracing — its types on Flowchart.Types, a row patch from Flowchart.patch.
9
+
10
+ # e3-ui — e3 + UI Bridge
11
+
12
+ `@elaraai/e3-ui` connects **east-ui** JSX tags to **e3** workspaces. You author a
13
+ decision surface as a first-class e3 **UI task** whose reads and writes against
14
+ workspace datasets are tracked in a manifest — so the engine knows what data the
15
+ UI depends on and can re-render reactively. With staged writes, `<Diff>` review,
16
+ and commit / discard, a view becomes a place a user commits a decision with its
17
+ evidence — not a read-only report.
18
+
19
+ The public surface is **JSX tags + platform helpers**, all from one import
20
+ (`@elaraai/e3-ui`): the e3-specific tags `<Diff>`, `<Ontology>`, `<Experiment>`, `<Plan>`, `<Sheet>`, `<Calendar>`, `<Roster>` and `<Flowchart>`, the `Data` and `Func`
21
+ binding helpers, `Studio` and `Query` components, and the `ui()` task factory. Base UI tags (`<VStack>`, `<Text>`,
22
+ `<Stat>`, …) come from `@elaraai/east-ui`. The factories (`Diff.Root(…)`) are an
23
+ implementation detail under `@elaraai/e3-ui/internal` (also the e3-free,
24
+ browser-safe entry for render-only bundles).
25
+
26
+ ## Before writing code — search the example index
27
+
28
+ Every East API has a tested example in the plugin's index — the index IS the
29
+ API reference, printed from each example's IR in TypeScript or python. Before
30
+ writing or changing East code:
31
+
32
+ 1. Call `search_east_examples` for each capability you
33
+ are about to use — `language: "python"` for east-py, `"typescript"`
34
+ otherwise. Summaries come back first: id, signature, the inputs and the
35
+ expected result, a few hundred bytes each.
36
+ 2. Fetch the one or two that match with `get_east_example`
37
+ and pattern your code on them.
38
+ 3. Do not read `node_modules/@elaraai/**` or `*.examples.ts` files wholesale,
39
+ and do not reason from `.d.ts` signatures: the index holds the same
40
+ programs, exact and far cheaper, and the signatures omit the runtime rules
41
+ that make East code correct.
42
+
43
+ Nothing is injected for you; the search is the step.
44
+
45
+ ## Quick Start
46
+
47
+ ```tsx
48
+ /** @jsxImportSource @elaraai/e3-ui */
49
+ import { East, FloatType, variant } from '@elaraai/east';
50
+ import { Reactive, Slider, UIComponentType } from '@elaraai/east-ui';
51
+ import { ui, Data } from '@elaraai/e3-ui';
52
+ import * as e3 from '@elaraai/e3';
53
+
54
+ const threshold = e3.input('threshold', FloatType, variant('value', 50.0));
55
+
56
+ // A UI task: reactive binding to a workspace dataset, no compute-time inputs.
57
+ const dashboard = ui('dashboard', [], East.function([], UIComponentType, (_$) => (
58
+ <Reactive>{$ => {
59
+ const t = $.let(Data.bind(threshold));
60
+ return <Slider value={t.read()} min={0} max={100} onChange={t.write} />;
61
+ }}</Reactive>
62
+ )));
63
+ // Manifest auto-derived: reads [threshold], writes [threshold]
64
+ ```
65
+
66
+ Deploy and run it like any e3 task; the workspace re-renders the component when
67
+ bound datasets change. The pragma `/** @jsxImportSource @elaraai/e3-ui */` makes
68
+ the file JSX-capable (byte-identical runtime to `@elaraai/east-ui`).
69
+
70
+ > `Data.bind` reads live **inside** the `<Reactive>{$ => …}</Reactive>` builder
71
+ > block — there is no inner `East.function`.
72
+
73
+ ## Decision Tree: What Do You Need?
74
+
75
+ ```
76
+ Task → What do you need?
77
+ │
78
+ ├─ Author a decision surface as an e3 task
79
+ │ ├─ Reacts to workspace data only → ui(name, [], fn) + Data.bind
80
+ │ └─ Also takes computed inputs → ui(name, [input], fn) (fn receives values)
81
+ │
82
+ ├─ Read / write workspace datasets from the UI — Data.bind(dataset, options?)
83
+ │ ├─ Read a value → .read()
84
+ │ ├─ Check if set → .has()
85
+ │ ├─ Write a value → .write(v)
86
+ │ ├─ Write + kick dataflow → .writeAndStart(v)
87
+ │ ├─ Current status (variant) → .status() (e.g. .status().hasTag('stale'))
88
+ │ ├─ The binding handle → .binding (pass to <Diff bindings={[…]} />)
89
+ │ └─ Staged mode → { mode: 'staged' } + .commit() / .discard()
90
+ │
91
+ ├─ Read a collection too large to hold whole — Data.bindPaged(dataset, options?)
92
+ │ ├─ One window → .page(offset, limit) (none = in flight; some([]) = exhausted; a failure throws)
93
+ │ ├─ Total elements → .total()
94
+ │ ├─ Key search → .seek(query) (none for an Array source)
95
+ │ ├─ The snapshot it serves → .revision() (the content hash; re-fires when it moves)
96
+ │ ├─ Show a confirmed write → .refresh(none) (or .refresh(some(hash)))
97
+ │ └─ Through a record's index → { index: byStatus, join?: true }
98
+ │ rows arrive in the INDEX's order as `{ik, key, value, row}`
99
+ │
100
+ ├─ Call a named package function (e3.function) from the UI — Func.bind(fn)
101
+ │ ├─ Launch (fire-and-forget, sync-callback safe) → .call(args…)
102
+ │ ├─ Last successful result → .read() (Option(O))
103
+ │ ├─ Lifecycle (variant) → .status() (idle|running|succeeded|failed|cancelled)
104
+ │ ├─ Failure detail → .error() (Option — message/kind/stdout/stderr)
105
+ │ ├─ Spinner boolean → .pending()
106
+ │ └─ Stop waiting → .cancel() (client-side; server still finishes)
107
+ │
108
+ ├─ Review pending (staged) changes
109
+ │ └─ <Diff bindings={[a.binding, b.binding, …]} />
110
+ │
111
+ ├─ Edit a graph / ontology dataset
112
+ │ └─ <Ontology binding={view.binding} /> (OntologyType: NodeType / LinkType)
113
+ │
114
+ ├─ Offer components for operators to arrange on pages (Studio)
115
+ │ ├─ Declare one — self-contained, like a ui() body → Studio.component(key, meta, fn)
116
+ │ ├─ Store the pages operators build → e3.record("pages", Studio.Types.Pages, new Map()) + e3.mutation.patch(pages)
117
+ │ ├─ The builder: canvas, palette, inspector, preview → <Studio.Builder pages components project env? audience? rollout? id? />
118
+ │ ├─ Templates, pages, and where new pages start → <Studio.Library pages components project onOpen? id? />
119
+ │ └─ Show one page, live or draft, with no chrome → <Studio.Page pages components page version? />
120
+ │
121
+ ├─ Let users query the bound datasets and save their queries (typed jq)
122
+ │ ├─ Store the queries they save → e3.record("queries", Query.Types.Saved, new Map()) + e3.mutation.patch(queries)
123
+ │ ├─ Ship queries in the record, checked at build → Query.value({ orders, customers }, [{ name, jq, description?, savedAt }])
124
+ │ ├─ The builder: steps or jq, checked, run, saved → <Query.Builder queries datasets query? id? />
125
+ │ └─ The saved queries, and where new ones start → <Query.Library queries datasets onOpen? id? />
126
+ │
127
+ ├─ Run the Decide loop over reasoning-task decisions
128
+ │ ├─ Union the bound decision views into one handle → Decision.bind([Contract]?, { decisions, judgements })
129
+ │ ├─ The queue (triage → understand → judge → apply) → <DecisionQueue handle={handle} …/>
130
+ │ ├─ The resolved read-back (Decide↔Trust seam) → <DecisionJournal handle={handle} />
131
+ │ └─ Scope the queue (author-owned, Table pattern) → Slice.bind over Decision.Types.Decision, rows = handle.queue()
132
+ │
133
+ ├─ Draw what is scheduled on ONE shared axis — the Plan (see The Plan below)
134
+ │ ├─ Rows derived from data by a series list → <Plan axis={…} data={…} series={[…]} />
135
+ │ ├─ Event kinds over records, on resource rows → <Plan axis={…} resources={{ presses: Schedule.resources(…) }} events={{ job: Schedule.events(record, {…}) }} />
136
+ │ ├─ Read-only rows: a dataset's, or hand-built → rows={[Plan.over(data, [series…]), Plan.chart({…})]}
137
+ │ ├─ Its axis: time, number or ordinal → Plan.axis / Plan.axis.number / Plan.axis.ordinal
138
+ │ ├─ Rows, nested by what the data holds → Plan.series.span / buckets / chart / heat / table / cards / events / group / section / views / rows
139
+ │ ├─ Data too large to hold whole → data={paged}, a Data.bindPaged handle
140
+ │ ├─ Event kinds over records too large to read whole → Schedule.events(record, { window, backlogWindow, entries }) + Schedule.resources(Data.bindPaged(record), {…})
141
+ │ ├─ A link between two runs, or two events → Plan.link({ from: Plan.ref(…), fromRun, … }) / Plan.link({ from: Plan.eventRef(kind, key), … })
142
+ │ ├─ Its library pane: templates, backlog, series, cards → library={[Plan.library.events(), Plan.library.backlog(), Plan.library.series(), Plan.library.tab(rows, {…})]}
143
+ │ ├─ Its inspector pane: what is selected → inspector (+ an event kind's own: Schedule.events(record, { inspector }))
144
+ │ ├─ Event kinds dragged: templates, backlog, moves → built in with resources + events (+ library); canDrop={fn(Schedule.Types.Candidate) => Option<String>}
145
+ │ ├─ Overlap warnings, without dropping overlapping events → Schedule.events(record, { overlaps: "warn" | "allow" }); the chip selects the first pair
146
+ │ ├─ Save each changed event kind through its patch door → applyMode="batch" (default); "auto" commits each ready gesture
147
+ │ └─ Dropped cards and moves as drafts → a series' edit + editing={{ onUpdate | onApply }}
148
+ │
149
+ ├─ Let planners type rows in place — the Sheet, in its frame (see The Sheet below)
150
+ │ ├─ An e3 record edited as a sheet → <Sheet record={…} columns={{…}} /> (record = Record.bind(r, [patch]))
151
+ │ │ ├─ One entry's rows, groups or loose rows → entry={{ key, rows: "field", id: "id" }} (+ group)
152
+ │ │ └─ A large record, a window at a time → window={Data.bindPaged(r)}
153
+ │ ├─ The host's rows → <Sheet data={…} id="id" columns={{…}} />
154
+ │ ├─ Its panes, each optional → library={[Sheet.library.rows(), Sheet.library.columns(), Sheet.library.tab(…)]} · inspector (+ fields)
155
+ │ ├─ Its columns, registers and the driver → Sheet.column.* / Sheet.register.* / Sheet.driver
156
+ │ ├─ Groups, loose rows between them, read-only sub rows → Sheet.group / Sheet.Types.Entry / Sheet.subRows
157
+ │ ├─ Data too large to hold whole → data={paged}, a Data.bindPaged handle
158
+ │ └─ Drafts checked as they are made, one checked Save → onUpdate | onApply, ready, newRow
159
+ │
160
+ ├─ Draw a state-transition or process flow — the Flowchart (see The Flowchart below)
161
+ │ ├─ An e3 record of flows by name → <Flowchart record={…} flow="…" /> (record = Record.bind(r, [patch]), r of Flowchart.Types.Flows)
162
+ │ ├─ The record's value, written as literals → Flowchart.values({ [name]: { lanes, states, links, triggers? } }) (a lone flow: one entry)
163
+ │ ├─ One flow of the host's, an input's value → <Flowchart data={Data.bind(input)} /> (the input's value Flowchart.value({ … }))
164
+ │ ├─ One flow from the app's own tables → <Flowchart data={Flowchart.over(states, { state, links, link, lanes, triggers?, trigger? })} />
165
+ │ ├─ Decision triggers and evidence on the transitions → a flow's triggers, a link's trigger / evidence
166
+ │ ├─ Selection and ⌥-click path tracing → onSelect*, onTracePath (a click on a lane's header selects the lane)
167
+ │ ├─ Its inspector: what is selected, and the open flow's issues → on by default (inspector={false} takes it away); a state's or a transition's own Details → inspector={{ state, transition }}
168
+ │ ├─ Its frame: find state, LR · TD, the rail, the footer → in its frame wherever it is used; give it a box of its own height
169
+ │ ├─ The flows listed by name, one opened, new ones started → library={[Flowchart.library.flows()]} (the open flow kept under `name`)
170
+ │ ├─ State and transition templates, the author's own cards → library={[…, Flowchart.library.states(rows, {…}), Flowchart.library.transitions(rows, {…}), Flowchart.library.tab(rows, {…})]} (each tab its own bound rows)
171
+ │ ├─ A card dropped on the canvas, or ⏎ on it → a state template onto a lane, a transition template onto a transition, an author's card where its drop's type says; ⏎ onto the selection
172
+ │ └─ Edit a flow: lanes, states, transitions — Undo, one Save → record={…}, or data={…} + onApply (every canvas gesture a draft; canConnect vetoes a pair)
173
+ │
174
+ ├─ Render deployed surfaces in a React app (@elaraai/e3-ui-components)
175
+ │ ├─ Which e3, and how requests reach it → <E3Provider config={{ apiUrl, repo, workspace, token, fetch }}>
176
+ │ ├─ The bindings' adapters → <ReactiveDatasetProvider> inside it
177
+ │ ├─ A deployed ui() task, by name → <UITaskPreview task="…" />
178
+ │ └─ e3 running in the page, no server → apiUrl and fetch from e3-web's createWebE3
179
+ │
180
+ └─ Let a user ask "did X change Y?" against a dataset and trust the answer
181
+ └─ <Experiment data configs … /> (generic over the row; runs e3.functions)
182
+ ```
183
+
184
+ ## Core Concepts
185
+
186
+ ### `ui(name, inputs, fn, options?)`
187
+
188
+ Wraps `e3.task()` with `kind: "ui"` and a **manifest** auto-derived from the IR:
189
+ - **Compute-time reads** — every dataset in `inputs` (the runner passes their
190
+ values to `fn` as positional args).
191
+ - **Reactive reads** — every `Data.bind(dataset).read()` / `.has()` in the IR.
192
+ - **Reactive writes** — every `Data.bind(dataset).write()` in the IR.
193
+ - **Bound functions** — every `Func.bind(fn)` in the IR.
194
+
195
+ `fn` returns `UIComponentType`, exactly: `ui()`'s signature takes no other
196
+ function, and refuses one cast past it when the task is defined, naming the
197
+ task and the type. A task is rendered by its `ui` role alone. Default runner
198
+ is `['east-c', 'run']`.
199
+
200
+ > `Data.bind` takes the def itself (`e3.input(...)` or a task), so the bound
201
+ > path and value type are captured at IR-build time by construction.
202
+
203
+ ### `Data.bind(dataset, options?)`
204
+
205
+ A workspace-scoped reactive binding to a dataset — pass the `e3.input` def
206
+ (or an `e3.task`, which binds its output dataset). Handle methods:
207
+
208
+ | Method | Meaning |
209
+ |---|---|
210
+ | `.read()` | current value (type `T`); tracks the dependency so `<Reactive>` re-renders |
211
+ | `.has()` | whether the dataset is set |
212
+ | `.write(v)` | set the value |
213
+ | `.writeAndStart(v)` | set the value and start the dataflow |
214
+ | `.status()` | binding status variant (e.g. `.status().hasTag('stale')`) |
215
+ | `.commit()` | apply staged edits (staged mode) |
216
+ | `.discard()` | drop staged edits (staged mode) |
217
+ | `.binding` | the binding handle to pass to `<Diff bindings={[…]} />` |
218
+
219
+ **Modes** (`options.mode`):
220
+ - `'direct'` (default) — each `write()` immediately mutates the destination.
221
+ - `'staged'` — `write()` accumulates a patch; `commit()` applies it, `discard()`
222
+ drops it.
223
+
224
+ ### `Data.bindPaged(dataset, options?)`
225
+
226
+ A read-only, WINDOWED binding for a collection too large to hold whole — the
227
+ paged sibling of `Data.bind`. There is no `write` / `commit`: a window is not a
228
+ value you can diff or stage.
229
+
230
+ | Method | Meaning |
231
+ |---|---|
232
+ | `.page(offset, limit)` **❗** | one window; `none` while in flight, `some([])` at exhaustion; a failed fetch throws its reason |
233
+ | `.total()` | the source's element count, once any window has landed |
234
+ | `.seek(query)` **❗** | where a key query lands in the source's row order; `none` for an Array source, which has no key order to search |
235
+ | `.revision()` | `Option<String>` — the snapshot every window and search is read from: the dataset's content hash (a record's state hash through an index); `none` while it is found or while the dataset has no value |
236
+ | `.refresh(target)` | move the source: `some(hash)` to that snapshot, `none` to the dataset's current one; returns at once |
237
+
238
+ `Data.bindPaged` is how paged data reaches a component. Pass the handle as a
239
+ `<Plan>`, `<Table>` or `<Sheet>`'s `data`: the component recognises it by its
240
+ East type (east-ui's `Paged.Types.PinnedSource`) and pages it, and nothing else
241
+ produces a paged source — a collection already in hand is local data, passed
242
+ inline. The def is an `e3.input`, an `e3.record`, or an `e3.task`, whose output
243
+ it binds. A dataset too large to hold whole is made where data is made — a task
244
+ that generates or loads its rows — never written into the package as an
245
+ input's value:
246
+
247
+ ```tsx
248
+ // Package side: the rows come from a task, from a small authored count.
249
+ // const units = e3.task('units', [unitCountInput], generateUnits); // Dict<String, UnitRow>
250
+ <Reactive>{$ => {
251
+ const paged = $.let(Data.bindPaged(units));
252
+ return <Plan axis={axis} data={paged} series={series} />;
253
+ }}</Reactive>
254
+ ```
255
+
256
+ Every window, total and search belongs to ONE snapshot, so rows from two
257
+ snapshots never sit side by side. The source follows its dataset: when a
258
+ dataflow run or another user's write changes it, the source moves to the new
259
+ snapshot, and the windows still on screen are fetched again from it — `page`
260
+ reads `none` for each until it lands, so a view holds its last frame while
261
+ `revision()` has changed. Call `refresh` from an event handler after a write the
262
+ view confirmed, to show it without waiting for the move. A failed fetch throws
263
+ rather than reading `none`, so wrap the read in `$.try` to render the failure;
264
+ a read a couple of seconds later fetches it again. A request that can never
265
+ succeed — a dataset that is not a collection, an index the record does not
266
+ declare — keeps throwing until the source moves.
267
+
268
+ **Through a record's index** (`options.index`) the window is the INDEX's order
269
+ rather than the record's, and each row carries what a view needs to render
270
+ without touching the record:
271
+
272
+ ```tsx
273
+ const queue = $.let(Data.bindPaged(plans, { index: byStatus }));
274
+ // rows: Array<{ ik: StatusKey, key: PlanKey, value: Projection, row: Option<Plan> }>
275
+ <Table data={queue} columns={{
276
+ ik: { header: "Status", value: (ik) => ik.status },
277
+ value: { header: "Plan" },
278
+ }} />
279
+ ```
280
+
281
+ Pass the `e3.recordIndex` DECLARATION, not its name: the window's type — the
282
+ index key and the covering projection — comes from it, so the rows are checked
283
+ at compile time. `join: true` reads each entry's row from the record too;
284
+ leaving it off is the point of a covering projection, since the view then
285
+ touches the index's segments and none of the record's.
286
+
287
+ `.seek` takes a `from..to` range as well as a key or prefix, bounding a leading
288
+ prefix of the key's flattened fields — `late, 3..ok` over a `{status, due}`
289
+ index key — which is what a time window or a status band asks for. A range
290
+ names at least one end; open at both it names no run, and the seek refuses it.
291
+ In the search box quoting is the escape: a quoted value is exact, and a `..`
292
+ inside it is text, so `"../config"` finds that key rather than a range.
293
+
294
+ ### Indexed records and shared Slice
295
+
296
+ Declare field indexes with `e3.recordIndex(name, record, { on: [fields...] })`,
297
+ or computed indexes with `key` / `keys`. Their existing declared key types
298
+ supply the controls; do not redeclare those types in Slice. A scalar computed
299
+ key uses the index name as its field; a Struct key supplies named fields in
300
+ key order. `keys` accepts a scalar or a single-field Struct and permits one
301
+ exact member, keeping pages and counts unique by primary ID. Arbitrary
302
+ compound fan-out remains available through `{ index }`; Slice refuses it.
303
+ `Data.bindPaged(record, { indexes: [declarations...] })` carries their field/key
304
+ types and joins rows by default. Bind it with
305
+ `Slice.bindRecord(key, binding, { fields, range, search, initial, presets })`.
306
+ `Slice.rows(slice)` supplies an ordered, pinned source whose entries retain the
307
+ original primary key. Pass it as Plan/Sheet data, or Roster `visiblePeople`,
308
+ or Flowchart `window`, and give the same Slice handle to the component's
309
+ `slice` prop. Existing
310
+ single-index `Data.bindPaged(record, { index, join })` remains separate.
311
+
312
+ Controls come from indexed field types: unit Variant/Boolean/hints become choice
313
+ chips; Strings use prefix suggestions; numbers/dates use typed ranges; Options
314
+ add Unset; Sets permit one exact member. Counts are exact original-record counts,
315
+ pending until known. Only a supported path through one index can combine choices.
316
+ Never filter resident pages or materialize a record to discover its choices.
317
+ Local arrays use `Slice.bind(key, rows, options?)`; neither arm needs a type
318
+ argument for `Slice.rows(slice)`.
319
+
320
+ Calendar event windows preserve overlap with `[from, to)`, including carry-in
321
+ and whole-window spans. Declare `interval: { from: "start", to: "end" }` on an
322
+ index (optional leading `on` fields), choose `range: "start"`, and pass that
323
+ Slice as the event kind's `slice` with primary `entries: Data.bindPaged(events)`.
324
+ Do not combine it with `filter`, `window` or `backlogWindow`. Do not replace it
325
+ with a start-only query or guessed lookback. Optional missing ends are instants;
326
+ an instant at `from` is included and one at `to` is excluded. Backlog remains
327
+ part of the same authoritative record.
328
+
329
+ Sessions retain original-key drafts across paging, narrowing and remount in the
330
+ same UI store. Save includes hidden edits and confirms primary rows at the
331
+ committed revision. A saved row leaving the narrowing produces footer feedback;
332
+ moving off a resident page does not. Slice persistence saves query state, not
333
+ unsaved drafts. Roster still saves weekly assignments and calculates coverage
334
+ over complete staff; its indexed staff query controls visibility only.
335
+
336
+ Search examples: `planRecordIndexes`, `sheetRecordIndexes`,
337
+ `calendarRecordIndexes`, `rosterRecordIndexes`, their Mobile counterparts,
338
+ and `flowchartRecordIndexes` (scalar, compound and membership computed keys).
339
+ Each shows its full reactive bindings and JSX inline.
340
+
341
+ ### `Func.bind(fn)`
342
+
343
+ A workspace-scoped call handle for a named package function
344
+ (`e3.function`) — e3's RPC method. `call(args…)` launches fire-and-forget
345
+ (safe in sync `onClick` handlers); the outcome arrives reactively:
346
+
347
+ | Method | Meaning |
348
+ |---|---|
349
+ | `.call(args…)` | launch with these args; latest-wins if one is already running |
350
+ | `.read()` | `Option(Output)` — last successful result |
351
+ | `.status()` | `idle` \| `running` \| `succeeded` \| `failed` \| `cancelled` |
352
+ | `.error()` | `Option` of failure detail (message, kind, stdout/stderr) |
353
+ | `.pending()` | true while a call is in flight |
354
+ | `.cancel()` | stop waiting (client-side; the server still finishes) |
355
+ | `.binding` | descriptor (`{ name }`) |
356
+
357
+ All handles bound to the same function share one tracked channel — one
358
+ component can launch while another renders the spinner. Functions are
359
+ **bounded** RPC (server deadline + result-size limit); long compute
360
+ belongs in dataflow tasks (`writeAndStart`). Pass the `e3.function` def —
361
+ name, parameter types and return type all come from it, so the binding
362
+ cannot drift from the deployed signature.
363
+
364
+ ```tsx
365
+ // Package side, in scope at authoring time:
366
+ // const forecastFn = e3.function('forecast', East.function([IntegerType, FloatType], FloatType, …));
367
+ <Reactive>{$ => {
368
+ const forecast = $.let(Func.bind(forecastFn));
369
+ const run = $.const(East.function([], NullType, $ => { $(forecast.call(12n, 1.05)); }));
370
+ return (
371
+ <VStack gap="3">
372
+ <Button onClick={run} loading={forecast.pending()}>Run forecast</Button>
373
+ <Stat label="Forecast" value={East.print(forecast.read())} />
374
+ </VStack>
375
+ );
376
+ }}</Reactive>
377
+ ```
378
+
379
+ ### `<Diff bindings={[…]} />`
380
+
381
+ Renders a review of pending changes for any combination of bindings — the
382
+ staged-mode companion for "review before apply" UX. Pass the `.binding`
383
+ accessors.
384
+
385
+ ### `<Ontology binding={view.binding} />`
386
+
387
+ A graph editor (`NodeType` / `LinkType` / `OntologyType`) bound to a dataset, for
388
+ editing typed node/link graphs. Stack a `<Diff>` beside it to surface the pending
389
+ node/link patch.
390
+
391
+ ### `<Experiment data configs … />`
392
+
393
+ An interactive **causal-experiment** surface: an end user asks *"did X change
394
+ Y?"* against a bound dataset and reads a derived, plain-language answer across
395
+ up to four tabs (The answer / Can we trust it? / How much? / Prove it). Generic
396
+ over the dataset's row (like `<Table>`). The bound `configs` list holds the
397
+ **questions** — each a full `ExperimentConfig` plus an optional precomputed
398
+ `result`/`design`; selecting one seeds the working config. **Run** calls the
399
+ single bound `experiment` function; the verdict-first headline, every word,
400
+ colour and bar are derived from the returned numbers — nothing is authored.
401
+ **Commit** appends to the journal.
402
+
403
+ | Prop | Binding | Meaning |
404
+ |---|---|---|
405
+ | `data` | `Data.bind(dataset)` | the rows to experiment on (`Array<Struct<Row>>`) |
406
+ | `configs` | `Data.bind(dataset)` | **required** — the questions (`Array<Experiment.Types.Configuration>`); each may carry a precomputed `result` and/or `design` |
407
+ | `experiment` | `Func.bind(fn)` | optional universal estimator — `(rows, config) → ExperimentResult`; omit when every question is precomputed |
408
+ | `design` | `Func.bind(fn)` | optional — `(rows, config, result, designConfig) → ExperimentDesign` (the "Prove it" trial recipe) |
409
+ | `journal` | `Data.bind(dataset)` | optional committed-experiment log; **Commit** appends |
410
+ | `columns` | — | per-column display config keyed by the row's fields (like `<Table>`), e.g. `{ bond_strength: { label: 'Bond strength', unit: 'MPa', higherIsBetter: true } }` — labels drive every sentence the surface speaks |
411
+ | `subject` | — | the domain noun for a row: `'batch'` (auto-pluralised) or `{ one, many }`; replaces the neutral `record(s)` |
412
+ | `readonly` | — | render without Run / Commit / edit affordances |
413
+ | `defaultTab` | — | initial tab: `'answer'` (default) \| `'trust'` \| `'dose'` \| `'validate'` |
414
+
415
+ ```tsx
416
+ <Reactive>{$ => {
417
+ const data = $.let(Data.bind(batchesInput));
418
+ const configs = $.let(Data.bind(experimentConfigsInput)); // the questions
419
+ const journal = $.let(Data.bind(experimentJournalInput));
420
+ const experiment = $.let(Func.bind(experimentFn)); // (rows, config) → ExperimentResult
421
+ return (
422
+ <Experiment data={data} configs={configs} experiment={experiment} journal={journal}
423
+ columns={{ bond_strength: { label: 'Bond strength', unit: 'MPa', higherIsBetter: true } }}
424
+ subject="batch" />
425
+ );
426
+ }}</Reactive>
427
+ ```
428
+
429
+ The render-contract value types are reached via `Experiment.Types.*`
430
+ (`Experiment.Types.Config` / `.Configuration` / `.Result` / `.Design` /
431
+ `.Verdict` / …, like `Table.Types.*`); the result's honesty `verdict`
432
+ (`causal` / `modest` / `adjustment_insufficient` /
433
+ `non_identifiable_positivity` / `not_estimable`) drives the headline, and the
434
+ two refusal verdicts (`adjusted = none`) render explanatory zones instead of a
435
+ number.
436
+
437
+ ### The Decide loop — `Decision.bind` + `<DecisionQueue>` + `<DecisionJournal>`
438
+
439
+ Reasoning tasks emit decisions as `Array<Decision.Types.Decision>` datasets
440
+ (built with `Decision.make` / `Decision.option` / `Decision.reference` /
441
+ `Decision.judgement`). `Decision.bind` unions the bound views into **one
442
+ per-surface handle** — it owns what no single binding can: the union +
443
+ write-routing by case id, the shared case **selection** (every component on
444
+ the handle stays in sync by construction), and the derived per-case **commit
445
+ gate**. The operator's staged contribution is a judgements dict bound the
446
+ same way.
447
+
448
+ ```tsx
449
+ const roster = $.let(Data.bind(rosterDecisions, { mode: 'direct' })); // source ⊕ patch view
450
+ const orders = $.let(Data.bind(orderDecisions, { mode: 'direct' }));
451
+ const judgements = $.let(Data.bind(judgementsInput, { mode: 'staged' }));
452
+ const handle = $.let(Decision.bind([RosterConstraint], { decisions: [roster, orders], judgements }));
453
+ ```
454
+
455
+ The optional type token is the solution's **constraint contract** (a by-name
456
+ `VariantType` shared with the reasoning task, which `$.matchTag`s injected
457
+ constraints fully typed); omit it for the default primitive op-variant.
458
+ Handle methods: `queue()` (the unioned cases) · `selected()` / `select(id)` /
459
+ `clearSelection()` · `decision()` · `update(d)` (probe edit through the owning
460
+ patch) · `judgement(id)` / `answer(id, promptId, answer)` /
461
+ `addKnowledge(id, text)` / `inject(id, constraint)` · `resolve(id, verdict)`
462
+ (verdict + removal + selection clear) · `commitState(id)` (gated / blocked /
463
+ handoff / ready).
464
+
465
+ **`<DecisionQueue handle={handle} …/>`** — *the* Decide surface: one queue over
466
+ the handle's cases, urgency-sorted with the routine tail collapsed; selecting a
467
+ row expands one facet at a time beneath it; Apply / Reject resolve through the
468
+ handle.
469
+
470
+ | Prop | Meaning |
471
+ |---|---|
472
+ | `handle` | **required** — the `Decision.bind` handle |
473
+ | `heading` | header label (e.g. `"Decisions waiting"`) |
474
+ | `modify` | per-kind probe editor `(decision, update) => UIComponent` — the Modify facet; `update(edited)` writes back through the owning binding |
475
+ | `evidence` | per-decision canvas `(decision) => UIComponent` inside the Evidence facet |
476
+ | `defaultExpanded` | the case shown expanded before any selection (an `Option` — derive from bound data, e.g. a `firstMap`) |
477
+ | `defaultFacet` / `facets` | which facet opens first (`'evidence'` default) / include-list of data facets (`modify` stays callback-gated) |
478
+ | `onApply` / `onReject` | side-effect hooks fired with the decision on resolve |
479
+ | `slice` | author-bound slice handle over the queue (see below) — narrowing applies before the urgency sort whether or not a rail mounts |
480
+ | `affordances` | rail affordances when `slice` is set (default `["filter", "search"]`; `brush` rejected) |
481
+ | `groups` / `groupBy` / `collapsible` | Group-by toolbar: custom label → `(decision) => String` accessors atop built-in Urgency / Kind / None; which opens first; collapsible heads |
482
+ | `maxHeight` / `density` | pinned-header scroll cap / density preset |
483
+
484
+ **The queue's scope is an ordinary author-owned slice** (the `Table` pattern —
485
+ you own the key and config, so scopes are per-surface over one shared handle,
486
+ and shareable with any other component). Bind it over the decision envelope
487
+ with the handle's own union as the rows feed:
488
+
489
+ ```tsx
490
+ const slice = $.let(Slice.bind('ops.queue.slice', handle.queue(), {
491
+ fields: { kind: { label: 'Kind' }, title: { label: 'Title' }, value: { label: 'Value' } },
492
+ search: ['kind', 'title'],
493
+ initial: { kind: ['roster'] },
494
+ }));
495
+ return <DecisionQueue handle={handle} heading="Decisions waiting" slice={slice} />;
496
+ ```
497
+
498
+ Pass `affordances={[]}` to keep the seeded narrowing with **no** rail — an
499
+ invisible author scope.
500
+
501
+ **`<DecisionJournal handle={handle} />`** — the resolved-cases read-back (the
502
+ Decide↔Trust seam): every staged judgement whose verdict is set, newest first —
503
+ the exact complement of the queue. Options: `heading`, `maxHeight`.
504
+
505
+ ### Studio components — `Studio.component(key, meta, fn)`
506
+
507
+ A Studio component is **self-contained**: an East UI function written exactly
508
+ like a `ui()` body, which binds its own data, sets up its own slices and returns
509
+ its UI. Operators arrange components on pages and never rebind or reconfigure
510
+ them, so different data is a different component, and a component's next
511
+ version is a deploy.
512
+
513
+ `Studio.component` returns a `Studio.Types.Component` struct, the way
514
+ `Slice.config` returns a slice config. Call it at module scope or inside an
515
+ East function.
516
+
517
+ ```tsx
518
+ export const salesCount = Studio.component("sales_count", {
519
+ name: "Sales", category: "Display", icon: "receipt", span: 4n,
520
+ description: "Sales recorded so far",
521
+ }, East.function([], UIComponentType, _$ => (
522
+ <Reactive>{$ => {
523
+ const sales = $.let(Data.bind(salesDaily));
524
+ return <Stat label="Sales" value={sales.read().size()} />;
525
+ }}</Reactive>
526
+ )));
527
+ ```
528
+
529
+ | `meta` | Meaning |
530
+ |---|---|
531
+ | `name`, `category`, `icon` | **required** — the palette card's name, the group it sits in, a Font Awesome solid icon |
532
+ | `span` | the span a new placement takes, in columns of 12 (default `12n`) |
533
+ | `description` | what it shows — the inspector's text, under its lock |
534
+ | `frame` | `"card"` (default) draws a tile frame; `"none"` renders bare |
535
+ | `tags` / `collections` | the palette's Filter facets |
536
+ | `deprecated` | hidden from the palette; placements keep rendering |
537
+
538
+ Two fields are derived from `fn`, never written:
539
+ - `reads` — the datasets, functions and records its code binds (`deriveManifest`
540
+ over `fn`); the palette card's meta line and the inspector's data list.
541
+ - `fingerprint` — a SHA-256 of `fn`'s IR in canonical form. The same code
542
+ fingerprints the same wherever it is written; any change to the code changes
543
+ it.
544
+
545
+ A surface lists the components it offers with `$.let([...])`, in palette order,
546
+ and hands the list to the Studio's components, which draw each placement by
547
+ calling its component's function:
548
+ - The surface's `ui()` manifest is the union of its listed components' reads:
549
+ every dataset they bind is reachable, and nothing else.
550
+ - State and Slice keys inside a component are the component's own, so two
551
+ placements of it share them.
552
+ - A placement whose component the list does not hold is a placeholder naming its
553
+ key; a key two listed components share is an error naming it.
554
+
555
+ ### Studio pages — `Studio.Types.Pages`
556
+
557
+ The Studio exports the pages record's type; a solution declares its storage like
558
+ any record, with one write, a patch:
559
+
560
+ ```ts
561
+ export const pages = e3.record("pages", Studio.Types.Pages, new Map());
562
+ export const pagesPatch = e3.mutation.patch(pages);
563
+ ```
564
+
565
+ The builder and the page library bind it with `Record.bind(pages, [pagesPatch])`;
566
+ a published page reads it with `Data.bind(pages)`. The type never depends on the
567
+ components, so a deploy that adds, changes or removes one runs no migration.
568
+
569
+ - `Studio.Types.Pages` is `Dict<Key, Entry>`. A `Key` is `{ project, page }`. An
570
+ `Entry` is a `page` — `{ draft, live }`, `live` being `none` until the first
571
+ publish, else `{ version, page }` — or a `template`, a layout new pages start from.
572
+ - A `Page` is `{ title, cells }`, and a `Cell` is `{ key, row, span, height,
573
+ align, title, component, fingerprint }`: a component's key, where it sits on the
574
+ SnapGrid (rows in the order their keys first appear), and its component's
575
+ fingerprint when it was placed, stamped anew each time the page publishes — so
576
+ a live version's cells hold the code each went live with.
577
+
578
+ Every operator action is one patch commit, computed in East as the diff of the
579
+ one entry it writes: the builder's Save (the page's draft cells), its Publish
580
+ (the live version becomes the draft, numbered one up — 1 the first time — each
581
+ placement stamped with its component's fingerprint) and its Save as template;
582
+ the page library's new page (a template's cells, or none for Blank grid). A
583
+ patch carries what it changes as it was, so a write drafted on a stale page is a
584
+ `conflict`, refused in the words of the screen that wrote it, and nothing is
585
+ overwritten.
586
+
587
+ ### The builder — `<Studio.Builder>`
588
+
589
+ The builder as one component: the open page's canvas under one toolbar, the
590
+ palette before it, the inspector after it, and the publish preview, which
591
+ Preview and Publish open in the canvas's place. Its writes are patches, so it
592
+ takes the record bound with its patch:
593
+
594
+ ```tsx
595
+ export const builder = ui("builder", [], East.function([], UIComponentType, _$ => (
596
+ <Reactive>{$ => {
597
+ const components = $.let([kpiRail, revenueTrend, breakdownBars]);
598
+ const record = $.let(Record.bind(pages, [pagesPatch]));
599
+ return <Studio.Builder pages={record} components={components} project="Ops console"
600
+ env="Staging" audience="Field ops · 24 users" rollout="Immediate" />;
601
+ }}</Reactive>
602
+ )));
603
+ ```
604
+
605
+ - **The canvas.** The open page's draft cells on the SnapGrid's editing canvas —
606
+ a template's cells when a template is open — each placement its component's
607
+ own UI, framed or bare. Every move, resize, drop and removal, and every
608
+ layout edit the inspector asks for, is a draft; the history item undoes,
609
+ redoes, discards and saves, and ⌘Z / Ctrl+Z undo from anywhere in the
610
+ builder. Save is one patch commit on the page; a save another write beat is
611
+ refused, and the history item says the source changed. The selection bar
612
+ names the selected placement: its component's icon and name, its key and
613
+ what its code reads.
614
+ - **The toolbar**, one row: the page's status — `Draft` with an open ring until
615
+ its first publish, `Live` while its draft is its live layout, `Live · edited`
616
+ once they differ, `Template` for a template — the grid chip and the time of
617
+ the last save; the width readout, the zoom, the history item, Desktop ·
618
+ Tablet, Save as template, Preview and Publish.
619
+ - **Save as template** names a template in a popover hanging from its button —
620
+ offering "<page> template" — and saves the open page, as last saved: one
621
+ commit. A name the project holds is refused as it is typed, and one another
622
+ write took first is refused in the popover. While a template is open it is
623
+ disabled.
624
+ - **The palette**, a pane of two tabs before the canvas. Components: every
625
+ listed component but the deprecated, by category, with a search and a Filter
626
+ menu over category, tags and collections; a card shows the component's icon,
627
+ its name, the datasets its code reads and a lock, and drags onto the canvas as
628
+ a placement at its component's span, storing its fingerprint. The component
629
+ the canvas has selected is drawn placed, `ON CANVAS · ×N`, unsaved drafts
630
+ counted; a click selects its first placement. Pages: the project's pages in
631
+ key order with their status (`LIVE · Vn`, `DRAFT · Vn LIVE` or `DRAFT`); a
632
+ click opens one.
633
+ - **The inspector**, the pane after the canvas: the selected placement's name
634
+ and its component's key, with a warning when the component's code changed
635
+ since the page went live; what its code reads, as keypaths
636
+ (`.inputs.sales_daily`); its description, under a lock; and its layout — its
637
+ span, held to its row's room, its row, its height (Auto or a preset in px)
638
+ and where it sits in a taller row. Each edit is one gesture of the canvas's
639
+ session. With nothing selected it says so.
640
+ - **The panes** collapse to rails: the palette's shows its icon, the number of
641
+ components and its name; the inspector's its icon — in the brand while a
642
+ placement is selected — the placement's span (`8/12`) and its name.
643
+ - **The publish preview**, in the canvas's place: a bar — "● Preview", Desktop ·
644
+ Tablet · Mobile (the page 1440, 1024 or 390 px wide at most), the Env pill,
645
+ and Exit, back to the canvas with its drafts as they were; the page as it will
646
+ publish, its unsaved drafts in place; and an aside — "Ready to publish", the
647
+ version it replaces and the one it becomes (`v3 → v4`), the changes since,
648
+ each placement added, removed, moved or resized; a banner saying the
649
+ components' logic is unchanged, or naming those whose code changed since the
650
+ live version; the Audience and Rollout rows; Save as draft, which saves the
651
+ canvas's drafts; and Publish, which saves them first, then commits the
652
+ publish. A page never published is its first version, one live as it stands
653
+ is up to date, and a template is not published.
654
+
655
+ The page open in the builder begins as the project's first; a `<Studio.Library>`
656
+ with the same `id` opens pages in it. The builder fills its parent's height and
657
+ draws no border around itself, so a host frames it or places it bare.
658
+
659
+ | Prop | Meaning |
660
+ |---|---|
661
+ | `pages` | **required** — the record bound with its patch: `Record.bind(pages, [pagesPatch])` |
662
+ | `components` | **required** — the components the surface lists, in palette order |
663
+ | `project` | **required** — the project whose pages it opens |
664
+ | `env` | where the preview publishes to — its Env pill, and "Publish vN to <env>"; omitted, neither names one |
665
+ | `audience` / `rollout` | who sees a published page, and when — the preview's rows; omitted, no row |
666
+ | `id` | names the builder — needed only when one surface holds two, and then given to the page library that opens its pages |
667
+
668
+ ### The page library — `<Studio.Library>`
669
+
670
+ A project's templates and pages, and where new pages start: a component of its
671
+ own, apart from the builder, headerless with one toolbar. A new page is one
672
+ commit, so it takes the record bound with its patch:
673
+
674
+ ```tsx
675
+ <Reactive>{$ => {
676
+ const components = $.let([kpiRail, revenueTrend, breakdownBars]);
677
+ const record = $.let(Record.bind(pages, [pagesPatch]));
678
+ return <Studio.Library pages={record} components={components} project="Ops console" />;
679
+ }}</Reactive>
680
+ ```
681
+
682
+ - **The toolbar**, one row: the search "Search N pages and M templates…", which
683
+ narrows both rows by title; Sort · Name, A to Z (the record's key order) or
684
+ Z to A; the Pages row's Grid · List; and "+ New page in <project>".
685
+ - **The pane**: the projects the record holds and the surface's own, the shown
686
+ one in the brand; the project's pages, each with its status dot — ● live,
687
+ ○ draft — the one open in the builder in the strong ink; the legend at its
688
+ foot. A project's click shows it; a page's click opens it in the builder.
689
+ - **Templates**: Blank grid — the blank page — then the project's templates,
690
+ four across, each a wireframe of its layout, its title and what it places
691
+ ("KPI rail ×2 · Revenue trend"); a click starts a new page from it.
692
+ - **Pages**: two across, each with its wireframe at its start, its title and
693
+ status, how many components it places, and "Open in builder →", which opens
694
+ it in the builder and calls `onOpen`; a dashed card last starts a new page.
695
+ - **A new page** takes a name the project does not hold and a template, or
696
+ Blank grid, in a popover hanging from the New page button — a template's
697
+ card and the dashed card open it there too, their template picked. It is one
698
+ commit; a name another write took first is refused in the popover.
699
+
700
+ The project shown, the search, the order, the Pages row's layout and the
701
+ popover are its own; the page it opens is the builder's, shared by `id`. It
702
+ draws no border around itself.
703
+
704
+ | Prop | Meaning |
705
+ |---|---|
706
+ | `pages` | **required** — the record bound with its patch: `Record.bind(pages, [pagesPatch])` |
707
+ | `components` | **required** — the components the surface lists — what a template's line names |
708
+ | `project` | **required** — the project it shows first |
709
+ | `onOpen` | told when a page opens in the builder, with its key — the host shows the builder |
710
+ | `id` | names the builder whose open page it writes — needed only when one surface holds two builders |
711
+
712
+ ### One page — `<Studio.Page>`
713
+
714
+ One page with no chrome, as everyone else sees it: its layout on the SnapGrid,
715
+ each placement its component's own UI. It reads the record's value and never
716
+ writes it, so a surface built from it holds the record's path and its listed
717
+ components' reads, and no write.
718
+
719
+ ```tsx
720
+ export const opsConsole = ui("ops_console", [], East.function([], UIComponentType, _$ => (
721
+ <Reactive>{$ => {
722
+ const components = $.let([kpiRail, revenueTrend, breakdownBars]);
723
+ const all = $.let(Data.bind(pages));
724
+ return <Studio.Page pages={all.read()} components={components}
725
+ page={{ project: "Ops console", page: "Overview" }} />;
726
+ }}</Reactive>
727
+ )));
728
+ ```
729
+
730
+ | Prop | Meaning |
731
+ |---|---|
732
+ | `pages` | **required** — the record's value: `Data.bind(pages).read()`, or a bound record's `read()` |
733
+ | `components` | **required** — the components the surface lists |
734
+ | `page` | **required** — the page's `{ project, page }` key |
735
+ | `version` | `"live"` (default), the published layout, or `"draft"`, the layout as last saved; a template draws its cells either way |
736
+
737
+ - A frameless component (`frame: "none"`) renders bare; every other placement is
738
+ a tile.
739
+ - A page with no live version, and a key the record does not hold, each draw a
740
+ placeholder that says so.
741
+ - Under a narrow container the tiles stack in row order.
742
+ - A chart that fills (`<Chart height="fill">`) takes a sized tile's height, and
743
+ its natural height in a tile sized by its content.
744
+ - The page draws no border around itself; a solution places it in a layout of
745
+ its own.
746
+
747
+ ### Queries — `<Query.Builder>` and `<Query.Library>`
748
+
749
+ Operators build **typed jq queries** over the datasets a surface binds — as steps
750
+ in plain words or as jq — see them checked as they edit, run them to read the
751
+ result, and save them. A solution declares one record of saved queries, with
752
+ one write, a patch:
753
+
754
+ ```ts
755
+ export const queries = e3.record("queries", Query.Types.Saved, new Map());
756
+ export const queriesPatch = e3.mutation.patch(queries);
757
+ ```
758
+
759
+ `Query.Types.Saved` is `Dict<String, SavedQuery>`, by name. A saved query is
760
+ `{ name, description, program, root, saved_at }`: its program as written (a
761
+ `JqType` tree, never text to re-parse), the `{ name, path }` of each data source
762
+ it reads, an optional one-sentence description — none shows a sentence
763
+ generated from its steps — and when it was saved. It saves only once it checks.
764
+ It holds no types: they are what checking its program against its data sources
765
+ gives. The type never depends on the data sources, so adding one runs no
766
+ migration.
767
+
768
+ To ship queries in the record, write its value with `Query.value(sources,
769
+ queries)`: each query inline, checked against the data sources when the package
770
+ builds, as the builder checks a query it saves. The sources are named as a
771
+ query reads them, each the dataset or task `Data.bind` takes:
772
+
773
+ ```ts
774
+ export const queries = e3.record("queries", Query.Types.Saved, Query.value({ orders, customers }, [
775
+ { name: "Big orders", jq: ".orders | map(select(.total >= 1000))", savedAt: new Date("2026-10-01T09:00:00Z") },
776
+ { name: "Orders by region", jq: ".customers as $c | .orders | group_by($c[.customer_id].region) | map(length)",
777
+ description: "How many orders each region placed.", savedAt: new Date("2026-10-01T09:00:00Z") },
778
+ ]));
779
+ ```
780
+
781
+ A query that does not check fails the build with the checker's words, as do two
782
+ queries of one name and a description over 140 characters. A query's root is
783
+ the data sources it reads, in the order given.
784
+
785
+ ```tsx
786
+ export const builder = ui("query_builder", [], East.function([], UIComponentType, _$ => (
787
+ <Reactive>{$ => {
788
+ const orders = $.let(Data.bindPaged(d.orders)); // large: paged, never loaded whole
789
+ const customers = $.let(Data.bind(d.customers));
790
+ const saved = $.let(Record.bind(d.queries, [d.queriesPatch]));
791
+ return <Query.Builder queries={saved} datasets={{ orders, customers }} />;
792
+ }}</Reactive>
793
+ )));
794
+
795
+ export const library = ui("query_library", [], East.function([], UIComponentType, _$ => (
796
+ <Reactive>{$ => {
797
+ const orders = $.let(Data.bindPaged(d.orders));
798
+ const customers = $.let(Data.bind(d.customers));
799
+ const saved = $.let(Record.bind(d.queries, [d.queriesPatch]));
800
+ return <Query.Library queries={saved} datasets={{ orders, customers }} />;
801
+ }}</Reactive>
802
+ )));
803
+ ```
804
+
805
+ `datasets` is the **root**: a query on this surface reads `.orders` and
806
+ `.customers`, and nothing else. Each name must be a jq identifier and each
807
+ value a `Data.bind`, `Data.bindPaged` or `Record.bind` handle; a surface handed
808
+ none, or a name jq can't read, is refused when it is built. The surface's
809
+ manifest follows: the record, its patch and each bound source.
810
+
811
+ **`<Query.Builder>`** is the builder: one toolbar (the history item, Copy jq,
812
+ Save… and Run ⌘⏎); a pane with three tabs — **Query** (the steps, each a card of
813
+ plain-word slots with its checked shape after it, or the jq in an editor with
814
+ completions and a problems panel; Visual · jq at the top), **Datasets** (the
815
+ bound data sources — a click starts a new query on one) and **Library** (this
816
+ viewer's recent runs and the saved queries — a click opens one); the results
817
+ beside it, a Table or a tree with Download (CSV, BEAST2); and a status line.
818
+
819
+ - Every edit is checked at once, in the browser, and is one undoable gesture of
820
+ the history item; Save commits the query as one patch of its one entry,
821
+ and a save drafted on a changed entry is a conflict, never an overwrite.
822
+ - **Run** checks and translates the query in the browser and runs it on e3 as a
823
+ **one-shot call** over the data sources it reads — or, when the dataset it
824
+ works through weighs more than one piece (16 MiB), as a **split call** over
825
+ that dataset's pieces, which e3 runs as a job of pieces and merges —
826
+ platform-free either way, so a reader can run it. The results' footer says
827
+ which ("One call", "Split call · 24 pieces"), and a click explains the plan:
828
+ the path and why, what each piece runs, how the pieces combine and what runs
829
+ once after them. Opening a saved query runs it; editing never does. Nothing
830
+ else reads data but a slot's summary, and a run's dataset status before it
831
+ plans.
832
+
833
+ | Prop | Meaning |
834
+ |---|---|
835
+ | `queries` | **required** — the record bound with its patch: `Record.bind(queries, [queriesPatch])` |
836
+ | `datasets` | **required** — the data sources a query may read, by the names it reads them: `{ orders, customers }` |
837
+ | `query` | the saved query it opens first, by name; omitted, a new query on the first data source |
838
+ | `id` | names the builder — needed only when one surface holds two, and then given to the library that opens queries in it |
839
+
840
+ **`<Query.Library>`** is the saved queries, and where new queries start: one
841
+ toolbar (the search over names, descriptions and data sources; Sort · Recent or
842
+ Name; Grid · List; "+ New query on <data source>"); a pane of the data sources
843
+ with their counts, and Recent; and a gallery, each card a wireframe of its query
844
+ — its source and a bar per step — with its name, its description, "orders · 5
845
+ steps · up to 10 orders · saved Tue" and "Open in builder →". It reads no
846
+ dataset: a card draws a query, never its data. A query opens in the builder that
847
+ shares its `id`, and its card drags onto it. A query whose data sources aren't
848
+ bound here says why and doesn't open.
849
+
850
+ | Prop | Meaning |
851
+ |---|---|
852
+ | `queries` | **required** — the record bound with its patch |
853
+ | `datasets` | **required** — the same data sources the builder reads |
854
+ | `onOpen` | told a query's name when it opens one in the builder — the host shows the builder |
855
+ | `id` | names the builder whose open query it writes — needed only when one surface holds two builders |
856
+
857
+ Neither draws a border around itself; each fills its parent's height.
858
+
859
+ ### The Plan — `<Plan>`
860
+
861
+ `<Plan>` is the planning canvas, and there is one (#1191): ONE shared axis —
862
+ time, number or ordinal (#631) — over heterogeneous rows (state-runs,
863
+ allocation lanes, chart measures, heat, bucketed numerals, shift chips, event
864
+ marks), each named by a typed id, with slice / key-search / series-library
865
+ chrome, an editing session (every dropped card, move and resize a draft,
866
+ #880 / #825) and paged sources. It renders in its builder
867
+ frame wherever it is used (#1193): one toolbar holding every control it draws
868
+ outside its canvas, the banners, the canvas in main, and the footer. Its rows
869
+ come from three sources, in this order down the canvas:
870
+
871
+ - **event kinds over records** — `resources`, the rows, and `events`, the
872
+ kinds placed on them: `Schedule`'s, the very values a Calendar takes, each
873
+ kind a record of its own bound with its patch mutation;
874
+ - **`data` and its `series`** (or `pick`) — a keyed source's entries, laid out
875
+ by the series list and nested from the data's own structure, on any axis; a
876
+ `Data.bindPaged` handle is its `data` as readily as a collection in hand;
877
+ - **`rows`** — hand-built rows and `Plan.over(data, [series…])`, read only.
878
+
879
+ A Gantt is a Plan with span rows, a Planner a Plan with bucket rows, an
880
+ AlignedStack a Plan mixing chart / heat / table rows on the shared axis
881
+ (#571). Reach for it for anything scheduled on ONE shared axis — calendar
882
+ time, a numbered day / shift / distance, or an ordered list of phases — with
883
+ mixed row kinds, nesting to any depth, a paged source, rows addressed by
884
+ stable ids, or events kept in records of their own.
885
+
886
+ The tag and its authoring vocabulary — `Plan.axis`, `Plan.series.*`,
887
+ `Plan.children`, `Plan.ref`, `Plan.over`, `Plan.eventRef`, the value and cell
888
+ builders, `Plan.Types` — come from `@elaraai/e3-ui`, its event and resource
889
+ kinds from `Schedule`, and the tags around it from `@elaraai/east-ui`. It
890
+ moved here from east-ui (#1177) and is one tag (#1191): a surface that wrote
891
+ east-ui's `<Plan>`, or `<Plan.View>`, imports `Plan` from `@elaraai/e3-ui` and
892
+ writes `<Plan>`, its props as they were. Its words in React —
893
+ `PlanMessagesProvider` and `planMessages` — are `@elaraai/e3-ui-components`'.
894
+
895
+ ```tsx
896
+ /** @jsxImportSource @elaraai/e3-ui */
897
+ import { Plan } from '@elaraai/e3-ui';
898
+ // … the series list and the axis, as below …
899
+ return <Plan axis={axis} data={rows} series={series} />;
900
+ ```
901
+
902
+ ```
903
+ <Plan axis={Plan.axis({…})} data={rows} series={[Plan.series.span(Row, {…}), …]} /> — the planning canvas: ONE shared axis — { time | number | ordinal } (#631): a UTC window ÷ resolution, a numeric window ÷ step, or an ordinal list = n bucket columns — over heterogeneous rows — the eight row kinds: span state-runs, bucket allocation lanes, chart measures, heat cells, bucketed table numerals, cards shift chips, event marks, and group strips — sliced, searched and picked as one surface. Rows derive from `data` through `series` as an ordered STREAM (#822): the series list IS the layout (one contiguous block per series, top to bottom), a parent is followed by its subtree, and hierarchy comes only from the data's own nesting — never from a field value. Every row carries a typed id, `Plan.Types.RowId` = { series, path } (the series that made it and the entry keys that lead to it; `Plan.ref` builds one), which every callback reports and `links` address. Nothing behaves differently because `data` is inline or paged
904
+ ├─ The frame (#1193): ONE toolbar holding every control the Plan draws outside its canvas, in this order — the slice's narrowing (cohort · filter · search), the scope badge, the key search, Expand/Collapse all, the shared date navigator (or numeric Slice range), the configured resolution, the diagnostics; at its end the summary line, the overlaps chip and the history item (a Plan with none of them has no toolbar). It is one row at every width: the rail folds first, then the summary shortens, the resolution folds into a menu and Expand/Collapse all keeps its icon, the summary hides, the key search folds into its icon (which opens the box in a popover, the focus in it), then the time-axis view controls share the date popover, and the history item folds last, to its buttons; on a touch screen every control there is a 44px tap target. The banners — each session's, an event kind's titled with its name (#1194): a Save's conflict, a refusal, an unknown outcome with Retry, a source out of date with Discard. Main — the canvas: the horizon, the ruler, pinned rows and the rows. The footer — the counts: the event kinds' events in the window, their backlog, the changes pending and when an event kind's record was last saved; then the author's `footer` and the transport line. ⌘Z undoes and ⇧⌘Z redoes from anywhere in the frame; a field being typed into keeps its own undo. The Plan draws no border
905
+ ├─ Props:
906
+ │ ├─ axis (required) — ONE of three kinds; every element instant on the canvas must ride its arm. The kind is also a TYPE: `Plan.axis.number(…)` fixes the tag's `K`, every builder result carries the kind its instants' STATIC types imply (a `DateTimeType` accessor ⇒ `"time"`, a `FloatType` field ⇒ `"number"`, `Plan.at.ordinal(…)` ⇒ `"ordinal"`), a series collects its elements' kinds, and a series (or literal row) on another arm FAILS TO COMPILE at the tag — no wire change, the brand is phantom. Kind-erased values (a stored record, an `Expr<Plan.Types.Instant>`, an East-mapped element list, a `$.let`-bound axis or `$.const`-bound series list, chart rows) constrain nothing at compile time and are held to the axis at render — a row on another arm is a render-time diagnostic naming the row and the arm, never a silent misplacement. Plan.axis({ window?, resolution, resolutions?, now?, format? }) — the TIME shorthand (= Plan.axis.time): half-open [min, max) UTC window; omit window ⇒ the bound slice's datetime range — there is NO fit to the data (#822): a canvas that neither states a window nor binds a slice is refused, at build when the axis is written in the tag, else as the render-time NO WINDOW diagnostic (a bound or stored axis); `resolutions` lists the WEEK/DAY segment options; `now` draws the observed/plan divider; `format` overrides tick labels (date tokens; defaults: week ⇒ "W27", day ⇒ "MON"); at a resolution coarser than a row's data a bucket shows ONE value per row — the fold of those in it (#824) · Plan.axis.number({ window?, step, now?, format? }) — a numeric window ÷ `step` (bucket edges on whole steps; omit window ⇒ the bound slice's float / integer range, under the same no-fit rule; `format` a Chart.format.* spec; no resolution segment — step IS the declaration) · Plan.axis.ordinal({ values, now? }) — the declared values ARE the buckets, in order (the list is the window: no slice range, no brush, the window keys idle; an unlisted value positions nowhere; an interval END names its LAST bucket, inclusive)
907
+ │ ├─ data (required unless `events` or `rows` — a Plan with no rows from any source is refused at build) — a KEYED collection: a `Dict<K, R>` value/expression for the inline arm, or a `$.let`-bound `Data.bindPaged(…)` handle for a WINDOWED arm, recognised by its East type: `pinned` when it names its snapshot, which `editing.onApply` needs; `paged` when it is the shape a UI exported before `revision` / `refresh`, which names none. Any key type `K` — a row's path starts with its entry's key, a String as it is, any other key as its `.east` text (`3`, `(hall="H1", bin=3)`) — and any entry type `R`: a struct, a `RecursiveType` node, or a collection (a `groupToDicts` group). A positional collection is refused — key it at the call site with `rows.toDict((_$, r) => r.id)`. A paged canvas pages by PARENTS (#823): a window is N top-level entries, each with its whole subtree, so a parent never straddles two windows and its bands, means, subtotals and member count are exact — nest children in the source, and group a flat paged source in its dataflow (a group is one entry holding its members; a parent is bounded by a page). Each top-level series is a BLOCK, exactly as inline: a paged canvas pages every block on its own over the same windows (its own bands and resident run; one read of a window serves every block), draws a section's header and hand-built rows once (FIXED blocks), and rebases only the block a far jump lands in; a window landing above the rows in view at a height its estimate missed moves the scroll, never the rows. A paged source may serve SHORT windows (e3 trims pages of wide entries to a byte budget) and the canvas still reads WHOLE ones — its derived source re-requests what a trimmed page left out. When the source's `revision()` moves (`Data.bindPaged` follows each write to its dataset), the canvas re-reads its resident windows at the new snapshot IN PLACE: the rows on screen stay until theirs land (no remount, no empty frame), the scroll position holds, and a standing key search is asked again at the new snapshot, its text kept and the view where it is (its matches named rows of the old one, #1199)
908
+ │ ├─ series (required unless `pick`) — the row recipes over `data`; the list IS the layout (#822): each series contributes one contiguous block, top to bottom in declared order, its rows in source order, each parent followed by its subtree. Data series: Plan.series.span/buckets/chart/heat/table/cards/events(Row, { key, title, subtitle?, icon?, keyType?, match?, label, id?, stacked?, sub?, value?, status?, expand?, children?, collapsed?, edit?, …kind fields }) — every accessor receives (entry, key); a `RecursiveType` entry arrives as its node. What a gesture WRITES is declared on the series (#880): `edit: { items: "jobs", create: (drop, entry, key) => item }` (span / buckets / cards / events) names the entry's `Array` field a dropped card joins and builds the item from the `Plan.Types.Drop` — see `editing`. Naming the item's `String` key field and its instant fields as well — `edit: { items: "jobs", key: "key", start: "start", end: "end" }` (span / cards) or `{ items, key, at }` (buckets / events) — makes its runs, chips, tiles and marks MOVE, and its runs and chips RESIZE (#825): an element's key is its item's key — its identity across every row it can move to, since a row's list keeps its keys unique (a card or a move that would repeat one is refused, the drag showing ⊘) — an instant field is a `DateTime`, a `Float` / `Integer` (number axis), a `String` (ordinal) or a `Plan.Types.Instant`, and `create` becomes optional. `children` nests, to any depth: a bare accessor `(r) => r.children` walks more of THIS series (a recursive entry's own children), `Plan.children(of, [series…])` steps down to a child collection of another entry type (an `Array` in data order, a `Dict` in key order — its series laid out like a top-level list), an array of step-downs gives several child collections in order (a gesture on a nested row writes back through them, so where a series below takes gestures they read a FIELD of the entry — `r => r.children`, `Plan.children(r => r.presses, …)` — or are the entry itself, `g => g`; a computed collection is refused at build); `collapsed: true | (r, k) => …` is a parent's initial state. A parent derives exactly, because its whole subtree rides in its entry: span bands over the subtree's runs (`rollup` "union" | "byStatus" | "sum"; a band sums its runs' quantities unit by unit — the unit rides each `Plan.quantity`), a heat parent with no cells of its own the children's per-bucket `aggregate` (default "mean") painted on its `scale` ({ min?, max?, warnAt? }; default the scale its members share), a table parent with no values per-position subtotals (`aggregate` default "sum", `format`) — each summarising what its children SHOW, their values already folded to the resolution · Plan.series.group(Row, { key, title, label, children, summaryAggregate?, summary?, collapsed? }) — one strip PER ENTRY, its members the entry's children (derived member count; collapsed it rests as its summary strip — explicit `summary` cells OR a `summaryAggregate` of the members' heat cells, never both) · Plan.series.section(Row, { key, title, collapsed?, meta?, value?, status?, summary?, summaryAggregate? }, [series…]) — a fixed titled block over series (it adds no path segment; its header's id is `Plan.sectionRef(key, …parentPath)`) · Plan.series.views(Row, { key, title, match?, children?, collapsed? }, [series…]) — ONE entity shown several ways: one row per member series per entry, ADJACENT and in declared order (a member's own `match` decides whether its row shows; members declare no `children`), the entry's children following its view rows under the first — more of the views' own entries too (a bare accessor), each drawn as the members' rows, to any depth, a span member's `rollup` rolling them up — and a seek on the entry landing on its first view row · Plan.series.rows(Row, identity, rows) — hand-built rows (the kind factories below) placed as one block. Series keys are unique across the WHOLE series tree — a repeat is a build-time Error naming both sites (a list bound as an East value is checked at render: a repeated id draws as a row diagnostic, never a silent drop). There is no `groupBy`: to group a flat source, reshape it first — inline, one `groupToDicts` in the canvas function (`rows.groupToDicts(($, r) => r.hall, ($, _r, k) => k)`, entries `Dict<String, Row>` whose key is the group); a paged source in the dataflow. A source keyed by another type (`Dict<Integer, R>`) works with series whose accessors ignore the key; one that reads it declares `keyType` and, bound as a list, types it `Plan.Types.Series(R, KeyType)`
909
+ │ ├─ pick (optional, exclusive with `series`) — Plan.pick(key, allSeries, { hidden? }): the bound series library — the toolbar has no Series button (#1193): the library pane's Series tab (#1195, when `library` lists `Plan.library.series()`) lists the series by title, subtitle and kind icon in the list's order (that order is the canvas layout); hidden series drop from the canvas (a hidden section, group or views takes its whole block); there are no row counts (#822 — a count means something only with every entry in hand); a pick is STATE, so the Plan must sit inside a <Reactive>
910
+ │ ├─ resources + events (optional) — event kinds over records (#1191), `Schedule`'s — the very values a Calendar takes: `resources={{ presses: Schedule.resources(rows, { name, icon, label, … }) }}` are the rows events are placed on, in this order — `rows` a `Dict`, or a `Data.bindPaged` read of one, which pages the kind (#1199, see Large records, a window at a time) — and `events={{ job: Schedule.events(Record.bind(jobs, [jobsPatch]), { name, icon, title, start, end | at, resource: { field, of }, … }) }}` the kinds, each a record of its own committed through its patch mutation. Their rows come first, then `data`'s, then `rows`'. Each resource kind is a block (#1192): every resource a row per way the kinds placed on it draw — bars, tiles, chips, marks, in that order — then its `measures`, under its `group` strips and nested by its `parent`; a row's id is `entry { series: "<slot>.<draw>", path: [group?, …parents, key] }`, an element's key its event's `Schedule.Types.EventRef` as East prints it, and an event no resource holds draws on its kind's Unassigned row after every resource kind. The rows are read over the window the canvas draws, and read again when a record commits. Each kind is a session over its record, under ONE history with `data`'s (#1194): every gesture one transaction, drawn as Save would leave it; Undo and Redo (the history item, ⌘Z / ⇧⌘Z / ⌘Y anywhere in the frame but a field being typed into) step through the gestures in the order they were made, whatever their kind; Discard drops every kind's drafts; Save commits each kind with a change as one patch through its patch mutation, checked against what its drafts began from — one kind's conflict, refusal or unanswered write (Save turns into Retry, the same request) leaving the others' commits, each kind's banner titled with its name. Their events drag (#1196), each gesture one step of that history: a template from the library's Events tab, or an unscheduled event from its Backlog tab, drops on a resource's row at the bucket under the pointer — the template's event made under a new key for its duration (from its `at` on a day or longer) and selected, the backlog event scheduled for its own; an element moves along its row or onto another resource's row, writing the resource field, a selected element moving the selection with it, and a bar's or a chip's edge resizes it, never shorter than one snap; an event dropped on the Backlog tab is unscheduled (a kind whose times are Options); the ghost says what lands where (`Brochure run · Press A1 · Mon, Oct 12, 2026`) or, in red, why not (`Needs presses`, `canDrop`'s message); and an element of an event its drafts changed wears the brand tint in a brand border. An event is scheduled in time, so event kinds on a number or ordinal axis are refused at build, naming the axis and the kinds (an axis held in a variable is refused in the same words as the Plan is evaluated); `resources` without `events`, and a kind's `resource` naming a slot `resources` has not, are refused too. `applyMode` ("batch" default | "auto") says when the kinds' drafts go — on Save, or each ready gesture as it lands; `data`'s session takes `editing.mode` — and `date` the date brought into view first
911
+ │ ├─ rows (optional) — read-only rows after the event kinds' and `data`'s: hand-built rows (`Plan.chart({ … })`, `Plan.span({ … })`, …) and `Plan.over(data, [series…])`, series over a dataset — a keyed collection, or a `Data.bind` handle over one — which refuses a series declaring `edit` at build (a Plan's edits go through its event kinds and `data`'s session). Each is a FIXED block, drawn once on a paged canvas; a `pinned` row sits under the ruler. Their instants ride the axis's arm, or the tag fails to compile
912
+ │ ├─ library (optional, #1195) — the start pane's tabs, in order, each a `Plan.library.*` call: `events()` — every event kind's templates, under the kind's name and then the template's group; `backlog()` — every event kind's unscheduled events, grouped by when they are due (this week, overdue included; next week; later; no date — UTC weeks from the axis's `now`, else from when the Plan mounted); `series()` — `Pick.Panel`'s list of what a viewer can hide, in the order the canvas draws it: each resource kind and its measures, the event kinds, `data`'s picked series and the Plan's `rows` — hidden per viewer under the Plan's `id`, and only while the tab is listed; `tab(rows, { name, icon?, label, meta?, group?, drop? })` — a card per row of a `Dict<K, R>` (accessors `(row, key)`), searched by key, label and meta, a click selecting one; each card drags onto the rows of `data` whose series makes an item of a card (`edit.create`), the Plan taking its own panel's cards with no `id` or `sources` (#1259), and with `drop: (row, key) => Schedule.patch(KindRowType, …)` onto an event, the patch's type naming the event kind it lands on — the patch set on the event under the pointer as one step (#1196), refused between events and on another kind's. The Backlog tab reads every kind's drafts, so a card scheduled leaves it and an event unscheduled joins it at once. Left out, or empty, no library pane. Collapsed, the pane is a rail with the backlog's count, or the first tab's. A tab listed twice, the Events or Backlog tab with no event kinds, the Series tab with nothing to hide, and a `drop` over no event kind's row type (or one two kinds share) are refused at build, naming the tab
913
+ │ ├─ inspector (optional, #1197) — the end pane: what is selected on the canvas. An event kind's element — a bar, tile, chip or mark — selects its event and its row on a click, Shift / ⌘ / Ctrl adding it to the selection or taking it out, and wears the brand's ring while it is selected; a row's name or plot selects the row, the plot's click naming the bucket under the pointer; Esc clears it all. One event shows its kind, title, when it runs and status, its facts (resource, start and end or its instant, lane, state, quantity), its kind's form over `fields` — or the kind's own inspector, `Schedule.events(record, { …, inspector: (row, update) => UIComponentType })`, in its place — then Duplicate and Delete; several, how many, each kind's count, the list and the bulk edit (state, resource, a shift of a day or an hour); a row, its resource's name, lines and group, its events in the window and its measures at the named bucket; nothing, the window's counts and three hints. Its edits are each one transaction of the Plan's history (#1194): a field of the form — tinted while the record holds it otherwise — the kind's own inspector's `update`, Duplicate (copies under new keys, then selected), Delete, and the bulk edit over every selected event that takes it, across kinds. Refused on a Plan with no event kinds
914
+ │ ├─ links (optional) — [Plan.link({ key, from: Plan.ref(series, …path), fromRun, to: Plan.ref(…), toRun, quantity?: Plan.quantity(34, { unit: "k sheets" }) })] run-edge quantity ribbons, their ends named by row id (a `views` entry's chart row and its span row are two different ends); an end may instead be an event — `from: Plan.eventRef(kind, key)`, no `fromRun` — drawn wherever the event is, and a link naming a kind `events` has not is refused at build (one whose kind is not known there — a list held in a variable or built in East, or an event end held in a variable — as the Plan is evaluated); rows an edge touches carry the links-focus control, always shown at the end of the row's gutter line and pressed while its focus is open (it gathers the transitive upstream/downstream family; unrelated rows collapse to 11px rails / ⋯ gap bands — never removed). In the focus each link is an arrow out of its source's end and into its destination's start, each as it draws — a bar at least the narrowest, a chip and a tile's cell in by their inset, a mark across its glyph: an S where the gap between them allows, else a loopback between the rows; on one row a feed, or a runoff. Nothing of it leaves the plot: a destination at the plot's start is entered from above or below, a source at its end lifts off its edge, an end past the window lands in a dashed slot on the plot's edge, and an end out of view meets the view's edge in a stub. Its quantity's third of the family's largest sets its weight — 2, 4 or 8, and 1.5 with no quantity — over a casing of the paper, and the quantity's caption — its `text`, else its value through its `format`, then its unit — prints on a paper knockout and is its tooltip; a link with no quantity says nothing. A click on a link reports the `link` element ref ({ key, from, to }) and opens the root's popover for it
915
+ │ ├─ popover / hover (optional) — generalized element resolvers fn(Plan.Types.ElementRef) => Option<UIComponent> over EVERY element (run / event / chip / mark / cell refs, each carrying the row's id — compare with `East.equal(ev.row, Plan.ref(…))` — and link refs { key, from, to }, a ribbon belonging to no one row); resolved lazily at click/hover time — a `none` result opens nothing
916
+ │ ├─ expandRender / expandGutter (optional) — the R2 expand-in-place renders fn(Plan.Types.RowId) => UIComponent for rows declaring `expand` (per-row DATA: `{ height?: "168px", axis?: "keep" | "dim" | "off" }` — the render's height, and whether the shared grid + now-line run through it, wash to 40%, or hide inside that row); the focused row GROWS to hold the render (its marks keep their band at the top, its gutter cell grows with it and takes `expandGutter`); every other data row compresses to a 16px strip — never removed: bars / tiles / chips shrink to 7px marks, chart and table rows re-encode as a tone strip, event marks keep their silhouette; a strip click or Esc returns
917
+ │ ├─ editing (optional) — the editing session (#880), the Sheet's (#879) over the source's TOP-LEVEL entries: { onApply? | onUpdate?, onPatch?, mode?, ready? }. Every dropped card, move and resize drafts the entry its row came from (a gesture on a nested row drafts the entry its whole subtree rides in), drawn at once where it was made — the entry's rows derived again, marked pending, or incomplete / invalid while a check refuses that entry — each gesture ONE undoable transaction. The history item (issues · Undo · Redo · Discard · Save, and its status line) ends the frame's toolbar; ⌘Z / Ctrl+Z undo, ⌘⇧Z / Ctrl+Shift+Z / Ctrl+Y redo. `onApply` fn(Editing.Types.ChangeSet(R, K)) => Editing.Types.ApplyResult (sync or async) commits one checked batch against the base the drafts began from — the inline `Dict`'s snapshot, or a paged source's revision (a paged `onApply` needs the source's `revision` and `refresh`): a batch against a source that moved is refused, never rebased, and a banner says "Source changed — review or discard these drafts"; a Save that throws leaves the outcome unknown, and the banner's "Retry request" resends the SAME request (dedupe by its `requestId`); drafts retire only when the source reads back at the committed revision. `onUpdate` fn(Dict<K, R>) => Null is the inline adapter instead (exclusive with `onApply`): pass `data={handle}` and `onUpdate={handle.write}`, and each batch applies with `Editing.apply` over the handle's LATEST `Dict` and writes the whole result once — idempotent across retries. `onPatch` fn(Plan.Types.PatchEvent(R)) => Null hears every gesture (origin drop / move / resize / undo / redo / discard). `mode` "batch" (default — Save sends) | "auto" (each ready gesture goes at once). `ready` fn(R, K) => Editing.Types.Readiness checks a drafted entry — a refusal names the entry and holds Save (a check that throws refuses its own entry only). Without `editing` the canvas takes no gesture
918
+ │ ├─ slice + affordances (optional) — bound slice chrome (default ["cohort","filter","search","range","resolution","brush","summary"]): the slice's range (`datetime` on a time axis, the field's `float` / `integer` on a number axis) / resolution IS the window + resolution source of truth (axis seeds the unbound case; an ordinal axis has no range arm; the window widens outward to whole periods). A slice range is CLOSED (both ends inclusive) and the window half-open, so the canvas writes `[min, max)` as the range ending at the last value before `max` on the field's own lattice — an integer's `max − 1`, a datetime's millisecond before, a float's next double down — and reads it back whole (#949): seed an integer range `{ from: 1n, to: 8n }` for the eight steps 1–8 (the range chip reads `1–8`), a datetime one ending the millisecond before the window's end (`week(39n).addMilliseconds(-1n)`); `brush` mounts the horizon band on time and number axes — an OVERVIEW of the range field in whole periods, one histogram bar each, with a lens joining its window to the plot's edges (drag its body to slide the window, an edge to resize it, empty track to draw one — every snapped step APPLIES live, so the canvas re-renders honestly mid-gesture and the release commits), `resolution` the WEEK/DAY segment (time axis, slice-bound only), `summary` the count line. On a PAGED canvas, narrowing affordances are scope-badged ("loaded rows only") and `search` becomes a KEY SEARCH over the source's `seek` — the toolbar's search box, folding to its icon on a row short of room; the jump REBASES residency at the match (windows in between are never fetched); the query is a whole-key literal, a prefix, leading struct fields, or a `from..to` RANGE over a leading prefix of the key's flattened fields (`late, 3..ok`), which is what a time window or a status band asks for — quoting is the escape: a quoted value is exact and a `..` inside it is text (`"../config"`)
919
+ │ ├─ grain (optional) — initial grain "resource" (default) | "group" (root groups collapse to summary strips); the `g` key cycles it, and a canvas with a root group mounts the toolbar's GROUP · RESOURCE segment for it — slice or no slice (#632; the narrow layout's tabs own the grain there); onGrainChange observes
920
+ │ ├─ ui (optional) — the interaction state, held by the HOST (#824): State.bind([Plan.Types.UiState], key, Plan.uiState({ selected?, collapsed?, expanded?, charts?, focus? })) — the canvas draws it from its first frame, takes every outside write (a selection, rows folded or opened, charts expanded) and writes the user's own actions back, once per action; `collapsed` / `expanded` list the rows folded / opened AGAINST their declaration (a row in neither follows it; in both, folded); `focus` is a REQUEST — the canvas opens the rows it nests under, scrolls it to the top of the view, makes it the tab stop (DOM focus stays put) and writes `focus: none` back; a paged row it has not loaded is opened by its window, or sought by its entry's key where the source can seek. Bound, the canvas persists no toggles of its own under its `storageKey`
921
+ │ ├─ id + sources + canDrop (optional) — DnD TARGET (the shared grammar): cards — an author's tab's in the Plan's own library panel (`Plan.library.tab`, #1259), or a Library's beside the Plan, which reaches it by its `id` when `sources` lists the Library — `add` onto rows whose series declares `edit` — span / buckets / events / cards only (chart / heat / table render DERIVED values, and section headers and group strips are wayfinding — they register no cell) — and only with `editing`: a drop is a DRAFT of the session (#880), its item built by the series' `create` from the `Plan.Types.Drop` ({ from: { library, key }, row, at, duplicate } — `at` the start of the bucket it landed in, on the axis arm). `canDrop` sees the drag grammar's `add`: its `into.row` is the row id's canonical TEXT — key host tables by `East.print(Plan.ref(series, …path))`, or read it back with `row.parse(Plan.Types.RowId)`; slot = the bucket start instant per the axis arm — time: Z-less ISO (`slot.parse(DateTimeType)`), number: a decimal (`slot.parse(FloatType)`), ordinal: the value; drop verdicts resolve LIVE where the drag rests — `canDrop` is asked of the event a drop there would deliver (an `add`'s `duplicate` is whether Alt is held), renders the ⊘ stage, and is asked again before the drop becomes a draft — and the landing band previews WHERE the card lands. A moved or resized element (#825) is vetoed the same way: `canDrop` sees the grammar's `move` ({ from, to } cells, `from.event` the element's key) or `resize` ({ event, edge }). The canvas's own elements, and its own panel's cards, need no `id` — only a Library beside the Plan does. A card held at a bounded canvas's edge scrolls it to the rows beyond; by keyboard (#608) → / ← step onto a row and along its buckets and ↑ / ↓ between rows, each bucket announced ("Poster run is over H1-P03, Week of Jul 6, 2026."). `onDrag` is removed (#880) and throws at build. With event kinds, `canDrop` may instead be fn(Schedule.Types.Candidate) => Option<String>, vetting an event kind's drop with its message on the ghost, as the Calendar's — the arm is read from the function's type; it is asked where a drag rests and again of the drop, `from` the template's key, the backlog event's or the moved event's (#1196)
922
+ │ ├─ onSelect / onElementClick / onGroupToggle (optional) — row selection, ONE element callback and section toggles; payloads are row ids + element keys + instants, never indices: onSelect the `Plan.Types.RowId`; onElementClick a `Plan.Types.ElementRef` — the SAME ref the popover resolver receives, its arm the element kind (run { row, run } · event { row, event } · mark { row, mark } · chip { row, chip } · cell { row, at } — `at` a Plan.Types.Instant on the axis arm, a folded bucket's start · link { key, from, to }), so `ref.match({ run: …, link: … }, …)` handles the kinds it cares about; onGroupToggle { row, expanded } for any row with children
923
+ │ ├─ footer (optional) — [{ text, tone?, end? }] status-footer items, in the frame's footer after its counts; a paged canvas adds the transport line ("N loaded of M · Loading…", counted in source ELEMENTS); until the source is exhausted a TOP-LEVEL section's member count prints `~`-marked (its members are entries the windows share out) — every other parent's numbers are exact, its subtree riding whole in one entry
924
+ │ └─ style (optional) — { height ("fill" fills the parent) and maxHeight — the whole Plan's, its frame's, the canvas filling main and scrolling its own rows; with neither, a host that gives the Plan a height bounds it the same way, and one that gives none lets it grow with its rows — density ("compact" ⇒ dense 24px rows), gutterWidth ("168px", CSS px) }; a bounded canvas pins the PARENT of the rows in view under its header — with its ancestors' path on a deep tree — once the parent's own row scrolls off, inline and paged (a click goes to it, #823)
925
+ ├─ Narrow (below 480px of CONTAINER width — a phone, a splitter pane, a task preview; §10): the same definition reflows to a review tool — the frame's toolbar keeps its items, folded to fit (the GROUP · RESOURCE segment leaves: the tabs own the grain), no horizon brush, and Groups · Rows · Measures tabs (the `<Tabs>` line grammar, counts as plain numerals) over ONE slice, then the card list with the shared ruler as its sticky first row (a separator per bucket, labels thinned to what fits): Groups = the group grain as hottest-first strip cards (tap opens its rows) — the LANDING only when it is a map (three or more groups, or any strip); Rows = every data row as a card SECTIONED by group (a section header scopes to that group; `← All rows` returns) with the gutter identity as the card head and the row's plot — the same kind renderer — as the body on the shared window; Measures = chart rows full-width at expanded density; tap selects, a second tap on an `expand` row drills it in place (~148px; neighbours keep their size), a two-finger horizontal drag pans the window; a bounded `height` pins the header and scrolls the list; a paged source shows its resident prefix. Wrap a Plan in `<Box width="360px">` to see it on a desktop page
926
+ ├─ Keyboard (#819): the body is a TREEGRID with ONE tab stop that roves between its rows — every row, group band, ⋯ gap band and paged-window band (loading or failed) is a `row` with aria-level / aria-expanded / aria-selected and an `aria-rowindex` that stays exact under virtualization, collapse and paging · ↑ / ↓ step, Home / End go to the first / last, PgUp / PgDn move a viewport · → opens a closed section (a group band, a nesting parent, an `expandable` chart) and steps into an open one's first child; ← closes an open one, else steps to the parent · Enter does the row's click (select; a group band toggles; a rail, strip or ⋯ band returns from the row focus) · Space toggles the section / chart · a step onto an UNLOADED band asks the source for that window and moves on to the row once it lands (Home / End reach the source's own first / last row) · Tab walks the row's widgets — its controls, its elements in time order, tabbables in the expand render — then leaves the canvas; ← / → (Home / End) step between elements in time order; Enter / Space on an element does its click (the popover, the selection — an event kind's element selects its event, Shift+Enter adds it, #1197 — the element callback) · Esc ladder, one rung per press: popover → element back to its row → brush → focus → deselect (the row, its bucket and the events at once) · n recenters the window on `now` · [ / ] pan one period · g cycles the grain — window keys are SLICE writes, so an unbound canvas idles them · with `editing`, ⌘Z / Ctrl+Z undo the last gesture and ⌘⇧Z / Ctrl+Shift+Z / Ctrl+Y redo it (#880) · with `editing`, Space on a movable element picks it up (#825): ← / → move it one bucket, Shift+← / → its end and Alt+← / → its start, ↑ / ↓ carry it to the nearest row above / below that takes it, Space / Enter drop it, Esc / Tab cancel — each step said in the canvas's live region; an event kind's element is carried the same way (#1196), ↑ / ↓ along the rows its kind draws on, a refusal said with why · the toolbar's GROUP · RESOURCE and WEEK · DAY segments are radio groups: one tab stop each, ← / → (Home / End) move and pick
927
+ ├─ Screen readers (#819): a polite live region says what changed — a selection, a section or chart opening / closing, a row focus coming or going, the grain, the resolution, each window a paged source lands ("Loaded elements 201–400 of 5,000", counted in source elements like the transport line); every element is named in words — label, span or bucket ("Week of Jul 6, 2026"), state, tone — a chart row reads as an image with a min / max / last summary per layer, and colour-only cells (heat depth, booked weight, segment composition, compressed strips) carry their value as text; narrow, the Groups · Rows · Measures tabs are a real tablist (arrow keys, one tabpanel each)
928
+ ├─ Localization (#820): every word the canvas says itself — toolbar, ruler, footer, diagnostics, bands, narrow tabs and cards, the history bar (the table carries the editing session's words, #880), element names, live-region announcements — comes from ONE typed message table, and every number and date it prints is in the LOCALE: react-aria's `<I18nProvider locale="de-DE">` above the app sets it (the browser's language otherwise), and derived numbers ("2.234,5 k sheets"), ruler ticks ("MO · DI"), the words a reader hears ("29. Juni 2026") and a Chart.format.* axis all follow it. Host React code overrides any subset of the words for a subtree with `<PlanMessagesProvider messages={GERMAN}>` (@elaraai/e3-ui-components; `planMessages` is the English table — each message a function of named, already-formatted parameters, plus the raw `n` for plurals; define the overrides ONCE, not per render — providers nest). What the AUTHOR wrote is data and never translated: labels, footer items, and a date `format` pattern on the axis (East tokens, as written); the label a patch event carries to the host stays in English, as the Sheet's does
929
+ └─ Factories:
930
+ ├─ Plan.axis({ … }) = Plan.axis.time / Plan.axis.number({ window?, step, now?, format? }) / Plan.axis.ordinal({ values, now? }) — the shared axis declaration, one of three kinds (Plan.Types.Axis); Plan.at.time(d) / Plan.at.number(n) / Plan.at.ordinal(s) build ONE INSTANT explicitly (Plan.Types.Instant) — needed only for element RECORDS written as data (a Plan.Types.HeatCell array, a stored Plan.Types.Run): every element builder below takes a Date / number / string, or a DateTime / Float / Integer / String expression, and wraps it to the arm by its type, so a `start: r.start` DateTime accessor and a `day: FloatType` field both need nothing written
931
+ ├─ Plan.series.* — the data-driven row series (see `series` above); Plan.Types.Series(Row) is one series' East type over `Dict<String, Row>` entries, Plan.Types.Series(Row, KeyType) over another key type
932
+ ├─ Plan.children(of, [series…]) — a step down from an entry to a child collection of another entry type (`of(entry, key)` returns an `Array` or a `Dict`), for a series' `children`
933
+ ├─ Plan.ref(series, …path) / Plan.sectionRef(series, …path) — a row's id (Plan.Types.RowId = entry { series, path } | section { series, path }): `Plan.ref("presses", "H1-P03")`, a nested row `Plan.ref("rollup", "Contract A", "H1-P03")`, a `views` member's row by the MEMBER's key; for links, `East.equal` comparisons in resolvers, and host tables keyed by `East.print(id)` (an id is a variant — it cannot be a Dict key itself)
934
+ ├─ Plan.run({ key, start, end, label, quantity?, state, status?, moved?, icon? }) — one state-run bar (state: "actual"|"in-progress"|"confirmed"|"estimated"|"added"|"recommended"|"removed"|"rejected"; `quantity` is ONE Plan.quantity — the bar prints its caption after the label and a parent's rollup band sums it with its siblings' in the same unit; status "warning" draws the stuck ring; runs past the window mask-fade, never fabricate an end)
935
+ ├─ Plan.quantity(value, { unit?, format?, text? }) — a quantity (Plan.Types.Quantity): `value` is what sums, weighs and compares, `unit` what a rollup sums by (sheets never add to hours), `format` a Format.* spec printing the value in the viewer's locale, `text` a caption printed instead (the value still sums) — a run's and a link's `quantity`
936
+ ├─ Plan.event({ key, at, lane?, label?, icon?, state, tone?, color?, colorPalette?, stretch?, content?, animation? }) — one bucket tile (label omitted ⇒ the resting ✓ / dashed `plan` chip; lane omitted in a laned row spans the full cell — the mixed grammar)
937
+ ├─ Plan.lane({ key, label? }) / Plan.marker({ at, lane?, status?, message }) — bucket sub-slot lanes + cell status rings (status defaults "danger"; message = the tooltip)
938
+ ├─ Plan.chip({ key, from, to, label, state, icon? }) — one cards shift chip; Plan.mark({ key, at, kind, icon?, label? }) — one event mark (kind: "milestone" | "exception" | Plan.markKind.decision(applied))
939
+ ├─ Plan.decision({ key, at, applied }) / Plan.port({ at, label? }) — span-row decision diamonds (◇ pending / ◆ applied) + quantity in/out ports
940
+ ├─ Plan.heatCells(cells, { min?, max?, warnAt?, fold?, format? }) / Plan.weightCells(cells, { fold?, format? }) / Plan.segmentCells(cells, { fold?, format? }) + Plan.segment({ fill, weight, label? }) — the three heat-row cell arms (colour depth / booked-vs-free bars / compositions); `fold` is what a coarser bucket shows of the cells in it (heat and weight "mean", segments "sum"; "sum" | "mean" | "min" | "max" | "last" | "count"), `format` a Format.* spec for the values the arm prints — a heat cell without a `label` prints its value only through a declared `format`, and the words a reader hears for a weight or a segment share follow it
941
+ ├─ Plan.tableCells(rawCells) / Plan.tableSeries({ cells, format?, tone?, strong?, rollup?, fold? }) — bucketed numerals (a raw cell's `at` wraps by its field type — DateTime / Float / Integer / String / an instant) (multi-series per row, style declared once per position; explicit text/tone overrides via PlanTableCellType values); a series folds by `fold` (default "sum"), and `Plan.series.table`'s `fold` declares it for its `cells`
942
+ ├─ Plan.layer(chartLayer, { axis?, breach?, series?, fold? }) + Plan.fixed("120px") — chart rows consume Chart.Line/Column/Area/Scatter/Band/ref* builder results AS DATA on the shared scale (the x accessor's static type picks the arm — DateTimeType ⇒ time, Float/Integer ⇒ number, String ⇒ ordinal — and must match the canvas axis at render; Chart.Bar is a build-time error on every kind); Plan.layer adds the y-axis side, breach threshold, stack series and the fold a coarser bucket shows (columns "sum", lines and areas "mean"; scatter and band layers draw every point)
943
+ ├─ Plan.span/buckets/chart/heat/table/cards/events/group({ key, label, id?, sub?, value?, meta?, stacked?, swatches?, collapsed?, pinned?, height?, status?, expand?, …kind fields, rows? }) — literal kind factories returning row STREAMS (the row, then its nested `rows:` in order; parents DECLARE rollup/aggregate and the renderer derives the numbers); ride them beside data-driven series via Plan.series.rows — a hand-built row's id is that series' key plus the factory `key`s that lead to it (`Plan.ref("works", "shutdown", "elec")`), so keys must be unique among siblings (a repeat draws as a DUPLICATE ID row diagnostic)
944
+ ├─ Plan.link({ key, from, fromRun, to, toRun, quantity? }) — one link-graph edge; `key` is what a ribbon click's `link` ref names it by, `from` / `to` are row ids (`Plan.ref`) with their runs, or events (`Plan.eventRef`) with none, `quantity` a Plan.quantity
945
+ ├─ Plan.eventRef(kind, key) — an event of one of the Plan's event kinds, named for a link's end (Plan.Types.RunRef) · Plan.over(data, [series…]) — series over a dataset, read only, for `rows` (#1191)
946
+ ├─ Plan.library.events() / backlog() / series() / tab(rows, config) — the library pane's tabs (#1195, see `library`) · Schedule.patch(R, { field: value, … }) — a patch over an event kind's row type (Schedule.Types.Patch(R): every field an `Option`, the fields left out `none`), what an author's card dropped on an event sets
947
+ ├─ Plan.uiState({ selected?, collapsed?, expanded?, charts?, focus? }) — the seed of a bound `ui` state (Plan.Types.UiState): rows named by id (`Plan.ref`), omitted fields empty
948
+ └─ Plan.Types.PatchEvent(R) — what `editing.onPatch` receives for entries of `R` · Plan.Types.Drop ({ from: { library, key }, row: RowId, at: Instant, duplicate }) — what an `edit.create` builds its item from · Plan.Types.Gesture (drop(Drop) | move(Move)) and Plan.Types.RowEdits ({ drop, move: Option<MoveEdits> } — the gestures a row takes) · Plan.Types.Move ({ key, from: RowId, to: RowId, start, end } — a moved or resized element, #825) — the editing wire (#880); the session's contracts are the shared `Editing.Types.*` (ChangeSet(R, K), ApplyResult, Readiness)
949
+ ```
950
+
951
+ #### The series list is the layout, the data is the hierarchy (#822)
952
+
953
+ A canvas is `data` plus a list of series, and the list IS the layout: one
954
+ block per series, top to bottom, each parent followed by its subtree. Nesting
955
+ comes only from what an entry holds — a recursive entry's own children, or a
956
+ step down into a child collection — so a parent's bands, means and subtotals
957
+ are exact, and the canvas reads the same inline or paged. There is no
958
+ `groupBy`: to group a flat source, reshape it first.
959
+
960
+ ```tsx
961
+ // Grouping is a DATA step: one groupToDicts makes each hall an entry holding its rows.
962
+ const halls = $.let(rows.groupToDicts(($, r) => r.hall, ($, _r, k) => k));
963
+ const HallGroup = DictType(StringType, HallRow);
964
+ const series = $.const([
965
+ // One strip PER HALL; its rows stepped down into, laid out like a top-level list.
966
+ Plan.series.group(HallGroup, {
967
+ key: "halls", title: "Halls",
968
+ label: (_g, hall) => hall,
969
+ summaryAggregate: "mean",
970
+ children: Plan.children((g) => g, [
971
+ Plan.series.span(HallRow, {
972
+ key: "hall-jobs", title: "Jobs",
973
+ match: r => r.jobs.size().greater(0n),
974
+ label: r => r.label,
975
+ runs: r => r.jobs.map((_$, j) => Plan.run({ key: j.key, start: j.start, end: j.end, label: j.ticket, state: j.state })),
976
+ }),
977
+ Plan.series.heat(HallRow, {
978
+ key: "hall-load", title: "Load",
979
+ match: r => r.cells.size().greater(0n),
980
+ label: r => r.label,
981
+ cells: r => Plan.heatCells(r.cells, { min: 0, max: 100 }),
982
+ }),
983
+ ]),
984
+ }),
985
+ ], ArrayType(Plan.Types.Series(HallGroup)));
986
+ // <Plan axis={axis} data={halls} series={series} />
987
+ ```
988
+
989
+ A recursive entry nests to whatever depth the data has, and every parent
990
+ derives its numbers from its subtree:
991
+
992
+ ```tsx
993
+ const OrderRow = RecursiveType((self) => StructType({
994
+ name: StringType, act: ArrayType(RawCell), children: DictType(StringType, self),
995
+ }));
996
+ Plan.series.table(OrderRow, {
997
+ key: "orders", title: "Orders", label: r => r.name,
998
+ cells: r => Plan.tableCells(r.act), // a parent carries no values of its own…
999
+ children: r => r.children, aggregate: "sum", // …and shows its subtree's subtotal, at every depth
1000
+ format: Format.Number({ maximumFractionDigits: 0n }),
1001
+ })
1002
+ ```
1003
+
1004
+ One entity shown several ways is a `views` series: each entry gets one row per
1005
+ member series, side by side, and each row has its own id:
1006
+
1007
+ ```tsx
1008
+ Plan.series.views(OpsRow, { key: "presses", title: "Presses", match: r => r.pick.equal("presses") }, [
1009
+ Plan.series.span(OpsRow, { key: "press-jobs", title: "Press jobs", label: r => r.label,
1010
+ runs: r => r.jobs.map((_$, j) => Plan.run({ key: j.key, start: j.start, end: j.end, label: j.label, state: j.state })) }),
1011
+ Plan.series.chart(OpsRow, { key: "press-util", title: "Press · utilisation", label: r => r.label, layers: r => [Chart.Line(r.points, { x: p => p.week, y: p => p.pct })] }),
1012
+ Plan.series.table(OpsRow, { key: "press-sheets", title: "Press · sheets", label: r => r.label, cells: r => r.nums }),
1013
+ ])
1014
+ // a click on p03's utilisation row reports Plan.ref("press-util", "p03")
1015
+ ```
1016
+
1017
+ | Signature | Description | Example |
1018
+ | --- | --- | --- |
1019
+ | **Layout and nesting** | | |
1020
+ | `series={[s1, s2, …]}` | The list is the layout: one block per series, top to bottom; a pick's list order is the same layout. | `planTargetState` |
1021
+ | `children: (r, k) => r.children` | More of this series: a `RecursiveType` entry, to any depth. A parent's span bands (`rollup`, summed per quantity unit), heat `aggregate` (on its `scale`) or table subtotals (`aggregate`, `format`) derive from its subtree. | `planTargetState`, `planMeasures` |
1022
+ | `children: Plan.children(of: (r, k) => Array \| Dict, series: Series[])` | A step down to a child collection of another type, laid out like a top-level list; an array of step-downs gives several collections, in order. | `planTargetState` |
1023
+ | `Plan.series.group(G, { key, title, label, children, summaryAggregate?, summary?, collapsed? })` **❗** | One strip per entry, its members the entry's children; the removed `by` form throws. | `planTargetState` |
1024
+ | `rows.groupToDicts(($, r) => r.hall, ($, _r, k) => k)` | Grouping is a data step; a paged source is grouped in its dataflow. | `planTargetState` |
1025
+ | `Plan.series.section(R, { key, title, collapsed?, meta?, value?, status?, summaryAggregate? }, members: Series[])` | A fixed titled block over series; it adds no path segment. | `planTargetState` |
1026
+ | `Plan.series.views(R, { key, title, match?, children?, collapsed? }, members: Series[])` **❗** | One row per member per entry, adjacent; the entry's children follow under the first view row, and a seek lands there. A member may not declare `children`. Its children may be more of its own entries (a bare accessor), each drawn as the members' rows; a span member's `rollup` rolls them up. | `planTargetState` |
1027
+ | `Plan.series.rows(R, { key, title }, [Plan.span({ key, label, rows? }), …])` | Hand-built rows as one block; a row's id is the series key plus the factory keys to it. | `planTargetState` |
1028
+ | **Paged sources (#823)** | | |
1029
+ | `data={paged}` — a `Data.bindPaged(…)` handle **❗** | Parents are the page unit: a window is N top-level entries with their whole subtrees, so nest children in the source and group a flat source in its dataflow. | `dataBindPagedPlan` |
1030
+ | several series over one paged source | Each series is a block that pages on its own — its own bands and resident run — and one read of a window serves every block; a section's header and hand-built rows are fixed blocks, drawn once. | `dataBindPagedBlocks` |
1031
+ | **Identity** | | |
1032
+ | `Plan.ref(series: String, ...path: String[]): RowId` | A row's typed id, for links, `East.equal` in resolvers, and host tables keyed by `East.print(id)`. | `planTargetState`, `planRowDrop` |
1033
+ | `Plan.sectionRef(series: String, ...path: String[]): RowId` | A section header's id, at its parent's path. | `planTargetState` |
1034
+ | `onSelect` / `expandRender` / `expandGutter`: `fn(Plan.Types.RowId)`; element refs, `onGroupToggle`, a drop (`Plan.Types.Drop`): `{ row: RowId, … }` | Every callback names a row by its id. | `planVariants`, `planTargetState`, `planRowDrop` |
1035
+ | series keys unique across the whole tree **❗** | A repeated key is a build-time error naming both series; a repeated run-time id draws a DUPLICATE ID row diagnostic. | — |
1036
+ | **Window** | | |
1037
+ | `Plan.axis({ window: { min, max }, … })` or `slice={{ slice }}` **❗** | The window is stated, or it is the bound slice's range. A canvas with neither is refused, and nothing fits the axis to the data. | `planTargetState`, `planNumberAxis` |
1038
+
1039
+ A paged canvas pages by parents, block by block (#823): a window holds its
1040
+ entries whole, so every parent derives exactly, and each top-level series is a
1041
+ block paging on its own over the same windows — the canvas draws exactly as it
1042
+ does inline. Group a flat paged source in the dataflow that produces it, so a
1043
+ group arrives as one entry holding its members.
1044
+
1045
+ Removed with #822: `groupBy` on span / heat / table; `Plan.series.group(R, {
1046
+ by })` and the static `group(R, chrome, children)` form (use `section`);
1047
+ `keyPrefix` / `keySuffix` (use `views`); numbered keys to force a layout
1048
+ (order the series list); fit-to-data; and `Plan.pick`'s `data` counts.
1049
+
1050
+ #### Values, folds, one element callback and a bound ui state (#824)
1051
+
1052
+ A quantity is ONE value — the number, its unit and how it prints — so a bar's
1053
+ caption and a rollup's total can never disagree. Values fold to the axis's
1054
+ resolution: weekly cells on a MONTH axis show one cell per month per row, and
1055
+ every cell builder, table series and chart layer says how (`fold`). Every
1056
+ element click is one callback over the same ref the popover resolver receives,
1057
+ and the interaction state can live with the host.
1058
+
1059
+ ```tsx
1060
+ Plan.run({ key: j.key, start: j.start, end: j.end, label: j.ticket, state: j.state,
1061
+ quantity: Plan.quantity(j.sheets, { unit: "k sheets", format: Format.Number({ maximumFractionDigits: 0n }) }) })
1062
+ Plan.heatCells(r.load, { min: 0, max: 100, fold: "max", format: Format.Number({ maximumFractionDigits: 0n }) })
1063
+
1064
+ // The host holds what is selected, folded, opened and expanded; a write brings a row into view.
1065
+ const ui = $.let(State.bind([Plan.Types.UiState], "ops.plan.ui", Plan.uiState({ collapsed: [Plan.ref("halls", "Hall 3")] })));
1066
+ const goTo = $.const(East.function([Plan.Types.RowId], NullType, ($, id) => {
1067
+ const s = $.let(ui.read());
1068
+ $(ui.write(East.value({ selected: some(id), collapsed: s.collapsed, expanded: s.expanded, charts: s.charts, focus: some(id) }, Plan.Types.UiState)));
1069
+ }));
1070
+ // One callback for every element; a partial match answers only the arms it names.
1071
+ const picked = $.let(State.bind([StringType], "ops.plan.picked", ""));
1072
+ const onElementClick = $.const(East.function([Plan.Types.ElementRef], NullType, ($, ref) => {
1073
+ $.match(ref, {
1074
+ run: ($, r) => { $(picked.write(East.str`run ${r.run} on ${East.print(r.row)}`)); },
1075
+ link: ($, l) => { $(picked.write(East.str`link ${l.key}: ${l.from.run} → ${l.to.run}`)); },
1076
+ });
1077
+ }));
1078
+ // <Plan axis={axis} data={halls} series={series} ui={ui} onElementClick={onElementClick} />
1079
+ ```
1080
+
1081
+ | Signature | Description | Example |
1082
+ | --- | --- | --- |
1083
+ | `Plan.quantity(value: Float, { unit?: String, format?: Format.*, text?: String }): Quantity` | A run's or a link's quantity: its caption is `text`, else the value through `format`, then its unit; rollup bands sum it unit by unit. | `planTargetState` |
1084
+ | `fold?: "sum" \| "mean" \| "min" \| "max" \| "last" \| "count"` | What a coarser bucket shows of a row's values in it: heat and weight `mean`, segments, table numerals and columns `sum`, lines and areas `mean`. One value in a bucket keeps its own instant, label and text. | `planMeasures` |
1085
+ | `onElementClick: fn(Plan.Types.ElementRef) => Null` | Every element kind — run, event, mark, chip, cell, link — through one callback; the arm says which. | `planVariants` |
1086
+ | `ui: State.bind([Plan.Types.UiState], key, Plan.uiState({ … }))` | The host's selection, folds, opens, expanded charts and a `focus` request the canvas spends; the user's actions are written back. | `planTargetState` |
1087
+ | `Plan.link({ key, from, fromRun, to, toRun, quantity? })` | A ribbon keyed for its click ref, weighed and captioned by its quantity. | `planTargetState` |
1088
+
1089
+ Removed with #824: `qty` and the string `quantity` on a run (one
1090
+ `Plan.quantity`); the span series' `unit` (a quantity carries its unit); the
1091
+ five element callbacks `onRunClick` / `onEventClick` / `onMarkClick` /
1092
+ `onChipClick` / `onCellClick` (`onElementClick`); a link's `label` (its
1093
+ quantity's caption); and a group strip given both `summary` and
1094
+ `summaryAggregate` (refused at build).
1095
+
1096
+ #### Every change is a draft (#880)
1097
+
1098
+ The Plan's editing session is the Sheet's (#879), over the source's TOP-LEVEL
1099
+ entries. A dropped card and a moved or resized element are gestures, never
1100
+ callbacks: each drafts the entry its row came from — at any depth, since the
1101
+ whole subtree rides in its entry — the canvas draws the draft at once by
1102
+ deriving the entry's rows again, and Save sends every draft as one checked
1103
+ batch. The series says what a gesture writes; the root says where the batch
1104
+ goes.
1105
+
1106
+ ```tsx
1107
+ // A LIVE handle over the halls: the canvas reads it, and Save writes it.
1108
+ const halls = $.let(State.bind([DictType(StringType, Hall)], "ops.plan.halls", seed));
1109
+ // The author's check over one drafted hall; a refusal names the press and holds Save.
1110
+ const ready = $.const(East.function([Hall, StringType], Editing.Types.Readiness, ($, hall, _key) => {
1111
+ const crowded = $.let(hall.presses.filter((_$, p) => p.jobs.size().greater(4n)));
1112
+ const result = $.let(variant("ready", null), Editing.Types.Readiness);
1113
+ $.if(crowded.size().greater(0n), ($) => {
1114
+ $.assign(result, variant("invalid", crowded.toArray((_$, p, k) => ({
1115
+ field: "jobs", message: East.str`${k} holds ${East.print(p.jobs.size())} jobs — at most 4`,
1116
+ }))));
1117
+ });
1118
+ return result;
1119
+ }));
1120
+ // Every gesture as it is made — a drop, a move, an undo.
1121
+ const last = $.let(State.bind([StringType], "ops.plan.last", ""));
1122
+ // The palette: the Plan's own library panel, a card per job template.
1123
+ const templates = $.let(Data.bind(jobTemplates));
1124
+ const onPatch = $.const(East.function([Plan.Types.PatchEvent(Hall)], NullType, ($, event) => {
1125
+ $(last.write(East.str`${event.origin.getTag()} · ${event.label}`)); // drop · Drop brochure on P03
1126
+ }));
1127
+ <Plan axis={axis} data={halls}
1128
+ library={[Plan.library.tab(templates.read(), { name: "Jobs", label: t => t.name })]} // a card drags onto a press
1129
+ series={[Plan.series.span(Hall, {
1130
+ key: "halls", title: "Halls", label: h => h.name, runs: _h => [],
1131
+ // A gesture on a press writes back into its hall through this FIELD.
1132
+ children: Plan.children(h => h.presses, [
1133
+ Plan.series.span(Press, {
1134
+ key: "presses", title: "Presses", label: (_p, k) => k,
1135
+ runs: p => p.jobs.map((_$, j) => Plan.run({ key: j.key, start: j.start, end: j.end, label: j.label, state: j.state })),
1136
+ edit: { // a dropped card joins `jobs`; a run moves and resizes
1137
+ items: "jobs", key: "key", start: "start", end: "end",
1138
+ create: (drop, p) => ({
1139
+ key: East.str`${drop.from.key}-${East.print(p.jobs.size())}`, label: drop.from.key,
1140
+ start: drop.at.unwrap("time"), end: drop.at.unwrap("time").addWeeks(2n),
1141
+ state: variant("proposed", variant("added", null)),
1142
+ }),
1143
+ },
1144
+ }),
1145
+ ]),
1146
+ })]}
1147
+ editing={{ onUpdate: halls.write, onPatch, ready }} />
1148
+ ```
1149
+
1150
+ | Signature | Description | Example |
1151
+ | --- | --- | --- |
1152
+ | **What a gesture writes (on the series)** | | |
1153
+ | `edit: { items: F, create: (drop: Plan.Types.Drop, entry, key) => Item }` — `F` an `Array<Item>` field; span / buckets / cards / events **❗** | A library card dropped on a row joins `F` as `create`'s item: `drop.from` is the card, `drop.at` the start of the bucket it landed in, on the axis arm. A misnamed field fails the build. | `planRowDrop` |
1154
+ | `edit: { items: F, key: K, start: S, end: E }` (span / cards) or `{ items: F, key: K, at: A }` (buckets / events) **❗** | A run, chip, tile or mark moves by its body, and a run or chip resizes by either end, with the pointer, a touch or the keyboard (#825). It moves in whole buckets; Shift moves one finer unit (a day under a week, an hour under a day, 15 minutes under an hour). Onto another row whose items are the same type, the item leaves its list for that row's, as one gesture over both entries. `K` is the item's `String` key field, since an element's key is its item's key — and its identity across every row it can move to: a row's list keeps its keys unique, so a card or a move that would repeat one is refused (⊘ while dragging); `S`, `E` and `A` are instant fields (`DateTime`; `Float` / `Integer` on a number axis; `String` on an ordinal one; `Plan.Types.Instant`). `create` becomes optional. A field a move cannot write fails the build. | `planRowDrop` |
1155
+ | `children: r => r.kids` / `Plan.children(r => r.kids, …)` / `Plan.children(g => g, …)` **❗** | A gesture below an entry writes back through its `children`, so where a series below takes gestures they read a FIELD of the entry or are the entry itself; a computed collection fails the build. | `planRowDrop` |
1156
+ | **The session (on the root)** | | |
1157
+ | `editing={{ onUpdate: handle.write }}` with `data={handle}` **❗** | The inline adapter: Save applies the batch with `Editing.apply` over the handle's latest `Dict` and writes it once — idempotent across retries. It needs the handle itself as `data`. | Inline adapter shown above; the record-backed `planRowDrop` uses `Record.onApply` |
1158
+ | `editing={{ onApply: fn(Editing.Types.ChangeSet(R, K)) => Editing.Types.ApplyResult }}` **❗** | The host's transaction, sync or async, checked against the base the drafts began from. A paged source needs `revision` and `refresh`; the host applies atomically, dedupes by `requestId` and returns the committed revision. | `planRowDrop` (`Record.onApply`) |
1159
+ | `onPatch: fn(Plan.Types.PatchEvent(R)) => Null` | One call per gesture, and per undo, redo and discard. | `planRowDrop` |
1160
+ | `ready: fn(R, K) => Editing.Types.Readiness` | The author's check over a drafted entry: a refusal marks the rows the draft changed and holds Save; a check that throws refuses its own entry only. | `planRowDrop` |
1161
+ | `mode: "batch" \| "auto"` | Save sends the batch (default), or each ready gesture goes at once. | `planRowDrop` (batch); auto mode is exercised by `plan-editing.spec.ts` |
1162
+ | `canDrop: fn(DragEventType) => Boolean` | Vets the event a drop where the drag rests would deliver — its `duplicate` whether Alt is held — showing the ⊘ stage, and again before it becomes a draft. A move is vetoed as the grammar's `move` or `resize` (#825), and a refusal is announced. | `planRowDrop` |
1163
+
1164
+ - **Drawn where made.** A drafted entry's rows are derived again, exactly as
1165
+ Save will leave them. A row the draft changed carries the Sheet's mark:
1166
+ pending, or incomplete / invalid while a check refuses its entry — each
1167
+ entry marked for its own issues. The narrow layout's cards carry the same marks.
1168
+ - **One gesture, one transaction.** The history item ends the frame's toolbar:
1169
+ issues · Undo · Redo · Discard · Save, and its status line. ⌘Z / Ctrl+Z
1170
+ undo; ⌘⇧Z / Ctrl+Shift+Z / Ctrl+Y redo.
1171
+ - **The base is the source's.** An inline `Dict` is checked by its snapshot, a
1172
+ paged source by its revision. A batch against a source that moved is
1173
+ refused, never rebased: a banner says "Source changed — review or discard
1174
+ these drafts".
1175
+ A Save whose outcome is unknown retries the SAME request ("Retry
1176
+ request"), and drafts retire only once the source reads back at the
1177
+ committed revision ("Saved — loading the confirmed revision…").
1178
+ - **Moves (#825).** A move along its row, or a resize, drafts the item's
1179
+ instants in place. A move to another row takes the item out of its list
1180
+ and appends it to the target row's, and a batch that takes an item and
1181
+ places it nowhere is refused whole. The row under the drag draws a landing
1182
+ band with the proposed span, and the ghost carries the element's label and
1183
+ span. The narrow layout takes no moves.
1184
+ - **No session, no gesture.** Without `editing` the toolbar has no history
1185
+ item, no card lands and nothing moves.
1186
+
1187
+ Removed with #880: the root's `onDrag` (a series' `edit`), which throws at
1188
+ build, naming its replacement.
1189
+
1190
+ Removed with #1260: approving and rejecting. A Plan's changes are drafts of
1191
+ its session, saved together, so the root's `review` (its decision column, its
1192
+ summary and Rerun, Approve all and Reject all), a series' `review` and
1193
+ `approval`, a hand-built row's `approval` and `Schedule.events`' `review` role
1194
+ are gone, with the verdict buttons on a row and in the inspector. Each throws
1195
+ at build, naming the removal. The history item's commit is Save.
1196
+
1197
+ #### `Schedule`: resource and event kinds shared with Calendar
1198
+
1199
+ Bind records inside the example's own `Reactive` body. Resources and templates
1200
+ can come from bound records; the backlog is the event record's unscheduled rows.
1201
+ `Schedule` declares field roles and accessors. The internal renderer owns the
1202
+ frame, Slice toolbar, shared fields, drag layer and editing session.
1203
+
1204
+ | API / option | Meaning | Tested example |
1205
+ | --- | --- | --- |
1206
+ | `Schedule.resources(rows, { name, icon, label, meta? })` | Keyed resources; accessors receive `(row, key)`. `meta` is an optional second line. Use `Record.bind(record, []).read()` for a resource record. | `planEvents`, `planPrintWorks` |
1207
+ | Resource `group`, `parent` | Plan groups resources by the group label, and nests a resource under the optional key of its parent in the same kind. | `planPrintWorks` |
1208
+ | Resource `sub`, `value`, `status`, `collapsed` | Plan's gutter subtitle, value and status; initial collapse is a Boolean or accessor. | `planPrintWorks` |
1209
+ | Resource `rollup`, `measures` | Parent bands use `union` (default), `byStatus` or `sum`. Measures are read-only `Plan.series.heat`, `table` or `chart` rows over the resource type, with unique keys and no children. | `planPrintWorks` |
1210
+ | `Schedule.events(record, { name, icon, title, start, end, … })` | A record bound with its patch mutation; `title` names a String field, and `start`/`end` name matching DateTime or Option<DateTime> fields. | `planEvents` |
1211
+ | Event `at`, `draw` | An instant uses `at` instead of start/end and defaults to `marks`; it may draw `buckets`. Intervals default to `span`, and may draw `buckets`, `cards` or `marks`. | `planPrintWorks`, `planEventLinks` |
1212
+ | Event `resource: { field, of }` | A String/Option<String> field targets one resource slot. A variant field maps each case to a resource slot, such as bay or van. | `planPrintWorks` |
1213
+ | Event `state`, `quantity: { field, unit?, format? }`, `lane` | Plan's lifecycle field (confirmed when omitted), Float quantity with its unit/format, and String lane for bucket tiles. | `planPrintWorks` |
1214
+ | Event `status: { field, cases }` | A non-Option variant field with one `{ label, tone, ring }` per case; warning status rings the element. | `planPrintWorks` |
1215
+ | Event `overlaps: "warn" \| "allow"` | Warn is the default. Allow permits parallel events. Both preserve every event; warnings never remove or truncate overlaps. | `planPrintWorks` |
1216
+ | Event `backlog: { duration, due? }` | Option times allow unscheduled rows. Accessors derive their duration and optional due date from `(row, key)`. | `planEvents`, `planPrintWorks` |
1217
+ | Event `templates` | Presets have `key`, `name`, optional `group` and `at` clock, `duration`, and `values` for fields other than time/resource. Instant presets omit duration. Interval templates may use `Schedule.templates(boundRows, config)`. | `planPrintWorks`, `calendarOperations` |
1218
+ | Event `fields`, `Schedule.field.*` | The shared `Fields` vocabulary: `text`, `number`, `select`, `tags`, `checklist`, `reference`, `readonly`, `hidden`; other editors derive from the field type. | `planEvents`, `planPrintWorks` |
1219
+ | Event `ready`, `inspector` | Readiness returns `Editing.Types.Readiness` and can hold Save. A custom inspector receives the typed row and its session writer. | `planPrintWorks` |
1220
+ | Event `slice`, `entries` | A `Slice.bindRecord` with an interval index owns narrowing and the visible range; `Data.bindPaged(record)` supplies original-key reads for editing. See Indexed records and shared Slice above. | `calendarRecordIndexes` |
1221
+ | Event `window`, `backlogWindow`, `entries` | The separate single-index paging form, described under Large records below. Do not combine it with record `slice`. | `planWindows` |
1222
+
1223
+ `Schedule.Types` exposes the same contracts to both builders:
1224
+
1225
+ | Type | Value |
1226
+ | --- | --- |
1227
+ | `ResourceRef`, `EventRef` | `{ kind, key }`: the slot name and the original key's text. |
1228
+ | `Status`, `StatusCases(VariantType)` | `{ label, tone, ring }`, and one such status per variant case. |
1229
+ | `Clock` | `{ hour, minute }`, both Integers. |
1230
+ | `Duration` | The shared time-step variant: minutes, hours, days, weeks or months, with a Float amount. |
1231
+ | `Candidate` | `kind`, `from` (template/backlog/event key), `start`, `end`, optional `resource`; the Plan's drop veto receives this. |
1232
+ | `Patch(RowType)` | Every field optional; `Schedule.patch` constructs the patch. An omitted field stays unchanged; `none` supplied for an Option field clears it. |
1233
+
1234
+ Event kinds default to batch Save. For automatic commits, set
1235
+ `applyMode="auto"` on the same `<Plan>` with its bound resources and events:
1236
+
1237
+ ```tsx
1238
+ <Plan resources={resources} events={events} axis={axis} applyMode="auto" />
1239
+ ```
1240
+
1241
+ Each ready gesture commits through its kind's patch mutation. This does not change the separate data-series session's
1242
+ `editing.mode`. Auto mode is covered by `plan-events.spec.ts` and
1243
+ `plan-builder-editing.dom.test.tsx`; the showcase examples demonstrate batch Save.
1244
+
1245
+ #### Event kinds, read-only rows and links between events (#1191)
1246
+
1247
+ Beside `data`, a Plan takes event kinds over records — `Schedule`'s, the very
1248
+ values a Calendar takes. `resources` are the rows; each kind in `events` is a
1249
+ record of its own, bound with its patch mutation, and each of its events sits
1250
+ on the resource it names. `rows` adds read-only rows: hand-built ones, and
1251
+ series over a dataset with `Plan.over`. A link names an event by its kind and
1252
+ key, never its row: a draft can move the event, and the link follows it.
1253
+
1254
+ ```tsx
1255
+ const presses = $.let(Record.bind(planPrintPresses, []));
1256
+ const jobs = $.let(Record.bind(planLinkJobs, [planLinkJobsPatch]));
1257
+ const stock = $.let(Data.bind(planLinkStock));
1258
+ <Plan axis={axis}
1259
+ resources={{ presses: Schedule.resources(presses.read(), { name: "Presses", icon: "print", label: p => p.name, group: p => p.hall }) }}
1260
+ events={{ job: Schedule.events(jobs, {
1261
+ name: "Print job", icon: "file-lines", title: "title", start: "start", end: "end",
1262
+ resource: { field: "press", of: "presses" }, state: "state", quantity: { field: "sheets", unit: "sheets" },
1263
+ }) }}
1264
+ rows={[Plan.over(stock, [
1265
+ Plan.series.table(PrintStock, { key: "stock", title: "Paper stock", label: s => s.name, cells: s => Plan.tableCells(weekly(s.weekly)) }),
1266
+ ])]}
1267
+ links={[Plan.link({ key: "covers", from: Plan.eventRef("job", "J-2001"), to: Plan.eventRef("job", "J-2002"),
1268
+ quantity: Plan.quantity(12000.0, { unit: "covers" }) })]} />
1269
+ ```
1270
+
1271
+ | Signature | Description | Example |
1272
+ | --- | --- | --- |
1273
+ | `resources: { [slot]: Schedule.resources(rows, { name, icon, label, … }) }` + `events: { [slot]: Schedule.events(Record.bind(r, [patch]), { name, icon, title, start, end \| at, resource: { field, of }, … }) }` **❗** | Event kinds over records, on the resources' rows, ahead of `data`'s. `resources` without `events`, or a `resource` naming a slot `resources` has not, fails the build. | `planEvents`, `planPrintWorks` |
1274
+ | event kinds on `Plan.axis.number` / `Plan.axis.ordinal` **❗** | Refused at build, naming the axis and the kinds: an event is scheduled in time. An axis held in a variable is refused in the same words as the Plan is evaluated. | — |
1275
+ | `data`, beside `events` or `rows` | Optional: a Plan of event kinds, or of `rows` alone, needs none. A Plan with no rows from any source fails the build. | `planEvents` |
1276
+ | `rows: [Plan.chart({ …, pinned? }), Plan.over(…), …]` | Read-only rows after the event kinds' and `data`'s, each a fixed block; a pinned one sits under the ruler. | `planPrintWorks`, `planEventLinks` |
1277
+ | `Plan.over(data: Dict \| Data.bind handle, series: Series[])` **❗** | Series over a dataset, read only: a series declaring `edit` fails the build, naming `Schedule.events`. | `planEventLinks` |
1278
+ | `Plan.eventRef(kind: String, key: String): Plan.Types.RunRef` | An event for a link's end, wherever it draws; `Plan.link` takes it without `fromRun` / `toRun`. A link naming a kind `events` has not fails the build — or, when its kind is not known there (a list held in a variable or built in East, an event end held in a variable), is refused as the Plan is evaluated. | `planEventLinks` |
1279
+ | `canDrop: fn(Schedule.Types.Candidate) => Option<String>` | An event kind's drop veto, its message on the ghost, as the Calendar's — asked where a drag rests and again of the drop (#1196), its `from` the template's key, the backlog event's or the moved event's, its start, end and resource where the drop would put it; a `fn(DragEventType) => Boolean` vets drops on `data`'s rows instead. | `planPrintWorks` |
1280
+ | `applyMode: "batch" \| "auto"`, `date` | When the event kinds' drafts go — on Save, each kind with a change as one patch through its patch mutation, checked against what its drafts began from, or each ready gesture as it lands (#1194) — and the date brought into view first. | `planPrintWorks` (`date`, batch Save); auto mode described above |
1281
+
1282
+ Removed with #1191: `<Plan.View>` (`<Plan>`).
1283
+
1284
+ #### How event kinds draw (#1192)
1285
+
1286
+ Each resource kind is a block of rows, ahead of `data`'s. Every resource has a
1287
+ row per way the kinds placed on it draw — bars, tiles, chips, marks, in that
1288
+ order, kinds that draw alike sharing one — then its `measures`, each applied
1289
+ to the resource's row. Its first row carries the resource's label, sub line,
1290
+ value and status; the others name the kinds that draw that way. A kind with
1291
+ `group` sits under its group strips, and one with `parent` nests each resource
1292
+ under the one it names, to any depth, the parent's bars rolling its children's
1293
+ up. Each element is an event in the window, wearing its kind's icon, its
1294
+ lifecycle, its quantity, its lane and its status's warning ring.
1295
+
1296
+ The rows are read over the window the canvas draws and the periods it lays
1297
+ out beyond each edge, from the records as they stand, and read again when one
1298
+ commits. A commit that changes none of them redraws nothing, and a read that
1299
+ fails leaves the last rows standing and says why on the toolbar. Beside a
1300
+ paged `data` they lead every window, drawn once.
1301
+
1302
+ | Signature | Description | Example |
1303
+ | --- | --- | --- |
1304
+ | a row's id: `entry { series: "<slot>.<draw>", path: [group?, …parents, key] }` | A resource's rows, by its kind's slot and the way they draw (`presses.span`, `presses.marks`). A measure row's id is the measure's key and the resource's path, a strip's `"<slot>.group"` and its group. Selection, collapse, links and focus address them. | `planPrintWorks` |
1305
+ | an element's key: `East.print(Schedule.Types.EventRef { kind, key })` | Unique on a row the kinds that draw alike share; a popover, an element click and a link's event end name the event by it. | `planEventLinks` |
1306
+ | the Unassigned rows: `entry { series: "<kind>.unassigned", path: [draw] }` | An event whose resource is none, or names one its kind does not have, draws on its kind's Unassigned row, after every resource kind. | `planEvents` |
1307
+ | `Plan.link({ from: Plan.eventRef(kind, key), … })` | The link meets the event where it draws: a bar's end (a run shorter than the narrowest bar draws the narrowest), a chip's, in by the cell inset, a tile's cell, in its lane, and a mark's glyph. `planEventLinks` draws every way a link can, one link each. | `planEventLinks` |
1308
+ | a resource kind no event kind is placed on, with no `measures` **❗** | Refused at build: it would draw no rows. | — |
1309
+ | a key the event rows take (`<slot>`, `<slot>.<draw>`, `<slot>.group`, `<kind>.unassigned`) that a measure, a `data` series or a `Plan.over` series has **❗** | Refused at build, naming both: a row's id is its series' key and its path. | — |
1310
+
1311
+ #### Overlap feedback
1312
+
1313
+ With `overlaps: "warn"`, each overlapping event wears the shared warning ring.
1314
+ The toolbar chip after the summary counts pairs; selecting it selects the first
1315
+ pair in time order and brings its row into view, expanding its ancestors. The
1316
+ inspector lists the selected event's pairs or the selected resource's pairs.
1317
+ `planEvents` and `planPrintWorks` demonstrate this. Overlapping events are kept.
1318
+
1319
+ Bucket cells also preserve their events when space is short: they draw only
1320
+ whole tiles, followed by a `+n` menu listing those that do not fit. Choosing a
1321
+ menu item performs the same action as selecting that tile (`planTargetState`).
1322
+
1323
+ #### The frame (#1193)
1324
+
1325
+ `<Plan>` renders in its builder frame wherever it is used: the toolbar, the
1326
+ banners, the canvas in main and the footer, and the panes its props ask for —
1327
+ the library with `library` (#1195), the inspector with `inspector` (#1197);
1328
+ with neither there is no pane. It draws no border, so a host frames it or
1329
+ places it bare.
1330
+
1331
+ | Signature | Description | Example |
1332
+ | --- | --- | --- |
1333
+ | the toolbar | Every control the Plan draws outside its canvas, one row at every width: the rail folds first, then the Plan's own steps and the key search into its icon; the history item folds last. | `planTargetState`, `planRowDrop` |
1334
+ | the banners | Each session's — `data`'s, and each event kind's titled with its name (#1194): a Save's conflict, a refusal, an unknown outcome with Retry, a source out of date with Discard; each leaves when what it reports does, and one kind's leaves the other kinds' commits standing. | `planRowDrop`, `planPrintWorks` |
1335
+ | the footer | The counts — the event kinds' events in the window, their backlog, the changes pending and the last save of an event kind's record — then the author's `footer` and the transport line. | `planPrintWorks` |
1336
+ | `style={{ height: "fill" }}` / `maxHeight` | The whole Plan's: the canvas fills main and scrolls its own rows. | `planTargetState` |
1337
+ | a host's height, and no `style.height` | The canvas fills main and scrolls there; a host that gives none lets it grow with its rows. | — |
1338
+
1339
+ Removed with #1193: the canvas's own toolbar row (the frame's toolbar holds
1340
+ its items) and its review foot, the Series button (the library pane's
1341
+ Series tab, #1195) and the narrow layout's chip row (its items are the
1342
+ toolbar's).
1343
+
1344
+ #### The library pane (#1195)
1345
+
1346
+ `library` lists the start pane's tabs, in order, each a `Plan.library.*`
1347
+ call; left out, or empty, there is no library pane. Its cards are what a
1348
+ planner drags onto the canvas — an author's tab's onto the rows of `data`
1349
+ that make an item of a card (#1259), the event kinds' onto their resources
1350
+ (#1196) — and its Series tab is what a viewer shows and hides.
1351
+
1352
+ ```tsx
1353
+ const customers = $.let(Record.bind(planPrintCustomers, []));
1354
+ <Plan axis={axis}
1355
+ resources={{ presses: Schedule.resources(presses.read(), { name: "Presses", icon: "print", label: p => p.name, group: p => p.hall }) }}
1356
+ events={{ job: Schedule.events(jobs, {
1357
+ name: "Print job", icon: "file-lines", title: "title", start: "start", end: "end",
1358
+ resource: { field: "press", of: "presses" },
1359
+ backlog: { duration: j => variant("hours", j.sheets.divide(8000.0)), due: j => j.due },
1360
+ templates: [{ key: "brochure", name: "Brochure run", group: "Jobs", duration: variant("hours", 6.0), values: { … } }],
1361
+ }) }}
1362
+ library={[
1363
+ Plan.library.events(), // every kind's templates
1364
+ Plan.library.backlog(), // every kind's unscheduled events, by when they are due
1365
+ Plan.library.series(), // what a viewer shows and hides
1366
+ Plan.library.tab(customers.read(), { // the author's own cards
1367
+ name: "Customers", icon: "building",
1368
+ label: c => c.name, meta: c => some(c.trade), group: c => c.district,
1369
+ drop: c => Schedule.patch(PrintJob, { customer: c.name }), // what a card dropped on a job sets
1370
+ }),
1371
+ ]} />
1372
+ ```
1373
+
1374
+ | Signature | Description | Example |
1375
+ | --- | --- | --- |
1376
+ | `Plan.library.events()` **❗** | Every event kind's templates, under the kind's name and then the template's `group` (`Print job · Jobs`). A card is its kind's icon, its name and `Print job · 6 h · presses`: its kind, how long it runs (an instant kind's runs no time) and the resource kinds it is placed on. Dropped on a resource's row it makes its event there (#1196). Refused on a Plan with no event kinds. | `planEvents`, `planPrintWorks` |
1377
+ | `Plan.library.backlog()` **❗** | Every event kind's unscheduled events (a kind with Option times and a `backlog`), grouped by when they are due: Due this week (overdue included), Due next week, Later, No date — UTC weeks, from the Monday of the week the axis's `now` is in, else the week the Plan mounted in. A card is `6 h · Press A · due Fri 16` (`Unassigned` on no resource). It is read again as a kind's record commits, with every kind's drafts in place (#1196): a card dropped on a resource's row is scheduled and leaves it, an event dropped on the tab is unscheduled and joins it. Collapsed, the pane's rail counts it. Refused on a Plan with no event kinds. | `planEvents`, `planPrintWorks` |
1378
+ | `Plan.library.series()` **❗** | `Pick.Panel`'s list in the order the canvas draws: each resource kind and its measures, the event kinds, `data`'s series when they are picked (`pick`), and the Plan's `rows` — a hand-built row by its key, a `Plan.over` series by its own. Hiding an event kind hides its elements everywhere, its Unassigned row and any row only it draws on with them (a resource's first row is its own, and stays); a resource kind its rows; a measure, or one of `rows`, its rows — a `Plan.over` series' nested series with it. `data`'s series hide through their pick. The rest are kept per viewer under the Plan's `id`, and only while the library lists this tab. Refused on a Plan with nothing a viewer can hide. | `planPrintWorks` |
1379
+ | `Plan.library.tab(rows: Dict<K, R>, { name, icon?, label, meta?, group?, drop? })` **❗** | A card per row, its rows read as `Schedule.resources` reads them, accessors `(row, key)`: its label, its meta, the tab's icon, grouped by `group`, searched by key, label and meta. A click selects a card, and a click on the selected card lets it go. A key of another type than String is its card's key as East prints it. Its cards drag onto the rows of `data` whose series makes an item of a card (`edit.create`) — the drop's `from.key` the card's key, so `canDrop` and `create` read it as a Library card's — and the Plan takes them with no `id` or `sources` (#1259). | `planEvents`, `planPrintWorks`, `planRowDrop` |
1380
+ | `drop: (row, key) => Schedule.patch(KindRowType, { … })` **❗** | With it, each card drags onto an event too, while one of the patch's kind is on the canvas. What a card dropped on an event sets (#1196): the patch's type names the event kind it lands on, so a patch over no kind's row type, or over one two kinds share, is refused at build, naming the tab. Dropped on the event under the pointer it sets the patch's fields as one step (`Harbour Arts Society → Spring catalogue` on the ghost); refused between events (`Drop a customer onto an event`) and on another kind's (`Stops take no customer`). | `planEvents`, `planPrintWorks` |
1381
+ | `Schedule.patch(R, { field: value, … })` / `Schedule.Types.Patch(R)` | A patch over an event kind's row type: every field an `Option`, each field left out `none`; one set to `none` clears an Option field. | `planEvents` |
1382
+ | a tab listed twice — an author's by its name **❗** | Refused at build, naming it. | — |
1383
+
1384
+ The pane is the frame's start pane, 272px open: its open tab and whether it
1385
+ is collapsed are kept per viewer under the Plan's `id`, and below 560px of
1386
+ frame it opens from its rail over the canvas. On a touch screen the Series
1387
+ tab's search is a 44px field.
1388
+
1389
+ #### The inspector pane (#1197)
1390
+
1391
+ `inspector` gives the Plan its end pane: what is selected on the canvas. A
1392
+ click on an event's element — a bar, a tile, a chip or a mark of an event
1393
+ kind's rows — selects the event and its row, and the element wears the brand's
1394
+ ring; Shift, ⌘ or Ctrl adds an event to the selection or takes it out. A click
1395
+ on a row's name selects the row, and one on its plot names the bucket under the
1396
+ pointer too. Esc clears it all. An event kind may give its own inspector for
1397
+ one event, in place of the form over its `fields`:
1398
+
1399
+ ```tsx
1400
+ // A stop's own inspector: its title, and its kind on a segment — `update` writes the edited stop back.
1401
+ const inspectStop = $.const(East.function([PrintStop, FunctionType([PrintStop], NullType)], UIComponentType, ($, stop, update) => {
1402
+ const setKind = $.const(East.function([StringType], NullType, ($2, picked) => {
1403
+ const kind = $2.const(picked.equal("service").ifElse(
1404
+ () => East.value(variant("service", null), PrintStop.fields.kind),
1405
+ () => East.value(variant("plate_change", null), PrintStop.fields.kind)));
1406
+ $2(update({ title: stop.title, at: stop.at, press: stop.press, kind }));
1407
+ }));
1408
+ return <SegmentGroup value={stop.kind.getTag()} onChange={setKind} size="sm"
1409
+ items={[SegmentGroup.Item("plate_change", "Plate change"), SegmentGroup.Item("service", "Service")]} />;
1410
+ }));
1411
+ <Plan axis={axis} resources={{ presses: … }}
1412
+ events={{
1413
+ job: Schedule.events(jobs, { …, fields: { customer: Schedule.field.text({ label: "Customer" }) } }),
1414
+ stop: Schedule.events(stops, { name: "Stop", icon: "screwdriver-wrench", title: "title", at: "at",
1415
+ resource: { field: "press", of: "presses" }, inspector: inspectStop }),
1416
+ }}
1417
+ inspector />
1418
+ ```
1419
+
1420
+ | Signature | Description | Example |
1421
+ | --- | --- | --- |
1422
+ | `inspector` (`inspector={true}`) **❗** | The end pane, 320px. One event: its kind, its title, when it runs and its status; its resource, its start and end or its instant, its lane, its state and its quantity; its kind's form over `fields`, the fields its roles read left to their own lines; Duplicate and Delete; an overlaps banner lists this event's pairs. Several: how many, each kind's count, the list, and the bulk edit — the state, the resource, a shift of a day or an hour. A row: its resource's name, its lines and its group, its events in the window — how many, their hours, their quantities by unit — its overlapping pairs, and its measures at the bucket a click on its plot named; an Unassigned row, its kind's events on no resource; any other row, what it draws at that bucket. Nothing: the window's events, hours and backlog, and three hints. Collapsed, a rail naming what is selected. Refused on a Plan with no event kinds; `false`, or left out, no pane. | `planPrintWorks` |
1423
+ | `Schedule.events(record, { …, inspector: fn(R, fn(R) => Null) => UIComponentType })` **❗** | The kind's own inspector for one event, in place of its form, over the event's row; `update(edited)` writes the edited event back. Passed through untouched, called only where the pane draws it. A function over another row type, or with no writer, fails the build. Plan and Calendar use it when their optional `inspector` pane is present; read-only Calendar never calls its editing callback. | `planPrintWorks` |
1424
+ | the edits | Each one transaction of the Plan's history (#1194): a field of the kind's form, tinted while the record holds it otherwise; the kind's own inspector's `update`; Duplicate — each copy under a new key (a `String` key `-2`, `-3`, … after its own, an `Integer` key past the largest; a kind keyed otherwise has none), the copies then selected; Delete; and the bulk edit across kinds — the state, the resource (each event placed on that resource's kind), a shift of a day or an hour. They are off while a selected event's kind is saving or its record is not yet read. | `planPrintWorks` |
1425
+
1426
+ The pane is the frame's end pane: whether it is collapsed is kept per viewer
1427
+ under the Plan's `id`, and below 560px of frame it opens from its rail over
1428
+ the canvas.
1429
+
1430
+ #### Drag and drop over event kinds (#1196)
1431
+
1432
+ The event kinds' drags are built in: a Plan given `resources` and `events`
1433
+ takes them, and its `library` gives the cards. Each is one step of the Plan's
1434
+ one history (#1194), which Undo takes back. A drag starts after 4px and snaps
1435
+ to the resolution; its ghost says what lands where, or — red — why it can't.
1436
+ The panes slide off main while it lasts, and nothing drags in the narrow
1437
+ layout.
1438
+
1439
+ | Signature | Description | Example |
1440
+ | --- | --- | --- |
1441
+ | a template card → a resource's row | Makes an event of its kind at the bucket under the pointer — from the template's `at` on a day or longer — for the template's duration, under a new key (a String key the template's, made unique: `brochure-2`), selected. Any of a resource's rows takes it: a stop's template on a press's bars lands on the press. Refused on a resource of a kind its kind is not placed on (`Needs presses`), or where `canDrop` refuses. | `planPrintWorks` |
1442
+ | a backlog card → a resource's row | Schedules its event at the bucket under the pointer for its own duration, on the row's resource. The same refusals. | `planPrintWorks` |
1443
+ | a bar, tile, chip or mark → along its row, or another resource's | Moves its event — across rows writing the resource field. A selected element moves the selection with it: the others by the same units, those on its resource onto the row's. Refused onto a resource of a kind it is not placed on. | `planPrintWorks` |
1444
+ | a bar's or a chip's edge → along the axis | Resizes it, never shorter than one snap. | `planPrintWorks` |
1445
+ | an event → the Backlog tab | Unschedules it: its times none, its resource kept. Refused for a kind whose times are no Options (`Stops have no backlog`). No trash zone shows. | `planPrintWorks` |
1446
+ | an author's card → an event of its patch's kind | Sets the fields the patch sets on the event, as one step. Refused anywhere but an event, or on another kind's. | `planPrintWorks`, `planEvents` |
1447
+ | an element of an event its drafts changed | Wears the brand tint in a brand border (a mark, the tint's ring), in both themes. | `planPrintWorks` |
1448
+
1449
+ #### Large records, a window at a time (#1199)
1450
+
1451
+ A record too large to read whole is read a window at a time: an event kind
1452
+ through its record's indexes, and a resource kind paged as the canvas
1453
+ scrolls. An event kind given `window` — a paged read of a day index over its
1454
+ record, keyed by `Schedule.days` — reads only the days the canvas draws;
1455
+ given `backlogWindow`, a paged read of an index keyed by
1456
+ `Schedule.unscheduled`, its backlog; and given `entries`, a paged read of the
1457
+ record's own entries, one event by its key. A resource kind given its
1458
+ resources as a paged read pages them, 200 to a window, the key search seeking
1459
+ one. Neither record is ever read whole: not to draw, not to edit, not to save.
1460
+
1461
+ ```tsx
1462
+ // Package side: the jobs record and its two indexes (e3.recordIndex), each keyed by Schedule's own function.
1463
+ // export const jobsByDay = e3.recordIndex("jobs_by_day", jobs, { keys: … Schedule.days(start, end) … });
1464
+ // export const unscheduled = e3.recordIndex("jobs_unscheduled", jobs, { keys: … Schedule.unscheduled(job.start, job.due) … });
1465
+ <Reactive>{$ => {
1466
+ const presses = $.let(Data.bindPaged(pressesTask)); // a window of presses at a time
1467
+ const jobs = $.let(Record.bind(jobsRecord, [jobsPatch]));
1468
+ const days = $.let(Data.bindPaged(jobsRecord, { index: jobsByDay, join: true }));
1469
+ const backlog = $.let(Data.bindPaged(jobsRecord, { index: unscheduled, join: true }));
1470
+ const entries = $.let(Data.bindPaged(jobsRecord)); // one job by its key
1471
+ return <Plan axis={axis}
1472
+ resources={{ presses: Schedule.resources(presses, { name: "Presses", icon: "print", label: p => p.name, sub: p => some(p.hall) }) }}
1473
+ events={{ job: Schedule.events(jobs, {
1474
+ name: "Print job", icon: "file-lines", title: "title", start: "start", end: "end",
1475
+ resource: { field: "press", of: "presses" },
1476
+ backlog: { duration: j => variant("hours", j.sheets.divide(8000.0)), due: j => j.due },
1477
+ window: days, backlogWindow: backlog, entries,
1478
+ }) }} />;
1479
+ }}</Reactive>
1480
+ ```
1481
+
1482
+ | Signature | Description | Example |
1483
+ | --- | --- | --- |
1484
+ | `Schedule.events(record, { …, window: Data.bindPaged(record, { index, join: true }) })` **❗** | The kind's events over the days the canvas draws, read through a day index keyed by `Schedule.days` (a scheduled event filed under every day it runs into): the first day sought and the index's pages read from it; a pan seeks the day it brings in. An event filed under several days draws once, and the drafts draw over the window. Refused at build: an index of another record, or keyed otherwise; a `window` over Option times without `backlogWindow`; a `window` without `entries`. An index read without `join: true` is refused as it is read. | `planWindows` |
1485
+ | `backlogWindow: Data.bindPaged(record, { index, join: true })` **❗** | The kind's backlog — the library's Backlog tab and the footer's count — read through an index keyed by `Schedule.unscheduled`. Refused on a kind whose times are plain `DateTime`s. | `planWindows` |
1486
+ | `entries: Data.bindPaged(record)` **❗** | The record's own entries: one event by its key — the inspector's, a gesture's before its first draft, a Save's read back, a conflict's — its key sought and a one-row page read. Required beside `window`, refused without one. The kind's editing is a session over the record's revision: each change checked by the record against what it began from, and a Save's conflict naming each event another write moved, read by its key at the record's new revision, with who changed the record last. | `planWindows` |
1487
+ | `Schedule.resources(Data.bindPaged(record), { name, icon, label, … })` **❗** | A resource kind paged as the canvas scrolls: a window of resources at a time, the events on them drawn with them, the key search seeking a resource by its key, its types its page's `Dict`'s. Its resources keyed by `String`, with no `group` or `parent`; one paged kind per Plan, and none beside a paged `data`. A link's end on its rows is named by the row's id; the inspector and the backlog's cards name a resource once it is read by its key. An event on a resource it does not have draws on no row, and the bulk edit offers none of its resources. The Calendar refuses a paged read: it reads a kind's resources whole. | `planWindows` |
1488
+ | `Schedule.resources(rows, { window })` **❗** | Gone (#1199): refused at build, naming the paged form. | — |
1489
+ | a `ui()` task over them | A record bound with `Record.bind` and read with `Data.bindPaged` too is in its manifest's `records` and `pages`, never its `paths`: it is never preloaded or polled whole. | `planWindows` |
1490
+
1491
+ A key search stands as the canvas reads new rows: a pan, a draft or a commit
1492
+ to the jobs reads the presses' windows again over the same snapshot, and the
1493
+ search keeps its text, its matches and the view. Only a new snapshot of the
1494
+ presses asks it again, there.
1495
+
1496
+ ### The Sheet — `<Sheet>`
1497
+
1498
+ `<Sheet>` is the planning spreadsheet, and there is one: it renders in its
1499
+ builder frame wherever it is used — one toolbar holding every control the
1500
+ sheet has, the banners, the grid in main with its strip docked under it, and
1501
+ the footer — and its panes are optional props: `library`, before the grid,
1502
+ and `inspector`, after it. No prop, no pane. Its rows come from one of two
1503
+ sources:
1504
+
1505
+ - `record` — an e3 record bound with its patch door: its entries, one entry's
1506
+ rows or groups, or a large record a window at a time. Save is one patch
1507
+ commit through the record, and the footer gives the record's last save.
1508
+ - `data` — the host's rows: an array, a whole-value bind handle (`State.bind`,
1509
+ `Data.bind`) or a paged source (`Data.bindPaged`). Edits reach the host
1510
+ through `onApply`, `onUpdate` and `onPatch`; with none of them the sheet is
1511
+ read only.
1512
+
1513
+ Its columns are typed — a date, a quantity with its unit, an integer, text, a
1514
+ register lookup, reference or enum, a set of register members, a directed
1515
+ `from > to` LINK between register members as a typed value, a stamped
1516
+ read-only code, a custom parse / print pair — with a blank tail that invites
1517
+ the next row, typed parsing with a docked candidate strip, a copilot that
1518
+ fills cells and proposes whole rows from author East functions, a lens over a
1519
+ bound slice's narrowing with saved-view tabs, drag and drop, Excel
1520
+ round-tripping, and a key search over a paged source. Every change is a draft
1521
+ of an editing session, checked as it is made and applied as one checked
1522
+ batch. Where east-ui's `<Table>` displays rows, the Sheet is where a planner
1523
+ types them: reach for it when the rows are authored in place and written back.
1524
+
1525
+ The tag and its authoring vocabulary — `Sheet.column.*`, `Sheet.register.*`,
1526
+ `Sheet.driver`, `Sheet.link.*`, `Sheet.patch`, `Sheet.group`, `Sheet.subRows`,
1527
+ `Sheet.library.*`, `Sheet.field`, `Sheet.apply`, `Sheet.Types` — come from
1528
+ `@elaraai/e3-ui`, and the tags around it from `@elaraai/east-ui`. It moved
1529
+ here from east-ui (#1179), and `<Sheet.View>` and `<Sheet.Builder>` are one
1530
+ component now (#1216): a surface that wrote either writes `<Sheet>`, a
1531
+ builder's `id` is its `name`, and the sheet fills the box it is given —
1532
+ `style` holds only `gutterWidth`. Its words in React — `SheetMessagesProvider`
1533
+ and `sheetMessages` — are `@elaraai/e3-ui-components`'.
1534
+
1535
+ ```tsx
1536
+ /** @jsxImportSource @elaraai/e3-ui */
1537
+ import { Box, Reactive } from '@elaraai/east-ui';
1538
+ import { Record, Sheet } from '@elaraai/e3-ui';
1539
+ // Package side: export const jobs = e3.record("jobs", DictType(StringType, Job), new Map([…]));
1540
+ // export const jobsPatch = e3.mutation.patch(jobs);
1541
+ <Reactive>{$ => {
1542
+ const record = $.let(Record.bind(jobs, [jobsPatch]));
1543
+ return (
1544
+ <Box height="560px">
1545
+ <Sheet record={record} columns={{
1546
+ task: Sheet.column.text(Job, { header: "Task", width: "240px" }),
1547
+ start: Sheet.column.date(Job, { header: "Start", width: "96px" }),
1548
+ qty: Sheet.column.quantity(Job, { header: "Qty", width: "96px" }),
1549
+ }} />
1550
+ </Box>
1551
+ );
1552
+ }}</Reactive>
1553
+ ```
1554
+
1555
+ ```
1556
+ <Sheet record={Record.bind(r, [patch])} | data={rows} id="id" columns={{ start: Sheet.column.date(Row, {…}), qty: Sheet.column.quantity(Row, Driver, {…}), … }} library?={[…]} inspector? /> — the planning SPREADSHEET in its builder frame: typed columns over its rows (date · quantity + unit · integer · text · register lookup / reference / enum · a set of register members · a directed `from > to` LINK between register members as a TYPED value · stamped read-only codes · a custom parse / print pair), a blank tail that invites the next row, typed parsing with a docked candidate strip (nothing ever floats over the grid), a copilot that fills cells and proposes whole rows from author East functions, a lens over a bound slice's narrowing (hits keep their row numbers, the rest collapse into context bands) with saved-view tabs, drag and drop, Excel round-tripping, and a key search over a paged source. Declared the way east-ui's Table and the Plan are: every per-row fact is an accessor, the builders take the row type FIRST, and nothing at the author's side is addressed by a string name
1557
+ ├─ The frame: ONE toolbar holding every control the sheet has, in this order — the view tabs, the context switch, the match count, the key search, the slice's rail, the scope badge and the history item (a sheet with none of them, read only with no slice, has no toolbar). It is one row at every width: the rail folds first, then the sheet's own steps — the tabs into `+n`, the count, the context label, the strip closing up, the context switch — then the key search into its icon (which opens the box in a popover, the focus in it) and the view tabs into one chip naming the open view, its menu every view, `+ TAB` and the open view's close (#1221), and the history item last, to its buttons; on a touch screen every control there is a 44px tap target. The banners — a Save's conflict naming its rows and who changed the record last, a refusal with its reason, an unknown outcome and a failed confirmation read each with Retry, the out-of-date notice with Discard, and an `entry` the record does not hold; main — the grid, filling the room the panes leave and scrolling its own rows, the strip docked under it; the footer — the sheet's, and over a record its last save. ⌘Z undoes and ⇧⌘Z / ⌘Y redo from anywhere in the frame; a field being typed into keeps its own undo. The sheet fills its parent and draws no border: give it a box of its own height
1558
+ ├─ Rows — ONE of two sources (both, or neither, is refused):
1559
+ │ ├─ record — `Record.bind(r, [e3.mutation.patch(r)])` over a `Dict` record: its entries are the rows, in key order, each row's id its key's text (any key type: a non-String key by its `.east` text). `window={Data.bindPaged(r)}` reads the same record a window at a time. `entry={{ key, rows: F, id: I }}` is one entry's Array field `F`, in its own order, each row identified by the `String` field `I`; each entry keeps its own drafts, and a key the record does not hold opens empty and read only, named in a banner. With `group`, the entry's field holds groups, or `Sheet.Types.Entry(P, "lines")` entries with loose rows between them (`id` then names a field of both types); a record of groups is grouped the same way. Save is ONE patch commit, checked against what each row was when its edit began, confirmed by the rows the record reads back. Over a record `id`, `onApply` and `onUpdate` are refused (the record identifies and commits its rows); `entry` and `window` need a record
1560
+ │ └─ data — the host's rows: an `Array<R>` value / expression or a `$.let`-bound whole-value handle (`State.bind` / `Data.bind`) for the INLINE arm; a paged source for a WINDOWED arm — a `$.let`-bound `Data.bindPaged(…)` handle, recognised by its East type: `pinned` when it names its snapshot, which `onApply` needs, `paged` when it is the shape a UI exported before `revision` / `refresh`, which names none — positional (`Array<R>` windows) or keyed (`Dict<String, R>` windows; the key is the row id). When a pinned source's `revision()` moves (`Data.bindPaged` follows each write to its dataset), the sheet re-reads its resident windows at the new snapshot IN PLACE: the rows on screen stay until theirs land (no remount, no empty frame), the scroll position and row heights hold, and a standing key search is cleared. A failure stays where it happened: a window the source cannot read is ONE band where its rows would be — the elements it covers, the reason and a Retry — while the windows around it keep working and the rows after it keep their numbers; a `total()` or `revision()` that throws is said on the footer's transport line with a Retry while the rows stay; only a source that fails before anything lands replaces the grid, with a Retry. A row that throws while it draws is a one-row diagnostic. A `Dict` inline is refused (a sorted map would sit rows in key order, not the planner's) — a record's entries come through `record`. `id` (required on a positional source) names the `String` field that identifies a row; over entries of groups and loose rows, a field of BOTH types
1561
+ ├─ Props:
1562
+ │ ├─ columns (required) — keyed by the row's fields and checked per key (a key that is not a field, a date under a `String` field, a builder over another row type: type errors): Sheet.column.text(R, cfg) · date(R, { base?, format?, level?, actual? }) — the common date field (`dd / mm / yyyy` segments); pasted text takes the B§3 grammar (`+3d`, `4d` from `base`, `fri`, ISO, `d/m[/yy]`); `level: r => …` reads each row's date at a Sheet.Types.DateLevel ("week" | "day" | "range" | "time" — no shifts: a host with shifts uses a `custom` kind) and `actual: r => Option<DateTime>` is when the work really happened (the cell then prints it with its difference, the wanted date becoming the cell's detail) · quantity(R, cfg) or quantity(R, D, { uom: d => d.uom, format? }) — a float with the DRIVER row's unit in the common number field, in the viewer's language (#852): the cell groups (1,234.5 — German 1.234,5; through `format` when declared), the edit box and copy are bare (1234.5 — German 1234,5), typed and pasted text reads the viewer's separators (pasted `1.2k` / `1.2m`, German `1,5k`, still parse; a typed quantity rounds to a whole number), and ⏎ on an unchanged edit box writes nothing · integer(R, cfg) · lookup(R, { options? }) — the DRIVER column only (scored candidates from its register) · reference(R, register, cfg) — a lookup over a flat member list · enum(R, register, { options? }) — an upper-cased register word with a valence dot · set(R, register, { members?, multiple?, store? }) — comma members, the link grammar without an arrow · link(R, D, register, { to? | from?, members, multiple?, sides?, arity?, check?, store?, options? }) — `from > to`, the split cell; `members: [{ kind, identified?, countable?, resolvesTo?, ranged? }]` — `ranged` offers and prints runs of consecutive codes as one range. `options` (enum / lookup / link) is fn(Sheet.Types.DraftContext(R, D)) => Option<Array<String>> — the member keys the row is OFFERED (`none` = the whole register; typed text still resolves against the whole register) · stamped(R, { owner? }) — read-only, skipped by paste and clear · custom(R, { accepts, parse, print }) — an author parse / print pair over the field's payload. Every kind takes { header, sub, width, editable?, fill?, detail? } (`header` + `sub` are the two header lines; `fill` = providers, the first that yields wins; `detail: r => String | Option<String>` is the text the hover and the strip show beyond the value); text / date / quantity / integer also take `value: r => …` for a derived READ-ONLY projection on any field. A set / link column sits on a `Sheet.Types.Link` field, an `Array<Sheet.Types.Member>` field (the other half named by `to` / `from`), or a `String` field the grammar parses on read and prints on commit per `store` ("asTyped" | "canonical" — the register's labels)
1563
+ │ ├─ group (optional) — Sheet.group(P, "lines", { title, sub?, cells?, folded?, noun? }): the rows are GROUPS whose lines live in one `Array<L>` field; `columns` are declared over `L`; `cells` = band cells (Sheet.group.cell.*) keyed by the line column they sit under; `noun: { singular, plural }` is the word the renderer prints for a group (omitted, the sheet says its own in the viewer's language — "group" / "groups" in English, #861). LOOSE rows between the groups (#846): rows of Sheet.Types.Entry(P, "lines") entries — each `variant("group", P)` or `variant("row", L)` — and a row entry draws as a plain row: no band or rail, numbered in the groups' sequence, its own cells. The seam above a band or beside a loose row inserts a loose row (a line's seam and a group's blank line still insert a line); loose rows delete, paste and count on their own ("2 groups · 3 lines · 3 loose rows"), fold-all passes them by and no band sticks over them. A new line there gets its `id` field minted unless `newRow` supplies one; drafts, checks and the change set carry the entry (a draft is `variant("group", …)` or `variant("row", …)`, a loose row's DraftContext has `group: none`)
1564
+ │ ├─ subRows (optional) — Sheet.subRows(R, { arrayField: (item, row) => Sheet.subRow({ code?, name, chips?, facets?, id? }) }): READ-ONLY rows under each line (a flat row) that share none of its columns — keyed like `columns` by the array fields of the type the columns are built over (a grouped sheet: the line type), key order = display order; `facets` is a label → String | Option<String> record (a `none` drops out); the renderer owns the tree, the `{line}.{n}` index, folding and search
1565
+ │ ├─ driver (optional) — Sheet.driver(column, rows, { key, label, aliases?, meta? }): the `lookup` column whose member decides what the row does; its rows are the register and its row type `D` is what a quantity's `uom`, a link's `sides` and every copilot function (`ctx.driver`) read
1566
+ │ ├─ registers (optional) — { name: Sheet.register.members(rows, { kind, key, label, aliases?, meta?, parent?, tone? }) | Sheet.register.concat([…]) }: the lookup tables reference / enum / set / link columns resolve against; accessors receive `(value, key)` (a `Dict<String, T>` register reads its key as the second argument; an Array's key is its index); duplicate keys fold, first wins — so a family kind ("CNC router" from every router) declares one member per distinct value
1567
+ │ ├─ owned (optional) — accessor r => Bool: rows the upstream system owns — no copilot, stamped columns read-only
1568
+ │ ├─ suggest (optional) — { ahead?, triggers?, ghost?, propose: [fn] }: the copilot's row proposers — East functions (sync, or async for a model call) over Sheet.Types.DraftContext(R, D) — current draft row and neighbours, rowIndex, driver: Option<D> and today; draft fields are missing | value(T) | invalid(String), so guard with hasTag("value") before unwrap("value") — returning Array<Sheet.Types.Proposal(R)> ({ patch: Sheet.patch(R, { … }), meta }); a column's `fill` providers are the same shape returning Option<Sheet.Types.Fill(T)> ({ value, meta }). The first that yields wins; fills CHAIN in column order (a later column sees the earlier fills as if taken); an async one shows a pending chip in the strip and the newest context wins; a rejected fill / proposal is remembered for the session
1569
+ │ ├─ slice + affordances (optional) — bound slice chrome on the toolbar (default ["search"]; filter / cohort allowed; brush / legend / breakdown refused — no axis, no series): the sheet NEVER narrows — it draws the narrowing as the LENS: hits keep brand row numbers, ±0 / ±1 / ±3 context rows show either side, the rest collapse into bands whose pill opens 1 · 3 · 10 · all rows at a time, the count reads `n matches · m context`, no blank tail. The lens matches every declared column, the ones a viewer hid too. A Link column is searched through `Slice.config`'s `text` projection (`stations: { label: "Work centres", text: r => Sheet.link.print(r.stations) }`); a field the slice narrows on must be a COLUMN of the sheet. Over a paged source the lens is scope-badged "loaded rows only" and a keyed source's `search` becomes a KEY SEARCH over `seek` (the jump rebases residency and, once the match's window is in, lands the ring on the match and scrolls to it — until then the jump owns the viewport, so a scroll report from where the sheet was cannot undo it; a match whose window cannot be read shows its failed band instead). The ring, a range and an open editor stay on their rows as windows land around them
1570
+ │ ├─ views / activeView (optional) — `views` is a whole-value bind handle of Array<Sheet.Types.View> (`State.bind` keeps them per viewer, `Data.bind` shares them): saved views = slice-state snapshots plus the lens's context and reveals, evaluated live as TABS — the pinned whole-sheet tab, `+ TAB` snapshot (named from the query), live match counts, the dirty dot when the slice drifts from the tab, ⏎ update / esc revert, × or middle-click close, double-click rename, drag reorder — on a row short of room, one chip naming the open view, its menu every view, `+ TAB` and the open view's close (#1221); every change lands at once and is written back through the handle (`onViewsChange` is refused); `activeView` opens a tab and is followed when the host moves it
1571
+ │ ├─ onUpdate (optional, `data` only, INLINE arm) — fn(Array<R>) => Null over a LIVE data bind handle: reads the latest collection, checks the batch base and writes the complete result once. Hidden fields survive. Pass data={rows} and onUpdate={rows.write}; a captured array is refused for this adapter
1572
+ │ ├─ onPatch / onApply (optional) — onPatch: fn(Sheet.Types.PatchEvent(E)) => Null observes one draft gesture including incomplete values (either source); onApply (`data` only): sync/async fn(Sheet.Types.ChangeSet(E)) => Sheet.Types.ApplyResult persists a complete checked batch. Paged writes require revision/refresh, atomic host application and request-id deduplication
1573
+ │ ├─ applyMode (optional) — "batch" (default: the history item's Save sends the batch) | "auto" (each ready gesture goes at once, through the same acknowledgement path)
1574
+ │ ├─ newRow / newGroup / ready (optional) — newRow: fn(NewRow) => Patch(R) supplies defaults, including hidden fields; newGroup: fn(NewGroup) => Patch(G) a new group's; ready.row: fn(Draft(R), DraftContext(R, D)) => Readiness adds business rules; ready.group: fn(DraftGroup(G, "rows")) => Readiness checks grouped drafts. Required fields and valid parsing are always checked; optional absence becomes none
1575
+ │ ├─ edits (optional) — insertRows / removeRows gate structure independently of cell edits; insertGroups / removeGroups require grouping. moveRows: "none" | "within" | "between" and moveGroups say what a grip may move. Keyed top-level creation uses key order; positional insertion uses gutter buttons, the selection strip or Alt+Insert / Alt+Shift+Insert
1576
+ │ ├─ onSelect / selection (optional) — the ring reported as { rowId, line, key }; give `selection` and the ring is CONTROLLED (follows the value, scrolls into view, every move still reports)
1577
+ │ ├─ newRowId (optional) — fn() => String minting inserted rows' ids (else the renderer mints one); over a record keyed by a non-String key, the new row's key as its `.east` text — required there unless `edits` inserts no row
1578
+ │ ├─ readOnly / blanks / density (optional) — the whole sheet read-only · padding rows below the last real one (default 18; typing into one INSERTS a row after the last real one — blanks are padding, never rows) · row rhythm
1579
+ │ ├─ footer (optional) — [{ text, tone? }] counts; a paged source adds the transport line ("N loaded of M · Loading…")
1580
+ │ ├─ style (optional) — { gutterWidth } — the sheet fills the box it is given and scrolls its own rows there
1581
+ │ └─ name (optional) — names the sheet when a surface holds two: its panes' open tab and collapsed state, the columns a viewer hides, its library's drag source and its drop target are kept under it
1582
+ ├─ Panes — optional props, each its own; the examples show every combination (none, a library, an inspector, both):
1583
+ │ ├─ library (optional) — the start pane's tabs, in order, each a `Sheet.library.*` call: `rows()` — the templates, by their group, each card saying what it sets; `columns()` — the declared columns, each with its kind and an eye that hides it from the grid per viewer (the last shown stays; the lens still matches a hidden one; a sheet whose library lists no Columns tab hides none); `tab(data, { name, icon?, key, label, meta?, group?, drop? })` — the author's own cards from an Array or a `Dict<String, T>` (its key the accessors' second argument), searched by key, label and meta; `drop: (row, key) => Sheet.patch(R | G, …)` sets a row's fields where a card lands, or a band's when the patch is over the group type. Left out, or empty, no library pane (SB59). Collapsed, the pane is a rail with the templates' count
1584
+ │ ├─ templates (optional) — { rows?: [{ key, name, group?, values: Sheet.patch(R, …) }], groups?: [{ …, values: Sheet.patch(P, …) }] }: the Rows tab's cards; a dropped card is `newRow`'s (`newGroup`'s) defaults with the template's fields over them; a key repeated, or a group template on a flat sheet, is refused
1585
+ │ ├─ inspector (optional) — given alone (`inspector`, `inspector={true}`): the end pane's Details shows the selected row's every field — through its column's kind, or by its type (a field no column shows included) — tinted where it differs from what the source holds, each edit ONE transaction; several rows selected, a column set across them as one step; a band, the group's own fields, Add line, Duplicate and Delete with its lines; Issues lists the batch's issues by row, each going to its cell (over a paged source, sought by its key). `inspector={East.function([R, FunctionType([R], NullType)], UIComponentType, ($, row, update) => …)}` — the author's own Details for a complete row (SB58), passed through untouched and called where Details draws; `update(edited)` is one transaction; a row whose draft is still incomplete shows the form. With nothing selected, Details counts the rows, the pending drafts and the issues, and over a record says the last commit and who made it. Left out, no inspector pane
1586
+ │ └─ fields / groupFields (optional, with `inspector`) — the inspector form's hints by field — `Sheet.field.*`, east-ui's `Fields`: a label, a help line, an editor, read only or hidden; a column's kind is its field's default (SB10). Given without an inspector they are refused
1587
+ ├─ Drag and drop: a template lands on the seam it is dropped on — a row beside a row, a line in the group under the pointer, a group between groups, or, on a keyed source, where its key sorts; an author's card sets its patch's fields on the row or band it lands on; a row's, a line's or a band's grip moves it, as `edits` allows (a keyed source's rows and groups have no grip). The ghost's caption says where, and turns red where a drop is refused; ⏎ on a card does what a drop below the ring would; each drop is one transaction. On a coarse pointer a frame too narrow for the touch gutter beside the first column folds it (#1215): each row's actions go into one 44px row-actions button — the row's grip and its menu
1588
+ ├─ Keyboard (B§6): arrows / ⇧arrows (↓ on the last row appends — not under a lens or an unexhausted paged source) · ⇥ / ⇧⇥ walk the copilot's fills, then take rows, then move · ⏎ takes the next suggestion, else edits with the value selected (F2 too); a printable key seeds a fresh edit · ⌘⏎ fills the row (one undo step), ⌘⇧⏎ takes everything · esc ladder, one rung per press: editor → chip selection → selected proposal → row fill → every suggestion → range → dirty tab revert → the whole sheet · ⌫ clears cells (never a stamped one) or deletes whole selected rows · ⌘C / ⌘V round-trip with Excel (a link cell as two columns) · ⌘/ and ⌘F reach the toolbar's search: the key search — its box, or, folded to its icon, the box in its popover, opened (#1221) — else the rail's search box. In a link editor: `,` resolves a member, `>` hops From → To, ⇥ takes the ghost → a predicted chip → hops → commits right, ⌫ pops the last chip
1589
+ ├─ Localization (#861): every word the sheet says itself — the toolbar and the view tabs, the header, the rows, bands and gap pills, the strip and the editor, the footer and the history item, the banners, the panes, the insertion chips, and the message each gesture leaves — comes from ONE typed message table, its counts in the LOCALE react-aria's `<I18nProvider locale="de-DE">` sets (the browser's language otherwise). Host React code overrides any subset of the words for a subtree with `<SheetMessagesProvider messages={GERMAN}>` (@elaraai/e3-ui-components; `sheetMessages` is the English table — each message a function of named, already-formatted parameters, plus the raw `n` for plurals; define the overrides ONCE, not per render — providers nest). The message a gesture leaves is kept as data and worded as it shows, so a new table re-words it. What the AUTHOR wrote is data and never translated: headers and subs, a group's `noun`, register labels and metas, lock tags, footer items, library tab names; the date and link GRAMMARS keep their forms (day-first dates, `TBC`, `N x kind`), and the issues a patch event carries to the host stay in English (the sheet shows them in its words)
1590
+ └─ Factories:
1591
+ ├─ Sheet.column.text / date / quantity / integer / lookup / reference / enum / set / link / stamped / custom(R, …) — the column builders (see `columns`); Sheet.driver(column, rows, accessors) — the driver; Sheet.register.members(rows, accessors) / Sheet.register.concat([…]) — registers
1592
+ ├─ Sheet.link.parse(text, members) / Sheet.link.print(link) — the link grammar as East functions (`R2140, Bay 2 > 4 x CNC router`: codes and aliases, ranges `R2140-45`, counted `N x kind`, `TBC`, free text kept as a `text` member — never a refusal) · Sheet.link.arity(half, implied) — how many members a half should hold, `implied: fn(Context(R, D)) => Option<Sheet.Types.Counted>` (the strip reads "n × kind implied · k named") · Sheet.link.check.exists() and author checks fn(Sheet.Types.CheckContext(R)) => Option<String> — a `some(message)` FLAGS the member (warn chip + title), never blocks
1593
+ ├─ Sheet.patch(R, { field: value, … }) — a row patch (omitted fields `none`): a proposal's row, where the runner writes only the fields with editable columns, a template's values, a card's drop, or the explicit defaults `newRow` / `newGroup` return for a new row, hidden fields included (a field left `none` starts missing)
1594
+ ├─ Sheet.subRows(R, sources) / Sheet.subRow({ code?, name, chips?, facets?, id? }) — sub rows (see `subRows`); a left-out `code` / `id` is "", `chips` / `facets` []
1595
+ ├─ Sheet.library.rows() / columns() / tab(data, config) — the library's tabs; Sheet.field.* — the inspector's hints (east-ui's `Fields`)
1596
+ ├─ Sheet.apply(E, idField) — the checked batch applier as an East function: fn(entries, Sheet.Types.ChangeSet(E), revision: Option<String>) => Sheet.Types.Applied(E) — the base (snapshot or revision) is checked first, then the whole batch applies or none of it does (`conflict` says why); `E` is the row struct or a Sheet.Types.Entry(G, "rows") union of groups and ungrouped rows. Request deduplication stays with the host's `onApply`. It IS east-ui's shared `Editing.apply` (#879); a keyed Dict source applies with `Editing.apply(DictType(K, E))` — entries addressed by key, placed `keyOrder`
1597
+ └─ Sheet.Types.DraftContext(R, D) / Draft(R) / Fill(T) / Patch(R) / Proposal(R) / PatchEvent(E) / ChangeSet(E) / Applied(E) / Entry(G, "rows") / ApplyResult / Readiness / CheckContext(R) — typed contracts for providers, drafts, checked application and checks; grouped contexts use (G, "rows", D). The transaction and draft types are east-ui's shared editing contract's (`Editing.Types.*`, #879) under their Sheet names — the same values. Sheet.Types.Link / Member / Cell / Row / Line / SubRow / Facet / DateLevel / Noun / View / Selection / Counted / Sides / RegisterMember are shared value and wire types.
1598
+ ```
1599
+
1600
+ #### Drafts and checked application
1601
+
1602
+ The row's `StructType` defines completeness, including fields without columns.
1603
+ Columns define editing and parsing. Missing optional fields normalize to `none`;
1604
+ missing required fields and invalid text block the entire batch. Optional
1605
+ `ready.row` / `ready.group` business rules cannot bypass these automatic checks.
1606
+
1607
+ ```tsx
1608
+ <Sheet data={jobs} id="id"
1609
+ columns={{ task: Sheet.column.text(JobType), qty: Sheet.column.integer(JobType) }}
1610
+ onUpdate={jobs.write} />
1611
+ ```
1612
+
1613
+ Here `jobs` is a live `State.bind` or `Data.bind` handle over `ArrayType(JobType)`.
1614
+ `onUpdate` reads the latest collection when applying, checks the original batch
1615
+ base and writes once. Use `onPatch` for a journal of individual gestures,
1616
+ including incomplete drafts, and `onApply` for host transactions. A paged host
1617
+ must atomically check its revision, deduplicate the request id and return the
1618
+ committed revision. An append-only journal is not an application acknowledgement.
1619
+ An unknown outcome retries the same frozen request.
1620
+
1621
+ A record's rows are `record`'s: the sheet reads them and commits through the
1622
+ record's patch door, every example sheet that writes is bound this way (#1180).
1623
+ Rows that are the host's but kept in an e3 record — one entry's Array field,
1624
+ read and shaped before the sheet sees them — commit through `Record.onApply`
1625
+ over that entry's rows:
1626
+
1627
+ ```tsx
1628
+ // Package side: export const plans = e3.record("plans", DictType(StringType, Plan), new Map([["week", { jobs: [] }]]));
1629
+ // export const plansPatch = e3.mutation.patch(plans);
1630
+ const record = $.let(Record.bind(plans, [plansPatch]));
1631
+ const jobs = $.let(record.read().get("week").jobs);
1632
+ const onApply = $.const(Record.onApply(record, {
1633
+ entry: "week",
1634
+ get: East.function([Plan], ArrayType(JobType), (_$, plan) => plan.jobs),
1635
+ set: East.function([Plan, ArrayType(JobType)], Plan, (_$, _plan, next) => ({ jobs: next })),
1636
+ idField: "id",
1637
+ }));
1638
+ <Sheet data={jobs} id="id" columns={{ /* … */ }} onApply={onApply} />
1639
+ ```
1640
+
1641
+ The batch is checked against the rows the edit began from, and the patch
1642
+ reaches the entry's rows and nothing else of it; groups, and entries of groups
1643
+ and loose rows, commit the same way. A record's own entries as the rows,
1644
+ `Record.onApply(record)`, page in key order instead (`recordSheetApply`).
1645
+
1646
+ The transaction contract is every editable collection's, not the Sheet's alone
1647
+ (#879): east-ui's `Editing.apply` and `Editing.Types.*` — `ChangeSet`,
1648
+ `PatchEvent`, `Readiness`, `Origin`, `Draft`, `Entry` and the rest — are the
1649
+ very values `Sheet.apply` and `Sheet.Types.*` name, and the Plan's session is
1650
+ the same one: a gesture's `origin` names its `resize` and `drop` too. A keyed `Dict` source applies with
1651
+ `Editing.apply(DictType(K, E))`: each change names its entry by key (a
1652
+ `String` key as it is, any other key by its `.east` text), and a new entry is
1653
+ placed `keyOrder`. The east-ui skill documents the contract.
1654
+
1655
+ **Draft and editing contracts**
1656
+
1657
+ | Signature | Description | Example |
1658
+ | --- | --- | --- |
1659
+ | `Sheet.Types.Draft(R)` | Each field is missing / value(T) / invalid(String). | `sheetWeeks` |
1660
+ | `Sheet.Types.DraftContext(R, D)` | Current draft row, neighbours and optional driver; grouped overload `(G, "rows", D)`. | `sheetWorkshop` |
1661
+ | `newRow: fn(NewRow) => Patch(R)` | Explicit defaults for newly inserted drafts, including required hidden fields. | `sheetBatches` |
1662
+ | `ready.row: fn(Draft(R), DraftContext(R)) => Readiness` | Synchronous business checks alongside mandatory schema checks. | `sheetWeeks` |
1663
+ | `onPatch: fn(PatchEvent(E)) => Null` | Draft contents, placement, origin and readiness once per gesture. | `sheetWeeks` |
1664
+ | `onApply: fn(ChangeSet(E)) => ApplyResult` | Complete checked batch; supports async callbacks and safe retries. `Record.onApply` commits it to an e3 record. | `sheetVariants`, `recordSheetApply` |
1665
+ | `Sheet.apply(E, "id")` | Applies a checked batch to a collection: the whole batch, or a conflict saying why. | `sheetApplyBatch` |
1666
+ | `Editing.apply(E, "id")` / `Editing.apply(DictType(K, E))` | The shared applier (#879) — an Array by its identity field, or a keyed Dict by key (`Editing.Types.ChangeSet(E, K)`). | `editingApplyBatch`, `editingApplyKeyed` (east-ui) |
1667
+ | `Sheet.Types.Entry(G, "rows")` | Groups with their rows beside ungrouped rows, as one union; `Sheet.apply`, `DraftEntry` and `PatchEvent` take it. | `sheetApplyEntries` |
1668
+ | rows of `Sheet.Types.Entry(G, "rows")` + `group={Sheet.group(G, "rows", …)}` | Loose rows between the groups: a row entry is a plain row of the line type; `id` names a `String` field of both types. | `sheetLoose` |
1669
+ | `edits: { insertRows?, removeRows?, insertGroups?, removeGroups?, moveRows?, moveGroups? }` | Structure permissions; group flags require grouping; keyed top-level movement is refused. The grips move rows, lines and groups as these allow. | `sheetPaged`, `sheetBatches` |
1670
+
1671
+ Providers receive drafts: test `field.hasTag("value")` before reading
1672
+ `field.unwrap("value")`. They can fill a row before its remaining fields are
1673
+ complete. Constructors can supply hidden fields; copilot patches target editable
1674
+ columns. Typing, paste, fill, drops and accepted suggestions share the
1675
+ transaction path and Undo/Redo.
1676
+
1677
+ #### Sub rows and column rules
1678
+
1679
+ Sub rows show a line's own records (operations, bookings) without giving them
1680
+ columns; column rules say what a cell offers, how deep a date reads, and what a
1681
+ cell says beyond its value. Rule accessors (`level`, `actual`, `detail`) run in
1682
+ the row projection, so they follow the host's rows, not an open edit.
1683
+
1684
+ | Signature | Description | Example |
1685
+ | --- | --- | --- |
1686
+ | `subRows={Sheet.subRows(L, { field: (item, row) => Sheet.subRow({…}) })}` | Read-only sub rows per array field, in key order; a variant source matches arm by arm. | `sheetBatches` |
1687
+ | `Sheet.group(P, "lines", { title, noun: { singular, plural } })` | The host's word for a group; omitted, the sheet says its own in the viewer's language. | `sheetBatches` |
1688
+ | `options: fn(DraftContext(R, D)) => Option<Array<String>>` | enum / lookup / link: the members a row is offered; `none` = all. | `sheetWeeks` |
1689
+ | `date(R, { level: r => DateLevel, actual: r => Option<DateTime> })` | Read the date at the row's level; print the actual once it happened. | `sheetWeeks` |
1690
+ | `detail: r => String \| Option<String>` | Text the hover and the strip show beyond the cell's value. | `sheetWeeks` |
1691
+ | `members: [{ kind, identified: true, ranged: true }]` | Offer and print runs of consecutive codes as one range. | `sheetWeeks` |
1692
+
1693
+ #### The rows, the panes and the frame
1694
+
1695
+ | Signature | Description | Example |
1696
+ | --- | --- | --- |
1697
+ | **The rows** | | |
1698
+ | `record: Record.bind(r, [e3.mutation.patch(r)])` **❗** | A `Dict` record bound with its patch door; its entries are the rows, in key order. | `sheetBasic` |
1699
+ | `window: Data.bindPaged(r)` **❗** | The same record's entries, a window at a time; never with `entry`. | `sheetPaged` |
1700
+ | `entry: { key, rows: F, id: I }` **❗** | One entry's Array field `F`, in its own order; `I` a `String` field of its rows. | `sheetWeeks` |
1701
+ | `entry` + `group: Sheet.group(P, "lines", …)` | `F` holds groups, or `Sheet.Types.Entry(P, "lines")` entries, loose rows between the groups. | `sheetBatches`, `sheetLoose` |
1702
+ | `group` over the record's entries | Each entry a group, its lines its Array field. | `sheetWorkshop` |
1703
+ | `data` + `id` (+ `onApply` / `onUpdate`) | The host's rows: an array, a bind handle or a paged source. | `sheetVariants`, `sheetStress` |
1704
+ | `record` with `data`, or neither; `id` / `onApply` / `onUpdate` over a record; `entry` / `window` with `data` **❗** | Refused, naming the prop and the fix. | — |
1705
+ | **The panes** | | |
1706
+ | `library: [Sheet.library.rows(), Sheet.library.columns(), Sheet.library.tab(data, { name, key, label, drop?, … })]` **❗** | The start pane's tabs, in order; none, no pane. A tab's `drop` patch over the row type lands on rows, over the group type on bands. | `sheetLibrary`, `sheetWorkshop` |
1707
+ | `templates: { rows?: [{ key, name, group?, values: Sheet.patch(R, …) }], groups?: […Sheet.patch(P, …)] }` **❗** | The Rows tab's cards; a key repeated, or a group template on a flat sheet, is refused. | `sheetWorkshop`, `sheetBatches` |
1708
+ | `inspector` | The end pane: Details for what is selected, its every field, and Issues. | `sheetWorkshop`, `sheetBatches` |
1709
+ | `inspector: fn(R, fn(R) => Null) => UIComponentType` **❗** | The author's own Details for a complete row; a row still missing a field shows the form. | `sheetWeeks` |
1710
+ | `fields: { f: Sheet.field.readonly() \| Sheet.field.hidden() \| … }` / `groupFields` **❗** | The inspector form's hints, by field; refused without an inspector. | `sheetWorkshop`, `sheetBatches` |
1711
+ | **The frame** | | |
1712
+ | the toolbar | Every control the sheet has, one row at every width: the rail folds first, then the sheet's own steps, then the key search into its icon and the view tabs into one chip (#1221); the history item folds last. ⌘F reaches the key search in either form. | `sheetWorkshop`, `sheetPaged` |
1713
+ | `views: State.bind([ArrayType(Sheet.Types.View)], key, [])` **❗** | The saved views, as a bind handle; `onViewsChange` is refused. | `sheetWorkshop`, `sheetStress` |
1714
+ | `name: String` | Names the sheet when a surface holds two; its panes' state, the columns hidden, its drag source and its drop target follow it. | every example but `sheetBasic` |
1715
+
1716
+ Removed with #1216: `<Sheet.View>` and `<Sheet.Builder>` (both `<Sheet>`), a
1717
+ builder's `id` (`name`), `onViewsChange` (`views` is a bind handle) and
1718
+ `style.height` / `maxHeight` (the sheet fills its box).
1719
+
1720
+ ### The Flowchart — `<Flowchart>`
1721
+
1722
+ `<Flowchart>` is the state-transition flowchart: states as nodes in ORDERED
1723
+ phase lanes — its layout derived from the lanes and the links, never from
1724
+ coordinates — H/V-routed transition arrows, optional per-link decision
1725
+ triggers (lettered diamonds) and evidence-weighted strokes. The dim-ladder
1726
+ highlight and the selection grammar are built in, and what is selected shows
1727
+ in its inspector. Where east-ui's
1728
+ `<Schematic>` places items at
1729
+ world coordinates, the Flowchart lays its states out itself, for reading a
1730
+ process flow.
1731
+
1732
+ There is one Flowchart, and it renders in its builder frame wherever it is
1733
+ used (#1245): one toolbar — find state, LR · TD, the freshness chip and, over
1734
+ `data` with a slice, the slice's rail, and where it edits the history item —
1735
+ the canvas in main, filling it and scrolling both ways inside it, and the
1736
+ footer's counts: over many flows the open flow's name first, where it edits
1737
+ the changes waiting on Save, and over a record its last save. Its library
1738
+ pane, when `library` lists a tab, holds the tabs it lists, in its order: the
1739
+ Flows tab (#1246), state and transition templates and the author's own cards,
1740
+ each tab its own bound rows (#1248, below), whose cards drop on the canvas
1741
+ (#1249, below). Its inspector, on by default, is the end pane: what is
1742
+ selected, through its form, and the open flow's issues (#1250, below). It
1743
+ fills the box it is given and draws no border: give it a box of its own
1744
+ height.
1745
+
1746
+ Its flows come from one of two sources:
1747
+
1748
+ - **`record`** — an e3 record of `Flowchart.Types.Flows`, flows by name, bound
1749
+ with its patch mutation: `Record.bind(r, [e3.mutation.patch(r)])`. The usual
1750
+ case: the canvas shows the flow opened last, else `flow`, else the first flow
1751
+ by name. A record always holds flows by name — `e3.mutation.patch` writes
1752
+ only keyed records — so a lone flow is a record of one entry, or the host's
1753
+ `data`; a record of one flow is refused at build.
1754
+ - **`data`** — the host's flows by name or one flow, the value's type picking
1755
+ the arm: a value, an expression or a bind handle (`Data.bind`).
1756
+ `Flowchart.over(states, { … })` builds one flow from the app's own tables
1757
+ through their row mappers, and a `slice` narrows the transitions it builds
1758
+ from. Read only, unless the host gives `onApply`, its commit of the
1759
+ flowchart's edits: one patch of the value — over flows by name the open
1760
+ flow's insert, update or delete by name, never the whole value replaced;
1761
+ over one flow, the flow's own patch — answered as Save is.
1762
+
1763
+ A flow is `{ description, lanes, states, links, triggers }` of the row types
1764
+ (`Flowchart.Types.Flow`). `Flowchart.values({ [name]: flow })` and
1765
+ `Flowchart.value(flow)` write a dataset's value as literals, filling what a
1766
+ literal leaves out and refusing at build what would not draw or commit: two
1767
+ lanes, states, links or decisions of one key, a state naming a lane the flow
1768
+ does not have, a link naming a decision it does not have. A link naming a
1769
+ state the flow does not have is kept — it draws as the unresolved ghost.
1770
+
1771
+ Every edit is a draft of the open flow's editing session (#1247), each flow
1772
+ keeping its own: over a record, and over `data` given `onApply`, the canvas's
1773
+ gestures are its — "+ LANE" at the band row's tail, a lane's header
1774
+ double-clicked to rename it in place (a click selects the lane, as the user
1775
+ ruled on 2026-10-08: "a click on a lane's header selects the lane, and a double-click renames it in place, as a state's double-click opens its editor"), its × (off while the lane holds states, its tooltip saying why), the
1776
+ "+ STATE" ghost under a hovered lane, a state double-clicked into its editor
1777
+ (a new key rekeys its transitions' ends and the decisions' queues) or dragged
1778
+ across lanes, a handle dragged to another state (`canConnect` vetoes a pair;
1779
+ a drop on the state it left is its ↻ in-place transition), and Del on the
1780
+ selection: a state (with its transitions), several states, a transition, a
1781
+ decision, or a lane that holds none — and every edit the inspector makes. Each
1782
+ is ONE transaction the history item undoes and redoes — ⌘Z, ⇧⌘Z or ⌘Y from
1783
+ anywhere in the frame but a field being typed into — and Save sends the open
1784
+ flow's drafts as one commit. Two lanes, states, keyed transitions or decisions
1785
+ of one key hold Save off, the history item counting the issue. The flowchart
1786
+ takes no callback for an edit.
1787
+
1788
+ The tag and its types — `Flowchart.Types` — come from `@elaraai/e3-ui`, and
1789
+ the tags around it from `@elaraai/east-ui`. It moved here from east-ui
1790
+ (#1243), and its tables became a flow (#1244): a surface that wrote east-ui's
1791
+ `<Flowchart states={…} links={…} lanes={…} />` passes the same tables and
1792
+ mappers to `Flowchart.over`, as `data`.
1793
+
1794
+ ```tsx
1795
+ /** @jsxImportSource @elaraai/e3-ui */
1796
+ import { East } from '@elaraai/east';
1797
+ import { Box, Reactive, UIComponentType } from '@elaraai/east-ui';
1798
+ import { Flowchart, Record } from '@elaraai/e3-ui';
1799
+ import e3 from '@elaraai/e3';
1800
+
1801
+ // The depot's flows, by name: each written as a literal, checked when the package builds.
1802
+ export const depotFlows = e3.record("depot_flows", Flowchart.Types.Flows, Flowchart.values({
1803
+ "Inbound parcels": {
1804
+ description: "From the trailer to the van",
1805
+ lanes: [{ key: "intake", label: "Intake" }, { key: "sort", label: "Sort" }, { key: "load", label: "Load" }],
1806
+ states: [
1807
+ { key: "ARV", label: "Arrived", lane: "intake" },
1808
+ { key: "CH*", label: "Sort chutes", lane: "sort", members: 12n },
1809
+ { key: "LDD", label: "Loaded", lane: "load" },
1810
+ ],
1811
+ links: [{ from: "ARV", to: "CH*", trigger: "route" }, { from: "CH*", to: "LDD" }],
1812
+ triggers: [{ key: "route", label: "route", owner: "sort-planner" }],
1813
+ },
1814
+ }));
1815
+ export const depotFlowsPatch = e3.mutation.patch(depotFlows);
1816
+
1817
+ const flowchart = East.function([], UIComponentType, _$ => (
1818
+ <Reactive>{$ => {
1819
+ const flows = $.let(Record.bind(depotFlows, [depotFlowsPatch]));
1820
+ return (
1821
+ <Box height="480px">
1822
+ <Flowchart record={flows} flow="Inbound parcels" library={[Flowchart.library.flows()]} />
1823
+ </Box>
1824
+ );
1825
+ }}</Reactive>
1826
+ ));
1827
+ ```
1828
+
1829
+ One flow from the app's own tables, each an e3 input, through their row
1830
+ mappers — read only, as the host gives no `onApply`:
1831
+
1832
+ ```tsx
1833
+ /** @jsxImportSource @elaraai/e3-ui */
1834
+ import { ArrayType, East, StringType, StructType, variant } from '@elaraai/east';
1835
+ import { Box, Reactive, UIComponentType } from '@elaraai/east-ui';
1836
+ import { Data, Flowchart } from '@elaraai/e3-ui';
1837
+ import e3 from '@elaraai/e3';
1838
+
1839
+ // The app's own tables: its steps by phase, and the moves between them.
1840
+ export const Step = StructType({ code: StringType, name: StringType, phase: StringType });
1841
+ export const steps = e3.input("steps", ArrayType(Step), variant("value", [
1842
+ { code: "ARV", name: "Arrived", phase: "intake" },
1843
+ { code: "SRT", name: "Sorting", phase: "sort" },
1844
+ { code: "LDD", name: "Loaded", phase: "dispatch" },
1845
+ ]));
1846
+ export const Move = StructType({ src: StringType, dst: StringType, kind: Flowchart.Types.Kind });
1847
+ export const moves = e3.input("moves", ArrayType(Move), variant("value", [
1848
+ { src: "ARV", dst: "SRT", kind: variant("planned", null) },
1849
+ { src: "SRT", dst: "LDD", kind: variant("observed", null) },
1850
+ ]));
1851
+
1852
+ const flowchart = East.function([], UIComponentType, (_$) => (
1853
+ <Reactive>{$ => {
1854
+ const states = $.let(Data.bind(steps));
1855
+ const links = $.let(Data.bind(moves));
1856
+ return (
1857
+ <Box height="500px">
1858
+ <Flowchart
1859
+ data={Flowchart.over(states.read(), {
1860
+ state: s => ({ key: s.code, label: s.name, lane: s.phase }),
1861
+ links: links.read(), link: l => ({ from: l.src, to: l.dst, kind: l.kind }),
1862
+ lanes: [{ key: "intake", label: "Intake" }, { key: "sort", label: "Sort" }, { key: "dispatch", label: "Dispatch" }],
1863
+ })}
1864
+ name="steps"
1865
+ />
1866
+ </Box>
1867
+ );
1868
+ }}</Reactive>
1869
+ ));
1870
+ ```
1871
+
1872
+ The host's flows, edited, and committed by the host: Save hands `onApply` the
1873
+ session's request id and one patch of the flows — the open flow's insert,
1874
+ update or delete by name — which the host commits through a record's patch
1875
+ mutation under that id, answering with what e3 said (`flowchartVariants` maps
1876
+ every outcome). A write that got no answer throws, so the session's Retry sends
1877
+ the same request id again, and e3 answers it with the first write's commit
1878
+ rather than writing twice (#1275):
1879
+
1880
+ ```tsx
1881
+ const flows = $.let(Record.bind(depotFlows, [depotFlowsPatch]));
1882
+ const onApply = $.const(East.asyncFunction([StringType, PatchType(Flowchart.Types.Flows)], Editing.Types.ApplyResult, ($2, requestId, patch) => {
1883
+ const outcome = $2.let(flows.commit.patch(requestId, patch));
1884
+ const answer = $2.let(variant("rejected", [{ entry: "", row: none, field: none, message: "The write was refused" }]), Editing.Types.ApplyResult);
1885
+ $2.match(outcome, {
1886
+ committed: ($3, done) => { $3.assign(answer, variant("applied", { revision: some(done.stateHash) })); },
1887
+ // invalid, failed and timed_out → rejected with their words; conflict → conflict
1888
+ transport: ($3, lost) => { $3.error(East.str`The write got no answer, so it may have committed — retry to find out: ${lost.message}`); },
1889
+ });
1890
+ return answer;
1891
+ }));
1892
+ <Flowchart data={flows.read()} flow="Inbound parcels" onApply={onApply} library={[Flowchart.library.flows()]} inspector={false} name="host" />
1893
+ ```
1894
+
1895
+ ```
1896
+ <Flowchart record={…} | data={…} /> — state-transition flowchart in its builder frame: states as nodes in ORDERED phase lanes (layout derived — no coordinates), H/V-routed transition arrows, optional per-link decision triggers (lettered diamonds); dim-ladder highlight built in; the inspector, on by default, shows what is selected
1897
+ ├─ The frame (#1245): ONE toolbar holding every control the flowchart has — find state (a search over the open flow's states by key and by label; a pick selects the state and scrolls it into view), LR · TD, the freshness chip and, at its end over `data` with a slice, the slice's rail, and where it edits the history item (#1246, #1247: the open flow's session — its status, its issues, Undo, Redo, Discard and Save). It is one row at every width: the rail folds first, then the freshness chip goes, LR · TD folds into one chip naming the orientation (its menu both) and find state's box into its icon (which opens the box in a popover, the focus in it), and the history item last, to its buttons; on a touch screen every control there is a 44px tap target. The banners — the open flow's session's: a Save's conflict or refusal, an unknown outcome and a failed confirmation read, each with Retry, and the source changed under its drafts, with Discard; and a `flow` the flowchart doesn't hold, named with the flow shown in its place (`Gone isn't a flow here — showing Inbound parcels`) until the viewer opens a flow or the record gains that name. Main — the canvas, filling it and scrolling both ways inside it, its lanes running main's whole height; over flows by name with none — an empty record — the shared empty state, with "+ New flow" where it edits. The footer — the counts: over many flows the open flow's name first, the transitions (narrowed from how many while the slice narrows them) and their planned · observed · unresolved split, where it edits the changes waiting on Save (`3 pending` — each lane, state, transition and decision the drafts add, change or remove), and over a record its last save. The start pane is `library`'s, an optional prop; the end pane is the inspector, on by default. The flowchart fills its parent and draws no border: give it a box of its own height
1898
+ ├─ Its flows — ONE of two sources (both, or neither, is refused):
1899
+ │ ├─ record — Record.bind(r, [e3.mutation.patch(r)]): r of Flowchart.Types.Flows, flows by name (the canvas opens the flow the viewer opened last, kept in the UI store under `name`; else `flow`; else the first by name). Each flow keeps its own session (#1246): its drafts stay while another flow is open, and Save sends the open flow's as ONE patch through the record's patch mutation — `Record.onApply(record, { keyed: true })`, the flow's insert, update or delete by name; the drafts retire once the record reads it back. A record always holds flows by name — e3's patch mutation writes only keyed records — so a lone flow is a record of one entry, or `data`; a record of one flow is refused
1900
+ │ └─ data — a value, an expression or a bind handle of Flowchart.Types.Flows (+ `flow`) or Flowchart.Types.Flow, the value's type picking the arm; read only unless given onApply (async, (String, PatchType(the value's type)) → Editing.Types.ApplyResult — `East.asyncFunction([StringType, PatchType(T)], Editing.Types.ApplyResult, ($, requestId, patch) => …)`), the host's commit: Save hands it the session's request id — the same again on a Retry, so a host that keys its write by it (`commit.patch(requestId, patch)`) writes once (#1275) — and one patch of the value — over flows by name the open flow's insert, update or delete by name, never the whole value replaced; over one flow the flow's own patch — and the drafts retire once the host's value holds what it was handed
1901
+ ├─ Flowchart.over(states, { state?, links, link?, lanes, lane?, triggers?, trigger? }) — one Flowchart.Types.Flow from the app's tables:
1902
+ │ ├─ states + links + lanes (required) — the three tables (lanes accept a literal [{ key, label? }] array; array order = band order)
1903
+ │ ├─ state / link / lane / trigger (optional) — row mappers to { key, label?, lane, members?, notes? } / { key?, from, to, kind?, trigger?, evidence? } / { key, label? } / { key, label, letter?, owner?, queue?, outcomes? }; omit when rows are already Flowchart.Types.*
1904
+ │ └─ triggers (optional) — decision registry; a link's `trigger` names one (0..1 per link ⇒ the lettered diamond at the longest-run midpoint; clicking it highlights governed links)
1905
+ ├─ Flowchart.values({ [name]: flow }) / Flowchart.value(flow) — a dataset's value as literals { description?, lanes, states, links, triggers? }, Options filled, checked at build (two of one key; a state naming no lane the flow has; a link naming a decision it does not have)
1906
+ ├─ A flow's rows:
1907
+ │ ├─ link `kind` "planned" (solid, default) | "observed" (dashed 5/4); DERIVED marks: a from/to ref with no state row ⇒ the neg-dashed ghost "No state row" node (unresolved, counted in the footer); from == to folds to the `↻ n` badge (never routed); `members` ⇒ the ×N state-class badge
1908
+ │ └─ link `evidence` { volume?, count?, measuredAt?, unit? } — stroke weight (log 1.6 / 2 / 2.5 px, floor 1.4) + paper-filled run badges whose chrome inherits the link class (imported, never hand-authored)
1909
+ ├─ Props:
1910
+ │ ├─ orientation (optional) — "LR" (default) | "TD" initial; the toolbar's LR · TD toggles it (view state, never a filter chip; TD swaps the handle axes) — the viewer's pick kept in the UI store under `name`, so a remount keeps it, the payload's value showing until they pick (#1246); freshness (optional) — the toolbar's chip { label, date? }
1911
+ │ ├─ legend / minimap (optional) — legend default true (reserves canvas space); minimap auto at ≥ 25 states, drawn in main's corner over the canvas, where it stays while the canvas scrolls
1912
+ │ ├─ window + slice={{ slice }} (optional, over record) — Data.bindPaged(record, { indexes }) → Slice.bindRecord → window={Slice.rows(slice)}; the Flows tab pages the query, indexed field search covers the full record, the active complete graph is read separately by primary ID; sessions survive filtering and eviction, and Save confirms through primary reads with the shared exit notice (`flowchartRecordIndexes`)
1913
+ │ ├─ slice + affordances (optional, over data) — the slice's rail at the toolbar's end (default ["filter","search"], narrowing the transitions); the host feeds Flowchart.over's links through Slice.rows; the footer derives `N links · narrowed from M · −%` + the planned/observed split
1914
+ │ ├─ onSelectState / onSelectLink / onSelectTrigger / onTracePath (optional) — click / ⌥-click callbacks (entity keys); Esc restores everything instantly
1915
+ │ ├─ canConnect (optional) — fn(from, to) => Boolean: vetoes a pair BEFORE the connect draft snaps, and fails OPEN
1916
+ │ ├─ readOnly (optional) — no gesture edits — no "+ LANE", lane ×, ghost, connect, move, Del, "+ New flow" or history item — the selection and hover staying (inspecting isn't editing), the inspector printing every field and editing none; feed it a permission or published-mode flag
1917
+ │ ├─ library (optional, #1246) — the start pane's tabs, in order, each a `Flowchart.library.*` call: `flows()` — every flow by name, over a record or `data`'s flows by name, each card its name and under it its description, or with none its counts (`4 lanes · 9 states · 11 transitions`), the open flow's card placed and a flow with drafts marked Pending; a click opens a flow; the tab's search reads names and descriptions; where the flowchart edits, "+ New flow" under the cards names a new flow in a popover hanging from it — a name the flowchart holds refused there, with the reason — and opens it with one lane, a draft insert Save commits and Discard drops; `states(rows, { name?, icon?, key, label, meta?, group?, drop })` (#1248) — state templates: one card per row of the tab's OWN rows, an Array or a `Dict<String, T>` an input or a record binds (its key the accessors' second argument, an Array's index printed; a key that repeats keeps its first card), apart from the flows and from the other tabs — its label, its meta under it and the tab's icon, grouped by `group`, searched by key, label and meta, each card a drag source that a click selects and a second click lets go; `drop: (row, key) => Flowchart.patch(Flowchart.Types.State, …)` is the fields of the state a card dropped on a lane adds; unnamed, the tab is `States`, in the flowchart's words; `transitions(rows, { …, drop })` — transition templates, the same, `drop` a `Flowchart.patch(Flowchart.Types.Link, …)` that retypes the transition a card lands on — its kind, its decision and its other fields, never its key, from or to (refused as the tab's cards are read); unnamed, `Transitions`; `tab(rows, { name, icon?, key, label, meta?, group?, drop? })` — the author's own cards, each a drag source when the tab declares `drop`, the patch's type naming what a card lands on (`State` a state, `Link` a transition, `Lane` a lane's header, `Trigger` a decision); what a dropped card does is the Drag and drop branch's, below (#1249). An empty tab says so in the shared empty state — `No flows`, `No templates`, `Nothing in <name>`, and `No matches` for a search that hides every card. Left out, or empty, no library pane; collapsed, the pane is a rail with the first tab's count. `flows()` over one flow (`data` of Flowchart.Types.Flow), a tab listed twice (the Flows tab or a template tab, or two of the author's tabs of one name), a data tab's rows of neither an Array nor a `Dict<String, T>`, and a `drop` over another row's patch than its tab's are refused at build, naming the tab
1918
+ │ ├─ inspector (optional, #1250) — the frame's end pane, ON BY DEFAULT: left out, or `true`, it shows — pinned beside main with room, over main from its rail without — and `inspector={false}` takes it away. Its tabs Details and Issues, Issues with its count; collapsed, a rail with its icon, the issue count and what is selected. Details shows what is selected, every field through the shared form (east-ui's `Fields`, each by the input its type takes), each edit ONE transaction of the open flow's session, a field the drafts changed tinted and the head's chip Pending (New for a row the record holds none of): a state — key (a new key rekeys its transitions' ends and the decisions' queues), label, lane, members (Set and Clear), notes; its transitions in and out, each a link that selects it; Duplicate and Delete — an end no state stands for saying so, with its transitions, Delete taking them away; a transition — from and to, kind, decision (or none), key; its evidence read only (volume and unit, count, when measured); Delete; a decision — key, label, letter, owner, queue (tags over the flow's states), outcomes; the transitions it governs; Delete, clearing it from them; a lane, which a click on its header selects — key (a new key moves its states), label; how many states it holds; Delete, off while it holds any, saying why; several states (a shift-click puts one in or takes it out) — how many, a lane every one moves to, Delete; nothing — the open flow: over many flows its name (a new name renames it, one transaction, refused for a name the flowchart holds) and description, Duplicate and Delete, over one its description; its counts, its transitions' planned · observed · unresolved split, over a record its last save and who made it, and three hints. A key or a name left empty is refused, the footer saying why. `inspector={{ state?, transition? }}` gives a state or a transition the author's own Details in place of its form — `East.function([Flowchart.Types.State, FunctionType([Flowchart.Types.State], NullType)], UIComponentType, ($, state, update) => …)`, `Flowchart.Types.Link`'s for a transition — `update(edited)` writing the edited row back as ONE transaction (read only, nothing); every other kind's Details are its form. Issues lists the open flow's issues — two of one key, which hold Save off; a state naming a lane the flow has none of; a transition naming a state it has none of; a decision's queue naming one; a Save's conflict or refusal — each a click selecting what it names. Read only — over `data` with no `onApply`, or with `readOnly` — Details shows every field and edits none; name (optional) — names the flowchart when a surface holds two: its open flow, LR · TD, its panes' open tab and collapsed state are kept under it
1919
+ │ └─ No `height`, `maxHeight` or `density`: the flowchart fills the box it is given and draws at one rhythm, the spec's 116×40 cards in their lanes — each is refused at build
1920
+ ├─ Editing (#1247) — over a record, and over `data` given `onApply`, every gesture is ONE transaction of the open flow's session: "+ LANE" (Font Awesome's plus over its word, at the band row's tail) adds a lane keyed `lane-<n>`, labelled `Lane <n>`; a lane's header, double-clicked, is renamed in place (⏎ / blur commits, Esc cancels) — a click selects the lane, as the user ruled on 2026-10-08: "a click on a lane's header selects the lane, and a double-click renames it in place, as a state's double-click opens its editor"; a lane's × (Font Awesome's xmark beside its header) deletes it — off while it holds states, its tooltip saying why (`Move its 2 states first`); the "+ STATE" ghost (Font Awesome's plus) under a hovered lane opens the inline editor (key, then label; ⏎ commits, Esc dismisses) and adds the state at the end of its lane; a state double-clicked opens the same editor — a new key rekeys its transitions' ends and the decisions' queues in the same transaction; a state dragged across lanes moves (candidate bands highlight); a handle dragged to a state connects them — a transition of the default type (planned, no decision, no evidence) keyed `<from>→<to>`, made unique — the drop on the source its ↻ in-place transition, a drop that would repeat one pulsing it; Del (or Backspace) in the canvas deletes the selection — a state with its transitions, several states, a transition, a decision, cleared from the transitions it governs, or a lane that holds no state — never in a field being typed into. ⌘Z undoes and ⇧⌘Z / ⌘Y redo from anywhere in the frame but a field. Save is on while the open flow has a change and no two lanes, states, keyed transitions or decisions share a key; a Save's conflict or refusal keeps every draft under its banner, and a write with no answer turns Save into Retry, which resends the same request
1921
+ ├─ Drag and drop (#1249) — a library card carried over the canvas (picked up after 4px; on a touch screen after a 300ms hold): the ghost's caption says where it lands — `after CH* in Sort`, `at the start of Sort`, `in Hold`, `onto CH* → LDD` — or, red, why it can't: `Drop onto a lane`, `Drop onto a transition`, `Drop onto a state`, `Drop onto a lane's header`, `Drop onto a decision`, `The flowchart is read only`. A state template dropped on a lane adds a state there, at the row under the pointer — after the states above it — the lane washed in the brand's tint and a brand line where it lands: seeded with its drop's fields over a state's defaults, in that lane, its key the drop's where the flow doesn't hold it, else made unique (`HLD-2`), else minted (`state-<n>`), and selected. A transition template dropped on a transition retypes it — the transition taking the brand wash — its key and its ends kept. An author's card sets its fields on what its drop's type names: a state, a transition, a lane by its header, a decision by its diamond (a new key followed as an edit's is — a state's into its transitions' ends and the decisions' queues, a lane's by its states, a decision's onto the transitions it governs). ⏎ on a card does what a drop on the canvas's selection would — a state template after the selected state, in its lane, at the end of a selected lane, or at the end of the first lane with nothing selected; any other card on what is selected, when it lands there — a lane's card on the lane its header selected — and where that is refused the footer says why; on a touch screen a tap on the selected card does the same, the card staying selected. Each drop is ONE transaction of the open flow's session; the library pane over main slides off it while a card is carried
1922
+ └─ Factories: Flowchart.values / Flowchart.value / Flowchart.over / Flowchart.patch(T, { … }) (a row patch over State | Link | Lane | Trigger, every field an Option) / Flowchart.library.flows() / states(rows, cfg) / transitions(rows, cfg) / tab(rows, cfg) (the library's tabs); closed-set fields are typed values via Flowchart.Types.* — Flow, Flows, State, Link, Lane, Trigger, Evidence, Kind, Orientation, Patch(T)
1923
+ ```
1924
+
1925
+ | Signature | Description | Example |
1926
+ | --- | --- | --- |
1927
+ | `<Flowchart record={…} flow="…" />`, `Flowchart.values({ … })` | A record of flows by name, bound with its patch mutation; the canvas shows the flow opened last, else `flow`, else the first by name — a `flow` it doesn't hold named in a banner above main. LR · TD is the viewer's, kept under `name`. | `flowchartFlows` |
1928
+ | `<Flowchart record={flows} window={Slice.rows(slice)} slice={{ slice }} />` **❗** | Paged flow records through declared indexes and shared record Slice. Only nearby cards mount; the active graph and its drafts retain the original ID outside the narrowing. Search flows uses the description index; Find state searches the open graph. | `flowchartRecordIndexes` |
1929
+ | `library={[Flowchart.library.flows()]}` **❗** | The library pane's Flows tab (#1246): every flow by name — its description or its counts, the open one placed, one with drafts Pending — a click opening it, the open flow kept under `name`; where it edits, "+ New flow" opens a new flow, a draft insert Save commits through the record's patch mutation. Each flow keeps its own drafts. | `flowchartFlows` |
1930
+ | `library={[…, Flowchart.library.states(rows, {…}), Flowchart.library.transitions(rows, {…}), Flowchart.library.tab(rows, {…})]}` **❗** | The library's template and author's tabs (#1248): one card per row of each tab's own bound rows — an Array or a `Dict<String, T>`, apart from the flows and from the other tabs — its label, its meta and the tab's icon, grouped and searched; each template card a drag source, and an author's when its tab declares a `drop`, whose patch's type names what it lands on; a click selects a card, a second lets it go. | `flowchartLibrary` |
1931
+ | a library card dropped on the canvas, or ⏎ on it **❗** | Drag and drop (#1249): a state template adds a state on the lane at the row under the pointer, its key the drop's, made unique or minted; a transition template retypes the transition it lands on; an author's card sets its fields on what its drop's type names. ⏎ drops a card on the canvas's selection, and on a touch screen a tap on the selected card does too; refused, the ghost — or, for ⏎, the footer — says why. Each drop is one transaction. | `flowchartLibrary` |
1932
+ | `<Flowchart data={Data.bind(input)} />`, `Flowchart.value({ … })` | One flow of the host's, an input's value, read only. | `flowchartHandover` |
1933
+ | `<Flowchart data={Flowchart.over(states, { state, links, link, lanes })} />` | One flow from the app's own tables — each an e3 input — through their row mappers. | `flowchartDepot` |
1934
+ | `<Flowchart data={flows} onApply={…} />` **❗** | The host's flows by name, or one flow, edited: Save hands `onApply` the session's request id and one patch of the value — over flows by name the open flow's insert, update or delete by name, over one flow the flow's own patch — which the host commits, through a record's patch mutation under that id (`commit.patch(requestId, patch)`) or as it keeps them, answering with what happened; a write with no answer throws, and the Retry hands the same id (#1275). Over flows by name the Flows tab lists them and "+ New flow" starts one. | `flowchartVariants` |
1935
+ | `Flowchart.over`'s `triggers` + `trigger`, a link's `trigger` / `evidence`, `slice` + `affordances`, `freshness` | Decision diamonds, evidence-weighted strokes and badges, the slice's rail and the freshness chip on the toolbar. | `flowchartDepot` |
1936
+ | the frame (#1245) | One toolbar — find state, LR · TD, the freshness chip, the rail — one row at every width, the rail folding first, then the chip, LR · TD into its chip and find state into its icon; the canvas filling main, scrolling both ways; the footer's counts, the open flow's name first over many, the last save over a record. | `flowchartDepot`, `flowchartFlows` |
1937
+ | `<Flowchart record={…} canConnect={…} />` **❗** | Editing (#1247): every gesture on the canvas — "+ LANE", a lane renamed or deleted, the "+ STATE" ghost, a state edited (rekeying its transitions) or moved, a handle dragged to connect, Del on the selection — one transaction of the open flow's session; Undo, Redo and Discard, and one checked Save through the record's patch mutation. `canConnect` vetoes a pair. A record's lone flow is its one entry. Over `data`, the same with `onApply`, handed the session's request id with its patch — the same id on a Retry (#1275). | `flowchartDetail`, `flowchartFlows` |
1938
+ | `inspector` (on by default) / `inspector={false}` **❗** | The end pane (#1250): Details for what is selected through the shared form — a state, a transition, a decision, a lane its header selects, several states, or the open flow — each edit one transaction, tinted against the record; Issues, each a click selecting what it names. `false` takes it away. Read only, every field printed. | `flowchartDepot`, `flowchartFlows`; `false`: `flowchartHandover`, `flowchartVariants` |
1939
+ | `inspector={{ state, transition }}` **❗** | A state's or a transition's own Details, in place of its form: an East function over the row and its writer, `update(edited)` one transaction of the open flow's session. | `flowchartDetail` |
1940
+ | `onSelectState` / `onSelectLink` / `onSelectTrigger` / `onTracePath` | What the host hears, after the canvas selects: a state's key, a transition's, a decision's, and a transition ⌥-clicked. | `flowchartVariants` |
1941
+ | `legend` / `minimap` / `readOnly` | The legend, on by default; the minimap, shown from 25 states unless given, in main's corner over the canvas; read only — no gesture, no drop, no history item, every field printed. Each a Boolean or an expression the host changes. | `flowchartVariants` |
1942
+ | `orientation="TD"` | Opens top down; after that LR · TD on the toolbar is the viewer's, kept under `name`. | `flowchartHandover` |
1943
+ | `name` | Names the flowchart when a surface holds two: its open flow, LR · TD, its panes' open tab and collapsed state, its library's cards and its drop target are kept under it. | every example but `flowchartFlows` |
1944
+ | `record` and `data` together, or neither; `onApply` or top-level `affordances` over a record; a record Slice without `window`, or a local Slice over a record; `window` over data; `flow` over one flow; a record of one flow, or of another type, or bound without its patch mutation; `affordances: ["brush"]`; `states=`, `links=`, … on the tag; `height` / `maxHeight`; a callback for an edit (`onAddState`, `onCreateLink`, …) or `linkMode`; `Flowchart.library.flows()` over one flow; a tab listed twice — the Flows tab or a template tab, or two of the author's tabs of one name; a data tab's rows of neither an Array nor a `Dict<String, T>`; a `drop` over another row's patch than its tab's; a `library` that is not a list of `Flowchart.library.*` calls; a hover card's prop — `stateHover`, `linkHover`, `triggerHover`; an `inspector` neither a Boolean nor `{ state, transition }`; a kind's own Details over another row, or returning no UI; and `density` **❗** | Refused at build, each naming the prop and the remedy; a transition card whose `drop` sets its transition's key, from or to is refused as the tab's cards are read. | — |
1945
+ | `Flowchart.patch(Flowchart.Types.State, { key: "HLD", label: some("Held") })` | A patch over one of a flow's rows: the fields it sets, the rest `none`. | `flowchartLibrary` |
1946
+
1947
+ Between the examples, every pane combination: none (`flowchartHandover`), a
1948
+ library (`flowchartVariants`), an inspector (`flowchartDepot`, read only;
1949
+ `flowchartDetail`, its own Details), and both (`flowchartFlows`,
1950
+ `flowchartLibrary`, `flowchartRecordIndexes`). The indexed example has 2,048 flows
1951
+ and exercises backend search by description, computed state count, lane and
1952
+ decision owner, paging and original-ID Save. A composite description/state-count
1953
+ index lets those two filters combine; lane and owner use exact membership.
1954
+
1955
+ Removed with #1245: the canvas's eyebrow (its controls are the toolbar's
1956
+ items) and `height` / `maxHeight` (the flowchart fills its box).
1957
+
1958
+ Removed with #1247: a callback per edit — `onCreateLink`, `onDeleteLink`,
1959
+ `onAddLane`, `onRenameLane`, `onDeleteLane`, `onAddState`, `onEditState`,
1960
+ `onMoveState` — and `linkMode`, with the event types they took
1961
+ (`Flowchart.Types.LinkCreateEvent`, `LaneRenameEvent`, `StateAddEvent`,
1962
+ `StateEditEvent`, `StateMoveEvent`, `LinkMode`): the gestures are the
1963
+ session's, and each prop is refused at build, naming the remedy. A host that
1964
+ heard each gesture commits once, through `onApply`.
1965
+
1966
+ Removed with #1250: the hover cards — `stateHover`, `linkHover` and
1967
+ `triggerHover` — each refused at build naming the inspector, which shows what
1968
+ is selected (ruled by the user on 2026-10-08); and a click on a lane's header
1969
+ renaming it: a click selects the lane, and a double-click renames it in
1970
+ place.
1971
+
1972
+ Removed with #1251: `density`, which the canvas never drew by — it draws at
1973
+ one rhythm, the spec's 116×40 cards in their lanes (ruled by the user on
1974
+ 2026-10-09) — refused at build.
1975
+
1976
+ ## Rendering surfaces in an app — `<E3Provider>`
1977
+
1978
+ A deployed `ui()` task renders in a React app through
1979
+ `@elaraai/e3-ui-components`. `<E3Provider config>` says which e3 the app talks
1980
+ to, and how its requests reach it. `<ReactiveDatasetProvider>`, inside it,
1981
+ installs the adapters `Data.bind`, `Data.bindPaged`, `Func.bind` and
1982
+ `Record.bind` resolve through, for the config's workspace, and renders its
1983
+ children once they are in. `<UITaskPreview task>` fetches a `ui()` task's
1984
+ output and renders it, preloading what its manifest reads and polling it.
1985
+
1986
+ | `E3Config` | Meaning |
1987
+ |---|---|
1988
+ | `apiUrl` | **required** — the e3 API's base URL |
1989
+ | `repo` | the repository; `"default"` when omitted |
1990
+ | `workspace` | the workspace the bindings read and write |
1991
+ | `token` | a bearer token, or `null`; every request reads it afresh, so it may rotate |
1992
+ | `fetch` | the `fetch` every request goes through (`RequestOptions.fetch`), the global one when omitted. A host that answers e3's API itself gives its own: an e3 running in the page. It may change, as the token may |
1993
+
1994
+ `E3Provider` also takes a `queryClient`, to share a TanStack Query cache with
1995
+ the app; it makes its own otherwise.
1996
+
1997
+ Over an e3 running in the page (e3-web: the **e3** skill), `apiUrl` and
1998
+ `fetch` are the ones `createWebE3` gives, and no request reaches the network:
1999
+
2000
+ ```tsx
2001
+ // main.tsx — a deployed ui() task, every request it makes answered in the page
2002
+ import { createRoot } from 'react-dom/client';
2003
+ import { ChakraProvider } from '@chakra-ui/react';
2004
+ import { system } from '@elaraai/east-ui-components';
2005
+ import { E3Provider, ReactiveDatasetProvider, UITaskPreview } from '@elaraai/e3-ui-components';
2006
+ import { createWebE3 } from '@elaraai/e3-web';
2007
+
2008
+ const e3 = await createWebE3(new Worker(new URL('./e3.worker.ts', import.meta.url), { type: 'module' }));
2009
+
2010
+ createRoot(document.getElementById('root')!).render(
2011
+ <ChakraProvider value={system}>
2012
+ <E3Provider config={{ apiUrl: e3.apiUrl, repo: 'default', workspace: 'main', fetch: e3.fetch }}>
2013
+ <ReactiveDatasetProvider>
2014
+ <UITaskPreview task="dashboard" />
2015
+ </ReactiveDatasetProvider>
2016
+ </E3Provider>
2017
+ </ChakraProvider>,
2018
+ );
2019
+ ```
2020
+
2021
+ ## Key Patterns
2022
+
2023
+ ### Staged commit / discard
2024
+
2025
+ ```tsx
2026
+ <Reactive>{$ => {
2027
+ const t = $.let(Data.bind(threshold, { mode: 'staged' }));
2028
+ const value = $.let(t.read());
2029
+ const commit = $.const(East.function([], NullType, $ => { $(t.commit()); }));
2030
+ const discard = $.const(East.function([], NullType, $ => { $(t.discard()); }));
2031
+ return (
2032
+ <VStack gap="3">
2033
+ <Slider value={value} min={0} max={100} onChange={t.write} />
2034
+ <HStack gap="2">
2035
+ <Button variant="outline" onClick={discard}>Discard</Button>
2036
+ <Button variant="solid" onClick={commit}>Apply</Button>
2037
+ </HStack>
2038
+ <Diff bindings={[t.binding]} />
2039
+ </VStack>
2040
+ );
2041
+ }}</Reactive>
2042
+ ```
2043
+
2044
+ ### Disable controls on stale data
2045
+
2046
+ ```tsx
2047
+ <Slider
2048
+ value={t.read()}
2049
+ onChangeEnd={t.writeAndStart}
2050
+ disabled={t.status().hasTag('stale')}
2051
+ />
2052
+ ```
2053
+
2054
+ ### Numbers, dates and the locale
2055
+
2056
+ Every e3-ui surface prints through east-ui's one formatter:
2057
+ - the queue's values and deadlines;
2058
+ - the journal's times and the constraint chips;
2059
+ - the experiment's effects and its journal;
2060
+ - a dataset preview's counts and sizes;
2061
+ - a diff's values;
2062
+ - the Plan's and the Sheet's numbers, counts and dates.
2063
+
2064
+ Numbers follow the viewer's locale, and every date prints its UTC day. A host sets the locale by wrapping the app in `<I18nProvider locale="de-DE">`, re-exported from `@elaraai/east-ui-components`; the browser's language stands in otherwise.
2065
+
2066
+ A value that is data prints bare: every digit, never grouped, with the locale's decimal separator (a year stays `2026`). That covers a constraint's number and a diff's integer. A declared spec, such as a decision's `format`, prints as the east-ui skill's Formats branch describes.
2067
+
2068
+ ## Examples
2069
+
2070
+ Tested examples live in `test/*.examples.tsx`:
2071
+ - `data.examples.tsx` — `Data.bind` read/write/has, staged vs direct;
2072
+ `Data.bindPaged` under a Plan, a Table and a Sheet — the large ones over
2073
+ rows an `e3.task` generates — a snapshot's revision, and a record read
2074
+ through its index.
2075
+ - `func.examples.tsx` — `Func.bind` call/status/cancel, shared channels.
2076
+ - `diff.examples.tsx` — reviewing pending changes with `<Diff>`.
2077
+ - `ontology.examples.tsx` — graph/ontology editing with `<Ontology>`.
2078
+ - `experiment/experiment.examples.tsx` — causal-experiment surface with `<Experiment>`.
2079
+ - `decision/queue.examples.tsx` — `<DecisionQueue>` facets, probe editors, the
2080
+ author-bound slice scope, grouping.
2081
+ - `decision/journal.examples.tsx` — `<DecisionJournal>` read-back.
2082
+ - `decision/loop.examples.tsx` — the full loop: two task outputs unioned by one
2083
+ `Decision.bind` handle, queue + journal in lockstep.
2084
+ - `studio/component.examples.tsx` — `Studio.component`: a self-contained
2085
+ component placed twice on a page, the two placements sharing its state.
2086
+ - `studio/page.examples.tsx` — `<Studio.Page>`: a page's live layout with no
2087
+ chrome.
2088
+ - `studio/studio.examples.tsx` — the Studio as a solution writes it: the data
2089
+ its components read, the components, the pages record, and the three surfaces
2090
+ it mounts — `<Studio.Builder>`, `<Studio.Library>` and a published
2091
+ `<Studio.Page>`.
2092
+ - `plan/plan.examples.tsx` — `planTargetState` combines all row kinds,
2093
+ nesting, links, bound UI state, the series library and a narrow layout;
2094
+ `planMeasures` combines charts, heat, tables and resolution folds;
2095
+ `planRowDrop` edits nested record entries through one session;
2096
+ `planVariants`, `planNumberAxis`, `planOrdinalAxis` and `slicePlanChrome`
2097
+ retain their distinct axis, configuration and Slice examples.
2098
+ - `plan/plan-events.examples.tsx` — `planEvents` is the smallest builder,
2099
+ with a bound backlog, a customer-card tab and an Unassigned row.
2100
+ `planPrintWorks` covers grouped presses and crews, nested bindery resources,
2101
+ jobs, stops, shifts and plates, deliveries assigned to a bay or van, lanes,
2102
+ status, readiness, overlap rules, linked events, measures and stock. Its
2103
+ library and inspector use the shared frame and Save session.
2104
+ `planEventLinks` keeps the individual link-routing cases.
2105
+ - `plan/plan-windows.examples.tsx` — `<Plan>` over records too large to read
2106
+ whole (`planWindows`): 2,000 presses a task generates, paged as the canvas
2107
+ scrolls, and the jobs read through their day index, their backlog index and
2108
+ their own entries, edited and saved without the record read whole.
2109
+ - `sheet/sheet.examples.tsx` — `<Sheet>`, each in its frame, its rows bound
2110
+ from e3: the smallest sheet over a record; the configurator over the host's
2111
+ rows, committed through `onApply`; two thousand rows a task generates, read
2112
+ only, with the lens and saved views over them; a library of the author's own
2113
+ cards; the workshop's orders, the flagship (groups, the driver and
2114
+ registers, the link grammar, the copilot's fills and proposers, readiness,
2115
+ templates, the library, the inspector, the lens and views); one week's rows
2116
+ with every column kind and its rules, a journal and the author's own
2117
+ inspector; one day's batches dragged and moved, with sub rows; loose rows
2118
+ between work packages; and a record read a window at a time. Between them,
2119
+ every pane combination: none, a library, an inspector, and both. A sheet
2120
+ paged from a dataset is `data.examples.tsx`'s, and one over a record's own
2121
+ entries through `Record.onApply` `record.examples.tsx`'s `recordSheetApply`.
2122
+ - `sheet/sheet-link.examples.ts` — the link grammar: `Sheet.link.parse` and
2123
+ `Sheet.link.print`.
2124
+ - `sheet/sheet-transactions.examples.ts` — `Sheet.apply` over rows, and over
2125
+ entries of groups and loose rows.
2126
+ - `flowchart/flowchart.examples.tsx` — `<Flowchart>`, each in its frame, in
2127
+ a box of its own height, its flows bound from e3: a record of the depot's
2128
+ flows by name, its value from `Flowchart.values`, with its Flows tab
2129
+ (`flowchartFlows`); the configurator — the legend, the minimap and read only
2130
+ over the host's flows, Save committed by the host's `onApply` through the
2131
+ record's patch mutation, and what is selected heard in its aside
2132
+ (`flowchartVariants`); the depot's flows with the library — the Flows tab,
2133
+ step types from an input's rows, transition types from a record's rows by
2134
+ name and the author's own cards, each tab its own bound data, each card
2135
+ dropped on the canvas (`flowchartLibrary`); a flow from the host's tables,
2136
+ each an input — decision triggers, evidence, a ×14 state class, an in-place
2137
+ loop, an unresolved ghost, a bound slice and its inspector, read only
2138
+ (`flowchartDepot`); one flow of the host's, an input's value from
2139
+ `Flowchart.value`, top down with no pane (`flowchartHandover`); and a
2140
+ record's one flow edited on the canvas — every gesture a draft, Save one
2141
+ commit, a `canConnect` veto — with a state's and a transition's own Details
2142
+ (`flowchartDetail`). Between them, every pane combination: none, a library,
2143
+ an inspector, and both.
2144
+ - `query/query.examples.tsx` — queries as a solution writes them: the shared
2145
+ fixture's datasets; the saved queries record, its value seven queries from
2146
+ `Query.value`; the builder open on three of them and over an empty record; an
2147
+ order history the package's tasks generate, with its own saved queries and a
2148
+ builder whose runs are split calls; and the library.
2149
+
2150
+ ## Related skills
2151
+
2152
+ - **e3** — workspaces, tasks, `e3.input`, dataflow execution (the engine `ui()`
2153
+ builds on), and e3-web, which runs e3 in the page.
2154
+ - **east-ui** — the JSX component library (`<Reactive>`, `<Slider>`, `<Stat>`, …)
2155
+ that `ui()` renders.
2156
+ - **east** — the language used inside `East.function` bodies.
2157
+ - **east-ontology** — the `<Ontology>` editor's node/link model and the workshop
2158
+ method for building one.
2159
+ - **east-design** — decide where a decision surface fits in the overall solution.
2160
+ - **e3-ui-cli** — screenshot a surface from the terminal: `e3-ui shot
2161
+ --from-source` renders a zero-input `ui()` task; `--from-task` renders a
2162
+ deployed task's computed output.
2163
+
2164
+ ## Calendar — a schedule over bound records
2165
+
2166
+ Import `Calendar` from `@elaraai/e3-ui`. Its renderer is in
2167
+ `@elaraai/e3-ui-components`; BuilderFrame is internal. The former east-ui
2168
+ heatmap Calendar and its `scale`/`totals`/`footer` helpers have been removed.
2169
+
2170
+ Bind an event record with its patch mutation inside `Reactive`, then give
2171
+ `Calendar.events` the names of its title, start, end and resource fields.
2172
+ Bind resource records and template records there too. `Calendar.resources`
2173
+ and `Calendar.templates` read their dictionaries, so record updates change
2174
+ the labels and available templates reactively. Backlog rows belong to the
2175
+ event record: optional start/end fields with no schedule, plus `backlog`
2176
+ duration and due-date accessors. Scheduling and returning to backlog update
2177
+ that same row; they never copy it into another record.
2178
+
2179
+ ```tsx
2180
+ // Inside Reactive: jobs has optional start/end and a machine reference.
2181
+ const jobs = $.let(Record.bind(d.jobs, [d.jobsPatch]));
2182
+ const machines = $.let(Record.bind(d.machines, []));
2183
+ const templates = $.let(Record.bind(d.jobTemplates, []));
2184
+ return <Calendar
2185
+ resources={{ machines: Calendar.resources(machines.read(), {
2186
+ name: "Machines", icon: "gears", label: machine => machine.name,
2187
+ }) }}
2188
+ events={{ job: Calendar.events(jobs, {
2189
+ name: "Job", icon: "industry", title: "title", start: "start", end: "end",
2190
+ resource: { field: "machine", of: "machines" },
2191
+ backlog: { duration: row => variant("hours", row.hours), due: row => row.due },
2192
+ templates: Calendar.templates(templates.read(), {
2193
+ name: row => row.name, group: row => some(row.group),
2194
+ duration: row => variant("hours", row.hours), values: row => row.values,
2195
+ }),
2196
+ }) }}
2197
+ library={[Calendar.library.templates(), Calendar.library.backlog()]}
2198
+ inspector />;
2199
+ ```
2200
+
2201
+ The runnable examples `calendarQuickstart`, `calendarOperations`,
2202
+ `calendarMinimal`, `calendarMobile`, `calendarWindowed`, `calendarReadOnly` and `calendarCustomInspector`
2203
+ include their record declarations and seeds. Search those names in the example
2204
+ index. Their bindings become the UI task's read/write manifest.
2205
+
2206
+ | Signature | Description | Example |
2207
+ | --- | --- | --- |
2208
+ | `<Calendar events resources? slice? library? inspector? view? hours? week? density? now? readOnly? canDrop? onSelect? id? />` **❗** | One shared frame, Toolbar with author-bound Slice controls and history, schedule and the shared footer rail. Calendar day/week/month, Resources day, Timeline day/week/month. Panes are optional. Empty event maps, invalid working hours and duplicate library tab names are refused. | `calendarOperations`, `calendarMinimal` |
2209
+ | `Calendar.events(record, config)` **❗** | `Schedule.events`: span fields, resource references, status cases, shared `field` editors, author-owned `filter(row, key)` (usually `Slice.apply.matches`), `ready`, custom `inspector`, overlap policy and record patch writes. Whole-row edits use one EditSession per kind and one shared EditHistory. | `calendarOperations` |
2210
+ | `slice={{ slice, affordances }}` | Plan's author-bound `Slice.bind` handle, never a renderer-created filter dataset. Apply `Slice.rows`/`Slice.apply` upstream; preserve resource/event keys. Its datetime range drives the day-index window; navigation and external range controls write the same state. Paged row predicates cover only that window, not the entire record. | `calendarOperations`, `calendarWindowed` |
2211
+ | `Calendar.resources(rows, config)` | `Schedule.resources` over a dictionary from a bound record or dataset; Calendar reads resource kinds whole. | `calendarOperations` |
2212
+ | `Calendar.templates(rows, { name, group?, at?, duration, values })` **❗** | Bound template dictionary; typed `values` supplies exactly the event fields other than its scheduling roles. Literal templates remain supported by Schedule. Template changes do not rewrite existing event rows. | `calendarOperations` |
2213
+ | `Calendar.library.templates()` / `.backlog()` / `.tab(rows, config)` **❗** | Shared Library cards and search. An author's tab may apply `Calendar.patch(RowType, fields)` to a compatible selected event. Invalid or ambiguous patch row types are refused. | `calendarOperations` |
2214
+ | `Calendar.days(start, end)` / `.unscheduled(start, due)` | UTC half-open day keys and the unscheduled index key. Supply paged `window`, `backlogWindow` when applicable, and `entries` for selection and draft baselines by key. | `calendarWindowed` |
2215
+ | `readOnly` | Same layouts, filters, selection and overlaps, without sessions, mutation actions or editing callbacks. | `calendarReadOnly` |
2216
+ | Narrow layout | Below 480px of main-panel width, chronological agenda cards replace the grid. Create, Schedule, Move, Resize, Duplicate, Delete, Return to backlog and author-card actions use shared anchored forms and the same commands as desktop gestures. No dragging. Desktop view, date, filters, selection and drafts survive resizing. | `calendarMobile` |
2217
+
2218
+ `canDrop` refuses a proposed placement before it becomes a draft. `ready`
2219
+ validates the resulting row and may block Save. Unknown commit outcomes,
2220
+ conflicts, Undo/Redo/Discard and draft restoration use the shared editing
2221
+ contract. Date/time fields are UTC. An indexed source labels filters and counts
2222
+ as operating over its loaded window.
2223
+
2224
+
2225
+ ## Roster — weekly staffing over bound records
2226
+
2227
+ Import `Roster` from `@elaraai/e3-ui`; the renderer is in e3-ui-components.
2228
+ One `<Roster>` owns its internal BuilderFrame. The former east-ui Roster and
2229
+ Board, their closed UI variant arms, recipes and examples are removed. Rebuild
2230
+ and re-export packages using those old components; stored e3 record formats do
2231
+ not change. Staff, configuration, forecast and proposals may all be bound
2232
+ record/input/task values inside the example's inline `Reactive` body.
2233
+
2234
+ | Signature | Description | Example |
2235
+ | --- | --- | --- |
2236
+ | **Builder and sources** | | |
2237
+ | `<Roster weeks people groups shifts duties? positions? agencies? rules? costs? forecast? proposals? check? library? inspector? slice? visiblePeople? window? week? view? density? chipSkills? requirements? readOnly? id? />` **❗** | Shifts day/week and People week. `weeks` is a `Record.bind` handle for `Roster.Types.Weeks` with its patch mutation. Empty literal groups/shifts, duplicate library tabs and missing write doors are refused. The renderer validates live configuration. | `rosterWarehouse`, `rosterMinimal` |
2238
+ | `Roster.people(rows: Dict<String, R>, { name, group, position?, skills?, contract?, agency?, trainer?, trainee?, usual? })` | Typed `(row, key)` accessors over bound staff. Original dictionary keys are assignment identities. | `rosterWarehouse` |
2239
+ | `visiblePeople: Set<String>` and `slice={{ slice, affordances }}` | Author-owned Slice controls visibility by original keys. Coverage/cost/rules use complete `people` and the complete active week. Filters never drop hidden drafts from Save. | `rosterWarehouse` |
2240
+ | `window={Data.bindPaged(weeksRecord)}` | Read only active/copy weeks and the open picker month; no full history download. A datetime Slice range selects a week, and navigation writes the same range. | `rosterWindowed` |
2241
+ | **Library and inspector** | | |
2242
+ | `Roster.library.people()` / `.activities()` | Shared Library cards, avatars, search, role/skill facets and explicit placement. Named staff and unnamed agency requests stay distinct. | `rosterWarehouse`, `rosterMobile` |
2243
+ | `Roster.library.tab(rows, { name, icon?, label, meta?, group?, drop? })` **❗** | Reified typed card accessors over a bound dictionary. `drop(row, key)` returns a typed assignment patch. Non-string card keys use East's canonical print. | `rosterWarehouse` |
2244
+ | `Roster.patch({ position?, activity?, offset?, overtime?, agreed? })` **❗** | A custom card's patch on a named assignment. `slot` and `who` cannot be patched. Runtime commands validate positions/activities and read-only state. | `rosterWarehouse` |
2245
+ | `inspector` or `inspector={{ assignment?, requirement? }}` | Shared typed forms by default. Custom East callbacks receive `(value, update)` and update through the same commands/session. | `rosterCustomInspector` |
2246
+ | **Domain functions and values** | | |
2247
+ | `Roster.Types.{Weeks, Week, Status, Slot, Who, Assignment, Requirements, Requirement, Person, Group, Skill, Shift, Position, Agency, Rules, Costs, Context, Coverage, Proposal, Issue, Fix, CheckContext}` | Weeks are UTC DateTime-keyed dictionaries; assignments have stable string keys, a configured slot and a named person or agency request. Requirements hold positions and hours by activity. | `rosterWarehouse` |
2248
+ | `Roster.coverage(week, context)` | Pure East function: positions, named people, nominal/agency/overtime/requested hours, skill capacity/assigned hours, costs, leads and trainers for every configured slot. | `rosterCoverage` |
2249
+ | `Roster.check(week, context)` | Pure East checks: missing lead, double booking, within-week adjacent-day rest, trainee/trainer, skill compatibility, open positions/skill gaps and changed-hours agreement, with typed fix actions. | `rosterChecks` |
2250
+ | `Roster.weekHours(week, context)` / `Roster.rest(assignment, id, week, context)` | Pure named-person totals and adjacent-day rest. Offset shifts start/end without reducing nominal hours; overtime extends the end. Unnamed requests supply no person/skill capacity. | `rosterWeekHours`, `rosterRest` |
2251
+
2252
+ Every gesture is a shared Session transaction. Save patches the active week
2253
+ only; Publish includes the held draft and its status in one checked write.
2254
+ Lost responses stay unconfirmed and retry with the same identity. Published
2255
+ weeks are read-only. Copy into an unstarted week retains its forecast targets,
2256
+ mints assignment keys and resets changed hours/agreement. Proposals are
2257
+ accepted/dismissed into the week; a stale or already rostered proposal is hidden.
2258
+ Below 480px of **main** width, Shifts and People use cards with explicit
2259
+ Assign/Move/Edit/Remove/Restore/Request/Accept/Reject/target actions and no DnD.
2260
+ The `rosterMobile` example demonstrates the complete inline authoring pattern.