@elaraai/east-codex-plugin 1.0.96 → 1.0.98

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.
@@ -54,7 +54,7 @@ e3-ui https://e3.example.com # a bare origin → the repositories li
54
54
  # Screenshots need the browser once per machine (add --with-deps on fresh Linux servers):
55
55
  e3-ui install-browser
56
56
  e3-ui shot --from-source ./dashboard.tsx -o dashboard.png
57
- e3-ui shot --from-source test/collections/schematic.examples.tsx -e schematicNets -o nets.png
57
+ e3-ui shot --from-source test/collections/table.examples.tsx -e tableBasic -o table.png
58
58
  e3-ui shot --from-task main.dashboard --repo ./.repos -o dashboard.png
59
59
  e3-ui shots src --out .shots --json # EVERYTHING renderable under src/
60
60
  ```
@@ -303,7 +303,7 @@ npm run shot # = e3-ui shot --from-source src/ui/index.tsx --export surfa
303
303
  e3-ui shot --from-source test/display/combine.examples.tsx -e combineDensities -o combine.png
304
304
 
305
305
  # Width-flexible component (Schematic/Plan/Table) — mount the frame at viewport width
306
- e3-ui shot --from-source test/collections/schematic.examples.tsx -e schematicStress --frame-width full -o stress.png
306
+ e3-ui shot --from-source test/collections/table.examples.tsx -e tableFrozen --frame-width full -o frozen.png
307
307
 
308
308
  # Sweep a whole project (the --ui scaffold wires this as `npm run shots`):
309
309
  e3-ui shots src --out .shots # PNGs, faithful width, typed skip reasons
@@ -1,11 +1,11 @@
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), (Schematic), (Map), (Library) (a drag palette, or a gallery of large cards whose media is any component), (Blend), (Slice.Rail), (Pagination), (ChipRail),… See the detailed scope below."
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."
4
4
  ---
5
5
 
6
6
  ## Detailed skill scope
7
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>, <Schematic>, <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.
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
9
 
10
10
  # East UI
11
11
 
@@ -533,35 +533,7 @@ Task → Which tag?
533
533
  │ │ ├─ Matrix.cell({ segments?, markers?, orientation?, slot?, popover? }) — one cell (slot = arbitrary UIComponent; popover = click body)
534
534
  │ │ ├─ Matrix.segment({ fill?, weight, label?, color?, min?, max?, step? }) — one segment of the cell bar
535
535
  │ │ └─ Matrix.marker({ status?, message, at?, label? }) — corner status marker
536
- │ ├─ <Schematic items={rows} extent={{width,height}} item={r => ({…})} /> — 2D world-coord canvas: items / zones / links / nets from flat tables
537
- │ │ ├─ Props:
538
- │ │ │ ├─ items + extent (required) — item rows + world bounds (canvas scales to fit)
539
- │ │ │ ├─ item (optional) — row mapper to { key, x, y, label, sublabel?, icon?, status?, meter?{value,max}, metric?, width?, footprint?, tone?, color?, bg?, fillOpacity?, weight?, excluded?, layer? } (omit when already Schematic.Types.Item)
540
- │ │ │ ├─ zones + zone (optional) — zone rows + mapper to { key, label, x, y, width, height, pattern?, geometry?, tone?, color?, bg?, fillOpacity?, weight?, layer? }
541
- │ │ │ ├─ links + link (optional) — link rows + mapper to { key, from, to, label?, metric?, style?, route?, via?, layer? }
542
- │ │ │ ├─ nets + net (optional) — manifold/bus rows (ONE row = many sources → many destinations) + mapper to { key, sources, destinations, label?, metric?, style?, route?, via?, layer? }; drawn P&ID-style — a header BAR spans each multi-endpoint side with a stub per endpoint, the trunk runs bar → via… → bar (junction dots ONLY where a tap 3-way joins a bar)
543
- │ │ │ ├─ selectionMode (optional) — "single" (default) | "multiple" | "range"; multiple ⇒ marquee tool (drag-box multi-select w/ live preview + count; plain box/tap replaces, Shift extends)
544
- │ │ │ ├─ onSelect / onSelectionChange (optional) — item click (key) / full selection-set events ({key?, selected, selectedKeys, additive, region?}); works in every tool (grab/zoom/marquee)
545
- │ │ │ ├─ onSelectZone / onZoneSelectionChange (optional) — zone click-select (items win hit-test; innermost zone wins; Shift extends) reporting the zones AND their childItemKeys
546
- │ │ │ ├─ selectZoomFocus (optional) — a canvas selection also moves the camera (tap flies, marquee fits)
547
- │ │ │ ├─ onItemOpen (optional) — double-click drill-in (background double-click keeps Fit/reset)
548
- │ │ │ ├─ onViewportChange (optional) — debounced viewport-settled reporting ({zoom, minX, minY, maxX, maxY}) for sync / lazy-load / persist
549
- │ │ │ ├─ linkMode (optional) — connect-gesture mode: "draw" (adds locally, form-input style) | "connect" (event-only, repeatable: plan operations); Shift+drag ADDS to the session
550
- │ │ │ ├─ onCreateLink / onSelectLink / onEditLink / onDeleteLink (optional) — link lifecycle ({link, links, additive, existing} on create; click-select key; endpoint re-target; Del delete)
551
- │ │ │ ├─ canConnect (optional) — fn(from, to) => Bool vetoes pairs BEFORE they resolve (the draft never snaps; one rule covers links, Shift-session/net extensions, and re-targets; a throwing validator fails OPEN)
552
- │ │ │ ├─ onEditNet (optional) — net membership edits: trunk/bar click selects the WHOLE net, a STUB click selects ONE leg (Del removes just that endpoint; onEditNet reports membership AFTER; a side emptying deletes the whole net via onDeleteLink). Shift-session gestures keep ONE bus (a member never flips sides); with a LINK selected, Shift-drag from its endpoint SEEDS the session with that link (onCreateLink.absorbed lists absorbed keys — delete those rows when upserting); with a NET selected, Shift-drag out of a member adds the target as a leg; a Shift connect-session commits as a net (onCreateLink.net = {key, sources, destinations}, stable session key — upsert by net.key)
553
- │ │ │ ├─ readOnly / readOnlyLinks / readOnlyItems (optional) — flattened per-domain edit gates
554
- │ │ │ ├─ onMoveItem (optional) — move tool (readOnlyItems off): drags items to new positions; a selected item moves the WHOLE selection rigidly, local-first; fires once per gesture ({key, x, y, keys, dx, dy})
555
- │ │ │ ├─ itemHover / zoneHover / linkHover (optional) — East fn key => UIComponent lazy hover cards (charts in a card over a tank / pipe); any camera or edit gesture closes them; hover ignores readOnly + locked layers
556
- │ │ │ ├─ slice + affordances (optional) — bound slice chrome (default ["search"]); flat effect props sliceHidden / sliceOpacity / sliceDesaturate / sliceDot / sliceEmphasis:"halo"|"pulse" / sliceFrame / sliceFrameFit keep filtered-OUT items as ghost/desaturate/dot context + emphasise the remainder instead of hiding — feed the FULL set (Slice.partition) and mark item.excluded (e.g. t.matched.not())
557
- │ │ │ ├─ sliceSelectField (optional) — bound-slice fieldId a marquee/tap selection writes an `in` filter of selected item keys into (one-directional selection→slice) — pair with the ghost effect (not a Slice.rows feed on the same slice)
558
- │ │ │ ├─ layers (optional) — [{ key, label, tone?, visible?, locked?, opacity? }] + tag items/zones/links with layer:"key"; a canvas layer button opens a show/hide/solo/lock panel (persists per panel); lock ⇒ non-selectable (click-through), opacity dims
559
- │ │ │ ├─ scaleUnit / grid / navigator / minimap (optional) — scale bar unit, metric grid (default on), zones→items TOC (default when zones exist), minimap (default 25+ items)
560
- │ │ │ └─ height / maxHeight (optional) — uniform sizing (#320); default aspect-driven, capped 75vh
561
- │ │ └─ Factories:
562
- │ │ ├─ Schematic.circle(r) / .polyline(verts, {width}) / .polygon(verts) / .rect() — item footprints + zone geometry
563
- │ │ ├─ Schematic.outline() / .hatch() — zone boundary patterns
564
- │ │ └─ Schematic.solid() / .dashed() — link / net stroke styles
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
565
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
566
538
  │ ├─ <Map markers={…} center={Map.at(lat,lng)} zoom={n} /> — interactive geographic basemap; read-only / selection-only
567
539
  │ │ ├─ Props:
@@ -1021,12 +993,14 @@ Task → Which tag?
1021
993
  │ ├─ Where a bare token / status value plugs in:
1022
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
1023
995
  │ │ ├─ Table rowStatus — fn(rowIndex) => StatusToken row tint
1024
- │ │ ├─ Schematic item { status } (Option token dot) and { tone } (brand|ink|muted|success|warning|danger stroke override)
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)
1025
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`
1026
998
  │ │ ├─ Matrix.marker { status } — corner markers
1027
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)
1028
1000
  │ │ └─ <Meter tone> / BarStrip item { tone } / SegmentedMeter segment { tone } — bar fills
1029
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
1030
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
1031
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
1032
1006
  │
@@ -1089,8 +1063,9 @@ pinned read the server refuses because the dataset has moved on (409
1089
1063
  `dataset_hash_mismatch`) rediscovers the current snapshot instead of failing
1090
1064
  its window. How a consumer bridges the move is its own: e3-ui's `<Plan>` and
1091
1065
  `<Sheet>` keep the rows they show until the new snapshot's windows land; the
1092
- Sheet clears a standing key search, and the Plan asks it again there, its
1093
- text kept.
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.
1094
1069
 
1095
1070
  ## Key Patterns
1096
1071
 
@@ -1222,7 +1197,7 @@ Non-UI sub-structures are never child sub-tags.
1222
1197
  Every size prop is a **plain string** and every renderer parses it the same
1223
1198
  way (`parseCssSize`). Four spellings, uniform across data components (`<Table>`,
1224
1199
  e3-ui's `<Plan>`, `<Matrix>`,
1225
- `<Library>`, `<Schematic>`, `<SnapGrid>`) and layout primitives (`<Box>` / `<Flex>` /
1200
+ `<Library>`, `<SnapGrid>`) and layout primitives (`<Box>` / `<Flex>` /
1226
1201
  `<Stack>` / `<Grid>` / `<Card>`):
1227
1202
 
1228
1203
  | Value | Means |
@@ -1514,11 +1489,13 @@ tier so they stay subordinate to tags at every density.
1514
1489
  and written back (through an e3 record's patch, or `onUpdate` / `onApply`)
1515
1490
  — the e3-ui skill documents it; for reading, sorting and reviewing a
1516
1491
  dataset, `<Table>`.
1517
- - **Flowchart vs Schematic** — `<Schematic>` is a world-coordinate 2D canvas
1518
- (data carries x/y; zones, footprints, camera); e3-ui's `<Flowchart>`
1519
- (#1243) derives its whole layout from lanes + links (no coordinates) for
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
1520
1497
  state-transition / process-flow reading, with decision triggers and
1521
- evidence on the links — the e3-ui skill documents it.
1498
+ evidence on the links.
1522
1499
  - **Library vs Deck** — `<Library>` is the draggable palette (DnD source),
1523
1500
  or with `variant="gallery"` a library a person browses — large cards, each
1524
1501
  with its media, a byline and an action a click follows;