@elaraai/east-codex-plugin 1.0.99 → 1.0.101

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.
Files changed (37) hide show
  1. package/.build/mcp/server.js +3 -2
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/index.json +12207 -216
  4. package/package.json +1 -1
  5. package/skills/e3/SKILL.md +37 -809
  6. package/skills/e3/reference/browser.md +93 -0
  7. package/skills/e3/reference/cli.md +123 -0
  8. package/skills/e3/reference/from-code.md +48 -0
  9. package/skills/e3/reference/rack.md +139 -0
  10. package/skills/e3/reference/record-indexes.md +326 -0
  11. package/skills/e3/reference/record-migrations.md +63 -0
  12. package/skills/e3/reference/repository.md +25 -0
  13. package/skills/e3-ui/SKILL.md +273 -3623
  14. package/skills/e3-ui-cli/SKILL.md +1 -5
  15. package/skills/east/SKILL.md +31 -464
  16. package/skills/east/reference/beast2.md +71 -0
  17. package/skills/east/reference/cross-language-and-json-schema.md +87 -0
  18. package/skills/east/reference/queries.md +46 -0
  19. package/skills/east/reference/runners-and-ir.md +148 -0
  20. package/skills/east/reference/trees-and-recursion.md +56 -0
  21. package/skills/east/reference/values-in-typescript.md +62 -0
  22. package/skills/east-py/SKILL.md +29 -1652
  23. package/skills/east-py/reference/beast2.md +108 -0
  24. package/skills/east-py/reference/cli.md +51 -0
  25. package/skills/east-py/reference/columns-and-platform-functions.md +87 -0
  26. package/skills/east-py/reference/control-flow-and-queries.md +147 -0
  27. package/skills/east-py/reference/cross-language.md +70 -0
  28. package/skills/east-py/reference/ir-and-diagnostics.md +150 -0
  29. package/skills/east-py/reference/patterns.md +369 -0
  30. package/skills/east-py/reference/performance.md +70 -0
  31. package/skills/east-py/reference/value-methods.md +306 -0
  32. package/skills/east-py/reference/values-construction-and-json.md +88 -0
  33. package/skills/east-py/reference/writing-east-functions.md +275 -0
  34. package/skills/east-py-datascience/SKILL.md +12 -33
  35. package/skills/east-py-io/SKILL.md +1 -5
  36. package/skills/east-py-std/SKILL.md +1 -5
  37. package/skills/east-ui/SKILL.md +220 -1332
@@ -1,27 +1,23 @@
1
1
  ---
2
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."
3
+ description: "Builds interactive decision surfaces as e3 UI tasks (ui()) authored in east-ui JSX and bound to workspace data: Data.bind and Data.bindPaged for datasets, Record.bind for records and their mutations, Func.bind for e3.function calls, staged edits reviewed with the Diff tag. Provides the planning builders Plan, Sheet, Calendar, Roster, Allocation, Flowchart and Schematic, plus Ontology, Experiment, the Decide loop (Decision.bind, DecisionQueue, DecisionJournal), the Studio page builder, saved jq queries (Query.Builder), and rendering deployed surfaces in a React app (E3Provider). Use when a UI reads or writes e3 workspace data or runs as an e3 task; components with no e3 data are east-ui's."
4
4
  ---
5
5
 
6
- ## Detailed skill scope
6
+ # e3-ui — e3 + UI bridge
7
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 Publish one patch making the draft its next live version; <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 one Slice.bindRecords rail (its rows, each event kind, resource kind and templates record a source, one window; an event kind on paged resources read a cell at a time through a series index and shaded from a summary index zoomed out), 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), or the `rows` source of its one Slice.bindRecords rail — the record's rows, the source's narrowing drawn over them as the lens (a filtered spreadsheet: only the rows it keeps, one after another, each at its row number, e3 placing them from the index) — the rail narrowing its templates records too; 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, saved-view tabs over every source's narrowing, 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 paged through its source, one Slice.bindRecords rail — a source per event kind, resource kind and templates record, one date window — a resource kind paged a window at a time (Data.bindPaged), the events on it read a cell at a time through a series index and shaded from a summary index past 10,000, shared Toolbar/Library/FieldForm/EditSession behavior, and explicit agenda/card actions below 480px. BuilderFrame remains internal. (15) Roster — weekly staffing over the app's own records: its duties a Schedule.events kind (start, end, resource, shift, group, position?, activity?, hours?), its people and agencies Schedule.resources kinds, its weeks Schedule.periods for Publish, its cover Roster.targets, and its shifts, groups, positions, activities and proposals read through Roster.* accessors; Shifts (Day · Week) and People (Week · Month) layouts — the People week a tile a duty in the shift's colour token (Roster.shifts' color, east-ui's ColorTokenType), the month a column a week, and the app's week patterns (Roster.patterns, Roster.library.patterns()) dropped on a person's week as one step; pure coverage/rules over the duty row type; the app's pay in its own codes, asked a person at a time; Find fixes on the app's fit e3.function (Func.bind, Roster.fit(R)); the week's duties read through the slice's duty source; one Slice.bindRecords rail over the duties, targets, people and activities; one history over a session per record, Save per record and Publish saving first, then the week's status; 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 rail of its one Slice.bindRecords, 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 — over a record those its rail's `flows` source narrows it to, counted — and opens one, the open flow kept under the flowchart's name, and '+ New flow' starts one, beside state and transition templates, templates records (Flowchart.library.states / transitions), and the author's own cards (Flowchart.library.tab), each following the source of the rail it names, 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. (17) The Allocation — <Allocation>, a day's arrivals booked into timed lane slots and each bin's quantity allocated to resources with room and time for its hold, always in its builder frame, as a Timeline (lanes, links, resource rows) or a Table (a row per slot), over the app's own records: its bins an instant Schedule.events kind (at, resource, arrival, quantity, parts, hold, kind?), its lanes and resources Schedule.resources kinds (offset; min, max, note, hold, jobs), what it books from Allocation.arrivals (each arrival's values a booked bin's own fields), and its days Schedule.periods for Publish — one history over the bins' and the days' sessions, every gesture a draft, Save per record and Publish saving first, then the day's status — the app's fit an e3.function bound with Func.bind (a place or a take question about the drafted day, FitRequest(R) over the bin row type, built on Allocation.answer / fit / lookahead), split loads and Find a fit, the app's bin fields as columns and its own check over CheckContext(R), one Slice.bindRecords rail over the day's bins, its lanes, resources and arrivals, the shared Library, Inspector and session, explicit-action cards below 480px, and pure loads / candidates / check / slots over Day(R) a task runs too. (18) The Schematic — <Schematic>, the 2D world-coordinate drawing of the app's own records: a kind per record, keyed by String, its fields mapped to the Schematic's roles and its shapes made by accessors over the row's own fields — items (Schematic.items: a centre, a box, a footprint drawn about the centre, a label, a status, a meter, a figure), zones (Schematic.zones: a box, outlined or hatched, a geometry about its centre), links between two items (Schematic.links: from and to naming item slots) and nets joining many to many (Schematic.nets: sources and destinations) — each kind editable bound with its patch door (Record.bind) or read only (Data.bind), read whole or complete through its source of one Slice.bindRecords rail (entries: Data.bindPaged) — a window at a time where that source lists an area index (index.area), its density shaded past 5,000 rows in view — its details a record keyed as it is (Schematic.details), its templates a record (Schematic.templates), its layers the app's rows (Schematic.layers), the library's tabs over every kind (Schematic.library.templates() / backlog() / index() / layers() / tab), each card dropped on the canvas — an item template adds an item at the point, a backlog row is placed there, a link or net template gives a link or a net of its kind its values, an author's card sets its Schematic.patch's fields, ⏎ onto the selection or at the view's centre — the inspector opted into: Details through the shared form over each kind's fields and its details', an item's position, a link's ends and a net's sides, and Issues, each selecting what it names; below 480px of main nothing drags, Details' Connect to… and the Backlog card's Place taking the gestures' place; a camera with a minimap, selection by a tap, Shift and the marquee, and every gesture — Move, Connect and a Shift session growing a net, an end retargeted, a net extended, Del — one step of one history over a session per record it writes, with Undo / Redo and Save sending each record's changes through its patch door, canConnect answering each pair with none or the refusal's words; onSelect hears the whole selection, each entity by its kind's slot and its key — its shapes and types on Schematic (Schematic.circle / polyline / polygon / rect about the anchor, outline / hatch, solid / dashed, Schematic.patch, Schematic.Types).
8
+ `@elaraai/e3-ui` connects **east-ui** JSX tags to **e3** workspaces. A decision
9
+ surface is an e3 **UI task** whose reads and writes of workspace data are
10
+ recorded in a manifest derived from its IR, so the engine knows what the UI
11
+ depends on and re-renders it when that data changes. With staged writes,
12
+ `<Diff>` review and commit / discard, a view is where a user commits a decision
13
+ with its evidence.
9
14
 
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>`, `<Allocation>`, `<Flowchart>` and `<Schematic>`, 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).
15
+ Everything comes from one import, `@elaraai/e3-ui`: the `ui()` task factory, the
16
+ bindings (`Data`, `Record`, `Func`, `Decision`, `Slice.bindRecords`), the e3
17
+ tags (`<Diff>`, `<Ontology>`, `<Experiment>`, `<Plan>`, `<Sheet>`, `<Calendar>`,
18
+ `<Roster>`, `<Allocation>`, `<Flowchart>`, `<Schematic>`, `<DecisionQueue>`,
19
+ `<DecisionJournal>`) and the `Studio` and `Query` components. Base tags
20
+ (`<VStack>`, `<Text>`, `<Stat>`, …) come from `@elaraai/east-ui`.
25
21
 
26
22
  ## Before writing code — search the example index
27
23
 
@@ -42,6 +38,13 @@ writing or changing East code:
42
38
 
43
39
  Nothing is injected for you; the search is the step.
44
40
 
41
+ For e3-ui, search with `package: "e3-ui"`. Each builder's examples hold the
42
+ full package side (records, indexes, mutations) beside the JSX, so its
43
+ smallest one is the place to start; the Start from column of the builders
44
+ table below gives each one's id for `get_east_example`. A prop's full
45
+ contract is in its doc comment; the build refuses a wrong shape with an error
46
+ that names the fix.
47
+
45
48
  ## Quick Start
46
49
 
47
50
  ```tsx
@@ -53,33 +56,38 @@ import * as e3 from '@elaraai/e3';
53
56
 
54
57
  const threshold = e3.input('threshold', FloatType, variant('value', 50.0));
55
58
 
56
- // A UI task: reactive binding to a workspace dataset, no compute-time inputs.
59
+ // A UI task: a reactive binding to a workspace dataset, no compute-time inputs.
57
60
  const dashboard = ui('dashboard', [], East.function([], UIComponentType, (_$) => (
58
61
  <Reactive>{$ => {
59
62
  const t = $.let(Data.bind(threshold));
60
63
  return <Slider value={t.read()} min={0} max={100} onChange={t.write} />;
61
64
  }}</Reactive>
62
65
  )));
63
- // Manifest auto-derived: reads [threshold], writes [threshold]
66
+ // Manifest derived from the IR: binds inputs.threshold
67
+ export default e3.package('dashboard', '1.0.0', dashboard);
64
68
  ```
65
69
 
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`).
70
+ Deploy and run it like any e3 task (`e3 workspace deploy`, `e3 dataflow run`);
71
+ the workspace re-renders the component when bound data changes.
69
72
 
70
- > `Data.bind` reads live **inside** the `<Reactive>{$ => …}</Reactive>` builder
71
- > block — there is no inner `East.function`.
73
+ - The pragma makes the file JSX-capable, and needs `"jsx": "react-jsx"` in the
74
+ project's tsconfig (a scaffolded project has it). Without it, `tsx` compiles
75
+ JSX to `React.createElement` and fails with `React is not defined`.
76
+ - Bindings live **inside** the `<Reactive>{$ => …}</Reactive>` block; there is
77
+ no inner `East.function`.
72
78
 
73
79
  ## Decision Tree: What Do You Need?
74
80
 
81
+ Each leaf names the API; search the index for it to get a tested example.
82
+
75
83
  ```
76
84
  Task → What do you need?
77
85
  │
78
86
  ├─ Author a decision surface as an e3 task
79
- │ ├─ Reacts to workspace data only → ui(name, [], fn) + Data.bind
87
+ │ ├─ Reacts to workspace data only → ui(name, [], fn) + bindings inside <Reactive>
80
88
  │ └─ Also takes computed inputs → ui(name, [input], fn) (fn receives values)
81
89
  │
82
- ├─ Read / write workspace datasets from the UI — Data.bind(dataset, options?)
90
+ ├─ Read / write a workspace dataset — Data.bind(dataset, options?)
83
91
  │ ├─ Read a value → .read()
84
92
  │ ├─ Check if set → .has()
85
93
  │ ├─ Write a value → .write(v)
@@ -97,6 +105,14 @@ Task → What do you need?
97
105
  │ └─ Through a record's index → { index: "by_status", join?: true }
98
106
  │ rows arrive in the INDEX's order as `{ik, key, value, row}`
99
107
  │
108
+ ├─ Read a record and apply its mutations — Record.bind(record, [mutation names])
109
+ │ ├─ Its current value → .read()
110
+ │ ├─ Apply a mutation → .mutate.<name>(args…)
111
+ │ ├─ The mutation's lifecycle → .mutate.status() / .pending() / .error()
112
+ │ ├─ Recompute what reads it → .start() (a mutation commits but does not run the dataflow)
113
+ │ ├─ Its commit history → .history()
114
+ │ └─ A builder's Save door → Record.bind(record) on a record declaring mutation.patch()
115
+ │
100
116
  ├─ Call a named package function (e3.function) from the UI — Func.bind(fn)
101
117
  │ ├─ Launch (fire-and-forget, sync-callback safe) → .call(args…)
102
118
  │ ├─ Last successful result → .read() (Option(O))
@@ -127,97 +143,97 @@ Task → What do you need?
127
143
  ├─ Run the Decide loop over reasoning-task decisions
128
144
  │ ├─ Union the bound decision views into one handle → Decision.bind([Contract]?, { decisions, judgements })
129
145
  │ ├─ The queue (triage → understand → judge → apply) → <DecisionQueue handle={handle} …/>
130
- │ ├─ The resolved read-back (Decide↔Trust seam) → <DecisionJournal handle={handle} />
146
+ │ ├─ The resolved read-back → <DecisionJournal handle={handle} />
131
147
  │ └─ Scope the queue (author-owned, Table pattern) → Slice.bind over Decision.Types.Decision, rows = handle.queue()
132
148
  │
133
- ├─ Draw what is scheduled on ONE shared axis — the Plan (see The Plan below)
149
+ ├─ Draw what is scheduled on ONE shared axis — the Plan
134
150
  │ ├─ Rows derived from data by a series list → <Plan axis={…} data={…} series={[…]} />
135
151
  │ ├─ Event kinds over records, on resource rows → <Plan axis={…} resources={{ presses: Schedule.resources(…) }} events={{ job: Schedule.events(record, {…}) }} />
136
152
  │ ├─ Read-only rows: a dataset's, or hand-built → rows={[Plan.over(data, [series…]), Plan.chart({…})]}
137
153
  │ ├─ Its axis: time, number or ordinal → Plan.axis / Plan.axis.number / Plan.axis.ordinal
138
154
  │ ├─ Rows, nested by what the data holds → Plan.series.span / buckets / chart / heat / table / cards / events / group / section / views / rows
139
155
  │ ├─ Data too large to hold whole → data={paged}, a Data.bindPaged handle
140
- │ ├─ Narrow its rows, event kinds, resources, templates → slice={{ slice: Slice.bindRecords(key, { rows?, job?, presses?, jobTemplates? }) }} (one window, which the rows never follow; Schedule.templates(rows, { …, source }))
141
- │ ├─ Event kinds over records too large to read whole → a kind's source over its interval index (range: "start") + Schedule.events(record, { entries }), counted first and drawn within 10,000 events; with no rail, { window, backlogWindow, entries } over resources read whole, counted first by the days its events run on; Schedule.resources(Data.bindPaged(record), {…})
142
- │ ├─ …on paged resources: read a cell at a time → the kind's source lists index.series + index.summary beside its interval index, shaded from the summary zoomed out; any other form is refused, naming both
143
- │ ├─ …its paged resources narrowed by the rail → a source named after the paged kind's slot, Data.bindPaged(record, { indexes }) over its own record: the canvas pages the narrowing's rows
156
+ │ ├─ Narrow its rows, event kinds, resources, templates → slice={{ slice: Slice.bindRecords(key, { rows?, job?, presses?, jobTemplates? }) }} (Schedule.templates(rows, { …, source }))
157
+ │ ├─ Event kinds over records too large to read whole → the kind's source over its interval index (range: "start") + Schedule.events(record, { entries }); drawn within 10,000 events
158
+ │ ├─ …on paged resources: read a cell at a time → the kind's source lists index.series + index.summary beside its interval index
144
159
  │ ├─ A link between two runs, or two events → Plan.link({ from: Plan.ref(…), fromRun, … }) / Plan.link({ from: Plan.eventRef(kind, key), … })
145
160
  │ ├─ Its library pane: templates, backlog, series, cards → library={[Plan.library.events(), Plan.library.backlog(), Plan.library.series(), Plan.library.tab(rows, {…})]}
146
161
  │ ├─ Its inspector pane: what is selected → inspector (+ an event kind's own: Schedule.events(record, { inspector }))
147
- │ ├─ Event kinds dragged: templates, backlog, moves → built in with resources + events (+ library); canDrop={fn(Schedule.Types.Candidate) => Option<String>}
148
- │ ├─ The app's optimiser over the window and the backlog: the Elara eye → optimise={Func.bind(e3.function)} from Plan.Types.OptimiseRequest({ job: Job }, { presses: Press }) to Plan.Types.OptimiseResult({ job: Job }); its answer lands as ONE step of the history (#1409)
149
- │ ├─ Overlap warnings, without dropping overlapping events → Schedule.events(record, { overlaps: "warn" | "allow" }); the chip selects the first pair
162
+ │ ├─ Drags of templates, backlog cards and events → built in with resources + events (+ library); canDrop={fn(Schedule.Types.Candidate) => Option<String>}
163
+ │ ├─ The app's optimiser over the window and the backlog → optimise={Func.bind(e3.function)} from Plan.Types.OptimiseRequest({ job: Job }, { presses: Press }) to Plan.Types.OptimiseResult({ job: Job })
164
+ │ ├─ Overlap warnings, without dropping overlapping events → Schedule.events(record, { overlaps: "warn" | "allow" })
150
165
  │ ├─ Save each changed event kind through its patch door → applyMode="batch" (default); "auto" commits each ready gesture
151
- │ └─ Dropped cards and moves as drafts → a series' edit + editing={{ onUpdate | onApply }}
166
+ │ └─ Dropped cards and moves of data rows as drafts → a series' edit + editing={{ onUpdate | onApply }}
152
167
  │
153
- ├─ Let planners type rows in place — the Sheet, in its frame (see The Sheet below)
168
+ ├─ Let planners type rows in place — the Sheet
154
169
  │ ├─ An e3 record edited as a sheet → <Sheet record={…} columns={{…}} /> (record = Record.bind(r))
155
170
  │ │ ├─ One entry's rows, groups or loose rows → entry={{ key, rows: "field", id: "id" }} (+ group)
156
171
  │ │ └─ A large record, a window at a time → window={Data.bindPaged(r)}
157
172
  │ ├─ The host's rows → <Sheet data={…} id="id" columns={{…}} />
158
- │ ├─ Narrow its rows and templates — one rail → slice={{ slice: Slice.bindRecords(key, { rows, rowTemplates, … }) }} (the record's rows, `rows`' narrowing drawn over them as the lens; Sheet.templates(rows, { …, source }))
173
+ │ ├─ Narrow its rows and templates — one rail → slice={{ slice: Slice.bindRecords(key, { rows, rowTemplates, … }) }} (Sheet.templates(rows, { …, source }))
159
174
  │ ├─ Its panes, each optional → library={[Sheet.library.rows(), Sheet.library.columns(), Sheet.library.tab(…)]} · inspector (+ fields)
160
- │ ├─ Its columns, registers and the driver → Sheet.column.* / Sheet.register.* / Sheet.driver
175
+ │ ├─ Its columns, registers and the driver → Sheet.column.* / Sheet.register.* / Sheet.driver
161
176
  │ ├─ Groups, loose rows between them, read-only sub rows → Sheet.group / Sheet.Types.Entry / Sheet.subRows
162
- │ ├─ Data too large to hold whole → data={paged}, a Data.bindPaged handle
163
- │ ├─ The app's optimiser over the rows in view: the Elara eye → optimise={Func.bind(e3.function)} from Sheet.Types.OptimiseRequest(R) to Sheet.Types.OptimiseResult(R); its answer lands as ONE step of the history (#1409)
164
- │ └─ Drafts checked as they are made, one checked Save → onUpdate | onApply, ready, newRow
177
+ │ ├─ Data too large to hold whole → data={paged}, a Data.bindPaged handle
178
+ │ ├─ The app's optimiser over the rows in view → optimise={Func.bind(e3.function)} from Sheet.Types.OptimiseRequest(R) to Sheet.Types.OptimiseResult(R)
179
+ │ └─ Drafts checked as they are made, one checked Save → onUpdate | onApply, ready, newRow
165
180
  │
166
- ├─ Draw a state-transition or process flow — the Flowchart (see The Flowchart below)
167
- │ ├─ An e3 record of flows by name → <Flowchart record={…} flow="…" /> (record = Record.bind(r), r of Flowchart.Types.Flows)
168
- │ ├─ The record's value, written as literals → Flowchart.values({ [name]: { lanes, states, links, triggers? } }) (a lone flow: one entry)
169
- │ ├─ One flow of the host's, an input's value → <Flowchart data={Data.bind(input)} /> (the input's value Flowchart.value({ … }))
170
- │ ├─ One flow from the app's own tables → <Flowchart data={Flowchart.over(states, { state, links, link, lanes, triggers?, trigger? })} />
171
- │ ├─ Decision triggers and evidence on the transitions → a flow's triggers, a link's trigger / evidence
172
- │ ├─ Selection and ⌥-click path tracing → onSelect*, onTracePath (a click on a lane's header selects the lane)
173
- │ ├─ 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 }}
174
- │ ├─ 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
175
- │ ├─ The flows listed by name, one opened, new ones started → library={[Flowchart.library.flows()]} (the open flow kept under `name`)
176
- │ ├─ Narrow its flows, templates and tabs — one rail → slice={{ slice: Slice.bindRecords(key, { flows?, steps?, … }) }} (`flows` over the same record, counted in the Flows tab)
177
- │ ├─ State and transition templates, the author's own cards → library={[…, Flowchart.library.states(templates.read(), {…, source }), Flowchart.library.transitions(templates.read(), {…, source }), Flowchart.library.tab(rows, {…})]} (templates records, each naming its source of the rail)
178
- │ ├─ 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
179
- │ └─ Edit a flow: lanes, states, transitions — Undo, one Save → record={…}, or data={…} + onApply (every canvas gesture a draft; canConnect vetoes a pair)
181
+ ├─ Schedule bound records on a calendar — the Calendar
182
+ │ ├─ Event records, with their backlog → <Calendar events={{ job: Calendar.events(Record.bind(jobs), { name, icon, title, start, end, resource: { field, of }, entries, backlog }) }} />
183
+ │ ├─ Resources and templates, read whole → resources={{ machines: Calendar.resources(Data.bind(r).read(), {…}) }} · Calendar.templates(rows, {…})
184
+ │ ├─ Narrow it — one rail, one date window → slice={{ slice: Slice.bindRecords(key, { job: { source, range: "start" }, machines?, jobTemplates? }) }}
185
+ │ └─ The app's optimiser → optimise={Func.bind(e3.function)}
180
186
  │
181
- ├─ Draw the app's records at world coordinates — a floor, a site — the Schematic (see The Schematic below)
187
+ ├─ Draw a state-transition or process flow — the Flowchart
188
+ │ ├─ An e3 record of flows by name → <Flowchart record={…} flow="…" /> (record = Record.bind(r), r of Flowchart.Types.Flows)
189
+ │ ├─ The record's value, written as literals → Flowchart.values({ [name]: { lanes, states, links, triggers? } }) (a lone flow: one entry)
190
+ │ ├─ One flow of the host's, an input's value → <Flowchart data={Data.bind(input)} /> (the input's value Flowchart.value({ … }))
191
+ │ ├─ One flow from the app's own tables → <Flowchart data={Flowchart.over(states, { state, links, link, lanes, triggers?, trigger? })} />
192
+ │ ├─ Decision triggers and evidence on the transitions → a flow's triggers, a link's trigger / evidence
193
+ │ ├─ Selection and ⌥-click path tracing → onSelect*, onTracePath
194
+ │ ├─ Its inspector → on by default (inspector={false} takes it away); a state's or a transition's own Details → inspector={{ state, transition }}
195
+ │ ├─ The flows listed by name, one opened, new started → library={[Flowchart.library.flows()]}
196
+ │ ├─ State and transition templates, the author's cards → library={[…, Flowchart.library.states(templates.read(), {…, source }), Flowchart.library.transitions(…), Flowchart.library.tab(rows, {…})]}
197
+ │ ├─ Narrow its flows, templates and tabs — one rail → slice={{ slice: Slice.bindRecords(key, { flows?, steps?, … }) }}
198
+ │ └─ Edit a flow: lanes, states, transitions, one Save → record={…}, or data={…} + onApply (canConnect vetoes a pair)
199
+ │
200
+ ├─ Draw the app's records at world coordinates — a floor, a site — the Schematic
182
201
  │ ├─ A kind per record, under its slot → <Schematic extent={{ width, height }} items={{ racks: Schematic.items(record, { name, icon, x, y, label, … }) }} zones={{ … }} links={{ … }} nets={{ … }} />
183
202
  │ ├─ Editable, or read only → Record.bind(record) · Data.bind(record)
184
- │ ├─ Every gesture one step: Undo, Save per record → built in over an editable kind: Move, Connect (Shift grows a net), an end retargeted, a net extended, Del
185
- │ ├─ Narrow its kinds and templates — one rail → slice={{ slice: Slice.bindRecords(key, { <a kind's slot>: { source: Data.bindPaged(record, { indexes }) }, … }) }} (+ the kind's entries: Data.bindPaged(record)) · narrowed="dim"
186
- │ ├─ A floor too large to read whole: a window at a time → its source lists index.area({ x, y, width, height, at: "centre", cell }) (+ ones led by the rail's fields); past 5,000 rows in view, their density
187
- │ ├─ Find an item by its key, wherever it stands → built in: Find seeks every item kind's record; a pick flies to the item and selects it
188
- │ ├─ On a phone: below 480px of main, nothing drags → built in: Details' Connect to… and the Backlog card's Place, beside an item's x and y, a link's ends, a net's sides and Delete
203
+ │ ├─ Narrow its kinds and templates — one rail → slice={{ slice: Slice.bindRecords(key, { <a kind's slot>: { source: Data.bindPaged(record, { indexes }) }, … }) }} (+ the kind's entries: Data.bindPaged(record))
204
+ │ ├─ A floor too large to read whole: a window at a time → its source lists index.area({ x, y, width, height, at: "centre", cell }); past 5,000 rows in view, their density
189
205
  │ ├─ Shapes from the row's own fields → footprint: (u) => some(Schematic.circle(u.radius)) · a zone's geometry: (a) => some(Schematic.polygon(a.corners))
190
206
  │ ├─ What a card draws from another record → Schematic.items(…, { details: Schematic.details(record, { status, meter, metric, sublabel }) })
191
207
  │ ├─ The layers, from the app's record → layers={Schematic.layers(systems.read(), { label, order?, tone?, color?, visible?, locked?, opacity? })}
192
208
  │ ├─ Templates, the backlog, the index, the layers → Schematic.templates(rows, { …, source }) · library={[Schematic.library.templates(), .backlog(), .index(), .layers()]}
193
- │ ├─ A card dropped on the canvas, or ⏎ on it → an item template adds an item at the point, a backlog row is placed there, a link or net template onto one of its kind; an author's card onto an entity: Schematic.library.tab(rows, { …, drop: (r) => Schematic.patch(R, { … }) }); ⏎ onto the selection
194
- │ ├─ The inspector, a kind's form and its own Details → inspector · Schematic.items(record, { …, fields?: { f: Fields.* }, ready?: (row, key) => Readiness, inspector?: East.function([R, FunctionType([R], NullType)], UIComponentType, …) })
209
+ │ ├─ An author's card dropped onto an entity → Schematic.library.tab(rows, { …, drop: (r) => Schematic.patch(R, { … }) })
210
+ │ ├─ The inspector, a kind's form and its own Details → inspector · Schematic.items(record, { …, fields?, ready?, inspector? })
195
211
  │ └─ What the host hears, and the connect veto → onSelect={fn(Array<Schematic.Types.Ref>)} · canConnect={fn(Schematic.Types.Candidate) → Option<String>}
196
212
  │
197
- ├─ Staff a week's shifts from the app's own duties — the Roster (see Roster below)
198
- │ ├─ The duties: the app's record, a span kind → events={{ duty: Schedule.events(Record.bind(duties), { start, end, resource: { field, of }, shift, group, position?, activity?, hours? }) }}
199
- │ ├─ Who is rostered → resources={{ people: Schedule.resources(staff.read(), { name, icon, label, group, … }), agencies? }}
200
- │ ├─ The lists it reads, over the app's rows → Roster.shifts / groups / positions / activities / proposals(rows, { … })
201
- │ ├─ Publish, and the targets: the app's weeks and cover → periods={Schedule.periods(Record.bind(weeks), { every: "week", status, dismissed? })} · targets={Roster.targets(Record.bind(cover), { day, group, shift, positions, hours })}
202
- │ ├─ Costs in the app's own pay codes → pay={fn(Roster.Types.PayRequest(R)) → Roster.Types.Pay} currency="…"
203
- │ ├─ Who fits a Find fix: the app's fit, on e3 → fit={Func.bind(e3.function)} from Roster.Types.FitRequest(R) to FitResult, over Roster.answer(R) + Roster.fit(R)
204
- │ ├─ The app's optimiser over the week: the Elara eye → optimise={Func.bind(e3.function)} from Roster.Types.OptimiseRequest(R) to Roster.Types.OptimiseResult(R); its answer lands as ONE step of the history (#1409)
205
- │ ├─ Narrow its duties, targets, people, activities and patterns → slice={{ slice: Slice.bindRecords(key, { duty: { source, range: "start" }, targets?, people?, activities?, patterns? }) }}
206
- │ ├─ People by week or by month, its tiles' and marks' words → view={{ layout: "people", period: "week" | "month", date }} · tileTimes="always" | "different" · letters
207
- │ ├─ The shifts' colours, and the app's week patterns → shifts={Roster.shifts(rows, { …, color: s => s.colour })} (an Option<ColorToken>) · patterns={Roster.patterns(rows, { name, icon?, label, days, order? })} · library={[…, Roster.library.patterns()]}
208
- │ └─ The week's figures in a task → Roster.coverage / check / weekHours / rest (R)
213
+ ├─ Staff a week's shifts from the app's own duties — the Roster
214
+ │ ├─ The duties: the app's record, a span kind → events={{ duty: Schedule.events(Record.bind(duties), { start, end, resource: { field, of }, shift, group, position?, activity?, hours? }) }}
215
+ │ ├─ Who is rostered → resources={{ people: Schedule.resources(staff.read(), { name, icon, label, group, … }), agencies? }}
216
+ │ ├─ The lists it reads, over the app's rows → Roster.shifts / groups / positions / activities / proposals(rows, { … })
217
+ │ ├─ Publish, and the targets: the app's weeks and cover → periods={Schedule.periods(Record.bind(weeks), { every: "week", status, dismissed? })} · targets={Roster.targets(Record.bind(cover), { day, group, shift, positions, hours })}
218
+ │ ├─ Costs in the app's own pay codes → pay={fn(Roster.Types.PayRequest(R)) → Roster.Types.Pay} currency="…"
219
+ │ ├─ Who fits a Find fix: the app's fit, on e3 → fit={Func.bind(e3.function)} from Roster.Types.FitRequest(R) to FitResult, over Roster.answer(R) + Roster.fit(R)
220
+ │ ├─ The app's optimiser over the week → optimise={Func.bind(e3.function)} from Roster.Types.OptimiseRequest(R) to Roster.Types.OptimiseResult(R)
221
+ │ ├─ Narrow its duties, targets, people, activities, patterns → slice={{ slice: Slice.bindRecords(key, { duty: { source, range: "start" }, targets?, people?, activities?, patterns? }) }}
222
+ │ ├─ People by week or by month → view={{ layout: "people", period: "week" | "month", date }}
223
+ │ ├─ The shifts' colours, and the app's week patterns → Roster.shifts(rows, { …, color }) · patterns={Roster.patterns(rows, {…})} · library={[…, Roster.library.patterns()]}
224
+ │ └─ The week's figures in a task → Roster.coverage / check / weekHours / rest (R)
209
225
  │
210
- ├─ Book a day's arrivals into lane slots, each bin on its resources — the Allocation (see Allocation below)
211
- │ ├─ The bins: the app's record, an instant kind → events={{ bin: Schedule.events(Record.bind(bins), { at, resource: { field, of: "<lanes>" }, arrival, quantity: { field, unit }, parts: { field, of: "<resources>" }, hold, kind? }) }}
212
- │ ├─ The lanes and the resources → resources={{ <lanes>: Schedule.resources(rows, { name, icon, label, offset? }), <resources>: Schedule.resources(rows, { name, icon, label, min, max, … }) }}
213
- │ ├─ What it books from → arrivals={Allocation.arrivals(rows, { label, quantity, hold, kind?, values?, … })}
214
- │ ├─ Publish: the app's days → periods={Schedule.periods(Record.bind(days), { every: "day", status })}
215
- │ ├─ Who fits where: the app's fit, on e3 → fit={Func.bind(e3.function)} from Allocation.Types.FitRequest(R) to FitResult, over Allocation.answer(R) + Allocation.fit (+ Allocation.lookahead(R))
216
- │ ├─ The app's optimiser over the day: the Elara eye → optimise={Func.bind(e3.function)} from Allocation.Types.OptimiseRequest(R) to Allocation.Types.OptimiseResult(R); its answer lands as ONE step of the history (#1409)
217
- │ ├─ Narrow its bins, lanes, resources and arrivals — one rail → slice={{ slice: Slice.bindRecords(key, { bin: { source, range: "at" }, <lanes>?, <resources>?, arrivals? }) }}
218
- │ ├─ Its panes → library={[Allocation.library.arrivals(), Allocation.library.resources()]} · inspector (+ the bin kind's own inspector)
219
- │ ├─ The app's bin fields on the board, and its own issues → columns={[{ key, label, text }]} · check={fn(CheckContext(R)) → Array<Issue>}
220
- │ └─ The board's figures in a task → Allocation.loads / candidates / check / slots (R)
226
+ ├─ Book a day's arrivals into lane slots, each bin on its resources — the Allocation
227
+ │ ├─ The bins: the app's record, an instant kind → events={{ bin: Schedule.events(Record.bind(bins), { at, resource: { field, of: "<lanes>" }, arrival, quantity: { field, unit }, parts: { field, of: "<resources>" }, hold, kind? }) }}
228
+ │ ├─ The lanes and the resources → resources={{ <lanes>: Schedule.resources(rows, { name, icon, label, offset? }), <resources>: Schedule.resources(rows, { name, icon, label, min, max, … }) }}
229
+ │ ├─ What it books from → arrivals={Allocation.arrivals(rows, { label, quantity, hold, kind?, values?, … })}
230
+ │ ├─ Publish: the app's days → periods={Schedule.periods(Record.bind(days), { every: "day", status })}
231
+ │ ├─ Who fits where: the app's fit, on e3 → fit={Func.bind(e3.function)} from Allocation.Types.FitRequest(R) to FitResult, over Allocation.answer(R) + Allocation.fit (+ Allocation.lookahead(R))
232
+ │ ├─ The app's optimiser over the day → optimise={Func.bind(e3.function)} from Allocation.Types.OptimiseRequest(R) to Allocation.Types.OptimiseResult(R)
233
+ │ ├─ Narrow its bins, lanes, resources and arrivals — one rail → slice={{ slice: Slice.bindRecords(key, { bin: { source, range: "at" }, <lanes>?, <resources>?, arrivals? }) }}
234
+ │ ├─ Its panes → library={[Allocation.library.arrivals(), Allocation.library.resources()]} · inspector
235
+ │ ├─ The app's bin fields on the board, and its own issues → columns={[{ key, label, text }]} · check={fn(CheckContext(R)) → Array<Issue>}
236
+ │ └─ The board's figures in a task → Allocation.loads / candidates / check / slots (R)
221
237
  │
222
238
  ├─ Render deployed surfaces in a React app (@elaraai/e3-ui-components)
223
239
  │ ├─ Which e3, and how requests reach it → <E3Provider config={{ apiUrl, repo, workspace, token, fetch }}>
@@ -226,331 +242,78 @@ Task → What do you need?
226
242
  │ └─ e3 running in the page, no server → apiUrl and fetch from e3-web's createWebE3
227
243
  │
228
244
  └─ Let a user ask "did X change Y?" against a dataset and trust the answer
229
- └─ <Experiment data configs … /> (generic over the row; runs e3.functions)
245
+ └─ <Experiment data configs experiment? design? journal? columns subject /> (generic over the row; runs e3.functions)
230
246
  ```
231
247
 
232
- ## Core Concepts
248
+ ## Bindings
233
249
 
234
250
  ### `ui(name, inputs, fn, options?)`
235
251
 
236
- Wraps `e3.task()` with `kind: "ui"` and a **manifest** auto-derived from the IR:
237
- - **Compute-time reads** — every dataset in `inputs` (the runner passes their
238
- values to `fn` as positional args).
239
- - **Reactive reads** — every `Data.bind(dataset).read()` / `.has()` in the IR.
240
- - **Reactive writes** — every `Data.bind(dataset).write()` in the IR.
241
- - **Bound functions** — every `Func.bind(fn)` in the IR.
242
-
243
- `fn` returns `UIComponentType`, exactly: `ui()`'s signature takes no other
244
- function, and refuses one cast past it when the task is defined, naming the
245
- task and the type. A task is rendered by its `ui` role alone. Default runner
246
- is `['east-c', 'run']`.
247
-
248
- > `Data.bind` takes the def itself (`e3.input(...)` or a task), so the bound
249
- > path and value type are captured at IR-build time by construction.
252
+ Wraps `e3.task()` with a `ui` role and a **manifest** derived from the IR: the
253
+ datasets in `inputs` (their values passed to `fn`), every dataset, record and
254
+ paged source the body binds, and every `Func.bind`. `fn` returns
255
+ `UIComponentType` exactly. It runs on `east-c` by default; where only the Node
256
+ runner is installed, pass `{ runner: { runtime: "east-node" } }` as
257
+ `options`. Bindings
258
+ take the def itself (`e3.input`, `e3.task`, `e3.record`, `e3.function`), so the
259
+ path and type are fixed when the IR is built.
250
260
 
251
261
  ### `Data.bind(dataset, options?)`
252
262
 
253
- A workspace-scoped reactive binding to a dataset — pass the `e3.input` def
254
- (or an `e3.task`, which binds its output dataset). Handle methods:
255
-
256
- | Method | Meaning |
257
- |---|---|
258
- | `.read()` | current value (type `T`); tracks the dependency so `<Reactive>` re-renders |
259
- | `.has()` | whether the dataset is set |
260
- | `.write(v)` | set the value |
261
- | `.writeAndStart(v)` | set the value and start the dataflow |
262
- | `.status()` | binding status variant (e.g. `.status().hasTag('stale')`) |
263
- | `.commit()` | apply staged edits (staged mode) |
264
- | `.discard()` | drop staged edits (staged mode) |
265
- | `.binding` | the binding handle to pass to `<Diff bindings={[…]} />` |
263
+ A reactive binding to an `e3.input` or a task's output. `read()` tracks the
264
+ dependency, so `<Reactive>` re-renders when it changes. Modes:
265
+ - `'direct'` (default): each `write()` mutates the dataset.
266
+ - `'staged'`: `write()` accumulates a patch; `commit()` applies it, `discard()`
267
+ drops it, and `<Diff bindings={[b.binding]} />` reviews it.
266
268
 
267
- **Modes** (`options.mode`):
268
- - `'direct'` (default) — each `write()` immediately mutates the destination.
269
- - `'staged'` — `write()` accumulates a patch; `commit()` applies it, `discard()`
270
- drops it.
269
+ A record a builder reads whole beside its pages (a templates list, the
270
+ resources a check reads) binds with `Data.bind`, which the manifest preloads.
271
+ `Record.bind` stays the door a Save commits through: the manifest never
272
+ preloads a record `Record.bind` reads beside `Data.bindPaged`, so its `read()`
273
+ fails on e3.
271
274
 
272
275
  ### `Data.bindPaged(dataset, options?)`
273
276
 
274
- A read-only, WINDOWED binding for a collection too large to hold whole — the
275
- paged sibling of `Data.bind`. There is no `write` / `commit`: a window is not a
276
- value you can diff or stage.
277
-
278
- | Method | Meaning |
279
- |---|---|
280
- | `.page(offset, limit)` **❗** | one window; `none` while in flight, `some([])` at exhaustion; a failed fetch throws its reason |
281
- | `.total()` | the source's element count, once any window has landed |
282
- | `.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 |
283
- | `.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 |
284
- | `.refresh(target)` | move the source: `some(hash)` to that snapshot, `none` to the dataset's current one; returns at once |
285
-
286
- `Data.bindPaged` is how paged data reaches a component. Pass the handle as a
287
- `<Plan>`, `<Table>` or `<Sheet>`'s `data`: the component recognises it by its
288
- East type (east-ui's `Paged.Types.PinnedSource`) and pages it, and nothing else
289
- produces a paged source — a collection already in hand is local data, passed
290
- inline. The def is an `e3.input`, an `e3.record`, or an `e3.task`, whose output
291
- it binds. A dataset too large to hold whole is made where data is made — a task
292
- that generates or loads its rows — never written into the package as an
293
- input's value:
294
-
295
- ```tsx
296
- // Package side: the rows come from a task, from a small authored count.
297
- // const units = e3.task('units', [unitCountInput], generateUnits); // Dict<String, UnitRow>
298
- <Reactive>{$ => {
299
- const paged = $.let(Data.bindPaged(units));
300
- return <Plan axis={axis} data={paged} series={series} />;
301
- }}</Reactive>
302
- ```
303
-
304
- Every window, total and search belongs to ONE snapshot, so rows from two
305
- snapshots never sit side by side. The source follows its dataset: when a
306
- dataflow run or another user's write changes it, the source moves to the new
307
- snapshot, and the windows still on screen are fetched again from it — `page`
308
- reads `none` for each until it lands, so a view holds its last frame while
309
- `revision()` has changed. Call `refresh` from an event handler after a write the
310
- view confirmed, to show it without waiting for the move. A failed fetch throws
311
- rather than reading `none`, so wrap the read in `$.try` to render the failure;
312
- a read a couple of seconds later fetches it again. A request that can never
313
- succeed — a dataset that is not a collection, an index the record does not
314
- declare — keeps throwing until the source moves.
315
-
316
- **Through a record's index** (`options.index`) the window is the INDEX's order
317
- rather than the record's, and each row carries what a view needs to render
318
- without touching the record:
319
-
320
- ```tsx
321
- const queue = $.let(Data.bindPaged(plans, { index: "by_status" }));
322
- // rows: Array<{ ik: StatusKey, key: PlanKey, value: Projection, row: Option<Plan> }>
323
- <Table data={queue} columns={{
324
- ik: { header: "Status", value: (ik) => ik.status },
325
- value: { header: "Plan" },
326
- }} />
327
- ```
328
-
329
- Name one of the indexes the record declares: the name is checked against the
330
- record, and the window's type — the index key and the covering projection —
331
- comes from the index's declaration, so the rows are checked at compile time.
332
- `join: true` reads each entry's row from the record too; leaving it off is the
333
- point of a covering projection, since the view then touches the index's
334
- segments and none of the record's.
335
-
336
- `.seek` takes a `from..to` range as well as a key or prefix, bounding a leading
337
- prefix of the key's flattened fields — `late, 3..ok` over a `{status, due}`
338
- index key — which is what a time window or a status band asks for. A range
339
- names at least one end; open at both it names no run, and the seek refuses it.
340
- In the search box quoting is the escape: a quoted value is exact, and a `..`
341
- inside it is text, so `"../config"` finds that key rather than a range.
342
-
343
- ### Indexed records and shared Slice
344
-
345
- Declare field indexes in the record's `indexes` with `index.on([fields...])`, or
346
- computed indexes with `index.key(fn)` / `index.keys(fn)`. Their existing
347
- declared key types supply the controls; do not redeclare those types in Slice. A
348
- scalar computed key uses the index name as its field; a Struct key supplies
349
- named fields in key order. `keys` accepts a scalar or a single-field Struct and
350
- permits one exact member, keeping pages and counts unique by primary ID.
351
- Arbitrary compound fan-out remains available through `{ index }`; Slice refuses
352
- it. `Data.bindPaged(record, { indexes: [names...] })` carries their field/key
353
- types and joins rows by default. The indexes a binding lists carry one
354
- projection, or each carries the whole row — as an area index does — or nothing:
355
- one that carries the row is read without a join, the others with one, and any
356
- other mix is refused at build, naming the index.
357
-
358
- **Beside a nested series index** (`index.nested({ collections, tile, summary
359
- })`), the record's other indexes carry each row without the collections it
360
- declares, and a binding listing any of them lists it too:
361
- `Data.bindPaged(machines, { indexes: ["machines_by_site_status",
362
- "machines_in_time"] })`. Such a binding pages the lean rows (its projection the
363
- record's row, each listed collection empty) and never joins one: `join: true` is
364
- refused, and so is an index with a `value` of its own beside it, which is bound
365
- apart. A row is read whole by its key. The binding's type carries how each
366
- collection is declared (what it holds, its times, its rollups), and the nested
367
- index's own entries — items, totals and subtotals — are read a cell at a time: a
368
- page or a count of it is refused. A component given an indexed binding as `data`
369
- reads its unfiltered view, a page at a time in its default index's order. A
370
- `<Plan>` given such a binding as `data`, or a Slice whose `rows` source is one,
371
- holds its `series` to the index in the editor: a series reading a collection the
372
- index does not declare, by other times than it files by, items as values, a
373
- subtotal by a rollup it does not keep, or runs rolled up that it files under no
374
- parent, fails to compile, the error naming the index and what to write. The Plan
375
- holds them again as it is built, a series list held in a variable too, and
376
- refuses as well a function of the row mapping a collection the page carries
377
- empty (a function it cannot see into, given the row, is refused rather than
378
- guessed), a subtotal of values drawn as another number than stored or at a
379
- resolution finer than the index's tile, a read by name where the binding lists
380
- no nested series index or on an axis other than time, and an index keeping no
381
- totals. Rows paged whole (`Data.bindPaged(dataset)`) are read as before.
382
-
383
- **A Plan over them reads a cell at a time** (#1438; the Plan's `plan-nested`
384
- example, `planNestedAll`: every series kind over two hundred works and ten
385
- years — chart, events, cards and buckets switched off to start — its series
386
- picked from the library, a crew's hours typed into). The rail pages the rows lean; for the rows in view and 25
387
- either side, in blocks of fifty, the Plan reads each collection its series
388
- draw — one range a row a level its items are filed at — in one batch of
389
- searches and one read of the entries, and draws them with the same series as
390
- over rows read whole. A pan reads only the tiles it adds; a zoom reads the
391
- levels it shows. Past 10,000 items of a collection in the cells it wants, the
392
- rows shade from the index's totals at its summary tile (runs and chips by the
393
- share of the bucket booked, marks by how many, values folded as the series
394
- folds them), or are hatched, a banner saying how many and why. A parent reads
395
- what e3 keeps for it: a table's or a heat's aggregate and a group's strip are
396
- its subtotals, one range at the resolution, by the rollup its `fold` and
397
- `aggregate` make (which the index must keep: `values({ rollup })`); a span's
398
- bands are the items e3 files under it (`items(…, { rollup: true })`) — so a
399
- folded parent reads none of the rows beneath it. Editing over them: a gesture
400
- drafts each row it touches read whole by its key, every row asked meanwhile in
401
- one request; each drafted row's Save, previewed by e3 (#1437), is laid over
402
- the cells, so the moved item and every subtotal over it draw before Save,
403
- while which rows show keeps to what is saved; Save restates each listed
404
- collection's change by key (`Record.onApply(record, { keyed: true })`), so
405
- another planner's item added meanwhile is kept. A table's `edit: true` takes
406
- typed numbers the same way (the ledgers: a reading typed into a leaf moves
407
- every subtotal above it at once). What each series reads is known as the Plan
408
- is built, so its series are a list of `Plan.series.*` values: in `series`, or
409
- in `Plan.pick(key, [...])` passed to `pick` as it returns it, which lets a
410
- viewer switch each series on and off from the library's Series tab
411
- (`Plan.library.series()`). A list held as an East expression, or a pick held
412
- in an East variable (`$.let`), is refused: the Plan could not see what its
413
- series read. While cells are read — a pan, a zoom, a scroll, a commit — the
414
- rows waiting on them wash, their plots busy, until the cells land. Its horizon
415
- spans the time every series reads, shown or not, as e3 keeps it beside the
416
- index (its span, `<index>_span`): from the first month to the last any row's
417
- items or values touch, in the collections the series read, read once and again
418
- at each commit — a series switched off moves no edge of it, and with every
419
- series off the strip still spans the data — so the brush reaches every part of
420
- the data from the start, not the window's own margins. Its bars are how much
421
- the shown series' collections hold in each month, as the span counts it: a
422
- bar each month, quarter or year — the finest that keeps 4px a bar — toned on
423
- the heat ramp by its count, the largest in a meta line under the caption
424
- (`max 1,559 items / mo`), and a bar's hover saying its period and count. Its
425
- canvas holds its own window, and a zoom zooms it: as many buckets of the new
426
- resolution as it showed of the old, about the same middle, inside that span —
427
- the year shows the whole of it.
428
-
429
- **A builder narrows through `Slice.bindRecords` alone** (#1340): one rail on
430
- its toolbar, `Slice.bindRecords(key, { [source]: { source:
431
- Data.bindPaged(record, { indexes }), label?, icon?, fields, range?, search?,
432
- initial? } }, { presets? })`, passed as `slice={{ slice, affordances?,
433
- persist? }}`. Each source is named after what it narrows and filters every
434
- place its records appear — the main area, the Choosers and the Library tab
435
- that lists them; the Sheet's `rows` source draws its narrowing over the
436
- record's rows as the lens instead (#1349) — and the builder reads each
437
- source's keys itself. Every
438
- source with a `range` shares the builder's one time window; a Plan's `rows`
439
- source and its resource kinds' take none, so the dates on screen never decide
440
- which rows it lists. Calculations —
441
- coverage, costs, loads, checks, totals — read every record, whatever the
442
- rail hides. Refused at build, each naming the change: `Slice.bind`, a single
443
- `Slice.bindRecord`, a source the builder does not take,
444
- `data={Slice.rows(slice)}` or `window={Slice.rows(slice)}`, the Roster's
445
- `visiblePeople`, and an event kind's own `slice` or `filter`. Every
446
- builder has moved: the Allocation, the Roster, the Calendar, the Plan, the
447
- Sheet, the Flowchart and the Schematic.
448
-
449
- Templates are records: each templates list reads a templates record and names
450
- its source of the rail (`source`), and a list written in the code is refused.
451
- A record a builder reads whole beside its pages — a templates list, the
452
- resources a check reads — binds with `Data.bind`: a UI task's manifest
453
- preloads it, but never a record `Record.bind` reads beside `Data.bindPaged`,
454
- whose `read()` then fails on e3. `Record.bind` stays the mutation door a Save
455
- commits through. east-ui's own Table, Library and charts keep
456
- `Slice.bind`. Existing single-index `Data.bindPaged(record, { index, join })`
457
- remains separate.
458
-
459
- Controls come from indexed field types: unit Variant/Boolean/hints become choice
460
- chips; Strings use prefix suggestions; numbers/dates use typed ranges; Options
461
- add Unset; Sets permit one exact member. Counts are exact original-record counts,
462
- pending until known. The rail's summary names, in each source's own words, the
463
- sources a narrowing hides rows of (`2 of 30 print job events`), and nothing while
464
- none does; folded, its Filters popover heads each source's fields with the
465
- source's count, as a Library tab counts — `6`, or `2 of 30` while narrowed
466
- (#1358). Only a supported path through one index can combine choices.
467
- Never filter resident pages or materialize a record to discover its choices.
468
- Local arrays use `Slice.bind(key, rows, options?)`; neither arm needs a type
469
- argument for `Slice.rows(slice)`.
470
-
471
- Calendar event windows preserve overlap with `[from, to)`, including carry-in
472
- and whole-window spans. Declare an interval index among the record's indexes,
473
- `index.interval({ on?, from: "start", to: "end" })` (optional leading `on` fields), name
474
- the event kind's source after its slot with `range: "start"` (`job: { source:
475
- Data.bindPaged(jobs, { indexes: ["jobs_by_time"] }), range: "start" }`), and give
476
- the kind `entries: Data.bindPaged(jobs)` for its original-key reads. A kind
477
- narrowed through its source takes no `window` or `backlogWindow`. Do not
478
- replace it with a start-only query or guessed lookback. Optional missing ends
479
- are instants; an instant at `from` is included and one at `to` is excluded.
480
- Backlog remains part of the same authoritative record.
481
-
482
- A **window over a drawing** — the rows whose box meets a viewport — reads
483
- through an area index (`index.area`, the **e3** skill) listed in a
484
- source's binding: `Data.bindPaged(racks, { indexes: ["racks_by_area",
485
- "racks_by_hall_area"] })`. The Schematic reads a kind so wherever the kind's source
486
- of its rail lists one, the window its view shows (see The Schematic below,
487
- `schematicRecordIndexes`). A read of a source — its `pageWhere` and
488
- `countWhere` — takes a read, `{ where, area }`: the narrowing, and for a read
489
- by area its clause beside it, `some(variant("window", { minX, minY, maxX,
490
- maxY }))` in world units, or `some(variant("unplaced", null))` for the rows not
491
- yet placed, on an index whose `x` and `y` are Options; any other read gives
492
- `area: none`. The narrowing's exact choices of the fields an area index is led
493
- by pick it. The record slice plans a window as at most 266 searches a
494
- combination of those choices, sent in one request, and reads every row whose
495
- box meets the viewport grown by an eighth of its larger side, each once —
496
- beside rows of the searched cells that it misses, which the reader draws or
497
- not. The window is the reader's, never the rail's: no choice holds it, and the
498
- rail's state, its presets and `contains` keep the narrowing alone. A read no
499
- listed area index serves — choices beside the window no area index is led by
500
- exactly, a range or a prefix beside it, or more than one value of a Set field,
501
- which would read a row twice — is refused, naming why. An area index carries
502
- its rows, so a window reads the index alone, without a join, each entry's
503
- `value` its row. e3's parts of a generated key are its index's kind's, never a
504
- field's name (#1432): a row's field named `area` or `__area` is a field of the
505
- rail like any other, and may lead an area index a window reads through.
506
-
507
- Sessions retain original-key drafts across paging, narrowing and remount in the
508
- same UI store. Save includes hidden edits and confirms primary rows at the
509
- committed revision. A saved row leaving the narrowing produces footer feedback;
510
- moving off a resident page does not. Slice persistence saves query state, not
511
- unsaved drafts. The Roster and the Allocation keep a session for each record
512
- they write — the Roster's duties, weeks and targets, the Allocation's bins and
513
- days — under one history: Save sends each record's drafts as its own request,
514
- and their figures read every person, resource and event of the period,
515
- whatever the rail shows. The Schematic keeps one for each kind it writes, and
516
- a kind read by area keeps its drafts by key wherever the window goes: a row
517
- moved off the window draws where its draft places it while the narrowing holds
518
- its stored row, and Save writes it through the kind's patch door.
519
-
520
- Search examples: `planRecordIndexes`, `sheetRecordIndexes`,
521
- `calendarRecordIndexes`, `rosterRecordIndexes`, `schematicRecordIndexes` (a
522
- window read by area), their Mobile counterparts, and `flowchartRecordIndexes`
523
- (scalar, compound and membership computed keys).
524
- Each shows its full reactive bindings and JSX inline.
277
+ A read-only, windowed binding for a collection too large to hold whole, passed
278
+ as a `<Plan>`, `<Table>` or `<Sheet>`'s `data`; nothing else produces a paged
279
+ source. Every window, total and search belongs to one snapshot (`revision()`,
280
+ the content hash), and the source follows its dataset when a run or another
281
+ user moves it; `page` reads `none` for each window until the new one lands. A
282
+ failed fetch throws, so wrap a hand-read in `$.try`.
283
+
284
+ - A dataset too large to hold whole is made where data is made — a task that
285
+ generates or loads its rows (bound as the task def) — never an input's
286
+ inline value.
287
+ - Through a record's index (`{ index: "by_status" }`) the window is in the
288
+ index's order and each row is `{ ik, key, value, row }`; `join: true` also
289
+ reads the row. The index name and the row type are checked against the
290
+ record's declaration.
291
+ - `.seek` takes a key, a prefix, or a `from..to` range over a leading prefix of
292
+ the key's fields (`late, 3..ok`); quote a value to make it exact.
293
+ - `{ indexes: [...] }` lists several indexes for a `Slice.bindRecords` source.
294
+
295
+ ### `Record.bind(record, mutations?)`
296
+
297
+ The handle to an `e3.record`: `read()`, `mutate.<name>(args…)` for each
298
+ mutation named in the list (with `mutate.status()`, `pending()`, `error()`),
299
+ `start()` to run the dataflow over the new state, and `history()` for its
300
+ commits. Builders take `Record.bind(record)` of a record declaring
301
+ `patch: mutation.patch()` and commit every Save through it; a stale Save is a
302
+ conflict naming the entry, and nothing is overwritten. `Record.onApply(record,
303
+ { keyed? })` adapts a record for a host's `onApply`.
525
304
 
526
305
  ### `Func.bind(fn)`
527
306
 
528
- A workspace-scoped call handle for a named package function
529
- (`e3.function`) — e3's RPC method. `call(args…)` launches fire-and-forget
530
- (safe in sync `onClick` handlers); the outcome arrives reactively:
531
-
532
- | Method | Meaning |
533
- |---|---|
534
- | `.call(args…)` | launch with these args; latest-wins if one is already running |
535
- | `.read()` | `Option(Output)` — last successful result |
536
- | `.status()` | `idle` \| `running` \| `succeeded` \| `failed` \| `cancelled` |
537
- | `.error()` | `Option` of failure detail (message, kind, stdout/stderr) |
538
- | `.pending()` | true while a call is in flight |
539
- | `.cancel()` | stop waiting (client-side; the server still finishes) |
540
- | `.binding` | descriptor (`{ name }`) |
541
-
542
- All handles bound to the same function share one tracked channel — one
543
- component can launch while another renders the spinner. Functions are
544
- **bounded** RPC (server deadline + result-size limit); long compute
545
- belongs in dataflow tasks (`writeAndStart`). Pass the `e3.function` def —
546
- name, parameter types and return type all come from it, so the binding
547
- cannot drift from the deployed signature.
307
+ A call handle for an `e3.function` (bounded RPC: a server deadline and a
308
+ result-size limit; long compute belongs in dataflow tasks and
309
+ `writeAndStart`). `call(args…)` is fire-and-forget and safe in a sync
310
+ `onClick`, latest-wins; the outcome arrives reactively through `read()`,
311
+ `status()`, `error()` and `pending()`. All handles bound to one function share
312
+ one channel, so one component can launch while another shows the spinner.
548
313
 
549
314
  ```tsx
550
- // Package side, in scope at authoring time:
551
- // const forecastFn = e3.function('forecast', East.function([IntegerType, FloatType], FloatType, …));
552
315
  <Reactive>{$ => {
553
- const forecast = $.let(Func.bind(forecastFn));
316
+ const forecast = $.let(Func.bind(forecastFn)); // e3.function('forecast', East.function([IntegerType, FloatType], FloatType, …))
554
317
  const run = $.const(East.function([], NullType, $ => { $(forecast.call(12n, 1.05)); }));
555
318
  return (
556
319
  <VStack gap="3">
@@ -561,2472 +324,109 @@ cannot drift from the deployed signature.
561
324
  }}</Reactive>
562
325
  ```
563
326
 
564
- ### `<Diff bindings={[…]} />`
565
-
566
- Renders a review of pending changes for any combination of bindings — the
567
- staged-mode companion for "review before apply" UX. Pass the `.binding`
568
- accessors.
569
-
570
- ### `<Ontology binding={view.binding} />`
571
-
572
- A graph editor (`NodeType` / `LinkType` / `OntologyType`) bound to a dataset, for
573
- editing typed node/link graphs. Stack a `<Diff>` beside it to surface the pending
574
- node/link patch.
575
-
576
- ### `<Experiment data configs … />`
577
-
578
- An interactive **causal-experiment** surface: an end user asks *"did X change
579
- Y?"* against a bound dataset and reads a derived, plain-language answer across
580
- up to four tabs (The answer / Can we trust it? / How much? / Prove it). Generic
581
- over the dataset's row (like `<Table>`). The bound `configs` list holds the
582
- **questions** — each a full `ExperimentConfig` plus an optional precomputed
583
- `result`/`design`; selecting one seeds the working config. **Run** calls the
584
- single bound `experiment` function; the verdict-first headline, every word,
585
- colour and bar are derived from the returned numbers — nothing is authored.
586
- **Commit** appends to the journal.
587
-
588
- | Prop | Binding | Meaning |
327
+ ## The builders
328
+
329
+ `<Plan>`, `<Sheet>`, `<Calendar>`, `<Roster>`, `<Allocation>`, `<Flowchart>`
330
+ and `<Schematic>` share one contract:
331
+
332
+ - **Data is the app's own records.** Each builder maps roles onto the app's
333
+ fields (`title: "title", start: "start", resource: { field, of }`) and
334
+ stores nothing in a shape of its own. Editable data is
335
+ `Record.bind(record)` over a record declaring `mutation.patch()`.
336
+ `Schedule.events` / `resources` / `templates` / `periods` are the shared
337
+ vocabulary for kinds of events and resources (Plan, Calendar, Roster,
338
+ Allocation).
339
+ - **Every gesture is a draft.** Drags, drops, typed cells and form edits are
340
+ steps of one editing session with Undo / Redo, saved with one checked Save
341
+ through each record's patch door (or the host's `onApply`). Drafts survive
342
+ paging, narrowing and remount.
343
+ - **It renders in its own frame**: one toolbar, the canvas, a footer, and the
344
+ panes its props ask for (`library`, `inspector`). Give it a box with a height.
345
+ - **One rail narrows it**: `slice={{ slice: Slice.bindRecords(key, { … }) }}`,
346
+ each source named after what it narrows (an event kind's slot, a resource
347
+ kind's slot, `rows`, a templates list's `source`), each
348
+ `Data.bindPaged(record, { indexes })` over that record's declared indexes.
349
+ Sources with a `range` share the one time window. Calculations (coverage,
350
+ costs, loads, checks) read every record, whatever the rail hides.
351
+ Templates lists are records, each naming its rail `source`.
352
+ - **Large records are read through their indexes** (declared in the record,
353
+ the **e3** skill): an event kind through an interval index
354
+ (`index.interval({ from: "start", to: "end" })`) with `range: "start"` and
355
+ `entries: Data.bindPaged(record)` for reads by key; events on paged
356
+ resources a cell at a time through `index.series` + `index.summary`; a
357
+ drawing a window at a time through `index.area`.
358
+ - **The app's optimiser**: `optimise={Func.bind(fn)}`, an `e3.function` from
359
+ the builder's `Types.OptimiseRequest` to its `Types.OptimiseResult`; its
360
+ answer lands as one undoable step.
361
+ - **Misuse is refused at build**, naming the change — forms from earlier
362
+ releases included — so read the error rather than guessing.
363
+
364
+ | Builder | What it draws | Start from |
589
365
  |---|---|---|
590
- | `data` | `Data.bind(dataset)` | the rows to experiment on (`Array<Struct<Row>>`) |
591
- | `configs` | `Data.bind(dataset)` | **required** — the questions (`Array<Experiment.Types.Configuration>`); each may carry a precomputed `result` and/or `design` |
592
- | `experiment` | `Func.bind(fn)` | optional universal estimator — `(rows, config) → ExperimentResult`; omit when every question is precomputed |
593
- | `design` | `Func.bind(fn)` | optional — `(rows, config, result, designConfig) → ExperimentDesign` (the "Prove it" trial recipe) |
594
- | `journal` | `Data.bind(dataset)` | optional committed-experiment log; **Commit** appends |
595
- | `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 |
596
- | `subject` | — | the domain noun for a row: `'batch'` (auto-pluralised) or `{ one, many }`; replaces the neutral `record(s)` |
597
- | `readonly` | — | render without Run / Commit / edit affordances |
598
- | `defaultTab` | — | initial tab: `'answer'` (default) \| `'trust'` \| `'dose'` \| `'validate'` |
599
-
600
- ```tsx
601
- <Reactive>{$ => {
602
- const data = $.let(Data.bind(batchesInput));
603
- const configs = $.let(Data.bind(experimentConfigsInput)); // the questions
604
- const journal = $.let(Data.bind(experimentJournalInput));
605
- const experiment = $.let(Func.bind(experimentFn)); // (rows, config) → ExperimentResult
606
- return (
607
- <Experiment data={data} configs={configs} experiment={experiment} journal={journal}
608
- columns={{ bond_strength: { label: 'Bond strength', unit: 'MPa', higherIsBetter: true } }}
609
- subject="batch" />
610
- );
611
- }}</Reactive>
612
- ```
613
-
614
- The render-contract value types are reached via `Experiment.Types.*`
615
- (`Experiment.Types.Config` / `.Configuration` / `.Result` / `.Design` /
616
- `.Verdict` / …, like `Table.Types.*`); the result's honesty `verdict`
617
- (`causal` / `modest` / `adjustment_insufficient` /
618
- `non_identifiable_positivity` / `not_estimable`) drives the headline, and the
619
- two refusal verdicts (`adjusted = none`) render explanatory zones instead of a
620
- number.
621
-
622
- ### The Decide loop — `Decision.bind` + `<DecisionQueue>` + `<DecisionJournal>`
623
-
624
- Reasoning tasks emit decisions as `Array<Decision.Types.Decision>` datasets
625
- (built with `Decision.make` / `Decision.option` / `Decision.reference` /
626
- `Decision.judgement`). `Decision.bind` unions the bound views into **one
627
- per-surface handle** — it owns what no single binding can: the union +
628
- write-routing by case id, the shared case **selection** (every component on
629
- the handle stays in sync by construction), and the derived per-case **commit
630
- gate**. The operator's staged contribution is a judgements dict bound the
631
- same way.
632
-
633
- ```tsx
634
- const roster = $.let(Data.bind(rosterDecisions, { mode: 'direct' })); // source ⊕ patch view
635
- const orders = $.let(Data.bind(orderDecisions, { mode: 'direct' }));
636
- const judgements = $.let(Data.bind(judgementsInput, { mode: 'staged' }));
637
- const handle = $.let(Decision.bind([RosterConstraint], { decisions: [roster, orders], judgements }));
638
- ```
639
-
640
- The optional type token is the solution's **constraint contract** (a by-name
641
- `VariantType` shared with the reasoning task, which `$.matchTag`s injected
642
- constraints fully typed); omit it for the default primitive op-variant.
643
- Handle methods: `queue()` (the unioned cases) · `selected()` / `select(id)` /
644
- `clearSelection()` · `decision()` · `update(d)` (probe edit through the owning
645
- patch) · `judgement(id)` / `answer(id, promptId, answer)` /
646
- `addKnowledge(id, text)` / `inject(id, constraint)` · `resolve(id, verdict)`
647
- (verdict + removal + selection clear) · `commitState(id)` (gated / blocked /
648
- handoff / ready).
649
-
650
- **`<DecisionQueue handle={handle} …/>`** — *the* Decide surface: one queue over
651
- the handle's cases, urgency-sorted with the routine tail collapsed; selecting a
652
- row expands one facet at a time beneath it; Apply / Reject resolve through the
653
- handle.
654
-
655
- | Prop | Meaning |
656
- |---|---|
657
- | `handle` | **required** — the `Decision.bind` handle |
658
- | `heading` | header label (e.g. `"Decisions waiting"`) |
659
- | `modify` | per-kind probe editor `(decision, update) => UIComponent` — the Modify facet; `update(edited)` writes back through the owning binding |
660
- | `evidence` | per-decision canvas `(decision) => UIComponent` inside the Evidence facet |
661
- | `defaultExpanded` | the case shown expanded before any selection (an `Option` — derive from bound data, e.g. a `firstMap`) |
662
- | `defaultFacet` / `facets` | which facet opens first (`'evidence'` default) / include-list of data facets (`modify` stays callback-gated) |
663
- | `onApply` / `onReject` | side-effect hooks fired with the decision on resolve |
664
- | `slice` | author-bound slice handle over the queue (see below) — narrowing applies before the urgency sort whether or not a rail mounts |
665
- | `affordances` | rail affordances when `slice` is set (default `["filter", "search"]`; `brush` rejected) |
666
- | `groups` / `groupBy` / `collapsible` | Group-by toolbar: custom label → `(decision) => String` accessors atop built-in Urgency / Kind / None; which opens first; collapsible heads |
667
- | `maxHeight` / `density` | pinned-header scroll cap / density preset |
668
-
669
- **The queue's scope is an ordinary author-owned slice** (the `Table` pattern —
670
- you own the key and config, so scopes are per-surface over one shared handle,
671
- and shareable with any other component). Bind it over the decision envelope
672
- with the handle's own union as the rows feed:
673
-
674
- ```tsx
675
- const slice = $.let(Slice.bind('ops.queue.slice', handle.queue(), {
676
- fields: { kind: { label: 'Kind' }, title: { label: 'Title' }, value: { label: 'Value' } },
677
- search: ['kind', 'title'],
678
- initial: { kind: ['roster'] },
679
- }));
680
- return <DecisionQueue handle={handle} heading="Decisions waiting" slice={slice} />;
681
- ```
682
-
683
- Pass `affordances={[]}` to keep the seeded narrowing with **no** rail — an
684
- invisible author scope.
685
-
686
- **`<DecisionJournal handle={handle} />`** — the resolved-cases read-back (the
687
- Decide↔Trust seam): every staged judgement whose verdict is set, newest first —
688
- the exact complement of the queue. Options: `heading`, `maxHeight`.
689
-
690
- ### Studio components — `Studio.component(key, meta, fn)`
691
-
692
- A Studio component is **self-contained**: an East UI function written exactly
693
- like a `ui()` body, which binds its own data, sets up its own slices and returns
694
- its UI. Operators arrange components on pages and never rebind or reconfigure
695
- them, so different data is a different component, and a component's next
696
- version is a deploy.
697
-
698
- `Studio.component` returns a `Studio.Types.Component` struct, the way
699
- `Slice.config` returns a slice config. Call it at module scope or inside an
700
- East function.
701
-
702
- ```tsx
703
- export const salesCount = Studio.component("sales_count", {
704
- name: "Sales", category: "Display", icon: "receipt", span: 4n,
705
- description: "Sales recorded so far",
706
- }, East.function([], UIComponentType, _$ => (
707
- <Reactive>{$ => {
708
- const sales = $.let(Data.bind(salesDaily));
709
- return <Stat label="Sales" value={sales.read().size()} />;
710
- }}</Reactive>
711
- )));
712
- ```
713
-
714
- | `meta` | Meaning |
715
- |---|---|
716
- | `name`, `category`, `icon` | **required** — the palette card's name, the group it sits in, a Font Awesome solid icon |
717
- | `span` | the span a new placement takes, in columns of 12 (default `12n`) |
718
- | `description` | what it shows — the inspector's text, under its lock |
719
- | `frame` | `"card"` (default) draws a tile frame; `"none"` renders bare |
720
- | `tags` / `collections` | the palette's Filter facets |
721
- | `deprecated` | hidden from the palette; placements keep rendering |
722
-
723
- One field is derived from `fn`, never written: `reads`, the datasets,
724
- functions and records its code binds (`deriveManifest` over `fn`) — the palette
725
- card's meta line, the canvas tile's and the inspector's data list, each dataset
726
- and record named in words (a task's output by its task's name:
727
- `.inputs.sales_daily` reads "Sales daily"), never a keypath.
728
-
729
- A surface lists the components it offers with `$.let([...])`, in palette order,
730
- and hands the list to the Studio's components, which draw each placement by
731
- calling its component's function:
732
- - The surface's `ui()` manifest is the union of its listed components' reads:
733
- every dataset they bind is reachable, and nothing else.
734
- - State and Slice keys inside a component are the component's own, so two
735
- placements of it share them.
736
- - A placement whose component the list does not hold is a placeholder naming its
737
- key; a key two listed components share is an error naming it.
738
- - A placement holds its component's key alone, so a deploy that changes a
739
- component's code changes every page that places it, its live version too.
740
-
741
- ### Studio pages — `Studio.Types.Pages`
742
-
743
- The Studio exports the pages record's type; a solution declares its storage like
744
- any record, with one write, a patch:
745
-
746
- ```ts
747
- export const pages = e3.record("pages", Studio.Types.Pages, {
748
- initial: new Map(),
749
- mutations: (mutation) => ({
750
- patch: mutation.patch(),
751
- }),
752
- });
753
- ```
754
-
755
- The builder and the page library bind it with `Record.bind(pages)`;
756
- a published page reads it with `Data.bind(pages)`. The type never depends on the
757
- components, so a deploy that adds, changes or removes one runs no migration.
758
-
759
- - `Studio.Types.Pages` is `Dict<Key, Entry>`. A `Key` is `{ project, page }`. An
760
- `Entry` is a `page` — `{ draft, live }`, `live` being `none` until the first
761
- publish, else `{ version, page }` — or a `template`, a layout new pages start from.
762
- - A `Page` is `{ title, cells }`, and a `Cell` is `{ key, row, span, height,
763
- align, title, component }`: a component's key, and where it sits on the
764
- SnapGrid (rows in the order their keys first appear).
765
-
766
- Every operator action is one patch commit, computed in East as the diff of the
767
- one entry it writes: the builder's Save (the page's draft cells), its Publish
768
- (the live version becomes the draft, numbered one up — 1 the first time) and
769
- its Save as template;
770
- the page library's new page (a template's cells, or none for Blank grid). A
771
- patch carries what it changes as it was, so a write drafted on a stale page is a
772
- `conflict`, refused in the words of the screen that wrote it, and nothing is
773
- overwritten.
774
-
775
- ### The builder — `<Studio.Builder>`
776
-
777
- The builder as one component: the open page's canvas under one toolbar, the
778
- palette before it, the inspector after it, and the publish preview, which
779
- Preview and Publish open in the canvas's place. Its writes are patches, so it
780
- takes the record bound with its patch:
781
-
782
- ```tsx
783
- export const builder = ui("builder", [], East.function([], UIComponentType, _$ => (
784
- <Reactive>{$ => {
785
- const components = $.let([kpiRail, revenueTrend, breakdownBars]);
786
- const record = $.let(Record.bind(pages));
787
- return <Studio.Builder pages={record} components={components} project="Ops console"
788
- env="Staging" audience="Field ops · 24 users" rollout="Immediate" />;
789
- }}</Reactive>
790
- )));
791
- ```
792
-
793
- - **The canvas.** The open page's draft cells on the SnapGrid's editing canvas —
794
- a template's cells when a template is open — each placement its component's
795
- own UI, framed or bare. Every move, resize, drop and removal, and every
796
- layout edit the inspector asks for, is a draft; the history item undoes,
797
- redoes, discards and saves, and ⌘Z / Ctrl+Z undo from anywhere in the
798
- builder. Save is one patch commit on the page; a save another write beat is
799
- refused, and the drafts are carried over to the newer page, a part both
800
- changed waiting to be chosen before Save — with none, the Save goes again
801
- by itself. The selection bar
802
- names the selected placement: its component's icon and name, and what its
803
- code reads, never its key.
804
- - **The toolbar**, one row: the page's status — `Draft` with an open ring until
805
- its first publish, `Live` while its draft is its live layout, `Live · edited`
806
- once they differ, `Template` for a template — the grid chip and the time of
807
- the last save; the width readout, the zoom, the history item, Desktop ·
808
- Tablet, Save as template, Preview and Publish.
809
- - **Save as template** names a template in a popover hanging from its button —
810
- offering "<page> template" — and saves the open page, as last saved: one
811
- commit. A name the project holds is refused as it is typed, and one another
812
- write took first is refused in the popover. While a template is open it is
813
- disabled.
814
- - **The palette**, a pane of two tabs before the canvas. Components: every
815
- listed component but the deprecated, by category, with a search and a Filter
816
- menu over category, tags and collections; a card shows the component's icon,
817
- its name, the data its code reads in words and a lock, and drags onto the canvas as
818
- a placement at its component's span. The component
819
- the canvas has selected is drawn placed, `ON CANVAS · ×N`, unsaved drafts
820
- counted; a click selects its first placement. Pages: the project's pages in
821
- key order with their status (`LIVE · Vn`, `DRAFT · Vn LIVE` or `DRAFT`); a
822
- click opens one.
823
- - **The inspector**, the pane after the canvas: the selected placement's name
824
- (never its component's key); what its code reads, each named in words ("Sales
825
- daily"), never a keypath; its description, under a lock; and its layout — its
826
- span, held to its row's room, its row, its height (Auto or a preset in px)
827
- and where it sits in a taller row. Each edit is one gesture of the canvas's
828
- session. With nothing selected it says so.
829
- - **The panes** collapse to rails: the palette's shows its icon, the number of
830
- components and its name; the inspector's its icon — in the brand while a
831
- placement is selected — the placement's span (`8/12`) and its name.
832
- - **The publish preview**, in the canvas's place: a bar — "● Preview", Desktop ·
833
- Tablet · Mobile (the page 1440, 1024 or 390 px wide at most), the Env pill,
834
- and Exit, back to the canvas with its drafts as they were; the page as it will
835
- publish, its unsaved drafts in place; and an aside — "Ready to publish", the
836
- version it replaces and the one it becomes (`v3 → v4`), the changes since,
837
- each placement added, removed, moved or resized; the Audience and Rollout
838
- rows; Save as draft, which saves the
839
- canvas's drafts; and Publish, which saves them first, then commits the
840
- publish. A page never published is its first version, one live as it stands
841
- is up to date, and a template is not published.
842
-
843
- The page open in the builder begins as the project's first; a `<Studio.Library>`
844
- with the same `id` opens pages in it. The builder fills its parent's height and
845
- draws no border around itself, so a host frames it or places it bare.
846
-
847
- | Prop | Meaning |
848
- |---|---|
849
- | `pages` | **required** — the record bound with its patch: `Record.bind(pages)` |
850
- | `components` | **required** — the components the surface lists, in palette order |
851
- | `project` | **required** — the project whose pages it opens |
852
- | `env` | where the preview publishes to — its Env pill, and "Publish vN to <env>"; omitted, neither names one |
853
- | `audience` / `rollout` | who sees a published page, and when — the preview's rows; omitted, no row |
854
- | `id` | names the builder — needed only when one surface holds two, and then given to the page library that opens its pages |
855
-
856
- ### The page library — `<Studio.Library>`
857
-
858
- A project's templates and pages, and where new pages start: a component of its
859
- own, apart from the builder, headerless with one toolbar. A new page is one
860
- commit, so it takes the record bound with its patch:
861
-
862
- ```tsx
863
- <Reactive>{$ => {
864
- const components = $.let([kpiRail, revenueTrend, breakdownBars]);
865
- const record = $.let(Record.bind(pages));
866
- return <Studio.Library pages={record} components={components} project="Ops console" />;
867
- }}</Reactive>
868
- ```
869
-
870
- - **The toolbar**, one row: the search "Search N pages and M templates…", which
871
- narrows both rows by title; Sort · Name, A to Z (the record's key order) or
872
- Z to A; the Pages row's Grid · List; and "+ New page in <project>".
873
- - **The pane**: the projects the record holds and the surface's own, the shown
874
- one in the brand; the project's pages, each with its status dot — ● live,
875
- ○ draft — the one open in the builder in the strong ink; the legend at its
876
- foot. A project's click shows it; a page's click opens it in the builder.
877
- - **Templates**: Blank grid — the blank page — then the project's templates,
878
- four across, each a wireframe of its layout, its title and what it places
879
- ("KPI rail ×2 · Revenue trend"); a click starts a new page from it.
880
- - **Pages**: two across, each with its wireframe at its start, its title and
881
- status, how many components it places, and "Open in builder →", which opens
882
- it in the builder and calls `onOpen`; a dashed card last starts a new page.
883
- - **A new page** takes a name the project does not hold and a template, or
884
- Blank grid, in a popover hanging from the New page button — a template's
885
- card and the dashed card open it there too, their template picked. It is one
886
- commit; a name another write took first is refused in the popover.
887
-
888
- The project shown, the search, the order, the Pages row's layout and the
889
- popover are its own; the page it opens is the builder's, shared by `id`. It
890
- draws no border around itself.
891
-
892
- | Prop | Meaning |
893
- |---|---|
894
- | `pages` | **required** — the record bound with its patch: `Record.bind(pages)` |
895
- | `components` | **required** — the components the surface lists — what a template's line names |
896
- | `project` | **required** — the project it shows first |
897
- | `onOpen` | told when a page opens in the builder, with its key — the host shows the builder |
898
- | `id` | names the builder whose open page it writes — needed only when one surface holds two builders |
899
-
900
- ### One page — `<Studio.Page>`
901
-
902
- One page with no chrome, as everyone else sees it: its layout on the SnapGrid,
903
- each placement its component's own UI. It reads the record's value and never
904
- writes it, so a surface built from it holds the record's path and its listed
905
- components' reads, and no write.
906
-
907
- ```tsx
908
- export const opsConsole = ui("ops_console", [], East.function([], UIComponentType, _$ => (
909
- <Reactive>{$ => {
910
- const components = $.let([kpiRail, revenueTrend, breakdownBars]);
911
- const all = $.let(Data.bind(pages));
912
- return <Studio.Page pages={all.read()} components={components}
913
- page={{ project: "Ops console", page: "Overview" }} />;
914
- }}</Reactive>
915
- )));
916
- ```
917
-
918
- | Prop | Meaning |
919
- |---|---|
920
- | `pages` | **required** — the record's value: `Data.bind(pages).read()`, or a bound record's `read()` |
921
- | `components` | **required** — the components the surface lists |
922
- | `page` | **required** — the page's `{ project, page }` key |
923
- | `version` | `"live"` (default), the published layout, or `"draft"`, the layout as last saved; a template draws its cells either way |
924
-
925
- - A frameless component (`frame: "none"`) renders bare; every other placement is
926
- a tile.
927
- - A page with no live version, and a key the record does not hold, each draw a
928
- placeholder that says so.
929
- - Under a narrow container the tiles stack in row order.
930
- - A chart that fills (`<Chart height="fill">`) takes a sized tile's height, and
931
- its natural height in a tile sized by its content.
932
- - The page draws no border around itself; a solution places it in a layout of
933
- its own.
934
-
935
- ### Queries — `<Query.Builder>` and `<Query.Library>`
936
-
937
- Operators build **typed jq queries** over the datasets a surface binds — as steps
938
- in plain words or as jq — see them checked as they edit, run them to read the
939
- result, and save them. A solution declares one record of saved queries, with
940
- one write, a patch:
941
-
942
- ```ts
943
- export const queries = e3.record("queries", Query.Types.Saved, {
944
- initial: new Map(),
945
- mutations: (mutation) => ({
946
- patch: mutation.patch(),
947
- }),
948
- });
949
- ```
950
-
951
- `Query.Types.Saved` is `Dict<String, SavedQuery>`, by name. A saved query is
952
- `{ name, description, program, root, saved_at }`: its program as written (a
953
- `JqType` tree, never text to re-parse), the `{ name, path }` of each data source
954
- it reads, an optional one-sentence description — none shows a sentence
955
- generated from its steps — and when it was saved. It saves only once it checks.
956
- It holds no types: they are what checking its program against its data sources
957
- gives. The type never depends on the data sources, so adding one runs no
958
- migration.
959
-
960
- To ship queries in the record, write its value with `Query.value(sources,
961
- queries)`: each query inline, checked against the data sources when the package
962
- builds, as the builder checks a query it saves. The sources are named as a
963
- query reads them, each the dataset or task `Data.bind` takes:
964
-
965
- ```ts
966
- export const queries = e3.record("queries", Query.Types.Saved, {
967
- initial: Query.value({ orders, customers }, [
968
- { name: "Big orders", jq: ".orders | map(select(.total >= 1000))", savedAt: new Date("2026-10-01T09:00:00Z") },
969
- { name: "Orders by region", jq: ".customers as $c | .orders | group_by($c[.customer_id].region) | map(length)",
970
- description: "How many orders each region placed.", savedAt: new Date("2026-10-01T09:00:00Z") },
971
- ]),
972
- mutations: (mutation) => ({
973
- patch: mutation.patch(),
974
- }),
975
- });
976
- ```
977
-
978
- A query that does not check fails the build with the checker's words, as do two
979
- queries of one name and a description over 140 characters. A query's root is
980
- the data sources it reads, in the order given.
981
-
982
- ```tsx
983
- export const builder = ui("query_builder", [], East.function([], UIComponentType, _$ => (
984
- <Reactive>{$ => {
985
- const orders = $.let(Data.bindPaged(d.orders)); // large: paged, never loaded whole
986
- const customers = $.let(Data.bind(d.customers));
987
- const saved = $.let(Record.bind(d.queries));
988
- return <Query.Builder queries={saved} datasets={{ orders, customers }} />;
989
- }}</Reactive>
990
- )));
991
-
992
- export const library = ui("query_library", [], East.function([], UIComponentType, _$ => (
993
- <Reactive>{$ => {
994
- const orders = $.let(Data.bindPaged(d.orders));
995
- const customers = $.let(Data.bind(d.customers));
996
- const saved = $.let(Record.bind(d.queries));
997
- return <Query.Library queries={saved} datasets={{ orders, customers }} />;
998
- }}</Reactive>
999
- )));
1000
- ```
1001
-
1002
- `datasets` is the **root**: a query on this surface reads `.orders` and
1003
- `.customers`, and nothing else. Each name must be a jq identifier and each
1004
- value a `Data.bind`, `Data.bindPaged` or `Record.bind` handle; a surface handed
1005
- none, or a name jq can't read, is refused when it is built. The surface's
1006
- manifest follows: the record, its patch and each bound source.
1007
-
1008
- **`<Query.Builder>`** is the builder: one toolbar (the history item, Copy jq,
1009
- Save… and Run ⌘⏎); a pane with three tabs — **Query** (the steps, each a card of
1010
- plain-word slots with its checked shape after it, or the jq in an editor with
1011
- completions and a problems panel; Visual · jq at the top), **Datasets** (the
1012
- bound data sources — a click starts a new query on one) and **Library** (this
1013
- viewer's recent runs and the saved queries — a click opens one); the results
1014
- beside it, a Table or a tree with Download (CSV, BEAST2); and a status line.
1015
-
1016
- - Every edit is checked at once, in the browser, and is one undoable gesture of
1017
- the history item; Save commits the query as one patch of its one entry,
1018
- and a save drafted on a changed entry is a conflict, never an overwrite.
1019
- - **Run** checks and translates the query in the browser and runs it on e3 as a
1020
- **one-shot call** over the data sources it reads — or, when the dataset it
1021
- works through weighs more than one piece (16 MiB), as a **split call** over
1022
- that dataset's pieces, which e3 runs as a job of pieces and merges —
1023
- platform-free either way, so a reader can run it. The results' footer says
1024
- which ("One call", "Split call · 24 pieces"), and a click explains the plan:
1025
- the path and why, what each piece runs, how the pieces combine and what runs
1026
- once after them. Opening a saved query runs it; editing never does. Nothing
1027
- else reads data but a slot's summary, and a run's dataset status before it
1028
- plans.
1029
-
1030
- | Prop | Meaning |
1031
- |---|---|
1032
- | `queries` | **required** — the record bound with its patch: `Record.bind(queries)` |
1033
- | `datasets` | **required** — the data sources a query may read, by the names it reads them: `{ orders, customers }` |
1034
- | `query` | the saved query it opens first, by name; omitted, a new query on the first data source |
1035
- | `id` | names the builder — needed only when one surface holds two, and then given to the library that opens queries in it |
1036
-
1037
- **`<Query.Library>`** is the saved queries, and where new queries start: one
1038
- toolbar (the search over names, descriptions and data sources; Sort · Recent or
1039
- Name; Grid · List; "+ New query on <data source>"); a pane of the data sources
1040
- with their counts, and Recent; and a gallery, each card a wireframe of its query
1041
- — its source and a bar per step — with its name, its description, "orders · 5
1042
- steps · up to 10 orders · saved Tue" and "Open in builder →". It reads no
1043
- dataset: a card draws a query, never its data. A query opens in the builder that
1044
- shares its `id`, and its card drags onto it. A query whose data sources aren't
1045
- bound here says why and doesn't open.
1046
-
1047
- | Prop | Meaning |
1048
- |---|---|
1049
- | `queries` | **required** — the record bound with its patch |
1050
- | `datasets` | **required** — the same data sources the builder reads |
1051
- | `onOpen` | told a query's name when it opens one in the builder — the host shows the builder |
1052
- | `id` | names the builder whose open query it writes — needed only when one surface holds two builders |
1053
-
1054
- Neither draws a border around itself; each fills its parent's height.
1055
-
1056
- ### The Plan — `<Plan>`
1057
-
1058
- `<Plan>` is the planning canvas, and there is one (#1191): ONE shared axis —
1059
- time, number or ordinal (#631) — over heterogeneous rows (state-runs,
1060
- allocation lanes, chart measures, heat, bucketed numerals, shift chips, event
1061
- marks), each named by a typed id, with one rail (`Slice.bindRecords`,
1062
- #1344), a key search and a series library, an editing session (every dropped
1063
- card, move and resize a draft, #880 / #825) and paged sources. It renders in its builder
1064
- frame wherever it is used (#1193): one toolbar holding every control it draws
1065
- outside its canvas, the banners, the canvas in main, and the footer. Its rows
1066
- come from three sources, in this order down the canvas:
1067
-
1068
- - **event kinds over records** — `resources`, the rows, and `events`, the
1069
- kinds placed on them: `Schedule`'s, the very values a Calendar takes, each
1070
- kind a record of its own bound with its patch mutation;
1071
- - **`data` and its `series`** (or `pick`) — a keyed source's entries, laid out
1072
- by the series list and nested from the data's own structure, on any axis; a
1073
- `Data.bindPaged` handle is its `data` as readily as a collection in hand;
1074
- - **`rows`** — hand-built rows and `Plan.over(data, [series…])`, read only.
1075
-
1076
- A Gantt is a Plan with span rows, a Planner a Plan with bucket rows, an
1077
- AlignedStack a Plan mixing chart / heat / table rows on the shared axis
1078
- (#571). Reach for it for anything scheduled on ONE shared axis — calendar
1079
- time, a numbered day / shift / distance, or an ordered list of phases — with
1080
- mixed row kinds, nesting to any depth, a paged source, rows addressed by
1081
- stable ids, or events kept in records of their own.
1082
-
1083
- The tag and its authoring vocabulary — `Plan.axis`, `Plan.series.*`,
1084
- `Plan.children`, `Plan.ref`, `Plan.over`, `Plan.eventRef`, the value and cell
1085
- builders, `Plan.Types` — come from `@elaraai/e3-ui`, its event and resource
1086
- kinds from `Schedule`, and the tags around it from `@elaraai/east-ui`. It
1087
- moved here from east-ui (#1177) and is one tag (#1191): a surface that wrote
1088
- east-ui's `<Plan>`, or `<Plan.View>`, imports `Plan` from `@elaraai/e3-ui` and
1089
- writes `<Plan>`, its props as they were. Its words in React —
1090
- `PlanMessagesProvider` and `planMessages` — are `@elaraai/e3-ui-components`'.
1091
-
1092
- ```tsx
1093
- /** @jsxImportSource @elaraai/e3-ui */
1094
- import { Plan } from '@elaraai/e3-ui';
1095
- // … the series list and the axis, as below …
1096
- return <Plan axis={axis} data={rows} series={series} />;
1097
- ```
1098
-
1099
- ```
1100
- <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
1101
- ├─ The frame (#1193): ONE toolbar holding every control the Plan draws outside its canvas, in this order — the rail of its one `Slice.bindRecords` (each source's field chips and the presets, #1344), the key search, Expand/Collapse all, the shared date navigator (on a number axis the leading source's range is a chip of the rail), the configured resolution, the diagnostics; at its end the rail's summary, naming each source a narrowing hides rows of in its own words (#1358), 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, its summary after every step of it, then the date navigator compacts, the resolution folds into a menu and Expand/Collapse all keeps its icon, the key search folds into its icon (which opens the box in a popover, the focus in it), then the time-axis view controls — the fold toggle, the resolution and the overlaps chip — share the date popover, one move, and the history item folds last, to its buttons — below that, where the row is still too wide, the rail's icon drops its caret, so the history and Save stay in the row at a phone's width; 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): changes that conflict with newer ones, whose Choose opens the history item's conflicts, a Save's conflict, a refusal, an unknown outcome with Retry. 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`, the one loading line — what the view waits for (`Loading rows 201–400`), a source's new narrowing, or a read that failed with its reason and Retry; nothing while nothing is in flight — and after a Save what left each source's narrowing (`1 print job event left this view`). ⌘Z undoes and ⇧⌘Z redoes from anywhere in the frame; a field being typed into keeps its own undo. The Plan draws no border
1102
- ├─ Props:
1103
- │ ├─ 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 range the sources of its `slice` holding the window hold — an event kind's, a tab's, never the `rows` source's or a resource kind's (#1344) — there is NO fit to the data (#822): a canvas that neither states a window nor has a source holding a range 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 leading source'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 source's range holds it, no brush, the window keys idle; an unlisted value positions nowhere; an interval END names its LAST bucket, inclusive)
1104
- │ ├─ data (required unless `events`, `rows` or `slice`'s `rows` source, which gives the rows and refuses `data` beside it — 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, the view where it is (its matches named rows of the old one, #1199) — a match its box shows kept while the new snapshot holds it in place, else its query shown again
1105
- │ ├─ 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. A series reads the collections its row holds BY NAME (#1436), each a `Dict` field of the row: `Plan.items(field, times, draw)` reads things people drag — runs, decisions, tiles, chips, marks — keyed by an id (a `String`), each item's instants the fields `times` names (`{ from, to }` for a run or a chip, `{ at }` for the rest; a `DateTime` or an `Option` of one — no start draws nowhere, no end is an instant —, a `Float` / `Integer` on the number axis, a `String` on the ordinal) and its look `draw(item, id, row)`'s, everything its element takes but its key and instants (`Plan.items("jobs", { from: "start", to: "end" }, (job) => ({ label: job.ticket, state: job.state }))`); `Plan.values(field, draw)` reads values keyed by their instant (a `DateTime`; a `String` on the ordinal axis), `draw(value, at, row)` giving what each takes besides its instant — a heat, weight, segment or table row's cells (`Plan.heatCells(Plan.values("load", (pct) => ({ value: some(pct) })), { min: 0, max: 100 })`), a table series' cells, a chart layer's points (`Plan.line(Plan.values("ontime", (pct) => ({ y: pct })))`), a span's `ports`, a bucket row's `markers`, a group's `summary`. Each read brands the series with what it reads (phantom: a misnamed field, a time field the item lacks or a look missing a required field fails to compile), a read written outside a series is refused, and a function of the row stays for anything that reads no collection. What a gesture WRITES is declared on the series (#880), through the collection its elements' `Plan.items` names: `edit: true` (span / buckets / cards / events) makes its runs, chips, tiles and marks MOVE — along their row, or to another, the item leaving one row's collection under its id and joining the other's under the same id — and its runs and chips RESIZE (#825), each gesture written into the item's named times; `edit: { create: (drop, entry, key) => item }` takes dropped cards as well, `create`'s item joining the row's collection under the id the canvas mints for it (`drop.id`) — see `editing`. An element's key is its item's id, its identity across every row it can move to: a row's collection keeps its ids unique, so a move onto a row holding the id is refused (the drag showing ⊘). A table's values take typed numbers with `edit: true` — on `Plan.series.table` for its `cells`, or on a position, `Plan.tableSeries({ cells, edit: true })` — its cells a `Plan.values` read drawing each value as stored (`value: some(v)`; `some(v.toFloat())` for an Integer collection): at the Plan's finest zoom, a number typed into a cell replaces the one value its bucket holds, at that value's date, adds one at the bucket's start where none is, and cleared deletes it; at a coarser zoom each cell is a summary and takes none, a double click, Enter or a tap zooming to the finest about it — the zooms are the slice's, so a Plan without one types at the resolution it shows (`Plan.Types.ValueEdit`; each row says which positions take a number, and whether whole numbers only, in `edits.values` — `Plan.Types.TypedPosition`). `children` nests, to any depth, by field: `children: "parts"` names a `Dict` field of the row holding more of THIS series' entries (a `RecursiveType` entry's own children, keyed by an id), `Plan.children("members", [series…])` steps down to a `Dict` field holding child rows of another type, keyed by an id, its series laid out like a top-level list, and an array of step-downs gives several child collections in order (a gesture on a nested row writes back through them); `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 its children's subtotal at each position where its own collection holds no values for the row (`aggregate` default "sum" — "count" counts the leaf rows beneath that draw a value in the bucket —, `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, each group an entry holding its rows in a field its series step down into (`rows.groupToDicts(($, r) => r.hall, ($, _r, k) => k).map(($, members) => ({ members }))`, entries `{ members: Dict<String, Row> }` keyed by 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)`
1106
- │ ├─ 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); what a viewer switches there is kept under `key` in the browser's storage, so a reload opens the series as they were left (an id the list no longer holds dropped; a pick the tab never wrote opens with `hidden`); 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>
1107
- │ ├─ 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), { 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
1108
- │ ├─ 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
1109
- │ ├─ 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?, source? })` — a card per row of a `Dict<K, R>` (accessors `(row, key)`), searched by key, label and meta, a click selecting one, following the rail's `source` it names by its rows' keys (#1344); 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
1110
- │ ├─ 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
1111
- │ ├─ 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
1112
- │ ├─ 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
1113
- │ ├─ 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
1114
- │ ├─ 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
1115
- │ ├─ slice (optional, #1344) — slice={{ slice: Slice.bindRecords(key, { rows?, <an event kind's slot>?, <a resource kind's slot>?, <a templates list's or a tab's source>? }, { presets? }), affordances?, persist? }}: ONE rail on the toolbar (affordances default ["fields","presets","summary","brush"]), each source named after what it narrows. `rows` gives the canvas its rows, paged from it in its index's order — `data` beside it is refused — edits reaching the record through `editing.onApply` (`Record.onApply(record, { keyed: true })`), the session the record's, a Save that takes rows out of the narrowing said in the footer. A source named after an event kind's slot reads that kind's events in the window and its backlog through its interval index (`index.interval({ on?, from: "start", to: "end" })` among the jobs record's indexes, `range: "start"`), the kind giving `entries: Data.bindPaged(record)` for its reads by key; a draft of an event its narrowing does not hold never shows, and Save sends it. A kind placed on a paged resource kind is read a cell at a time (#1039) — the events of the resources around the rows in view over the tiles the window touches, a range a resource a level (#1433), two requests a change — and shaded from the summary past what it draws: its source lists a series index and a summary index beside the interval index, and any other form is refused, naming both. Every other kind is counted before one of its events is read, and past 10,000 events in the range the canvas reads none is read or drawn (see Large records below). One named after a resource kind's slot narrows that kind's rows: of resources read whole and keyed by String, the rows and the bulk edit's Chooser, which keeps the resources the selected events are on; of a paged kind (`Schedule.resources(Data.bindPaged(record), …)`), its windows — the canvas pages the narrowing's rows themselves, the source `Data.bindPaged(record, { indexes })` over the kind's own record, in its index's order, the counts the narrowing's, so a choice reads only the narrowed resources in view and their cells (`planSeriesByHall`, `planRecordIndexes`). One a templates list (`Schedule.templates(rows, { …, source })`) or a library tab names narrows that tab's cards: each tab counts what it shows (`Customers 6 of 16`) and, emptied, says so with Clear filters; the Backlog counts `N of M`, its Clear filters keeping the window. Every source holding a range of the axis's arm — an event kind's, a tab's that lists what is in the dates on screen — holds ONE window — on a time axis the date navigator's, the leading source's range editor its Range panel and every source's range out of the rail; on a number axis the leading source's range a chip of the rail: the date navigator, the horizon brush, `[` / `]` / `n` and the resolution write each source, and a record's resolution only re-buckets, fetching nothing. The canvas's rows never follow the dates on screen: the `rows` source and a resource kind's take no `range` — refused as the Plan is evaluated, naming the change — so a date field there is a field of the rail the viewer sets, and a pan reads no row; a slice none of whose sources holds the window leaves the canvas its own, which the same controls move, kept for the viewer as the canvas's folds are, so a reload opens on the dates the viewer left. `brush` mounts the horizon band on time and number axes: an OVERVIEW of the sources' range in whole periods (with no source holding the window, the axis's stated window and the window shown, as long again either side, so its lens slides either way), 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; or Tab to its start handle, window and end handle, an arrow moving a period, Shift ten, Home / End the ends, Esc clearing), committing once a gesture — over record sources with no bars yet, over rows read through a nested series index each month's items as bars (see the nested series above); `resolution` the WEEK/DAY segment (time axis); `summary` the rail's counts. Calculations — the footer's counts, the overlaps — read every event the kinds read. Refused at build, each naming the change: the bare handle, `Slice.bind`, a single `Slice.bindRecord`, a source nothing names, `data` beside `rows`, a resource kind keyed otherwise than by String as a source, a paged one's source over another record, a kind's own `slice` or `filter`, and a templates list written in the code or naming no source — and, as the Plan is evaluated, a `range` on the `rows` source or a resource kind's. With a `rows` source there is no key search: the rail narrows the rows — nor over a paged resource kind its source narrows, whose searches run in the source's index's order. On a PAGED `data` the toolbar's KEY SEARCH seeks over the source's `seek` — the 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"`)
1116
- │ ├─ 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
1117
- │ ├─ 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`
1118
- │ ├─ 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, id } — `at` the start of the bucket it landed in, on the axis arm; `id` the key the canvas mints for the new item, unique among every element it holds) and joining the collection the series' `Plan.items` names under that id. `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)
1119
- │ ├─ optimise (optional, #1409) — `Func.bind` of the app's `e3.function` from `Plan.Types.OptimiseRequest(E, S)` — the plan window in view, the run's number, every event kind's rows in the window and the backlog by key as the session holds them (base plus every unapplied draft, every row whatever the rail shows), and every resource kind's rows read whole as context (a kind paged a window at a time carries none) — to `Plan.Types.OptimiseResult(E)`, the events complete. The Elara eye in the toolbar, immediately before the history item: one call per run; while it is out the history and every gesture are locked, a change of window stops it (Stop too), and a late answer is ignored. Its answer is diffed by key and recorded as ONE step of the history — Undo in one, Redo replays it, Save with everything else — each event it placed from the backlog an add on the canvas, one it moved a change with a ghost where it stood, one it took back a remove; each marked until Apply with its provenance on hover (`Added by Elara · run #7`), the Backlog count and the footer's counts flashing; a result equal to the request records nothing and says so
1120
- │ ├─ 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
1121
- │ ├─ footer (optional) — [{ text, tone?, end? }] status-footer items, in the frame's footer after its counts; a paged canvas adds the one loading line (what the view waits for, or why a window could not be read, with Retry); rows not read draw as the shared run — label bars and the plot washed, at the rows' pitch — and until the source is exhausted a TOP-LEVEL section's member count is a placeholder bar (its members are entries the windows share out) — every other parent's numbers are exact, its subtree riding whole in one entry
1122
- │ └─ 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)
1123
- ├─ 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, its count `not counted` over a paged source whose entries make no fixed number of chart rows; 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
1124
- ├─ 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 write the window into the sources holding it, else into the canvas's own; a canvas with no slice keeps the axis's stated window and 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
1125
- ├─ 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; what a paged source reads is the footer's loading line, a polite live region that speaks once a load; 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)
1126
- ├─ 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
1127
- └─ Factories:
1128
- ├─ 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
1129
- ├─ 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
1130
- ├─ Plan.items(field, times, draw) / Plan.values(field, draw) — a series' reads of the collections its row holds, by name (#1436, see `series`): things people drag keyed by an id, and values keyed by their instant
1131
- ├─ Plan.children(field, [series…]) — a step down from an entry to a `Dict` field of child rows of another type, keyed by an id, for a series' `children`
1132
- ├─ 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)
1133
- ├─ 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)
1134
- ├─ 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`
1135
- ├─ 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)
1136
- ├─ Plan.lane({ key, label? }) / Plan.marker({ at, lane?, status?, message }) — bucket sub-slot lanes + cell status rings (status defaults "danger"; message = the tooltip)
1137
- ├─ 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))
1138
- ├─ Plan.decision({ key, at, applied }) / Plan.port({ at, label? }) — span-row decision diamonds (◇ pending / ◆ applied) + quantity in/out ports
1139
- ├─ 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, `cells` a `Plan.values` read of the row's collection (`Plan.heatCells(Plan.values("load", (pct) => ({ value: some(pct) })))`; `{ fraction, planned }` for weights, `{ segments }` for compositions) or an array of cells (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
1140
- ├─ Plan.tableCells(Plan.values(field, (v) => ({ value: some(v) })) | rawCells) / Plan.tableSeries({ cells, format?, tone?, strong?, rollup?, fold?, edit? }) — bucketed numerals (`edit: true` over a values read: the position takes typed numbers, #1436) (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`
1141
- ├─ Plan.line / Plan.area / Plan.column / Plan.scatter / Plan.band(Plan.values(field, draw), { axis?, breach?, series?, fold? }) — a chart row's layer over the row's values, a point at each value's instant (`draw` gives `{ y }`, a band's `{ lo, hi }`; columns stack by `series`, `breach` on lines and columns, scatter and band draw every point) (#1436)
1142
- ├─ 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)
1143
- ├─ 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)
1144
- ├─ 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
1145
- ├─ 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)
1146
- ├─ 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
1147
- ├─ 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
1148
- ├─ Plan.Types.OptimiseRequest(E, S) / Plan.Types.OptimiseResult(E) — what the app's optimiser is asked and answers (#1409): `E` and `S` the event and resource kinds' row types by slot (`Plan.Types.OptimiseRequest({ job: Job }, { presses: Press })`, a kind keyed otherwise than by String `{ key, row }`); the request `{ from, to, run, events, resources }`, each kind's rows by key; the result `{ events }`, the events complete, a new event's key the optimiser's own
1149
- └─ Plan.Types.PatchEvent(R) — what `editing.onPatch` receives for entries of `R` · Plan.Types.Drop ({ from: { library, key }, row: RowId, at: Instant, duplicate, id: String }) — what an `edit.create` builds its item from, `id` the key its item goes in under · Plan.Types.Gesture (drop(Drop) | move(Move) | value(ValueEdit)) and Plan.Types.RowEdits ({ drop, move: Option<MoveEdits>, values: Array<Integer> } — the gestures a row takes, `values` the table positions taking typed numbers) · Plan.Types.ValueEdit ({ row, position, at, value: Option<Float> } — a number typed into a table cell, `at` the date of the one value its bucket holds, else its bucket's start; `none` when cleared, #1436) · 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)
1150
- ```
1151
-
1152
- #### The series list is the layout, the data is the hierarchy (#822)
1153
-
1154
- A canvas is `data` plus a list of series, and the list IS the layout: one
1155
- block per series, top to bottom, each parent followed by its subtree. Nesting
1156
- comes only from what an entry holds — a recursive entry's own children, or a
1157
- step down into a child collection — so a parent's bands, means and subtotals
1158
- are exact, and the canvas reads the same inline or paged. There is no
1159
- `groupBy`: to group a flat source, reshape it first.
1160
-
1161
- A row's collections are `Dict`s it holds, read by name (#1436): things people
1162
- drag keyed by an id, with their times as fields, through `Plan.items`; values
1163
- keyed by their instant through `Plan.values`; child rows keyed by an id,
1164
- through `Plan.children` or a tree's own field.
1165
-
1166
- ```tsx
1167
- // A press's jobs by id, its load by the instant of each reading.
1168
- const Job = StructType({ ticket: StringType, start: DateTimeType, end: DateTimeType, state: EventStateType });
1169
- const HallRow = StructType({ label: StringType, hall: StringType, jobs: DictType(StringType, Job), load: DictType(DateTimeType, FloatType) });
1170
- // Grouping is a DATA step: each hall an entry holding its rows, in the field its series step down into.
1171
- const halls = $.let(rows.groupToDicts(($, r) => r.hall, ($, _r, k) => k).map(($, members) => ({ members })));
1172
- const Hall = StructType({ members: DictType(StringType, HallRow) });
1173
- const series = $.const([
1174
- // One strip PER HALL; its rows stepped down into, laid out like a top-level list.
1175
- Plan.series.group(Hall, {
1176
- key: "halls", title: "Halls",
1177
- label: (_h, hall) => hall,
1178
- summaryAggregate: "mean",
1179
- children: Plan.children("members", [
1180
- Plan.series.span(HallRow, {
1181
- key: "hall-jobs", title: "Jobs",
1182
- match: r => r.jobs.size().greater(0n),
1183
- label: r => r.label,
1184
- runs: Plan.items("jobs", { from: "start", to: "end" }, (job) => ({ label: job.ticket, state: job.state })),
1185
- }),
1186
- Plan.series.heat(HallRow, {
1187
- key: "hall-load", title: "Load",
1188
- match: r => r.load.size().greater(0n),
1189
- label: r => r.label,
1190
- cells: Plan.heatCells(Plan.values("load", (pct) => ({ value: some(pct) })), { min: 0, max: 100 }),
1191
- }),
1192
- ]),
1193
- }),
1194
- ], ArrayType(Plan.Types.Series(Hall)));
1195
- // <Plan axis={axis} data={halls} series={series} />
1196
- ```
1197
-
1198
- A recursive entry nests to whatever depth the data has, and every parent
1199
- derives its numbers from its subtree:
1200
-
1201
- ```tsx
1202
- const OrderRow = RecursiveType((self) => StructType({
1203
- name: StringType, act: DictType(DateTimeType, FloatType), children: DictType(StringType, self),
1204
- }));
1205
- Plan.series.table(OrderRow, {
1206
- key: "orders", title: "Orders", label: r => r.name,
1207
- cells: Plan.tableCells(Plan.values("act", (n) => ({ value: some(n) }))), // where a parent holds no values of its own…
1208
- children: "children", aggregate: "sum", // …it shows its subtree's subtotal, at every depth
1209
- format: Format.Number({ maximumFractionDigits: 0n }),
1210
- })
1211
- ```
1212
-
1213
- One entity shown several ways is a `views` series: each entry gets one row per
1214
- member series, side by side, and each row has its own id:
1215
-
1216
- ```tsx
1217
- Plan.series.views(OpsRow, { key: "presses", title: "Presses", match: r => r.pick.equal("presses") }, [
1218
- Plan.series.span(OpsRow, { key: "press-jobs", title: "Press jobs", label: r => r.label,
1219
- runs: Plan.items("jobs", { from: "start", to: "end" }, (job) => ({ label: job.label, state: job.state })) }),
1220
- Plan.series.chart(OpsRow, { key: "press-util", title: "Press · utilisation", label: r => r.label,
1221
- layers: [Plan.line(Plan.values("util", (pct) => ({ y: pct })))] }),
1222
- Plan.series.table(OpsRow, { key: "press-sheets", title: "Press · sheets", label: r => r.label,
1223
- cells: Plan.tableCells(Plan.values("sheets", (n) => ({ value: some(n) }))) }),
1224
- ])
1225
- // a click on p03's utilisation row reports Plan.ref("press-util", "p03")
1226
- ```
1227
-
1228
- | Signature | Description | Example |
1229
- | --- | --- | --- |
1230
- | **Layout and nesting** | | |
1231
- | `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` |
1232
- | `Plan.items(field, { from, to } \| { at }, draw: (item, id, row) => look)` | Things people drag — runs, decisions, tiles, chips, marks — read from a `Dict` field of the row keyed by an id, each item's instants its named fields; `draw` gives everything its element takes but its key and instants. Over a collection keyed by an instant, or a field that is no `Dict`, it is refused in words naming the field. | `planTargetState`, `planRowDrop` |
1233
- | `Plan.values(field, draw: (value, at, row) => look)` | Values read from a `Dict` field keyed by their instant: cells, a table series' cells, chart layers (`Plan.line` … `Plan.band`), a span's `ports`, a bucket row's `markers`, a group's `summary`. A collection keyed by `String` rides only an ordinal axis. | `planTargetState`, `planMeasures` |
1234
- | `children: "children"` | More of this series: a `Dict` field of a `RecursiveType` entry, keyed by an id, 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` |
1235
- | `children: Plan.children(field, series: Series[])` | A step down to a `Dict` field of child rows of another type, keyed by an id, laid out like a top-level list; an array of step-downs gives several collections, in order. | `planTargetState` |
1236
- | `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` |
1237
- | `rows.groupToDicts(($, r) => r.hall, ($, _r, k) => k).map(($, members) => ({ members }))` | Grouping is a data step, each group an entry holding its rows in a field; a paged source is grouped in its dataflow. | `planTargetState` |
1238
- | `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` |
1239
- | `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` |
1240
- | `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` |
1241
- | **Paged sources (#823)** | | |
1242
- | `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` |
1243
- | 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` |
1244
- | **Identity** | | |
1245
- | `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` |
1246
- | `Plan.sectionRef(series: String, ...path: String[]): RowId` | A section header's id, at its parent's path. | `planTargetState` |
1247
- | `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` |
1248
- | 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. | — |
1249
- | **Window** | | |
1250
- | `Plan.axis({ window: { min, max }, … })` or a source of `slice={{ slice }}` holding a `range` — an event kind's or a tab's, never the `rows` source's or a resource kind's **❗** | The window is stated, or it is the range its sources hold (#1344); while no source holds it the canvas holds its own, which its navigation moves without reading a row. A canvas with neither is refused, and nothing fits the axis to the data; a `range` on the `rows` source or a resource kind's is refused as the Plan is evaluated, naming the change. | `planTargetState`, `planNumberAxis`, `planRecordIndexes`, `slicePlanChrome` |
1251
-
1252
- A paged canvas pages by parents, block by block (#823): a window holds its
1253
- entries whole, so every parent derives exactly, and each top-level series is a
1254
- block paging on its own over the same windows — the canvas draws exactly as it
1255
- does inline. Group a flat paged source in the dataflow that produces it, so a
1256
- group arrives as one entry holding its members.
1257
-
1258
- Removed with #822: `groupBy` on span / heat / table; `Plan.series.group(R, {
1259
- by })` and the static `group(R, chrome, children)` form (use `section`);
1260
- `keyPrefix` / `keySuffix` (use `views`); numbered keys to force a layout
1261
- (order the series list); fit-to-data; and `Plan.pick`'s `data` counts.
1262
-
1263
- #### Values, folds, one element callback and a bound ui state (#824)
1264
-
1265
- A quantity is ONE value — the number, its unit and how it prints — so a bar's
1266
- caption and a rollup's total can never disagree. Values fold to the axis's
1267
- resolution: weekly cells on a MONTH axis show one cell per month per row, and
1268
- every cell builder, table series and chart layer says how (`fold`). Every
1269
- element click is one callback over the same ref the popover resolver receives,
1270
- and the interaction state can live with the host.
1271
-
1272
- ```tsx
1273
- runs: Plan.items("jobs", { from: "start", to: "end" }, (job) => ({ label: job.ticket, state: job.state,
1274
- quantity: Plan.quantity(job.sheets, { unit: "k sheets", format: Format.Number({ maximumFractionDigits: 0n }) }) })),
1275
- cells: Plan.heatCells(Plan.values("load", (pct) => ({ value: some(pct) })), { min: 0, max: 100, fold: "max", format: Format.Number({ maximumFractionDigits: 0n }) }),
1276
-
1277
- // The host holds what is selected, folded, opened and expanded; a write brings a row into view.
1278
- const ui = $.let(State.bind([Plan.Types.UiState], "ops.plan.ui", Plan.uiState({ collapsed: [Plan.ref("halls", "Hall 3")] })));
1279
- const goTo = $.const(East.function([Plan.Types.RowId], NullType, ($, id) => {
1280
- const s = $.let(ui.read());
1281
- $(ui.write(East.value({ selected: some(id), collapsed: s.collapsed, expanded: s.expanded, charts: s.charts, focus: some(id) }, Plan.Types.UiState)));
1282
- }));
1283
- // One callback for every element; a partial match answers only the arms it names.
1284
- const picked = $.let(State.bind([StringType], "ops.plan.picked", ""));
1285
- const onElementClick = $.const(East.function([Plan.Types.ElementRef], NullType, ($, ref) => {
1286
- $.match(ref, {
1287
- run: ($, r) => { $(picked.write(East.str`run ${r.run} on ${East.print(r.row)}`)); },
1288
- link: ($, l) => { $(picked.write(East.str`link ${l.key}: ${l.from.run} → ${l.to.run}`)); },
1289
- });
1290
- }));
1291
- // <Plan axis={axis} data={halls} series={series} ui={ui} onElementClick={onElementClick} />
1292
- ```
1293
-
1294
- | Signature | Description | Example |
1295
- | --- | --- | --- |
1296
- | `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` |
1297
- | `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` |
1298
- | `onElementClick: fn(Plan.Types.ElementRef) => Null` | Every element kind — run, event, mark, chip, cell, link — through one callback; the arm says which. | `planVariants` |
1299
- | `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` |
1300
- | `Plan.link({ key, from, fromRun, to, toRun, quantity? })` | A ribbon keyed for its click ref, weighed and captioned by its quantity. | `planTargetState` |
1301
-
1302
- Removed with #824: `qty` and the string `quantity` on a run (one
1303
- `Plan.quantity`); the span series' `unit` (a quantity carries its unit); the
1304
- five element callbacks `onRunClick` / `onEventClick` / `onMarkClick` /
1305
- `onChipClick` / `onCellClick` (`onElementClick`); a link's `label` (its
1306
- quantity's caption); and a group strip given both `summary` and
1307
- `summaryAggregate` (refused at build).
1308
-
1309
- #### Every change is a draft (#880)
1310
-
1311
- The Plan's editing session is the Sheet's (#879), over the source's TOP-LEVEL
1312
- entries. A dropped card and a moved or resized element are gestures, never
1313
- callbacks: each drafts the entry its row came from — at any depth, since the
1314
- whole subtree rides in its entry — the canvas draws the draft at once by
1315
- deriving the entry's rows again, and Save sends every draft as one checked
1316
- batch. The series says what a gesture writes; the root says where the batch
1317
- goes.
1318
-
1319
- ```tsx
1320
- // A LIVE handle over the halls: the canvas reads it, and Save writes it.
1321
- const halls = $.let(State.bind([DictType(StringType, Hall)], "ops.plan.halls", seed));
1322
- // The author's check over one drafted hall; a refusal names the press and holds Save.
1323
- const ready = $.const(East.function([Hall, StringType], Editing.Types.Readiness, ($, hall, _key) => {
1324
- const crowded = $.let(hall.presses.filter((_$, p) => p.jobs.size().greater(4n)));
1325
- const result = $.let(variant("ready", null), Editing.Types.Readiness);
1326
- $.if(crowded.size().greater(0n), ($) => {
1327
- $.assign(result, variant("invalid", crowded.toArray((_$, p, k) => ({
1328
- field: "jobs", message: East.str`${k} holds ${East.print(p.jobs.size())} jobs — at most 4`,
1329
- }))));
1330
- });
1331
- return result;
1332
- }));
1333
- // Every gesture as it is made — a drop, a move, an undo.
1334
- const last = $.let(State.bind([StringType], "ops.plan.last", ""));
1335
- // The palette: the Plan's own library panel, a card per job template.
1336
- const templates = $.let(Data.bind(jobTemplates));
1337
- const onPatch = $.const(East.function([Plan.Types.PatchEvent(Hall)], NullType, ($, event) => {
1338
- $(last.write(East.str`${event.origin.getTag()} · ${event.label}`)); // drop · Drop brochure on P03
1339
- }));
1340
- <Plan axis={axis} data={halls}
1341
- library={[Plan.library.tab(templates.read(), { name: "Jobs", label: t => t.name })]} // a card drags onto a press
1342
- series={[Plan.series.span(Hall, {
1343
- key: "halls", title: "Halls", label: h => h.name, runs: _h => [],
1344
- // A gesture on a press writes back into its hall through this field.
1345
- children: Plan.children("presses", [
1346
- Plan.series.span(Press, {
1347
- key: "presses", title: "Presses", label: (_p, k) => k,
1348
- // Its jobs, by id: a run each, from its start to its end.
1349
- runs: Plan.items("jobs", { from: "start", to: "end" }, (job) => ({ label: job.label, state: job.state })),
1350
- edit: { // a run moves and resizes; a dropped card joins `jobs`
1351
- create: (drop) => ({ // …under the id the canvas mints, drop.id
1352
- label: drop.from.key,
1353
- start: drop.at.unwrap("time"), end: drop.at.unwrap("time").addWeeks(2n),
1354
- state: variant("proposed", variant("added", null)),
1355
- }),
1356
- },
1357
- }),
1358
- ]),
1359
- })]}
1360
- editing={{ onUpdate: halls.write, onPatch, ready }} />
1361
- ```
1362
-
1363
- | Signature | Description | Example |
1364
- | --- | --- | --- |
1365
- | **What a gesture writes (on the series)** | | |
1366
- | `edit: { create: (drop: Plan.Types.Drop, entry, key) => Item }` beside `Plan.items(F, …)`; span / buckets / cards / events **❗** | A library card dropped on a row joins `F` as `create`'s item, under the id the canvas mints (`drop.id`, unique among every element it holds): `drop.from` is the card, `drop.at` the start of the bucket it landed in, on the axis arm. Elements given any other way than `Plan.items` fail the build, in words naming the read to give. | `planRowDrop` |
1367
- | `edit: true` beside `Plan.items(F, { from, to } \| { at }, draw)` (span / buckets / cards / 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), each gesture written into the item's named times. 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 row's collection under its id and joins that row's under the same id, as one gesture over both entries. An element's key is its item's id — its identity across every row it can move to: a row's collection keeps its ids unique, so a move onto a row holding the id is refused (⊘ while dragging). Over a read of values, `edit` is refused: what people move is keyed by an id. | `planRowDrop` |
1368
- | `edit: true` on `Plan.series.table` (its `cells`) or `Plan.tableSeries({ cells, edit: true })` — its cells `Plan.tableCells(Plan.values(F, draw))` **❗** | A number typed into a cell is the collection's value at the bucket's start: set, added where none is, deleted when cleared; an Integer collection takes a whole number. Its draw gives each value as stored (`value: some(v)`) — show it another way through `format`; any other draw, or cells given as a function, fails the build in words naming the series. On the canvas (#1438), Enter, F2, a double click or a digit opens an input over the cell: the Sheet's number field at the cell's width, with no stepper — below 480px of main, a tap opens it in a popover anchored to the cell. Enter writes, Esc leaves the cell as it was, ↑ and ↓ step the number, and Tab and Shift+Tab move along the row. Its text reads through the position's `format` (a percent's `82` or `82%` writes `0.82`), and an Integer collection's input refuses a fraction. A cell takes a number where its bucket holds one value of the collection, or none (every bucket in the window draws a cell then); a parent's cell drawing its children's subtotals takes none, and a bucket folding several values takes none, its tooltip naming the resolution its values take one at. Over rows read lean beside a nested series index, the first number typed on a row reads it whole, and every subtotal above it moves as e3 previews it. | — |
1369
- | `children: "kids"` / `Plan.children("kids", …)` **❗** | A gesture below an entry writes back through its `children`, each a field of the entry; a field that is no `Dict` of rows keyed by an id, or a tree's field holding another type than the row's, fails the build. | `planRowDrop` |
1370
- | **The session (on the root)** | | |
1371
- | `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` |
1372
- | `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`) |
1373
- | `onPatch: fn(Plan.Types.PatchEvent(R)) => Null` | One call per gesture, and per undo, redo and discard. | `planRowDrop` |
1374
- | `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` |
1375
- | `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` |
1376
- | `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` |
1377
-
1378
- - **Drawn where made.** A drafted entry's rows are derived again, exactly as
1379
- Save will leave them. A row the draft changed carries the Sheet's mark:
1380
- pending, or incomplete / invalid while a check refuses its entry — each
1381
- entry marked for its own issues. The narrow layout's cards carry the same marks.
1382
- - **One gesture, one transaction.** The history item ends the frame's toolbar:
1383
- issues · conflicts (while one waits) · Undo · Redo · Discard · Save, and its
1384
- status line. ⌘Z / Ctrl+Z undo; ⌘⇧Z / Ctrl+Shift+Z / Ctrl+Y redo.
1385
- - **The base is the source's.** An inline `Dict` is checked by its snapshot, a
1386
- paged source by its revision. When the source moves under the drafts —
1387
- another person's save, a run's — each drafted entry is carried over to its
1388
- newer value by East's three-way patch merge (the history item says
1389
- "Checking your changes against the newest data" meanwhile): changes to
1390
- different parts combine, and a part both changed to different values is a
1391
- conflict. The draft keeps its own value there, and Save waits until every
1392
- conflict is chosen, the draft's value or the source's, each choice one step
1393
- Undo takes back. While one waits, the history item leads with the
1394
- conflicts button (≠ and how many, before Issues), Save waits
1395
- aria-disabled (its tooltip says why), each item holding one wears the warn
1396
- ring until it is chosen (the optimiser's highlight in the warn colour: 1px
1397
- at its edge, inside a cell, and a soft glow, over the highlight where an
1398
- item has both), and the banner band under
1399
- the toolbar — the ≠ mark, the word Conflict — says how many changes
1400
- conflict, its Choose opening the same popover: a card for each conflict —
1401
- the item as the banners name it (an event by its title), with Go to, which
1402
- shows the item and selects it — the groups folded over it opened, and the
1403
- view moved to its dates, week or day where it shows others — the popover
1404
- staying open off it, by a side of the frame that leaves it clear where it
1405
- would cover it (where neither does, and in a frame under 480px, it
1406
- closes); the part's label; Yours and Theirs, each
1407
- value in plain words; who changed it last, where the source said so when
1408
- it refused a Save, and what both began from — with Keep all mine and Use
1409
- all theirs at its foot. An event's start and end read as one range: a
1410
- conflict at either is one card, Dates, the range whole on each side, its
1411
- two chosen together and counted once — and with them the fields a move
1412
- writes with the times, which place the event with them: a Roster duty's
1413
- shift and group, an Allocation bin's bay. While it waits each side's place
1414
- stands whole, and choosing takes one side's whole: Theirs takes their
1415
- shift back with their times, never their times in your shift. It never
1416
- opens by itself.
1417
- A Save another write got there first is refused, and once its drafts carry
1418
- over with nothing to choose it is sent again by itself — three times in a
1419
- row at most, then the person's Save sends it; with a conflict, the person
1420
- saves once it is chosen. A Save whose outcome is unknown retries the SAME request ("Retry
1421
- request"), and drafts retire only once the source reads back with the
1422
- Save in it ("Saved — reading it back…"): at the revision it committed or
1423
- a later one, so another Save landing just after it holds nothing up.
1424
- - **Kept through a reload.** The drafts are kept in the tab's storage as
1425
- each gesture is made, and a reload of the tab brings them back, carried
1426
- over to what the source holds then: as they were where it has not moved,
1427
- combined with a change since or a conflict to choose where it has, and
1428
- none where a Save landed before the reload. They are the workspace's they
1429
- were made in: the same view over another workspace, repository or server
1430
- in the tab holds none of them, before a reload or after. Undo starts at
1431
- them. They go when the tab closes, and at a sign-out; storage that
1432
- refuses them, or drafts a reload cannot restore, is a banner. The Sheet,
1433
- the Calendar, the Roster, the Allocation board, the Schematic and the
1434
- Flowchart keep theirs the same way.
1435
- - **Moves (#825).** A move along its row, or a resize, drafts the item's
1436
- instants in place. A move to another row takes the item out of its list
1437
- and appends it to the target row's, and a batch that takes an item and
1438
- places it nowhere is refused whole. The row under the drag draws a landing
1439
- band with the proposed span, and the ghost carries the element's label and
1440
- span. The narrow layout takes no moves.
1441
- - **No session, no gesture.** Without `editing` the toolbar has no history
1442
- item, no card lands and nothing moves.
1443
-
1444
- Removed with #880: the root's `onDrag` (a series' `edit`), which throws at
1445
- build, naming its replacement.
1446
-
1447
- Removed with #1260: approving and rejecting. A Plan's changes are drafts of
1448
- its session, saved together, so the root's `review` (its decision column, its
1449
- summary and Rerun, Approve all and Reject all), a series' `review` and
1450
- `approval`, a hand-built row's `approval` and `Schedule.events`' `review` role
1451
- are gone, with the verdict buttons on a row and in the inspector. Each throws
1452
- at build, naming the removal. The history item's commit is Save.
1453
-
1454
- #### `Schedule`: the kinds every builder shares
1455
-
1456
- Bind records inside the example's own `Reactive` body. Resources and templates
1457
- can come from bound records; the backlog is the event record's unscheduled rows.
1458
- `Schedule` declares field roles and accessors. The internal renderer owns the
1459
- frame, Slice toolbar, shared fields, drag layer and editing session.
1460
-
1461
- Every builder takes the app's own records through these declarations (#1365):
1462
- what it writes is the app's record, its fields mapped to the builder's roles
1463
- (`Schedule.events`); what it reads comes from the app's rows through
1464
- accessors (`Schedule.resources`); and what it publishes is a record of the
1465
- app's too, its status a field the app maps (`Schedule.periods`). The Calendar
1466
- and Plan take Plan's roles, the Roster and the Allocation their own beside
1467
- them, and a builder takes no notice of the roles it has no use for, so one
1468
- record of duties drives a Calendar and a Roster at once. A role names a field
1469
- of the row: its type is checked when the code compiles and again at build,
1470
- refused naming the role, the field and its type (`` `shift` names a String
1471
- field — "unpaidBreak" holds .Float ``). A gesture writes only the fields its
1472
- roles map; every other field of the row reads back as it was, and a new row's
1473
- unmapped fields hold their type's default.
1474
-
1475
- | API / option | Meaning | Tested example |
1476
- | --- | --- | --- |
1477
- | `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` |
1478
- | 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. `group` is also a Roster person's home group and an Allocation resource's group. | `planPrintWorks` |
1479
- | Resource `sub`, `value`, `status`, `collapsed` | Plan's gutter subtitle, value and status; initial collapse is a Boolean or accessor. | `planPrintWorks` |
1480
- | 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` |
1481
- | Resource `position`, `skills`, `contract`, `agency`, `trainer`, `trainee`, `usual` | The Roster's people (#1367): a person's default position (String), the skills they hold (`Set<String>`), their contracted weekly hours (Float), whether they are a named agency worker, train others or need a trainer beside them (Booleans), and their usual shift (`Option<String>`). | `rosterWarehouse` |
1482
- | Resource `offset` · `min`, `max`, `note`, `hold`, `jobs` | The Allocation's lanes: how far past each slot's start a lane's bins are booked (a TimeStep). Its resources: their range in the quantity's unit (Floats, required by the Allocation), a line about the next job (`Option<String>`), how long a reservation is held (a TimeStep) and their other work (`Array<Allocation.Types.Job>`). | `allocationKilnYard` |
1483
- | a resource accessor returning another type **❗** | Each accessor is reified once and held to the type it returns: one returning another is refused at build, naming what it returns (`` "People": `contract` returns a Float, a person's contracted weekly hours — and this one returns .String ``). | — |
1484
- | `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. `title` is optional: the Calendar and Plan draw it and refuse a kind without one; the Roster and the Allocation draw a duty and a bin by their roles. | `planEvents` |
1485
- | Event `shift`, `group`, `position?`, `activity?`, `hours?` | The Roster's roles (#1367): String fields naming a duty's shift, the group it is rostered in and the position it holds; an `Option<String>` its one activity; and an accessor `(row, key) => Float`, the hours it counts — its length when omitted. See the Roster below. | `rosterWarehouse`, `rosterMinimal` |
1486
- | Event `arrival`, `parts: { field, of }`, `hold`, `kind?` | The Allocation's roles (#1367): an `Option<String>` naming the arrival a bin books (`none`, a reservation); a `Dict<String, Float>`, its quantity on each resource of the slot `of` names; a TimeStep, how long a resource holds it; and an `Option<String>`, what it goes with. With Plan's `quantity` and an instant's `at`. See the Allocation below. | `allocationKilnYard`, `allocationMinimal` |
1487
- | roles of both builders on one kind, or two roles naming one field **❗** | Refused at build, naming them: a kind is the Roster's duties or the Allocation's bins, and a builder writes each of its roles into a field of its own. | — |
1488
- | 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` |
1489
- | 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` |
1490
- | 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` |
1491
- | Event `status: { field, cases }` | A non-Option variant field with one `{ label, tone, ring }` per case; warning status rings the element. | `planPrintWorks` |
1492
- | Event `overlaps: "warn" \| "allow"` | Warn is the default. Allow permits parallel events. Both preserve every event; warnings never remove or truncate overlaps. | `planPrintWorks` |
1493
- | Event `backlog: { duration, due? }` | Option times allow unscheduled rows. Accessors derive their duration and optional due date from `(row, key)`. | `planEvents`, `planPrintWorks` |
1494
- | Event `templates` | `Schedule.templates(rows, { name, group?, at?, duration, values, source })` (`Calendar.templates` in a Calendar) over a templates record, its `source` the rail's source that narrows its cards; `values` supplies the fields other than time and resource, and an instant kind's templates omit `duration`. The Calendar and the Plan refuse a list written in the code (#1343, #1344). | `calendarOperations`, `planPrintWorks` |
1495
- | 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` |
1496
- | Event `ready`, `inspector` | Readiness returns `Editing.Types.Readiness` and can hold Save. A custom inspector receives the typed row and its session writer. | `planPrintWorks` |
1497
- | Event source, `entries` | The builder's `Slice.bindRecords` narrows a kind through a source named after its slot, over an interval index: its events in the window and its backlog read through it (the Calendar, #1343; the Plan, #1344), and the Roster's week of duties and the Allocation's day of bins, the range their own navigation writes (#1368, #1371). `entries: Data.bindPaged(record)` supplies original-key reads for editing. A kind's own `slice` and `filter` are refused at build, naming the change. See Indexed records and shared Slice above. | `calendarRecordIndexes`, `calendarOperations`, `planPrintWorks`, `planWindows`, `rosterWindowed`, `allocationWindowed` |
1498
- | Event `window`, `backlogWindow`, `entries` | The separate single-index paging form, described under Large records below. A kind narrowed through a source of its builder's rail takes neither `window` nor `backlogWindow`, and a Plan refuses it on a kind placed on a paged resource kind, which is read a cell at a time through its source (#1039). | `calendarWindowed` |
1499
- | `Schedule.periods(Record.bind(r), { every, status: { field, draft, published }, dismissed?, entries? })` **❗** | What a builder publishes (#1367): the app's record of periods, `Dict<DateTime, P>`, a row each keyed by its start — a UTC midnight, a week's first day by the builder's week start for `"week"`, or a `"day"`. `status.field` names a variant field of `P`, not an Option, and `draft` and `published` two of its cases; the published case holds `Null` or `{ at: DateTime }`. `dismissed`, the Roster's, names a `Set<String>` field: the proposals a week dismissed. `entries: Data.bindPaged(r)` reads the periods by key — the period, the one before it, the open picker's span, each one key search and one page — else the record is read whole. Without `periods`, a builder has no status chip and no Publish. | `rosterWarehouse`, `rosterWindowed`, `allocationKilnYard`, `allocationWindowed` |
1500
-
1501
- A period whose status is the published case is read-only in every layout,
1502
- phones included, and so is one in a case that is neither, its chip naming the
1503
- case; a period with no row is Not started once its read lands; until then the
1504
- status chip is a placeholder in its slot. Publish saves the period's drafts
1505
- first, and once every record reads back as saved writes the published case —
1506
- the time in `at` when the case holds one — and saves the period: a Save that
1507
- fails leaves the period a draft with its drafts kept, so a published period
1508
- never sits over unsaved rows. A period row the builder makes holds its type's
1509
- default in every field it doesn't map. Refused at build, each naming the
1510
- option: a record not bound with its patch mutation, not keyed by DateTime, or
1511
- whose rows are no structs; an `every` that is neither `"week"` nor `"day"`; a
1512
- `status.field` the row lacks, that is no variant or that is an Option; a
1513
- `status.draft` or `status.published` that is no case of it (`` `status.published`
1514
- names a case of "state" (cancelled, issued, open) — and it names "sent" ``), or
1515
- both naming one; a published case holding anything else; a `dismissed` that is
1516
- no `Set<String>` field; and `entries` that is not the record's own entries.
1517
-
1518
- `Schedule.Types` exposes the same contracts to every builder:
1519
-
1520
- | Type | Value |
1521
- | --- | --- |
1522
- | `ResourceRef`, `EventRef` | `{ kind, key }`: the slot name and the original key's text. |
1523
- | `Status`, `StatusCases(VariantType)` | `{ label, tone, ring }`, and one such status per variant case. |
1524
- | `Clock` | `{ hour, minute }`, both Integers. |
1525
- | `Duration` | The shared time-step variant: minutes, hours, days, weeks or months, with a Float amount. |
1526
- | `Candidate` | `kind`, `from` (template/backlog/event key), `start`, `end`, optional `resource`; the Plan's drop veto receives this. |
1527
- | `Patch(RowType)` | Every field optional; `Schedule.patch` constructs the patch. An omitted field stays unchanged; `none` supplied for an Option field clears it. |
1528
- | `Fit`, `Refusal` | One verdict of an app's fit — `fits { score, why, warn }`, or `refused` with its `Refusal` (`{ group, reason, measure }`) — the Roster's and the Allocation's alike. |
1529
-
1530
- Event kinds default to batch Save. For automatic commits, set
1531
- `applyMode="auto"` on the same `<Plan>` with its bound resources and events:
1532
-
1533
- ```tsx
1534
- <Plan resources={resources} events={events} axis={axis} applyMode="auto" />
1535
- ```
1536
-
1537
- Each ready gesture commits through its kind's patch mutation. This does not change the separate data-series session's
1538
- `editing.mode`. Auto mode is covered by `plan-events.spec.ts` and
1539
- `plan-builder-editing.dom.test.tsx`; the showcase examples demonstrate batch Save.
1540
-
1541
- #### Event kinds, read-only rows and links between events (#1191)
1542
-
1543
- Beside `data`, a Plan takes event kinds over records — `Schedule`'s, the very
1544
- values a Calendar takes. `resources` are the rows; each kind in `events` is a
1545
- record of its own, bound with its patch mutation, and each of its events sits
1546
- on the resource it names. `rows` adds read-only rows: hand-built ones, and
1547
- series over a dataset with `Plan.over`. A link names an event by its kind and
1548
- key, never its row: a draft can move the event, and the link follows it.
1549
-
1550
- ```tsx
1551
- const presses = $.let(Record.bind(planPrintPresses, []));
1552
- const jobs = $.let(Record.bind(planLinkJobs));
1553
- const stock = $.let(Data.bind(planLinkStock));
1554
- <Plan axis={axis}
1555
- resources={{ presses: Schedule.resources(presses.read(), { name: "Presses", icon: "print", label: p => p.name, group: p => p.hall }) }}
1556
- events={{ job: Schedule.events(jobs, {
1557
- name: "Print job", icon: "file-lines", title: "title", start: "start", end: "end",
1558
- resource: { field: "press", of: "presses" }, state: "state", quantity: { field: "sheets", unit: "sheets" },
1559
- }) }}
1560
- rows={[Plan.over(stock, [
1561
- Plan.series.table(PrintStock, { key: "stock", title: "Paper stock", label: s => s.name, cells: s => Plan.tableCells(weekly(s.weekly)) }),
1562
- ])]}
1563
- links={[Plan.link({ key: "covers", from: Plan.eventRef("job", "J-2001"), to: Plan.eventRef("job", "J-2002"),
1564
- quantity: Plan.quantity(12000.0, { unit: "covers" }) })]} />
1565
- ```
1566
-
1567
- | Signature | Description | Example |
1568
- | --- | --- | --- |
1569
- | `resources: { [slot]: Schedule.resources(rows, { name, icon, label, … }) }` + `events: { [slot]: Schedule.events(Record.bind(r), { 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` |
1570
- | 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. | — |
1571
- | `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` |
1572
- | `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` |
1573
- | `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` |
1574
- | `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` |
1575
- | `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` |
1576
- | `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 |
1577
-
1578
- Removed with #1191: `<Plan.View>` (`<Plan>`).
1579
-
1580
- #### How event kinds draw (#1192)
1581
-
1582
- Each resource kind is a block of rows, ahead of `data`'s. Every resource has a
1583
- row per way the kinds placed on it draw — bars, tiles, chips, marks, in that
1584
- order, kinds that draw alike sharing one — then its `measures`, each applied
1585
- to the resource's row. Its first row carries the resource's label, sub line,
1586
- value and status; the others name the kinds that draw that way. A kind with
1587
- `group` sits under its group strips, and one with `parent` nests each resource
1588
- under the one it names, to any depth, the parent's bars rolling its children's
1589
- up. Each element is an event in the window, wearing its kind's icon, its
1590
- lifecycle, its quantity, its lane and its status's warning ring.
1591
-
1592
- The rows are read over the window the canvas draws and the periods it lays
1593
- out beyond each edge, from the records as they stand, and read again when one
1594
- commits. A commit that changes none of them redraws nothing, and a read that
1595
- fails leaves the last rows standing and says why on the toolbar. Beside a
1596
- paged `data` they lead every window, drawn once.
1597
-
1598
- | Signature | Description | Example |
1599
- | --- | --- | --- |
1600
- | 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` |
1601
- | 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` |
1602
- | 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` |
1603
- | `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` |
1604
- | a resource kind no event kind is placed on, with no `measures` **❗** | Refused at build: it would draw no rows. | — |
1605
- | 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. | — |
1606
-
1607
- #### Overlap feedback
1608
-
1609
- With `overlaps: "warn"`, each overlapping event wears the shared warning ring.
1610
- The toolbar chip after the summary counts pairs; selecting it selects the first
1611
- pair in time order and brings its row into view, expanding its ancestors. The
1612
- inspector lists the selected event's pairs or the selected resource's pairs.
1613
- `planEvents` and `planPrintWorks` demonstrate this. Overlapping events are kept.
1614
-
1615
- Bucket cells also preserve their events when space is short: they draw only
1616
- whole tiles, followed by a `+n` menu listing those that do not fit. Choosing a
1617
- menu item performs the same action as selecting that tile (`planTargetState`).
1618
-
1619
- #### The frame (#1193)
1620
-
1621
- `<Plan>` renders in its builder frame wherever it is used: the toolbar, the
1622
- banners, the canvas in main and the footer, and the panes its props ask for —
1623
- the library with `library` (#1195), the inspector with `inspector` (#1197);
1624
- with neither there is no pane. It draws no border, so a host frames it or
1625
- places it bare.
1626
-
1627
- | Signature | Description | Example |
1628
- | --- | --- | --- |
1629
- | the toolbar | Every control the Plan draws outside its canvas, one row at every width: the rail of its one `Slice.bindRecords` folds first, its summary after every step of it, then the Plan's own steps and the key search into its icon; the fold toggle, the resolution and the overlaps chip into the date navigator's View, one move; the history item folds last, and below that, at a phone's width, the rail's icon drops its caret, the history and Save staying in the row. | `planTargetState`, `planRowDrop`, `planPrintWorks` |
1630
- | the banners | Each session's — `data`'s, and each event kind's titled with its name (#1194): changes that conflict with newer ones, whose Choose opens the history item's conflicts, a Save's conflict, a refusal, an unknown outcome with Retry; each leaves when what it reports does, and one kind's leaves the other kinds' commits standing. | `planRowDrop`, `planPrintWorks` |
1631
- | 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 one loading line. | `planPrintWorks` |
1632
- | `style={{ height: "fill" }}` / `maxHeight` | The whole Plan's: the canvas fills main and scrolls its own rows. | `planTargetState` |
1633
- | 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. | — |
1634
-
1635
- Removed with #1193: the canvas's own toolbar row (the frame's toolbar holds
1636
- its items) and its review foot, the Series button (the library pane's
1637
- Series tab, #1195) and the narrow layout's chip row (its items are the
1638
- toolbar's).
1639
-
1640
- Removed with #1344: the local Slice — `Slice.bind`, the bare `slice={slice}`
1641
- handle and a single `Slice.bindRecord` (one `Slice.bindRecords`), and
1642
- `data={Slice.rows(slice)}` (the `rows` source of `slice={{ slice }}`) — with
1643
- its cohort, filter and search chips, the scope badge, the summary line's
1644
- local count, the brush's histogram and its live per-step writes (a record's
1645
- query moves once a gesture), a resolution's rewrite of the window (it
1646
- re-buckets) and templates written in the code (`Schedule.templates` over a
1647
- record). Each form still written is refused at build, naming the change.
1648
-
1649
- Changed with #1344 too: the canvas's rows never follow the dates on screen. A
1650
- `range` on the `rows` source or a resource kind's — which held the window, so
1651
- every pan narrowed the rows again — is refused as the Plan is evaluated,
1652
- naming the change: leave it out, and the field stays a field of the rail the
1653
- viewer sets. A slice with no source holding the window leaves the canvas its
1654
- own window, which the date navigator, the brush and the keys move, and which a
1655
- reload opens on, as the canvas's folds are kept.
1656
-
1657
- #### The library pane (#1195)
1658
-
1659
- `library` lists the start pane's tabs, in order, each a `Plan.library.*`
1660
- call; left out, or empty, there is no library pane. Its cards are what a
1661
- planner drags onto the canvas — an author's tab's onto the rows of `data`
1662
- that make an item of a card (#1259), the event kinds' onto their resources
1663
- (#1196) — and its Series tab is what a viewer shows and hides.
1664
-
1665
- ```tsx
1666
- // What the Plan reads whole binds with Data.bind: the customers, and the job templates — a record of their own.
1667
- const customers = $.let(Data.bind(planPrintCustomers));
1668
- const jobTemplates = $.let(Data.bind(planPrintJobTemplates));
1669
- // One rail (#1344): the templates' and the customers' sources narrow their tabs.
1670
- const slice = $.let(Slice.bindRecords("ops.plan", {
1671
- jobTemplates: { source: Data.bindPaged(planPrintJobTemplates, { indexes: ["plan_print_job_templates_by_group"] }), fields: { group: { label: "Job templates" } } },
1672
- customers: { source: Data.bindPaged(planPrintCustomers, { indexes: ["plan_print_customers_by_district"] }), fields: { district: { label: "District" } } },
1673
- }));
1674
- <Plan axis={axis} slice={{ slice }}
1675
- resources={{ presses: Schedule.resources(presses.read(), { name: "Presses", icon: "print", label: p => p.name, group: p => p.hall }) }}
1676
- events={{ job: Schedule.events(jobs, {
1677
- name: "Print job", icon: "file-lines", title: "title", start: "start", end: "end",
1678
- resource: { field: "press", of: "presses" },
1679
- backlog: { duration: j => variant("hours", j.sheets.divide(8000.0)), due: j => j.due },
1680
- templates: Schedule.templates(jobTemplates.read(), { // a templates record, following its source of the rail
1681
- name: t => t.name, group: t => some(t.group), duration: t => variant("hours", t.hours), values: t => t.values, source: "jobTemplates",
1682
- }),
1683
- }) }}
1684
- library={[
1685
- Plan.library.events(), // every kind's templates
1686
- Plan.library.backlog(), // every kind's unscheduled events, by when they are due
1687
- Plan.library.series(), // what a viewer shows and hides
1688
- Plan.library.tab(customers.read(), { // the author's own cards
1689
- name: "Customers", icon: "building",
1690
- label: c => c.name, meta: c => some(c.trade), group: c => c.district,
1691
- drop: c => Schedule.patch(PrintJob, { customer: c.name }), // what a card dropped on a job sets
1692
- source: "customers", // the rail's source it follows
1693
- }),
1694
- ]} />
1695
- ```
1696
-
1697
- | Signature | Description | Example |
1698
- | --- | --- | --- |
1699
- | `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). Each kind's list follows its source of the rail (#1344): the tab counts what it shows (`Events 8 of 12`) and, when the rail leaves a list none, says so with Clear filters for it. Refused on a Plan with no event kinds. | `planEvents`, `planPrintWorks` |
1700
- | `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. A kind narrowed through its source (#1344) shows its narrowing's backlog, the tab counting `N of M` — what shows beside the stored events the choices hide — and its Clear filters keeping the window. Refused on a Plan with no event kinds. | `planEvents`, `planPrintWorks` |
1701
- | `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), and leaves it out of every figure of the canvas's — the footer's counts, the inspector's stats and a row's facts — nothing saying so, its backlog the Backlog tab's still; 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, kept per viewer under its `key`; the rest under the Plan's `id`, and only while the library lists this tab. Refused on a Plan with nothing a viewer can hide. | `planPrintWorks` |
1702
- | `Plan.library.tab(rows: Dict<K, R>, { name, icon?, label, meta?, group?, drop?, source? })` **❗** | `source` names the rail's source it follows, by its rows' keys (`Customers 6 of 16`, #1344). 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` |
1703
- | `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` |
1704
- | `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` |
1705
- | a tab listed twice — an author's by its name **❗** | Refused at build, naming it. | — |
1706
-
1707
- The pane is the frame's start pane, 272px open: its open tab and whether it
1708
- is collapsed are kept per viewer under the Plan's `id`, and below 560px of
1709
- frame it opens from its rail over the canvas. On a touch screen the Series
1710
- tab's search is a 44px field.
1711
-
1712
- #### The inspector pane (#1197)
1713
-
1714
- `inspector` gives the Plan its end pane: what is selected on the canvas. A
1715
- click on an event's element — a bar, a tile, a chip or a mark of an event
1716
- kind's rows — selects the event and its row, and the element wears the brand's
1717
- ring; Shift, ⌘ or Ctrl adds an event to the selection or takes it out. A click
1718
- on a row's name selects the row, and one on its plot names the bucket under the
1719
- pointer too. Esc clears it all. An event kind may give its own inspector for
1720
- one event, in place of the form over its `fields`:
1721
-
1722
- ```tsx
1723
- // A stop's own inspector: its title, and its kind on a segment — `update` writes the edited stop back.
1724
- const inspectStop = $.const(East.function([PrintStop, FunctionType([PrintStop], NullType)], UIComponentType, ($, stop, update) => {
1725
- const setKind = $.const(East.function([StringType], NullType, ($2, picked) => {
1726
- const kind = $2.const(picked.equal("service").ifElse(
1727
- () => East.value(variant("service", null), PrintStop.fields.kind),
1728
- () => East.value(variant("plate_change", null), PrintStop.fields.kind)));
1729
- $2(update({ title: stop.title, at: stop.at, press: stop.press, kind }));
1730
- }));
1731
- return <SegmentGroup value={stop.kind.getTag()} onChange={setKind} size="sm"
1732
- items={[SegmentGroup.Item("plate_change", "Plate change"), SegmentGroup.Item("service", "Service")]} />;
1733
- }));
1734
- <Plan axis={axis} resources={{ presses: … }}
1735
- events={{
1736
- job: Schedule.events(jobs, { …, fields: { customer: Schedule.field.text({ label: "Customer" }) } }),
1737
- stop: Schedule.events(stops, { name: "Stop", icon: "screwdriver-wrench", title: "title", at: "at",
1738
- resource: { field: "press", of: "presses" }, inspector: inspectStop }),
1739
- }}
1740
- inspector />
1741
- ```
1742
-
1743
- | Signature | Description | Example |
1744
- | --- | --- | --- |
1745
- | `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; a paged resource's placeholders until its cells land, never 0 — 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 — the hours those of the kinds it reads — 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` |
1746
- | `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` |
1747
- | 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` |
1748
-
1749
- The pane is the frame's end pane: whether it is collapsed is kept per viewer
1750
- under the Plan's `id`, and below 560px of frame it opens from its rail over
1751
- the canvas.
1752
-
1753
- #### Drag and drop over event kinds (#1196)
1754
-
1755
- The event kinds' drags are built in: a Plan given `resources` and `events`
1756
- takes them, and its `library` gives the cards. Each is one step of the Plan's
1757
- one history (#1194), which Undo takes back. A drag starts after 4px and snaps
1758
- to the resolution; its ghost says what lands where, or — red — why it can't.
1759
- The panes slide off main while it lasts, and nothing drags in the narrow
1760
- layout.
1761
-
1762
- | Signature | Description | Example |
1763
- | --- | --- | --- |
1764
- | 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` |
1765
- | 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` |
1766
- | 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` |
1767
- | a bar's or a chip's edge → along the axis | Resizes it, never shorter than one snap. | `planPrintWorks` |
1768
- | 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` |
1769
- | 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` |
1770
- | 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` |
1771
-
1772
- #### Large records, a window at a time (#1199)
1773
-
1774
- A record too large to read whole is read a window at a time: an event kind
1775
- through its record's indexes, and a resource kind paged as the canvas
1776
- scrolls. An event kind narrowed through its source of the Plan's slice
1777
- (#1344) reads its window and its backlog through the source's interval index,
1778
- as `planPrintWorks`' jobs do — counted first, and read only within 10,000
1779
- events (#1039, below) — and one placed on a paged resource kind is read a cell
1780
- at a time through its source, as `planWindows`' jobs are (below); what follows
1781
- is the form for a kind with no rail, over resources read whole
1782
- (`calendarWindowed`). An event kind given `window` — a paged read of a day
1783
- index over its record, keyed by `Schedule.days` — reads only the days the
1784
- canvas draws, on a Plan counted first by the entries the index files under
1785
- them and read only within 10,000 (#1039, below); given `backlogWindow`, a paged read of an index keyed by
1786
- `Schedule.unscheduled`, its backlog; and given `entries`, a paged read of the
1787
- record's own entries, one event by its key. A resource kind given its
1788
- resources as a paged read pages them, 200 to a window, the key search seeking
1789
- one — and every event kind placed on it is read a cell at a time: one with no
1790
- source of the slice, read whole or through its day index, is refused at
1791
- build, naming the series and the summary index to declare over its own
1792
- fields. Neither record is ever read whole: not to draw, not to edit, not to
1793
- save.
1794
-
1795
- ```tsx
1796
- // Package side: the jobs record declares its two indexes, each keyed by Schedule's own function.
1797
- // indexes: (index) => ({
1798
- // jobs_by_day: index.keys(East.function(… Schedule.days(start, end) …)),
1799
- // jobs_unscheduled: index.keys(East.function(… Schedule.unscheduled(job.start, job.due) …)),
1800
- // }),
1801
- <Reactive>{$ => {
1802
- const presses = $.let(Data.bind(pressesTask)); // read whole: a paged kind's jobs are read a cell at a time (below)
1803
- const jobs = $.let(Record.bind(jobsRecord));
1804
- const days = $.let(Data.bindPaged(jobsRecord, { index: "jobs_by_day", join: true }));
1805
- const backlog = $.let(Data.bindPaged(jobsRecord, { index: "jobs_unscheduled", join: true }));
1806
- const entries = $.let(Data.bindPaged(jobsRecord)); // one job by its key
1807
- return <Plan axis={axis}
1808
- resources={{ presses: Schedule.resources(presses.read(), { name: "Presses", icon: "print", label: p => p.name, sub: p => some(p.hall) }) }}
1809
- events={{ job: Schedule.events(jobs, {
1810
- name: "Print job", icon: "file-lines", title: "title", start: "start", end: "end",
1811
- resource: { field: "press", of: "presses" },
1812
- backlog: { duration: j => variant("hours", j.sheets.divide(8000.0)), due: j => j.due },
1813
- window: days, backlogWindow: backlog, entries,
1814
- }) }} />;
1815
- }}</Reactive>
1816
- ```
1817
-
1818
- | Signature | Description | Example |
1819
- | --- | --- | --- |
1820
- | `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 days sought from the first's midnight to the window's end — where they start in the index and how many entries they hold — and the index's pages read from there; a pan seeks the days it brings in. On a Plan that count comes first, and past 10,000 entries no page is read (#1039, below). 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`; either beside a source of the rail; and, on a Plan, a kind so read placed on a paged resource kind, naming the source to name after it and its series and summary indexes (#1039). An index read without `join: true` is refused as it is read. | `calendarWindowed` |
1821
- | `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. | `calendarWindowed` |
1822
- | `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` or a source of the rail, refused without either. 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` |
1823
- | `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`. Every event kind placed on it is read a cell at a time through its source of the slice (#1039, below): one read whole, one read through its day index (`window`) and one placed beside another resource kind are refused at build, the refusal naming the series and the summary index to declare over the kind's own fields. 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 takes one too, under the same rules (#1424; see Calendar below). | `planWindows` |
1824
- | a source of the slice named after the paged kind's slot **❗** | The narrowing's rows are the kind's windows (#1344): `Data.bindPaged(record, { indexes })` over the kind's own record, paged in the source's index's order, 200 to a window — never every resource read, nor a window of them filtered by key — the rail and the canvas counting the narrowing's, the frame following none of its keys. A choice keeps the last view standing, retained, until its first window lands; a bounded canvas puts the resource at its top back where the narrowing's first windows draw it, and else starts at the top. It has no key search: a narrowing's searches run in its index's order. A source over another record's rows is refused at build. | `planSeriesByHall`, `planRecordIndexes` |
1825
- | `Schedule.resources(rows, { window })` **❗** | Gone (#1199): refused at build, naming the paged form. | — |
1826
- | 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` |
1827
-
1828
- A key search stands as the canvas reads new rows: a pan, a draft or a commit
1829
- to the jobs reads the presses' windows again over the same snapshot, and the
1830
- search keeps its text, its matches and the view. Only a new snapshot of the
1831
- presses asks it again, there.
1832
-
1833
- #### A cell at a time, shaded zoomed out (#1039)
1834
-
1835
- An event kind placed on a paged resource kind reads only the events of the
1836
- resources around the rows in view: its source lists a **series index** of its
1837
- record beside the interval index, and a **summary index** with it
1838
- (`planWindows`). A series index files each event once under its resource, at
1839
- the level its length fits — its tile, or a coarser one up to a year — and past
1840
- a year under each year it touches, carrying its row (#1433); a summary holds,
1841
- under each resource and tile, how many events touch it and the milliseconds of
1842
- it they cover (the **e3** skill). A kind on a paged resource kind read any other way — its source
1843
- listing its interval index alone, or a summary and no series; no source, its
1844
- record read whole or the days in view through its day index; or placed
1845
- beside another resource kind — is refused, naming both declarations over the
1846
- kind's own fields: `index.series({ key: "press", from: "start", to: "end",
1847
- tile: "week" })` and `index.summary({ key: "press", from: "start", to: "end",
1848
- tile: "month" })` among the jobs record's indexes. Nothing else in the Plan
1849
- changes:
1850
-
1851
- ```tsx
1852
- // Package side, among the jobs record's indexes, beside the interval index:
1853
- // jobs_by_press_week: index.series({ key: "press", from: "start", to: "end", tile: "week" }),
1854
- // jobs_by_press_month: index.summary({ key: "press", from: "start", to: "end", tile: "month" }),
1855
- const slice = $.let(Slice.bindRecords("ops.plan", {
1856
- job: { source: Data.bindPaged(jobs, { indexes: ["jobs_by_time", "jobs_by_press_week", "jobs_by_press_month"] }), range: "start" },
1857
- }));
1858
- ```
1859
-
1860
- A **cell** is the events of a block of fifty of the paged kind's resources at
1861
- one level — of a kind its source of the slice narrows, fifty of the narrowing's,
1862
- in its index's order, so only the narrowed resources in view have their events
1863
- read, and a choice reads none before its own rows are drawn
1864
- (`planSeriesByHall`, #1344). The Plan wants the blocks meeting the rows in view and twenty-five
1865
- resources either side, at each level over the tiles the range it reads touches
1866
- — its window and the periods laid out beyond each edge — one tile either side,
1867
- and the tile before those, whose events may run into them: a range a resource
1868
- a level, whatever the span (#1433). Every wanted cell's searches go in one
1869
- request, which counts its entries before one is read, and the entries of the
1870
- tiles it does not hold in one more. A pan or a
1871
- scroll within the cells it holds reads nothing, and a commit reads the wanted
1872
- cells again, the old standing in until they land. The rail's window and its
1873
- exact count stay the interval index's.
1874
-
1875
- | Signature | Description | Example |
1876
- | --- | --- | --- |
1877
- | a source listing `index.series` + `index.summary` beside the interval index **❗** | The kind read a cell at a time, two requests a change: a block of fifty resources, a range a resource a level, whatever the span (#1433). An event past a year is under every year it touches and draws once; the drafts draw where they place their events, read or not; a link's event end the cells do not hold is read by its key, in one read. | `planWindows`, `planRecordIndexes` |
1878
- | past 10,000 events in the cells wanted | The summary's cells instead, at the largest of its tiles that divides the canvas's bucket — a day, an ISO week (which divides no month), a month, a quarter or a year — each resource's share of each bucket booked for bars and chips, how many events touch it for tiles and marks. With none that divides it, the events over the window while their count there is within the cap; past it the rows are hatched, and a banner names how many events there are and the resolution that shades them. | `planWindows` |
1879
- | a narrowing | A series index led by the narrowed fields serves it exactly; any other field is asked of the cells' events in one read. A summary shades a narrowing only when led by its fields. | `planWindows` |
1880
- | the footer and the inspector | The window's events counted exactly from the source, as the rail counts them; their hours and overlaps over the rows drawn — "Hours in view", once the cells have landed — and the backlog read whole through the source's unset start. A resource selected while its cells are not read — scrolled out of the blocks read, or before the first read lands — shows its figures as placeholders until they land, never 0. | `planWindows` |
1881
- | a kind on a paged resource kind whose source lists its interval index alone, or a summary and no series; one read whole, or through its day index; one placed beside another resource kind **❗** | Refused, each naming the series and the summary index to declare over the kind's own fields — as the payload builds where the indexes are known there, else as the Plan is evaluated, in the same words. | — |
1882
- | a series index without a summary; an index filed by another field than the kind's resource field, or over other times than its own; a series index for a kind placed on resources read whole, or on none; two series or two summaries of one tile over the same fields **❗** | Refused as the payload builds, each naming the change. | — |
1883
-
1884
- Every other event kind is **counted first** (#1039): before one of its events
1885
- is read, it is counted over the range the canvas reads — its window and the
1886
- periods it lays out beyond each edge, for every resource. A kind read through
1887
- its source is counted through its interval index, the count its window's read
1888
- asks first, so counting asks e3 nothing of its own; a kind read through its
1889
- day index by the entries the index files under the days of the range, in the
1890
- search its read asks first — an event under each day it runs on, so an upper
1891
- bound on its events, never their number; and a kind whose record is read
1892
- whole in memory. Within 10,000 it is read over the window as ever; past them
1893
- none of its events is read or drawn:
1894
-
1895
- | Signature | Description | Example |
1896
- | --- | --- | --- |
1897
- | a kind past 10,000 events, its source listing a summary **❗** | Its rows shade from the summary as a kind read by its cells does, at the largest of its tiles that divides the canvas's bucket, and no event of the range is read. | — |
1898
- | a kind past 10,000 events with no summary that shades the bucket **❗** | Its rows are hatched, and the banner says how many events there are and the resolution its summary shades at — with none, to narrow the filters or zoom in. A pan, a zoom, a narrowing or a commit that brings the range within the cap reads its events again. | — |
1899
- | a kind read whole, past 10,000 events | Counted in memory, and drawn the same: hatched, with the banner. | — |
1900
- | the footer and the inspector over a kind past the cap | Its events in the window counted — through the source as the rail counts them, or in memory — never read; a counted kind is read over the window only once its count over the range the canvas reads is within the cap. A resource's row counts none of its events: the inspector says so (`Print jobs not counted: too many to draw at this resolution`), never 0. With nothing selected it counts its events but not their hours — the hours those of the kinds it reads, none where no kind's are — and names it, in one line with any kind it counts none of (`Print job hours not counted: too many to draw at this resolution`). A kind hidden in the Series tab is in no figure, and nothing says so. | — |
1901
- | a kind read through its day index (`window`), past 10,000 entries **❗** | Counted first through its day index, its count the days its events run on: none of its days is read, its rows are hatched, and its events are not counted anywhere — the banner says so (`Print job events in view: not counted`), the footer (`13 events, print jobs not counted`) and the inspector too, never a number it does not have. Within 10,000 entries its days are read as ever. | `calendarWindowed` |
1902
-
1903
- ### The Sheet — `<Sheet>`
1904
-
1905
- `<Sheet>` is the planning spreadsheet, and there is one: it renders in its
1906
- builder frame wherever it is used — one toolbar holding every control the
1907
- sheet has, the banners, the grid in main with its strip docked under it, and
1908
- the footer — and its panes are optional props: `library`, before the grid,
1909
- and `inspector`, after it. No prop, no pane. Its rows come from one of three
1910
- sources:
1911
-
1912
- - `record` — an e3 record bound with its patch door: its entries, one entry's
1913
- rows or groups, or a large record a window at a time. Save is one patch
1914
- commit through the record, and the footer gives the record's last save.
1915
- - `data` — the host's rows: an array, a whole-value bind handle (`State.bind`,
1916
- `Data.bind`) or a paged source (`Data.bindPaged`). Edits reach the host
1917
- through `onApply`, `onUpdate` and `onPatch`; with none of them the sheet is
1918
- read only.
1919
- - the **`rows` source of its `slice`** — `slice={{ slice: Slice.bindRecords(key,
1920
- { rows, … }) }}` (#1345): the source's record's rows, every one in the
1921
- record's order, each row's id its record key. While the source narrows them
1922
- the sheet draws the narrowing over them as the **lens** (#1349), a filtered
1923
- spreadsheet: only the rows the narrowing keeps, one after another in the
1924
- record's order, each at its row number. Save commits through
1925
- `onApply={Record.onApply(record, { keyed: true })}` by original primary key.
1926
-
1927
- Its columns are typed — a date, a quantity with its unit, an integer, text, a
1928
- register lookup, reference or enum, a set of register members, a directed
1929
- `from > to` LINK between register members as a typed value, a stamped
1930
- read-only code, a custom parse / print pair — with a blank tail that invites
1931
- the next row, typed parsing with a docked candidate strip, a copilot that
1932
- fills cells and proposes whole rows from author East functions, one rail over
1933
- its `Slice.bindRecords` — its rows, whose narrowing it draws as the lens, its
1934
- templates records and the tabs that name a source — with saved-view tabs, drag
1935
- and drop, Excel round-tripping, and a key search over a paged source. Every change is a draft
1936
- of an editing session, checked as it is made and applied as one checked
1937
- batch. Where east-ui's `<Table>` displays rows, the Sheet is where a planner
1938
- types them: reach for it when the rows are authored in place and written back.
1939
-
1940
- The tag and its authoring vocabulary — `Sheet.column.*`, `Sheet.register.*`,
1941
- `Sheet.driver`, `Sheet.link.*`, `Sheet.patch`, `Sheet.group`, `Sheet.subRows`,
1942
- `Sheet.library.*`, `Sheet.field`, `Sheet.apply`, `Sheet.Types` — come from
1943
- `@elaraai/e3-ui`, and the tags around it from `@elaraai/east-ui`. It moved
1944
- here from east-ui (#1179), and `<Sheet.View>` and `<Sheet.Builder>` are one
1945
- component now (#1216): a surface that wrote either writes `<Sheet>`, a
1946
- builder's `id` is its `name`, and the sheet fills the box it is given —
1947
- `style` holds only `gutterWidth`. Its words in React — `SheetMessagesProvider`
1948
- and `sheetMessages` — are `@elaraai/e3-ui-components`'.
1949
-
1950
- ```tsx
1951
- /** @jsxImportSource @elaraai/e3-ui */
1952
- import { Box, Reactive } from '@elaraai/east-ui';
1953
- import { Record, Sheet } from '@elaraai/e3-ui';
1954
- // Package side: export const jobs = e3.record("jobs", DictType(StringType, Job), {
1955
- // initial: new Map([…]),
1956
- // mutations: (mutation) => ({ patch: mutation.patch() }),
1957
- // });
1958
- <Reactive>{$ => {
1959
- const record = $.let(Record.bind(jobs));
1960
- return (
1961
- <Box height="560px">
1962
- <Sheet record={record} columns={{
1963
- task: Sheet.column.text(Job, { header: "Task", width: "240px" }),
1964
- start: Sheet.column.date(Job, { header: "Start", width: "96px" }),
1965
- qty: Sheet.column.quantity(Job, { header: "Qty", width: "96px" }),
1966
- }} />
1967
- </Box>
1968
- );
1969
- }}</Reactive>
1970
- ```
1971
-
1972
- ```
1973
- <Sheet record={Record.bind(r)} | data={rows} id="id" | slice={{ slice: Slice.bindRecords(key, { rows, … }) }} 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, one rail over its Slice.bindRecords with the LENS — the `rows` source's narrowing drawn over the record's rows, only the rows it keeps, each at its row number (#1349) — and saved-view tabs over every source's narrowing, 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
1974
- ├─ The frame: ONE toolbar holding every control the sheet has, in this order — the view tabs, the lens's count line (while the `rows` source narrows the rows, #1349), the key search, the rail over its `Slice.bindRecords` and its summary (each source a narrowing hides rows of, named in its own words, #1358), 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 its summary, then the sheet's own steps — the tabs into `+n`, the count line, the strip closing up — 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); where the sheet has a key search, the chip folds last into the search's popover, its views over the box (#1345); and the history item last, to its buttons — below that, where the row is still too wide, the rail's icon drops its caret, so the history and Save stay in the row at a phone's width; 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, each source the library follows whose narrowing could not be read, with Retry, 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, over a record its last save, and over the slice's `rows` source the rows a Save took out of the narrowing. ⌘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
1975
- ├─ Rows — ONE of three sources (two, or none, is refused):
1976
- │ ├─ record — `Record.bind(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
1977
- │ ├─ 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. Rows not read draw as the shared run — the sheet's own rows at its pitch, a flat sheet's real row numbers — and a failure stays where it happened: a window the source cannot read is said once, in its run's first row in view (`Couldn't read rows 201–400`, Retry), its reason on the footer's loading line, 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 loading 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
1978
- │ └─ the `rows` source of `slice` — slice={{ slice: Slice.bindRecords(key, { rows: { source: Data.bindPaged(r, { indexes }), fields, range?, search? }, … }) }} (#1345): the source's record's rows, every one in the record's order, each row's id its record key, a grouped sheet's groups its records; while the source narrows them, the sheet draws the narrowing over them as the LENS (#1349), a filtered spreadsheet — only the rows the narrowing keeps, one after another in the record's order, each at its row number, its number marked; nothing stands between them for the rows it leaves out. e3 places the narrowing's rows from its index alone, and the lens reads only the record's segments that hold matches near the view — a page and one ask of which of its rows the narrowing holds, each — so rows with no match are never read, whatever the record's size; a segment not read yet is one band of its matches at the rows' pitch, so the sheet is as tall as its matches before their rows land and after, and they land where the band stood. The count line says `n matches`, n e3's count. A segment whose rows disagree with where e3 placed the narrowing's is one failed band saying the record changed, with a Retry — never a match the index does not hold. A grouped sheet's lens narrows its groups: a matching group's every line shows. Edits through `onApply={Record.onApply(record, { keyed: true })}`, a Save that takes rows out of the narrowing said in the footer; the key search seeks in the record's order and lists the rows its key finds wherever they are, a row the narrowing leaves out naming the choices that hide it as the rail words them — `· hidden by Status: Ready — picking it clears that filter`, which of them hide it asked of e3 through the record's indexes, `· hidden by the filters` until it says — and a pick of it clears just those choices, every other one kept (every choice of the source, before e3 has said), and goes to the row at its number; a choice cleared so is a change of the rail like any other, a saved view's tab marked changed and Esc putting it back. `record`, `data`, `window` and `entry` beside it are refused, each naming the change
1979
- ├─ Props:
1980
- │ ├─ 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)
1981
- │ ├─ 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`)
1982
- │ ├─ 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
1983
- │ ├─ 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
1984
- │ ├─ 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
1985
- │ ├─ owned (optional) — accessor r => Bool: rows the upstream system owns — no copilot, stamped columns read-only
1986
- │ ├─ 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
1987
- │ ├─ slice (optional) — slice={{ slice: Slice.bindRecords(key, { rows?, <a templates list's source>…, <a tab's source>… }, { presets? }), affordances?, persist? }} (#1345): ONE rail on the toolbar over its sources — `rows` narrows the sheet's rows (above), each templates list's source its cards in the Rows tab, and an author's tab's source that tab's cards; a sheet over `record` or `data` takes a slice of templates sources alone. The bare handle, `Slice.bind`, a single `Slice.bindRecord`, a source nothing names, `affordances` / `persist` outside `slice` and the `brush` affordance (the sheet has no axis) are refused, each naming the change. While `rows` narrows the rows, the sheet draws the narrowing over the record's rows as the lens (above, #1349). Over a keyed paged source the key search seeks 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
1988
- │ ├─ views / activeView (optional) — `views` is a whole-value bind handle of Array<Sheet.Types.RecordView> (`State.bind` keeps them per viewer, `Data.bind` shares them): saved views, each every source's narrowing by the source's name (#1345), as TABS — the pinned whole-sheet tab, which clears every source, `+ TAB` snapshot (named from the sources' searches), each tab's count its `rows` narrowing's through the record's index, the dirty dot when the rail drifts from the tab, × 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), and with a key search last folded into its popover (#1345); 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. The tabs show on a sheet with a `rows` source; a sheet without one takes `views` and shows none
1989
- │ ├─ 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
1990
- │ ├─ 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
1991
- │ ├─ applyMode (optional) — "batch" (default: the history item's Save sends the batch) | "auto" (each ready gesture goes at once, through the same acknowledgement path)
1992
- │ ├─ optimise (optional, #1409) — `Func.bind` of the app's `e3.function` from `Sheet.Types.OptimiseRequest(R)` (`OptimiseRequest(R, K)` over a record keyed otherwise than by String) — the run's number and the rows in view by key as the session holds them, base plus every unapplied draft, the lens's rows read whole — to `Sheet.Types.OptimiseResult(R)`, the rows complete. The Elara eye before the history item: one call per run, the history and every edit locked while it is out, a change of view or tab stopping it. Its answer is diffed by key and recorded as ONE step of the history — Undo in one, Save with everything else — a row added or changed marked cell by cell until Apply (a blank filled an add, a value changed a change, its provenance on hover), the toolbar's count flashing; a result equal to the request records nothing and says so
1993
- │ ├─ 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
1994
- │ ├─ 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
1995
- │ ├─ 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)
1996
- │ ├─ 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
1997
- │ ├─ 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
1998
- │ ├─ footer (optional) — [{ text, tone? }] counts; a paged source adds the one loading line (what the view waits for, or why a read failed, with Retry)
1999
- │ ├─ style (optional) — { gutterWidth } — the sheet fills the box it is given and scrolls its own rows there
2000
- │ └─ 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
2001
- ├─ Panes — optional props, each its own; the examples show every combination (none, a library, an inspector, both):
2002
- │ ├─ 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, each list following its source of the rail — the tab counting what it shows (`Rows 5 of 11`) and, when its sources leave it none, saying so with Clear filters for them; `columns()` — the declared columns, each with its kind and an eye that hides it from the grid per viewer (the last shown stays; a sheet whose library lists no Columns tab hides none); `tab(data, { name, icon?, key, label, meta?, group?, drop?, source? })` — 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, following the rail's `source` it names as the Rows tab does; `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
2003
- │ ├─ templates (optional) — Sheet.templates(templates.read(), { name, group?, values, source }), or a list of them: templates RECORDS (#1345), bound with `Data.bind`, one card per row in the record's key order, each list naming its source of `slice` — a grouped sheet's row templates and group templates two records and two sources, a group template's `values` over the group type; a dropped card is `newRow`'s (`newGroup`'s) defaults with the template's fields over them. A list written in the code, one naming no source of the slice or one it lacks, one naming `rows`, two naming one source, and values over another type are refused, each naming the change
2004
- │ ├─ 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) — an issue on a row the `rows` source's narrowing hides naming the choices that hide it, and a click clearing just those and going to its cell, as a pick of the key search does. `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
2005
- │ └─ 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
2006
- ├─ 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
2007
- ├─ Keyboard (B§6): arrows / ⇧arrows (↓ on the last row appends — on a flat sheet, once a paged source is exhausted) · ⇥ / ⇧⇥ 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 key search — its box, or, folded to its icon, the box in its popover, opened (#1221) — else the row's first 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
2008
- ├─ Localization (#861): every word the sheet says itself — the toolbar and the view tabs, the header, the rows and bands, 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)
2009
- └─ Factories:
2010
- ├─ 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
2011
- ├─ 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
2012
- ├─ 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)
2013
- ├─ Sheet.subRows(R, sources) / Sheet.subRow({ code?, name, chips?, facets?, id? }) — sub rows (see `subRows`); a left-out `code` / `id` is "", `chips` / `facets` []
2014
- ├─ Sheet.library.rows() / columns() / tab(data, config) — the library's tabs; Sheet.templates(rows, { name, group?, values, source }) — a templates record's cards for the Rows tab (#1345); Sheet.field.* — the inspector's hints (east-ui's `Fields`)
2015
- ├─ 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`
2016
- ├─ Sheet.Types.OptimiseRequest(R, K?) / Sheet.Types.OptimiseResult(R, K?) — what the app's optimiser is asked and answers (#1409): `{ run, rows }`, the rows in view by key as the session holds them; `{ rows }`, the rows complete, a new row's key the optimiser's own
2017
- └─ 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 / RecordView / Selection / Counted / Sides / RegisterMember are shared value and wire types.
2018
- ```
2019
-
2020
- #### Drafts and checked application
2021
-
2022
- The row's `StructType` defines completeness, including fields without columns.
2023
- Columns define editing and parsing. Missing optional fields normalize to `none`;
2024
- missing required fields and invalid text block the entire batch. Optional
2025
- `ready.row` / `ready.group` business rules cannot bypass these automatic checks.
2026
-
2027
- ```tsx
2028
- <Sheet data={jobs} id="id"
2029
- columns={{ task: Sheet.column.text(JobType), qty: Sheet.column.integer(JobType) }}
2030
- onUpdate={jobs.write} />
2031
- ```
2032
-
2033
- Here `jobs` is a live `State.bind` or `Data.bind` handle over `ArrayType(JobType)`.
2034
- `onUpdate` reads the latest collection when applying, checks the original batch
2035
- base and writes once. Use `onPatch` for a journal of individual gestures,
2036
- including incomplete drafts, and `onApply` for host transactions. A paged host
2037
- must atomically check its revision, deduplicate the request id and return the
2038
- committed revision. An append-only journal is not an application acknowledgement.
2039
- An unknown outcome retries the same frozen request.
2040
-
2041
- A record's rows are `record`'s: the sheet reads them and commits through the
2042
- record's patch door, every example sheet that writes is bound this way (#1180).
2043
- Rows that are the host's but kept in an e3 record — one entry's Array field,
2044
- read and shaped before the sheet sees them — commit through `Record.onApply`
2045
- over that entry's rows:
2046
-
2047
- ```tsx
2048
- // Package side: export const plans = e3.record("plans", DictType(StringType, Plan), {
2049
- // initial: new Map([["week", { jobs: [] }]]),
2050
- // mutations: (mutation) => ({ patch: mutation.patch() }),
2051
- // });
2052
- const record = $.let(Record.bind(plans));
2053
- const jobs = $.let(record.read().get("week").jobs);
2054
- const onApply = $.const(Record.onApply(record, {
2055
- entry: "week",
2056
- get: East.function([Plan], ArrayType(JobType), (_$, plan) => plan.jobs),
2057
- set: East.function([Plan, ArrayType(JobType)], Plan, (_$, _plan, next) => ({ jobs: next })),
2058
- idField: "id",
2059
- }));
2060
- <Sheet data={jobs} id="id" columns={{ /* … */ }} onApply={onApply} />
2061
- ```
2062
-
2063
- The batch is checked against the rows the edit began from, and the patch
2064
- reaches the entry's rows and nothing else of it; groups, and entries of groups
2065
- and loose rows, commit the same way. A record's own entries as the rows,
2066
- `Record.onApply(record)`, page in key order instead (`recordSheetApply`).
2067
-
2068
- The transaction contract is every editable collection's, not the Sheet's alone
2069
- (#879): east-ui's `Editing.apply` and `Editing.Types.*` — `ChangeSet`,
2070
- `PatchEvent`, `Readiness`, `Origin`, `Draft`, `Entry` and the rest — are the
2071
- very values `Sheet.apply` and `Sheet.Types.*` name, and the Plan's session is
2072
- the same one: a gesture's `origin` names its `resize` and `drop` too. A keyed `Dict` source applies with
2073
- `Editing.apply(DictType(K, E))`: each change names its entry by key (a
2074
- `String` key as it is, any other key by its `.east` text), and a new entry is
2075
- placed `keyOrder`. The east-ui skill documents the contract.
2076
-
2077
- **Draft and editing contracts**
2078
-
2079
- | Signature | Description | Example |
2080
- | --- | --- | --- |
2081
- | `Sheet.Types.Draft(R)` | Each field is missing / value(T) / invalid(String). | `sheetWeeks` |
2082
- | `Sheet.Types.DraftContext(R, D)` | Current draft row, neighbours and optional driver; grouped overload `(G, "rows", D)`. | `sheetWorkshop` |
2083
- | `newRow: fn(NewRow) => Patch(R)` | Explicit defaults for newly inserted drafts, including required hidden fields. | `sheetBatches` |
2084
- | `ready.row: fn(Draft(R), DraftContext(R)) => Readiness` | Synchronous business checks alongside mandatory schema checks. | `sheetWeeks` |
2085
- | `onPatch: fn(PatchEvent(E)) => Null` | Draft contents, placement, origin and readiness once per gesture. | `sheetWeeks` |
2086
- | `onApply: fn(ChangeSet(E)) => ApplyResult` | Complete checked batch; supports async callbacks and safe retries. `Record.onApply` commits it to an e3 record. | `sheetVariants`, `recordSheetApply` |
2087
- | `Sheet.apply(E, "id")` | Applies a checked batch to a collection: the whole batch, or a conflict saying why. | `sheetApplyBatch` |
2088
- | `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) |
2089
- | `Sheet.Types.Entry(G, "rows")` | Groups with their rows beside ungrouped rows, as one union; `Sheet.apply`, `DraftEntry` and `PatchEvent` take it. | `sheetApplyEntries` |
2090
- | 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` |
2091
- | `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` |
2092
-
2093
- Providers receive drafts: test `field.hasTag("value")` before reading
2094
- `field.unwrap("value")`. They can fill a row before its remaining fields are
2095
- complete. Constructors can supply hidden fields; copilot patches target editable
2096
- columns. Typing, paste, fill, drops and accepted suggestions share the
2097
- transaction path and Undo/Redo.
2098
-
2099
- #### Sub rows and column rules
2100
-
2101
- Sub rows show a line's own records (operations, bookings) without giving them
2102
- columns; column rules say what a cell offers, how deep a date reads, and what a
2103
- cell says beyond its value. Rule accessors (`level`, `actual`, `detail`) run in
2104
- the row projection, so they follow the host's rows, not an open edit.
2105
-
2106
- | Signature | Description | Example |
2107
- | --- | --- | --- |
2108
- | `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` |
2109
- | `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` |
2110
- | `options: fn(DraftContext(R, D)) => Option<Array<String>>` | enum / lookup / link: the members a row is offered; `none` = all. | `sheetWeeks` |
2111
- | `date(R, { level: r => DateLevel, actual: r => Option<DateTime> })` | Read the date at the row's level; print the actual once it happened. | `sheetWeeks` |
2112
- | `detail: r => String \| Option<String>` | Text the hover and the strip show beyond the cell's value. | `sheetWeeks` |
2113
- | `members: [{ kind, identified: true, ranged: true }]` | Offer and print runs of consecutive codes as one range. | `sheetWeeks` |
2114
-
2115
- #### The rows, the panes and the frame
2116
-
2117
- | Signature | Description | Example |
2118
- | --- | --- | --- |
2119
- | **The rows** | | |
2120
- | `record: Record.bind(r)` **❗** | A `Dict` record bound with its patch door; its entries are the rows, in key order. | `sheetBasic` |
2121
- | `window: Data.bindPaged(r)` **❗** | The same record's entries, a window at a time; never with `entry`. | `sheetPaged` |
2122
- | `entry: { key, rows: F, id: I }` **❗** | One entry's Array field `F`, in its own order; `I` a `String` field of its rows. | `sheetWeeks` |
2123
- | `entry` + `group: Sheet.group(P, "lines", …)` | `F` holds groups, or `Sheet.Types.Entry(P, "lines")` entries, loose rows between the groups. | `sheetBatches`, `sheetLoose` |
2124
- | `group` over the record's entries | Each entry a group, its lines its Array field. | `sheetWorkshop` |
2125
- | `data` + `id` (+ `onApply` / `onUpdate`) | The host's rows: an array, a bind handle or a paged source. | `sheetVariants` |
2126
- | `slice={{ slice: Slice.bindRecords(key, { rows, … }) }}` + `onApply={Record.onApply(record, { keyed: true })}` **❗** | The `rows` source's record's rows, in the record's order, each row's id its record key (#1345); `record`, `data`, `window` and `entry` beside it are refused. | `sheetWorkshop`, `sheetStress`, `sheetRecordIndexes` |
2127
- | the lens: the `rows` source narrowed **❗** | Its narrowing drawn over the record's rows (#1349), a filtered spreadsheet: only the rows it keeps, one after another, each at its row number, and the count line, its matches — e3 placing them from the index, the lens reading only the segments near the view. | `sheetRecordIndexes` |
2128
- | `record` with `data`, or neither; `id` / `onApply` / `onUpdate` over a record; `entry` / `window` with `data` **❗** | Refused, naming the prop and the fix. | — |
2129
- | **The panes** | | |
2130
- | `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` |
2131
- | `templates: [Sheet.templates(rows, { name, group?, values, source }), …]` **❗** | The Rows tab's cards, each list a templates record naming its source of `slice` (#1345); a list written in the code, or one naming no source, `rows` or another list's source, is refused. | `sheetWorkshop`, `sheetBatches` |
2132
- | `inspector` | The end pane: Details for what is selected, its every field, and Issues. | `sheetWorkshop`, `sheetBatches` |
2133
- | `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` |
2134
- | `fields: { f: Sheet.field.readonly() \| Sheet.field.hidden() \| … }` / `groupFields` **❗** | The inspector form's hints, by field; refused without an inspector. | `sheetWorkshop`, `sheetBatches` |
2135
- | **The frame** | | |
2136
- | the toolbar | Every control the sheet has, one row at every width: the rail folds first, then its summary, then the sheet's own steps, then the key search into its icon and the view tabs into one chip (#1221) — with a key search, last into its popover (#1345); the history item folds last, and below that, at a phone's width, the rail's icon drops its caret, the history and Save staying in the row. ⌘F reaches the key search in either form. | `sheetWorkshop`, `sheetPaged` |
2137
- | `views: State.bind([ArrayType(Sheet.Types.RecordView)], key, [])` **❗** | The saved views, each every source's narrowing by name (#1345), as a bind handle; `onViewsChange` is refused. | `sheetWorkshop`, `sheetStress` |
2138
- | `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` |
2139
-
2140
- Removed with #1216: `<Sheet.View>` and `<Sheet.Builder>` (both `<Sheet>`), a
2141
- builder's `id` (`name`), `onViewsChange` (`views` is a bind handle) and
2142
- `style.height` / `maxHeight` (the sheet fills its box).
2143
-
2144
- Removed with #1345: the bare `slice={slice}`, `data={Slice.rows(slice)}` and
2145
- `window={Slice.rows(slice)}` (the `rows` source of `slice={{ slice }}`),
2146
- `affordances` and `persist` outside `slice`, `Slice.bind` and a single
2147
- `Slice.bindRecord` (`Slice.bindRecords`), `Sheet.Types.View`
2148
- (`Sheet.Types.RecordView`) and templates written in the code (`Sheet.templates`
2149
- over a record) — each refused at build, naming the change.
2150
-
2151
- Changed with #1349: the `rows` source's rows are its record's, every one in the
2152
- record's order, the source's narrowing drawn over them as the lens — where they
2153
- were the narrowing's rows alone, in its index's order. The lens is a filtered
2154
- spreadsheet: it draws only the rows the narrowing keeps, each at its row
2155
- number, with no rows beside them, no gaps and no context switch, and a saved
2156
- view keeps no `context` and no `reveals` — `Sheet.Types.Reveal` is gone. An
2157
- application's own record of saved views changes type with it: a view saved
2158
- before reads no more, and resets.
2159
-
2160
- ### The Flowchart — `<Flowchart>`
2161
-
2162
- `<Flowchart>` is the state-transition flowchart: states as nodes in ORDERED
2163
- phase lanes — its layout derived from the lanes and the links, never from
2164
- coordinates — H/V-routed transition arrows, optional per-link decision
2165
- triggers (lettered diamonds) and evidence-weighted strokes. The dim-ladder
2166
- highlight and the selection grammar are built in, and what is selected shows
2167
- in its inspector. Where the Schematic (below) places items at world
2168
- coordinates, the Flowchart lays its states out itself, for reading a process
2169
- flow.
2170
-
2171
- There is one Flowchart, and it renders in its builder frame wherever it is
2172
- used (#1245): one toolbar — find state, LR · TD, the freshness chip, the rail
2173
- of its one `Slice.bindRecords` (#1346), and where it edits the history item —
2174
- the canvas in main, filling it and scrolling both ways inside it, and the
2175
- footer's counts: over many flows the open flow's name first, where it edits
2176
- the changes waiting on Save, and over a record its last save. Its library
2177
- pane, when `library` lists a tab, holds the tabs it lists, in its order: the
2178
- Flows tab (#1246), state and transition templates — templates records — and
2179
- the author's own cards (#1248, below), each following the source of the rail
2180
- it names (#1346), whose cards drop on the canvas (#1249, below). Its
2181
- inspector, on by default, is the end pane: what is selected, through its form,
2182
- and the open flow's issues (#1250, below). It fills the box it is given and
2183
- draws no border: give it a box of its own height.
2184
-
2185
- Its flows come from one of two sources:
2186
-
2187
- - **`record`** — an e3 record of `Flowchart.Types.Flows`, flows by name, bound
2188
- with its patch mutation: `Record.bind(r)`. The usual
2189
- case: the canvas shows the flow opened last, else `flow`, else the first flow
2190
- by name. A record always holds flows by name — a patch mutation writes
2191
- only keyed records — so a lone flow is a record of one entry, or the host's
2192
- `data`; a record of one flow is refused at build.
2193
- - **`data`** — the host's flows by name or one flow, the value's type picking
2194
- the arm: a value, an expression or a bind handle (`Data.bind`).
2195
- `Flowchart.over(states, { … })` builds one flow from the app's own tables
2196
- through their row mappers; nothing narrows the host's flows (#1346). Read
2197
- only, unless the host gives `onApply`, its commit of the
2198
- flowchart's edits: one patch of the value — over flows by name the open
2199
- flow's insert, update or delete by name, never the whole value replaced;
2200
- over one flow, the flow's own patch — answered as Save is.
2201
-
2202
- A flow is `{ description, lanes, states, links, triggers }` of the row types
2203
- (`Flowchart.Types.Flow`). `Flowchart.values({ [name]: flow })` and
2204
- `Flowchart.value(flow)` write a dataset's value as literals, filling what a
2205
- literal leaves out and refusing at build what would not draw or commit: two
2206
- lanes, states, links or decisions of one key, a state naming a lane the flow
2207
- does not have, a link naming a decision it does not have. A link naming a
2208
- state the flow does not have is kept — it draws as the unresolved ghost.
2209
-
2210
- Every edit is a draft of the open flow's editing session (#1247), each flow
2211
- keeping its own: over a record, and over `data` given `onApply`, the canvas's
2212
- gestures are its — "+ LANE" at the band row's tail, a lane's header
2213
- double-clicked to rename it in place (a click selects the lane, as the user
2214
- 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
2215
- "+ STATE" ghost under a hovered lane, a state double-clicked into its editor
2216
- (a new key rekeys its transitions' ends and the decisions' queues) or dragged
2217
- across lanes, a handle dragged to another state (`canConnect` vetoes a pair;
2218
- a drop on the state it left is its ↻ in-place transition), and Del on the
2219
- selection: a state (with its transitions), several states, a transition, a
2220
- decision, or a lane that holds none — and every edit the inspector makes. Each
2221
- is ONE transaction the history item undoes and redoes — ⌘Z, ⇧⌘Z or ⌘Y from
2222
- anywhere in the frame but a field being typed into — and Save sends the open
2223
- flow's drafts as one commit. Two lanes, states, keyed transitions or decisions
2224
- of one key hold Save off, the history item counting the issue. The flowchart
2225
- takes no callback for an edit.
2226
-
2227
- The tag and its types — `Flowchart.Types` — come from `@elaraai/e3-ui`, and
2228
- the tags around it from `@elaraai/east-ui`. It moved here from east-ui
2229
- (#1243), and its tables became a flow (#1244): a surface that wrote east-ui's
2230
- `<Flowchart states={…} links={…} lanes={…} />` passes the same tables and
2231
- mappers to `Flowchart.over`, as `data`.
2232
-
2233
- ```tsx
2234
- /** @jsxImportSource @elaraai/e3-ui */
2235
- import { East } from '@elaraai/east';
2236
- import { Box, Reactive, UIComponentType } from '@elaraai/east-ui';
2237
- import { Flowchart, Record } from '@elaraai/e3-ui';
2238
- import e3 from '@elaraai/e3';
2239
-
2240
- // The depot's flows, by name: each written as a literal, checked when the package builds.
2241
- export const depotFlows = e3.record("depot_flows", Flowchart.Types.Flows, {
2242
- initial: Flowchart.values({
2243
- "Inbound parcels": {
2244
- description: "From the trailer to the van",
2245
- lanes: [{ key: "intake", label: "Intake" }, { key: "sort", label: "Sort" }, { key: "load", label: "Load" }],
2246
- states: [
2247
- { key: "ARV", label: "Arrived", lane: "intake" },
2248
- { key: "CH*", label: "Sort chutes", lane: "sort", members: 12n },
2249
- { key: "LDD", label: "Loaded", lane: "load" },
2250
- ],
2251
- links: [{ from: "ARV", to: "CH*", trigger: "route" }, { from: "CH*", to: "LDD" }],
2252
- triggers: [{ key: "route", label: "route", owner: "sort-planner" }],
2253
- },
2254
- }),
2255
- mutations: (mutation) => ({
2256
- patch: mutation.patch(),
2257
- }),
2258
- });
2259
-
2260
- const flowchart = East.function([], UIComponentType, _$ => (
2261
- <Reactive>{$ => {
2262
- const flows = $.let(Record.bind(depotFlows));
2263
- return (
2264
- <Box height="480px">
2265
- <Flowchart record={flows} flow="Inbound parcels" library={[Flowchart.library.flows()]} />
2266
- </Box>
2267
- );
2268
- }}</Reactive>
2269
- ));
2270
- ```
2271
-
2272
- One flow from the app's own tables, each an e3 input, through their row
2273
- mappers — read only, as the host gives no `onApply`:
2274
-
2275
- ```tsx
2276
- /** @jsxImportSource @elaraai/e3-ui */
2277
- import { ArrayType, East, StringType, StructType, variant } from '@elaraai/east';
2278
- import { Box, Reactive, UIComponentType } from '@elaraai/east-ui';
2279
- import { Data, Flowchart } from '@elaraai/e3-ui';
2280
- import e3 from '@elaraai/e3';
2281
-
2282
- // The app's own tables: its steps by phase, and the moves between them.
2283
- export const Step = StructType({ code: StringType, name: StringType, phase: StringType });
2284
- export const steps = e3.input("steps", ArrayType(Step), variant("value", [
2285
- { code: "ARV", name: "Arrived", phase: "intake" },
2286
- { code: "SRT", name: "Sorting", phase: "sort" },
2287
- { code: "LDD", name: "Loaded", phase: "dispatch" },
2288
- ]));
2289
- export const Move = StructType({ src: StringType, dst: StringType, kind: Flowchart.Types.Kind });
2290
- export const moves = e3.input("moves", ArrayType(Move), variant("value", [
2291
- { src: "ARV", dst: "SRT", kind: variant("planned", null) },
2292
- { src: "SRT", dst: "LDD", kind: variant("observed", null) },
2293
- ]));
2294
-
2295
- const flowchart = East.function([], UIComponentType, (_$) => (
2296
- <Reactive>{$ => {
2297
- const states = $.let(Data.bind(steps));
2298
- const links = $.let(Data.bind(moves));
2299
- return (
2300
- <Box height="500px">
2301
- <Flowchart
2302
- data={Flowchart.over(states.read(), {
2303
- state: s => ({ key: s.code, label: s.name, lane: s.phase }),
2304
- links: links.read(), link: l => ({ from: l.src, to: l.dst, kind: l.kind }),
2305
- lanes: [{ key: "intake", label: "Intake" }, { key: "sort", label: "Sort" }, { key: "dispatch", label: "Dispatch" }],
2306
- })}
2307
- name="steps"
2308
- />
2309
- </Box>
2310
- );
2311
- }}</Reactive>
2312
- ));
2313
- ```
2314
-
2315
- The host's flows, edited, and committed by the host: Save hands `onApply` the
2316
- session's request id and one patch of the flows — the open flow's insert,
2317
- update or delete by name — which the host commits through a record's patch
2318
- mutation under that id, answering with what e3 said (`flowchartVariants` maps
2319
- every outcome). A write that got no answer throws, so the session's Retry sends
2320
- the same request id again, and e3 answers it with the first write's commit
2321
- rather than writing twice (#1275):
2322
-
2323
- ```tsx
2324
- const flows = $.let(Record.bind(depotFlows));
2325
- const onApply = $.const(East.asyncFunction([StringType, PatchType(Flowchart.Types.Flows)], Editing.Types.ApplyResult, ($2, requestId, patch) => {
2326
- const outcome = $2.let(flows.commit.patch(requestId, patch));
2327
- const answer = $2.let(variant("rejected", [{ entry: "", row: none, field: none, message: "The write was refused" }]), Editing.Types.ApplyResult);
2328
- $2.match(outcome, {
2329
- committed: ($3, done) => { $3.assign(answer, variant("applied", { revision: some(done.stateHash) })); },
2330
- // invalid, failed and timed_out → rejected with their words; conflict → conflict
2331
- transport: ($3, lost) => { $3.error(East.str`The write got no answer, so it may have committed — retry to find out: ${lost.message}`); },
2332
- });
2333
- return answer;
2334
- }));
2335
- <Flowchart data={flows.read()} flow="Inbound parcels" onApply={onApply} library={[Flowchart.library.flows()]} inspector={false} name="host" />
2336
- ```
2337
-
2338
- ```
2339
- <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
2340
- ├─ 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, at its end the rail of its one `Slice.bindRecords` and its summary, naming each source a narrowing hides rows of in its own words (#1346, #1358), 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, its summary after every step of it, 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) — with a rail, LR · TD then folds into that popover, its View, one move, so a phone's row keeps the rail and Save — and the history item last, to its buttons, and below that, where the row is still too wide, the rail's icon drops its caret, the history and Save staying in the row; 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; a source of the rail whose narrowing could not be read, with Retry; 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 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
2341
- ├─ Its flows — ONE of two sources (both, or neither, is refused):
2342
- │ ├─ record — Record.bind(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
2343
- │ └─ 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
2344
- ├─ Flowchart.over(states, { state?, links, link?, lanes, lane?, triggers?, trigger? }) — one Flowchart.Types.Flow from the app's tables:
2345
- │ ├─ states + links + lanes (required) — the three tables (lanes accept a literal [{ key, label? }] array; array order = band order)
2346
- │ ├─ 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.*
2347
- │ └─ 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)
2348
- ├─ 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)
2349
- ├─ A flow's rows:
2350
- │ ├─ 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
2351
- │ └─ 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)
2352
- ├─ Props:
2353
- │ ├─ 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? }
2354
- │ ├─ 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
2355
- │ ├─ slice (optional, #1346) — slice={{ slice: Slice.bindRecords(key, { flows?, <a templates list's source>…, <a tab's source>… }, { presets? }), affordances?, persist? }}: ONE rail at the toolbar's end. Over `record`, its `flows` source — `Data.bindPaged(record, { indexes })` over the same record — narrows the Flows tab, which pages what it narrows the record to, in its index's order, and counts it (`Flows 683 of 2,048`); without one the tab lists the record read whole. When the rail leaves no flow the tab says so (`No flows match the filters`), with Clear filters for `flows` alone; its own search finds a flow by name within the narrowing, never writing the rail (`Search 683 flows by name…`, `680 hidden by filter · Show all`), and says so when the rail's choices block it, naming the filters to clear. The open flow is read by its name whatever the narrowing, its drafts kept, Pending again once it shows; a Save that takes it out of the narrowing confirms by primary reads and says so in the footer (`1 flow left this view`). Each templates list's source narrows that list's cards (`Steps 2 of 5`), and an author's tab's its cards by the key its `key` gives, each with the shared empty state. Over `data` nothing narrows the flows: the slice holds only the sources its lists and tabs name. Refused, each naming the change: `window`, the bare handle, `Slice.bind`, a single `Slice.bindRecord`, a source nothing names, `affordances` outside `slice`, the `brush`, and a `flows` source over `data` (`flowchartRecordIndexes`, `flowchartLibrary`)
2356
- │ ├─ onSelectState / onSelectLink / onSelectTrigger / onTracePath (optional) — click / ⌥-click callbacks (entity keys); Esc restores everything instantly
2357
- │ ├─ canConnect (optional) — fn(from, to) => Boolean: vetoes a pair BEFORE the connect draft snaps, and fails OPEN
2358
- │ ├─ 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
2359
- │ ├─ 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(templates.read(), { name?, icon?, source, label, meta?, group?, drop })` (#1248, #1346) — state templates: a templates RECORD, a `Dict<String, T>` bound with `Data.bind`, one card per row in the record's key order, each keyed by the record's key (the accessors' second argument), following its `source` of the rail — 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(templates.read(), { …, source, 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?, source? })` — the author's own cards from an Array or a `Dict<String, T>`, following the rail's `source` it names by the key its `key` gives, 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>`, a templates list written in the code, naming no source of the slice or one it lacks, naming `flows`, or given a `key`, the state and transition templates naming one source, and a `drop` over another row's patch than its tab's are refused at build, naming the tab
2360
- │ ├─ 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
2361
- │ └─ 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
2362
- ├─ 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
2363
- ├─ 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
2364
- └─ 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(templates, cfg) / transitions(templates, 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)
2365
- ```
2366
-
2367
- | Signature | Description | Example |
2368
- | --- | --- | --- |
2369
- | `<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` |
2370
- | `<Flowchart record={flows} slice={{ slice: Slice.bindRecords(key, { flows: { source: Data.bindPaged(flowsRecord, { indexes }), … } }) }} />` **❗** | The Flows tab pages and counts what the `flows` source narrows the record to (#1346): only nearby cards mount; the open flow and its drafts keep their original name outside the narrowing; the tab's own search finds a flow by name within it; Find state searches the open graph. | `flowchartRecordIndexes` |
2371
- | `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` |
2372
- | `library={[…, Flowchart.library.states(templates.read(), {…, source }), Flowchart.library.transitions(templates.read(), {…, source }), Flowchart.library.tab(rows, {…})]}` **❗** | The library's template and author's tabs (#1248): a templates list is a templates record, one card per row keyed by the record's key, an author's tab an Array or a `Dict<String, T>` — each following the source of the rail it names (#1346) — 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` |
2373
- | 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` |
2374
- | `<Flowchart data={Data.bind(input)} />`, `Flowchart.value({ … })` | One flow of the host's, an input's value, read only. | `flowchartHandover` |
2375
- | `<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` |
2376
- | `<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` |
2377
- | `Flowchart.over`'s `triggers` + `trigger`, a link's `trigger` / `evidence`, `freshness` | Decision diamonds, evidence-weighted strokes and badges, and the freshness chip on the toolbar. | `flowchartDepot` |
2378
- | the frame (#1245) | One toolbar — find state, LR · TD, the freshness chip, the rail and its summary — one row at every width, the rail folding first, its summary after every step of it, then the chip, LR · TD into its chip and find state into its icon, and with a rail LR · TD into find state's popover; 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`, `flowchartRecordIndexes` |
2379
- | `<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` |
2380
- | `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` |
2381
- | `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` |
2382
- | `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` |
2383
- | `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` |
2384
- | `orientation="TD"` | Opens top down; after that LR · TD on the toolbar is the viewer's, kept under `name`. | `flowchartHandover` |
2385
- | `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` |
2386
- | `record` and `data` together, or neither; `onApply` over a record; `window`, the bare slice handle, `Slice.bind`, a single `Slice.bindRecord`, a source nothing names, `affordances` outside `slice`, and a `flows` source over `data` (#1346); a templates list written in the code, naming no source, naming `flows` or given a `key`, and the two templates lists naming one source; `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. | — |
2387
- | `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` |
2388
-
2389
- Between the examples, every pane combination: none (`flowchartHandover`), a
2390
- library (`flowchartVariants`), an inspector (`flowchartDepot`, read only;
2391
- `flowchartDetail`, its own Details), and both (`flowchartFlows`,
2392
- `flowchartLibrary`, `flowchartRecordIndexes`). The indexed example has 2,048 flows
2393
- narrowed through its rail's `flows` source — by description, computed state
2394
- count, lane, decision owner and name — with the Flows tab's own search by name
2395
- within the narrowing, paging and original-ID Save. A composite
2396
- description/state-count index lets those two filters combine, and a
2397
- description/name index lets the tab's search find within a description; lane
2398
- and owner use exact membership.
2399
-
2400
- Removed with #1245: the canvas's eyebrow (its controls are the toolbar's
2401
- items) and `height` / `maxHeight` (the flowchart fills its box).
2402
-
2403
- Removed with #1247: a callback per edit — `onCreateLink`, `onDeleteLink`,
2404
- `onAddLane`, `onRenameLane`, `onDeleteLane`, `onAddState`, `onEditState`,
2405
- `onMoveState` — and `linkMode`, with the event types they took
2406
- (`Flowchart.Types.LinkCreateEvent`, `LaneRenameEvent`, `StateAddEvent`,
2407
- `StateEditEvent`, `StateMoveEvent`, `LinkMode`): the gestures are the
2408
- session's, and each prop is refused at build, naming the remedy. A host that
2409
- heard each gesture commits once, through `onApply`.
2410
-
2411
- Removed with #1250: the hover cards — `stateHover`, `linkHover` and
2412
- `triggerHover` — each refused at build naming the inspector, which shows what
2413
- is selected (ruled by the user on 2026-10-08); and a click on a lane's header
2414
- renaming it: a click selects the lane, and a double-click renames it in
2415
- place.
2416
-
2417
- Removed with #1251: `density`, which the canvas never drew by — it draws at
2418
- one rhythm, the spec's 116×40 cards in their lanes (ruled by the user on
2419
- 2026-10-09) — refused at build.
2420
-
2421
- Removed with #1346: `window={Slice.rows(slice)}` (the `flows` source of
2422
- `slice={{ slice }}`), the slice over the host's tables and its footer readout
2423
- (`N links · narrowed from M · −%`), `affordances` outside `slice`, templates
2424
- read from an Array or an input (templates records) and a templates list's
2425
- `key` — each refused at build, naming the change.
2426
-
2427
- ### The Schematic — `<Schematic>`
2428
-
2429
- `<Schematic>` is the 2D world-coordinate drawing of the app's own records:
2430
- placed items (racks, cooling units, power distribution units), zones (halls,
2431
- cages, hot and cold aisles), links between two items (fibre runs) and nets
2432
- joining many to many (a power distribution unit feeding a row of racks), each
2433
- where its row places it and the canvas scaled to fit the extent. Where the
2434
- Flowchart lays its states out itself, the Schematic draws what the records
2435
- place.
2436
-
2437
- It stores nothing in a shape of its own (#1386): each kind is a record of the
2438
- app's, keyed by String, its fields mapped to the Schematic's roles —
2439
- `Schematic.items`, `zones`, `links` and `nets`, each under a slot of its
2440
- sort's prop. A role names a field of the row: its type is checked when the
2441
- code compiles and again at build, refused naming the role, the field and its
2442
- type (`` `x` names a Float field, or an Option of one — "name" holds .String ``).
2443
- A role the app computes — a second line, a meter, a tone — is an accessor
2444
- `(row, key) => …`, reified once and called per row. A shape is one too
2445
- (#1401): a footprint, or a zone's geometry, is built from the row's own fields
2446
- with `Schematic.circle`, `polygon`, `polyline` or `rect`, so no field of the
2447
- app's record holds a type of the Schematic's — a shape role naming a field is
2448
- refused, naming the accessor to write. The layers are the app's rows as well,
2449
- read through `Schematic.layers` as the Roster reads its lists, an entity's
2450
- `layer` field naming one by its record's key. A gesture writes only the
2451
- fields its roles map: every other field of the row reads back as it was.
2452
-
2453
- A kind's binding says whether it is editable and how it is read; any other
2454
- binding is refused, naming the one to use:
2455
-
2456
- | Read | Editable | Read only |
2457
- | --- | --- | --- |
2458
- | whole | `Record.bind(record)` | `Data.bind(record)` |
2459
- | complete, through its source of the slice | `Record.bind(…)` + `entries: Data.bindPaged(record)` | `Data.bindPaged(record)` |
2460
- | a window at a time, by area — its source lists an area index | the same, its source `Data.bindPaged(record, { indexes: ["by_area", …] })` | the same |
2461
-
2462
- A source of `slice={{ slice: Slice.bindRecords(key, { … }) }}` named after a
2463
- kind's slot reads that kind through it — `Data.bindPaged(record, { indexes })`
2464
- over the kind's record — every row of its narrowing; an indexed read is the
2465
- source, never the kind's record. A kind's details (`Schematic.details`) are
2466
- bound as their kind is read: whole beside a kind read whole, by key beside one
2467
- read through its source — and beside one read by area, by the runs its
2468
- window's cells are of the area index, e3 reading the keys from the index so
2469
- none is sent, each cell's once, at every zoom, so a dot draws its item's
2470
- status as a card does. Bound with their patch door —
2471
- `Record.bind(record)`, with `entries:
2472
- Data.bindPaged(record)` beside a kind read through its source — the inspector
2473
- edits them beside their kind's row; `Data.bind` or `Data.bindPaged` alone
2474
- reads them only.
2475
-
2476
- A kind whose source lists an area index — `index.area({ x, y, width, height,
2477
- at: "centre", cell })` among its record's indexes, the **e3** skill — is read by
2478
- area (#1393), a window at a time: the rows whose box meets the view and a
2479
- margin about it, read from the index alone. Past 5,000 rows in the view it
2480
- draws their density from the index's counts, in the theme's heat steps, the
2481
- footer saying how many it shades; zoomed in, the rows themselves, their
2482
- details read by the runs the window's cells are of the area index. A choice
2483
- of the rail reads through an area index led by its fields, else through the
2484
- one led by none, the rest asked of the window's rows in one request; a source
2485
- whose area indexes are all led by fields, or box the rows otherwise than the
2486
- kind's roles place them, is refused as the kind is read: its read fails, with
2487
- Retry, the reason naming what to declare. Its
2488
- Backlog reads the index's rows with no position, and the Index tab a zone's
2489
- items by the zone's box, each with the drafts in place wherever the window
2490
- goes: a row a draft unplaces is in the Backlog, and one a draft moves is under
2491
- the zone it now stands in. Every edit is a draft by the row's key, whatever
2492
- the window: a row moved off the window it was read in draws where its draft
2493
- places it while the narrowing holds its stored row, and Save writes it
2494
- through the kind's patch door — the index moving it, so a window there reads
2495
- it back (`schematicRecordIndexes`, `schematicRecordIndexesMobile`). A selected
2496
- row stays selected as the window moves off it — Details reads it by its key,
2497
- Del deletes it, and `onSelect` hears no camera move — and is let go of only as
2498
- a read shows it gone (its record holds none of it, it has no position, or the
2499
- narrowing leaves it out), as a draft deletes or unplaces it, or as a layer
2500
- hides or locks it. The drawing's counts take such a kind from its source,
2501
- never its window, and Issues checks the rows read around the view and every
2502
- unsaved change (below).
2503
-
2504
- The canvas draws each kind's rows: an item at its centre, as a card, a
2505
- labelled pin or a dot by the zoom, its footprint about its centre; a zone in
2506
- its box, outlined or hatched, its shape about the box's centre; a link routed
2507
- between its ends, two of one pair fanning into lanes; a net as a bus. An item
2508
- draws as its card only where the card draws whole — one held to the item's
2509
- `width` once that width holds its words — and clear of its neighbours, else as
2510
- a pin, its dot on the item and its words after it, clear of every other
2511
- item's mark, else as a dot (ruled 23 Oct 2026): what an item draws as follows
2512
- where the items stand, never a pan. Fit frames the drawing inside a margin,
2513
- centred, and the zoom reaches in until its smallest item held to its own
2514
- width draws as its card. A kind drawn as its density shades it in the theme's
2515
- five heat steps. Its links and
2516
- nets draw in the Plan's and the Allocation's links look (#1403): cased in the
2517
- paper, in the muted ink or their style's tone, each ending on the edges of the
2518
- items it joins where they draw at the zoom — a card's side, a labelled pin's
2519
- edge, a dot's rim — a link's head where it arrives at its `to` item and a
2520
- net's on each of its destination legs, a caption — its `label` and its
2521
- `metric`, `uplink · 100G` — on a knockout at its middle from the label zoom;
2522
- the one under the pointer lit, and a selected one, in the strong ink, their
2523
- ends ringed. An item kind
2524
- whose `x` and `y` are Options keeps its rows with no position as its backlog,
2525
- drawn nowhere. A record another session commits is drawn again. `onSelect`
2526
- hears the whole selection after each change — items, zones, links and nets
2527
- alike, each a `Schematic.Types.Ref`, `{ kind, key }`, and `[]` once it is
2528
- cleared — one call a change, however many entities it selects, and none for a
2529
- change that leaves the selection as it was. Its frame came with #1387: one
2530
- toolbar — the rail of its `slice`, the tools, the zoom and Fit, Find, the
2531
- steps and, where it edits, the history item — over the canvas, and the
2532
- footer, which says only what is live (below); its library pane with #1389, its
2533
- inspector with #1391, its
2534
- narrowing with #1392 and Find over every item kind's record with #1404
2535
- (below).
2536
-
2537
- Its narrowing (#1392) is the one rail of its `slice`, each source narrowing
2538
- its kind wherever the kind appears: on the canvas, in the library's Backlog,
2539
- its Index and the templates the source names, in the inspector's Choosers and
2540
- what an item is joined to, and in the drawing's counts; a link or a net draws
2541
- only while its ends do. By default a row the narrowing leaves out is hidden:
2542
- its kind reads only what its narrowing holds. With `narrowed="dim"`, or
2543
- `{ show: "dim", … }`, the kind reads every row through its source, never the
2544
- narrowing, so a choice reads no row again, and a row the narrowing leaves out
2545
- draws as context — faded to `opacity` (0.35), drained of colour while
2546
- `desaturate` (on by default), a bare marker with `dot` — as do a link to one
2547
- and a net whose members on a side are all context. Context takes no tap, no
2548
- marquee, no step and no drop, and leaves every list and count but Find's.
2549
- Whatever `show` is, `emphasis` rings each match — `halo`, or `pulse`, which
2550
- breathes — `frame` boxes the matches, and `fit` flies the camera to them when
2551
- the narrowing changes, once what it flies to is read, never as a zoom or a
2552
- Move changes what matches — to a kind read by area's matches by the box its
2553
- narrowing's rows stand in, as its area index's counts answer it. Which rows
2554
- match is each source's shown keys, never a predicate over the rows, and a
2555
- choice builds the Schematic no more.
2556
-
2557
- Find (#1404) seeks every item kind's record by key, never what the canvas
2558
- draws, as the Sheet's Search Records seeks its record: a kind read through
2559
- its source is sought through e3 in its record's own order — a find of its keys
2560
- and a page of the rows its list shows, never the record read whole — and a
2561
- kind read whole in its rows. Its box takes a key's start, a quoted key or a
2562
- range, keys case-sensitive, and asks again as what its lines say moves — a
2563
- record, a narrowing, the layers — never as the canvas reads a window. A pick
2564
- shows the item's key in the box and its place among the matches (`3 of 7`),
2565
- and Next and Previous step on from it, each showing its match; asked again,
2566
- the box keeps a match wherever the matches still hold it. Each line reads
2567
- the item's key, its label where it is not its key, its kind's name, what
2568
- keeps it off the canvas — `on a hidden layer`, or `no position` — and, where
2569
- the rail's filters leave it out, the choices that do, as every builder's
2570
- Search Records names them: `· hidden by Owner: Northwind Media — picking it
2571
- clears that filter`, asked of e3 through the kind's indexes, `· hidden by the
2572
- filters` until it has said — and, under `narrowed="dim"`, which draws the item
2573
- as context, `· dimmed by Owner: Northwind Media — picking it clears that
2574
- filter` and `· dimmed by the filters`. A pick of such an
2575
- item clears just those choices — every choice of its kind's source while e3
2576
- has not said — then goes to it as any pick does, and selects it once the
2577
- narrowing they leave draws it as itself. A pick flies to an item drawn as
2578
- itself and selects it; to one on a hidden layer it flies to where it stands,
2579
- selects nothing, and the footer says why — `A04 is on a hidden layer`; `A06
2580
- has no position: it is in the Backlog`. In a toolbar's row the box is 28px, as
2581
- every builder's key search is there.
2582
-
2583
- The footer says only what is live, and nothing while nothing is (ruled 23 Oct
2584
- 2026): a kind drawn as its density in place of items — a kind read by area
2585
- (#1393) past the rows a window draws — how many rows it shades in the view and
2586
- that zooming in draws them (`Density: 20,000 racks — zoom in to draw them`,
2587
- `about` that many where the view cuts a cell, `the filters not applied` under a
2588
- narrowing its area index doesn't lead); why the last gesture was refused,
2589
- until the viewer's next action — a pan, a zoom, Fit or a fly, a Find pick, or
2590
- a press on the canvas — a resize alone keeping it; each Save's notice of what
2591
- left a source's narrowing; and where Find's last pick landed off the canvas.
2592
- The drawing's counts and each record's last save are the inspector's Details',
2593
- and whether changes wait on Save the history's.
2594
-
2595
- The library (#1389) is the frame's start pane, 272px open, holding the tabs
2596
- `library` lists, in its order, each with its count; its open tab and whether
2597
- it is collapsed are kept per viewer under the Schematic's `id`, collapsed it
2598
- is a rail counting the backlog (else the first tab's cards), and below 560px
2599
- of frame it opens from its rail over the canvas:
2600
-
2601
- - **Templates** — every kind's templates, item, link and net kinds alike, each
2602
- card its template's name over its kind's, grouped by its kind and then its
2603
- template's `group`. Each kind's list follows the source its templates record
2604
- names: the tab counts what it shows (`3 of 5`) and, when the rail leaves a
2605
- list none, says so above the rest, with Clear filters.
2606
- - **Backlog** — every item kind's rows with no position, the drafts in place,
2607
- each card its label, its kind's name and its second line, grouped by its
2608
- kind. A kind read through its source lists the rows its narrowing holds, and
2609
- a narrowing that leaves none says so, with Clear filters.
2610
- - **Index** — the zones nested by containment, each counting the items it
2611
- holds, its nested zones' among them; an open zone lists its items, then its
2612
- nested zones, and the items in no zone come last; a hatched zone is an
2613
- annotation, holding none. A zone's row flies to the zone, selects it and
2614
- opens it; an item's flies to the item and selects it; the zone the viewport
2615
- is in is marked. Its search keeps the items whose label, key or kind's name
2616
- holds it, under their zones. The tree is one tab stop — ↑ ↓ Home End move,
2617
- → opens a zone or goes in, ← closes it or goes up, Enter does a row's click
2618
- — and only the rows in view are mounted.
2619
- - **Layers** — each layer in its order: its swatch in its colour token, else
2620
- its tone, its name and how many entities it holds, with Isolate, Lock and
2621
- Show or Hide, and Show all while a layer is hidden (the layers its author
2622
- hides at first among them; the locks stay). The viewer's choices are kept
2623
- under the Schematic's `id`, over the author's defaults: a hidden layer's
2624
- entities never draw, and a locked one's never select — a tap, the marquee
2625
- and the steps pass them by, and Find and the Index fly to them and select
2626
- nothing — and locking a layer lets go of what is selected on it.
2627
- - **An author's tab** — its cards, each its label and its meta, grouped by its
2628
- `group`, following the source of the rail it names (`Racks 2 of 7`).
2629
-
2630
- A card tab's search finds within that tab alone, never writing the rail; a
2631
- click picks a card and a second lets it go.
2632
-
2633
- The cards drop on the canvas (#1390) through the shared drag engine, as the
2634
- Flowchart's do, each drop one step of the history and the ghost's caption
2635
- saying where the card lands, or why it can't:
2636
-
2637
- - **An item template** lands at the drop point: a new item, its key minted
2638
- unique, its `x` and `y` the point's and every other field the template's
2639
- `values`. The point is written at the screen's resolution, so the caption
2640
- says what is written, after the zone holding it (`Cage A · 12.00, 1.00 m`).
2641
- The item is selected.
2642
- - **A backlog row** lands at the drop point, its `x` and `y` written, and is
2643
- selected.
2644
- - **A link or a net template** lands on a link or a net of its kind: its
2645
- `values` over the row, never its ends, its sides or its key (`onto A03 →
2646
- ODF-1`).
2647
- - **An author's card** — a tab whose `drop` is `(row) => Schematic.patch(R, {
2648
- … })` — lands on an entity of the kind whose row type is `R` and sets those
2649
- fields (`onto A03`). A tab without `drop` doesn't drag.
2650
- - **⏎ on a card** drops it on the selection — an author's card on every
2651
- selected entity of its kind, one step — or a template or a backlog row at
2652
- the view's centre; on a touch screen, a tap on the selected card does the
2653
- same and leaves it selected. Refused, the footer says why.
2654
-
2655
- A drop is refused — the caption red, the cursor not allowed — outside the
2656
- drawing (`Outside the drawing`), with no entity of the card's kind under it
2657
- (`Drop onto a rack`), or on a kind bound read only (`Racks are read only`); a
2658
- locked layer's entities and a hatched zone take no drop, and an item's card
2659
- covers the zones and links beneath it. The canvas marks where a card lands:
2660
- the zone holding the point tinted, a link's or a net's line washed, a ring
2661
- round the marker or the point, and a card in the brand. A drop that changes
2662
- nothing records nothing. While a link or net template is picked in the
2663
- library, Connect draws that kind's links with its values.
2664
-
2665
- Every gesture is one step of one history over a session per record it writes
2666
- (#1388) — each kind bound with its patch door, and each such kind's details —
2667
- as the Roster's and the Allocation's are:
2668
-
2669
- - **Move** — the tool, over an editable item kind — drags the item under the
2670
- pointer, or the selection with it when the item is selected, by the mouse
2671
- or a touch, every centre kept within the extent; Esc mid-drag puts it back.
2672
- - **Connect** — the tool, over an editable link kind, its menu picking the
2673
- kind (the first, until the viewer picks) — drags from an item onto another:
2674
- a link of that kind between them. Shift held on the next drag grows them
2675
- into a net of the first editable net kind whose sides take their items —
2676
- the first drag's two items one each side, an item joined from a member
2677
- downstream, one joined into a member upstream, a member never changing side
2678
- — which absorbs the links the drags drew; with no such kind, each drag adds
2679
- a link. A Shift-drag from a selected link's end starts the session with
2680
- that link.
2681
- - A selected link's **end** drags onto another item, retargeting that end;
2682
- with Connect, a Shift-drag from a selected net's member onto an item
2683
- **extends** the net's destinations.
2684
- - **Del** (or Backspace) deletes the selection: a link or a net; a net's leg,
2685
- its item taken off that side, the net deleted once a side holds none; and
2686
- items, with every link and every net leg naming one. Refused, in the
2687
- footer's words, when a link or a net bound read only names an item it
2688
- would delete (`A01 isn't deleted: Fibre run u1 names it, and is read only`).
2689
-
2690
- `canConnect` is asked of each pair a draft would join, as a
2691
- `Schematic.Types.Candidate` — the slot of the link or net kind the gesture
2692
- writes, and its two items — and answers `none`, which allows it, or the
2693
- refusal's words; a pair whose end or side holds no item of that slot is
2694
- refused the same way (`Fibre run can't end at PDU-B`). A refused draft never
2695
- snaps: the item rings danger, the draft says why in the drag caption, and
2696
- letting go records nothing. A gesture writes only the fields its roles map —
2697
- an item's `x` and `y`, a link's ends, a net's sides — every other field of the
2698
- row as it was; a new link or net is made under a key minted unique
2699
- (`crypto.randomUUID()`), its other fields its type's default. The canvas draws
2700
- the drafts where Save would leave them; a draft of a row the rail's narrowing
2701
- leaves out waits in its session until the rail lets it back, and a new row
2702
- draws always. Undo and Redo — the history item, or ⌘Z, ⇧⌘Z and ⌘Y anywhere in
2703
- the frame but a field being typed into — step through the gestures in the
2704
- order they were made, whatever their kind; Discard drops every draft; Save
2705
- sends each record's changes as its own request through its patch door,
2706
- checked against what its drafts began from: one record's conflict or refusal
2707
- keeps its drafts under a banner titled with its kind's name, the others'
2708
- commits standing, and a write with no answer turns Save into Retry, which
2709
- resends the same request. After a Save the footer says what left each kind's
2710
- narrowing. A kind bound read only, and every
2711
- kind under `readOnly`, takes no gesture; with nothing editable there is no
2712
- history item.
2713
-
2714
- The inspector (#1391), given `inspector`, is the frame's end pane, 320px open:
2715
- its tabs Details and Issues, Issues with its count; collapsed, a rail counting
2716
- the issues and naming what is selected. Whether it is collapsed, and its open
2717
- tab, are kept per viewer under the Schematic's `id`, and below 560px of frame
2718
- it opens from its rail over the canvas. Enter, or a double-click on an
2719
- entity, opens what is selected in Details. Details draws each field through
2720
- the shared form, by the input its type takes — a field the drafts changed
2721
- tinted, the head's chip Pending (New for a row its record holds none of):
2722
-
2723
- - **An item** — its kind's form over the fields no role writes (the kind's
2724
- `fields`, `Fields` hints over its row), or the kind's own `inspector` in its
2725
- place; its details record's form, or the details' own; its position, `x`
2726
- and `y`, with Unplace where the kind keeps a backlog; Delete; and what it is
2727
- joined to, each link and net a control that selects it.
2728
- - **A zone** — its form.
2729
- - **A link** — its ends, each a Chooser over the items of the slots its role
2730
- names, and its form; Delete.
2731
- - **A net** — its sides, each tags over its slot's items' keys, a side never
2732
- emptied (Delete takes the net), and its form; Delete. **A net's leg** — the
2733
- stub a tap selected — its item, and Remove, which takes it off its side.
2734
- - **Several** — how many of each kind, and Delete.
2735
- - **Nothing** — the drawing's counts, and each record's last save with who
2736
- made it. A kind read by area is counted from its source's indexes, never its
2737
- window, its drafts laid over the count and a placeholder while it is read;
2738
- what no read can count is named on a line of its own, with why (`Links not
2739
- counted: what they join is read as the view moves`).
2740
-
2741
- Every edit is one step of the history: a field through its record, an own
2742
- Details' `update(edited)` with the whole row, a position, the ends or the
2743
- sides through the kind's roles, and Delete as Del. Read only — a kind bound
2744
- read only, or `readOnly` — every field is printed and none edits, an own
2745
- Details giving way to the form. Issues lists the drawing's issues — an item
2746
- outside the drawing, a shape reaching past its box, a colour naming no theme
2747
- colour, a link or a net naming an item no kind holds — and its sessions': a
2748
- drafted row the kind's `ready` refuses, which holds Save, and a Save refused
2749
- or in conflict. Each issue selects what it names and flies to it. Over a kind
2750
- read by area, Issues checks the rows read around the view and every unsaved
2751
- change, and one line says the kind's other rows are checked only as the view
2752
- reaches them (`Racks out of view are checked only as the view reaches them`).
2753
-
2754
- Below 480px of main (#1394) — a phone, or a narrow pane in a wide window — the
2755
- canvas pans with one finger, pinches with two and selects with a tap, and
2756
- nothing drags: the View's tools hold no Move or Connect, no library card
2757
- drags, the canvas is no drop cell and a selected link draws no handles.
2758
- Details takes the gestures' place, beside an item's `x` and `y`, a link's
2759
- ends, a net's sides and Delete:
2760
-
2761
- - **Connect to…** — on an item, a Chooser of the items a link may end at,
2762
- beside the link kind while more than one editable kind starts at the item:
2763
- a choice records the link as a drag of Connect would, a picked template's
2764
- values with it.
2765
- - **Place** — a Backlog card picked shows its row in Details, `Not placed`,
2766
- and Place puts it at the view's centre, selected; a tap on the selected card
2767
- does the same.
2768
-
2769
- Every route that connects — Connect to…, a link's ends, a net's sides — is
2770
- held to `canConnect`, its words said in the footer. The layout follows main's
2771
- width, not the window's: a box narrowed and widened again keeps its selection
2772
- and its drafts (`schematicRecordIndexesMobile`; `schematicDataCentre` on a
2773
- phone).
2774
-
2775
- ```tsx
2776
- /** @jsxImportSource @elaraai/e3-ui */
2777
- import { DictType, East, FloatType, StringType, StructType } from '@elaraai/east';
2778
- import { Box, Reactive, UIComponentType } from '@elaraai/east-ui';
2779
- import { Data, Schematic } from '@elaraai/e3-ui';
2780
- import e3 from '@elaraai/e3';
2781
-
2782
- // The app's racks: a record keyed by String — each rack's centre, box, name, model and power.
2783
- export const FloorRack = StructType({ name: StringType, x: FloatType, y: FloatType, w: FloatType, h: FloatType, model: StringType, kw: FloatType, capacity: FloatType });
2784
- export const floorRacks = e3.record("floor_racks", DictType(StringType, FloorRack), {
2785
- initial: new Map([
2786
- ["A01", { name: "A01", x: 2.4, y: 2.9, w: 3.2, h: 1.2, model: "42U · 8 kW", kw: 5.2, capacity: 8.0 }],
2787
- ["A02", { name: "A02", x: 6.0, y: 2.9, w: 3.2, h: 1.2, model: "42U · 8 kW", kw: 7.4, capacity: 8.0 }],
2788
- ]),
2789
- });
2790
-
2791
- const floor = East.function([], UIComponentType, (_$) => (
2792
- <Reactive>{$ => {
2793
- const racks = $.let(Data.bind(floorRacks)); // read only, and read whole
2794
- return (
2795
- <Box height="440px">
2796
- <Schematic id="floor" extent={{ width: 18, height: 12 }} scaleUnit="m"
2797
- items={{ racks: Schematic.items(racks, {
2798
- name: "Rack", icon: "server", x: "x", y: "y", width: "w", height: "h", label: "name",
2799
- sublabel: (r) => r.model,
2800
- meter: (r) => ({ value: r.kw, max: r.capacity }),
2801
- }) }} />
2802
- </Box>
2803
- );
2804
- }}</Reactive>
2805
- ));
2806
- ```
2807
-
2808
- A floor over several records, its racks editable and read through their
2809
- source of the rail, their loads a details record keyed as they are, edited in
2810
- the inspector, their templates a record of their own, its cooling units round by their own radius,
2811
- its fibre trunks a net kind a Shift session grows runs into, its layers a
2812
- record of systems, its tenants an author's tab whose cards set a rack's owner,
2813
- what is selected kept by the host and a run between two frames refused in the
2814
- veto's words (`schematicDataCentre`):
2815
-
2816
- ```tsx
2817
- // Inside Reactive: the racks through their patch door, read by key beside their source of the rail.
2818
- const racks = $.let(Record.bind(dcRacks));
2819
- const rackEntries = $.let(Data.bindPaged(dcRacks)); // one rack by its key
2820
- const loads = $.let(Record.bind(dcRackLoads)); // the racks' loads, edited in the inspector
2821
- const loadEntries = $.let(Data.bindPaged(dcRackLoads)); // by key, beside a kind read through its source
2822
- const frames = $.let(Data.bind(dcFrames));
2823
- const cooling = $.let(Record.bind(dcCooling));
2824
- const areas = $.let(Data.bind(dcAreas)); // read only, and read whole
2825
- const fibre = $.let(Record.bind(dcFibre));
2826
- const trunks = $.let(Record.bind(dcTrunks)); // none yet: a Shift session grows one
2827
- const systems = $.let(Data.bind(dcSystems)); // the layers: a record of the app's
2828
- const rackTemplates = $.let(Data.bind(dcRackTemplates));
2829
- const owners = $.let(Data.bind(dcOwners)); // the tenants: an author's tab whose cards set a rack's owner
2830
- // coolingDetails: a cooling unit's own Details — East.function([DcCooling, FunctionType([DcCooling], NullType)], UIComponentType, …)
2831
- // The whole selection after each change, each entity by its kind's slot and key, kept where the app reads it.
2832
- const selected = $.let(State.bind([ArrayType(Schematic.Types.Ref)], "ops.floor.selected", []));
2833
- const onSelect = $.const(East.function([ArrayType(Schematic.Types.Ref)], NullType, ($2, refs) => { $2(selected.write(refs)); }));
2834
- // Two frames are joined by a cross-connect, never a fibre run: the veto's words refuse the pair.
2835
- const canConnect = $.const(East.function([Schematic.Types.Candidate], OptionType(StringType), ($2, candidate) => {
2836
- const reason = $2.let(none, OptionType(StringType));
2837
- $2.if(candidate.from.kind.equal("network").and(() => candidate.to.kind.equal("network")), ($3) => {
2838
- $3.assign(reason, some("Two frames are joined by a cross-connect"));
2839
- });
2840
- return reason;
2841
- }));
2842
- // One rail: the racks by name, hall and owner, and their templates by group.
2843
- const slice = $.let(Slice.bindRecords("ops.floor", {
2844
- racks: { source: Data.bindPaged(dcRacks, { indexes: ["racks_by_name", "racks_by_hall", "racks_by_owner"] }), search: ["name", "owner"],
2845
- fields: { name: { label: "Rack" }, hall: { label: "Hall", hints: ["Cage A"] }, owner: { label: "Owner", hints: ["Harbour Labs"] } } },
2846
- rackTemplates: { source: Data.bindPaged(dcRackTemplates, { indexes: ["rack_templates_by_group"] }), fields: { group: { label: "Group", hints: ["Racks"] } } },
2847
- }));
2848
- <Schematic id="floor" inspector extent={{ width: 28, height: 14 }} scaleUnit="m" slice={{ slice }} narrowed="dim"
2849
- onSelect={onSelect} canConnect={canConnect}
2850
- items={{
2851
- racks: Schematic.items(racks, {
2852
- name: "Rack", icon: "server", x: "x", y: "y", width: "w", height: "h", label: "name", layer: "system", entries: rackEntries,
2853
- details: Schematic.details(loads, { // what each card draws from the rack's load
2854
- entries: loadEntries,
2855
- meter: (l) => ({ value: l.kw, max: l.capacity }),
2856
- status: { field: "alarm", cases: {
2857
- ok: { label: "OK", tone: variant("success", null), ring: false },
2858
- hot: { label: "Hot", tone: variant("danger", null), ring: false },
2859
- } },
2860
- }),
2861
- templates: Schematic.templates(rackTemplates.read(), { // every field of a rack but x and y
2862
- name: (t) => t.name, group: (t) => some(t.group), values: (t) => t.values, source: "rackTemplates",
2863
- }),
2864
- }),
2865
- network: Schematic.items(frames, { name: "Network frame", icon: "network-wired", x: "x", y: "y", width: "w", height: "h", label: "name", layer: "system" }),
2866
- cooling: Schematic.items(cooling, {
2867
- name: "Cooling unit", icon: "fan", x: "x", y: "y", width: "w", height: "h", label: "name", layer: "system",
2868
- footprint: (c) => some(Schematic.circle(c.radius)), // a circle of the unit's own radius, about its centre
2869
- inspector: coolingDetails, // its own Details, in place of its form
2870
- }),
2871
- }}
2872
- zones={{ areas: Schematic.zones(areas, {
2873
- name: "Area", icon: "vector-square", x: "x", y: "y", width: "w", height: "h", label: "name", layer: "system",
2874
- pattern: (a) => a.kind.match({ // outlined or hatched by what the area is
2875
- room: (_$) => Schematic.outline(), cold: (_$) => Schematic.hatch({ tone: "brand" }), hot: (_$) => Schematic.hatch({ tone: "warning" }),
2876
- }),
2877
- }) }}
2878
- links={{ fibre: Schematic.links(fibre, {
2879
- name: "Fibre run", icon: "bolt", layer: "system", via: "path", // an Array of { x, y } Floats field
2880
- from: { field: "from", of: { rack: "racks", frame: "network" } }, to: { field: "to", of: { rack: "racks", frame: "network" } },
2881
- label: (f) => f.label,
2882
- style: (f) => f.cable.match({ fibre: (_$) => Schematic.solid(), logical: (_$) => Schematic.dashed() }),
2883
- }) }}
2884
- nets={{ trunks: Schematic.nets(trunks, { // racks to a frame: what a Shift session grows its runs into
2885
- name: "Fibre trunk", icon: "diagram-project", layer: "system",
2886
- sources: { field: "racks", of: "racks" }, destinations: { field: "frames", of: "network" }, // Array<String> fields of keys
2887
- label: (t) => t.label,
2888
- }) }}
2889
- layers={Schematic.layers(systems.read(), { // a layer per system, an entity's `layer` naming it by key
2890
- label: (s) => s.label, color: (s) => some(s.colour), order: (s) => s.order, locked: (s) => s.fixed, opacity: (s) => s.dim,
2891
- })}
2892
- library={[Schematic.library.templates(), Schematic.library.backlog(), Schematic.library.index(), Schematic.library.layers(),
2893
- Schematic.library.tab(owners.read(), { // a card dropped on a rack sets its owner
2894
- name: "Owners", icon: "building", label: (o) => o.name, meta: (o) => some(o.contact),
2895
- drop: (o) => Schematic.patch(DcRack, { owner: o.name }),
2896
- })]} />
2897
- ```
2898
-
2899
- ```
2900
- <Schematic extent={{ width, height }} items={{ <slot>: Schematic.items(record, { … }) }} /> — the 2D world-coordinate drawing of the app's own records: a kind per record, under its slot
2901
- ├─ Props:
2902
- │ ├─ extent (required) — the drawing's world bounds, { width, height }, each a positive number of world units; the canvas fits them
2903
- │ ├─ items (required) — the item kinds, by slot, one at least: Schematic.items(record, { name, icon, x, y, label, width?, height?, footprint?, layer?, sublabel?, metric?, meter?, status?, tone?, color?, weight?, fillOpacity?, details?, templates?, entries?, fields?, inspector?, ready? }) — `x` and `y` Float fields, the item's centre, or both Options of Float: a row with neither has no position, the kind's backlog, drawn nowhere; `width` and `height` Float fields, its box about its centre; `footprint` an accessor `(row, key) => Option<Schematic.Types.Geometry>` built from the row's own fields with Schematic.circle / polygon / polyline / rect, drawn about its centre, refused without the box or naming a field; `label` a String field, or an accessor; `icon` a Font Awesome solid icon, or an accessor; `layer` a String field naming a layer by its record's key; `status: { field, cases }` a variant field, a Status per case; `fields` the inspector form's hints over the fields no role writes (`Fields`); `inspector` the kind's own Details, fn(R, fn(R) => Null) => UIComponentType, in place of its form; `ready` the app's check of a drafted row, fn(R, String) => Editing.Types.Readiness, its refusal listed in Issues and holding Save — each typed over the kind's own row; the rest accessors `(row, key) => …`
2904
- │ ├─ zones (optional) — the zone kinds, by slot: Schematic.zones(record, { name, icon, x, y, width, height, label, pattern?, geometry?, layer?, tone?, color?, fillOpacity?, weight?, details?, entries?, fields?, inspector?, ready? }) — `x`, `y`, `width` and `height` the Float fields of its box, its top-left corner and its size; `pattern` an accessor, outline (the default) or hatch — a hatched zone is an annotation, holding no items and taking no tap; `geometry` an accessor `(row, key) => Option<Schematic.Types.Geometry>` built from the row's own fields, drawn about its box's centre, refused naming a field. A zone takes no templates and no gesture on the canvas
2905
- │ ├─ links (optional) — the link kinds, by slot: Schematic.links(record, { name, icon, from: { field, of }, to: { field, of }, via?, label?, metric?, style?, route?, layer?, details?, templates?, entries?, fields?, inspector?, ready? }) — an end is a String field holding a key of the item slot `of` names, or a variant of String cases with an item slot per case (`of: { rack: "racks", frame: "network" }`) — never an Option: a link has both its ends; `via` an `Array` of `{ x, y }` Floats field, its waypoints
2906
- │ ├─ nets (optional) — the net kinds, by slot: Schematic.nets(record, { name, icon, sources: { field, of }, destinations: { field, of }, via?, label?, metric?, style?, route?, layer?, details?, templates?, … }) — each side a `Set<String>` or `Array<String>` field of keys of the item slot `of` names; drawn as a bus — a header bar over each side of many members, a stub per member, the trunk between them, a dot only where a tap joins a bar; a press on the trunk, a bar or a junction selects the net wherever its bus draws, one on a stub its leg
2907
- │ ├─ scaleUnit (optional) — the scale bar's unit
2908
- │ ├─ slice (optional) — slice={{ slice: Slice.bindRecords(key, { <a kind's slot>?, <a templates list's or a tab's source>? }, { presets? }), affordances?, persist? }}: ONE rail, each source named after what it narrows — a kind's slot, that kind, read complete through it, or a window at a time where it lists an area index; a templates list's or a tab's, its cards. The brush is refused: a 2D canvas has no axis
2909
- │ ├─ narrowed (optional) — how a row the narrowing leaves out draws: "hide" (the default — its kind reads only what its narrowing holds), "dim" (its kind reads every row; what the narrowing leaves out draws as context), or { show, opacity? (0.35), desaturate? (on), dot?, emphasis?: "halo" | "pulse", frame?, fit? } — `emphasis`, `frame` and `fit` take the matches whatever `show` is
2910
- │ ├─ layers (optional) — Schematic.layers(rows, { label, order?, tone?, color?, visible?, locked?, opacity? }): the app's own rows, a `Dict` keyed by String (a record's `read()`), each row a layer under its key, through accessors `(row, key) => …` as the Roster's lists are — in their `order`, lowest first, then key order; `color` an Option of a theme colour token over `tone`; `visible`, `locked` and `opacity` the author's defaults, which the viewer's choices in the Layers tab override. An entity's `layer` field names one by its key; a locked layer's entities never select, a hidden one's never draw
2911
- │ ├─ library (optional) — the library pane's tabs, in order, each over every kind as the Calendar's are: Schematic.library.templates() (every kind's templates, each kind's under its name) · backlog() (every item kind's rows with no position, each kind's under its name) · index() (the zones, with zone kinds) · layers() (with layers) · tab(rows, { name, icon?, label, meta?, group?, drop?, source? }) (`drop` a `Schematic.patch(R, …)` over one kind's row type: the fields a card dropped on an entity of that kind sets); each listed once
2912
- │ ├─ inspector (optional) — `inspector` (true) shows the end pane, 320px: Details of what is selected and Issues (below); left out, or `false`, no pane, as the Plan's. A kind's own Details is its kind's `inspector`, its details' their own `inspector`
2913
- │ ├─ readOnly / grid / minimap / id (optional) — every kind read only, taking no gesture; the metric grid (on); the minimap (from 25 items); `id` keeps the Schematic's panes, layers and tools apart when one surface holds two, as the Plan's does
2914
- │ ├─ canConnect (optional) — fn(Schematic.Types.Candidate) => Option<String>: asked of each pair a connect drag would join — `{ kind, from, to }`, the slot of the link or net kind it writes and its two items, each a `Schematic.Types.Ref` — before the draft snaps; `none` allows it, and words refuse it — the draft says them in its caption, and letting go records nothing; a veto that throws allows the pair and logs it
2915
- │ └─ onSelect (optional) — fn(Array<Schematic.Types.Ref>) => Null: the whole selection after each change — items, zones, links and nets alike, each { kind: its slot, key: its row's key }, `[]` once cleared — one call a change, none for a change that leaves it as it was
2916
- ├─ Editing (#1388) — every gesture ONE step of one history over a session per record it writes, each kind bound with its patch door and each such kind's details: Move (the tool, over an editable item kind) drags the item under the pointer, or the selection with it, every centre kept within the extent, Esc mid-drag putting it back; Connect (the tool, over an editable link kind, its menu picking the kind) drags from an item onto another, a link of that kind, and Shift held on the next drag grows the drags into a net of the first editable net kind whose sides take their items, absorbing their links (with none, each drag adds a link); a selected link's end drags onto another item; with Connect, a Shift-drag from a selected net's member extends its destinations; Del or Backspace deletes the selection — a link, a net, a net's leg, items with every link and net leg naming one — refused in the footer's words where a link or a net bound read only names an item it would delete. An end or a side holding no item of a slot refuses the pair as `canConnect` does (`Fibre run can't end at PDU-B`). A gesture writes only the fields its roles map; a new link's or net's key is minted unique (`crypto.randomUUID()`), its other fields their type's defaults. The canvas draws the drafts where Save would leave them; a draft of a row the narrowing leaves out waits in its session, and a new row draws always. The history item ends the toolbar — Undo, Redo, Discard and Save, and ⌘Z, ⇧⌘Z and ⌘Y anywhere in the frame but a field being typed into; Save sends each record's changes as its own request through its patch door, one record's conflict or refusal kept under a banner titled with its kind's name while the others' commits stand, a write with no answer turning Save into Retry, the same request. After a Save the footer says what left each kind's narrowing
2917
- ├─ Drops (#1390) — each card dropped on the canvas ONE step of the history, the ghost's caption saying where it lands or why it can't: an item template adds an item at the point (its key minted, its `x` and `y` the point's at the screen's resolution, every other field the template's `values`), selected; a backlog row is placed at the point, selected; a link or net template gives a link or a net of its kind its `values`, never its ends, sides or key; an author's card sets its `drop`'s `Schematic.patch` on an entity of that patch's kind. ⏎ on a card — on a touch screen a tap on the selected card — drops it on the selection (an author's card on every selected entity of its kind) or a template or backlog row at the view's centre, refused in the footer's words. Refused outside the drawing, with no entity of the card's kind under it, or on a kind bound read only; a locked layer's entities and a hatched zone take none, and an item's card covers the zones and links beneath it. A picked link or net template gives Connect its values
2918
- ├─ Inspector (#1391) — the end pane, its tabs Details and Issues (Issues with its count), opened on Details by Enter or a double-click on an entity: Details through the shared form, each field by the input its type takes, a field the drafts changed tinted and the head's chip Pending (New for a row its record holds none of) — an item's kind's form over the fields no role writes, or the kind's own `inspector`, its details' form or own Details, its position (`x`, `y`) and Unplace (a kind with a backlog), Delete, and what it is joined to, each selecting it; a zone's form; a link's ends as Choosers over the items of their slots, its form, Delete; a net's sides as tags over its slot's keys (a side never emptied: Delete takes the net), its form, Delete; a net's leg, its item and Remove; several, how many of each kind, and Delete; nothing, the drawing's counts — a kind read by area counted from its source's indexes, never its window, a line naming what no read can count — and each record's last save with who made it — each edit ONE step of the history; read only, every field printed. Issues: an item outside the drawing, a shape past its box, a colour naming no theme colour, a link or net naming an item no kind holds, a drafted row `ready` refuses (holding Save), a Save refused or in conflict — each selecting what it names; over a kind read by area, the rows read around the view and every unsaved change, one line saying its rows out of view are checked only as the view reaches them
2919
- ├─ Narrowing (#1392) — each source of the rail narrows its kind on the canvas, in the Backlog, the Index and the templates it names, in the inspector's Choosers and what an item is joined to, and in the drawing's counts; a link or a net draws only while its ends do. Hidden by default; dimmed, its kind reads every row and draws what the narrowing leaves out as context — faded, greyed or a bare marker, a link to it and a net all of whose members on a side are it among it — which selects by no path and counts nowhere. A match — a row its source's shown keys hold — wears `emphasis` (a ring on its card or marker, an edge on a zone, a halo under a link's or a net's line), `frame` boxes two or more, and `fit` flies the camera to them when the narrowing changes, once what it flies to is read, never as a zoom or a Move changes what matches — a kind read by area's by the box its narrowing's rows stand in, from its area index's counts. A draft the narrowing leaves out waits in its session, hidden, or draws where its draft has it, dimmed; Save sends it either way
2920
- ├─ Reading by area (#1393) — a kind whose source lists index.area({ x, y, width, height, at: "centre", cell }): a window at a time, the rows whose box meets the view and its margin, read from the index alone; past 5,000 rows in view their density from the index's counts, the footer saying how many it shades (`Density: 20,000 racks — zoom in to draw them`); its details by the runs the window's cells are of the index; a choice of the rail through an area index led by its fields, else the one led by none, the rest asked of the window's rows; its Backlog through the index's rows with no position. Refused as the kind is read, its read failing with Retry: area indexes all led by fields, or one boxing the rows otherwise than the kind's roles place them, the reason naming what to declare. A draft is kept by the row's key whatever the window, drawn where it places its row while the narrowing holds its stored row — the Backlog listing a row it unplaces, the Index a row it moves under the zone it now stands in — and Save writes it through the kind's patch door. A selected row stays selected off the window — Details reads it by its key, Del deletes it, `onSelect` hears no camera move — until a read shows it gone, a draft deletes or unplaces it, or a layer hides or locks it. The drawing's counts take the kind from its source, never its window
2921
- ├─ Narrow (#1394) — below 480px of main: one finger pans, two pinch, a tap selects, and nothing drags — no Move or Connect among the View's tools, no library card drags, no drop cell, no link handles. Details takes the gestures' place: an item's Connect to… (a Chooser of the items a link may end at, the link kind beside it while several editable kinds start at the item) and a Backlog card's Place (at the view's centre), beside x and y, a link's ends, a net's sides and Delete, every route that connects held to `canConnect`; a resize keeps the selection and the drafts
2922
- └─ Factories:
2923
- ├─ Schematic.items / zones / links / nets(record, config) — the kinds · Schematic.details(record, { status?, meter?, metric?, sublabel?, fields?, inspector?, entries? }) — a kind's details · Schematic.templates(rows, { name, group?, icon?, values, source }) — a kind's templates record, `values` every field but what a drop places · Schematic.layers(rows, config) — the layers
2924
- ├─ Schematic.circle(r) / .polyline(verts, { width? }) / .polygon(verts) / .rect() — geometry about the entity's anchor, each vertex an offset from it: the row's own points, `{ x, y }` (no bulge) or `{ x, y, bulge }`; a radius and a width a Float of the row's
2925
- ├─ Schematic.outline() / .hatch() — zone patterns · Schematic.solid() / .dashed() — link and net styles
2926
- └─ Schematic.patch(R, { … }) — a patch over a kind's row type, what an author's card dropped on an entity sets · Schematic.Types.* — the value types the accessors return, and what the host hears (Ref, Candidate)
2927
- ```
2928
-
2929
- | Signature | Description | Example |
2930
- | --- | --- | --- |
2931
- | `items={{ racks: Schematic.items(Data.bind(racks), { name, icon, x, y, width?, height?, label, … }) }}` **❗** | An item kind over the app's record, read only and read whole; its card's second line and bar from accessors. A role naming a field the row lacks, or one of another type, is refused, naming the role, the field and its type. | `schematicFloor` |
2932
- | `Schematic.items(Record.bind(r), { …, entries: Data.bindPaged(r) })` + a source of `slice` named after its slot **❗** | Editable, read complete through its source. `Data.bind` there, or a `Record.bind` without `entries`, is refused, naming the binding to use. | `schematicDataCentre` |
2933
- | `x` / `y` Options of Float | The rows with no position are the kind's backlog: drawn nowhere, and listed by `Schematic.library.backlog()`. | `schematicDataCentre` |
2934
- | `slice={{ slice: Slice.bindRecords(key, { racks: { source: Data.bindPaged(racks, { indexes }) }, … }) }}` · `narrowed="dim"` **❗** | One rail (#1392): each source narrows its kind everywhere it appears — the canvas, the Backlog, the Index, the templates it names, the inspector's Choosers and the drawing's counts — a link or a net only while its ends draw. Hidden by default, the kind reading only its narrowing; `dim` reads every row and draws what the narrowing leaves out as context, faded and greyed, never selected. `emphasis`, `frame` and `fit` take the matches whatever `show` is. | `schematicDataCentre` |
2935
- | a kind's source listing `index.area(…)`, beside area indexes led by the rail's fields **❗** | Read by area, a window at a time from the index alone; past 5,000 rows in view their density, the footer saying how many; drafts kept by key wherever the window goes, and Save read back through the index; a selected row kept off the window, read by its key; the drawing's counts its source's. Area indexes all led by fields, or one boxing the rows otherwise than the kind's roles, are refused, naming what to declare. | `schematicRecordIndexes` |
2936
- | below 480px of main | Nothing drags; Details' Connect to… and the Backlog card's Place take the gestures' place, beside an item's `x` and `y`, a link's ends and a net's sides, each held to `canConnect`. | `schematicRecordIndexesMobile`, `schematicDataCentre` |
2937
- | an editable kind, and no `library` or `inspector` | The frame is its toolbar — the tools, Move among them, and the history — its canvas and its footer; every gesture still one step Save writes. | `schematicHandover` |
2938
- | `footprint: (u) => some(Schematic.circle(u.radius))` + `width` / `height`; `Schematic.polygon` / `.circle` / `.polyline` **❗** | An accessor over the row's own fields, returning an `Option<Schematic.Types.Geometry>`: geometry about the item's centre, or a zone's `geometry` about its box's centre, each vertex an offset from it — the row's own `{ x, y }` points, or `{ x, y, bulge }`. A footprint without the box, and a shape role naming a field, are refused, naming the accessor to write. | `schematicShapes`, `schematicDataCentre` |
2939
- | `zones={{ areas: Schematic.zones(…, { x, y, width, height, label, pattern?, geometry? }) }}`, `pattern: (a) => a.kind.match({ … })`, `Schematic.outline()` / `.hatch()` | Zones in their boxes under the items, outlined or hatched by what the row says it is. | `schematicShapes`, `schematicDataCentre` |
2940
- | `links={{ fibre: Schematic.links(…, { from: { field, of }, to: { field, of }, via? }) }}`, `Schematic.solid()` / `.dashed()` | Links between items, routed orthogonally, two of one pair fanning into lanes, in the shared links look: each from its `from` item's edge to its `to` item's, its head there, in the links' muted ink or its style's tone; an end of a variant field takes its slot from its case. | `schematicDataCentre` |
2941
- | `nets={{ feeds: Schematic.nets(…, { sources: { field, of }, destinations: { field, of } }) }}` | A bus joining many items to many. | `schematicDataCentre` |
2942
- | a kind bound with its patch door — `Record.bind(record)` **❗** | Every gesture one step of one history over a session per record (#1388): Move, Connect, Shift growing a net of the first editable net kind that takes its items, an end retargeted, a net extended, Del; Undo, Redo and Discard; Save sending each record's changes through its patch door, one refused leaving the others' commits standing. A gesture writes only the fields its roles map, a new row under a minted key. | `schematicDataCentre` |
2943
- | `details: Schematic.details(record, { status?, meter?, metric?, sublabel?, fields?, inspector?, entries? })` **❗** | A record keyed as its kind is, its roles drawn on the cards; a role given by the kind too is refused. Bound with its patch door — `entries` beside it where the kind is read through its source — the inspector edits it beside the kind's row. | `schematicDataCentre` |
2944
- | `templates: Schematic.templates(rows, { name, group?, values, source })` **❗** | A templates record, its `source` one of the slice's; `values` gives every field but what a drop places — an item's `x` and `y`, a link's ends, a net's sides. A list written in the code is refused. | `schematicDataCentre` |
2945
- | `library={[Schematic.library.templates(), .backlog(), .index(), .layers(), .tab(rows, {…})]}` **❗** | The library pane's tabs, each over every kind as the Calendar's are, each checked against the kinds: Templates and Backlog are refused when no kind has any, naming the change. The frame's start pane draws them, each with its count, each card tab following its source of the rail (#1389). | `schematicDataCentre` |
2946
- | the Layers tab's Isolate, Lock, Show or Hide and Show all | The viewer's layer choices, kept under the Schematic's `id` over the author's defaults: a hidden layer's entities never draw, a locked one's never select. | `schematicDataCentre` |
2947
- | a template's or a backlog row's card dropped on the canvas **❗** | One step (#1390): an item template adds an item at the point, its key minted, selected; a backlog row is placed there, selected; a link or net template gives a link or a net of its kind its values, never its ends, sides or key. The caption says where (`Cage A · 12.00, 1.00 m`, `onto A03 → ODF-1`), or why not (`Outside the drawing`, `Drop onto a fibre run`, `Racks are read only`). | `schematicDataCentre` |
2948
- | `Schematic.library.tab(owners.read(), { name, label, meta?, drop: (o) => Schematic.patch(DcRack, { owner: o.name }) })` **❗** | An author's card dropped on an entity of the patch's kind sets those fields, one step; ⏎ — on a touch screen a tap on the selected card — sets them on every selected entity of that kind. A tab without `drop` doesn't drag. | `schematicDataCentre` |
2949
- | `layers={Schematic.layers(rows, { label, order?, tone?, color?, visible?, locked?, opacity? })}` **❗** | The layers, the app's own rows in their `order`, then key order, each keyed by its row's key; an accessor of another type, and a list written in the code, are refused, naming them. | `schematicShapes`, `schematicDataCentre` |
2950
- | `color` / `tone` / `fillOpacity` / `weight` | Colour overrides on an item's footprint, a zone and a layer — a theme colour token or a tone. | `schematicShapes` |
2951
- | `inspector` · a kind's `fields`, `ready` and own `inspector` **❗** | The inspector pane, opted into as the Plan's is (#1391): Details — an item's form and its details', its position and Unplace, what it is joined to; a zone's form; a link's ends as Choosers; a net's sides as tags, a leg's Remove; several and Delete; with nothing selected the drawing's counts and saves — each edit one step; and Issues, each selecting what it names. `fields` hints a kind's form, `ready` checks a drafted row, and a kind's own `inspector` is its Details in place of its form. `inspector={{ <slot>: … }}` is refused, naming the kind's `inspector`. | `schematicDataCentre` |
2952
- | `onSelect={fn(Array<Schematic.Types.Ref>) => Null}` | The whole selection after each change, items, zones, links and nets alike, each `{ kind, key }`; `[]` once cleared. | `schematicDataCentre` |
2953
- | `canConnect={fn(Schematic.Types.Candidate) => Option<String>}` | A connect drag's candidate, `{ kind, from, to }`: `none` lets it snap, and words refuse it — the draft says them in its caption, and letting go records nothing; a veto that throws allows the pair. | `schematicDataCentre` |
2954
- | `id="floor"` | Keeps the Schematic's panes, layers and tools apart when one surface holds two. | every example |
2955
-
2956
- Removed with #1401, each still written refused at build, naming its
2957
- replacement: `name` (`id`); `inspector={{ <slot>: Details }}` (the kind's own
2958
- `inspector`); `Schematic.library.templates(slot)` and `unplaced(slot)`
2959
- (`templates()` and `backlog()`, over every kind); `onSelectionChange`,
2960
- `onZoneSelectionChange` and `onSelectLink` (`onSelect`, the whole selection);
2961
- `onViewportChange` (the canvas reads its own window); `onItemOpen` (Enter or a
2962
- double-click opens the selection in the inspector's Details); `selectZoomFocus`
2963
- (a tap selects in place; Find, the Index tab and the arrow keys fly); a
2964
- `layers` list written in the code (`Schematic.layers` over the app's rows);
2965
- and a `footprint` or a `geometry` naming a field that holds
2966
- `Schematic.Types.Geometry` (an accessor over the row's own fields). The
2967
- selection, zone selection and viewport event types are gone, and
2968
- `canConnect` hears a `Schematic.Types.Candidate` where it heard two
2969
- references.
2970
-
2971
- Removed with #1386, each still written refused at build, naming its
2972
- replacement: rows and their mappers — `items` as rows with `item`, and `zone`,
2973
- `link` and `net` — (kinds over the app's records, by slot); `onMoveItem`,
2974
- `onCreateLink`, `onEditLink`, `onDeleteLink` and `onEditNet` (the editing
2975
- session's gestures: bind a kind with its patch door to edit it); `linkMode`;
2976
- `readOnlyLinks` and `readOnlyItems` (a kind bound read only); the hover cards
2977
- `itemHover`, `zoneHover` and `linkHover` (the inspector); `affordances`
2978
- outside `slice`; the slice's effect props `sliceHidden`, `sliceOpacity`,
2979
- `sliceDesaturate`, `sliceDot`, `sliceEmphasis`, `sliceFrame` and
2980
- `sliceFrameFit` (`narrowed`); `sliceSelectField`; `selectionMode` (a tap
2981
- selects, Shift extends it, and the marquee boxes); `navigator` (the library's
2982
- Index tab); `height` and `maxHeight` (the Schematic fills the box it is given);
2983
- and `onSelectZone` (`onSelect`, over the whole selection since #1401). A prop
2984
- the Schematic doesn't take is refused, naming those it does.
366
+ | `<Plan>` | Heterogeneous rows on one time / number / ordinal axis: series over data, event kinds over records, read-only rows | `e3-ui:plan-events.examples.tsx:planEvents` (smallest), `e3-ui:plan.examples.tsx:planTargetState`, `e3-ui:plan-windows.examples.tsx:planWindows`, `e3-ui:plan-records.examples.tsx:planRecordIndexes` |
367
+ | `<Sheet>` | A planning spreadsheet over a record, the host's rows or a paged source: typed columns, registers, groups, copilot, Excel round-trip | `e3-ui:sheet.examples.tsx:sheetBasic` (smallest), `e3-ui:sheet.examples.tsx:sheetWorkshop`, `e3-ui:sheet.examples.tsx:sheetPaged`, `e3-ui:sheet-records.examples.tsx:sheetRecordIndexes` |
368
+ | `<Calendar>` | Calendar, Resources and Timeline layouts over event records with a backlog | `e3-ui:calendar.examples.tsx:calendarMinimal` (smallest), `e3-ui:calendar.examples.tsx:calendarOperations`, `e3-ui:calendar-records.examples.tsx:calendarRecordIndexes` |
369
+ | `<Roster>` | Weekly staffing: duties over people by shift, cover targets, pay, fit, publish | `e3-ui:roster.examples.tsx:rosterMinimal` (smallest), `e3-ui:roster.examples.tsx:rosterWarehouse`, `e3-ui:roster.examples.tsx:rosterPeople` |
370
+ | `<Allocation>` | A day's arrivals booked into lane slots, each bin on resources | `e3-ui:allocation.examples.tsx:allocationMinimal` (smallest), `e3-ui:allocation.examples.tsx:allocationKilnYard`, `e3-ui:allocation.examples.tsx:allocationFitRule` |
371
+ | `<Flowchart>` | States in ordered phase lanes, transitions, decision triggers | `e3-ui:flowchart.examples.tsx:flowchartFlows` (smallest), `e3-ui:flowchart.examples.tsx:flowchartDepot`, `e3-ui:flowchart.examples.tsx:flowchartDetail` |
372
+ | `<Schematic>` | Items, zones, links and nets at world coordinates | `e3-ui:schematic.examples.tsx:schematicFloor` (smallest), `e3-ui:schematic.examples.tsx:schematicDataCentre`, `e3-ui:schematic-records.examples.tsx:schematicRecordIndexes` |
373
+
374
+ Field types matter: a `Sheet.column.quantity` sits on a `Float` field, a
375
+ `Sheet.column.date` on a `DateTime`, each `Option` of it allowed; an event's
376
+ start and end are `Option<DateTime>` when it can wait in the backlog.
377
+
378
+ ## Other surfaces
379
+
380
+ - **`<Diff bindings={[…]} />`** reviews pending changes of any staged bindings.
381
+ - **`<Ontology binding={view.binding} />`** edits a typed node / link graph
382
+ (`OntologyType`); stack a `<Diff>` beside it. The **east-ontology** skill
383
+ builds the graph.
384
+ - **`<Experiment>`** answers "did X change Y?" over a bound dataset: `data` and
385
+ `configs` (the questions, `Experiment.Types.Configuration`) via `Data.bind`,
386
+ `experiment` (an estimator `(rows, config) → result`) and `design` via
387
+ `Func.bind`, a `journal` that Commit appends to, and `columns` / `subject`
388
+ whose labels every sentence speaks. The words are derived from the numbers;
389
+ nothing is authored.
390
+ - **The Decide loop.** Reasoning tasks emit `Array<Decision.Types.Decision>`
391
+ (`Decision.make` / `option` / `reference` / `judgement`).
392
+ `Decision.bind([Contract]?, { decisions: [views…], judgements })` unions them
393
+ into one handle owning the selection, the routing of writes by case and the
394
+ commit gate; the judgements bind staged. `<DecisionQueue handle …/>` is the
395
+ queue (`modify`, `evidence`, `facets`, `groups`, an author-bound `slice` from
396
+ `Slice.bind(key, handle.queue(), {…})`); `<DecisionJournal handle />` is the
397
+ resolved read-back.
398
+ - **The Studio.** `Studio.component(key, { name, category, icon, span?, … },
399
+ fn)` declares a self-contained component written like a `ui()` body; the
400
+ pages live in one `Studio.Types.Pages` record with a patch mutation.
401
+ `<Studio.Builder>` and `<Studio.Library>` take `Record.bind(pages)`;
402
+ `<Studio.Page>` takes `Data.bind(pages).read()`. Each takes the components
403
+ as one `$.let([...])` list in palette order; the surface's manifest is the
404
+ union of their reads.
405
+ - **Queries.** One `Query.Types.Saved` record with a patch mutation holds the
406
+ saved jq queries; `Query.value(sources, queries)` ships some, checked at
407
+ build. `<Query.Builder queries datasets />` edits a query as steps or jq,
408
+ checks it, runs it on e3 (split over a large dataset's pieces) and saves it;
409
+ `<Query.Library>` lists them.
2985
410
 
2986
411
  ## Rendering surfaces in an app — `<E3Provider>`
2987
412
 
2988
413
  A deployed `ui()` task renders in a React app through
2989
- `@elaraai/e3-ui-components`. `<E3Provider config>` says which e3 the app talks
2990
- to, and how its requests reach it. `<ReactiveDatasetProvider>`, inside it,
2991
- installs the adapters `Data.bind`, `Data.bindPaged`, `Func.bind` and
2992
- `Record.bind` resolve through, for the config's workspace, and renders its
2993
- children once they are in. `<UITaskPreview task>` fetches a `ui()` task's
2994
- output and renders it, preloading what its manifest reads and polling it.
414
+ `@elaraai/e3-ui-components`: `<E3Provider config>` names the e3 and how
415
+ requests reach it, `<ReactiveDatasetProvider>` inside it installs the bindings'
416
+ adapters, and `<UITaskPreview task="…">` fetches and renders a task's output.
2995
417
 
2996
418
  | `E3Config` | Meaning |
2997
419
  |---|---|
2998
420
  | `apiUrl` | **required** — the e3 API's base URL |
2999
421
  | `repo` | the repository; `"default"` when omitted |
3000
422
  | `workspace` | the workspace the bindings read and write |
3001
- | `token` | a bearer token, or `null`; every request reads it afresh, so it may rotate |
3002
- | `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 |
3003
-
3004
- `E3Provider` also takes a `queryClient`, to share a TanStack Query cache with
3005
- the app; it makes its own otherwise.
3006
-
3007
- Over an e3 running in the page (e3-web: the **e3** skill), `apiUrl` and
3008
- `fetch` are the ones `createWebE3` gives, and no request reaches the network:
423
+ | `token` | a bearer token, or `null`; read afresh for every request |
424
+ | `fetch` | the `fetch` requests go through; for an e3 running in the page, the one `createWebE3` gives (e3-web, the **e3** skill) |
3009
425
 
3010
- ```tsx
3011
- // main.tsx — a deployed ui() task, every request it makes answered in the page
3012
- import { createRoot } from 'react-dom/client';
3013
- import { ChakraProvider } from '@chakra-ui/react';
3014
- import { system } from '@elaraai/east-ui-components';
3015
- import { E3Provider, ReactiveDatasetProvider, UITaskPreview } from '@elaraai/e3-ui-components';
3016
- import { createWebE3 } from '@elaraai/e3-web';
3017
-
3018
- const e3 = await createWebE3(new Worker(new URL('./e3.worker.ts', import.meta.url), { type: 'module' }));
3019
-
3020
- createRoot(document.getElementById('root')!).render(
3021
- <ChakraProvider value={system}>
3022
- <E3Provider config={{ apiUrl: e3.apiUrl, repo: 'default', workspace: 'main', fetch: e3.fetch }}>
3023
- <ReactiveDatasetProvider>
3024
- <UITaskPreview task="dashboard" />
3025
- </ReactiveDatasetProvider>
3026
- </E3Provider>
3027
- </ChakraProvider>,
3028
- );
3029
- ```
426
+ `E3Provider` also takes a `queryClient` to share a TanStack Query cache. Wrap
427
+ the app in `<I18nProvider locale="…">` (re-exported from
428
+ `@elaraai/east-ui-components`) to set the locale every surface prints numbers
429
+ in; dates print in UTC.
3030
430
 
3031
431
  ## Key Patterns
3032
432
 
@@ -3051,786 +451,36 @@ createRoot(document.getElementById('root')!).render(
3051
451
  }}</Reactive>
3052
452
  ```
3053
453
 
3054
- ### Disable controls on stale data
3055
-
3056
- ```tsx
3057
- <Slider
3058
- value={t.read()}
3059
- onChangeEnd={t.writeAndStart}
3060
- disabled={t.status().hasTag('stale')}
3061
- />
3062
- ```
3063
-
3064
- ### Numbers, dates and the locale
3065
-
3066
- Every e3-ui surface prints through east-ui's one formatter:
3067
- - the queue's values and deadlines;
3068
- - the journal's times and the constraint chips;
3069
- - the experiment's effects and its journal;
3070
- - a dataset preview's counts and sizes;
3071
- - a diff's values;
3072
- - the Plan's and the Sheet's numbers, counts and dates.
3073
-
3074
- 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.
3075
-
3076
- 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.
3077
-
3078
- ## Examples
3079
-
3080
- Tested examples live in `test/*.examples.tsx`:
3081
- - `data.examples.tsx` — `Data.bind` read/write/has, staged vs direct;
3082
- `Data.bindPaged` under a Plan, a Table and a Sheet — the large ones over
3083
- rows an `e3.task` generates — a snapshot's revision, and a record read
3084
- through its index.
3085
- - `func.examples.tsx` — `Func.bind` call/status/cancel, shared channels.
3086
- - `diff.examples.tsx` — reviewing pending changes with `<Diff>`.
3087
- - `ontology.examples.tsx` — graph/ontology editing with `<Ontology>`.
3088
- - `experiment/experiment.examples.tsx` — causal-experiment surface with `<Experiment>`.
3089
- - `decision/queue.examples.tsx` — `<DecisionQueue>` facets, probe editors, the
3090
- author-bound slice scope, grouping.
3091
- - `decision/journal.examples.tsx` — `<DecisionJournal>` read-back.
3092
- - `decision/loop.examples.tsx` — the full loop: two task outputs unioned by one
3093
- `Decision.bind` handle, queue + journal in lockstep.
3094
- - `studio/component.examples.tsx` — `Studio.component`: a self-contained
3095
- component placed twice on a page, the two placements sharing its state.
3096
- - `studio/page.examples.tsx` — `<Studio.Page>`: a page's live layout with no
3097
- chrome.
3098
- - `studio/studio.examples.tsx` — the Studio as a solution writes it: the data
3099
- its components read, the components, the pages record, and the three surfaces
3100
- it mounts — `<Studio.Builder>`, `<Studio.Library>` and a published
3101
- `<Studio.Page>`.
3102
- - `plan/plan.examples.tsx` — `planTargetState` combines all row kinds,
3103
- nesting, links, bound UI state, the series library, one rail whose
3104
- deliveries source narrows its Deliveries tab and holds the window, and a
3105
- narrow layout; `planMeasures` combines charts, heat, tables and resolution
3106
- folds, its weeks source holding the window; `planRowDrop` edits nested
3107
- record entries through one session; `planVariants`, `planNumberAxis` (its
3108
- orders source on the integer arm), `planOrdinalAxis` and `slicePlanChrome`
3109
- (the `rows` source of its rail, the canvas holding its own window) retain
3110
- their distinct axis, configuration and Slice examples.
3111
- - `plan/plan-events.examples.tsx` — `planEvents` is the smallest builder,
3112
- with a bound backlog, a customer-card tab and an Unassigned row.
3113
- `planPrintWorks` covers grouped presses and crews, nested bindery resources,
3114
- jobs, stops, shifts and plates, deliveries assigned to a bay or van, lanes,
3115
- status, readiness, overlap rules, linked events, measures and stock, under
3116
- one rail — the jobs and the shifts through their interval indexes, their
3117
- range the one window, the presses, the customers and each kind's templates
3118
- record. Its library and inspector use the shared frame and Save session.
3119
- `planEventLinks` keeps the individual link-routing cases.
3120
- - `plan/plan-windows.examples.tsx` — `<Plan>` over records too large to read
3121
- whole (`planWindows`): 2,000 presses a task generates, paged as the canvas
3122
- scrolls, and the jobs on them narrowed through the rail's `job` source —
3123
- read a cell at a time through their series index, shaded from their summary
3124
- zoomed out, their backlog through their interval index — and read by key
3125
- through their own entries, edited and saved without the record read whole;
3126
- and its presses a record the rail narrows by hall through an index of it,
3127
- the canvas paging the narrowing's presses and reading the cells of those in
3128
- view alone (`planSeriesByHall`).
3129
- - `plan/plan-records.examples.tsx` — the Sheet's 50,000 work orders on a Plan
3130
- (`planRecordIndexes`, `planRecordIndexesMobile`): the work orders a paged
3131
- resource kind its rail's `orders` source narrows through their indexes —
3132
- their Due a field of the rail, so a pan keeps the rows where they are — and
3133
- their 50,000 operations a record of their own placed on them, the source
3134
- holding the window, read a cell at a time through its series index and
3135
- shaded from its summary zoomed out; each move saved through the operations'
3136
- patch door by the operation's key.
3137
- - `sheet/sheet.examples.tsx` — `<Sheet>`, each in its frame, its rows bound
3138
- from e3: the smallest sheet over a record; the configurator over the host's
3139
- rows, committed through `onApply`; two thousand jobs of a record, read only,
3140
- the narrowing its rail makes through the record's indexes drawn over them as
3141
- the lens, with saved views; a library of the author's own cards; the workshop's orders, the flagship
3142
- (groups, the driver and registers, the link grammar, the copilot's fills and
3143
- proposers, readiness, one rail over the orders and two templates records,
3144
- the library, the inspector and views); one week's rows with every column
3145
- kind and its rules, a journal and the author's own inspector; one day's
3146
- batches dragged and moved, with sub rows and templates records; loose rows
3147
- between work packages; and a record read a window at a time. Between them,
3148
- every pane combination: none, a library, an inspector, and both. A sheet
3149
- paged from a dataset is `data.examples.tsx`'s, and one over a record's own
3150
- entries through `Record.onApply` `record.examples.tsx`'s `recordSheetApply`.
3151
- - `sheet/sheet-records.examples.tsx` — the lens over 50,000 work orders
3152
- (`sheetRecordIndexes`, `sheetRecordIndexesMobile`): the `rows` source of the
3153
- sheet's rail narrows them through the record's indexes, and the sheet draws
3154
- only the orders the narrowing keeps, each at its row number, read a segment
3155
- at a time near the view, each Save through `Record.onApply` by the order's key.
3156
- - `sheet/sheet-link.examples.ts` — the link grammar: `Sheet.link.parse` and
3157
- `Sheet.link.print`.
3158
- - `sheet/sheet-transactions.examples.ts` — `Sheet.apply` over rows, and over
3159
- entries of groups and loose rows.
3160
- - `flowchart/flowchart.examples.tsx` — `<Flowchart>`, each in its frame, in
3161
- a box of its own height, its flows bound from e3: a record of the depot's
3162
- flows by name, its value from `Flowchart.values`, with its Flows tab
3163
- (`flowchartFlows`); the configurator — the legend, the minimap and read only
3164
- over the host's flows, Save committed by the host's `onApply` through the
3165
- record's patch mutation, and what is selected heard in its aside
3166
- (`flowchartVariants`); the depot's flows with the library — the Flows tab,
3167
- step and transition templates from templates records, and the author's own
3168
- cards from a record of roles, the rail narrowing each through the source it
3169
- names, each card dropped on the canvas (`flowchartLibrary`); a flow from the
3170
- host's tables, each an input — decision triggers, evidence, a ×14 state
3171
- class, an in-place loop, an unresolved ghost and its inspector, read only,
3172
- nothing narrowing it (`flowchartDepot`); a record of 2,048 flows, its rail's `flows` source
3173
- narrowing the Flows tab, which counts it and searches it by name
3174
- (`flowchartRecordIndexes`); one flow of the host's, an input's value from
3175
- `Flowchart.value`, top down with no pane (`flowchartHandover`); and a
3176
- record's one flow edited on the canvas — every gesture a draft, Save one
3177
- commit, a `canConnect` veto — with a state's and a transition's own Details
3178
- (`flowchartDetail`). Between them, every pane combination: none, a library,
3179
- an inspector, and both.
3180
- - `schematic/schematic.examples.tsx` — `<Schematic>` over the app's records:
3181
- one hall's racks, read only and read whole, each card's second line and
3182
- power meter from its row (`schematicFloor`); the same hall handed over to
3183
- its install crew, its racks moved and deleted, with no pane — the toolbar,
3184
- the canvas and the footer (`schematicHandover`); footprints and zone shapes
3185
- built by accessors from the rows' own fields and drawn about their anchors
3186
- — a unit's outline corners and a tower's radius about each unit's centre,
3187
- a hall's corners and a duct bank's arcing band about each area's box centre
3188
- — with theme colour tokens, tones and layers from a systems record
3189
- (`schematicShapes`); and a data centre floor over several records — racks
3190
- editable and read through their source of the rail, their loads as details
3191
- on each card, edited in the inspector, network frames, round cooling units with their own Details,
3192
- power distribution units, halls, cages and aisles outlined or hatched by
3193
- what they are, fibre runs between racks and frames, solid or dashed by
3194
- their cable, a run between two frames refused in the veto's words, power
3195
- feeds and fibre trunks as nets — no trunk until a Shift session grows one —
3196
- every gesture a step of one history and Save per record, rack and fibre
3197
- templates records, the racks with no position, the whole selection kept by
3198
- the host, the inspector, and the library's tabs over every kind
3199
- (`schematicDataCentre`).
3200
- - `schematic/schematic-records.examples.tsx` — a floor of 20,000 racks in ten
3201
- halls read a window at a time (`schematicRecordIndexes`): the racks bound
3202
- with their patch door and read through their source of the rail by area, an
3203
- area index at a 1 cm cell beside one led by the hall and an index of their
3204
- models; their density past 5,000 racks in view; their loads read by the runs
3205
- of the window's cells; a rack moved, a draft kept wherever the window goes
3206
- and saved through the door. The same floor in a phone-width frame with its
3207
- inspector, a rack found by its key and moved by its `x` and `y`
3208
- (`schematicRecordIndexesMobile`). Its records are seeded by the pure
3209
- generator that also runs as an e3 task.
3210
- - `query/query.examples.tsx` — queries as a solution writes them: the shared
3211
- fixture's datasets; the saved queries record, its value seven queries from
3212
- `Query.value`; the builder open on three of them and over an empty record; an
3213
- order history the package's tasks generate, with its own saved queries and a
3214
- builder whose runs are split calls; and the library.
3215
-
3216
- ## Related skills
3217
-
3218
- - **e3** — workspaces, tasks, `e3.input`, dataflow execution (the engine `ui()`
3219
- builds on), and e3-web, which runs e3 in the page.
3220
- - **east-ui** — the JSX component library (`<Reactive>`, `<Slider>`, `<Stat>`, …)
3221
- that `ui()` renders.
3222
- - **east** — the language used inside `East.function` bodies.
3223
- - **east-ontology** — the `<Ontology>` editor's node/link model and the workshop
3224
- method for building one.
3225
- - **east-design** — decide where a decision surface fits in the overall solution.
3226
- - **e3-ui-cli** — screenshot a surface from the terminal: `e3-ui shot
3227
- --from-source` renders a zero-input `ui()` task; `--from-task` renders a
3228
- deployed task's computed output.
3229
-
3230
- ## Calendar — a schedule over bound records
3231
-
3232
- Import `Calendar` from `@elaraai/e3-ui`. Its renderer is in
3233
- `@elaraai/e3-ui-components`; BuilderFrame is internal. The former east-ui
3234
- heatmap Calendar and its `scale`/`totals`/`footer` helpers have been removed.
3235
-
3236
- Bind each event record with its patch mutation inside `Reactive`, then give
3237
- `Calendar.events` the names of its title, start, end and resource fields.
3238
- Bind what the Calendar reads whole — its resource records and its templates
3239
- records — with `Data.bind`, which keeps them loaded beside its pages.
3240
- `Calendar.resources` and `Calendar.templates` read their dictionaries, so
3241
- record updates change the labels and available templates reactively. Backlog
3242
- rows belong to the event record: optional start/end fields with no schedule,
3243
- plus `backlog` duration and due-date accessors. Scheduling and returning to
3244
- backlog update that same row; they never copy it into another record.
3245
-
3246
- Its `slice` is one `Slice.bindRecords` (#1343), a source named after each
3247
- event kind's slot, each resource kind's slot, and each templates record or tab
3248
- that names one. An event kind's source reads its record through an interval
3249
- index, with `range: "start"`, and the kind gives `entries`, the record's own
3250
- entries, beside it:
3251
-
3252
- ```tsx
3253
- // Package side, among each record's indexes: jobs_by_time: index.interval({ from: "start", to: "end" }),
3254
- // jobs_by_status_time the same with `on: ["status"]`, machines_by_area: index.on(["area"]), job_templates_by_group: index.on(["group"]).
3255
- // Inside Reactive: jobs has optional start/end and a machine reference.
3256
- const machines = $.let(Data.bind(d.machines));
3257
- const templates = $.let(Data.bind(d.jobTemplates));
3258
- const jobs = $.let(Record.bind(d.jobs));
3259
- const jobIndex = $.let(Data.bindPaged(d.jobs, { indexes: ["jobs_by_time", "jobs_by_status_time"] }));
3260
- const jobEntries = $.let(Data.bindPaged(d.jobs));
3261
- const machineIndex = $.let(Data.bindPaged(d.machines, { indexes: ["machines_by_area"] }));
3262
- const templateIndex = $.let(Data.bindPaged(d.jobTemplates, { indexes: ["job_templates_by_group"] }));
3263
- // One rail, a source per record, each named after what it narrows.
3264
- const slice = $.let(Slice.bindRecords("ops.calendar", {
3265
- job: { source: jobIndex, fields: { status: { label: "Status" }, start: { label: "Dates" } }, range: "start" },
3266
- machines: { source: machineIndex, fields: { area: { label: "Area" } } },
3267
- jobTemplates: { source: templateIndex, fields: { group: { label: "Template" } } },
3268
- }));
3269
- return <Calendar slice={{ slice }}
3270
- resources={{ machines: Calendar.resources(machines.read(), {
3271
- name: "Machines", icon: "gears", label: machine => machine.name,
3272
- }) }}
3273
- events={{ job: Calendar.events(jobs, {
3274
- name: "Job", icon: "industry", title: "title", start: "start", end: "end",
3275
- resource: { field: "machine", of: "machines" }, entries: jobEntries,
3276
- backlog: { duration: row => variant("hours", row.hours), due: row => row.due },
3277
- templates: Calendar.templates(templates.read(), {
3278
- name: row => row.name, group: row => some(row.group),
3279
- duration: row => variant("hours", row.hours), values: row => row.values,
3280
- source: "jobTemplates",
3281
- }),
3282
- }) }}
3283
- library={[Calendar.library.templates(), Calendar.library.backlog()]}
3284
- inspector />;
3285
- ```
3286
-
3287
- The runnable examples `calendarQuickstart`, `calendarOperations`,
3288
- `calendarMinimal`, `calendarMobile`, `calendarWindowed`, `calendarReadOnly`,
3289
- `calendarCustomInspector`, `calendarRecordIndexes`,
3290
- `calendarRecordIndexesMobile`, `calendarWindows`, `calendarWindowsByHall` and
3291
- `calendarWindowsMobile` include their record declarations and seeds. Search
3292
- those names in the example index. Their bindings become the UI task's
3293
- read/write manifest.
3294
-
3295
- A record too large to read whole is read the Plan's way (#1424): a resource
3296
- kind may be paged — `Calendar.resources(Data.bindPaged(record), …)` — and an
3297
- event kind placed on it is read a cell at a time through a series index and
3298
- shaded from a summary index, its source listing both beside its interval
3299
- index; every other kind is counted before one of its events is read, and none
3300
- past 10,000 over the window is read or drawn. Its Backlog is paged through
3301
- each kind's source, a page at a time; nothing reads a record whole:
3302
-
3303
- ```tsx
3304
- // Package side, among the jobs record's indexes, beside its interval index (the e3 skill):
3305
- // jobs_by_press_week: index.series({ key: "press", from: "start", to: "end", tile: "week" }),
3306
- // jobs_by_press_month: index.summary({ key: "press", from: "start", to: "end", tile: "month" }),
3307
- // Inside Reactive: 2,000 presses a task generates, paged 200 to a window; the jobs a cell at a time.
3308
- const presses = $.let(Data.bindPaged(pressesTask));
3309
- const jobs = $.let(Record.bind(jobsRecord));
3310
- const entries = $.let(Data.bindPaged(jobsRecord));
3311
- const slice = $.let(Slice.bindRecords("ops.calendar", {
3312
- job: { source: Data.bindPaged(jobsRecord, { indexes: ["jobs_by_time", "jobs_by_press_week", "jobs_by_press_month"] }), range: "start" },
3313
- }));
3314
- return <Calendar slice={{ slice }} inspector library={[Calendar.library.backlog()]}
3315
- view={{ layout: "timeline", period: "week", date: new Date("2026-10-05T00:00:00Z") }}
3316
- resources={{ presses: Calendar.resources(presses, { name: "Presses", icon: "print", label: p => p.name, meta: p => some(p.hall) }) }}
3317
- events={{ job: Calendar.events(jobs, {
3318
- name: "Print job", icon: "file-lines", title: "title", start: "start", end: "end",
3319
- resource: { field: "press", of: "presses" }, entries,
3320
- backlog: { duration: j => variant("hours", j.sheets.divide(8000.0)), due: j => j.due },
3321
- }) }} />;
3322
- ```
3323
-
3324
- | Signature | Description | Example |
3325
- | --- | --- | --- |
3326
- | `<Calendar events resources? slice? library? inspector? view? hours? week? density? now? readOnly? canDrop? optimise? onSelect? id? />` **❗** | One shared frame: a toolbar with the time navigator, the rail over its `Slice.bindRecords` and its summary, and the history; the schedule; 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` |
3327
- | `Calendar.events(record, config)` **❗** | `Schedule.events`: span fields, resource references, status cases, shared `field` editors, `ready`, custom `inspector`, overlap policy and record patch writes. Narrowed through its source of `slice`, named after its slot, it gives `entries: Data.bindPaged(record)` beside it for its original-key reads. A kind's own `slice` or `filter`, and `window` / `backlogWindow` beside a source, are refused, naming the change. Whole-row edits use one EditSession per kind and one shared EditHistory. | `calendarOperations` |
3328
- | `slice={{ slice: Slice.bindRecords(key, { [kind]: { source, fields, range: "start" }, [resources]: …, [templates]: … }), affordances?, persist? }}` **❗** | One rail, a source per record (#1343). An event kind's reads its events in the window through an interval index — the window's rows alone — and the Backlog tab pages its backlog through it, its start Unset, never with the window (#1424); a draft draws where it places its event, so a backlog event scheduled shows where it lands, and the draft of an event the kind's narrowing does not hold draws nowhere. A resource kind's narrows its columns, the timeline's rows and the resource Choosers, which keep a placement's own resource and the resources an event's fields name; a paged kind's pages the narrowing's resources in its index's order. A templates list's and an app tab's narrow their cards. One date window: the first event source with a range leads, its range the time navigator's Range panel, never a chip of the rail, and navigation writes the window into every event source. Overlaps, checks and commands read every event and every resource. `Slice.bind`, a single `Slice.bindRecord` and a source nothing names are refused. | `calendarOperations`, `calendarRecordIndexes` |
3329
- | `Calendar.resources(rows, config)` | `Schedule.resources` over a dictionary, usually a record bound with `Data.bind`, read whole. | `calendarOperations` |
3330
- | `Calendar.resources(Data.bindPaged(record), { name, icon, label, meta? })` + a kind's source listing `index.series` and `index.summary` beside its interval index **❗** | A resource kind paged a window at a time (#1424): 200 resources to a window, the timeline's rows and the Resources view's columns the pages around the view — never every resource read — and each Chooser seeking a resource by its key through the paged read (`Press 1460 · P-1460 · Hall 4`). Where a view lays its resources out, an event kind placed on it is read a cell at a time — the events of the blocks of fifty resources around those in view, over the tiles the window touches, a range a resource a level (#1433), two requests a change — and past 10,000 events in the cells wanted shades each resource from the summary, the share of each period booked; the time grids and the agenda count it over the window first. A source named after the paged kind's slot (`Data.bindPaged(record, { indexes })` over its own record) pages the narrowing's resources in its index's order, the last view standing, retained, until its windows land. A kind on it whose source lists its interval index alone, or a summary and no series, one read whole or through its day index, and one placed beside another resource kind, are refused, naming both declarations over the kind's own fields. | `calendarWindows`, `calendarWindowsByHall`, `calendarWindowsMobile` |
3331
- | every other event kind, past 10,000 events over the window | Counted before one of its events is read — through its source's interval index, through its day index (the days its events run on, an upper bound) or in memory — and none of them read or drawn but its drafts: a resource's row or column shades from its source's summary at the view's period, else is hatched, the banner says how many events there are and where they show, and every figure that would count them says they are not counted, never 0. | `calendarRecordIndexes`, `calendarWindowed` |
3332
- | `Calendar.templates(rows, { name, group?, at?, duration, values, source })` **❗** | A templates record, bound with `Data.bind`, its `source` the rail's source over it, whose shown keys filter the Templates tab; typed `values` supplies exactly the event fields other than its scheduling roles. A list written in the code, one naming no source of the slice, and templates on a Calendar with no slice are refused, naming the change. Template changes do not rewrite existing event rows. | `calendarOperations` |
3333
- | `Calendar.library.templates()` / `.backlog()` / `.tab(rows, { …, source? })` **❗** | Shared Library cards and search, each tab following its sources: it counts what it shows (`5 of 6`) and, when the rail leaves it none, says so with Clear filters for them. The Backlog counts `N of M`, what its kinds' narrowing shows beside the stored events their choices hide — `…` until its counts are read, never a bare `Backlog` — and its Clear filters keeps each window. A kind narrowed through its source has its backlog paged through it (#1424), a page a request, its count the index's: never every unscheduled event read, no step of the dates reads it again, and a new narrowing keeps its cards and count standing, retained, until its own land. That paged list has no search of its own, as the Schematic's Backlog has none: the rail's choices narrow it. An author's tab names the source it follows (`source`) and may apply `Calendar.patch(RowType, fields)` to a compatible selected event. Invalid or ambiguous patch row types, and a `source` the slice lacks, are refused. | `calendarOperations` |
3334
- | the summary and the footer | The rail's summary names each source a narrowing hides rows of, in its own words (`6 of 10 production events`), and folded, the Filters popover heads each source's fields with its count (`4`, `6 of 10`, #1358); the window's own event count shows only with no slice. After a Save, a notice per event kind says, in its words, what left its narrowing. | `calendarOperations` |
3335
- | `Calendar.days(start, end)` / `.unscheduled(start, due)` | UTC half-open day keys and the unscheduled index key, for a kind with no source of `slice`: supply paged `window`, `backlogWindow` when applicable, and `entries` for selection and draft baselines by key. | `calendarWindowed` |
3336
- | `optimise={Func.bind(fn: FunctionDef<[Calendar.Types.OptimiseRequest(E, S)], Calendar.Types.OptimiseResult(E)>)}` **❗** | The app's optimiser (#1409): `E` and `S` the event and resource kinds' row types by slot (`Calendar.Types.OptimiseRequest({ job: Job }, { machines: Machine })`). The Elara eye in the toolbar, immediately before the history item, names the window (`Optimise Sep 28 – Oct 4`): one call per run with the window, the run's number, every event kind's rows in the window and the backlog by key as the session holds them — base plus every unapplied draft, every row whatever the rail shows — and every resource kind's rows read whole; the history and every gesture locked while it is out, a change of period stopping it. Its answer — the events complete — is diffed by key and recorded as ONE step: Undo in one, Redo replays the landing, Save commits it with everything else. A backlog event given a time is an add on the canvas, its Backlog count flashing; a moved event a change with a ghost at its old slot; one taken back a remove; each marked until Apply with its provenance on hover. A result equal to the request records nothing and says so; a failed call is a banner until the next run. | `calendarOptimise` |
3337
- | `readOnly` | Same layouts, filters, selection and overlaps, without sessions, mutation actions or editing callbacks. | `calendarReadOnly` |
3338
- | 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` |
3339
-
3340
- `canDrop` refuses a proposed placement before it becomes a draft. `ready`
3341
- validates the resulting row and may block Save. Unknown commit outcomes,
3342
- conflicts, Undo/Redo/Discard and draft restoration use the shared editing
3343
- contract. Date/time fields are UTC. A narrowed kind keeps its drafts by
3344
- original key: an edit the rail hides still saves, and a draft its narrowing
3345
- does not hold shows in neither the window nor the backlog. A source's counts
3346
- are exact counts of original records; a kind read through a day index
3347
- (`window`) counts the window it has loaded.
3348
-
3349
-
3350
- ## Roster — weekly staffing over the app's own records
3351
-
3352
- Import `Roster` from `@elaraai/e3-ui`; the renderer is in e3-ui-components.
3353
- One `<Roster>` owns its internal BuilderFrame. It stores nothing in a shape of
3354
- its own (#1365): it writes the app's duties through the duty kind's roles
3355
- (`Schedule.events`), reads its people and agencies (`Schedule.resources`),
3356
- publishes its weeks (`Schedule.periods`) and writes its cover targets
3357
- (`Roster.targets`), each the app's own record bound with its patch mutation;
3358
- its shifts, groups, positions, activities and proposals are read from the
3359
- app's rows through accessors. What the Roster reads whole binds with
3360
- `Data.bind`. Coverage, pay, checks and fits read every duty of the week, every
3361
- person and every activity, whatever the rail shows.
3362
-
3363
- The smallest roster — duties with their times, shift and team; staff; shift
3364
- times; teams:
3365
-
3366
- ```tsx
3367
- // Module level: the app's own duties; its workers (name, team), shift times (name, code, starts, hours, order) and teams likewise.
3368
- export const Duty = StructType({ person: StringType, start: DateTimeType, end: DateTimeType, shift: StringType, team: StringType });
3369
- export const duties = e3.record("duties", DictType(StringType, Duty), {
3370
- initial: new Map(),
3371
- mutations: (mutation) => ({
3372
- patch: mutation.patch(),
3373
- }),
3374
- });
3375
- // Inside Reactive:
3376
- const rota = $.let(Record.bind(duties));
3377
- const staff = $.let(Data.bind(workers));
3378
- const times = $.let(Data.bind(shiftTimes));
3379
- const groups = $.let(Data.bind(teams));
3380
- return <Roster
3381
- events={{ duty: Schedule.events(rota, {
3382
- name: "Duty", icon: "user-clock",
3383
- start: "start", end: "end", resource: { field: "person", of: "people" },
3384
- shift: "shift", group: "team",
3385
- }) }}
3386
- resources={{ people: Schedule.resources(staff.read(), { name: "People", icon: "user", label: w => w.name, group: w => w.team }) }}
3387
- shifts={Roster.shifts(times.read(), { label: s => s.name, code: s => s.code, start: s => s.starts, hours: s => s.hours, order: s => s.order })}
3388
- groups={Roster.groups(groups.read(), { label: t => t.name })} />;
3389
- ```
3390
-
3391
- The warehouse's roster over its own records — its duties, the weeks of its
3392
- rota, its cover targets and suggestions, staff and an agency — with its pay,
3393
- its check, Publish, one rail and its fit (`rosterWarehouse`):
3394
-
3395
- ```tsx
3396
- // Module level: the warehouse's duty, WarehouseDuty — who (a staff key, or an agency's), start, end, shift, team, role, task,
3397
- // unpaidBreak, agreed, costCentre and note — and its records: rosterDuties (its interval index roster_duties_by_time), rosterWeeks, rosterCover, ….
3398
- // Inside Reactive: what the Roster writes, each through its patch door.
3399
- const rota = $.let(Record.bind(rosterDuties));
3400
- const entries = $.let(Data.bindPaged(rosterDuties)); // one duty by its key
3401
- const byTime = $.let(Data.bindPaged(rosterDuties, { indexes: ["roster_duties_by_time"] })); // index.interval({ from: "start", to: "end" })
3402
- const weeks = $.let(Record.bind(rosterWeeks));
3403
- const cover = $.let(Record.bind(rosterCover));
3404
- // What it reads whole — every person and activity is the calculation scope — and their indexes for the rail.
3405
- const people = $.let(Data.bind(rosterStaff));
3406
- const acts = $.let(Data.bind(rosterActivities));
3407
- const staffIndex = $.let(Data.bindPaged(rosterStaff, { indexes: ["roster_staff_by_team_name", "roster_staff_by_skill"] }));
3408
- const actIndex = $.let(Data.bindPaged(rosterActivities, { indexes: ["roster_activities_by_group"] }));
3409
- const slice = $.let(Slice.bindRecords("ops.roster", {
3410
- // The week's duties: the Roster's navigation writes the range; no chip picks the week.
3411
- duty: { source: byTime, range: "start" },
3412
- people: { source: staffIndex, search: ["name", "skills"], fields: { team: { label: "Group" }, skills: { label: "Skill" } } },
3413
- activities: { source: actIndex, fields: { group: { label: "Group" } } },
3414
- }));
3415
- // firms, times, teams, roles and ideas: the agencies, shift times, teams, positions and suggestions, each Data.bind.
3416
- const fit = $.let(Func.bind(rosterStaffFit)); // the app's fit, below
3417
- // pay and check: below.
3418
- return <Roster week={{ start: "sunday" }} slice={{ slice }} fit={fit} pay={pay} currency="AUD" check={check} inspector
3419
- events={{ duty: Schedule.events(rota, {
3420
- name: "Duty", icon: "user-clock", entries,
3421
- start: "start", end: "end", resource: { field: "who", of: { staff: "people", agency: "agencies" } },
3422
- shift: "shift", group: "team", position: "role", activity: "task",
3423
- // The hours a duty counts: its length less its unpaid break.
3424
- hours: d => d.start.durationMinutes(d.end).subtract(d.unpaidBreak).divide(60.0),
3425
- fields: { costCentre: Schedule.field.text({ label: "Cost centre" }), note: Schedule.field.text({ label: "Note" }) },
3426
- }) }}
3427
- resources={{
3428
- people: Schedule.resources(people.read(), { name: "People", icon: "user", label: p => p.name, group: p => p.team,
3429
- position: p => p.position, skills: p => p.skills, contract: p => p.contract, agency: p => p.agency,
3430
- trainer: p => p.trainer, trainee: p => p.trainee, usual: p => p.usual }),
3431
- agencies: Schedule.resources(firms.read(), { name: "Agencies", icon: "building", label: a => a.name }),
3432
- }}
3433
- periods={Schedule.periods(weeks, { every: "week", status: { field: "state", draft: "open", published: "issued" }, dismissed: "dismissed" })}
3434
- targets={Roster.targets(cover, { day: "day", group: "team", shift: "shift", positions: "heads", hours: "hours" })}
3435
- shifts={Roster.shifts(times.read(), { label: s => s.label, code: s => s.code, start: s => s.start, hours: s => s.hours, order: s => s.order })}
3436
- groups={Roster.groups(teams.read(), { label: t => t.label, order: t => t.order })}
3437
- positions={Roster.positions(roles.read(), { label: p => p.label, code: p => p.code, lead: p => p.lead, order: p => p.order })}
3438
- activities={Roster.activities(acts.read(), { label: a => a.label, code: a => a.code, group: a => a.group, order: a => a.order })}
3439
- proposals={Roster.proposals(ideas.read(), { person: s => s.person, day: s => s.day, group: s => s.team, shift: s => s.shift, reason: s => s.why })}
3440
- rules={{ rest: 10.0 }}
3441
- library={[Roster.library.people(), Roster.library.activities(), Roster.library.tab(roles.read(), {
3442
- name: "Positions", icon: "id-badge", label: p => p.label, meta: p => some(p.code),
3443
- drop: (_p, key) => Schedule.patch(WarehouseDuty, { role: key }), // a card dropped on a duty sets its own field
3444
- })]} />;
3445
- ```
3446
-
3447
- Pay is the app's, in its own pay codes (#1368): an East function over one
3448
- person's duties for the week, or one agency's requests, that returns each
3449
- duty's cost by code. The Roster asks it a person at a time, again only for the
3450
- people whose duties changed, and totals what it answers by duty, slot, day,
3451
- week, person and code. The app's check is given those costs and each duty's
3452
- own row:
454
+ ### A record's mutation from a button
3453
455
 
3454
456
  ```tsx
3455
- // Ordinary time up to the person's contracted hours in the week, OT1 past them, and an agency's hours at its own rate.
3456
- const rateRows = $.let(Data.bind(rosterPayRates));
3457
- const rates = $.const(rateRows.read());
3458
- const pay = $.const(East.function([Roster.Types.PayRequest(WarehouseDuty)], Roster.Types.Pay, ($2, req) => {
3459
- const out = $2.let(new Map(), Roster.Types.Pay);
3460
- const zero = $2.const(0.0, FloatType);
3461
- const agency = $2.let(true, BooleanType);
3462
- const contract = $2.let(0.0, FloatType);
3463
- $2.match(req.who, { person: ($3, key) => {
3464
- $3.if(req.context.people.has(key), ($4) => {
3465
- const person = $4.const(req.context.people.get(key));
3466
- $4.assign(agency, person.agency);
3467
- $4.assign(contract, person.contract);
3468
- });
3469
- } });
3470
- const worked = $2.let(0.0, FloatType);
3471
- // The week's duties in time order, so the contract's hours run out where they do.
3472
- const ordered = $2.const(req.duties.toArray(($3, duty, key) => ({ key, duty })).sort(($3, d) => d.duty.start));
3473
- $2.for(ordered, ($3, d) => {
3474
- const costs = $3.let(new Map(), DictType(StringType, FloatType));
3475
- $3.if(agency, ($4) => {
3476
- $4(costs.insert("AGENCY", d.duty.hours.multiply(rates.get("AGENCY", () => 0.0))));
3477
- }).else(($4) => {
3478
- const ordinary = $4.const(East.max(East.min(d.duty.hours, contract.subtract(worked)), zero));
3479
- const over = $4.const(d.duty.hours.subtract(ordinary));
3480
- $4(costs.insert("ORD", ordinary.multiply(rates.get("ORD", () => 0.0))));
3481
- $4.if(East.greater(over, 0.0), ($5) => { $5(costs.insert("OT1", over.multiply(rates.get("OT1", () => 0.0)))); });
3482
- });
3483
- $3.assign(worked, worked.add(d.duty.hours));
3484
- $3(out.insert(d.key, costs));
3485
- });
3486
- return out;
3487
- }));
3488
- // The app's check sees the pay too: overtime on a duty nobody has agreed — a field of the warehouse's own row.
3489
- const check = $.const(East.function([Roster.Types.CheckContext(WarehouseDuty)], ArrayType(Roster.Types.Issue), ($2, cx) => {
3490
- const issues = $2.let([], ArrayType(Roster.Types.Issue));
3491
- $2.for(cx.week.assignments, ($3, a, id) => {
3492
- const costs = $3.const(cx.pay.get(id, () => East.value(new Map(), DictType(StringType, FloatType))));
3493
- $3.if(costs.has("OT1").and(() => East.notEqual(a.row.agreed, some(true))), ($4) => {
3494
- $4(issues.pushLast({ kind: variant("breach", null), tone: variant("info", null),
3495
- title: "Overtime not agreed", detail: East.str`${a.row.team} · ${a.row.shift}`,
3496
- slot: some(a.slot), assignment: some(id), flag: some("OT"), fix: none }));
3497
- });
3498
- });
3499
- return issues;
3500
- }));
3501
- ```
3502
-
3503
- A Find fix (Find a lead, a trainer, skilled staff) asks the app's fit — an
3504
- `e3.function` bound with `Func.bind`, the Allocation's contract — who fits the
3505
- issue's need on its slot, over the drafted week and every person, whatever
3506
- the rail shows. The People tab shows its fits among what the rail shows, best
3507
- first, each card with the fit's reason, under a chip that clears it; the
3508
- renderer decides no one itself. A fit builds on the ready-made rule, over the
3509
- app's duty row type:
3510
-
3511
- ```tsx
3512
- // Module level: the warehouse's fit, on e3 — the ready-made rule, then the most spare contract hours first.
3513
- export const rosterStaffFit = e3.function("roster_staff_fit", East.function([Roster.Types.FitRequest(WarehouseDuty)], Roster.Types.FitResult, ($, req) => {
3514
- const answer = $.const(Roster.answer(WarehouseDuty));
3515
- const rule = $.const(Roster.fit(WarehouseDuty));
3516
- const weekHours = $.const(Roster.weekHours(WarehouseDuty));
3517
- const hours = $.const(weekHours(req.week, req.context));
3518
- return answer(req, East.function([Roster.Types.FitRequest(WarehouseDuty), Roster.Types.Person], Roster.Types.Fit, ($2, request, person) => {
3519
- const verdict = $2.const(rule(request, person));
3520
- $2.match(verdict, { refused: ($3) => { $3.return(verdict); } });
3521
- const fits = $2.const(verdict.unwrap("fits"));
3522
- return variant("fits", { score: person.contract.subtract(hours.get(person.key, () => 0.0)), why: fits.why, warn: fits.warn });
3523
- }));
3524
- }));
3525
- ```
3526
-
3527
- | Signature | Description | Example |
3528
- | --- | --- | --- |
3529
- | **Builder and records** | | |
3530
- | `<Roster events resources shifts groups periods? targets? positions? activities? proposals? patterns? pay? currency? rules? check? fit? optimise? slice? library? inspector? view? tileTimes? letters? week? density? chipSkills? requirements? readOnly? id? />` **❗** | Shifts by day or week, People by week or month (#1406). Refused at build, each naming the change: a removed prop (below); `events` holding other than one kind; `resources` other than `people` and `agencies`; a duty kind whose resource names no `people`; a resource kind read a page at a time; a `people` kind with no `group`; `positions` beside a duty kind with no `position` role; `pay` without `currency`; a `pay`, a `check` or a `fit` over another row type; a `view.period` its layout does not take (Shifts takes `"day"` or `"week"`, People `"week"` or `"month"`); `Roster.library.patterns()` without `patterns`; and a library tab listed twice. The renderer validates live configuration. | `rosterWarehouse`, `rosterMinimal`, `rosterPeopleMonth` |
3531
- | `events={{ duty: Schedule.events(Record.bind(duties), { start, end, resource, shift, group, position?, activity?, hours?, fields?, inspector?, ready?, entries? }) }}` **❗** | Exactly one kind, the duties: a span kind of plain DateTime times, keyed by String. `resource` names a `people` key, or a variant whose cases name `people` and `agencies`: a person, or an agency asked to send someone. `hours` is what a duty counts for coverage, skill hours, contract hours, rest and pay; its length when omitted. The inspector shows a duty's times, position and activity, then the kind's form over the fields no role writes (`fields` hints) or the kind's own `inspector`; `ready` is the app's check on a draft. | `rosterWarehouse`, `rosterCustomInspector` |
3532
- | `resources={{ people: Schedule.resources(rows, { name, icon, label, group, position?, skills?, contract?, agency?, trainer?, trainee?, usual? }), agencies?: Schedule.resources(rows, { name, icon, label }) }}` | Every person and agency, read whole: the calculation scope. A person's key is what a duty's resource holds; `group` is their home group. | `rosterWarehouse` |
3533
- | `periods={Schedule.periods(Record.bind(weeks), { every: "week", status, dismissed?, entries? })}` | The app's weeks, each keyed by its first day by the Roster's week start: the status chip, Publish and the picker's Published · Draft · Not started. `dismissed` keeps the proposals a week rejected; without it, a proposal offers Accept only. Without `periods`, no Publish. | `rosterWarehouse`, `rosterPublished` |
3534
- | `targets={Roster.targets(Record.bind(cover), { day, group, shift, positions, hours, inspector?, entries? })}` **❗** | The app's cover targets, a row per slot, which its forecast fills: `day` a DateTime (a UTC midnight), `group` and `shift` Strings, `positions` an Integer, `hours` a `Dict<String, Float>` by activity. A slot with no row has no target; a target edit on one inserts a row under a minted key, its other fields their type's default. `inspector` is the app's own form for one target. | `rosterWarehouse`, `rosterCustomInspector` |
3535
- | `Roster.shifts(rows, { label, code, start, hours, order?, color? })` · `Roster.groups(rows, { label, order? })` · `Roster.positions(rows, { label, code, lead, order? })` **❗** | The lists the Roster reads over the app's rows, each a `Dict` keyed by String, in its `order`, then key order. A shift's `start` is a `Schedule.Types.Clock` and its `hours` what a new duty runs and a skill holder's capacity; its `color` (#1406) returns an `Option<ColorToken>` — east-ui's `ColorTokenType`, `Style.ColorToken("teal", "500")` — the People week's tiles' and the month's marks' fill, resolved through the theme, the same in both colour modes, the words on it in the ink the shade takes; `none`, neutral. A position that leads satisfies the lead rule, which needs the duty kind's `position` role. An accessor returning another type is refused, naming what it returns (`color`, naming `ColorTokenType`). | `rosterWarehouse`, `rosterMinimal`, `rosterPeople` |
3536
- | `Roster.activities(rows, { label, code?, group?, order? })` | Every activity from a keyed activities record (`Roster.Types.Activity` rows, or the app's own through the accessors): a group's skills are the activities of that group, and an activity of no group is a duty every group may assign. Coverage and checks read every one. | `rosterWarehouse` |
3537
- | `Roster.proposals(rows, { person, day, group, shift, reason })` | The app's suggestions, a person for a slot, each keyed by its row's key: Accept places the duty and keeps the key in the week's `dismissed`, one step; Reject keeps it there alone. A stale or already rostered proposal is hidden. | `rosterWarehouse` |
3538
- | `patterns={Roster.patterns(rows, { name, icon?, label, days, order? })}` **❗** | The app's week patterns (#1406), a keyed record read through accessors as the other lists are: `label` the card's name and the drop's words; `days` seven `Option<String>` shift keys from the week's first day, `none` a day off; `order` where it shows. `name` titles the tab `Roster.library.patterns()` lists them under — required, as `Schedule.events`' `name` is — and `icon` is its cards' Font Awesome solid icon (`calendar-week` by default). A pattern dropped on a person's week — a row's day in Week, a cell in Month, or chosen through a phone card's `Apply pattern…` — replaces its seven days as one `Apply pattern` step: a day it changes runs the pattern's shift in the person's home group at the shift's own times, position kept, activity kept within the group and cleared across one; a day off removes the duties, struck through until Save; a day it leaves as it is keeps its duty. The caption names the pattern, the person and the first warning (`Early · Mon–Fri → A. Alder · 6 h rest`), `Already matches …` where nothing changes, or the refusal: a published or read-only week, the Agency requests row (`Drop a pattern on a person's week.`), a shift not configured. A pattern with other than seven days or naming a shift the Roster has not configured is listed greyed with the reason and dragged by no one. Without `patterns` the People layout is as it is; the slice may narrow the tab through a `patterns` source. | `rosterPeople`, `rosterPeopleMonth` |
3539
- | `view={{ layout?, period?, date? }}` · `tileTimes="always" \| "different"` · `letters` | The first view (#1406): Shifts takes `"day"` (default) or `"week"`, People `"week"` (default) or `"month"`; each layout keeps its own period per viewer, and ‹ › and `[` `]` step it. A month is the four to six weeks touching it, a column each, from the configured week start; a week cell holds seven marks in the shifts' colours, lettered where a day is 13px or wider while `letters` is on (`true` by default); a column's header opens its week in Week. `tileTimes` says whether a tile shows the shift's hours (`06–14`) always (default) or only a duty's own times where they differ. Below 480px of main People offers Week alone, and a persisted month opens on its first week. | `rosterPeople`, `rosterPeopleMonth` |
3540
- | `slice={{ slice: Slice.bindRecords(key, { <duty slot>?, targets?, people?, activities?, <a tab's source>? }) }}` **❗** | One rail. The duty kind's source reads the week's duties through an interval index from `start` to `end`, `range: "start"`, the range the Roster's own navigation writes — no chip picks the week — the kind given `entries`; `targets` reads the week's targets the same way, `Roster.targets` given `entries`; `people` narrows the grid's and the People layout's people, the People tab and the person choices; `activities` the Activities tab and the activity choices. Without the duty source the duties are read whole. Coverage, pay and rules read every duty of the week and every person; filters never drop hidden drafts from Save. | `rosterWarehouse`, `rosterWindowed`, `rosterRecordIndexes` |
3541
- | **Pay, checks and fits** | | |
3542
- | `pay={fn(Roster.Types.PayRequest(R)) => Roster.Types.Pay}` + `currency` **❗** | The app's pay in its own codes: asked once per person with that person's duties for the week — `{ who, start, duties, context }` — and once per agency with its requests, each duty's cost by code back; asked again only for those whose duties, or whose duties' rows, changed. The Roster sums the costs by duty, slot, day, week, person and code, printed in `currency`; a call that throws is a warning banner naming the person, whose duties show no cost. Without `pay`, no costs show. | `rosterWarehouse` |
3543
- | `check={fn(Roster.Types.CheckContext(R)) => Array<Roster.Types.Issue>}` | The app's issues after the built-in ones, over `{ start, week, context, coverage, pay }`: each assignment carries its duty's own row (`a.row`), so a check reads the app's own fields. | `rosterWarehouse` |
3544
- | `fit={Func.bind(fn: FunctionDef<[Roster.Types.FitRequest(R)], Roster.Types.FitResult>)}` **❗** | The app's fit, beside `check`. A Find fix asks it who fits its issue's need on its slot, over the drafted week and the complete staff, whatever the rail shows; the People tab shows its fits among what the rail shows, best first, each card with the fit's reason, under a `Find · Leads` chip that clears it. One question is in flight at a time, answers are kept by question and drafts, and a find asks again when the drafts change. While asked, the fix reads `Finding…`; a failure is a warning banner, `Fits couldn't be checked`, with Retry. Omitted, no Find fix is offered, though `Roster.check` still reports the issue. A fit bound over another row type is refused, naming both. | `rosterWarehouse`, `rosterRecordIndexes` |
3545
- | `optimise={Func.bind(fn: FunctionDef<[Roster.Types.OptimiseRequest(R)], Roster.Types.OptimiseResult(R)>)}` **❗** | The app's optimiser (#1409). The Elara eye in the toolbar — between the issues item and the history item, as tall as the row's other controls, and at a phone's width, where the row's floor needs its room once the rail's icon has dropped its caret, the View's entry beside the issues, never out of the toolbar: `Stop optimising` while a run is out, off and saying why (`Read-only`) while the week's reads are in flight; listed only where the week can be optimised, never in Month — names the week (`Optimise W11`): one call per run with the week (`from`, `to`), the run's number, the week's duties by key as the session holds them — base plus every unapplied draft, every row whatever the rail shows — its targets by slot and `Roster.Types.Context`, the complete staff and configuration; whatever the layout. The history and every gesture are locked while it is out; a change of week stops it. Its answer — the duties complete — is diffed by key and recorded as ONE step: Undo in one, Redo replays the landing, Save commits it with everything else. Off → shift is an add, shift → another a change, shift → Off a remove struck on its tombstone for the highlight, each marked on the People tiles and the Shifts chips alike with its provenance on hover (`Was Mon Early · Elara run #7`); the changed people's hours and meter and the issues item flash. A result equal to the request records nothing and says so. | `rosterOptimise` |
3546
- | **Library and inspector** | | |
3547
- | `Roster.library.people()` / `.activities()` / `.patterns()` | Shared Library cards, avatars, search and explicit placement, each tab following its source of the rail: it counts what it shows and, emptied, says so with Clear filters. Neither People nor Activities has a filter of its own: leads, trainers, agency and skill are rail fields of the staff record, and a Find fix's result — the app's fit's answer — is shown in the People tab, with a chip that clears it. Named staff and unnamed agency requests stay distinct. `patterns()` (#1406) lists the app's week patterns under the declaration's `name`, each card its name, `5 shifts · 40 h` and a strip of seven marks in the shifts' colours under a header of the days' initials, dragged onto a person's week; refused without `patterns`. | `rosterWarehouse`, `rosterMobile`, `rosterPeople` |
3548
- | `Roster.library.tab(rows, { name, icon?, label, meta?, group?, drop?, source? })` **❗** | Reified typed card accessors over a bound dictionary, following the rail's `source` it names. `drop(row, key)` returns `Schedule.patch(DutyRowType, { … })`: the duty's own fields a card dropped on it sets, as Plan's tabs do. A card never replaces a duty's person. A `source` the slice lacks is refused. | `rosterWarehouse` |
3549
- | `inspector` | The end pane: a duty's times, position and activity, its kind's form or own `inspector`, and its costs by code; a slot's coverage and its targets, or `Roster.targets`' `inspector`. Every edit is a command of the same session as a drag or a card's action. | `rosterWarehouse`, `rosterCustomInspector` |
3550
- | **Domain functions and values** | | |
3551
- | `Roster.Types.{Week(R), Assignment(R), PayRequest(R), CheckContext(R), FitRequest(R), OptimiseRequest(R), OptimiseResult(R), Pay, Status, Slot, Who, Requirements, Requirement, Person, Activity, Group, Skill, Shift, Position, Agency, Rules, Context, Coverage, CoverageLine, Proposal, Issue, Fix, Need, FitResult, Fit, Refusal, Clock}` | The Roster's reading of the app's rows, carried in requests and stored nowhere. Each `(R)` is a constructor of the app's duty row type: the same `R`, the same East type. An `Assignment(R)` is `{ slot, who, position, activity, start, end, hours, row }`, `row` the duty's own; a `Week(R)` `{ status, assignments, requirements, dismissed }`, its status Schedule's period status (`draft`, `published { at }` or `other`). `Pay` is duty key → pay code → cost. A `Need` (leads, trainers, a skill) is a Find fix's; a `FitResult` `{ need, slot, people: Dict<String, Fit> }` echoes its question. `Fit` and `Refusal` are `Schedule.Types`', the Allocation's too. | `rosterWarehouse`, `rosterCoverage` |
3552
- | `Roster.coverage(R): (week, context, pay) => Dict<Slot, Coverage>` | Positions, named people, permanent, agency and requested hours — each duty's own hours — skill capacity and assigned hours, leads and trainers for every configured slot; its cost the app's pay summed, zero without it. Requests fill positions but never supply skills or a lead. | `rosterCoverage` |
3553
- | `Roster.check(R): (week, context) => Array<Issue>` | The built-in checks: missing lead, double booking, within-week rest, trainee without trainer, skill compatibility, open positions and skill gaps, each with its fix — a rest breach's moves the duty to another shift of its day, or to a later start. | `rosterChecks` |
3554
- | `Roster.fit(R): (request, person) => Fit` | The ready-made rule: refused `Not a lead` / `Not a trainer` / `Not skilled` without the need, `Rostered` that day, `Rest too short` (its measure the rest); else it fits, scored by spare contract hours this week and a week's 168 more in the slot's group, its reason `Dispatch · 14 h spare` or `from Inbound · 2 h over contract`. | `rosterFitTrainer` |
3555
- | `Roster.answer(R): (request, rule: (FitRequest(R), Person) → Fit) => FitResult` | A verdict per person of the complete staff from a rule, the need and the slot echoed: an `e3.function` fit's body. | `rosterAnswerLeads` |
3556
- | `Roster.weekHours(R): (week, context) => Dict<String, Float>` / `Roster.rest(R): (assignment, id, week, context) => Rest` | Each person's hours for the week, each duty's own; and a duty's rest before and after it, measured between the duties' own times. An agency's request has none. | `rosterWeeklyHours`, `rosterRest` |
3557
-
3558
- A duty's day is the UTC day whose shift start is nearest its start, and its
3559
- week the week holding that day. The Roster draws a duty's own times wherever
3560
- they differ from its shift's (`05:00–15:00` on the 06:00–14:00 shift) and
3561
- gives them no name and no worth — the app's `pay` does. Editing them keeps a
3562
- duty within 12 hours of its shift's start, its end after its start. A move to
3563
- another slot moves `start` and `end` with it, kept where they stood against
3564
- the shift's start, and writes `shift` and `group`: a move and back leaves them
3565
- as they were. A new duty runs its slot's shift, its other fields their type's
3566
- default, under a key minted unique (`crypto.randomUUID()`); Copy previous week
3567
- copies each duty of the week before at its shift's own times, its other fields
3568
- as they were. A duty whose shift or group isn't configured, or that names no
3569
- one, is listed in Issues and kept as stored, never placed.
3570
-
3571
- Every gesture is one step of one history over the duties', the weeks' and the
3572
- targets' sessions: accepting a proposal records the duty and the dismissal
3573
- together. Save sends each record's changes as its own request; a conflict or a
3574
- refusal keeps that record's drafts and leaves the others' commits standing,
3575
- and a lost response retries the same request. Drafts of every week stay in
3576
- their sessions, and Save includes them. Publish saves first, then writes the
3577
- week's status once every record reads back as saved; a failed save leaves the
3578
- week a draft, its drafts kept. A published week is read-only in every layout.
3579
- The People week (#1406) is a row a person under their group's band: the name
3580
- cell with the week's hours against the contract (and the cost, with `pay`)
3581
- over a meter, then a tile a duty in each day cell — the shift's label, its
3582
- hours by `tileTimes`, a duty's own times where they differ or the group where
3583
- it is not the person's, a warning mark where an issue names it — `+1` for a
3584
- second duty the same day, and `+ Assign` on a day off, a menu of the shifts
3585
- whose choice places the person as one gesture; a name selects the person-week,
3586
- which the inspector's Details read. Below 480px of **main** width, Shifts and
3587
- People use cards with explicit
3588
- Assign/Move/Edit/Remove/Restore/Request/Accept/Reject/target actions and no
3589
- drag; a People card gains `Apply pattern…` where `patterns` are given. The
3590
- `rosterMobile` example demonstrates the complete inline authoring pattern.
3591
-
3592
- Removed with #1368, each still written refused at build, naming its
3593
- replacement: `weeks` and `window` (`events={{ <slot>: Schedule.events(…) }}`
3594
- and `periods`, the week's duties read through the slice's duty source);
3595
- `people={Roster.people(…)}` and `agencies` as `Roster.Types.Agency` values
3596
- (`resources={{ people, agencies }}`, `Schedule.resources` kinds); `groups`,
3597
- `shifts` and `positions` as Roster values (`Roster.groups`, `Roster.shifts`,
3598
- `Roster.positions` over the app's rows); `forecast` (`targets={Roster.targets(…)}`,
3599
- a record of the app's that its forecast fills); proposals as
3600
- `Roster.Types.Proposal` values (`Roster.proposals`); `inspector={{
3601
- assignment, requirement }}` (the duty kind's own `inspector`, and
3602
- `Roster.targets`' `inspector`); `Roster.patch` in a tab's `drop`
3603
- (`Schedule.patch(DutyRowType, …)`); `costs` (`pay`, the app's East function in
3604
- its own codes, and `currency`); and an assignment's `offset`, `overtime` and
3605
- `agreed`, `rules.agree` and the agree issue and fix (the duty's own times and
3606
- fields, the app's `pay` and its `check`). `Roster.Types.Weeks` and
3607
- `Roster.Types.Costs` are gone: an app's weeks record becomes its own duties,
3608
- weeks and targets records. `visiblePeople` and `duties` stay refused (#1342).
3609
-
3610
- The runnable examples `rosterMinimal`, `rosterWarehouse`, `rosterMobile`,
3611
- `rosterPeople`, `rosterPeopleMonth`, `rosterWeek`, `rosterWindowed`,
3612
- `rosterPublished`, `rosterCustomInspector`, `rosterRecordIndexes` and
3613
- `rosterRecordIndexesMobile`
3614
- include their record declarations and seeds; `rosterCoverage`, `rosterChecks`,
3615
- `rosterWeeklyHours`, `rosterRest`, `rosterFitTrainer` and `rosterAnswerLeads`
3616
- run the pure functions over a small staff. Search those names in the example
3617
- index.
3618
-
3619
- ## Allocation — a day's arrivals booked into lane slots, each bin on its resources
3620
-
3621
- Import `Allocation` from `@elaraai/e3-ui`; the renderer is in
3622
- e3-ui-components, and its BuilderFrame is internal. One `<Allocation>` books a
3623
- day's arrivals into timed lane slots — each lane takes a bin every `every`, an
3624
- hour by default, at its offset past it — and allocates each bin's quantity to
3625
- the resources with room and time for its hold, as a Timeline (the lane grid,
3626
- the link channel and the resource rows) or a Table (a row per slot, in time
3627
- bands). It stores nothing in a shape of its own (#1365): it writes the app's
3628
- bins through the bin kind's roles (`Schedule.events`, an instant kind), reads
3629
- its lanes and resources (`Schedule.resources`) and what it books from
3630
- (`Allocation.arrivals`), and publishes the app's days (`Schedule.periods`).
3631
- Every gesture is a draft; Save sends each record's changes, and Publish saves,
3632
- then writes the day published, read only from then on. Issues never block
3633
- either. Fits, checks and totals read every lane, arrival and resource, and
3634
- every bin of the day, whatever the rail shows.
3635
-
3636
- The smallest board — bins with only the board's roles, the bays, the kilns and
3637
- the day's loads:
3638
-
3639
- ```tsx
3640
- // Module level: the app's own bins; its loads (code, m3, dryingDays), kilns and bays are records of its own too.
3641
- export const Bin = StructType({
3642
- bay: StringType, at: DateTimeType, load: OptionType(StringType),
3643
- m3: FloatType, kilns: DictType(StringType, FloatType), dryFor: TimeStepType,
3644
- });
3645
- export const bins = e3.record("bins", DictType(StringType, Bin), {
3646
- initial: new Map(),
3647
- mutations: (mutation) => ({
3648
- patch: mutation.patch(),
3649
- }),
3650
- });
3651
- // Inside Reactive:
3652
- const rows = $.let(Record.bind(bins));
3653
- const loads = $.let(Data.bind(arrivals));
3654
- const yard = $.let(Data.bind(kilns));
3655
- const bays = $.let(Data.bind(yardBays));
3656
- const fit = $.let(Func.bind(binFit)); // an e3.function from Allocation.Types.FitRequest(Bin), as the yard's fit below is over its own bins
3657
- return <Allocation fit={fit}
3658
- events={{ bin: Schedule.events(rows, {
3659
- name: "Bin", icon: "box",
3660
- at: "at", resource: { field: "bay", of: "bays" }, arrival: "load",
3661
- quantity: { field: "m3", unit: "m³" }, parts: { field: "kilns", of: "kilns" }, hold: "dryFor",
3662
- }) }}
3663
- resources={{
3664
- bays: Schedule.resources(bays.read(), { name: "Bays", icon: "warehouse", label: b => b.name, offset: b => b.offset }),
3665
- kilns: Schedule.resources(yard.read(), { name: "Kilns", icon: "fire", label: k => k.name, min: k => k.min, max: k => k.max, jobs: k => k.charges }),
3666
- }}
3667
- arrivals={Allocation.arrivals(loads.read(), { label: l => l.code, quantity: l => l.m3, hold: l => variant("days", l.dryingDays) })} />;
3668
- ```
3669
-
3670
- The kiln yard's board over its own records — bins with the yard's spec and
3671
- grade beside the board's roles, the days it publishes, a check over the bins'
3672
- own fields, one rail and its library (`allocationKilnYard`):
3673
-
3674
- ```tsx
3675
- // Inside Reactive: what the board writes, each through its patch door.
3676
- const bins = $.let(Record.bind(kilnBins));
3677
- const entries = $.let(Data.bindPaged(kilnBins)); // one bin by its key
3678
- const byTime = $.let(Data.bindPaged(kilnBins, { indexes: ["kiln_bins_by_time"] })); // index.interval({ from: "at", to: "at" })
3679
- const days = $.let(Record.bind(yardDays));
3680
- // What it reads whole — every bay, kiln and load is the calculation scope — and their indexes for the rail.
3681
- const yard = $.let(Data.bind(kilns));
3682
- const loads = $.let(Data.bind(arrivals));
3683
- const bays = $.let(Data.bind(yardBays));
3684
- const bayIndex = $.let(Data.bindPaged(yardBays, { indexes: ["yard_bays_by_area"] }));
3685
- const kilnIndex = $.let(Data.bindPaged(kilns, { indexes: ["kilns_by_group"] }));
3686
- const loadIndex = $.let(Data.bindPaged(arrivals, { indexes: ["arrivals_by_spec"] }));
3687
- // One rail, a source named after each slot it narrows.
3688
- const slice = $.let(Slice.bindRecords("ops.allocation", {
3689
- bin: { source: byTime, range: "at" }, // the day's bins: the board's navigation writes the range
3690
- bays: { source: bayIndex, fields: { area: { label: "Area" } } },
3691
- kilns: { source: kilnIndex, fields: { group: { label: "Kiln group" } } },
3692
- arrivals: { source: loadIndex, fields: { spec: { label: "Spec" } } },
3693
- }));
3694
- const fit = $.let(Func.bind(yardFit));
3695
- // The yard's check reads its own fields: a bin measured off its booked spec is flagged, never refused.
3696
- const check = $.const(East.function([Allocation.Types.CheckContext(KilnBin)], ArrayType(Allocation.Types.Issue), ($2, cx) => {
3697
- const issues = $2.let([], ArrayType(Allocation.Types.Issue));
3698
- $2.for(cx.plan.bins, ($3, bin, id) => {
3699
- $3.match(bin.arrival, { some: ($4, code) => {
3700
- $4.if(East.notEqual(bin.row.specBooked, bin.row.specMeasured), ($5) => {
3701
- $5(issues.pushLast({ kind: variant("custom", "Spec mismatch"), tone: variant("neutral", null),
3702
- title: East.str`${code} · bin ${id}`,
3703
- detail: East.str`Spec booked ${bin.row.specBooked} · measured ${bin.row.specMeasured} · ${bin.lane} ${bin.at.printFormatted("HH:mm")}`,
3704
- bin: some(id), resource: none, flag: some("≠ spec"), fix: none }));
3705
- });
3706
- } });
3707
- });
3708
- return issues;
3709
- }));
3710
- return <Allocation title="Kiln loading" fit={fit} check={check} slice={{ slice }} inspector
3711
- library={[Allocation.library.arrivals(), Allocation.library.resources()]}
3712
- view={{ layout: "timeline", date: new Date("2027-05-11T00:00:00Z") }}
3713
- events={{ bin: Schedule.events(bins, {
3714
- name: "Bin", icon: "box", entries,
3715
- at: "at", resource: { field: "bay", of: "bays" }, arrival: "load",
3716
- quantity: { field: "m3", unit: "m³" }, parts: { field: "kilns", of: "kilns" }, hold: "dryFor", kind: "spec",
3717
- fields: { specMeasured: Schedule.field.text({ label: "Spec measured" }), instruction: Schedule.field.text({ label: "Loading instruction" }) },
3718
- }) }}
3719
- resources={{
3720
- bays: Schedule.resources(bays.read(), { name: "Bays", icon: "warehouse", label: b => b.name, offset: b => b.offset }),
3721
- kilns: Schedule.resources(yard.read(), { name: "Kilns", icon: "fire", label: k => k.name, group: k => k.group, note: k => k.note,
3722
- min: k => k.min, max: k => k.max, hold: k => variant("days", k.days), jobs: k => k.charges }),
3723
- }}
3724
- arrivals={Allocation.arrivals(loads.read(), {
3725
- label: l => l.code, quantity: l => l.m3, hold: l => variant("days", l.dryingDays), kind: l => some(l.spec), due: l => some(l.due),
3726
- // A booked bin's own fields: the ones no role maps.
3727
- values: l => ({ specBooked: l.spec, specMeasured: l.spec, gradeBooked: l.grade.substring(0n, 1n), gradeMeasured: l.grade, instruction: l.instruction }),
3728
- })}
3729
- periods={Schedule.periods(days, { every: "day", status: { field: "state", draft: "draft", published: "issued" } })}
3730
- columns={[
3731
- { key: "spec", label: "Spec", text: b => East.equal(b.specBooked, b.specMeasured).ifElse(() => b.specMeasured, () => East.str`booked ${b.specBooked} · measured ${b.specMeasured}`),
3732
- tone: b => East.equal(b.specBooked, b.specMeasured).ifElse(() => none, () => some(variant("warning", null))) },
3733
- ]} />;
457
+ <Reactive>{$ => {
458
+ const r = $.let(Record.bind(counter, ["increment"]));
459
+ const bump = $.const(East.function([], NullType, $ => { $(r.mutate.increment(1n)); }));
460
+ return (
461
+ <VStack gap="2">
462
+ <Stat label="Counter" value={East.print(r.read())} />
463
+ <Button onClick={bump} loading={r.mutate.pending()}>Increment</Button>
464
+ <Text>{r.mutate.status().getTag()}</Text>
465
+ </VStack>
466
+ );
467
+ }}</Reactive>
3734
468
  ```
3735
469
 
3736
- The board computes no fit of its own. `fit` is the app's `e3.function`, bound
3737
- with `Func.bind`, from `Allocation.Types.FitRequest(R)` — the plan day, the day
3738
- as drafted with each bin's own row, one question, and every arrival and
3739
- resource — to `Allocation.Types.FitResult`. A question is a **place** — a bin
3740
- or an arrival, with the quantity being placed: a verdict per resource — or a
3741
- **take** — a resource: a verdict per bin, per arrival the day has not booked,
3742
- and one for reserving an empty slot. The answer echoes its question, and every
3743
- rank, refusal and reason the board shows is its. A fit builds on the
3744
- ready-made parts, over the app's bin row type:
470
+ ### Disable controls on stale data
3745
471
 
3746
472
  ```tsx
3747
- // Module level: the built-in rules, then a greedy look-ahead over the day's other loads.
3748
- export const yardFit = e3.function("yard_fit", East.function([Allocation.Types.FitRequest(KilnBin)], Allocation.Types.FitResult, ($, req) => {
3749
- const answer = $.const(Allocation.answer(KilnBin));
3750
- const rule = $.const(Allocation.fit);
3751
- const ahead = $.const(Allocation.lookahead(KilnBin));
3752
- return answer(req, East.function([Allocation.Types.Candidate], Allocation.Types.Fit, (_$2, c) => ahead(req, c, rule)),
3753
- "ranked by load, kind and spare days, and what it leaves for the day's other loads");
3754
- }));
473
+ <Slider value={t.read()} onChangeEnd={t.writeAndStart} disabled={t.status().hasTag('stale')} />
3755
474
  ```
3756
475
 
3757
- | Signature | Description | Example |
3758
- | --- | --- | --- |
3759
- | **Builder and records** | | |
3760
- | `<Allocation events resources arrivals fit optimise? periods? every? check? columns? slice? rules? library? inspector? view? horizon? title? readOnly? labels? table? id? />` **❗** | One toolbar row at every width — the day's navigator, its picker marking each day Published · Draft · Not started; Table · Timeline; the status chip; the focus; the rail and its count; the issues; with `optimise`, the Elara eye; the history and Publish — folding into one View in the narrowest frame, and below that, where the row is still too wide, the rail's icon dropping its caret and then the eye going into the View as its entry, the history and Save always in the row; then the Timeline or the Table, the panes the props ask for, and the footer's legend. Refused at build, each naming the change: a removed prop (below); `events` holding other than one kind; a bin kind with no lane or no parts; a resource kind that is neither the lanes' nor the resources'; resources read a page at a time or keyed by anything but String; a resources kind with no `min` or `max`; `arrivals` not from `Allocation.arrivals`, and its `values` of another struct than the bin kind's own fields; `periods` not from `Schedule.periods`; a `fit` bound over another row type, naming both; a `check` of another type; a library tab or a column given twice; an empty label; and Table bands that don't start at 0 and rise within the day. | `allocationMinimal`, `allocationKilnYard`, `allocationTable` |
3761
- | `events={{ bin: Schedule.events(Record.bind(bins), { at, resource: { field, of }, arrival, quantity: { field, unit? }, parts: { field, of }, hold, kind?, fields?, inspector?, ready?, entries? }) }}` **❗** | Exactly one kind, the bins: an instant kind keyed by String. A bin's UTC day is its plan day, and a batch's bins follow one minute apart. `resource` names its lane, a String key of the lanes' kind; `arrival` the arrival it books, `none` a reservation; `quantity`'s unit shows everywhere a quantity does; `parts` holds its quantity on each resource of the slot `of` names, empty while it is not linked; `hold` and `kind` are kept from booking. The inspector shows the kind's form over the fields no role writes (`fields` hints), or the kind's own `inspector`. | `allocationKilnYard`, `allocationCustomBin` |
3762
- | `resources={{ <lanes>: Schedule.resources(rows, { name, icon, label, offset? }), <resources>: Schedule.resources(rows, { name, icon, label, min, max, group?, meta?, note?, hold?, jobs? }) }}` **❗** | The lanes' kind under the slot the bin kind's `resource.of` names, each lane taking a bin each `every` at its `offset` past it, in key order; the resources' kind under the slot its `parts.of` names, each with its range in the quantity's unit. `jobs` is a resource's other work: one covering the day's start makes it busy, the first after it is its next job; `hold` is how long a reservation on it is checked for. Both are read whole and keyed by String. | `allocationKilnYard` |
3763
- | `arrivals={Allocation.arrivals(rows: Dict<String, R>, { label, quantity, hold, kind?, meta?, due?, window?, details?, values? })}` **❗** | Every arrival the day may book, each accessor `(row, key) => …`. Booking one writes the bin's roles — `arrival` its key, `quantity`, `kind` and `hold` from these accessors, `parts` empty, `at` and the lane where it is booked — and `values`' struct into the row's other fields: the bin kind's fields no role maps, held to them at build. Without `values` they take their type's default, as a reservation's always do. `due` before the day makes it overdue. | `allocationKilnYard` |
3764
- | `periods={Schedule.periods(Record.bind(days), { every: "day", status, entries? })}` | The app's days, each keyed by its UTC midnight: the status chip, Publish and the picker's Published · Draft · Not started. A published day is read only under its banner; navigation, the rail, the focus, links and the inspector still work. Without `periods`, no status chip and no Publish. | `allocationKilnYard`, `allocationPublished`, `allocationNoPublish` |
3765
- | `slice={{ slice: Slice.bindRecords(key, { <bin slot>?, <lanes>?, <resources>?, arrivals? }) }}` **❗** | One rail in both layouts. The bin kind's source reads the day's bins through an interval index from `at` to `at`, `range: "at"`, the range the board's own navigation writes — no chip picks the day — the kind given `entries`; without it the bins are read whole. The lanes', the resources' and `arrivals` each narrow every place their rows appear — the Timeline's lanes and rows, the Table's rows, the Choosers and the Library's tabs (`Resources 10 of 33`) — and the board reads each one's keys itself. The summary counts the day's bins too (`26 of 33 bin events`). The bare handle, `Slice.bind`, a single `Slice.bindRecord`, a source of another name and one keyed otherwise than by String are refused. | `allocationKilnYard`, `allocationTable`, `allocationWindowed` |
3766
- | `check={fn(Allocation.Types.CheckContext(R)) => Array<Allocation.Types.Issue>}` **❗** | The app's issues, after the built-in ones wherever issues show, over `{ day, plan, context, loads }`: each bin carries its own row (`bin.row`), so a check reads the app's own fields. An issue's `flag` marks its bin's card (`≠ spec`); a neutral or info issue is listed, not counted. | `allocationKilnYard` |
3767
- | `columns={[{ key, label, text: fn(R) => String, tone?: fn(R) => Option<StatusToken>, table? }]}` **❗** | The app's bin fields as Table columns after the quantity, and as the inspector's rows, each over the bin's own row; `table: false` shows one in the inspector only. | `allocationKilnYard` |
3768
- | `labels={{ lane?, arrival?, resource?, quantity? }}` **❗** | The board's nouns everywhere it writes them, each `"Bay"` or `{ one, other?, article? }`; Lane, Arrival, Resource and `QTY` by default. | `allocationLabels` |
3769
- | `table={{ bands: [{ from, label? }] }}` **❗** | The Table's time bands, each from its hour to the next band's, the last to midnight; four by default. | `allocationLabels` |
3770
- | `rules={{ under }}` · `every` · `view={{ layout, date }}` · `horizon={{ before, after }}` · `title` · `readOnly` · `id` | Whether the built-in rules warn under a resource's minimum (true); the slot spacing; the first layout and day, then kept under `id`; the Timeline's resource axis around the day (3 days before, 10 after); the summary's heading; no edits; storage keys when a surface holds two boards. | `allocationKilnYard` |
3771
- | **Library and inspector** | | |
3772
- | `Allocation.library.arrivals()` / `.resources()` **❗** | The start pane's tabs, in order — Arrivals: overdue, ready around now, removed from the plan, allocated; Resources: free, loading and busy today. Each card drags onto the board, or a click picks it and a click on a free lane hour books it; each tab follows its source of the rail. A tab listed twice is refused. | `allocationKilnYard` |
3773
- | `inspector` **❗** | The end pane, Details and Issues: what is selected — a bin with its Assigned to, each part's quantity, `Split…` (the remainder, or with none some of its largest part), its other fits and the kind's form, or the bin kind's own `inspector` (`update(edited)` one draft); a reservation; a free slot with what it can book and reserve; a resource — or the day's summary; and the day's issues, each with its fix. | `allocationKilnYard`, `allocationCustomBin` |
3774
- | **The fit** | | |
3775
- | `fit={Func.bind(fn: FunctionDef<[Allocation.Types.FitRequest(R)], Allocation.Types.FitResult>)}` **❗** | Required. The board asks for its active subject — the selected bin, a picked arrival, what a drag, a Chooser or Find a fit is for — and again when the drafts change, one question in flight at a time. While an answer is pending no verdict shows and a drop waits; a failure is the banner `Fits couldn't be checked`, with Retry. A fit bound over another row type than the bin kind's is refused, naming both types. | `allocationMinimal`, `allocationFitRule` |
3776
- | `Allocation.answer(R): (FitRequest(R), fit: fn(Candidate) => Fit, basis: String) => FitResult` | The question's candidates, each given a verdict by `fit`: a place's by resource, a take's by bin, by arrival and for reserving. `basis` is the answer's words for how it ranks. An app's fit's body. | `allocationAnswerPlace`, `allocationAnswerTake` |
3777
- | `Allocation.fit: (Candidate) => Fit` | The built-in rules, in order: busy (`busy until Fri 14`), a hold past the next job (`gap too short · next job Wed 19`), over max (`over max by 4 m³`), a reservation on a full resource (`full · …`). Else it fits, scored by its fill of the max, +0.25 beside a bin of its kind, −0.1 beside only others, −0.5 under the min and −0.04 a spare day up to six; its reason the spare days and the load it leaves (`1 d spare to Fri 21 · leaves 20 m³ · takes 10–24`), warning `under min` when `rules.under`. | `allocationRules` |
3778
- | `Allocation.candidates(R): (FitRequest(R)) => Array<Candidate>` | A place's subject on every resource, in key order; a take's every bin (its unallocated quantity, with its part there), every arrival the day has not booked, then a reservation. | `allocationRules` |
3779
- | `Allocation.lookahead(R): (FitRequest(R), Candidate, fit: fn(Candidate) => Fit) => Fit` | A greedy look-ahead: it places the candidate, then the day's unbooked arrivals largest first, each on its best fit, and lowers the score by one for each left with nowhere to go (`· leaves 1 load with no fit`); a refusal passes through. | `allocationLookahead` |
3780
- | a rule over the ready-made fit | An `e3.function` that refuses what the app refuses, then gives `Allocation.fit`'s verdict: the board's ranks and reasons are its. | `allocationFitRule` |
3781
- | `optimise={Func.bind(fn: FunctionDef<[Allocation.Types.OptimiseRequest(R)], Allocation.Types.OptimiseResult(R)>)}` **❗** | The app's optimiser (#1409). The Elara eye in the toolbar, after the issues item and immediately before the history item — at a phone's width, where the row's floor needs its room once the rail's icon has dropped its caret, the View's entry beside the issues, never out of the toolbar: `Stop optimising` while a run is out, off and saying why (`Read-only`) while the day's reads are in flight — names the day (`Optimise Tue, May 11, 2027`): one call per run with the day, the run's number, the day's bins by key as the session holds them — base plus every unapplied draft, every row whatever the rail shows — every arrival as the board reads them and `Allocation.Types.Context`. The history, the drags and every gesture are locked while it is out; a step to another day stops it. Its answer — the bins complete — is diffed by key and recorded as ONE step: Undo in one, Redo replays the landing, Save commits it with everything else. A bin added is an add (its arrival leaves the Arrivals to book), one moved a change with a ghost card at its old lane slot, one dropped a remove with its ghost (its arrival back in Arrivals), one linked or relinked a change with no ghost; each marked on the Timeline's cards, the Table's chips and the narrow cards with its provenance on hover; the lane heads' figures, the Arrivals count and the issues chip flash; for the highlight the Timeline draws the links the run added or changed with nothing selected, outlined in the Elara tone, and the loads of the kilns they land on glow with the cards. A result equal to the request records nothing and says so. The optimisation is joint — a result decides both a bin's slot and its links — and the yard's example optimiser is: a kiln over its maximum gives the excess of its latest bin to the kilns `Allocation.fit` ranks best, a bin not linked or partly allocated is linked, and every load not yet booked is booked into the day's first free bay slot and onto the kilns the fit ranks best, whole on the best fit or split when no one kiln takes it; what no kiln has room for is booked on none. | `allocationOptimise` |
3782
- | **Domain functions and values** | | |
3783
- | `Allocation.loads(R): (day, Day(R), Context) => Dict<String, Load>` | Every resource's fill, bins, hold and state on the day: free, loading or busy. | `allocationDayLoads` |
3784
- | `Allocation.check(R): (day, Day(R), Context) => Array<Issue>` | The built-in checks — Not linked, Partly allocated, Overlaps the next job, Over max, and Under minimum when `rules.under` — each with its fix; the app's `check` follows them wherever issues show. | `allocationChecks` |
3785
- | `Allocation.slots(R): (day, Day(R), Context) => Array<Slot>` | The day's lane slots, one per lane per `every`, in time then lane order, each free, booked or reserved, with its bins; a booking takes the first free one. | `allocationSlots` |
3786
- | `Allocation.Types.{Lane, Status, Bin(R), Day(R), Interval, Job, Detail, Arrival, Resource, Rules, Context, LoadState, Load, Candidate, Refusal, Fit, FitAsk, FitRequest(R), FitResult, OptimiseRequest(R), OptimiseResult(R), Fix, IssueKind, Issue, CheckContext(R), SlotStatus, Slot, Layout}` | The board's reading of the app's rows, carried in requests and stored nowhere. A type over a bin is a constructor of the app's bin row type: the same `R`, the same East type. A bin is `{ lane, at, arrival, quantity, kind, hold, parts, row }`, its roles beside the app's row, `parts` its quantity on each resource, empty while it is not linked; a reservation books no arrival. A day is `{ status, bins }`, its status Schedule's period status. `FitAsk` is `place { subject: bin \| arrival, quantity }` or `take { resource }`, and `FitResult` `{ ask, resources, bins, arrivals, reserve, basis }`. `Fit` and `Refusal` are `Schedule.Types`', the Roster's too. | `allocationKilnYard`, `allocationAnswerTake` |
3787
-
3788
- Every gesture — a drop, a Chooser's choice, a lane or a time step, a quantity,
3789
- a split, a fix, Back to Arrivals, Revert — is one step of one history over the
3790
- bins' and the days' sessions. Discard drops every draft; Save sends each
3791
- record's changes as its own request, and a write with no answer retries the
3792
- same request. A changed bin's row is written through the bin kind's roles,
3793
- every other field as it was; a new one's under a key minted unique
3794
- (`crypto.randomUUID()`), a booking's other fields its arrival's `values` and a
3795
- reservation's their defaults. Drafts of every day stay in their sessions, and
3796
- Save includes them. Publish saves first, then writes the day's status once
3797
- every record reads back as saved; a failed save leaves the day a draft, its
3798
- drafts kept. A bin's quantity may be split across resources: each part is its
3799
- own link, and what the parts leave is unallocated — a Partly allocated issue,
3800
- whose Find a fit asks the fit for the remainder and shows its fits in the
3801
- Library's Resources tab, best first, each with the fit's reason, under a chip
3802
- that clears it (`allocationSplit`). `Split…` is on every bin with something to
3803
- split: it places the remainder, or, on a bin wholly on its resources, takes a
3804
- quantity off its largest part — half of it by default — onto the resource
3805
- chosen, one step (`allocationKilnYard`). Below 480px of main the Timeline is a
3806
- card per resource and the Table a card per row, every action explicit — Book
3807
- an arrival…, Move, Split…, Unlink and Back to Arrivals; Book…, Reserve…,
3808
- Allocate… and a whole bin's Split… — the same commands, the pickers in
3809
- anchored popovers, and nothing drags (`allocationMobile`).
3810
-
3811
- Removed with #1371, each still written refused at build, naming its
3812
- replacement: `days` and `window` (`events={{ <slot>: Schedule.events(…) }}`
3813
- and `periods`, the day's bins read through the slice's bin source);
3814
- `Allocation.Types.Days(V)` and the bin values `V` (the app's own bins and days
3815
- records — `Bin(R)` and `Day(R)` carry the app's row as `row` where they
3816
- carried `values`); `events={Allocation.events(…)}` and `Allocation.events`
3817
- (`arrivals={Allocation.arrivals(…)}`); `Allocation.lanes` and
3818
- `Allocation.resources`, and `lanes` and `resources` as values
3819
- (`resources={{ <lanes>, <resources> }}`, `Schedule.resources` kinds under the
3820
- app's own slots); `publish={false}` (leave `periods` out); `quantity={{ unit
3821
- }}` (the `quantity` role's `unit`); `inspector={{ bin }}` (the bin kind's own
3822
- `inspector`); and `labels.event` and `Allocation.library.events()`
3823
- (`labels.arrival`, "Arrival" by default, and the Arrivals tab,
3824
- `Allocation.library.arrivals()`). `Allocation.Types.Event` is
3825
- `Allocation.Types.Arrival`, and `events` is `arrivals` in the context, the
3826
- fit's ask and its result. The Allocation had shipped in no release, so no
3827
- app's record moves.
476
+ ## Related skills
3828
477
 
3829
- The runnable examples `allocationMinimal`, `allocationKilnYard`,
3830
- `allocationTable`, `allocationLabels`, `allocationPublished`,
3831
- `allocationNoPublish`, `allocationSplit`, `allocationWindowed`,
3832
- `allocationMobile`, `allocationCustomBin` and `allocationFitRule` include their
3833
- record declarations and seeds; `allocationDayLoads`, `allocationRules`,
3834
- `allocationAnswerPlace`, `allocationAnswerTake`, `allocationLookahead`,
3835
- `allocationChecks` and `allocationSlots` run the pure functions over a small
3836
- yard. Search those names in the example index.
478
+ - **e3** — inputs, tasks, records with their indexes and mutations, and the
479
+ dataflow `ui()` builds on; e3-web runs e3 in the page.
480
+ - **east-ui** — the JSX components (`<Reactive>`, `<Table>`, `<Stat>`, …) a
481
+ `ui()` task renders, their formats and status colours.
482
+ - **east** — the language inside `East.function` bodies.
483
+ - **east-ontology** — the `<Ontology>` editor's model and the workshop method.
484
+ - **east-design** — where a decision surface fits in the solution.
485
+ - **e3-ui-cli** — screenshot a surface (`e3-ui shot --from-source` /
486
+ `--from-task`) and browse a repository in the terminal.