@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,18 +1,14 @@
1
1
  ---
2
2
  name: east-ui
3
- description: "Type-safe UI component library for the East language, authored as JSX tags. Use when writing East programs that define user interfaces. Triggers for: (1) Authoring `.tsx` component trees with `@elaraai/east-ui` tags, (2) Layout with (Box), (Flex), (Stack)/(VStack)/(HStack), (Grid), (SnapGrid) (a page of tiles held as data on the 12-column grid, and its wireframe thumbnail), (Splitter), (ScrollArea), (Sticky), (Expandable), (Dock), (Configurator) (control table + live preview + spec readout), (3) Forms with (Input), (Textarea), (Select), (Combobox), (Checkbox), (Switch), (Slider), (RadioGroup), (RadioCardGroup), (TagsInput), (FileUpload), (Field), (DateRangeInput), (TimeRangeInput), (4) Data display with (Table), (TreeView), (ValueTree), (DataList), (Deck), (Matrix), (Map), (Library) (a drag palette, or a gallery of large cards whose media is any component), (Blend), (Slice.Rail), (Pagination), (ChipRail), (Trace), (5) Charts… See the detailed scope below."
3
+ description: "Type-safe UI components for the East language, authored as JSX tags in .tsx files that compile to East IR: layout (Box, Stack, Grid, SnapGrid, Splitter, Dock), forms (Input, Select, Combobox, Slider, Switch, Field, date and time ranges), data display (Table with nested rows, DataList, TreeView, ValueTree, Matrix, Map, Library, Deck, Blend, Slice.Rail), charts (Chart layers Chart.Line/Column/Bar/Area/Scatter/Band with reference lines, Sparkline), overlays (Dialog, Drawer, Popover, Menu, Tooltip, CommandPalette), feedback (Banner, Status, Progress), disclosure (Tabs, Accordion, SegmentGroup), reactive state (Reactive, State.bind, Match), value formats (Format.*, Chart.format.*) and the status colour vocabulary. Use when writing East programs that define user interfaces; binding them to e3 workspace data is e3-ui's."
4
4
  ---
5
5
 
6
- ## Detailed skill scope
7
-
8
- Type-safe UI component library for the East language, authored as JSX tags. Use when writing East programs that define user interfaces. Triggers for: (1) Authoring `.tsx` component trees with `@elaraai/east-ui` tags, (2) Layout with <Box>, <Flex>, <Stack>/<VStack>/<HStack>, <Grid>, <SnapGrid> (a page of tiles held as data on the 12-column grid, and its wireframe thumbnail), <Splitter>, <ScrollArea>, <Sticky>, <Expandable>, <Dock>, <Configurator> (control table + live preview + spec readout), (3) Forms with <Input>, <Textarea>, <Select>, <Combobox>, <Checkbox>, <Switch>, <Slider>, <RadioGroup>, <RadioCardGroup>, <TagsInput>, <FileUpload>, <Field>, <DateRangeInput>, <TimeRangeInput>, (4) Data display with <Table>, <TreeView>, <ValueTree>, <DataList>, <Deck>, <Matrix>, <Map>, <Library> (a drag palette, or a gallery of large cards whose media is any component), <Blend>, <Slice.Rail>, <Pagination>, <ChipRail>, <Trace>, (5) Charts with <Chart layers={Chart.Line/Column/Bar/Area/Scatter/Band(...)}/> (Column = vertical, Bar = horizontal) plus Chart.refLine/refBand/refDot, <Sparkline>, (6) Overlays with <Dialog>, <Drawer>, <Popover>, <Menu>, <Tooltip>, <HoverCard>, <ToggleTip>, <ActionBar>, <CommandPalette>, <Hotkey>, (7) Feedback with <Banner>, <Status>, <Progress>, <Skeleton>, <EmptyState>, (8) Disclosure with <Tabs>, <Accordion>, <Carousel>, <Collapsible>, <SegmentGroup>, <OptionList>, <Story>, (9) Navigation within a page with <Breadcrumb> and <NavList> (an app's own navigation is its host's), (10) Reactive UI via <Reactive>{$ => …}</Reactive> + State.bind, and conditional hosting of stateful components via <Match on cases> (remounts the active variant case on tag change), (11) Value formatting — Chart.format.* specs (chart axes, Slice fields, Deck metrics, e3-ui's Plan) and Format.* specs (<Numeric>, <Stat>, Table columns) through one interpreter, in the viewer's locale (react-aria's I18nProvider) with every date in UTC, (12) Status colour vocabulary — the five status tokens, the Deck.statuses registry, Library.status, rowStatus tints and tone props — and ColorTokenType, the typed colour an app gives for a data fill (a theme hue at a shade, Style.ColorToken("teal", "500")).
9
-
10
6
  # East UI
11
7
 
12
8
  A type-safe UI component library for the East language. The public surface is
13
9
  **JSX tags** — capitalized, React-style components that desugar to East IR. No
14
- React at runtime: a `<Button>` evaluates to the identical
15
- `ExprType<UIComponentType>` value, which serializes and renders anywhere.
10
+ React at runtime: a `<Button>` evaluates to an `ExprType<UIComponentType>`
11
+ value, which serializes and renders anywhere.
16
12
 
17
13
  ## Before writing code — search the example index
18
14
 
@@ -33,11 +29,16 @@ writing or changing East code:
33
29
 
34
30
  Nothing is injected for you; the search is the step.
35
31
 
32
+ For east-ui, search with `package: "east-ui"`: every tag has examples, usually
33
+ a `…Basic` one and a `…Variants` one showing each prop. A prop's full contract
34
+ is in its doc comment, and a factory refuses a wrong shape at build with an
35
+ error that names the fix.
36
+
36
37
  ## Quick Start
37
38
 
38
39
  ```tsx
39
40
  /** @jsxImportSource @elaraai/east-ui */
40
- import { East, IntegerType, NullType, example } from "@elaraai/east";
41
+ import { East } from "@elaraai/east";
41
42
  import { VStack, HStack, Text, Button, UIComponentType } from "@elaraai/east-ui";
42
43
 
43
44
  const MyComponent = East.function([], UIComponentType, (_$) => (
@@ -53,1077 +54,214 @@ const MyComponent = East.function([], UIComponentType, (_$) => (
53
54
  const ir = MyComponent.toIR();
54
55
  ```
55
56
 
56
- Three things make a file JSX-capable:
57
+ What makes a file JSX-capable:
57
58
  1. The per-file pragma `/** @jsxImportSource @elaraai/east-ui */` (first line).
58
- 2. One tag import line from `@elaraai/east-ui`.
59
- 3. A `.tsx` extension.
59
+ 2. `"jsx": "react-jsx"` in the project's tsconfig. A scaffolded project has it;
60
+ in a bare folder, add it, or `tsx` compiles JSX to `React.createElement` and
61
+ fails with `React is not defined`.
62
+ 3. A `.tsx` extension, and the tags imported from `@elaraai/east-ui`.
60
63
 
61
64
  **Tags vs factories.** Each tag desugars 1:1 to a factory call —
62
65
  `<Button variant="solid">Save</Button>` builds the same IR as
63
66
  `Button.Root("Save", { variant: "solid" })`. The factories are an implementation
64
- detail under `@elaraai/east-ui/internal` (used by renderers/tests). **Author with
65
- tags**; props are exactly the factory's flat options bag.
67
+ detail under `@elaraai/east-ui/internal`. Author with tags; props are exactly
68
+ the factory's flat options bag.
66
69
 
67
70
  ## Decision Tree: Which Tag to Use
68
71
 
69
- Every public tag is listed with its purpose, its **Props** (each marked
70
- required / optional) and its **Factories** — the `Component.xyz(…)` builders
71
- that construct that component's config values. Props are the factory's flat
72
- option bag — no nested `style` object. Children are always UI components;
73
- non-UI sub-structures (columns, layers, cells, header fields) are **config
74
- props or typed callbacks**, never child sub-tags.
72
+ Props are the factory's flat option bag — no nested `style` object. Children
73
+ are always UI components; non-UI sub-structures (columns, layers, cells, items)
74
+ are **config props or typed callbacks**, never child sub-tags. An `items` prop
75
+ takes its component's item factory (`Select.Item(value, label)`,
76
+ `SegmentGroup.Item(key, content)`, …), not bare strings.
75
77
 
76
- Two shared prop bags recur; a Props list references them by name instead of
77
- re-listing each member's description:
78
+ Two prop bags recur on layout and display tags:
78
79
 
79
80
  - **BOX bag** (all optional) — `width`, `height`, `minWidth`, `minHeight`,
80
81
  `maxWidth`, `maxHeight`, `padding`, `margin`, `overflow`, `overflowX`,
81
- `overflowY`, `opacity`. CSS sizing/box-model pass-throughs (see the Sizing
82
- pattern below for the string spellings).
83
- - **COLOR overrides** (all optional) — `color`, `background`, `borderColor`.
84
- Explicit escape hatches over the palette / variant defaults; take semantic
85
- tokens (`fg.muted`, `bg.subtle`) or CSS colours.
82
+ `overflowY`, `opacity`. See the Sizing pattern for the string spellings.
83
+ - **COLOR overrides** (all optional) — `color`, `background`, `borderColor`:
84
+ semantic tokens (`fg.muted`, `bg.subtle`) or CSS colours.
86
85
 
87
- Every icon is a Font Awesome **solid** icon (#1263): an icon prop takes
88
- `{ prefix: "fas", name: "…" }`, or the bare solid name where it says so. East
89
- UI draws no other set — a factory refuses another prefix at build, naming the
90
- icon.
86
+ Every icon is a Font Awesome **solid** icon: an icon prop takes
87
+ `{ prefix: "fas", name: "…" }`, or the bare solid name where it says so.
91
88
 
92
89
  ```
93
90
  Task → Which tag?
94
91
  │
95
92
  ├─ Layout (arrange content)
96
- │ ├─ <Box> — generic block container
97
- │ │ └─ Props:
98
- │ │ ├─ children (required) — the boxed content
99
- │ │ ├─ display (optional) — CSS display (block / flex / grid / …)
100
- │ │ ├─ flexDirection / justifyContent / alignItems / gap (optional) — flex props when display is flex
101
- │ │ ├─ flex / flexGrow / flexShrink (optional) — behaviour as a flex CHILD
102
- │ │ ├─ fill (optional) — boolean shorthand for "fill remaining space" (flex:1 + min-height:0)
103
- │ │ ├─ scroll / scrollX / scrollY (optional) — boolean shorthands for a styled scroll region
104
- │ │ ├─ position / top / right / bottom / left / zIndex (optional) — positioning; zIndex is a token
105
- │ │ ├─ borderRadius / border / borderColor / borderWidth (optional) — border styling
106
- │ │ ├─ boxShadow / transform / transition / cursor / animation (optional) — presentation extras
107
- │ │ ├─ fontFamily / fontVariantNumeric (optional) — inherited text styling for the subtree
108
- │ │ ├─ density (optional) — provides "condensed"|"compact"|"comfortable" to densified descendants
109
- │ │ └─ …plus BOX bag + COLOR overrides
93
+ │ ├─ <Box> — generic block container (display, flex, fill / scroll shorthands, position, border, density)
110
94
  │ ├─ <Flex> — flexbox container
111
- │ │ └─ Props:
112
- │ │ ├─ children (required) — flex items
113
- │ │ ├─ direction (optional) — row | column (+reverse)
114
- │ │ ├─ wrap (optional) — nowrap | wrap | wrap-reverse
115
- │ │ ├─ justifyContent / alignItems / gap (optional) — main/cross alignment + spacing
116
- │ │ ├─ density (optional) — density provider (as Box)
117
- │ │ └─ …plus the same flex-child / position / border / presentation props as <Box>, BOX bag, COLOR overrides
118
95
  │ ├─ <Stack> / <VStack> / <HStack> — flex with stacking defaults (VStack = column, HStack = row)
119
- │ │ └─ Props:
120
- │ │ ├─ children (required) — stacked items
121
- │ │ ├─ direction (optional, <Stack> only) — stacking axis
122
- │ │ ├─ gap (optional) — spacing token between items
123
- │ │ ├─ align / justify (optional) — cross/main-axis alignment
124
- │ │ ├─ wrap (optional) — allow wrapping
125
- │ │ ├─ density (optional) — density provider (as Box)
126
- │ │ └─ …plus fill/scroll shorthands, flex-child, position, border, presentation props, BOX bag, COLOR overrides
127
- │ ├─ <Grid> — CSS grid container
128
- │ │ ├─ Props:
129
- │ │ │ ├─ children (required) — grid items (wrap one in Grid.Item to place it)
130
- │ │ │ ├─ templateColumns / templateRows / templateAreas (optional) — grid templates ("repeat(auto-fit, minmax(240px, 1fr))" reflows to 1 column on phones)
131
- │ │ │ ├─ gap / columnGap / rowGap (optional) — grid spacing
132
- │ │ │ ├─ justifyItems / alignItems / justifyContent / alignContent (optional) — item + track alignment
133
- │ │ │ ├─ autoColumns / autoRows / autoFlow (optional) — implicit-track sizing + placement
134
- │ │ │ ├─ density (optional) — density provider
135
- │ │ │ └─ …plus BOX bag (width/height/min*/max*/padding)
136
- │ │ └─ Factories:
137
- │ │ └─ Grid.Item(children, { colSpan?, rowSpan?, colStart?, colEnd?, rowStart?, rowEnd?, area? }) — explicit cell placement for one child
138
- │ ├─ <SnapGrid data={rows} cell={r => SnapGrid.cell({ key, row, span, content })} /> — a page of tiles on the 12-column grid, HELD AS DATA: each row of `data` is one tile. Rows stack in the order their keys first appear; a row's tiles sit left to right, continue on a line below once their spans pass 12 (never overlapping), and the row is as tall as its tallest tile. The spans answer to the SnapGrid's own width, not the viewport: under 480px every tile takes the full width, from 480px a span under 6 takes 6 and any other 12, from 960px the span declared. A framed tile has no header strip, and the SnapGrid draws no border of its own — the host draws the panel around it
139
- │ │ ├─ Props:
140
- │ │ │ ├─ data (required) — the rows: an `Array`, or a `Dict` (tiles in key order), inline or a `$.let`-bound whole-value handle (`State.bind` / `Data.bind`); a paged source is refused — a page's tiles are held whole
141
- │ │ │ ├─ cell (required) — r => SnapGrid.cell({…}): one row's tile, reified once and called per row; pick its `content` per row with a `match` on the row's kind
142
- │ │ │ ├─ variant (optional) — "tiles" (default) | "wireframe": each tile an outline at its size with its content left out, its spans kept at any width and its declared height exact — a page's thumbnail. It draws no frame of its own: its host frames it (a Library gallery card's media) and it fills the host's height. With no rows it is the blank page — a band over the body, each dashed
143
- │ │ │ ├─ width (optional) — the design width ("1440px"): a page's grid is that wide, scrolls inside a narrower host, and its spans answer to it; on the editing canvas it is the most the grid lays out at — a narrower column lays it out at the column's width, a wider one centres it — and the toolbar reads it out
144
- │ │ │ ├─ height / maxHeight (optional) — pin or cap the SnapGrid; the grid scrolls within
145
- │ │ │ ├─ edit + editing (optional, given together) — the builder's canvas: every tile keeps its declared span at any width, and each gesture is a DRAFT of the shared editing session — e3-ui's Sheet's and Plan's — each ONE undoable transaction (origin drop / move / resize / remove); the history item (Undo · Redo · Discard · Save) sits in the canvas's toolbar (see The frame), and ⌘Z / Ctrl+Z undo, ⌘⇧Z / Ctrl+Y redo; the drafts are kept in the tab through a reload, and come back carried over to the source as it is then. Editing takes an `Array` source — its order is the tiles' order, so a move is a new order and a new row key; a `Dict` is refused. `edit` names the row fields a gesture writes: { key: "id" (the String identity field), row: "row" (String), span: "span" (Integer), height?: "height" (Option<Integer>; omitted, heights are not edited), align?: "align" (SnapGrid.Types.Align; the field an align request writes — omitted, one is refused), create?: ($, card, at) => R — a dropped library card's new row: `card` the drag grammar's { library, key }, `at` { key (a fresh identity), row (the row it lands in) }; the canvas then writes `at.row` and fits the span }. `editing` is { onApply? | onUpdate?, onPatch?, onDrafted?, mode?, ready? } as on e3-ui's Plan: `onUpdate={handle.write}` with `data={handle}` is the inline adapter; `onPatch` hears SnapGrid.Types.PatchEvent(R); `onDrafted` fn(Array<R>) => Null hears the rows the canvas draws — the source with its drafts, exactly as Save would leave them — as it mounts and whenever they change (a gesture, an undo or redo, a Discard, a source that moved), so a pane beside it reads what it shows; `ready` fn(R) => Editing.Types.Readiness marks the tile it refuses and holds Save. Save leaves exactly the order the canvas shows
146
- │ │ │ ├─ ui (optional) — the bound selection: `State.bind([SnapGrid.Types.UiState], key, SnapGrid.uiState())` — the canvas draws the tile it holds and writes the one the user picks, so an inspector beside it reads and sets it; omitted, the canvas keeps its own. Its `request` asks the editing canvas for a change, as e3-ui's Plan's `focus` asks for a row: `ui.write(SnapGrid.uiState({ selected: key, request: { key, change: variant("span", 8n) } }))` — `span` (held to the row's room), `row` (counting from 1; a row already holding 6 tiles, or one past the last, is a new row after it), `height` (`none` for its content's), `align` (written to `edit.align`) — taken as ONE gesture of the session by the rules the handles and drags keep, undoable with the rest, and written back `none`
147
- │ │ │ ├─ view (optional) — the bound design width and zoom: `State.bind([SnapGrid.Types.ViewState], key, SnapGrid.viewState())` under a key of its own, apart from `ui` — the editing canvas draws at them and writes the width the user presses and the zoom step they take; omitted, the canvas keeps them, starting from `width` and `zoom`
148
- │ │ │ ├─ apply (optional) — the bound Apply request: `State.bind([SnapGrid.Types.ApplyState], key, variant("idle", null))` under a key of its own — a screen that must not leave drafts behind (a publish) writes `variant("asked", id)` with an id of its own, and the editing canvas saves its drafts as its history item does — waiting out a Save already running, retrying one of unknown outcome — and answers under the same id: `applied(id)` once the source confirms them, or at once with none; `refused({ id, reason })` when they cannot land, `reason` in the canvas's words (the conflict's, the rejection's, a check's, the drafts still being carried over to a source that moved, or the conflicts still to choose). The canvas stays the only writer of its drafts; omitted, only the history item saves
149
- │ │ │ ├─ widths (optional) — [{ label, icon?, width }] the design widths the editing canvas's toolbar offers, a device each (`{ label: "Desktop", icon: "desktop", width: "1440px" }`, `{ label: "Tablet", icon: "tablet-screen-button", width: "1024px" }`): the one the canvas draws at is pressed, and pressing another draws it at that width
150
- │ │ │ ├─ toolbar (optional) — { start?, end? } the host's items in the editing canvas's toolbar, each an array of UIComponents: `start` leads the row (a `<Status>`), `end` closes it (Preview, Publish buttons); they never fold
151
- │ │ │ ├─ panes (optional) — { start?, end? } the panes beside the editing canvas, under its toolbar — a palette, an inspector: a `<Dock surface="shell">` pane collapses to its rail and the canvas column takes the room
152
- │ │ │ ├─ surface (optional) — "card" (default; the editing canvas's own bordered panel) | "shell" (no frame — a canvas inside a host's frame). `view`, `apply`, `widths`, `toolbar`, `panes` and `surface` dress the editing canvas: given without `edit` and `editing`, the build refuses them
153
- │ │ │ ├─ sources (optional) — the Library ids whose cards land on the canvas (`edit.create` builds the row); id (optional) — the drag surface's name in a drop's cell refs; canDrop (optional) — fn(DragEventType) => Boolean, the veto over a card's `add` or a tile's `move` where the drag rests (⊘; a throwing predicate fails open). A drop's cell ref: `row` is the row key, or "" for a new row between rows; `slot` the pointed column "1"–"12", or the gap's index ("0" above the first row, n below the last)
154
- │ │ │ ├─ guides (optional) — draw the column ruler above the rows (the selected tile's columns in brand) and the column bands behind them
155
- │ │ │ └─ zoom (optional) — the scale the canvas draws at (1.0 actual size); the canvas scrolls inside its host
156
- │ │ ├─ The frame (editing): one toolbar across the canvas's width, then the `panes` beside a column holding the selection bar over the grid panel. The toolbar leads with `toolbar.start`, the grid chip ("12 col · snap on") and — once the source confirms a Save — the time it was saved ("Saved · 14:32", UTC); it closes with the width readout ("1440 px"), the zoom (− 100% +, 10% steps from 50% to 150%), the history item, the `widths` and `toolbar.end`. A narrower frame folds it by one ladder: the grid chip first, then the width readout, the saved time, the widths to their icons, and the history item last. The selection bar names the selected tile — its `icon` in a tile, its `label` (else its key) and its `meta` — or says "No selection · Click a component on the grid to arrange it". The history shortcuts work anywhere in the frame, a pane's controls too; a key typed into a field stays the field's
157
- │ │ ├─ The canvas: a click selects a tile (brand border and focus shadow, four corner handles, a span handle on the right edge, a height handle on the bottom edge, the bottom-right corner drags both, and a remove button); Esc or a click on empty canvas clears it. A span drag snaps per column — at least 2, at most 12 less the row's other spans. A height drag snaps to 40px steps, or to a neighbour's bottom edge within 16px while a dashed guide runs across the row; a tile with a `minHeight` shrinks to it, any other stops at its content's height; at most 960; released near its content's height it is auto again. A tile or a card drops beside a tile (a brand line with a "+" badge), between rows, or on the end zone under the last row, each a new row; a tile that takes a row past 12 shrinks to the free columns when that leaves it 3 or more, and otherwise every tile in the row takes ⌊12 / n⌋; a row holds at most 6 tiles (⊘), and a row left empty is gone. Keys: the arrows move the selection; [ and ] change the span by 1; Delete / Backspace remove; tiles drag by keyboard too. A tile's content takes the tile's height — a `<Chart height="fill" …/>` takes the tile's once given one, and its natural height in an auto tile
158
- │ │ └─ Factories:
159
- │ │ ├─ SnapGrid.cell({ key, row, span, height?, minHeight?, align?, frame?, label?, icon?, meta?, content }) — one tile: key (its identity) · row (the key of the row it sits in) · span (columns of 12, held to 1–12) · height (Option<Integer> px; none = its content's height) · minHeight (Option<Integer> px; the least height a height drag leaves it — a chart's plot; none = its content's height) · align ("top" default | "center" | "stretch" — where a shorter tile sits in its row) · frame (default true; false = bare) · label (Option<String>; its name for the drag ghost, the announcements, the history and the selection bar; none = its key) · icon (Option<String>; a Font Awesome solid icon name, the selection bar's tile) · meta (Option<String>; the selection bar's line after its name — what it is, what it reads) · content (the UIComponent it shows)
160
- │ │ ├─ SnapGrid.uiState({ selected?, request? }) — the seed of a bound `ui`, or what a host writes to it: a selection, and a change it asks of the editing canvas (SnapGrid.Types.Request { key, change: span | row | height | align })
161
- │ │ ├─ SnapGrid.viewState({ width?, zoom? }) — the seed of a bound `view`; omitted fields follow the SnapGrid's own `width` and `zoom`
162
- │ │ └─ SnapGrid.Types.{ Root, Cell, Align, Variant, UiState, Request, ViewState, ApplyState, Width, Surface, Place, PatchEvent(R), Editing } — the East types
163
- │ ├─ <Splitter> — resizable panel group
164
- │ │ ├─ Props:
165
- │ │ │ ├─ panels (required) — array of Splitter.Panel(…) values
166
- │ │ │ ├─ defaultSize (required) — initial size percentages, one per panel
167
- │ │ │ ├─ children (required) — one body per panel, in order
168
- │ │ │ ├─ orientation (optional) — horizontal | vertical
169
- │ │ │ ├─ collapseBelow (optional) — container px width below which the panels stack vertically
170
- │ │ │ └─ onResize / onResizeStart / onResizeEnd (optional) — drag lifecycle callbacks (sizes payload)
171
- │ │ └─ Factories:
172
- │ │ └─ Splitter.Panel({ id, minSize?, maxSize?, collapsible?, defaultCollapsed? }) — one panel: id (required), min/max size as percentages, collapsibility
96
+ │ ├─ <Grid> — CSS grid container; Grid.Item(children, { colSpan?, rowSpan?, … }) places one child
97
+ │ ├─ <SnapGrid data={rows} cell={r => SnapGrid.cell({ key, row, span, content })} /> — a page of tiles held as data on the 12-column grid; variant="wireframe" draws its thumbnail; edit + editing make it an editing canvas
98
+ │ ├─ <Splitter> — resizable panel group (collapseBelow stacks it on narrow screens)
173
99
  │ ├─ <Configurator> — labelled control table + live preview + derived spec readout
174
- │ │ ├─ Props:
175
- │ │ │ ├─ controls (required) — array of Configurator.Control(…) / .Slot(…) rows, in display order
176
- │ │ │ ├─ preview (required) — the component being configured
177
- │ │ │ ├─ live (optional) — render the LIVE pip in the preview header (default true)
178
- │ │ │ ├─ aside (optional) — { label, body } secondary panel under the preview
179
- │ │ │ ├─ spec (optional) — extra Configurator.Spec(…) rows for state with no control row of its own
180
- │ │ │ └─ labelWidth / sidebarWidth / previewMinHeight (optional) — sizing overrides
181
- │ │ └─ Factories:
182
- │ │ ├─ Configurator.Control(label, value, control, hint?) — a row that ALSO reports `value` in the spec column
183
- │ │ ├─ Configurator.Slot(label, control, hint?) — a row that reports nothing (use `spec` instead)
184
- │ │ └─ Configurator.Spec(label, value) — one extra spec row
185
100
  │ ├─ <Separator> — 1px rule
186
- │ │ └─ Props:
187
- │ │ ├─ orientation (optional) — horizontal | vertical
188
- │ │ ├─ variant (optional) — subtle | brand | dashed | strong
189
- │ │ ├─ label (optional) — inline label on the rule (string or UIComponent)
190
- │ │ └─ align (optional) — label placement along the rule
191
101
  │ ├─ <ScrollArea> — styled-scrollbar scroll container
192
- │ │ └─ Props:
193
- │ │ ├─ children (required) — scrollable content
194
- │ │ ├─ orientation (optional) — vertical (default) | horizontal
195
- │ │ ├─ scrollbarStyle (optional) — overlay (default) | classic
196
- │ │ └─ thumbColor / trackColor / background (optional) — scrollbar + viewport colours
197
102
  │ ├─ <Sticky> — position-sticky wrapper
198
- │ │ └─ Props:
199
- │ │ ├─ children (required) — the stuck content
200
- │ │ ├─ offset (optional) — CSS length sticky offset (default "0")
201
- │ │ ├─ boundary (optional) — stick to the parent scroll ancestor (default) or the viewport
202
- │ │ └─ background / borderColor / shadowColor (optional) — styling applied while stuck
203
- │ ├─ <Expandable> — region expands in place to fill the app container (CSS takeover, no remount); Esc collapses
204
- │ │ └─ Props:
205
- │ │ ├─ children (required) — the expandable region
206
- │ │ ├─ expanded (optional) — controlled expanded state
207
- │ │ ├─ onExpandedChange (optional) — fn(Boolean) => Null on user toggle
208
- │ │ ├─ label (optional) — accessible toggle name ("Expand ‹label›")
209
- │ │ ├─ zIndex (optional) — stacking level of the expanded surface (default 900, below Chakra floating tiers)
210
- │ │ └─ background (optional) — expanded-surface background (default bg.canvas)
211
- │ └─ <Dock> — inline pane that collapses along an axis to an icon rail, staying in flow (siblings reflow; never overlays) — a source panel beside a drop target (Library beside a Plan); Esc does NOT collapse. Expanded, it has no header strip: its one row is a tab row with the collapse control at its end. Collapsed, it is a rail: the expand control, then the icon in its tile, the badge, the label and the detail running down it
212
- │ └─ Props:
213
- │ ├─ children (required unless `tabs`) — the pane's body, under the `label` as its only tab; not shown when `tabs` are given
214
- │ ├─ tabs (optional) — [{ key, label, body }] the tab row, each tab with its own body: the first open to begin with, the one opened kept under the storage key, every body kept mounted so each keeps its state; ← / → / Home / End move along the row
215
- │ ├─ orientation (optional) — collapse axis: horizontal (default) | vertical
216
- │ ├─ side (optional) — edge the rail pins to: start (default) | end
217
- │ ├─ expandedSize / railSize (optional) — size along the axis expanded (px or %) / collapsed (default 44px)
218
- │ ├─ icon / label / badge (optional) — the rail's icon tile (FA name) / the pane's name: its only tab without `tabs`, the rail's label, and the controls' accessible names ("Collapse ‹label›" / "Expand ‹label›") / the rail's count chip (an empty one draws none, so a computed badge can come and go)
219
- │ ├─ active / detail (optional) — `active` draws the rail's icon tile and badge in the brand, as when the pane shows something (an inspector's selected tile); `detail` is a second line down the rail after the label — what the pane shows now (the tile's name), muted unless `active`
220
- │ ├─ surface (optional) — "card" (default; its own bordered panel) | "shell" (only the rule along its inner edge — a pane inside a host's frame, beside what it serves)
221
- │ ├─ collapsed (optional) — controlled collapsed state
222
- │ ├─ defaultCollapsed (optional) — uncontrolled initial state (default false)
223
- │ ├─ onCollapsedChange (optional) — fn(Boolean) => Null on user toggle
224
- │ ├─ persist (optional) — where the uncontrolled state persists (default none)
225
- │ ├─ keepMounted (optional) — keep the body mounted while collapsed (default true)
226
- │ ├─ lazy (optional) — mount the body only on first expand (default false)
227
- │ └─ animated (optional) — animate the rail↔expanded size change (default false)
228
- │
103
+ │ ├─ <Expandable> — region expands in place to fill the app container (no remount); Esc collapses
104
+ │ └─ <Dock> — inline pane that collapses along an axis to an icon rail, staying in flow (a source panel beside a drop target)
105
+ ├─ Container
106
+ │ └─ <Card> — chrome-bearing content card (vs <Box>, which is structural only)
229
107
  ├─ Typography (display text)
230
108
  │ ├─ <Text> — inline/block text
231
- │ │ ├─ Props:
232
- │ │ │ ├─ children (required) — the text (an East string — see the Text pattern below)
233
- │ │ │ ├─ textStyle (optional) — typographic preset token (body-md, heading-sm, …)
234
- │ │ │ ├─ fontWeight / fontStyle / fontFamily (optional) — face overrides (fontFamily: sans | serif | mono)
235
- │ │ │ ├─ fontVariantNumeric (optional) — e.g. tabular-nums for aligned digits
236
- │ │ │ ├─ textAlign / textDecoration / textTransform (optional) — alignment + decoration + casing
237
- │ │ │ ├─ textOverflow / whiteSpace (optional) — ellipsis / wrapping control
238
- │ │ │ ├─ lineHeight / letterSpacing (optional) — rhythm overrides
239
- │ │ │ ├─ borderWidth / borderStyle (optional) — text-block border (with borderColor)
240
- │ │ │ └─ …plus BOX bag + COLOR overrides
241
- │ │ └─ Factories:
242
- │ │ ├─ Text.Presets.Eyebrow(text, style?) — mono uppercase eyebrow (section labels, status words)
243
- │ │ ├─ Text.Presets.EyebrowSm(text, style?) — smaller eyebrow tier
244
- │ │ ├─ Text.Presets.MonoLabel(text, style?) — mono label (sidebar items, dense frame headers)
245
- │ │ ├─ Text.Presets.MonoSm(text, style?) — small mono annotation
246
- │ │ ├─ Text.Presets.MetaSm(text, style?) — small muted meta line
247
- │ │ └─ Text.Presets.MonoKpi(text, style?) — 24px mono tabular-nums KPI number
248
109
  │ ├─ <Heading> — display heading
249
- │ │ └─ Props:
250
- │ │ ├─ children (required) — the heading text
251
- │ │ ├─ as (optional) — rendered element h1…h6
252
- │ │ ├─ textStyle (optional) — heading preset token
253
- │ │ ├─ fontWeight / fontStyle / fontFamily (optional) — face overrides
254
- │ │ ├─ textAlign / textDecoration / lineHeight / letterSpacing (optional) — alignment + rhythm
255
- │ │ └─ …plus BOX bag + COLOR overrides
256
110
  │ ├─ <Link> — hyperlink
257
- │ │ └─ Props:
258
- │ │ ├─ href (required) — target URL
259
- │ │ ├─ children (required) — link text
260
- │ │ ├─ external (optional) — open in a new tab
261
- │ │ ├─ variant (optional) — underline-on-hover presets
262
- │ │ ├─ colorPalette (optional) — hue theming
263
- │ │ ├─ hoverColor / visitedColor (optional) — state colours
264
- │ │ └─ …plus textDecoration / lineHeight / letterSpacing, BOX bag, COLOR overrides
265
- │ ├─ <Code> — inline code token
266
- │ │ └─ Props:
267
- │ │ ├─ children (required) — the code text
268
- │ │ ├─ variant (optional) — visual preset
269
- │ │ ├─ colorPalette / size (optional) — hue + size
270
- │ │ └─ …plus textDecoration / lineHeight / letterSpacing, BOX bag, COLOR overrides
271
- │ ├─ <CodeBlock> — multi-line code block
272
- │ │ └─ Props:
273
- │ │ ├─ children (required) — the source text
274
- │ │ ├─ language (optional) — syntax-highlight language
275
- │ │ ├─ showLineNumbers / highlightLines (optional) — gutter numbers + highlighted line list
276
- │ │ ├─ showCopyButton (optional) — corner copy affordance
277
- │ │ ├─ wordWrap (optional) — soft-wrap long lines
278
- │ │ ├─ title (optional) — header caption
279
- │ │ ├─ headerBackground / lineNumberColor / highlightBackground (optional) — chrome colours
280
- │ │ └─ …plus BOX bag + COLOR overrides
111
+ │ ├─ <Code> / <CodeBlock> — inline code token / multi-line code block
281
112
  │ ├─ <List items={…}> — bulleted / numbered list
282
- │ │ └─ Props:
283
- │ │ ├─ items (required) — the entries (strings or nested components — a config prop, not JSX children)
284
- │ │ ├─ variant (optional) — ordered | unordered | dot
285
- │ │ ├─ marker / markerIcon / markerColor (optional) — marker glyph styling
286
- │ │ ├─ colorPalette / gap (optional) — hue + item spacing
287
- │ │ └─ …plus BOX bag + COLOR overrides
288
- │ ├─ <Highlight> — tints query substrings inside its text
289
- │ │ └─ Props:
290
- │ │ ├─ children (required) — the full text
291
- │ │ ├─ query (required) — substrings to highlight
292
- │ │ └─ color / background (optional) — highlight ink + wash, plus BOX bag
293
- │ ├─ <Mark> — semantic <mark> span
294
- │ │ └─ Props:
295
- │ │ ├─ children (required) — the marked text
296
- │ │ ├─ variant (optional) — severity preset
297
- │ │ └─ colorPalette + COLOR overrides + BOX bag (all optional)
113
+ │ ├─ <Highlight> / <Mark> — tints query substrings / a semantic <mark> span
298
114
  │ ├─ <Note> — inset callout / quote
299
- │ │ └─ Props:
300
- │ │ ├─ children (required) — note content
301
- │ │ ├─ variant (optional) — visual preset
302
- │ │ ├─ emphasis (optional) — brand | warn | danger
303
- │ │ ├─ accentColor (optional) — the callout stripe colour
304
- │ │ └─ width / maxWidth / padding / margin / opacity + COLOR overrides (all optional)
305
- │ └─ <Numeric> — tabular-num number with sentiment (shares the Formats vocabulary)
306
- │ └─ Props:
307
- │ ├─ value (required) — the raw number
308
- │ ├─ format (optional) — a Format.* spec: Format.Currency({ currency: "EUR" }), Format.Percent(…), Format.Compact(), … (see the Formats branch)
309
- │ ├─ sentiment (optional) — positive | negative | neutral colouring
310
- │ ├─ showSign (optional) — always render the +/− sign
311
- │ ├─ textStyle (optional) — typographic preset
312
- │ └─ signColor / color / background / opacity (optional) — ink overrides
313
- │
115
+ │ └─ <Numeric> — tabular-num number with sentiment, printed through a Format.* spec
314
116
  ├─ Buttons (user actions)
315
- │ ├─ <Button> — the standard action button
316
- │ │ └─ Props:
317
- │ │ ├─ children (required) — label text
318
- │ │ ├─ variant (optional) — solid | subtle | outline | ghost | plain
319
- │ │ ├─ colorPalette / size (optional) — hue + size token
320
- │ │ ├─ onClick (optional) — East.function([], NullType) handler
321
- │ │ ├─ startIcon / endIcon (optional) — leading / trailing icon ({ prefix: "fas", name })
322
- │ │ ├─ loading / loadingText / loadingIcon (optional) — spinner state + swapped label/icon
323
- │ │ ├─ disabled (optional) — blocks interaction
324
- │ │ └─ hoverBackground + COLOR overrides (optional) — palette escape hatches
325
- │ ├─ <IconButton> — icon-only button
326
- │ │ └─ Props:
327
- │ │ ├─ prefix / name (required) — Font Awesome solid icon ("fas", "chevron-right")
328
- │ │ ├─ label (required) — accessible aria-label
329
- │ │ ├─ variant / colorPalette / size (optional) — as Button
330
- │ │ ├─ onClick / loading / loadingIcon / disabled (optional) — as Button
331
- │ │ ├─ badge (optional) — superscript count text ("99+", "" = dot-only)
332
- │ │ ├─ badgeColorPalette (optional) — badge hue (default red)
333
- │ │ ├─ attention (optional) — "pulse" blinks the badge, "ring" rings the button
334
- │ │ └─ hoverBackground + COLOR overrides (optional)
335
- │ ├─ <CloseButton> — × dismiss button
336
- │ │ └─ Props: variant / size / label (aria, default "Close") / disabled / onClick / hoverBackground + COLOR overrides (all optional)
337
- │ ├─ <CopyButton> — copies to clipboard with ✓ feedback
338
- │ │ └─ Props:
339
- │ │ ├─ value (required) — the text copied
340
- │ │ ├─ label (optional) — text next to the copy icon
341
- │ │ ├─ timeout (optional) — "Copied!" duration ms
342
- │ │ ├─ successColor (optional) — confirmation glyph tint
343
- │ │ └─ variant / colorPalette / size / disabled / hoverBackground + COLOR overrides (optional)
344
- │ ├─ <Toggle> — pressable on/off button (NOT a form toggle — see <Switch>)
345
- │ │ └─ Props:
346
- │ │ ├─ pressed (required) — current state (Toggle has no internal state)
347
- │ │ ├─ children (required) — label
348
- │ │ ├─ onChange (optional) — fn(Boolean) => Null
349
- │ │ ├─ icon (optional) — leading icon
350
- │ │ ├─ pressedBackground / pressedColor (optional) — pressed-state colours
351
- │ │ └─ variant / size / disabled + COLOR overrides (optional)
117
+ │ ├─ <Button> — the standard action button (onClick, loading, variant, colorPalette)
118
+ │ ├─ <IconButton> / <CloseButton> / <CopyButton> — icon-only / × dismiss / copy with ✓ feedback
119
+ │ ├─ <Toggle> — pressable on/off button (not a form toggle — see <Switch>)
352
120
  │ └─ <ButtonGroup> — row/col cluster of buttons
353
- │ └─ Props:
354
- │ ├─ children (required) — the buttons
355
- │ ├─ attached (optional) — join into one control with shared borders
356
- │ └─ gap / borderColor (optional) — spacing when not attached; shared border colour when attached
357
- │
358
- ├─ Forms (user input)
359
- │ ├─ <Input> — typed text inputs (namespace tag)
360
- │ │ ├─ Nested tags: <Input.String> <Input.Integer> <Input.Float> <Input.DateTime> — value-typed variants
361
- │ │ └─ Props (shared unless noted):
362
- │ │ ├─ value (required) — current value (String / Integer / Float / DateTime respectively)
363
- │ │ ├─ onChange (optional) — fn(newValue) => Null (typed per variant)
364
- │ │ ├─ onBlur / onFocus (optional) — focus lifecycle
365
- │ │ ├─ variant (optional) — outline | subtle | flushed
366
- │ │ ├─ size (optional) — xs | sm | md | lg
367
- │ │ ├─ disabled (optional) — blocks input
368
- │ │ ├─ autoFocus (optional) — focus on first mount
369
- │ │ ├─ String: placeholder / maxLength / pattern (optional) — text constraints
370
- │ │ ├─ Integer & Float: min / max / step (optional); Float: precision (decimal places)
371
- │ │ ├─ DateTime: min / max / precision (date|time|datetime) / format (token list) (optional)
372
- │ │ └─ focusBorderColor / placeholderColor + COLOR overrides (optional)
121
+ ├─ Forms (user input) — value + onChange, the value usually a State.bind read
122
+ │ ├─ <Input> — typed inputs (namespace tag: Input.String, Input.Float, Input.Integer, Input.DateTime)
373
123
  │ ├─ <Textarea> — multi-line input
374
- │ │ └─ Props:
375
- │ │ ├─ value (required) — current text
376
- │ │ ├─ onChange / onBlur / onFocus / onValidate (optional) — edit + focus callbacks
377
- │ │ ├─ placeholder / rows / maxLength / autoresize (optional) — sizing + constraints
378
- │ │ ├─ resize (optional) — none | vertical | horizontal | both
379
- │ │ ├─ disabled / readOnly / required / invalid (optional) — form state
380
- │ │ └─ variant / size / focusBorderColor + COLOR overrides (optional)
381
- │ ├─ <Select> — single/multi-select dropdown
382
- │ │ ├─ Props:
383
- │ │ │ ├─ value (required) — selected value ("" = none)
384
- │ │ │ ├─ items (required) — array of Select.Item(…)
385
- │ │ │ ├─ onChange (optional) — fn(String) => Null (single)
386
- │ │ │ ├─ onChangeMultiple (optional) — fn(Array<String>) => Null (multi)
387
- │ │ │ ├─ multiple / placeholder / disabled / size (optional) — behaviour + chrome
388
- │ │ │ ├─ onOpenChange (optional) — dropdown open/close callback
389
- │ │ │ └─ COLOR overrides (optional) — trigger colours
390
- │ │ └─ Factories:
391
- │ │ └─ Select.Item(value, label, { disabled? }) — one option
124
+ │ ├─ <Select items={[Select.Item(value, label), …]}> — single/multi-select dropdown
392
125
  │ ├─ <Combobox> — typeahead / filter select
393
- │ │ ├─ Props:
394
- │ │ │ ├─ value (required) — current input / selected value
395
- │ │ │ ├─ items (required) — array of Combobox.Item(…)
396
- │ │ │ ├─ onChange / onChangeMultiple (optional) — selection callbacks (single / multi)
397
- │ │ │ ├─ onInputValueChange (optional) — fires as the user types
398
- │ │ │ ├─ allowCustomValue (optional) — accept values not in the list
399
- │ │ │ ├─ multiple / placeholder / disabled / size / onOpenChange (optional) — as Select
400
- │ │ │ └─ COLOR overrides (optional)
401
- │ │ └─ Factories:
402
- │ │ └─ Combobox.Item(value, label, { disabled? }) — one option
403
- │ ├─ <Checkbox> — boolean checkbox
404
- │ │ └─ Props:
405
- │ │ ├─ checked (required) — current state
406
- │ │ ├─ onChange (optional) — fn(Boolean) => Null
407
- │ │ ├─ label (optional) — trailing text
408
- │ │ ├─ indeterminate (optional) — partial-selection dash
409
- │ │ ├─ disabled / colorPalette / size (optional)
410
- │ │ └─ fillColor / checkColor / borderColor (optional) — slot colours
411
- │ ├─ <Switch> — form on/off toggle (binds a boolean)
412
- │ │ └─ Props:
413
- │ │ ├─ checked (required) — current state
414
- │ │ ├─ onChange (optional) — fn(Boolean) => Null
415
- │ │ ├─ label / disabled / colorPalette / size (optional)
416
- │ │ └─ onColor / offColor / thumbColor (optional) — track + knob colours
417
- │ ├─ <Slider> — range slider
418
- │ │ └─ Props:
419
- │ │ ├─ value (required) — current value
420
- │ │ ├─ onChange (optional) — fires during drag; onChangeEnd (optional) — fires on release
421
- │ │ ├─ min / max / step (optional) — range (defaults 0–100)
422
- │ │ ├─ orientation / variant / colorPalette / size / disabled (optional)
423
- │ │ └─ trackColor / fillColor / thumbColor / markColor (optional) — slot colours
424
- │ ├─ <RadioGroup> — single-select radio list
425
- │ │ └─ Props:
426
- │ │ ├─ value (required) — selected value ("" = none)
427
- │ │ ├─ items (required) — [{ value, label?, disabled? }]
428
- │ │ ├─ onChange (optional) — fn(String) => Null
429
- │ │ ├─ orientation / name / disabled / required / colorPalette / size (optional)
430
- │ │ └─ color / fillColor / borderColor (optional) — ink + radio colours
431
- │ ├─ <RadioCardGroup> — radios rendered as picker cards
432
- │ │ └─ Props:
433
- │ │ ├─ value (required) — selected card value
434
- │ │ ├─ items (required) — [{ value, label, description?, disabled? }]
435
- │ │ ├─ onChange (optional) — fn(String) => Null
436
- │ │ ├─ orientation / name / disabled / required / colorPalette / size (optional)
437
- │ │ └─ color / descriptionColor / cardBackground / selectedCardBackground / selectedBorderColor (optional)
126
+ │ ├─ <Checkbox> / <Switch> — boolean in a list / a form on/off toggle
127
+ │ ├─ <Slider> — range slider (onChange, onChangeEnd)
128
+ │ ├─ <RadioGroup> / <RadioCardGroup> — single-select radio list / radios as picker cards
438
129
  │ ├─ <TagsInput> — typeahead chip input
439
- │ │ └─ Props:
440
- │ │ ├─ defaultValue (optional) — initial tags
441
- │ │ ├─ onChange (optional) — fn(Array<String>) => Null with the new tag set
442
- │ │ ├─ suggestions (optional) — autocomplete list (free entry still allowed)
443
- │ │ ├─ max / maxLength / allowOverflow (optional) — tag-count / length constraints
444
- │ │ ├─ editable / delimiter / addOnPaste / blurBehavior (optional) — editing behaviours
445
- │ │ ├─ onInputChange / onHighlightChange (optional) — typing + highlight callbacks
446
- │ │ ├─ label / placeholder / disabled / readOnly / invalid (optional) — chrome + state
447
- │ │ ├─ variant / size / colorPalette (optional)
448
- │ │ └─ tagBackground / tagColor / tagBorderColor + COLOR overrides (optional) — per-chip colours
449
130
  │ ├─ <FileUpload> — drop-zone file picker
450
- │ │ └─ Props:
451
- │ │ ├─ onFileAccept (optional) — fn(files) => Null; onFileReject (optional) — fn(rejections) => Null
452
- │ │ ├─ accept / maxFiles / maxFileSize / minFileSize (optional) — acceptance constraints
453
- │ │ ├─ directory / allowDrop / capture (optional) — folder upload, drag-drop, mobile camera
454
- │ │ ├─ label / dropzoneText / triggerText / orientation (optional) — copy + layout
455
- │ │ ├─ disabled / required / name (optional) — form state
456
- │ │ └─ variant / size / dropzoneBackground / dropzoneBorderColor / activeBackground + COLOR overrides (optional)
457
131
  │ ├─ <Field> — form-field wrapper (label + control + helper/error)
458
- │ │ └─ Props:
459
- │ │ ├─ label (required) — the field caption; children (required) — the control
460
- │ │ ├─ helperText / errorText (optional) — descriptive + validation lines
461
- │ │ ├─ required / disabled / invalid / readOnly (optional) — form state
462
- │ │ ├─ orientation (optional) — label/control layout
463
- │ │ └─ labelColor / helperTextColor / errorColor / warningColor / infoColor / requiredIndicatorColor (optional)
464
- │ ├─ <DateRangeInput> — start–end date pair with preset chips
465
- │ │ └─ Props:
466
- │ │ ├─ startValue / endValue (required) — the range (UTC DateTime pair)
467
- │ │ ├─ onChange (optional) — fn(start, end) => Null
468
- │ │ ├─ min / max / precision (optional) — bounds + picker precision (date|minute|second)
469
- │ │ ├─ presets (optional) — [{ label, start, end }] preset rows above the inputs
470
- │ │ ├─ disabled (optional)
471
- │ │ └─ variant / size / focusBorderColor + COLOR overrides (optional)
472
- │ └─ <TimeRangeInput> — start–end time pair (minutes since midnight)
473
- │ └─ Props:
474
- │ ├─ startValue / endValue (required) — minutes 0–1439
475
- │ ├─ onChange (optional) — fn(startMin, endMin) => Null
476
- │ ├─ min / max / step (optional) — bounds + picker step (default 15)
477
- │ ├─ presets (optional) — [{ label, start, end }]
478
- │ ├─ disabled (optional)
479
- │ └─ variant / size / focusBorderColor + COLOR overrides (optional)
480
- │
132
+ │ └─ <DateRangeInput> / <TimeRangeInput> — start–end date pair with presets / time pair (minutes since midnight)
481
133
  ├─ Collections (display data sets) — structured data on `data=` / `columns=` / `items=` props
482
- │ ├─ <Table data={rows} columns={…} /> — sortable / pinnable / virtualized data grid; generic pass-through (column/cell inference preserved)
483
- │ │ ├─ Props:
484
- │ │ │ ├─ data (required) — array of row structs, or of RecursiveType rows whose node is a struct (nested with `tree`); or a paged source of either (#576)
485
- │ │ │ ├─ columns (required) — keyed config: ["a","b"] or { a: { header, width, value?, render?, format?, aggregate?, … } }; with no `render` a cell PRINTS ITSELF in the viewer's language (#874): a number keeps every digit, never grouped, with the viewer's decimal separator (1234.5 — German 1234,5; a year or an id prints as stored), a string as it is, anything else as East prints it; `format` — a Format.* spec (Format.Number() groups thousands, Format.Currency({ currency: "EUR" }), Format.Percent(…)) — prints the column's number cells AND a parent's subtotals through it (a `count` prints as a count); column `render` is an East fn ({rowIndex, path, columnKey, cellValue} → UIComponent) called per VISIBLE cell, drawing it instead — full-row access = capture the data array + index it (($, ctx) => { const row = $.let(rows.get(ctx.rowIndex)); … }; a flat table's rowIndex IS the data index, a nested row is reached by its `path`); render/on* fns may capture only data + bind-handles — never a UIComponentType value (beast2 can't serialize it)
486
- │ │ │ ├─ tree (optional) — { children: r => r.lines, collapsed?: true | r => Boolean } rows nest to ANY depth from the data's own tree (#954): `children` returns more of the SAME row type (a RecursiveType row's own field, or a lookup among the rows) — a recursive row reaches every accessor as its node — and a different type is refused at build; a parent IS its group row: its own cells, and in an `aggregate` column ("sum"|"mean"|"min"|"max"|"count") its children's subtotal, composed bottom-up (sum of sums, a mean of means — always a Float — min / max of theirs, `count` the leaf rows beneath), drawn through the column's `render` (its `cellValue` the subtotal) or `format` (a `count` prints itself through neither); a caret before a parent's first cell folds its subtree (persisted by path under the storageKey; `collapsed` is where it starts); a sort orders siblings among themselves, each parent carrying its subtree; rows arrive in PRE-ORDER, and a row's position in it is its `rowIndex`. There is no `groupBy`: group flat rows as a data step before the table; grand totals stay in footerRows
487
- │ │ │ ├─ columnGroups (optional) — column-group heading row (type-checked columnKeys)
488
- │ │ │ ├─ footer / footerRows (optional) — one / many footer rows, keys narrowed to the table's columns
489
- │ │ │ ├─ expandedContent (optional) — fn(rowIndex) => UIComponent expandable row detail (the row's pre-order index — a flat table's data index — stable under sorting AND pagination)
490
- │ │ │ ├─ frozen (optional) — column keys pinned left (visible during horizontal scroll)
491
- │ │ │ ├─ height / maxHeight (optional) — uniform sizing (#320): pin or cap the table; chrome-inclusive, rows scroll within
492
- │ │ │ ├─ variant / size / striped / interactive / stickyHeader / showColumnBorder (optional) — grid chrome
493
- │ │ │ ├─ density (optional) — row rhythm preset; rowHeight (optional) — explicit px override (fed to the virtualizer)
494
- │ │ │ ├─ virtualization / columnResize (optional) — row virtualization + header drag-resize
495
- │ │ │ ├─ selection (optional) — { mode, selected, onChange } embedded row-selection state over pre-order indices (a shift-click range spans the rows as displayed; select-all takes every row in the data)
496
- │ │ │ ├─ pagination (optional) — { pageSize, page, onPageChange } embedded pager over TOP-LEVEL rows, each page holding its rows' whole subtrees
497
- │ │ │ ├─ onCellClick / onCellDoubleClick / onRowClick / onRowDoubleClick / onRowSelectionChange / onSortChange (optional) — interaction callbacks; row events carry `rowIndex` (the pre-order index) and `path` ([i] the i-th top-level row, [i, j] its j-th child)
498
- │ │ │ ├─ rowStatus (optional) — fn(rowIndex) => StatusToken row tint over the pre-order index (see the Statuses branch)
499
- │ │ │ ├─ review / reviewStatus / reviewApproval (optional) — pinned-right Decision column + commitBar foot BELOW the pager; rowIndex is the row's pre-order index
500
- │ │ │ ├─ slice + affordances (optional) — bound slice chrome (default ["filter","search"]); filtering flows through the slice interface
501
- │ │ │ ├─ plotGutter (optional) — shared plot gutter (#147); frozen columns fill `left`
502
- │ │ │ └─ colorPalette + headerBackground / headerColor / zebraBackground / hoverBackground / selectedBackground / selectedBorderColor / footerBackground / borderColor (optional) — chrome colours
503
- │ │ └─ Factories: (columns/footers are plain config objects; no builders)
134
+ │ ├─ <Table data={rows} columns={…} /> — sortable / pinnable / virtualized grid
135
+ │ │ ├─ columns: ["a","b"] or { a: { header, width, value?, render?, format?, aggregate? } }
136
+ │ │ ├─ nested rows from the data's own tree → tree={{ children: r => r.lines, collapsed? }} + a column's aggregate
137
+ │ │ ├─ data: an array of row structs, or a paged source (e3-ui's Data.bindPaged)
138
+ │ │ └─ selection / pagination / frozen / expandedContent / rowStatus / onRowClick … / slice
504
139
  │ ├─ <DataList items={…} /> — label/value pairs
505
- │ │ └─ Props:
506
- │ │ ├─ items (required) — [{ label: String, value: UIComponent }] (plain structs — no builder needed)
507
- │ │ ├─ orientation / size / variant (optional) — pair layout + chrome
508
- │ │ └─ labelColor / valueColor / background / borderColor (optional)
509
140
  │ ├─ <TreeView nodes={…} /> — expandable hierarchical tree with selection
510
- │ │ ├─ Props:
511
- │ │ │ ├─ nodes (required) — array of TreeView.Item / TreeView.Branch values
512
- │ │ │ ├─ selectionMode (optional) — selection cardinality
513
- │ │ │ ├─ defaultExpandedValue / defaultSelectedValue (optional) — initial expansion / selection
514
- │ │ │ ├─ onExpandedChange / onSelectionChange / onFocusChange (optional) — interaction callbacks
515
- │ │ │ ├─ size / variant / animateContent / label (optional) — chrome
516
- │ │ │ └─ itemColor / itemHoverBackground / selectedBackground / selectedColor / caretColor / connectorColor (optional)
517
- │ │ └─ Factories:
518
- │ │ ├─ TreeView.Item(value, label, indicator?) — leaf node (indicator = a Font Awesome solid icon + style)
519
- │ │ └─ TreeView.Branch(value, label, children, indicator?, disabled?) — expandable node
520
- │ ├─ <Plan> — the planning canvas (ONE shared time | number | ordinal axis over heterogeneous rows: event kinds over records, rows laid out by a series list over data, and read-only rows) is e3-ui's (#1177, #1191): `import { Plan } from "@elaraai/e3-ui"` — its props, factories and patterns are in the e3-ui skill
521
- │ ├─ <Sheet> — the planning spreadsheet, always in its builder frame (typed columns over an e3 record's rows, the host's or its rail's `rows` source, a blank tail that invites the next row, typed grammars, an East-function copilot, one `Slice.bindRecords` rail with saved views, an editing session, and a library and an inspector pane, each an optional prop) is e3-ui's (#1179, #1216): `import { Sheet } from "@elaraai/e3-ui"` — its props, factories and patterns are in the e3-ui skill
141
+ │ ├─ <ValueTree value={anyEastValue} /> — editable tree of any East value, from its static type
522
142
  │ ├─ <Matrix data={…} columns={…} cell={(r, col) => Matrix.cell({…})} /> — rows × columns of status-coloured segment bars
523
- │ │ ├─ Props:
524
- │ │ │ ├─ data (required) — row structs, or RecursiveType rows whose node is a struct (nested with `tree`); columns (required) — array of Matrix.column(…) (data-drivable with .map)
525
- │ │ │ ├─ cell (required) — (row, column) => Matrix.cell(…) builder
526
- │ │ │ ├─ rowKey (required) — the row's key, its address in every event (keep keys unique across a nested tree); rowValue / rowSublabel (optional) — the row header's text
527
- │ │ │ ├─ tree (optional) — { children: r => r.members, collapsed?: true | r => Boolean } rows nest to ANY depth from the data's own tree (#955), as on the Table: `children` returns more of the SAME row type (a RecursiveType row's own field, or a lookup among flat rows — `r => people.filter((_$, p) => p.team.equal(r.name))`); a parent is a FULL row — its header indented with a fold caret, and its own cells from the same `cell` builder (no aggregates: a parent's bars are whatever its row builds); the caret folds its subtree (persisted by path under the storageKey). There is no `groupBy`: group flat rows as a data step
528
- │ │ │ ├─ rowHeader (optional) — header label for the left identity column
529
- │ │ │ ├─ orientation (optional) — default segment orientation
530
- │ │ │ └─ legend (optional) — explicit legend entries [{ fill, label }] (omitted ⇒ auto-derived)
531
- │ │ └─ Factories:
532
- │ │ ├─ Matrix.column({ key, label? }) — one x-axis column
533
- │ │ ├─ Matrix.cell({ segments?, markers?, orientation?, slot?, popover? }) — one cell (slot = arbitrary UIComponent; popover = click body)
534
- │ │ ├─ Matrix.segment({ fill?, weight, label?, color?, min?, max?, step? }) — one segment of the cell bar
535
- │ │ └─ Matrix.marker({ status?, message, at?, label? }) — corner status marker
536
- │ ├─ <Schematic> — the 2D world-coordinate drawing of the app's own records (items, zones, links and nets, each a kind over a record, placed where its row says; a camera, layers and selection) is e3-ui's (#1384, #1386): `import { Schematic } from "@elaraai/e3-ui"` — its props, factories and patterns are in the e3-ui skill
537
- │ ├─ <Flowchart> — the state-transition flowchart (states in ORDERED phase lanes, its layout derived — no coordinates; H/V-routed transitions; per-link decision triggers and evidence) is e3-ui's (#1243): `import { Flowchart } from "@elaraai/e3-ui"` — its props, factories and patterns are in the e3-ui skill
538
- │ ├─ <Map markers={…} center={Map.at(lat,lng)} zoom={n} /> — interactive geographic basemap; read-only / selection-only
539
- │ │ ├─ Props:
540
- │ │ │ ├─ markers + center + zoom (required) — marker rows + initial camera
541
- │ │ │ ├─ marker / area / line / label (optional) — row mappers for each table (omit when rows are already Map.Types.* values)
542
- │ │ │ ├─ areas / lines / labels (optional) — the additional overlay tables
543
- │ │ │ ├─ hexes (optional) — H3 lattice + per-cell detail (Map.hex(…))
544
- │ │ │ ├─ overlays (optional) — positioned East children (Map.overlay(child, { align }))
545
- │ │ │ ├─ tiles (optional) — basemap (default Map.carto("positron"))
546
- │ │ │ ├─ minZoom / maxZoom / lodZoom / fitBounds (optional) — zoom clamps, detail-LOD threshold, camera framing
547
- │ │ │ ├─ onAreaClick / onMarkerClick / onZoom / onSelect (optional) — interaction callbacks
548
- │ │ │ └─ scrollWheelZoom / attributionPrefix / height (optional) — chrome
549
- │ │ └─ Factories:
550
- │ │ ├─ Map.at(lat, lng) — a coordinate; Map.point(…) / Map.bounds(…) — flyTo targets
551
- │ │ ├─ Map.carto(style) / Map.osm() / Map.tile(url, …) — basemaps
552
- │ │ ├─ Map.hexDisk(…) / Map.cells(…) / Map.polygon(…) — H3 shapes; Map.hex(…) — the hex layer
553
- │ │ ├─ Map.marker(…) / Map.area(…) / Map.line(…) / Map.label(…) — overlay values
554
- │ │ ├─ Map.solid() / Map.dashed() — line styles
555
- │ │ └─ Map.overlay(child, { align }) — a positioned East child
556
- │ ├─ <Library id="people" data={rows} item={r => ({…})} /> — draggable palette (DnD source; targets list its id in their `sources`) under ONE toolbar row; a card drags by pointer or by KEYBOARD, announced — see the Drag and drop pattern. `variant="gallery"` draws the same cards LARGE, each with its `media` — any UI component — the library a person browses: a page library (each page's `<SnapGrid variant="wireframe">`), a report catalog (a `<Sparkline>` each)
557
- │ │ ├─ Props:
558
- │ │ │ ├─ id (required) — DnD source identity
559
- │ │ │ ├─ data (required) — item rows
560
- │ │ │ ├─ item (required) — row mapper to { key, label, sublabel?, icon?, status?, trailing?, draggable?, filtered?, placed?, media?, avatar?, byline?, action? } — `trailing` a glyph at the card's right edge (`some(Library.glyph(…))`: a lock on something fixed, a dot for a status); `placed` draws the card in its placed state, the brand border and tint (the item already on the target — say how often in its sublabel). A gallery card's own: `media` (any UIComponent, drawn inert — the card is the click target), `avatar` (the name whose initials the foot's avatar shows), `byline` (the foot's line after it), `action` (a label in the link voice at the foot's end, "Open in builder →", which a click on the card follows — `onCardClick`); a gallery card's `trailing` sits at its foot's end
561
- │ │ │ ├─ variant (optional) — "compact" (default; a line per card — the palette a surface drags from) | "gallery" (a large card per item: its `media` above the face or at its start, the name with its status as a dot and the word, the meta line, and a foot holding the `avatar`, `byline` and `action`). A compact Library refuses the gallery's fields at build, naming each
562
- │ │ │ ├─ layout (optional, gallery) — the layout a gallery starts in: "grid" (default; the style's `columns` across, fewer as the Library narrows, one on a phone) | "list" (a card per row, its media at the start). The toolbar's Grid · List switch changes it, and the viewer's pick is kept with the toolbar under the storage key; an expression that moves moves it
563
- │ │ │ ├─ toolbar (optional) — true (default) | false: no toolbar row, the cards sitting in their host's frame — for a host whose ONE toolbar serves several Libraries (a page library's Templates and Pages): the host narrows `data` itself and gives a gallery its `layout`, which the Library then follows. The options whose controls live in the toolbar — `search`, `groupBy`, `filters`, `dimensions`, `hint` and `slice` — are refused with it at build, naming each
564
- │ │ │ ├─ hint (optional) — a caption at the toolbar row's end (the first thing a narrow row folds away)
565
- │ │ │ ├─ dimensions + defaultDimensions (optional) — toolbar-toggleable card facts ({ kind: "meter" | "chips" | "text", … }); initially-visible keys (default first two)
566
- │ │ │ ├─ groupBy (optional) — [{ key, label, value, summary? }] GROUP BY options (omit for flat)
567
- │ │ │ ├─ filters (optional) — [{ key, label, values: r => Array<String> }] the toolbar's Filter menu: each facet's distinct values, in the order the cards first hold them (one value for a single-valued facet like a category, several for its tags); checked values keep the cards holding one of them (OR within a facet, AND across facets), the rest hide as the search's do and the group counts follow; the trigger counts the checked values ("Filter · 2"), and the footer's Show all clears them with the search
568
- │ │ │ ├─ search (optional) — filter-text accessor; unmatched cards hide (footer shows hidden count + Show all)
569
- │ │ │ ├─ noun (optional) — { singular, plural } what the items are called — the search box counts them ("Search 47 components…"; default item / items)
570
- │ │ │ ├─ onCardClick (optional) — fn(key) => Null when a card is clicked (a drag never clicks); a card that cannot be dragged is then a button, so Enter / Space click it too
571
- │ │ │ ├─ addLabel + onAdd (optional) — footer action; a gallery's dashed last card
572
- │ │ │ ├─ slice + affordances (optional) — bound slice chrome (default ["filter","search"])
573
- │ │ │ └─ style (optional) — { height, maxHeight, virtualization, columns?, mediaPlacement?, mediaSize? } — the last three a gallery's (refused on a compact Library): `columns` its cards across in the grid (Integer, default 3), `mediaPlacement` "top" (default, above the face) | "start" (at its start), `mediaSize` a CSS length — the media's height on top, its width at the start ("156px"). A gallery mounts every card (no virtualization)
574
- │ │ ├─ The toolbar: ONE row, the shared toolbar every toolbar host lays its chrome in — the search box (⌘ / focuses it) and GROUP · …, then at its end the `hint`, SECONDARY, FILTER and a gallery's Grid · List switch (a radio group: one tab stop, ← / → move and pick); with `slice` chrome the rail's affordances lead the same row, a `search` among them in place of the built-in one. A narrower row folds on one ladder: the rail first, then the hint goes, SECONDARY and FILTER fold to their icons, then GROUP does, and last the search box narrows and drops its key cap; the switch never folds. `toolbar: false` draws no row
575
- │ │ └─ Factories:
576
- │ │ ├─ Library.status(label, tone, ring?) — a card status: a compact card's chip, a gallery card's dot and word (tone = a status token; see the Statuses branch); `ring` draws the dot open, a state not reached yet (a Draft beside a Live)
577
- │ │ └─ Library.glyph(icon, label, tone?) — a card's trailing glyph: an FA icon, the words it says (its accessible name and tooltip), and an optional status tone (else the card's quiet ink, the brand ink while placed)
578
- │ ├─ <Deck data={rows} statuses={Deck.statuses({…})} card={r => ({ key, title, status, metrics, fill })} /> — grouped mini-card board (display, NOT a drag source — that's Library); every card carries an EXPLICIT status colour from the deck's STATUS REGISTRY (solid tag + dot, faint face wash, fill-bar colour); two card states: the LIST face + a VIEW state in an anchored POPOVER CARD whose head is inherited from the face
579
- │ │ ├─ Props:
580
- │ │ │ ├─ data (required) — array of rows to project into cards
581
- │ │ │ ├─ card (required) — accessor r => face fields: key (required; identity reported by onCardClick/onOpen) · title (required; identity line) · sublabel (muted mono-uppercase second line) · icon (FA solid name) · status (a KEY into `statuses` — paints the tag/wash/fill) · metrics ([Deck.metric(…)] raw-value strip) · fill ({ value, max, format? } status-coloured bar; format = shared spec over value OR (value, max) => String accessor; omitted → percentage) · facts ([Deck.meter/chips/text(…)]) · filtered (render dimmed — the Slice.partition "keep the excluded" feed)
582
- │ │ │ ├─ statuses (optional) — the status registry, Deck.statuses({…}); card `status` fields reference entries by key
583
- │ │ │ ├─ groupBy (optional) — [{ key, label, value, summary? }] named GROUP BY toolbar + None; grouping by the status accessor decorates group heads with the registry swatch + hint
584
- │ │ │ ├─ layout (optional) — "grid" (default; wrap auto-fill minmax(minCardWidth,1fr) → one phone column) | "list" (full-width rows)
585
- │ │ │ ├─ onClick (optional) — r => <…/> the STICKY popover's BODY (tap opens; Esc / outside / × close); the head — title, sublabel, icon, status tag + wash — is INHERITED from the card face
586
- │ │ │ ├─ onHover (optional) — r => <…/> the transient hover peek's body (hover-capable pointers only, intent-delayed)
587
- │ │ │ ├─ onOpen (optional) — fn(key) => Null; fires when a card's popover opens
588
- │ │ │ ├─ onClose (optional) — fn() => Null; fires once per popover close (Esc / outside / ×)
589
- │ │ │ ├─ onCardClick (optional) — fn(key) => Null; cards are tap targets even without popover content
590
- │ │ │ ├─ render (optional) — r => <…/> fully custom card body beneath the structured face
591
- │ │ │ ├─ footer (optional) — [{ label, value }] board-foot key/value stats
592
- │ │ │ ├─ legend (optional) — boolean; renders the registry legend (swatch + label + hint)
593
- │ │ │ ├─ slice + affordances (optional) — slice={handle} + affordances (default ["filter","search"] — brush/legend/breakdown rejected) mounts the rail + count footer; feed data via Slice.rows (remove) or Slice.partition → filtered (dim); filtering/search flow through the slice interface like Table — no bespoke search
594
- │ │ │ └─ style (optional) — { height, maxHeight, minCardWidth, virtualization }; height/maxHeight make the board its own (virtualized) scroll region, flat AND grouped
595
- │ │ └─ Factories:
596
- │ │ ├─ Deck.statuses({ key: { label, color, pulse?, hint? } }) — build the status registry; color is a standard status token "success"|"warning"|"danger"|"info"|"neutral" OR any custom CSS colour (the faint face tint is derived); pulse animates the tag dot (active states); hint feeds the legend + group heads
597
- │ │ ├─ Deck.metric(label, value, { format?, warn? }) — one metric cell: the RAW Float (or Option Float) value plus a shared format — a Chart.format.* spec or a v => String accessor (same vocabulary as chart axes); a none value renders "—"; warn paints the value in the danger tone
598
- │ │ ├─ Deck.Readout([{ label, value, format?, unit?, warn? }]) — popover readout rail: a bordered grid of big mono values with unit suffixes (raw values + shared format, like Deck.metric)
599
- │ │ ├─ Deck.Rows([{ label, value }]) — popover key/value detail rows (mono-uppercase keys, body-voice values)
600
- │ │ ├─ Deck.Note(text) — popover dashed-top mono footnote
601
- │ │ ├─ Deck.meter(label, value, max, text) — card-face meter fact (utilisation bar + right-aligned reading)
602
- │ │ ├─ Deck.chips(label, values) — card-face chip-set fact
603
- │ │ └─ Deck.text(label, text) — card-face dim text fact
604
- │ ├─ <ValueTree value={anyEastValue} /> — editable tree of ANY East value, materialized from its STATIC type at authoring time (structs/arrays/dicts/options/variants → branches; primitives → typed editable leaves; sets/blobs/vectors/matrices/refs/fns → read-only summaries; non-string-keyed dict entries label as field summaries and edit their VALUES — entry add/remove stays string-keyed)
605
- │ │ ├─ Props:
606
- │ │ │ ├─ value (required) — the East value to render; omit every callback for a read-only inspector
607
- │ │ │ ├─ onUpdate (optional) — fn([T], Null) whole-value handler: receives the WHOLE value with the edit applied (the factory rebuilds it for you); sync or async
608
- │ │ │ ├─ at (optional) — [ValueTree.at(T, probe, fn)] scoped subtree handlers; deepest matching scope wins, unmatched edits bubble to onUpdate
609
- │ │ │ ├─ onEdit (optional) — RAW path callback (escape hatch; overrides per event): fn(path, leaf) => Null leaf edit
610
- │ │ │ ├─ onInsert (optional) — RAW append/insert: array append paths end with an `append` step, dict adds carry the new `key`
611
- │ │ │ ├─ onRemove (optional) — RAW remove with the element/entry path
612
- │ │ │ ├─ onTag (optional) — RAW variant switch + option set/clear ("some"/"none")
613
- │ │ │ └─ style (optional) — { height, maxHeight, openDepth, toolbar }; bounded trees virtualize rows; openDepth = how many levels start expanded (default 1; 0 = all collapsed), toolbar adds a Collapse all / Expand all header row; Alt-click any twist collapses that whole subtree
614
- │ │ └─ Factories:
615
- │ │ ├─ ValueTree.at(T, p => p.machines.entry("m1"), fn([SubT], Null)) — a typed scope: struct fields as properties, .item(i), .entry(k), .some()
616
- │ │ ├─ ValueTree.zero(T) — the default element for inserts (delegates to East defaultValue)
617
- │ │ └─ ValueTree.Types.{Root, Node, Path, Step, Leaf, Style} — the East types for RAW callbacks
618
- │ ├─ <Roster> — the weekly staffing builder is in e3-ui: `import { Roster } from "@elaraai/e3-ui"`. Shifts day/week and People week, bound weeks/staff/configuration, shared Slice and editing; the former east-ui Roster and Board are removed.
619
- │ ├─ <Blend targets={…} config={{…}} /> — blend / batch assembly surface; pairs with a Library; target count picks the mode: 1 single | 2 compare (derived diff / Δ table) | 3+ portfolio
620
- │ │ ├─ Props:
621
- │ │ │ ├─ targets + id (required) — target rows + DnD target identity
622
- │ │ │ ├─ target (optional) — row mapper to Blend target fields (omit when already Blend.Types.Target)
623
- │ │ │ ├─ sources (optional) — Library ids accepted for add-drops
624
- │ │ │ ├─ diff (optional) — compare mode: metric keys for the foot table (default all); verdict (optional) — compare verdict line
625
- │ │ │ ├─ onDrag + canDrop (optional) — add/remove drag funnel + IR drop veto (⊘)
626
- │ │ │ ├─ onAmountChange (optional) — allocation amount edits
627
- │ │ │ └─ onAction (optional) — panel actions; the action foot rides the shared commitBar (Apply = approve-primary, Discard = reject-danger, Reset plain — apply/discard are the panel-scope review verbs)
628
- │ │ └─ Factories:
629
- │ │ ├─ Blend.allocation({ source, amount, pinned?, state? }) — one allocation line
630
- │ │ └─ Blend.metric({ key, label, value, numeric?, model?, band? }) — one target metric
631
- │ ├─ <Slice.Rail slice={slice} affordances={[…]} /> — shared narrowing chrome over one bound dataset; feed consumers via Slice.rows
632
- │ │ ├─ Props:
633
- │ │ │ ├─ slice (required) — the bound handle from Slice.bind
634
- │ │ │ ├─ affordances (optional) — ["filter","search","range","breakdown","cohort","presets","brush","legend"]; legends are explicit-only (list "legend" or compose <Slice.Legend>)
635
- │ │ │ ├─ persist (optional) — "local" | "session" | "url" opts the state into reload-surviving / shareable-link storage
636
- │ │ │ └─ brush (optional) — the brush strip is rich by default (the range field's format drives the axis labels; a self-excluding count histogram shows the row distribution); brush={{ axis?, count?, buckets? }} opts down to the bare track. The applied window is a full brush selection: drag its body to slide (width preserved), an edge to resize, empty track to draw (also the Plan's horizon-brush gesture). Its look is the horizon brush's (#1438): bars of one width toned on the heat ramp by count, whole inside the window's band and faded outside it, an outlined tab on each edge, and a hover's tooltip saying a bin's range and count; the start handle, the window and the end handle are three tab stops — ← → move a bin, Shift ten, Home / End the ends, Esc clears
637
- │ │ ├─ Nested tags: <Slice.Filter/Search/Range/Breakdown/Legend/Cohort/Presets/Summary slice={slice} /> — per-affordance chrome; <Slice.Cohort mode="toggle"|"manage" allowCreate? group?> (cohorts toggle on chip click; cohorts sharing a `group` render as one captioned run — a FAMILY of alternatives: active members OR within a family, families AND with each other and with standalone cohorts; an empty family member hides on the preset bar unless on; `group="…"` shows one family alone; <Slice.Presets> = toggle-only preset bar); <Slice.Legend> = facet bar (click = in-set multi-select over self-excluding slice.facetGroups(); mode="visibility" = eye rail); Summary/Filter footers read "N of M"
638
- │ │ └─ Factories:
639
- │ │ ├─ Slice.bind(key, rows, options?) — local Array rows; infers the row type. Options: fields (label/hints/format), range, search, initial, presets, breakdown and match. Initial/preset clauses name typed fields; local operators include gte/contains. The positional form is removed.
640
- │ │ ├─ Slice.bindRecord(key, indexed, options?) — Data.bindPaged(record, { indexes }) from e3-ui; fields/range/search/initial/presets come from declared field indexes: a field is any row field an index is led by, whatever its name — `area` and `__tile` included, e3's parts of a generated key being its index's kind's (#1432). No browser predicate, local operators, match or breakdown. Several exact values then one range/prefix must follow one index; a Set field takes one exact member. A source's `pageWhere`/`countWhere` take a read, `{ where, area }`: the narrowing, and a read by area's window or unplaced clause beside it, none for any other read.
641
- │ │ ├─ Slice.bindRecords(key, { name: { source: indexed, fields?, range?, search?, initial? }, … }, { presets? }) — several records narrowed from ONE rail: one Slice.bindRecord per named source under `${key}.${name}`; a choice in one source never changes another's rows or counts (no index relates two records). Presets narrow any sources at once (a source a preset doesn't name is cleared); slice.togglePreset(id) / slice.clearAll() act on every part. A component that narrows several kinds of row takes it as slice={{ slice }} with its sources named after them (the e3-ui Allocation's `lanes` and `resources`) and reads each source itself.
642
- │ │ ├─ Slice.config(Row, { fields, rangeFieldId?, searchFieldIds?, breakdownFieldIds? }) / Slice.state({…}) — low-level config/state for pure Slice.apply and state operations; bind options infer and seed these automatically.
643
- │ │ ├─ Slice.rows(slice) — the narrowed Array for local rows, or for records a live ordered source: one per binding whatever the narrowing, its windows read under the narrowing as it stands, its `query()` naming it (#1354); record entries retain original key beside tagged ik, covering value and optional joined row. Slice.rows(slice, source) reads one source of a Slice.bindRecords handle.
644
- │ │ ├─ Slice.partition([Row], slice) — the FULL set tagged [{value, matched}] (the "keep the excluded" feed — drive a de-emphasis effect from `matched`)
645
- │ │ ├─ Slice.apply.where / .matches / .breakdown — the pure filter engine (string ops eq/neq/in/notIn/contains/matches/startsWith/endsWith/isEmpty/isNotEmpty; integer in; datetime between)
646
- │ │ └─ slice.toggleFilter(pred) — idempotent single-predicate toggle for custom wiring; Range picker presets anchor to the DATA's date extent (clamped to now for live data) and pin concrete windows; an All chip clears the range; programmatic datetimePreset seeds stay rolling/wall-clock
647
- │ └─ <Pagination> — page-number control
648
- │ └─ Props:
649
- │ ├─ page / pageSize / count (required) — current page, rows per page, total rows
650
- │ ├─ onPageChange (required) — fn(newPage) => Null
651
- │ ├─ siblings / boundaries (optional) — ellipsis control
652
- │ └─ size / variant / activeBackground / activeColor + COLOR overrides (optional)
653
- │
143
+ │ ├─ <Map markers={…} center={Map.at(lat,lng)} zoom={n} /> — geographic basemap; read-only / selection-only
144
+ │ ├─ <Library id="…" data={rows} item={r => ({…})} /> — draggable palette (a drag source), or variant="gallery": large browsable cards whose media is any component
145
+ │ ├─ <Deck data={rows} statuses={Deck.statuses({…})} card={r => ({ key, title, status, metrics, fill })} /> — status-coloured mini-card board (display, not a drag source)
146
+ │ ├─ <Blend targets={…} config={{…}} /> — blend / batch assembly surface fed by a Library; 1 target single, 2 compare, 3+ portfolio
147
+ │ ├─ <Slice.Rail slice={slice} affordances={[…]} /> — narrowing chrome over one bound dataset (Slice.bind); consumers read Slice.rows(slice)
148
+ │ ├─ <Pagination> — page-number control
149
+ │ └─ <Plan>, <Sheet>, <Calendar>, <Roster>, <Allocation>, <Flowchart>, <Schematic> — the planning builders are e3-ui's (`import { Plan } from "@elaraai/e3-ui"`)
654
150
  ├─ Charts (visualize data) — layers are a config array of factory values, never child tags
655
- │ ├─ <Chart layers={…} /> — assemble mark + annotation layers; x-scale inferred from the x accessor type (String → band, number → linear, DateTime → time)
656
- │ │ ├─ Props:
657
- │ │ │ ├─ layers (required) — array of Chart.Line/Column/Bar/Area/Scatter/Band/refLine/refBand/refDot/Series values
658
- │ │ │ ├─ x / y / y2 (optional) — axis options: { label?, format? (shared spec — see the Formats branch), domain?, scale?, numTicks?, tickValues?, hideTicks?, hideLine?, tickStyle?, titleStyle?, titleGap? }
659
- │ │ │ │ tickValues (#318): floats on a linear axis ([0,1,2,…]) or DateTime[] on a time axis (pin ticks to exact instants, rendered through the date format); Date ticks on y/y2 are a build-time error
660
- │ │ │ │ tickStyle/titleStyle (#315): { fontSize?, fontFamily?: "sans"|"serif"|"mono", fontWeight?, color?, letterSpacing? } — restyle ticks/captions over the spec chrome
661
- │ │ │ │ titleGap (#327): px between ticks and caption — widens that axis's OWN margin band, never the shared plot gutter, so nudging a title can't shift a gutter-aligned plot lane
662
- │ │ │ ├─ height (optional) — px, or "fill": the parent's height, never less than the chart's natural height — what a parent sized by its content (an auto SnapGrid tile) shows it at; width (optional) — px (omit for responsive)
663
- │ │ │ ├─ grid / legend / tooltip (optional) — background gridlines (default on) / colour-matched legend / hover tooltip
664
- │ │ │ ├─ stackOffset (optional) — "none" | "expand" (percent stacking)
665
- │ │ │ └─ slice + affordances (optional) — bound slice chrome (default ["breakdown","range"]; the brush sets the slice's range)
666
- │ │ └─ Factories:
667
- │ │ ├─ Chart.Line / Chart.Column / Chart.Area / Chart.Scatter(rows, encoding, style?) — marks; encoding: { x, y } · { x, y, by } (split) · { x, columns: { Name: r => r.field } } (wide)
668
- │ │ ├─ Chart.Bar(rows, { x: numeric, y: category }, style?) — HORIZONTAL bars (band y-axis, linear x; flips the whole frame; same { x, y, by } / { y, columns } splits; can't mix with vertical marks); the left margin grows to hold the widest category label, so a parent that clips never cuts one
669
- │ │ ├─ Chart.Band(rows, { x, low, high }, style?) — filled range (e.g. confidence band)
670
- │ │ ├─ mark style (all optional) — { key (legend label), color, curve, width, dash, dots, fillOpacity, opacity, legend, tooltip, stack (group id — layers sharing one stack accumulate), axis: "left"|"right", order (draw order) }; Scatter adds size (uniform px radius; a per-point size accessor overrides)
671
- │ │ ├─ Chart.refLine({ y }|{ x }, label?, dash?) — reference line
672
- │ │ ├─ Chart.refBand({ y: [lo, hi] }|{ x: [lo, hi] }, label?) — reference band
673
- │ │ ├─ Chart.refDot({ x, y, label? }) — reference marker
674
- │ │ ├─ Chart.format.{ number, currency, percent, compact, date, time, datetime } — the SHARED format specs (see the Formats branch)
675
- │ │ └─ Chart.Series(slice, { x, value, mark? }) — a slice-bound layer (x/value are slice field ids; mark: "line"|"bar"|"area"|"scatter", default line)
676
- │ └─ <Sparkline> — inline trend beside a <Stat>
677
- │ └─ Props:
678
- │ ├─ data (required) — the values
679
- │ ├─ type (optional) — line | area
680
- │ └─ color / height / width (optional)
681
- │
151
+ │ ├─ <Chart layers={[…]} x? y? y2? grid? legend? tooltip? /> — x-scale inferred from the x accessor (String → band, number → linear, DateTime → time); give it a height (a sized parent, or height)
152
+ │ │ ├─ Chart.Line / Chart.Column / Chart.Area / Chart.Scatter(rows, encoding, style?) — encoding { x, y } · { x, y, by } (split) · { x, columns: { Name: r => r.field } } (wide)
153
+ │ │ ├─ Chart.Bar(rows, { x: numeric, y: category }, style?) — HORIZONTAL bars (Column is the vertical one); can't mix with vertical marks
154
+ │ │ ├─ Chart.Band(rows, { x, low, high }, style?) — filled range (a confidence band)
155
+ │ │ ├─ Chart.refLine({ y }|{ x }, label?, dash?) · Chart.refBand({ y: [lo, hi] }|{ x: [lo, hi] }, label?) · Chart.refDot({ x, y, label? })
156
+ │ │ ├─ axis options x / y / y2: { label?, format?, domain?, scale?, numTicks?, tickValues? }
157
+ │ │ └─ Chart.Series(slice, { x, value, mark? }) — a slice-bound layer
158
+ │ └─ <Sparkline data type? /> — inline trend beside a <Stat>
682
159
  ├─ Display (show information)
683
- │ ├─ <Badge> — mono uppercase micro-label (status / taxonomy); stays a tier smaller than tags
684
- │ │ └─ Props: variant (solid|subtle|outline) / colorPalette / size / density / borderRadius / borderWidth / borderStyle / justifyContent / alignItems + BOX bag + COLOR overrides (all optional; children required)
685
- │ ├─ <Tag> — operator-set keyword / filter pill (body font)
686
- │ │ └─ Props:
687
- │ │ ├─ children (required) — the tag text
688
- │ │ ├─ closable + onClose (optional) — × affordance + callback
689
- │ │ └─ variant / colorPalette / size / density / borderRadius / borderWidth / borderStyle + BOX bag + COLOR overrides (optional)
160
+ │ ├─ <Stat label value format? /> — metric tile: the raw value with a Format.* spec, plus change indicator
161
+ │ ├─ <MetricChip> — compact inline delta chip
162
+ │ ├─ <Badge> / <Tag> — mono uppercase micro-label (status / taxonomy) / operator-set keyword pill
690
163
  │ ├─ <Avatar> / <AvatarGroup> — user avatar / overlapping cluster with "+N more"
691
- │ │ └─ Props:
692
- │ │ ├─ Avatar: src (image URL) / name (initials fallback) / variant / colorPalette / size / density / borderRadius + BOX bag + COLOR overrides (all optional)
693
- │ │ └─ AvatarGroup: children (required) — the avatars; max (optional) — overflow threshold (+N after); size / density / borderColor (optional)
694
- │ ├─ <Image> — raster/vector image or logo
695
- │ │ ├─ Props:
696
- │ │ │ ├─ source (required) — Image.url(u) | Image.dataUri(s) | Image.blob(bytes, "png"|"svg"|…)
697
- │ │ │ ├─ fit (optional) — object-fit: contain | cover | fill | none | scaleDown
698
- │ │ │ ├─ aspectRatio / alt / borderRadius / background (optional) — framing + accessibility
699
- │ │ │ └─ …plus BOX bag
700
- │ │ └─ Factories:
701
- │ │ ├─ Image.url(u) — hosted image
702
- │ │ ├─ Image.dataUri(s) — self-contained base64
703
- │ │ └─ Image.blob(bytes, format) — raw BlobType bytes → revocable object URL
704
- │ ├─ <Icon> — a Font Awesome solid icon (East UI draws no other set, #1263)
705
- │ │ └─ Props:
706
- │ │ ├─ prefix / name (required) — the icon: "fas", the solid set, and its name; another prefix is refused at build, naming the icon
707
- │ │ ├─ variant (optional) — solid, the one set
708
- │ │ ├─ size (optional) — xs…2xl; label (optional) — accessible name
709
- │ │ └─ colorPalette / borderRadius + BOX bag + COLOR overrides (optional)
710
- │ ├─ <Kbd> — keyboard-shortcut chip (⌘ K)
711
- │ │ └─ Props: children (required); variant / size / density / colorPalette / shadowColor + COLOR overrides (optional)
712
- │ ├─ <Stat> — metric tile with label / value / change indicator
713
- │ │ └─ Props:
714
- │ │ ├─ label (required) — metric caption; value (required) — the raw value (Float / Integer / String)
715
- │ │ ├─ format (optional) — a Format.* spec over a numeric value: Format.Currency({ currency: "USD", maximumFractionDigits: 0n }), Format.Compact(), … (see the Formats branch)
716
- │ │ ├─ helpText (optional) — caption beneath the value
717
- │ │ ├─ baseline / delta / info (optional) — secondary line / change pill / ⓘ ToggleTip trigger (UIComponents)
718
- │ │ ├─ indicator (optional) — "up"|"down"|"flat" or { direction, sentiment?: positive|negative|neutral, icon? }
719
- │ │ ├─ density / size (optional) — rhythm + size preset
720
- │ │ └─ valueColor / labelColor / helpTextColor / indicatorColor (optional)
721
- │ ├─ <MetricChip> — compact mono delta chip
722
- │ │ └─ Props:
723
- │ │ ├─ children (required) — the value text; tone (required) — positive | negative | neutral | info (drives the palette)
724
- │ │ ├─ unit (optional) — suffix ("%", "ms"); icon (optional) — leading icon
725
- │ │ ├─ emphasis (optional) — subtle | solid | outline
726
- │ │ └─ density / size / borderRadius / iconColor + COLOR overrides (optional)
727
- │ ├─ <Meter> — horizontal capacity bar with sentiment colour (never a bare bar — value text on by default)
728
- │ │ └─ Props:
729
- │ │ ├─ value (required) — current value; max (optional) — full-bar value (default 100)
730
- │ │ ├─ tone (optional) — a status token driving the fill (see the Statuses branch)
731
- │ │ ├─ label (optional) — UIComponent beside the bar; showValue (optional) — trailing mono percent (default true)
732
- │ │ └─ density / thickness / borderRadius / fillColor / trackColor / labelColor (optional)
733
- │ ├─ <SegmentedMeter> — multi-segment meter (e.g. decomposed confidence)
734
- │ │ └─ Props:
735
- │ │ ├─ segments (required) — [{ value, tone?, color?, label? }]
736
- │ │ ├─ caption (optional) — UIComponent beside the bar; max (optional) — total reference (default sum)
737
- │ │ ├─ labels (optional) — inside | outside | none
738
- │ │ └─ density / thickness / borderRadius / trackColor / captionColor / labelColor (optional)
739
- │ ├─ <BarStrip items={[…]} /> or <BarStrip data={rows} item={r => ({ label, value, tone? })} /> — ranked horizontal-bar list (axis-free; fits inside a <Stat>)
740
- │ │ └─ Props:
741
- │ │ ├─ items (required, the written form) — [{ label (UIComponent), value, tone?, color?, trailing? }]
742
- │ │ ├─ data + item (required, the data form — instead of items) — an East array of the host's rows + a row mapper to the same bar fields, reified ONCE into an East function every row maps through: bars computed in East (a groupSum's totals, `.toArray`'d), which a written array cannot hold
743
- │ │ ├─ showValues (optional) — trailing value text (default true)
744
- │ │ ├─ sort / maxItems (optional) — sort + row cap, applied by the renderer to written and mapped bars alike
745
- │ │ └─ density / orientation / thickness / borderRadius / trackColor / labelColor / valueColor (optional)
746
- │ ├─ <EditableChip> — chip whose text becomes inline input on click
747
- │ │ └─ Props:
748
- │ │ ├─ children (required) — chip text
749
- │ │ ├─ onClick (optional) — activation callback; trigger (optional) — trailing icon (default chevron)
750
- │ │ └─ disabled / density / size / borderRadius / triggerIconColor + COLOR overrides (optional)
751
- │ ├─ <ChipRail> — horizontal rail of mixed chip-shaped children (<Tag>/<Badge>/<MetricChip>/<Avatar>/…); provides its density to the children
752
- │ │ └─ Props:
753
- │ │ ├─ children (required) — the chips
754
- │ │ ├─ separator (optional) — dot | line; labels (optional) — per-chip labels
755
- │ │ ├─ overflow (optional) — behaviour when the rail can't fit every chip (⋯ menu)
756
- │ │ └─ density / separatorColor / overflowTriggerColor / background (optional)
757
- │ └─ <Trace> — read-only inline heatmap (tracks × steps) with a now-line; sits flush beside a <ChipRail> at the same density in table cells
758
- │ └─ Props:
759
- │ ├─ tracks (required) — [{ name, values }] (heat normalises per track's own min/max)
760
- │ ├─ now (optional) — step index of the now-line; [0, now) measured, [now, end) predicted; omit for measured-only
761
- │ ├─ scale (optional) — heat colour encoding; future (optional) — how predicted steps are distinguished
762
- │ ├─ axis (optional) — per-step labels (ruler at comfortable density, tooltips always)
763
- │ ├─ density / brandColor / nowLineColor / labelWidth (optional) — rhythm + colour + name-gutter width
764
- │ └─ plotGutter (optional) — shared gutter (#147): pins the step lane so a Trace stacked under a Chart lines up (left supersedes labelWidth)
765
- │
164
+ │ ├─ <Image> / <Icon> / <Kbd> — image or logo / Font Awesome solid icon / keyboard-shortcut chip
165
+ │ ├─ <Meter> / <SegmentedMeter> — capacity bar with sentiment colour / decomposed meter
166
+ │ ├─ <BarStrip data={rows} item={r => ({ label, value, tone? })} /> — ranked horizontal-bar list, axis-free (fits a <Stat>)
167
+ │ ├─ <EditableChip> — chip whose text becomes an inline input on click
168
+ │ ├─ <ChipRail> — rail of mixed chip-shaped children; provides its density to them
169
+ │ └─ <Trace> — read-only inline heatmap (tracks × steps) with a now-line
766
170
  ├─ Feedback (status & async signals)
767
- │ ├─ <Banner> — page-spanning notice, the design system's Banner card: one row centred on itself — the status's mark (a triangle for warning/guard, a circle for error, else its 8px dot), the title as its message in the body face at 13, the description under it, the actions at its end (one Default button makes it 48 tall)
768
- │ │ └─ Props:
769
- │ │ ├─ status (required) — info | warning | success | error | neutral | change | guard | stale
770
- │ │ ├─ title (required) — string or UIComponent
771
- │ │ ├─ description / actions (optional) — body + trailing actions
772
- │ │ ├─ icon / showIcon (optional) — explicit icon override / hide the paired icon
773
- │ │ ├─ dismissible + onDismiss (optional) — close affordance
774
- │ │ └─ variant / size / iconColor / accentColor + COLOR overrides (optional)
775
- │ ├─ <Status> — dot + uppercase label (no fill)
776
- │ │ └─ Props:
777
- │ │ ├─ label (required) — string or UIComponent
778
- │ │ ├─ value (optional) — success | warning | danger | info | neutral (default neutral; see the Statuses branch)
779
- │ │ ├─ pulsing (optional) — animate the dot
780
- │ │ ├─ ring (optional) — an open ring in place of the filled dot: a state that is not live yet (a Draft beside a Live)
781
- │ │ ├─ icon / showIcon (optional) — icon override / hide
782
- │ │ └─ size / dotColor + COLOR overrides (optional)
171
+ │ ├─ <Banner status title subtitle? icon? dismissible?> — page-spanning notice (staleness, partial data)
172
+ │ ├─ <Status value> — dot + uppercase word
783
173
  │ ├─ <Progress> — linear progress bar
784
- │ │ └─ Props:
785
- │ │ ├─ value (required) — current value
786
- │ │ ├─ min / max (optional) — range (defaults 0–100)
787
- │ │ ├─ indeterminate (optional) — unknown-% mode
788
- │ │ ├─ label / valueText / showValue (optional) — captions
789
- │ │ ├─ estimatedDuration / startedAt (optional) — drive an ETA display
790
- │ │ ├─ tone (optional) — brand | pos | neg (bsys-restricted fill tone)
791
- │ │ └─ variant / size / striped / animated / trackColor / fillColor / labelColor (optional)
792
174
  │ ├─ <Skeleton> — shimmer placeholder
793
- │ │ └─ Props:
794
- │ │ ├─ shape (required) — text | rect | circle
795
- │ │ ├─ lines (optional) — line count (text shape); count (optional) — repeat in a VStack
796
- │ │ └─ width / height / fontSize / background / shimmerColor (optional)
797
175
  │ └─ <EmptyState> — zero-data state
798
- │ └─ Props:
799
- │ ├─ title (required) — string or UIComponent
800
- │ ├─ icon (optional) — its one mark, a Font Awesome solid icon ({ prefix: "fas", name: "inbox" }); a text `glyph` is removed (#1263) and refused at build
801
- │ ├─ description / actions (optional) — body + action row
802
- │ └─ size / iconColor + COLOR overrides (optional)
803
- │
804
176
  ├─ Disclosure (reveal / switch content) — item metadata is config, not child tags
805
177
  │ ├─ <Tabs items={…}> — content-panel switcher
806
- │ │ ├─ Props:
807
- │ │ │ ├─ items (required) — array of Tabs.Item(…)
808
- │ │ │ ├─ value / defaultValue (optional) — controlled / initial selected tab
809
- │ │ │ ├─ onValueChange (optional) — fn(String) => Null
810
- │ │ │ ├─ variant (optional) — line | plain; size — sm | md | lg
811
- │ │ │ ├─ orientation / activationMode / fitted / justify (optional) — layout + keyboard behaviour
812
- │ │ │ ├─ lazyMount / unmountOnExit (optional) — panel mount policy
813
- │ │ │ └─ colorPalette / listBackground / indicatorColor / activeTriggerColor / inactiveTriggerColor / contentBackground (optional)
814
- │ │ └─ Factories:
815
- │ │ └─ Tabs.Item(value, title, body, { disabled? }) — one tab
816
178
  │ ├─ <Accordion items={…}> — single/multi-open sections
817
- │ │ ├─ Props:
818
- │ │ │ ├─ items (required) — array of Accordion.Item(…)
819
- │ │ │ ├─ multiple / collapsible (optional) — allow multiple open / allow all closed
820
- │ │ │ ├─ value / defaultValue / onValueChange (optional) — controlled expansion
821
- │ │ │ └─ variant / size / triggerBackground / triggerHoverBackground / contentBackground + COLOR overrides (optional)
822
- │ │ └─ Factories:
823
- │ │ └─ Accordion.Item(value, trigger, children, { meta?, disabled? }) — one section (meta = right-aligned header caption)
824
179
  │ ├─ <Carousel> — paginated slide carousel
825
- │ │ └─ Props:
826
- │ │ ├─ children (required) — the slides
827
- │ │ ├─ index / defaultIndex / onIndexChange (optional) — controlled slide position
828
- │ │ ├─ slidesPerView / slidesPerMove / spacing (optional) — layout
829
- │ │ ├─ loop / autoplay / allowMouseDrag (optional) — behaviour
830
- │ │ ├─ showIndicators / showControls (optional) — dots + prev/next chrome
831
- │ │ └─ orientation / padding / indicatorColor / activeIndicatorColor / controlColor / controlBackground (optional)
832
- │ ├─ <Collapsible> — single show/hide section
833
- │ │ └─ Props:
834
- │ │ ├─ trigger (required) — always-visible header (string or UIComponent); children (required) — the body
835
- │ │ ├─ defaultOpen / onOpenChange (optional) — initial state + toggle callback
836
- │ │ └─ triggerColor / contentColor + COLOR overrides (optional)
180
+ │ ├─ <Collapsible> / <Disclosure> — single show/hide section / "Show more / Show less" toggle
837
181
  │ ├─ <SegmentGroup items={…}> — compact single-select mode switcher (no panels)
838
- │ │ ├─ Props:
839
- │ │ │ ├─ value (required) — selected segment; items (required) — array of SegmentGroup.Item(…)
840
- │ │ │ ├─ onChange (optional) — fn(String) => Null
841
- │ │ │ └─ size / colorPalette / orientation / activeBackground / activeColor / inactiveColor + COLOR overrides (optional)
842
- │ │ └─ Factories:
843
- │ │ └─ SegmentGroup.Item(value, label, { disabled? }) — one segment
844
182
  │ ├─ <OptionList> — keyboard-navigable single-select list (rows + description)
845
- │ │ ├─ Props:
846
- │ │ │ ├─ options (required) — array of OptionList.Option(…)
847
- │ │ │ ├─ selectedId (optional) — currently-selected row; onSelect (optional) — fn(id) => Null
848
- │ │ │ └─ itemColor / itemHoverBackground / selectedBackground / borderColor / impactColor (optional)
849
- │ │ └─ Factories:
850
- │ │ └─ OptionList.Option(id, label, { description?, trailing?, disabled? }) — one row (trailing = e.g. impact chip)
851
- │ ├─ <Story.Root steps={…}> — scroll-driven narrative; prose rail + sticky stage keyframes
852
- │ │ ├─ Props:
853
- │ │ │ ├─ steps (required) — array of Story.Step(…)
854
- │ │ │ ├─ layout (optional) — rail-left | rail-right | stacked
855
- │ │ │ ├─ stepLength (optional) — compact | default | long (scroll runway per step)
856
- │ │ │ ├─ stageHeight / height (optional) — stage sizing
857
- │ │ │ ├─ active / progress (optional) — State.bind bindings for narrative position + within-step scrub
858
- │ │ │ ├─ activeStep (optional) — static override: render one deterministic keyframe by step id
859
- │ │ │ ├─ title (optional) — renders the Story.Progress chrome row
860
- │ │ │ └─ onStepEnter / onStepExit (optional) — step activation callbacks (step id)
861
- │ │ └─ Factories:
862
- │ │ ├─ Story.Step(body, { id, eyebrow?, title?, stage? }) — one beat (stage = its sticky keyframe)
863
- │ │ └─ Story.Progress({ count, active?, title? }) — standalone dots / counter / prev-next chrome
864
- │ └─ <Disclosure> — "Show more / Show less" toggle
865
- │ └─ Props:
866
- │ ├─ children (required) — the truncatable text
867
- │ ├─ lines (optional) — visible lines before truncation
868
- │ ├─ moreLabel / lessLabel (optional) — trigger copy
869
- │ └─ color / triggerColor (optional)
870
- │
871
- ├─ Navigation — within a page; an app's own navigation is its host's (#1227)
872
- │ ├─ <Breadcrumb items={…}> — ancestor trail with '/' separators
873
- │ │ └─ Props:
874
- │ │ ├─ items (required) — [{ label, current (Option Bool), onClick (Option fn) }] trail entries
875
- │ │ ├─ leadingSeparator (optional) — adds a leading '/' so it reads as a path (/ workspace / page)
876
- │ │ └─ runAnchor (optional) — trailing run stamp pinned after a vertical rule
183
+ │ └─ <Story.Root steps={…}> — scroll-driven narrative; prose rail + sticky stage keyframes
184
+ ├─ Navigation — within a page; an app's own navigation is its host's
185
+ │ ├─ <Breadcrumb items={…}> — ancestor trail
877
186
  │ └─ <NavList sections={…}> — sidebar nav
878
- │ └─ Props:
879
- │ ├─ sections (required) — [{ label?, items: [{ key, label, icon?, badge?, active? }] }], or an East `Array<NavList.Types.Section>` computed from data (items built with `East.value({…}, NavList.Types.Item)`) — a rail of the pages a record holds
880
- │ ├─ onSelect (optional) — fn(key) => Null
881
- │ ├─ surface (optional) — "card" (default, bordered) | "shell" (drops the card chrome so the list reads as one surface with a host app-shell rail)
882
- │ └─ background (optional) — surface background token (bg.subtle)
883
- │
884
- ├─ Overlays (floating content) — `trigger` is a UIComponent prop; body is children
885
- │ ├─ <Dialog> — the one modal: a confirmation step before a destructive or irreversible act, naming it, with Cancel and the act's own verb — never a form (a form that makes or names something is a <Popover> from its trigger)
886
- │ │ └─ Props:
887
- │ │ ├─ trigger (required) — the opening UIComponent; children (required) — the body
888
- │ │ ├─ eyebrow / title / description (optional) — header copy (eyebrow = mono uppercase, e.g. "Confirm · cannot be undone")
889
- │ │ ├─ size / placement / scrollBehavior / motionPreset / role (optional) — presentation
890
- │ │ ├─ open / defaultOpen / onOpenChange (optional) — controlled state: `open={asking.read()} onOpenChange={asking.write}` opens it from any callback
891
- │ │ ├─ closeOnInteractOutside / closeOnEscape (optional) — behaviour; it is always modal, traps focus and holds the page still
892
- │ │ ├─ lazyMount / unmountOnExit (optional) — mount policy
893
- │ │ └─ onExitComplete / onEscapeKeyDown / onInteractOutside (optional) — lifecycle callbacks
187
+ ├─ Overlays (floating content) — `trigger` is a UIComponent prop; the body is children
188
+ │ ├─ <Dialog> — the one modal: a confirmation before a destructive or irreversible act, never a form
189
+ │ ├─ <Popover> — click-triggered panel; a form that makes or names something lives in one
894
190
  │ ├─ <Drawer> — side panel
895
- │ │ ├─ Props:
896
- │ │ │ ├─ trigger (required) — the opening UIComponent; children (required) — the body
897
- │ │ │ ├─ placement (optional) — start | end | top | bottom; size — panel size; contained — render within the parent container
898
- │ │ │ ├─ eyebrow / title / description (optional) — header copy
899
- │ │ │ ├─ bodyPadding / flush (optional) — body padding control (flush = full-bleed so a Table/Plan fills)
900
- │ │ │ ├─ fillBody (optional) — the body becomes a definite-height flex column so a single height:100% child fills + owns its scroll
901
- │ │ │ ├─ stacked + stackIcon (optional) — (#328) while a deeper drawer is open, this drawer collapses to a labeled vertical icon rail (instead of hiding behind) — click the rail to pop the stack back to it; Esc pops one level
902
- │ │ │ ├─ open / defaultOpen / onOpenChange / onExitComplete (optional) — controlled state + lifecycle
903
- │ │ │ └─ closeOnInteractOutside / closeOnEscape / lazyMount / unmountOnExit (optional) — behaviour + mount policy
904
- │ │ └─ Factories:
905
- │ │ └─ Drawer.open(OpenInput) — open one programmatically (nests/stacks by depth)
906
- │ ├─ <Popover> — click-triggered floating panel; a form that makes or names something (a name, then Cancel and its commit) lives in one, hanging from the control that starts it
907
- │ │ └─ Props:
908
- │ │ ├─ trigger (required); children (required) — the panel body
909
- │ │ ├─ title / description (optional) — header copy
910
- │ │ ├─ size / placement / hasArrow / gutter (optional) — positioning + chrome
911
- │ │ ├─ open / defaultOpen / onOpenChange (optional) — controlled state: `open={shown.read()} onOpenChange={shown.write}` opens it from any callback, at its own trigger
912
- │ │ └─ closeOnInteractOutside / closeOnEscape / autoFocus / lazyMount / unmountOnExit (optional) — it is never modal
913
- │ ├─ <HoverCard> — hover preview card
914
- │ │ └─ Props:
915
- │ │ ├─ trigger (required); children (required) — the card body
916
- │ │ ├─ title / description (optional) — mono eyebrow header (same as Popover)
917
- │ │ ├─ openDelay / closeDelay (optional) — hover timing
918
- │ │ └─ size / placement / hasArrow / open / defaultOpen / onOpenChange / lazyMount / unmountOnExit (optional)
919
- │ ├─ <Tooltip> — hover tooltip (content is a string)
920
- │ │ └─ Props: trigger (required) / content (required) / placement / hasArrow (optional)
921
- │ ├─ <ToggleTip> — click-toggle tooltip (sticky)
922
- │ │ └─ Props: trigger (required) / children (required) / placement / hasArrow / open / defaultOpen / onOpenChange / closeOnInteractOutside / closeOnEscape (optional)
191
+ │ ├─ <HoverCard> / <Tooltip> / <ToggleTip> — hover preview card / hover tooltip (a string) / click-toggle tooltip
923
192
  │ ├─ <Menu trigger={…} items={…}> — dropdown / context menu
924
- │ │ ├─ Props:
925
- │ │ │ ├─ trigger (required) — the opening element; items (required) — array of Menu.Item / Menu.Separator
926
- │ │ │ └─ placement (optional) — position relative to the trigger
927
- │ │ └─ Factories:
928
- │ │ ├─ Menu.Item(value, label, { disabled?, icon?, command?, destructive? }) — one action (icon = FA solid name; command = right-aligned mono accelerator "⌘D"; destructive renders in the negative ink)
929
- │ │ └─ Menu.Separator() — a group divider
930
193
  │ ├─ <CommandPalette commands={…}> — ⌘K palette with search + groups
931
- │ │ └─ Props:
932
- │ │ ├─ commands (required) — [{ id, label, icon?, shortcut?, group?, keywords?, action }] (action = fn() => Null)
933
- │ │ ├─ placeholder / triggerKey (optional) — search copy + global open chord ("mod+k")
934
- │ │ ├─ open / onOpenChange (optional) — controlled state
935
- │ │ └─ size / inputBackground / inputColor / itemColor / selectedBackground / selectedColor / groupLabelColor + COLOR overrides (optional)
936
- │ ├─ <Hotkey chord="mod+k" onTrigger={fn}> — invisible keydown listener (no render)
937
- │ │ └─ Props:
938
- │ │ ├─ chord (required) — modifiers mod/ctrl/cmd/shift/alt + key
939
- │ │ └─ onTrigger (required) — East.function([], NullType); pair with Reactive + State.bind to drive open state on CommandPalette/Dialog/Drawer
194
+ │ ├─ <Hotkey chord="mod+k" onTrigger={fn}> — invisible keydown listener
940
195
  │ └─ <ActionBar items={…}> — sticky bottom bulk-action bar
941
- │ ├─ Props:
942
- │ │ ├─ items (required) — array of ActionBar.Item(…)
943
- │ │ ├─ selectionCount / selectionLabel (optional) — "N items selected" copy; the bar is open while the count is above 0
944
- │ │ ├─ open / onOpenChange (optional) — controlled state, in place of the count's
945
- │ │ ├─ onSelect (optional) — fn(actionValue) => Null when an action is chosen
946
- │ │ └─ closeOnInteractOutside / closeOnEscape (optional)
947
- │ └─ Factories:
948
- │ └─ ActionBar.Item(value, label, disabled?) — one action button
949
- │
950
- ├─ Container
951
- │ └─ <Card> — chrome-bearing content card (vs <Box> which is structural-only)
952
- │ └─ Props:
953
- │ ├─ children (required) — the body
954
- │ ├─ header (optional) — { eyebrow?, meta?, title?, description? } strict option object composed into the header strip
955
- │ ├─ footer (optional) — { content?, actions? } footer strip (actions = trailing button row)
956
- │ ├─ state (optional) — "ready" | "loading" | "empty" | "error" | "stale" | "disabled" | "permission-denied" runtime state
957
- │ ├─ variant (optional) — elevated | outline | subtle
958
- │ ├─ density (optional) — density provider for the body
959
- │ ├─ bodyPadding / flush (optional) — body padding (default "18px 20px"); flush = full-bleed so a Plan / Table / Chart fills
960
- │ ├─ accentColor / headerBackground / footerBackground (optional) — chrome colours
961
- │ ├─ height / minHeight / maxHeight / width / minWidth / maxWidth / flex / overflow (optional) — sizing (a sized Card becomes a flex column constraining its body — see the Sizing pattern)
962
- │ └─ background / borderColor (optional)
963
- │
964
- ├─ Formats (value formatting — one interpreter, in the viewer's locale; #190, #850)
965
- │ ├─ The contract: a format-bearing prop takes a SPEC and the payload keeps the RAW value; the renderer prints it at render through ONE interpreter, in the viewer's LOCALE, every date in UTC. Two spec vocabularies — Chart.format.* and Format.* — and a shared arm prints the same whichever one declared it
966
- │ ├─ Chart.format.* (`Chart.Spec.Types.TickFormat`) — chart axes, Slice fields, Deck, the Plan:
967
- │ │ ├─ Chart.format.number() — plain number, grouped in the locale (1,234.5; German 1.234,5)
968
- │ │ ├─ Chart.format.currency({ code?, compact? }) — currency; compact ⇒ $1.8M (one fraction digit)
969
- │ │ ├─ Chart.format.percent() — 0.42 → 42% (whole percents)
970
- │ │ ├─ Chart.format.compact() — 12400 → 12.4K (one fraction digit)
971
- │ │ └─ Chart.format.date(pattern) / Chart.format.time(pattern) / Chart.format.datetime(pattern) — East date-token patterns
972
- │ ├─ Format.* (`Format.Types.Tick`) — <Numeric>, <Stat>, <Table> columns:
973
- │ │ ├─ Format.Number({ minimumFractionDigits?, maximumFractionDigits?, signDisplay? }) · Format.Currency({ currency, display?, compact?, minimumFractionDigits?, maximumFractionDigits? }) · Format.Percent({ minimumFractionDigits?, maximumFractionDigits?, signDisplay? }) · Format.Compact({ display? }) · Format.Unit({ unit, display? }) · Format.Scientific() · Format.Engineering()
974
- │ │ └─ Format.Date(pattern) / Format.Time(pattern) / Format.DateTime(pattern) — East date-token patterns
975
- │ ├─ Where each plugs in:
976
- │ │ ├─ <Chart> x/y/y2 { format } — axis tick labels; an undeclared time axis prints the locale's numeric date (6/29/2026; German 29.6.2026)
977
- │ │ ├─ Slice.config fields { format } — filter chips, brush axis labels, range summaries (string shorthands "number"|"percent"|"compact"|{currency:{code?,compact?}}|{date|time|datetime: pattern} also accepted)
978
- │ │ ├─ <Numeric format> and <Stat format> — KPI values (Format.*)
979
- │ │ ├─ <Table columns={{ c: { format } }}> — a column's number cells and a parent's subtotals (Format.*); an undeclared number cell prints every digit, never grouped, with the viewer's decimal separator
980
- │ │ ├─ Deck.metric / Deck.Readout cells / card fill { format } — board metrics (Chart.format.*)
981
- │ │ ├─ e3-ui's Plan.axis { format } — timeline tick labels (a date pattern on a time axis; Chart.format.* on a number axis)
982
- │ │ ├─ e3-ui's Plan.quantity { format } and Plan.heatCells / weightCells / segmentCells { format } — a run's or a link's caption, and the values a heat arm prints (Format.*)
983
- │ │ └─ e3-ui's Sheet.column.quantity(R, D, { format }) — a quantity column's cells (Format.*); its edit box and copy stay bare and its grammar reads the viewer's separators (#852)
984
- │ ├─ The locale: react-aria's `<I18nProvider locale="de-DE">` above the app sets it for every component — `@elaraai/east-ui-components` re-exports `I18nProvider`, so a host needs no react-aria dependency of its own — and the browser's language stands in otherwise. Numbers, counts (a pager's total, a footer's "N loaded of M") and the default dates follow it: 1.234,5 · 29.6.2026 · 29. Juni 2026. What the AUTHOR wrote prints as written: labels and footer items, and a date PATTERN — East's tokens, English month and weekday names, whatever the locale
985
- │ ├─ Accessor alternative: Deck metric/fill format props ALSO accept a text accessor ((value) => String / (value, max) => String) — reified at authoring time into a pre-rendered `text` field; the raw value still ships, and a `none` value renders "—"
986
- │ ├─ Date tokens: East's date tokens incl. weekdays — dd/ddd/dddd; "ddd DD" → Mon 30. All date rendering is UTC (East DateTime is a UTC instant) — a pattern, an axis, a filter chip, a range preset (Today / 7d / 30d / YTD are UTC days) — so no component depends on the viewer's timezone
987
- │ └─ tickValues (#318): pin chart ticks to exact floats / DateTime instants (rendered through the date format) to line a Chart up with a Plan's bucket columns
988
- │
989
- ├─ Statuses & tones (the shared five-token status vocabulary)
990
- │ ├─ The tokens: "success" | "warning" | "danger" | "info" | "neutral" (StatusTokenType / StatusValueType) — the ONE semantic palette for state colour across the library; theme-mapped, never raw hex
991
- │ ├─ Registries (define states ONCE, reference by key):
992
- │ │ └─ Deck.statuses({ key: { label, color, pulse?, hint? } }) — color is a standard token OR any custom CSS colour; one entry drives the card tag + dot/pulse, face wash, fill bar, group-head swatch + hint, and legend
993
- │ ├─ Where a bare token / status value plugs in:
994
- │ │ ├─ Library.status(label, tone, ring?) — palette card status chip, a gallery card's dot (`ring` open) · Library.glyph(icon, label, tone?) — its trailing glyph
995
- │ │ ├─ Table rowStatus — fn(rowIndex) => StatusToken row tint
996
- │ │ ├─ e3-ui's Schematic.items { status: { field, cases } } (a dot per case of a variant field) and { tone } (brand|ink|muted|success|warning|danger stroke override)
997
- │ │ ├─ e3-ui's Plan.run { status } (stuck ring) · Plan.marker { status } (cell rings, default danger) · Plan.event { tone } — tile tints, all ORTHOGONAL to `state`
998
- │ │ ├─ Matrix.marker { status } — corner markers
999
- │ │ ├─ <Status value> — dot + word (`ring` an open ring — not live yet); <Banner status> uses the wider notice set (info|warning|success|error|neutral|change|guard|stale)
1000
- │ │ └─ <Meter tone> / BarStrip item { tone } / SegmentedMeter segment { tone } — bar fills
1001
- │ ├─ Sentiment (value direction, NOT state): <MetricChip tone> positive|negative|neutral|info · <Numeric sentiment> positive|negative|neutral · <Stat indicator.sentiment> positive|negative|neutral · <Progress tone> brand|pos|neg
1002
- │ ├─ A colour the APP gives, not a state (#1406): ColorTokenType — a theme hue ("brand" | "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "cyan" | "purple" | "pink") holding its shade ColorShadeType ("50" … "900"); Style.ColorToken("teal", "500") is variant("teal", variant("500", null)). The typed value every colour accessor returns from here on (e3-ui's Roster.shifts `color`, Option<ColorToken>); a renderer resolves it as the theme's {colors.<hue>.<shade>}, the same in both colour modes, the words on it in the ink the shade takes (the foreground up to 400, the paper's from 500). `brand` and `gray` are the design system's scales, the rest Chakra's stock palettes
1003
- │ ├─ The Elara tokens (#1409): `elara` (the eye's iris and the banner's mark), `elara.ink`, `elara.edge` and `elara.soft` — the ONE accent for what the app's optimiser did, never a state and never an app's colour. Only east-ui-components' shared parts draw them: `OptimiseButton` (the Elara eye, `optimiseToolbarItem` in a builder's toolbar before the history item), `OptimiseBanner` (the `elara` banner tone), `OptimiseLegendItem` (`Elara change`), and the `optimise` recipe's landing over `data-op` / `data-fill` / `data-opn` — e3-ui's five builders list them when `optimise` is bound; an app writes none of them
1004
- │ ├─ state ≠ status: the AUDIT LIFECYCLE is orthogonal to the status tint. Blend allocations speak PlannerStateType ("committed"|"added"|"model"|"removed"|"rejected" — committed solid, proposals dashed/ghost/struck, rejected greyed; only proposed items drag); Plan elements speak the richer EventStateType ladder ("estimated"→"proposed"(added|recommended|removed)→"confirmed"→"in-progress"→"actual", plus "rejected"). A status token is the ORTHOGONAL semantic tint layered on top
1005
- │ └─ tone vs colorPalette: tone/status/sentiment = the semantic vocabulary above (meaning-bearing, theme-stable); colorPalette = decorative hue theming (Chakra palettes) for buttons/badges/tags where the colour carries no state meaning
1006
- │
1007
196
  ├─ Reactive (state-driven re-render)
1008
197
  │ ├─ <Reactive>{$ => { …State.bind reads…; return <…/>; }}</Reactive> — re-renders when read State keys change
1009
- │ │ └─ Props:
1010
- │ │ └─ children (required) — a builder function ($ => UIComponent); all State.bind reads live inside it
1011
- │ └─ <Match on={bind.read()} cases={{…}}> — hosting slot over a variant (#333), the component-level twin of variant.match
1012
- │ └─ Props:
1013
- │ ├─ on (required) — the variant expression selecting the active case; pass the READING expression (bind.read()) — a $.let snapshot freezes the slot
1014
- │ └─ cases (required) — one handler per case name, exhaustive; each gets that case's typed payload. Mounts ONLY the active case and REMOUNTS it on tag change (same-tag payload churn re-renders in place) — use it to swap a STATEFUL component (its own <Reactive>/binds) at one slot; a plain variant.match over mounted components keeps the first one mounted (function-blind reconciliation)
198
+ │ │ └─ children (required) — a builder function ($ => UIComponent); all State.bind reads live inside it
199
+ │ └─ <Match on={bind.read()} cases={{…}}> — hosting slot over a variant, the component-level twin of variant.match
200
+ │ ├─ on (required) — the variant expression selecting the active case; pass the READING expression (bind.read()) — a $.let snapshot freezes the slot
201
+ │ └─ cases (required) — one handler per case, exhaustive. Mounts only the active case and remounts it on tag change — use it to swap a stateful component (its own <Reactive>/binds) at one slot; a plain variant.match keeps the first one mounted
1015
202
  │
1016
203
  └─ State (typed reactive store)
1017
204
  └─ State.bind([T], key, defaultValue) → { read, write, has } closures;
1018
205
  read() tracks the dependency so <Reactive> re-renders when the value changes
1019
206
  ```
1020
207
 
1021
- ## Paged source snapshots
1022
-
1023
- Paged data is BOUND: a component's `data` is local — a collection value or
1024
- expression, or a whole-value `Data.bind` / `State.bind` handle — or a paged
1025
- source from the platform that owns the data, e3-ui's `Data.bindPaged`. east-ui
1026
- produces no paged source; a collection already in hand is local data. A
1027
- component recognises a paged source by its East type, a subtype of
1028
- `Paged.Types.PinnedSource(C)`, `Paged.Types.LiveSource(C)` or
1029
- `Paged.Types.Source(C)` over the collection `C` its `page` serves, and refuses
1030
- a struct with `page` / `total` that is none of them, naming the contract's
1031
- fields.
1032
-
1033
- The contract is a PINNED source: `{ id, page, total, seek, revision, refresh }`
1034
- — the `pinned` arm. `id` names the logical source; `revision()` names the
1035
- snapshot every page, total and seek position belongs to (`none` while it is
1036
- found). Call `refresh(some(committedHash))` after a confirmed write to move to
1037
- that exact snapshot, or `refresh(none)` to the one the source holds now; a
1038
- move invalidates every consumer, same-size rows and cached key searches
1039
- included. `Data.bindPaged` returns one — its revision is the dataset's content
1040
- hash. A component follows a pinned source from one snapshot to the next, and
1041
- edits a paged source only when it is pinned: an `onApply` over a source that
1042
- names no snapshot is refused at build time. Read the methods inside a tracked
1043
- evaluation; call `refresh` in an event handler.
1044
-
1045
- The same struct without `revision` and `refresh` — `{ id, page, total, seek }`,
1046
- the `paged` arm — is the handle a UI exported before them carries. It names no
1047
- snapshot: a component reads each window once, and the same `id` serves the
1048
- same rows for as long as the component holds it.
1049
-
1050
- A rail's narrowed source — `Slice.rows(slice, source)` over records — is a
1051
- pinned source that names its narrowing too: `{ id, page, total, seek,
1052
- revision, refresh, query }`, `Paged.Types.LiveSource(C)`, the `live` arm. Its
1053
- `id` names the source under every narrowing, its reads read the narrowing as
1054
- it stands when they run, and `query()` names it, so a component built over it
1055
- is not built again when a choice changes (#1354). A component keys its windows
1056
- by `query()` as by `revision()`, reading them again when either moves; editing
1057
- keeps the revision alone, so a Save confirms against the record's state.
1058
-
1059
- `Data.bindPaged` also follows its dataset without a call: the workspace
1060
- status poll reports each new content hash and the source moves to that
1061
- snapshot, so a `refresh` after your own write only gets there sooner. A
1062
- pinned read the server refuses because the dataset has moved on (409
1063
- `dataset_hash_mismatch`) rediscovers the current snapshot instead of failing
1064
- its window. How a consumer bridges the move is its own: e3-ui's `<Plan>` and
1065
- `<Sheet>` keep the rows they show until the new snapshot's windows land; the
1066
- Sheet clears a standing key search, and the Plan asks it again there: a
1067
- match its box shows stays while the new snapshot holds it in place, else the
1068
- box shows its query again.
208
+ ## Formats and statuses
209
+
210
+ **Formats.** A format-bearing prop takes a **spec** and the payload keeps the
211
+ **raw value**; the renderer prints it through one interpreter in the viewer's
212
+ locale, every date in UTC. Keep numbers as numbers and give the spec — never a
213
+ pre-formatted string.
214
+
215
+ | Vocabulary | Where it plugs in | Specs |
216
+ |---|---|---|
217
+ | `Format.*` (`Format.Types.Tick`) | `<Numeric format>`, `<Stat format>`, `<Table>` columns' `format` (cells and subtotals), e3-ui's quantities | `Format.Number({ …FractionDigits?, signDisplay? })` · `Format.Currency({ currency, compact? })` · `Format.Percent({ maximumFractionDigits? })` · `Format.Compact()` · `Format.Unit({ unit })` · `Format.Date(pattern)` / `Time` / `DateTime` |
218
+ | `Chart.format.*` | `<Chart>` axes' `format`, Slice fields, Deck metrics, e3-ui's `Plan.axis` | `number()` · `currency({ code?, compact? })` · `percent()` (0.42 → 42%) · `compact()` · `date(pattern)` / `time` / `datetime` |
219
+
220
+ A percent spec takes a fraction (0.183 → 18.3%). An undeclared number prints
221
+ every digit, ungrouped, with the locale's decimal separator. A host sets the
222
+ locale with `<I18nProvider locale="de-DE">` (re-exported from
223
+ `@elaraai/east-ui-components`). Date patterns use East's date tokens
224
+ (`"ddd DD"` → Mon 30).
225
+
226
+ **Status colour.** One semantic palette for state:
227
+ `"success" | "warning" | "danger" | "info" | "neutral"` (`StatusTokenType`),
228
+ theme-mapped, never raw hex. It plugs into `<Status value>`, `<Meter tone>`,
229
+ `BarStrip` / `SegmentedMeter` tones, `Table` `rowStatus`, `Library.status`,
230
+ `Matrix.marker`, and a Deck's registry `Deck.statuses({ key: { label, color,
231
+ pulse?, hint? } })`, defined once and referenced by key. `<Banner status>` has
232
+ its own wider set (info, warning, success, error, neutral, change, guard,
233
+ stale).
234
+
235
+ - **Sentiment** is value direction, not state: `<MetricChip tone>`,
236
+ `<Numeric sentiment>`, `<Stat indicator.sentiment>` (positive / negative /
237
+ neutral).
238
+ - **A colour the app gives** (a series, a shift) is `ColorTokenType`, a theme
239
+ hue at a shade: `Style.ColorToken("teal", "500")`.
240
+ - **`colorPalette`** is decorative hue theming for buttons, badges and tags;
241
+ tone / status / sentiment carry meaning.
242
+ - An audit **state** (Blend's `PlannerStateType`, the Plan's `EventStateType`)
243
+ is orthogonal to the status tint layered on it.
244
+
245
+ ## Paged sources
246
+
247
+ A component's `data` is local — a collection value, or a whole-value
248
+ `Data.bind` / `State.bind` handle — or a paged source, which only e3-ui's
249
+ `Data.bindPaged` produces. A component recognises a paged source by its East
250
+ type (`Paged.Types.PinnedSource` and its kin) and pages it: each window, total
251
+ and search belongs to one snapshot, and the component follows the source to
252
+ the next. A Table pages top-level rows with their subtrees, so subtotals are
253
+ exact over what has loaded; client sort is off on a paged table. A collection
254
+ already in hand is local data.
1069
255
 
1070
256
  ## Key Patterns
1071
257
 
1072
- ### Configurator — one array per axis, no parallel tables
1073
-
1074
- For "change a prop, watch it react" surfaces, put each axis in a **plain array
1075
- of the values themselves** and let the same array feed both the control and the
1076
- preview. For a variant-typed prop that array is just the variants — `getTag()`
1077
- supplies the segment key *and* its label, so there is no key/label table to keep
1078
- in step:
1079
-
1080
- ```tsx
1081
- <Reactive>{$ => {
1082
- const variants = $.const([
1083
- variant("outline", null), variant("brand", null), variant("danger", null),
1084
- ], ArrayType(Style.Types.StyleVariant));
1085
-
1086
- const bind = $.let(State.bind([StringType], "badge_variant", "outline"));
1087
- const key = $.let(bind.read());
1088
- const onPick = $.const(East.function([StringType], NullType, ($, n) => { $(bind.write(n)); }));
1089
-
1090
- // The selection is a lookup into the array the control renders.
1091
- const selected = $.let(variants.filter((_$, v) => v.getTag().equal(key)).get(0n));
1092
-
1093
- return (
1094
- <Configurator
1095
- controls={[
1096
- Configurator.Control("Variant", key,
1097
- <SegmentGroup value={key} onChange={onPick} size="sm"
1098
- items={variants.map((_$, v) => SegmentGroup.Item(v.getTag(), <Text>{v.getTag().upperCase()}</Text>))} />),
1099
- ]}
1100
- preview={<Badge variant={selected}>{selected.getTag().upperCase()}</Badge>}
1101
- spec={[Configurator.Spec("Radius", "sm")]}
1102
- />
1103
- );
1104
- }}</Reactive>
1105
- ```
1106
-
1107
- Numeric and token axes collapse the same way — an opacity is a percentage
1108
- (`[100n, 75n, 50n]`), a padding is a spacing token (`["0", "1", "3"]`). Only an
1109
- axis with no single value to name it by (a background/foreground *pair*, say)
1110
- needs a struct.
1111
-
1112
- **A variant-typed prop needs a variant value, not a string** — `density={"compact"}`
1113
- is a type error once the value comes from state, which is exactly why the array
1114
- holds `variant(...)` rather than keys.
1115
-
1116
258
  ### Reactive interactivity — builder children
1117
259
 
1118
260
  `<Reactive>` takes a **builder function** `{$ => …}` (not a nested
1119
- `East.function`). All `State.bind` reads live inside it so the component
261
+ `East.function`). All `State.bind` reads live inside it, so the component
1120
262
  re-renders when the bound key changes.
1121
263
 
1122
264
  ```tsx
1123
- /** @jsxImportSource @elaraai/east-ui */
1124
- import { East, IntegerType, NullType } from "@elaraai/east";
1125
- import { VStack, Text, Button, Reactive, State, UIComponentType } from "@elaraai/east-ui";
1126
-
1127
265
  const counter = East.function([], UIComponentType, (_$) => (
1128
266
  <Reactive>{$ => {
1129
267
  const count = $.let(State.bind([IntegerType], "count", 0n));
@@ -1141,50 +279,43 @@ const counter = East.function([], UIComponentType, (_$) => (
1141
279
  ));
1142
280
  ```
1143
281
 
282
+ A filtered view is the same shape: read the state inside the block and filter
283
+ the rows as an East expression (`rows.filter(($, r) => …)`), so the filter runs
284
+ again on every change.
285
+
1144
286
  ### Two callback families
1145
287
 
1146
- - **Build-time accessors** — `(row) => SubtypeExprOrValue<Scalar>` for chart
1147
- encodings (`x`/`y`/`by`/`columns`) and table column `value`. Passed through
1148
- verbatim; they return field expressions used while building the IR.
1149
- - **East-function handlers** — `onClick`, `onChange`, per-row builders. Pass an
1150
- `East.function(...)` value or a typed arrow; the factory lifts it.
288
+ - **Build-time accessors** — `(row) => field expression` for chart encodings
289
+ (`x` / `y` / `by` / `columns`) and a table column's `value`, used while the
290
+ IR is built.
291
+ - **East-function handlers** — `onClick`, `onChange`, per-row builders: an
292
+ `East.function(...)` value or a typed arrow, which the factory lifts.
1151
293
 
1152
- ### Text is East, not JSX text nodes
294
+ ### Text and conditionals are East
1153
295
 
1154
- Children are `SubtypeExprOrValue<StringType>` — interpolate East-side, never with
1155
- JSX braces between text:
296
+ Children are East strings — interpolate East-side, never with JSX braces
297
+ between text — and a conditional is an East expression returning a component:
1156
298
 
1157
299
  ```tsx
1158
300
  <Text>{East.str`Hello ${name}`}</Text> // correct
1159
- // <Text>Hello {name}</Text> // wrong — not East
301
+ // <Text>Hello {name}</Text> // not East
302
+ cond.ifElse(_$ => <A/>, _$ => <B/>) // never {cond && <El/>} or a ternary to null
1160
303
  ```
1161
304
 
1162
- ### Conditionals are East
1163
-
1164
- Use `cond.ifElse(<A/>, <B/>)` (a `UIComponentType`), never JS `{cond && <El/>}`
1165
- or ternaries returning `null` — those aren't East values.
1166
-
1167
305
  ### Data-driven components keep data on config props
1168
306
 
1169
- Tables, charts, matrices, lists and item-parents take structured data on
1170
- `data=` / `columns=` / `items=` / `layers=` props; per-row builders are typed
1171
- callbacks returning factory values (`cell={(r, col) => Matrix.cell({…})}`).
1172
- Non-UI sub-structures are never child sub-tags.
1173
-
1174
307
  ```tsx
1175
- // Table — columns config, inference preserved
1176
308
  <Table
1177
- data={[{ name: "Alice", role: "Admin" }, { name: "Bob", role: "User" }]}
1178
- columns={{ name: { header: "Name" }, role: { header: "Role" } }}
309
+ data={rows}
310
+ columns={{ name: { header: "Name" }, revenue: { header: "Revenue", format: Format.Currency({ currency: "AUD" }) } }}
1179
311
  striped variant="line"
1180
312
  />
1181
313
 
1182
- // Chart — layers config array
1183
314
  <Box height="220px" width="100%">
1184
315
  <Chart
1185
316
  layers={[
1186
- Chart.Column(rows, { x: r => r.month, y: r => r.revenue }, { key: "Revenue", color: "teal.solid" }),
1187
- Chart.Line(rows, { x: r => r.month, y: r => r.profit }, { key: "Profit", color: "purple.solid", dots: true }),
317
+ Chart.Column(rows, { x: r => r.month, columns: { Revenue: r => r.revenue } }),
318
+ Chart.refLine({ y: 100, label: "Target", dash: "4 4" }),
1188
319
  ]}
1189
320
  y={{ format: Chart.format.currency({ compact: true }) }}
1190
321
  legend grid tooltip
@@ -1192,326 +323,83 @@ Non-UI sub-structures are never child sub-tags.
1192
323
  </Box>
1193
324
  ```
1194
325
 
1195
- ### Sizing — one string prop, parsed everywhere
1196
-
1197
- Every size prop is a **plain string** and every renderer parses it the same
1198
- way (`parseCssSize`). Four spellings, uniform across data components (`<Table>`,
1199
- e3-ui's `<Plan>`, `<Matrix>`,
1200
- `<Library>`, `<SnapGrid>`) and layout primitives (`<Box>` / `<Flex>` /
1201
- `<Stack>` / `<Grid>` / `<Card>`):
1202
-
1203
- | Value | Means |
1204
- |---|---|
1205
- | `"fill"` | fill the parent box (`100%`) |
1206
- | `"240"` | a bare number → pixels (`240px`) |
1207
- | `"50%"` / `"calc(100vh - 4rem)"` | any CSS length passes through |
1208
- | `"18px"` | explicit units pass through |
1209
- | `"min(420px, 100%)"` / `"clamp(240px, 50%, 420px)"` | fluid sizes pass through — the mobile-safe way to say "420px, but never wider than the container" |
1210
-
1211
- **Fluid layouts** (desktop + mobile from one definition): prefer
1212
- `width="min(<ideal>px, 100%)"` over a bare pixel width; a `<Grid>` with
1213
- `templateColumns="repeat(auto-fit, minmax(240px, 1fr))"` reflows cards to
1214
- 1 column on phones; `<Splitter collapseBelow={480}>` stacks its panels
1215
- vertically when its container is narrower than 480px.
1216
-
1217
- ```tsx
1218
- // height bounds the whole component and it scrolls within; maxHeight caps
1219
- // it but stays content-sized until the cap is hit.
1220
- <Table data={rows} columns={cols} height="fill" /> // fills its parent
1221
- <Matrix … maxHeight="420" /> // content up to 420px, then scrolls
1222
-
1223
- // Layout primitives add boolean shorthands so you never hand-write the
1224
- // flex:1 + min-height:0 + overflow incantation for a scroll region:
1225
- <Card height="fill">
1226
- <Box fill scrollY> {/* fill remaining space, scroll vertically */}
1227
- <Table data={rows} columns={cols} height="fill" />
1228
- </Box>
1229
- </Card>
1230
- ```
1231
-
1232
- A `<Card>` given `height` / `maxHeight` becomes a flex column that constrains
1233
- its body, so a single `height="fill"` child (a data component, a scroll region)
1234
- resolves against it.
1235
-
1236
- Caveats that save a render cycle:
1237
-
1238
- - **`"fill"` / percentages need a definite parent.** `height="fill"` resolves
1239
- against the nearest box with a real height (a sized `<Box>`/`<Card>`, a flex
1240
- item with `fill`, a Drawer `fillBody`). Inside a content-sized parent it
1241
- silently resolves to auto — bound the parent, don't add pixels to the child.
1242
- A `<Chart height="fill">` is the exception: in a content-sized parent it
1243
- takes its natural height.
1244
- - **`height` vs `maxHeight`**: `height` pins the component to exactly that box
1245
- (header pinned, body scrolls); `maxHeight` stays content-sized UP TO the cap,
1246
- then scrolls. Bounded data components virtualize (only visible rows mount)
1247
- and show a reserved-gutter scrollbar; unbounded ones grow to content.
1248
- - **A definite `height`/`width` on Box/Flex/Stack also pins `flex-shrink: 0`**
1249
- (a sized box no longer collapses under flex pressure) — opt back in with
1250
- `flexShrink` if you want it squeezable.
1251
- - **Bare numbers are pixels, not Chakra spacing tokens** — `width="8"` is 8px.
1252
- `gap` / `padding` / `margin` keep token semantics (`gap="4"` is a spacing
1253
- token, not 4px).
1254
-
1255
- ### Nested rows — a P&L in one Table (#954)
1256
-
1257
- A Table's rows nest the way the Plan's do: a row carries its children, to any
1258
- depth, and a parent IS the group row. It draws its own cells, and in each
1259
- column that declares an `aggregate`, the subtotal of what its children show —
1260
- so a collapsed section reads as its subtotal line, and opening it drills down.
1261
- Hierarchy comes only from the data; there is no `groupBy`.
1262
-
1263
- ```tsx
1264
- // Sections hold categories, categories hold accounts: the data's own tree.
1265
- const Line = RecursiveType((self) => StructType({
1266
- account: StringType, q1: FloatType, fy: FloatType, lines: ArrayType(self),
1267
- }));
1268
- const pnl = $.const(PNL, ArrayType(Line)); // a parent's own quarters are 0 — its columns show its lines' subtotals
1269
- // One render for every cell: an account's amount, a parent's subtotal.
1270
- const money = $.const(East.function([Table.Types.CellRenderContext], UIComponentType, (_$, ctx) => (
1271
- <Text width="100%" textAlign="right">{East.Float.printCurrency(ctx.cellValue.unwrap("Float"))}</Text>
1272
- )));
1273
- return (
1274
- <Table
1275
- data={pnl}
1276
- columns={{
1277
- account: { header: "Account", width: "260px" },
1278
- q1: { header: "Q1", aggregate: "sum", render: money },
1279
- fy: { header: "FY", aggregate: "sum", render: money },
1280
- }}
1281
- tree={{
1282
- children: (r) => r.lines, // more of the SAME row type
1283
- collapsed: (r) => r.account.equal("Operating expenses"),
1284
- }}
1285
- footerRows={[{ account: { content: <Text fontWeight="bold">Net income</Text> }, /* … */ }]}
1286
- />
1287
- );
1288
- ```
1289
-
1290
- | Signature | Description | Example |
1291
- | --- | --- | --- |
1292
- | `tree={{ children: (r) => Array<Row> }}` **❗** | A row's children: more rows of the data's own element type (a recursive row's own field, or a lookup among the rows); another type is refused at build. A recursive row reaches every accessor — columns' `value`, `children`, `collapsed` — as its node. | `tablePnl`, `tableTree` |
1293
- | `tree={{ collapsed: true \| (r) => Boolean }}` | Where a parent starts; the viewer's folds persist by path under the `storageKey`. | `tablePnl`, `tableTree` |
1294
- | `aggregate: "sum" \| "mean" \| "min" \| "max" \| "count"` | A parent's cell in that column: its children's subtotal, composed bottom-up — a mean of means (a Float), `count` the leaf rows beneath. `sum` / `mean` need a numeric column. | `tablePnl`, `tableTree` |
1295
- | `render` / `format` on an `aggregate` column | A subtotal draws like any cell: the render gets it as `ctx.cellValue`, the format prints it. A `count` prints itself through neither. | `tablePnl`, `tableTree` |
1296
- | `rowIndex` / `path` | A row's pre-order position (a flat table's data index) — what `rowStatus`, `expandedContent`, `selection`, review and every event carry, stable under sorting and pagination — and its sibling index at each depth. | `tableTree` |
1297
- | `pagination` / a paged source **❗** | Both page TOP-LEVEL rows, each with its whole subtree, so a parent's subtotals are exact over whatever has loaded. | `dataBindPagedTable` (e3-ui) |
1298
-
1299
- A sort orders each parent's children among themselves (ties keep data order),
1300
- a parent carrying its subtree. A computed statement line (Gross profit) that
1301
- is not a plain subtotal is its own row in the data, or a `footerRows` entry.
1302
-
1303
- Removed with #954: `groupBy` (nest the data — a data step before the table)
1304
- and a column's `aggregateRender` (a parent is a row: its subtotal draws
1305
- through the column's `render` or `format`).
1306
-
1307
- ### Editing — one transaction contract (#879)
1308
-
1309
- An editable collection's changes are drafts, applied as one checked batch
1310
- through one contract: `Editing.apply` and `Editing.Types.*` — `ChangeSet`,
1311
- `PatchEvent`, `Readiness`, `Origin`, `Draft`, `Entry` and the rest. The
1312
- SnapGrid's editing canvas and e3-ui's `<Sheet>` and `<Plan>` each
1313
- run a session on it, and e3-ui's `Sheet.apply` and `Sheet.Types.*` are its
1314
- very values under the Sheet's names. A gesture's `origin` names what made it:
1315
- a typed or pasted value, a fill or a proposed row taken, an entry inserted,
1316
- moved or removed, a `resize`, a `drop`, an undo, a redo or a discard (a review
1317
- `verdict`, which no collection makes since #1260, stays so a journal of earlier
1318
- events still reads).
326
+ ### Nested rows — one Table, the data's own tree
1319
327
 
1320
- A host's `onApply` takes one checked `ChangeSet` and answers an
1321
- `ApplyResult`: it checks the base the drafts began from, applies the whole
1322
- batch or none of it, deduplicates by the request id and returns the committed
1323
- revision. An unknown outcome retries the same frozen request, and an
1324
- append-only journal (`onPatch`) is not an application acknowledgement.
1325
- `Editing.apply` is that check and application as an East function, over an
1326
- `Array` by its identity field or a keyed `Dict` by key: each change names its
1327
- entry by key (a `String` key as it is, any other key by its `.east` text), and
1328
- a new entry is placed `keyOrder`.
328
+ A row carries its children (a `RecursiveType` row's own field, or a lookup
329
+ among the rows); a parent is the group row, and each column with an
330
+ `aggregate` (`"sum" | "mean" | "min" | "max" | "count"`) shows its children's
331
+ subtotal, through the column's `format` or `render`. Hierarchy comes only from
332
+ the data — there is no `groupBy`. A computed line that is not a plain subtotal
333
+ (gross profit) is its own row, or a `footerRows` entry. Examples: `tablePnl`,
334
+ `tableTree`.
1329
335
 
1330
- | Signature | Description | Example |
1331
- | --- | --- | --- |
1332
- | `Editing.apply(E, "id")` / `Editing.apply(DictType(K, E))` | The shared applier — an Array by its identity field, or a keyed Dict by key (`Editing.Types.ChangeSet(E, K)`): the whole batch, or a conflict saying why. | `editingApplyBatch`, `editingApplyKeyed` |
1333
-
1334
- ### Fields — a builder inspector's typed form (#1147)
1335
-
1336
- A builder's inspector shows what is selected as a typed form over its struct.
1337
- `Fields.specs(R, hints, omit)` resolves each field into a `Fields.Types.Spec`:
1338
- its editor from its East type, a hint adding only what a type cannot say.
1339
- e3-ui's builders carry the specs in their payloads, and east-ui-components'
1340
- `FieldForm` draws each one as the shared `<Field>` (its label, its path as the
1341
- key) around the input its type takes — so an inspector an author writes
1342
- themselves from `<Field>` and the form tags looks the same.
1343
-
1344
- | Field type | Editor with no hint | Hint |
1345
- | --- | --- | --- |
1346
- | `String` | text | `Fields.text({ placeholder? })`; `Fields.reference({ of })` — a key of a keyed set the host lists |
1347
- | `Integer`, `Float` | number, with its steppers | `Fields.number({ unit?, step?, min?, max? })` — bigints for an Integer field, numbers for a Float |
1348
- | `Boolean` / `DateTime` | checkbox / date and time | — |
1349
- | a variant of empty cases | select, each case's name spelled out | `Fields.select({ labels? })` — the cases it labels first |
1350
- | `Set<String>`, `Array<String>` | tags, typed freely | `Fields.tags({ options? })` — suggested as a tag is typed |
1351
- | `Array` of a struct with one String and one Boolean field | checklist | `Fields.checklist({ text?, done? })` — naming them where there are several |
1352
- | a struct | its fields, under its name | a hint per nested field |
1353
- | `Option<T>` | `T`'s, which can be cleared | `T`'s |
1354
- | anything else | printed | `Fields.readonly()`; `Fields.hidden()` leaves any field out |
1355
-
1356
- Every hint but `hidden` takes `label` and `help`. A hint is checked against its
1357
- field's type as it compiles (`Fields.number` on a String field is a type
1358
- error), and the specs refuse one again as they resolve, naming the field.
1359
-
1360
- | Signature | Description | Example |
1361
- | --- | --- | --- |
1362
- | `Fields.specs(R, hints?, omit?): Array<Fields.Types.Spec>` **❗** | The specs: the hinted fields first, in hint order, then the rest as declared; a nested struct's fields by path, under its name; `omit`'s and the hidden fields left out. Refuses a hint that does not fit its field, naming it. | `fieldsSpecs` |
1363
- | `Fields.select({ labels })` | A variant's select: the cases it labels first, in its order, then the rest, each name spelled out. | `fieldsSelect` |
1364
-
1365
- ### Drag and drop — one grammar, every target (#608)
1366
-
1367
- A `<Library>` is a source; a `<Blend>` or e3-ui's `<Plan>`, `<Calendar>` or `<Roster>`
1368
- that lists its `id` in `sources` is a target. Every drag between them reduces
1369
- to one `DragEventType` — `add` (a card onto a cell), `move`, `remove` (to the
1370
- trash or back to the palette) or `resize` (a span's edge) — and the renderer
1371
- wires the flow, so nothing is wired by hand. A target's `canDrop` is asked of
1372
- the REAL event, so a policy on copies holds while the drag is still moving:
1373
-
1374
- ```tsx
1375
- // A person may be moved onto a shift, never copied there (Alt held).
1376
- const canDrop = $.const(East.function([DragEventType], BooleanType, (_$, event) =>
1377
- event.match({ add: (_$, add) => add.duplicate.not() }, (_$) => East.value(true))));
1378
- ```
1379
-
1380
- | Signature | Description | Example |
1381
- | --- | --- | --- |
1382
- | **The gesture** | | |
1383
- | pointer | A mouse or pen drag starts after 4px of travel, so a click stays a click; a touch after a 300ms hold — a drift first scrolls the page; a touch on a grip at once. Only the pointer that pressed moves, drops or cancels the drag — a second finger never does. | `rosterLibraryDnd` |
1384
- | keyboard | Every draggable is a focusable control: Space / Enter picks it up, the arrow keys carry it between the cells that take it (and along a Plan row's buckets), Space / Enter drops it, Escape / Tab cancels. A Plan element is picked up with Space alone, since Enter is its click, and carries its own keys (#825). A key pressed in a control inside it is the control's. | `rosterWarehouse`, `planRowDrop` (e3-ui) |
1385
- | reach | A drag resting near a scroll container's edge scrolls it — the container under the pointer: a bounded Plan's body, the page — and whatever scrolls under a still drag is read again. | `planRowDrop` (e3-ui) |
1386
- | **The verdict** | | |
1387
- | `canDrop: fn(DragEventType) => Boolean` | Asked of the event a drop where the drag rests would deliver — an `add`'s `duplicate` is whether Alt is held now — so the ⊘ stage shows before the drop, and asked again of the event delivered. A predicate that throws allows. | `rosterLibraryDnd`, `blendLibraryDnd`, `planRowDrop` (e3-ui) |
1388
- | the drop | Resolves where it happens: a cell that scrolled away is never dropped on, and a drop with nothing under it says so rather than vanishing. | — |
1389
- | **Screen readers** | | |
1390
- | announcements | The pick-up, each new cell or bucket the drag rests over (or one that refuses it), the drop and a cancel are said in a live region. Host React code re-words them with `<DragLayerProvider messages={{ pickedUp: ({ item }) => … }}>` (@elaraai/east-ui-components; `dragMessages` is the English table, and any subset overrides it). | — |
336
+ ### Sizing — one string prop, parsed everywhere
1391
337
 
1392
- ### Overlays — trigger prop + body children
338
+ Every size prop is a string: `"fill"` (the parent's box), `"240"` (pixels),
339
+ or any CSS length (`"50%"`, `"min(420px, 100%)"`). `"fill"` and percentages
340
+ need a parent with a definite height — inside a content-sized parent they
341
+ resolve to auto, so bound the parent. `height` pins a data component (its body
342
+ scrolls and virtualizes); `maxHeight` stays content-sized up to the cap.
343
+ `gap` / `padding` / `margin` take spacing tokens (`gap="4"`), not pixels. For
344
+ one definition on desktop and mobile, prefer `width="min(<ideal>px, 100%)"`
345
+ and `templateColumns="repeat(auto-fit, minmax(240px, 1fr))"`.
1393
346
 
1394
- `<Dialog>` is the one modal, and it is a confirmation step: before an act that
1395
- destroys something or cannot be undone, it names the act and offers Cancel and
1396
- the act's own verb. It is never a form. Anything that makes or names something
1397
- — a new page, a template, a cohort — is a `<Popover>` hanging from the control
1398
- that starts it, its fields in the body.
347
+ ### Overlays — trigger prop, body children, State for programmatic open
1399
348
 
1400
349
  A callback opens an overlay through the State its `open` reads, and
1401
- `onOpenChange` writes the State back as it closes. A callback carries no
1402
- element, so an anchored overlay — a popover, a hover card, a toggle tip —
1403
- opens at its own trigger, whatever wrote the State:
350
+ `onOpenChange` writes it back as it closes; an anchored overlay opens at its
351
+ own trigger whatever wrote the State:
1404
352
 
1405
353
  ```tsx
1406
354
  const shown = $.let(State.bind([BooleanType], "details_open", false));
1407
- const openIt = $.const(East.function([], NullType, $ => { $(shown.write(true)); }));
1408
- <Button onClick={openIt}>Open the details</Button>
1409
355
  <Popover trigger={<Button>Details</Button>} open={shown.read()} onOpenChange={shown.write}>…</Popover>
1410
356
  ```
1411
357
 
1412
- ```tsx
1413
- <Dialog trigger={<Button variant="outline">Remove cohort…</Button>}
1414
- eyebrow="Can't be undone" title="Remove cohort Late?">
1415
- <HStack gap="2" justify="flex-end">
1416
- <Button variant="outline">Cancel</Button>
1417
- <Button variant="solid">Remove cohort</Button>
1418
- </HStack>
1419
- </Dialog>
1420
- ```
1421
-
1422
- ### Density cascade — one prop tightens a whole surface
1423
-
1424
- Display components (`<Tag>`, `<Badge>`, `<Kbd>`, `<MetricChip>`, `<EditableChip>`,
1425
- `<Meter>`, `<BarStrip>`, `<SegmentedMeter>`, `<Stat>`, `<Avatar>`, `<Trace>`,
1426
- `<ChipRail>`) take `density="condensed" | "compact" | "comfortable"` and inherit
1427
- it from the nearest providing surface — a `<Table>` /
1428
- `<Matrix>` / `<ChipRail>` with `density` set, or any layout container
1429
- (`<Box>` / `<Stack>` / `<Flex>` / `<Grid>` / `<Card>`) given a `density` prop.
1430
- All densified components share one sizing rhythm, so mixed table cells (a tag
1431
- beside a trace beside a meter) line up; an explicit `density` on a component
1432
- wins over the cascade. `<Badge>` and `<Kbd>` scale on a smaller micro-label
1433
- tier so they stay subordinate to tags at every density.
1434
-
1435
- ```tsx
1436
- // One prop on the Table sizes every chip, trace and meter in its cells.
1437
- <Table density="compact" data={lines} columns={{ /* render cells with <Tag>, <Trace>, <Meter>… */ }} />
1438
-
1439
- // Or scope it to a row:
1440
- <HStack density="condensed" gap="2">
1441
- <Tag>Line A</Tag>
1442
- <Badge>WK 12</Badge>
1443
- <Meter value={72.0} tone="success" />
1444
- </HStack>
1445
- ```
358
+ ### Density cascade
359
+
360
+ Display components (`<Tag>`, `<Badge>`, `<MetricChip>`, `<Meter>`,
361
+ `<BarStrip>`, `<Stat>`, `<Avatar>`, `<Trace>`, `<ChipRail>`, …) take
362
+ `density="condensed" | "compact" | "comfortable"` and inherit it from the
363
+ nearest providing surface — a `<Table>` / `<Matrix>` / `<ChipRail>`, or a
364
+ layout container given `density`. An explicit `density` on a component wins.
365
+
366
+ ### Editing, fields and drag and drop
367
+
368
+ - **Editing**: an editable collection's changes are drafts applied as one
369
+ checked batch through `Editing.apply` and `Editing.Types.*` (`ChangeSet`,
370
+ `PatchEvent`, `Readiness`, …). A host's `onApply` takes one `ChangeSet` and
371
+ answers an `ApplyResult`, applying the whole batch or none of it.
372
+ - **Fields**: `Fields.specs(R, hints?, omit?)` turns a struct into an
373
+ inspector's typed form, each field's editor from its East type, a hint
374
+ (`Fields.number`, `Fields.select`, `Fields.reference`, …) adding what the
375
+ type cannot say.
376
+ - **Drag and drop**: a `<Library>` is a source; a target (`<Blend>`, e3-ui's
377
+ builders) lists its `id` in `sources`. Every drag reduces to one
378
+ `DragEventType` (`add`, `move`, `remove`, `resize`), and a target's
379
+ `canDrop: fn(DragEventType) => Boolean` vetoes it.
1446
380
 
1447
381
  ### Picking between similar components
1448
382
 
1449
- - **Switch vs Toggle vs Checkbox** — `<Switch>` binds a boolean form value;
1450
- `<Toggle>` is a pressable toolbar button; `<Checkbox>` binds a boolean in a list.
1451
- - **SegmentGroup vs Tabs vs RadioGroup** — `<SegmentGroup>` is a compact mode
1452
- switcher (no panels); `<Tabs>` switches content panels; `<RadioGroup>` is a form input.
1453
- - **Banner vs Status vs Progress** — `<Banner>` spans the page for staleness /
1454
- partial-data; `<Status>` is a dot + word; `<Progress>` shows task completion.
1455
- - **Meter vs Progress vs SegmentedMeter** — `<Meter>` is a static value vs a
1456
- range; `<Progress>` is completion; `<SegmentedMeter>` decomposes a meter.
1457
- - **Stat vs MetricChip** — `<Stat>` is a tile with hero number; `<MetricChip>` is
1458
- a compact inline delta pill.
1459
- - **Tag vs Badge** — `<Tag>` is an operator-set keyword / filter pill (body
1460
- font, optionally closable); `<Badge>` is a mono uppercase micro-label for
1461
- status / taxonomy (ok / warn / danger / count) that stays a tier smaller
1462
- than tags at the same density.
1463
- - **BarStrip vs Chart.Bar vs Chart.Column** — `<BarStrip>` is a small ranked
1464
- horizontal-bar list (no axes) for a KPI card; `Chart.Bar` draws horizontal
1465
- bars inside an axis-bearing `<Chart>` (numeric x, categorical y — grid,
1466
- legend, tooltip, stacking); `Chart.Column` is the vertical twin (formerly
1467
- named `Chart.Bar`).
1468
- - **Plan (subsumes the retired Gantt / Planner / AlignedStack, #571)** —
1469
- e3-ui's `<Plan>` (#1177, #1191) is the planning canvas: ONE shared axis — time, number or
1470
- ordinal (#631) — over heterogeneous rows (state-runs, allocation lanes, chart measures,
1471
- heat, bucketed numerals, shift chips, event marks), laid out by the series
1472
- list and nested from the data's own structure, or placed from event kinds
1473
- over records (e3-ui's `Schedule`, a Calendar's too), each named by a typed id,
1474
- with slice/key-search/series-library chrome, an editing session (every
1475
- dropped card, move and resize a draft, saved together — #880 / #825 / #1260) and PAGED sources. A Gantt
1476
- is a Plan with span rows, a Planner a Plan with bucket rows, an
1477
- AlignedStack a Plan mixing chart / heat / table rows on the shared axis.
1478
- Reach for `<Plan>` for anything scheduled on ONE shared axis — calendar
1479
- time, a numbered day / shift / distance, or an ordered list of phases —
1480
- with mixed row kinds, nesting to any depth, a paged source, or rows addressed
1481
- by stable ids; the e3-ui skill documents it.
1482
- - **Table vs Sheet** — `<Table>` DISPLAYS rows (sort, pin, nest, review,
1483
- paginate; cells printed in the viewer's language, or drawn by `render`);
1484
- e3-ui's `<Sheet>` (#1179, #1216) is where a planner TYPES
1485
- them, in its builder frame: typed cells with grammars (dates, quantities,
1486
- register lookups, a directed link), a blank tail that inserts rows, an
1487
- East-function copilot, and one rail narrowing its rows, its templates and
1488
- its tabs, with saved views. Reach for `<Sheet>` when the rows are authored in place
1489
- and written back (through an e3 record's patch, or `onUpdate` / `onApply`)
1490
- — the e3-ui skill documents it; for reading, sorting and reviewing a
1491
- dataset, `<Table>`.
1492
- - **Flowchart vs Schematic** — both are e3-ui's, and the e3-ui skill
1493
- documents them: `<Schematic>` (#1384, #1386) is a world-coordinate 2D
1494
- drawing of the app's records (each row carries its x/y; zones, footprints,
1495
- camera); `<Flowchart>` (#1243)
1496
- derives its whole layout from lanes + links (no coordinates) for
1497
- state-transition / process-flow reading, with decision triggers and
1498
- evidence on the links.
1499
- - **Library vs Deck** — `<Library>` is the draggable palette (DnD source),
1500
- or with `variant="gallery"` a library a person browses — large cards, each
1501
- with its media, a byline and an action a click follows;
1502
- `<Deck>` is the status-coloured display board (popover VIEW state, no drag).
1503
- - **Card vs Box** — `<Box>` is structural-only; `<Card>` carries chrome.
1504
- - **SnapGrid vs Grid** — `<Grid>` places the children written inside it, on
1505
- whatever tracks you template; `<SnapGrid>` lays out tiles mapped from rows —
1506
- a page held as data, on the fixed 12-column grid whose spans reflow to the
1507
- SnapGrid's width, with a wireframe thumbnail drawn from the same rows.
383
+ | Choice | Pick |
384
+ |---|---|
385
+ | `<Switch>` · `<Toggle>` · `<Checkbox>` | a boolean form value · a pressable toolbar button · a boolean in a list |
386
+ | `<SegmentGroup>` · `<Tabs>` · `<RadioGroup>` | a compact mode switcher · content panels · a form input |
387
+ | `<Banner>` · `<Status>` · `<Progress>` | a page-wide notice · a dot and word · task completion |
388
+ | `<Meter>` · `<Progress>` · `<SegmentedMeter>` | a value against a range · completion · a decomposed meter |
389
+ | `<Stat>` · `<MetricChip>` | a tile with a hero number · an inline delta pill |
390
+ | `<Tag>` · `<Badge>` | an operator-set keyword pill · a status / taxonomy micro-label |
391
+ | `<BarStrip>` · `Chart.Bar` · `Chart.Column` | a ranked list with no axes · horizontal bars in a chart · vertical columns |
392
+ | `<Table>` · e3-ui `<Sheet>` | displaying rows · rows typed in place and written back |
393
+ | `<Library>` · `<Deck>` | a draggable palette or browsable gallery · a status-coloured display board |
394
+ | `<Grid>` · `<SnapGrid>` | children placed on templated tracks · tiles held as data on 12 columns |
395
+ | `<Box>` · `<Card>` | structure only · a chrome-bearing card |
396
+ | e3-ui `<Plan>` · `<Flowchart>` · `<Schematic>` | anything on one shared axis · a state flow laid out from lanes · records at world coordinates |
1508
397
 
1509
398
  ## Related skills
1510
399
 
1511
- - **east** — the language UI component bodies are written in.
1512
- - **e3-ui** — bind components to live workspace data (`Data.bind`) and ship them
1513
- as reactive `ui()` e3 tasks; pair it with east-ui whenever the UI reads,
1514
- writes, or commits real data.
400
+ - **east** — the language component bodies are written in.
401
+ - **e3-ui** — bind components to live workspace data and ship them as `ui()`
402
+ e3 tasks, and the planning builders (`<Plan>`, `<Sheet>`, …); pair it with
403
+ east-ui whenever the UI reads, writes or commits real data.
1515
404
  - **e3** — the engine that runs UI tasks.
1516
- - **e3-ui-cli** — screenshot a component from the terminal (`e3-ui shot
1517
- --from-source`) or Node (`renderToPng`), with managed headless Chromium.
405
+ - **e3-ui-cli** — screenshot a component from the terminal (`e3-ui shot`).