@niscorp/nova 0.1.1 → 0.1.2
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.
- package/ACTION_DOCS.md +121 -30
- package/ADAPTER.md +167 -12
- package/CHANGELOG.md +12 -0
- package/DESIGN.md +45 -22
- package/I18N_DOCS.md +4 -4
- package/LAYOUT_DOCS.md +55 -14
- package/REACT_DOCS.md +52 -16
- package/README.md +54 -19
- package/SHELL_DOCS.md +136 -16
- package/TERMINAL_DOCS.md +13 -7
- package/dist/adapters/dom/components/index.d.cts +2 -2
- package/dist/adapters/dom/components/index.d.ts +2 -2
- package/dist/adapters/dom/index.cjs +351 -53
- package/dist/adapters/dom/index.cjs.map +1 -1
- package/dist/adapters/dom/index.d.cts +4 -2
- package/dist/adapters/dom/index.d.ts +4 -2
- package/dist/adapters/dom/index.js +2 -2
- package/dist/adapters/dom/server.cjs +356 -55
- package/dist/adapters/dom/server.cjs.map +1 -1
- package/dist/adapters/dom/server.d.cts +2 -2
- package/dist/adapters/dom/server.d.ts +2 -2
- package/dist/adapters/dom/server.js +7 -4
- package/dist/adapters/dom/server.js.map +1 -1
- package/dist/adapters/react/components/index.d.cts +2 -2
- package/dist/adapters/react/components/index.d.ts +2 -2
- package/dist/adapters/react/index.d.cts +4 -4
- package/dist/adapters/react/index.d.ts +4 -4
- package/dist/adapters/tty/components/index.d.cts +2 -2
- package/dist/adapters/tty/components/index.d.ts +2 -2
- package/dist/adapters/tty/index.d.cts +2 -2
- package/dist/adapters/tty/index.d.ts +2 -2
- package/dist/adapters/vue/components/index.d.cts +5 -5
- package/dist/adapters/vue/components/index.d.ts +5 -5
- package/dist/adapters/vue/index.d.cts +4 -4
- package/dist/adapters/vue/index.d.ts +4 -4
- package/dist/adapters/vue/index.js +1 -1
- package/dist/agent/index.d.cts +2 -2
- package/dist/agent/index.d.ts +2 -2
- package/dist/{chunk-7B3RDENH.js → chunk-6N4WRC5V.js} +9 -4
- package/dist/chunk-6N4WRC5V.js.map +1 -0
- package/dist/chunk-FQAJ24KA.js +408 -0
- package/dist/chunk-FQAJ24KA.js.map +1 -0
- package/dist/devtools/index.d.cts +2 -2
- package/dist/devtools/index.d.ts +2 -2
- package/dist/i18n/index.d.cts +2 -2
- package/dist/i18n/index.d.ts +2 -2
- package/dist/index.cjs +8 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +5 -5
- package/dist/index.d.ts +5 -5
- package/dist/index.js +2 -2
- package/dist/{palette-CP0wd3bE.d.ts → palette-Mx7XHYC6.d.ts} +1 -1
- package/dist/{palette-lm0bU9i5.d.cts → palette-wbJB_svk.d.cts} +1 -1
- package/dist/reflect/index.d.cts +2 -2
- package/dist/reflect/index.d.ts +2 -2
- package/dist/{types-DdltMfw7.d.ts → types-B-rjaUX0.d.ts} +1 -1
- package/dist/{types-Boh9ckdG.d.ts → types-BB9RXel5.d.ts} +1 -1
- package/dist/{types-De0KpxfI.d.cts → types-BLVRduoz.d.cts} +11 -1
- package/dist/{types-DhHL0twe.d.ts → types-B_nOtkyt.d.ts} +1 -1
- package/dist/{types-Brc7v_pS.d.ts → types-DE77Jl2W.d.ts} +11 -1
- package/dist/{types-Dv6JLmgo.d.cts → types-PDXOkvtK.d.cts} +1 -1
- package/dist/{types-Q80YtOQt.d.cts → types-mRKXqZPX.d.cts} +1 -1
- package/dist/{types-ByNSwtUV.d.cts → types-uk19d6KC.d.cts} +1 -1
- package/package.json +7 -7
- package/dist/chunk-7B3RDENH.js.map +0 -1
- package/dist/chunk-OAMC6R6E.js +0 -121
- package/dist/chunk-OAMC6R6E.js.map +0 -1
package/DESIGN.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Declarative, framework-agnostic UI runtime. JSON layouts, action lifecycles,
|
|
4
4
|
shell orchestration. The core is pure TypeScript with zero framework
|
|
5
|
-
dependencies.
|
|
5
|
+
dependencies. Adapters (React, Vue, plain DOM, TTY, Ink) consume the
|
|
6
6
|
`RenderNode[]` output.
|
|
7
7
|
|
|
8
8
|
This document describes the package as it actually exists today. Anything
|
|
@@ -39,10 +39,10 @@ action, and shell never import from each other transitively except via
|
|
|
39
39
|
`@layout` / `@action` / `@shell` aliases at well-defined seams (the shell
|
|
40
40
|
wires everything together at construction time).
|
|
41
41
|
|
|
42
|
-
Around the core sit
|
|
42
|
+
Around the core sit six subpath areas:
|
|
43
43
|
|
|
44
|
-
- **`adapters/`** — framework bindings (`react/`, `dom
|
|
45
|
-
export subpath. Adapters import only the core public surface; core never
|
|
44
|
+
- **`adapters/`** — framework bindings (`react/`, `vue/`, `dom/`, `tty/`,
|
|
45
|
+
`ink/`), each with its own export subpath. Adapters import only the core public surface; core never
|
|
46
46
|
imports an adapter. See [ADAPTER.md](ADAPTER.md).
|
|
47
47
|
- **`reflect/`** — read-only introspection (`@niscorp/nova/reflect`): layout
|
|
48
48
|
walks, shell snapshots, the action graph, audit classification, and what an
|
|
@@ -52,6 +52,11 @@ Around the core sit four subpath areas:
|
|
|
52
52
|
plain ActionDefinitions plus fns over `reflect/`.
|
|
53
53
|
- **`agent/`** — cortex agents owned by nova (`@niscorp/nova/agent`);
|
|
54
54
|
importing the subpath is what pulls in the optional cortex peer.
|
|
55
|
+
- **`i18n/`** — the language surface (`@niscorp/nova/i18n`): the phrase-key
|
|
56
|
+
vocabulary, the harvest, `translateRenderTree`, `fillPhrase`. The swap itself
|
|
57
|
+
runs in the renderer. See [I18N_DOCS.md](I18N_DOCS.md).
|
|
58
|
+
- **`migrations/`** — nova's grammar as a strata sequence
|
|
59
|
+
(`@niscorp/nova/migrations`: `NOVA_SEQUENCE`, `NOVA_SCHEMAS`).
|
|
55
60
|
|
|
56
61
|
---
|
|
57
62
|
|
|
@@ -73,7 +78,9 @@ NovaError (base; carries code + context + cause)
|
|
|
73
78
|
├── UnknownActionError (shell.push of unregistered id)
|
|
74
79
|
├── UnknownFragmentError (push `with` names an unregistered fragment)
|
|
75
80
|
├── ShellDisposedError (post-dispose call)
|
|
76
|
-
|
|
81
|
+
├── UnknownFunctionError (`fn` endpoint names an unregistered function)
|
|
82
|
+
├── LifecycleError (hook failure; carries hook + cause)
|
|
83
|
+
└── MutationError (a mutation op that cannot apply)
|
|
77
84
|
```
|
|
78
85
|
|
|
79
86
|
Subclasses are added only when there is a real throw site. No dead exports.
|
|
@@ -153,6 +160,8 @@ Zod schemas for the layout DSL:
|
|
|
153
160
|
- `ConditionalNodeSchema` — `{ if, then, else? }`.
|
|
154
161
|
- `LoopNodeSchema` — `{ for, as, key?, do }`.
|
|
155
162
|
- `LayoutRefNodeSchema` — `{ ref }`. Resolves against the layout store.
|
|
163
|
+
- `SlotNodeSchema` — `{ slot }`. Filled at compose time (see "ActionFragment
|
|
164
|
+
composition").
|
|
156
165
|
- `LayoutNodeSchema` — discriminated union of all of the above plus arrays.
|
|
157
166
|
|
|
158
167
|
### Renderer (`layout/renderer.ts`)
|
|
@@ -161,10 +170,10 @@ Walks a `LayoutNode` and emits a `RenderNode[]` tree:
|
|
|
161
170
|
|
|
162
171
|
```
|
|
163
172
|
RenderComponentNode { type: 'component'; name; props; children;
|
|
164
|
-
ref?; model?: { ref, path } }
|
|
173
|
+
ref?; key?; model?: { ref, path } }
|
|
165
174
|
RenderTextNode { type: 'text'; value }
|
|
166
175
|
RenderFragmentNode { type: 'fragment'; children }
|
|
167
|
-
RenderErrorNode { type: 'error'; message }
|
|
176
|
+
RenderErrorNode { type: 'error'; code; message; nodeRef?; key? }
|
|
168
177
|
```
|
|
169
178
|
|
|
170
179
|
The renderer:
|
|
@@ -199,7 +208,8 @@ own component implementations later.
|
|
|
199
208
|
Split into focused files:
|
|
200
209
|
|
|
201
210
|
- `effects.ts` — `CallEffect`, `EmitEffect`, navigation effects (`Push`,
|
|
202
|
-
`Pop`, `Replace`
|
|
211
|
+
`Pop`, `Replace`, `PopTo`, `ResetTo`, `RemoveInstance`, `RemoveSelf`,
|
|
212
|
+
`Reconcile`, `Reload`), and `StepSchema = Mutation | Effect`.
|
|
203
213
|
- `triggers.ts` — `TriggerConfigSchema { event?, message?, ref?, do }`.
|
|
204
214
|
- `endpoints.ts` — `EndpointConfigSchema`: a function call `{ fn, target?,
|
|
205
215
|
errorTarget? }` **or** an HTTP call `{ method, url, headers?, request?,
|
|
@@ -213,8 +223,7 @@ Split into focused files:
|
|
|
213
223
|
data is never transformed.
|
|
214
224
|
- `lifecycle.ts` — `LifecycleConfigSchema { mount?, unmount?, suspend?,
|
|
215
225
|
resume? }`. Each is `Step[]`.
|
|
216
|
-
- `index.ts` — `
|
|
217
|
-
exports.
|
|
226
|
+
- `index.ts` — `ActionDefinitionSchema`, `ActionFragmentSchema`, exports.
|
|
218
227
|
|
|
219
228
|
### Mutations (`action/mutations/`)
|
|
220
229
|
|
|
@@ -225,7 +234,7 @@ the first match. Adding a mutation is a new file, not an edit to a
|
|
|
225
234
|
giant switch.
|
|
226
235
|
|
|
227
236
|
Current ops: `set`, `toggle`, `increment`, `decrement`, `push`, `pop`,
|
|
228
|
-
`removeAt`, `clear`, `reset`.
|
|
237
|
+
`removeAt`, `move`, `clear`, `reset`.
|
|
229
238
|
|
|
230
239
|
Each op has its own Zod schema. The combined `MutationSchema` is the
|
|
231
240
|
union.
|
|
@@ -317,7 +326,7 @@ The shell exposes runtimes via `shell.getRuntime(id)` typed as
|
|
|
317
326
|
```
|
|
318
327
|
PublicActionRuntime = {
|
|
319
328
|
readonly instance, definition;
|
|
320
|
-
getData(); render();
|
|
329
|
+
getData(); setData(next); render();
|
|
321
330
|
onDataChange(handler); onStatusChange(handler);
|
|
322
331
|
}
|
|
323
332
|
```
|
|
@@ -350,7 +359,7 @@ The user's entry point. Splits responsibilities across small files:
|
|
|
350
359
|
- **`lifecycle-ops.ts`** — `unmountInstance`, `suspendTop`, `resumeTop`
|
|
351
360
|
bookkeeping. Idempotent unmount via an internal `Set`.
|
|
352
361
|
- **`canvas.ts`** — pure stack: `pushInstance`, `popInstance`,
|
|
353
|
-
`clearStack`, `peek`. No I/O.
|
|
362
|
+
`replaceTop`, `clearStack`, `peek`. No I/O.
|
|
354
363
|
- **`shell-internals.ts`** — `validateActions` (boundary Zod validation
|
|
355
364
|
on the action map at construction), `snapshotCanvas`,
|
|
356
365
|
`createRuntimeFactory`, and the test escape hatch
|
|
@@ -365,17 +374,22 @@ createShell(config: ShellConfig): Shell
|
|
|
365
374
|
`Shell` exposes:
|
|
366
375
|
|
|
367
376
|
```
|
|
368
|
-
push(canvasId, actionId, input?, fragments?): string
|
|
377
|
+
push(canvasId, actionId, input?, fragments?, options?): string
|
|
378
|
+
originOf(instanceId): string | undefined
|
|
369
379
|
pop(canvasId): void
|
|
370
380
|
popTo(canvasId, instanceId): void
|
|
381
|
+
removeInstance(canvasId, instanceId): void
|
|
371
382
|
replace(canvasId, actionId, input?, fragments?): string
|
|
372
383
|
clear(canvasId): void
|
|
384
|
+
back(): boolean
|
|
373
385
|
registerAction(definition): void
|
|
374
386
|
removeAction(actionId): void
|
|
375
387
|
registerFragment(fragment): void
|
|
376
388
|
addCanvas(config): void
|
|
377
389
|
removeCanvas(canvasId): void
|
|
378
390
|
setCanvasLayout(layout): void
|
|
391
|
+
setPhrases(phrases): void
|
|
392
|
+
getPhrases(): Phrasebook | undefined
|
|
379
393
|
setLayout(refId, layout): void
|
|
380
394
|
getCanvasState(canvasId): CanvasState
|
|
381
395
|
getRuntime(instanceId): PublicActionRuntime | undefined
|
|
@@ -509,9 +523,13 @@ yet beyond a placeholder:
|
|
|
509
523
|
across processes. Serving rendered trees over a socket is moss's job;
|
|
510
524
|
nova ships the surface it targets (`RenderApi`, ActionSlot-preserving
|
|
511
525
|
`flattenRenderTree`).
|
|
512
|
-
-
|
|
513
|
-
|
|
514
|
-
|
|
526
|
+
- ~~**Schema versioning.**~~ **Implemented.** The action, fragment and
|
|
527
|
+
layout grammars are a strata sequence at `@niscorp/nova/migrations`
|
|
528
|
+
(`NOVA_SEQUENCE`).
|
|
529
|
+
- **LLM tooling / JSON Schema generation / catalog.** Kept out of the core
|
|
530
|
+
— nova is a runtime, not a generator. What ships is the optional
|
|
531
|
+
`@niscorp/nova/agent` subpath (`layoutAgent`, `paletteFromRegistry`,
|
|
532
|
+
`collectInteractive`); catalogs are the host's.
|
|
515
533
|
|
|
516
534
|
---
|
|
517
535
|
|
|
@@ -557,6 +575,7 @@ A nova component registered with the React adapter receives:
|
|
|
557
575
|
- `children?: ReactNode` — populated when the layout node has children
|
|
558
576
|
- `novaModel?: { ref, path }` — populated when the layout node has a
|
|
559
577
|
`model:` binding (so the component can dispatch `ui:model` events)
|
|
578
|
+
- `novaRef?: string` — the layout node's `ref`, when set
|
|
560
579
|
- ...the layout node's `props` spread on top
|
|
561
580
|
|
|
562
581
|
That's it. Components do not receive a `shell`, an `instanceId`, an
|
|
@@ -612,7 +631,7 @@ default, and that the wrapper still mounts for an empty slot so exits can run).
|
|
|
612
631
|
Both `useRenderTree` and `useCanvas` cache their snapshot via `useRef`
|
|
613
632
|
so `useSyncExternalStore`'s `getSnapshot` returns a stable reference
|
|
614
633
|
when nothing has changed. This is mandatory for tearing-safety in
|
|
615
|
-
React
|
|
634
|
+
React's concurrent rendering.
|
|
616
635
|
|
|
617
636
|
- **`useRenderTree`** caches by **data identity**. The runtime exposes
|
|
618
637
|
the current data object; if the cached data reference is `===` to the
|
|
@@ -631,9 +650,9 @@ Both contracts are verified by `test/react/snapshot-stability.test.tsx`,
|
|
|
631
650
|
which asserts referential equality across re-renders without state
|
|
632
651
|
changes and reference inequality after a real data or stack change.
|
|
633
652
|
|
|
634
|
-
### React
|
|
653
|
+
### React compatibility
|
|
635
654
|
|
|
636
|
-
- Requires React
|
|
655
|
+
- Requires React 19 (the `react` peer is `^19.2.4`; uses `useSyncExternalStore`).
|
|
637
656
|
- Concurrent rendering: tearing-safe by construction.
|
|
638
657
|
- StrictMode: works correctly; snapshot caches survive effect double-
|
|
639
658
|
invocation.
|
|
@@ -676,8 +695,12 @@ wire weight.
|
|
|
676
695
|
|
|
677
696
|
`src/adapters/dom/` (`@niscorp/nova/adapters/dom`) renders a served tree to
|
|
678
697
|
vanilla DOM against a `RenderApi`: events wired by convention (`ref` →
|
|
679
|
-
`ui:click`, `model` → `ui:model`/`ui:key`), `debounce` honoured
|
|
680
|
-
|
|
698
|
+
`ui:click`, `model` → `ui:model`/`ui:key`), `debounce` honoured. It keeps the
|
|
699
|
+
tree it drew beside the DOM that tree produced and patches the page: an
|
|
700
|
+
element whose part of the tree did not change is the same node, never taken
|
|
701
|
+
off the page, so focus, scroll and a running animation are kept, and a field
|
|
702
|
+
being typed in is not replaced (ADAPTER.md, "The DOM adapter keeps what did
|
|
703
|
+
not change"). Its components
|
|
681
704
|
kit (`/adapters/dom/components`: `defaultRegistry`, `fallback`,
|
|
682
705
|
`DEFAULT_CSS`, `ROOT_CLASS`) is the batteries-included reference set. It
|
|
683
706
|
exists as the proof that a terminal needs no framework — and as the adapter
|
package/I18N_DOCS.md
CHANGED
|
@@ -38,8 +38,8 @@ child into a text node.
|
|
|
38
38
|
|
|
39
39
|
Every tree in the system comes out of `renderLayout` / `renderLayoutFromStore`,
|
|
40
40
|
and there are three callers — the action runtime, the shell, and
|
|
41
|
-
`<Nova.Layout>`. So an **adapter contains no i18n code at all**. React,
|
|
42
|
-
ink and any adapter written later receive words that are already in the reader's
|
|
41
|
+
`<Nova.Layout>`. So an **adapter contains no i18n code at all**. React, vue, dom,
|
|
42
|
+
tty, ink and any adapter written later receive words that are already in the reader's
|
|
43
43
|
language and never learn that a second one exists.
|
|
44
44
|
|
|
45
45
|
That is deliberate. An adapter renders a `RenderNode`; if i18n changed the
|
|
@@ -210,10 +210,10 @@ From `@niscorp/nova/i18n`:
|
|
|
210
210
|
| `harvestLayout` / `harvestDefinition` / `harvestDefinitions` | Enumerate the phrases an artifact can show |
|
|
211
211
|
| `missingFrom(harvested, book)` | What a language is still missing |
|
|
212
212
|
| `fillPhrase(value)` | Close a counted phrase held as data, outside a render |
|
|
213
|
-
| `translateRenderTree(tree,
|
|
213
|
+
| `translateRenderTree(tree, { phrases, keys?, onMiss? })` | For a tree you did **not** render — a replayed frame, a fixture. An empty book returns the same tree, patterns unfilled |
|
|
214
214
|
| `DEFAULT_PHRASE_KEYS` | The default prose prop set |
|
|
215
215
|
| `isBinding` / `isPhrase` / `matcherFor` | The primitives the rules are built from |
|
|
216
|
-
| `Phrasebook` / `PhraseKeys` | Types |
|
|
216
|
+
| `Phrasebook` / `PhraseKeys` / `PhraseKeyMatcher` / `TranslateOptions` / `HarvestedPhrase` | Types |
|
|
217
217
|
|
|
218
218
|
Config fields: `phrases`, `phraseKeys`, `onPhraseMiss` on `ShellConfig`,
|
|
219
219
|
`RenderContext`, `RenderOptions` and `<Nova.Layout>`. Shell methods:
|
package/LAYOUT_DOCS.md
CHANGED
|
@@ -80,6 +80,9 @@ The most common one. References a component by name; the registry supplies the i
|
|
|
80
80
|
- **`children`** *(optional)* — a single `LayoutNode` or an array of them. Components decide how to render their children slot.
|
|
81
81
|
- **`ref`** *(optional)* — a stable identifier. Used by triggers (`event: 'ui:click', ref: 'header-stack'`) and as the model binding key. If unset, the renderer auto-generates one for model-bound components.
|
|
82
82
|
- **`model`** *(optional)* — two-way binding path. See [Two-way binding](#two-way-binding).
|
|
83
|
+
- **`events`** *(optional)* — a record of event name → configuration. The schema accepts it; the renderer does not read it and it does not reach the `RenderNode`. Interaction is `ref` + an action trigger.
|
|
84
|
+
|
|
85
|
+
The node is strict: any other key fails `LayoutNodeSchema`.
|
|
83
86
|
|
|
84
87
|
### Resolved render output
|
|
85
88
|
|
|
@@ -96,6 +99,8 @@ A component node renders to a `RenderNode` of type `'component'`:
|
|
|
96
99
|
}
|
|
97
100
|
```
|
|
98
101
|
|
|
102
|
+
When `model` is set and the node has no explicit `value` prop, the renderer also adds `props.value` — the model path's current value.
|
|
103
|
+
|
|
99
104
|
The framework adapter (React) reads this and instantiates the React component with these props.
|
|
100
105
|
|
|
101
106
|
---
|
|
@@ -114,16 +119,16 @@ Render one of two branches based on a condition.
|
|
|
114
119
|
|
|
115
120
|
### Fields
|
|
116
121
|
|
|
117
|
-
- **`if`** *(required)* — a binding evaluated for truthiness. Strings are bindings, primitives are themselves, objects can be `{$if}` directives. Truthiness rules: `null`, `undefined`, `false`, `0`, `''`, `[]
|
|
122
|
+
- **`if`** *(required)* — a binding evaluated for truthiness. Strings are bindings, primitives are themselves, objects can be `{$if}` directives. Truthiness rules: `null`, `undefined`, `false`, `0`, `''`, `[]` are all falsy. Everything else is truthy — including an empty object `{}`.
|
|
118
123
|
- **`then`** *(required)* — `LayoutNode` rendered when the condition is truthy.
|
|
119
|
-
- **`else`** *(optional)* — `LayoutNode` rendered when the condition is falsy. If absent,
|
|
124
|
+
- **`else`** *(optional)* — `LayoutNode` rendered when the condition is falsy. If absent, nothing is rendered.
|
|
120
125
|
|
|
121
126
|
### Conditionals inside other places
|
|
122
127
|
|
|
123
128
|
There are **two kinds of conditional** in nova:
|
|
124
129
|
|
|
125
130
|
1. **Conditional NODE** (this one) — appears in the layout tree as a sibling of components. Swaps whole subtrees.
|
|
126
|
-
2. **`{$if}` directive** — appears inside a value position (e.g. a prop value, a string content). See [Bindings — directives](#directives).
|
|
131
|
+
2. **`{$if}` directive** — appears inside a value position (e.g. a prop value, a string content). See [Bindings — directives](#3-directives).
|
|
127
132
|
|
|
128
133
|
Use the node form when you're swapping whole UI sections. Use the directive form when you're picking a value for a single field.
|
|
129
134
|
|
|
@@ -152,12 +157,12 @@ Iterate an array and render the body once per item.
|
|
|
152
157
|
|
|
153
158
|
- **`for`** *(required)* — a binding that resolves to an array. If it doesn't resolve to an array, the loop renders nothing (graceful empty).
|
|
154
159
|
- **`as`** *(required)* — the variable name used for the current item inside `do`. References as `$<name>` (no dot).
|
|
155
|
-
- **`key`** *(optional)* — a path on each item used for stable
|
|
160
|
+
- **`key`** *(optional)* — a path on each item (e.g. `'id'`) used for stable identity. The renderer stamps each item's output with `key`: the value at that path, or the index when `key` is omitted. Adapters key by it, so looped rows can share a `ref` without colliding.
|
|
156
161
|
- **`do`** *(required)* — the `LayoutNode` rendered once per item, with the loop variable in scope.
|
|
157
162
|
|
|
158
|
-
### The `index`
|
|
163
|
+
### The `index` and `items` variables
|
|
159
164
|
|
|
160
|
-
Inside the loop body, the variable `index` is automatically bound to the current iteration index (0-based). Reference
|
|
165
|
+
Inside the loop body, the variable `index` is automatically bound to the current iteration index (0-based), and `items` to the array being iterated (`$items`) — so a control inside the loop can address the whole list. Both names are reserved: with an `as` of `'index'` or `'items'` the loop's own value wins and the item is unreachable. Reference the index as `$index`:
|
|
161
166
|
|
|
162
167
|
```ts
|
|
163
168
|
{
|
|
@@ -305,7 +310,22 @@ Inside a value position (a prop value, a children string, etc.), you can use the
|
|
|
305
310
|
}
|
|
306
311
|
```
|
|
307
312
|
|
|
308
|
-
Truthiness rules are the same as conditional nodes.
|
|
313
|
+
Truthiness rules are the same as conditional nodes. Without `$else`, a falsy `$if` resolves to `undefined`.
|
|
314
|
+
|
|
315
|
+
Four more directives resolve in the same positions:
|
|
316
|
+
|
|
317
|
+
```ts
|
|
318
|
+
{ $eq: ['$.status', 'open'] } // → true when both resolved operands are strictly equal
|
|
319
|
+
{ $exists: '$.record.id' } // → true when the operand resolves to anything but undefined
|
|
320
|
+
{ $at: ['$.results', '$.cursor'] } // → the array element at a (dynamic) index
|
|
321
|
+
{ $at: ['$.results', '$.cursor', 'id'] } // → one field of that element
|
|
322
|
+
{ $prism: <prism node> } // → the node evaluated by Prism against the innermost scope:
|
|
323
|
+
// the root data, or inside a loop the loop's own scope
|
|
324
|
+
// ({ <as>, index, items } — the root is not reachable there);
|
|
325
|
+
// undefined when it fails to evaluate
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
They compose: `{ $if: { $eq: ['$.tab', 'all'] }, $then: 'primary', $else: 'ghost' }`.
|
|
309
329
|
|
|
310
330
|
**Why both `if` (node) and `$if` (directive)?** Different layers. The node form swaps whole UI subtrees. The directive form picks a single value. The node form lives in the layout tree; the directive form lives in the value space.
|
|
311
331
|
|
|
@@ -313,13 +333,13 @@ Truthiness rules are the same as conditional nodes.
|
|
|
313
333
|
|
|
314
334
|
- Numbers, booleans, nulls — pass through unchanged
|
|
315
335
|
- Plain strings without `$` or `{{}}` — pass through unchanged
|
|
316
|
-
- Objects without `$if` — walked recursively, each value resolved
|
|
336
|
+
- Objects without a directive key (`$if`, `$eq`, `$exists`, `$at`, `$prism`) — walked recursively, each value resolved
|
|
317
337
|
|
|
318
338
|
---
|
|
319
339
|
|
|
320
340
|
## Two-way binding
|
|
321
341
|
|
|
322
|
-
Set `model: '<path>'` on a component to wire it for two-way data binding. The renderer resolves the path against the current scope chain (so loop variables work) and emits a `model: { ref, path }` field on the rendered node. The
|
|
342
|
+
Set `model: '<path>'` on a component to wire it for two-way data binding. The renderer resolves the path against the current scope chain (so loop variables work) and emits a `model: { ref, path }` field on the rendered node. The action runtime writes the event's `payload` back to that path when the component dispatches a `ui:model` event with that `ref` — before any `ui:model` trigger runs.
|
|
323
343
|
|
|
324
344
|
```ts
|
|
325
345
|
{
|
|
@@ -355,11 +375,16 @@ Type into the second input → `data.items[1].value` updates → re-render shows
|
|
|
355
375
|
{
|
|
356
376
|
store: LayoutStore, // for resolving LayoutRefs
|
|
357
377
|
registry: ComponentRegistry, // to validate component names
|
|
358
|
-
strict
|
|
359
|
-
onError
|
|
378
|
+
strict?: boolean, // throw on errors vs return error nodes (default false)
|
|
379
|
+
onError?: (error: NovaError) => void, // telemetry for non-strict errors
|
|
380
|
+
phrases?: Phrasebook, // i18n: source phrase → the reader's words (see I18N_DOCS.md)
|
|
381
|
+
phraseKeys?: PhraseKeys, // i18n: which prop keys carry prose
|
|
382
|
+
onPhraseMiss?: (phrase: string, where: string) => void, // i18n: a phrase with no entry in the book
|
|
360
383
|
}
|
|
361
384
|
```
|
|
362
385
|
|
|
386
|
+
`render({ layout, data?, store, registry, ... })` is the object-form alias of `renderLayout` — same options, named, with `data` optional.
|
|
387
|
+
|
|
363
388
|
When `strict: false` (the default), errors during rendering are caught at each subtree boundary, surfaced via `onError`, and replaced with an error `RenderNode`. Sibling subtrees keep rendering. When `strict: true`, errors propagate.
|
|
364
389
|
|
|
365
390
|
### Errors the renderer can produce
|
|
@@ -391,7 +416,9 @@ type RenderNode =
|
|
|
391
416
|
| { type: 'error'; code: string; message: string; nodeRef?: string };
|
|
392
417
|
```
|
|
393
418
|
|
|
394
|
-
|
|
419
|
+
Every variant may also carry `key?: string` — the identity key the renderer stamps on a loop item's output (see [Loop nodes](#loop-nodes)), distinct from `ref`.
|
|
420
|
+
|
|
421
|
+
This is the contract between the renderer and any framework adapter. The React adapter walks this tree and instantiates the registered React components. The Vue, DOM, TTY and Ink adapters (`@niscorp/nova/adapters/*`) do the same on their own surfaces.
|
|
395
422
|
|
|
396
423
|
---
|
|
397
424
|
|
|
@@ -420,9 +447,16 @@ registry.registerAll({
|
|
|
420
447
|
Input,
|
|
421
448
|
Button,
|
|
422
449
|
Box,
|
|
450
|
+
MyButton: { component: myButtonComponent, meta: { description: 'A clickable button.' } },
|
|
423
451
|
});
|
|
452
|
+
|
|
453
|
+
registry.get('MyButton'); // → { component, meta } | undefined
|
|
454
|
+
registry.has('MyButton'); // → boolean
|
|
455
|
+
registry.list(); // → array of registered names
|
|
424
456
|
```
|
|
425
457
|
|
|
458
|
+
Meta is `{ description?, propsSchema?, events? }` — `events` maps an event name to `{ description?, payloadType? }`.
|
|
459
|
+
|
|
426
460
|
### `registerAll` and static meta
|
|
427
461
|
|
|
428
462
|
If a component carries a static `.meta` property, `registerAll` picks it up automatically. Explicit meta in the call overrides static. See `REACT_DOCS.md` for the React-specific component shape.
|
|
@@ -453,8 +487,9 @@ const store = createLayoutStore();
|
|
|
453
487
|
|
|
454
488
|
store.set('user-card', { component: 'Box', children: [...] });
|
|
455
489
|
store.get('user-card'); // → the stored layout, or undefined
|
|
456
|
-
store.
|
|
490
|
+
store.delete('user-card'); // remove it
|
|
457
491
|
store.list(); // → array of stored ids
|
|
492
|
+
store.resolveReferences(layout); // → the layout with every { ref } it can resolve inlined
|
|
458
493
|
```
|
|
459
494
|
|
|
460
495
|
`set` validates the layout against `LayoutNodeSchema` and throws `DefinitionValidationError` if it doesn't parse. So you can't accidentally store an invalid layout.
|
|
@@ -478,7 +513,7 @@ In **strict mode** (`strict: true` on the render context) these throw. In **lax
|
|
|
478
513
|
|
|
479
514
|
```ts
|
|
480
515
|
// Component
|
|
481
|
-
{ component: string, props?: object, children?: LayoutNode | LayoutNode[], ref?: string, model?: string }
|
|
516
|
+
{ component: string, props?: object, children?: LayoutNode | LayoutNode[], ref?: string, model?: string, events?: object }
|
|
482
517
|
|
|
483
518
|
// Conditional (node form)
|
|
484
519
|
{ if: Resolvable, then: LayoutNode, else?: LayoutNode }
|
|
@@ -500,6 +535,12 @@ In **strict mode** (`strict: true` on the render context) these throw. In **lax
|
|
|
500
535
|
|
|
501
536
|
// Conditional (directive form, used in value positions)
|
|
502
537
|
{ $if: Resolvable, $then: any, $else?: any }
|
|
538
|
+
|
|
539
|
+
// Other value directives
|
|
540
|
+
{ $eq: [Resolvable, Resolvable] }
|
|
541
|
+
{ $exists: Resolvable }
|
|
542
|
+
{ $at: [Resolvable, Resolvable, field?] }
|
|
543
|
+
{ $prism: PrismNode }
|
|
503
544
|
```
|
|
504
545
|
|
|
505
546
|
For actions that drive data into the layout, see `ACTION_DOCS.md`. For wiring layouts into a React app, see `REACT_DOCS.md`.
|
package/REACT_DOCS.md
CHANGED
|
@@ -10,7 +10,7 @@ This guide is for **using** nova in React. For nova's framework-agnostic core, s
|
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
12
|
pnpm add @niscorp/nova
|
|
13
|
-
#
|
|
13
|
+
# `react` (^19.2.4) is an optional peer; a browser app brings `react-dom` itself.
|
|
14
14
|
```
|
|
15
15
|
|
|
16
16
|
`@niscorp/nova/adapters/react` is the same package, accessed via the subpath export. No separate install.
|
|
@@ -96,12 +96,13 @@ Use this when you have a `Shell`. The provider wires the shell's dispatch/publis
|
|
|
96
96
|
|
|
97
97
|
Props:
|
|
98
98
|
- **`shell`** — a `Shell` instance
|
|
99
|
-
- **`registry
|
|
99
|
+
- **`registry?`** — the component registry. Defaults to `shell.registry`; pass one only to render the shell against a different component set.
|
|
100
|
+
- **`slotWrapper?`** — see "The `slotWrapper` seam" below.
|
|
100
101
|
- **`children`** — the React subtree that uses nova hooks.
|
|
101
102
|
|
|
102
103
|
### `<NovaRenderProvider>` — render-only mode
|
|
103
104
|
|
|
104
|
-
Use this when you want to render a layout without a shell — for previews, tests, or the showroom. You supply the dispatch and publish functions yourself
|
|
105
|
+
Use this when you want to render a layout without a shell — for previews, tests, or the showroom. You supply the dispatch and publish functions yourself; both default to no-ops.
|
|
105
106
|
|
|
106
107
|
```tsx
|
|
107
108
|
<NovaRenderProvider
|
|
@@ -115,8 +116,9 @@ Use this when you want to render a layout without a shell — for previews, test
|
|
|
115
116
|
|
|
116
117
|
Props:
|
|
117
118
|
- **`registry`** — the component registry
|
|
118
|
-
- **`dispatch
|
|
119
|
-
- **`publish
|
|
119
|
+
- **`dispatch?`** — function to receive events from components (default: no-op)
|
|
120
|
+
- **`publish?`** — function to receive message bus publishes from components (default: no-op)
|
|
121
|
+
- **`slotWrapper?`** — see "The `slotWrapper` seam" below.
|
|
120
122
|
- **`fallback?`** — renderer for unregistered component names; omit for
|
|
121
123
|
strict `COMPONENT_NOT_FOUND` markers
|
|
122
124
|
- **`textWrapper?`** / **`errorMarker?`** — host-specific leaf renderers.
|
|
@@ -127,6 +129,20 @@ Props:
|
|
|
127
129
|
|
|
128
130
|
This is what the showroom uses for layout-only stories that don't need a shell.
|
|
129
131
|
|
|
132
|
+
### `<Nova.Layout>` / `<Nova.Shell>` / `<Nova.Canvas>` — mountable surfaces
|
|
133
|
+
|
|
134
|
+
Three components that hide the registry/provider/render-tree wiring. Each is also exported by its flat name (`NovaLayout`, `NovaShell`, `NovaCanvas`).
|
|
135
|
+
|
|
136
|
+
```tsx
|
|
137
|
+
<Nova.Layout layout={layout} data={data} /> // one layout, no shell
|
|
138
|
+
<Nova.Shell shell={shell} /> // the shell's whole frame
|
|
139
|
+
<Nova.Canvas id="main" /> // one canvas, inside a shell provider
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
- **`<Nova.Layout>`** — `layout` (a `LayoutNode` or a layout-store id), `data?`, `components?` (registered after the builtins), `registry?` / `store?` (pre-built; with `registry`, `components` and `builtins` are ignored), `builtins?` (default `true`), `strict?`, `onError?`, and the i18n fields `phrases?` / `phraseKeys?` / `onPhraseMiss?` (see `I18N_DOCS.md`). Renders through a `NovaRenderProvider` with no-op dispatch.
|
|
143
|
+
- **`<Nova.Shell>`** — `shell`, `registry?` (default `shell.registry`), `slotWrapper?`, `builtins?` (default `true`: registers the default component set on the registry if `CanvasSlot` is missing). Renders the shell's canvasLayout.
|
|
144
|
+
- **`<Nova.Canvas>`** — `id`, plus optional `shell`, `registry?`, `builtins?`. With `shell` it provides its own `NovaShellProvider`; without, it must sit inside one. Renders that canvas's actionLayout.
|
|
145
|
+
|
|
130
146
|
---
|
|
131
147
|
|
|
132
148
|
## Hooks
|
|
@@ -179,7 +195,7 @@ if (status === 'initializing') return <Spinner />;
|
|
|
179
195
|
|
|
180
196
|
### `useRenderTree(instanceId)`
|
|
181
197
|
|
|
182
|
-
Returns the live `RenderNode[]` for an action instance. Re-computes whenever the instance's data changes. **The result is referentially stable** when
|
|
198
|
+
Returns the live `RenderNode[]` for an action instance. Re-computes whenever the instance's data (or the shell's phrasebook) changes. **The result is referentially stable** when neither has changed — important for React's `useSyncExternalStore` and for downstream memoization.
|
|
183
199
|
|
|
184
200
|
```tsx
|
|
185
201
|
const tree = useRenderTree(activeId);
|
|
@@ -230,13 +246,15 @@ const tree = useRenderTree(activeId);
|
|
|
230
246
|
return <RenderTree nodes={tree} />;
|
|
231
247
|
```
|
|
232
248
|
|
|
249
|
+
An unregistered component name renders the provider's `fallback` when one was given, otherwise an error marker with code `COMPONENT_NOT_FOUND`. `<RenderNodeView node={...} />` is the single-node form `RenderTree` maps over.
|
|
250
|
+
|
|
233
251
|
That's the entire React-side rendering pipeline. Everything else is the components themselves.
|
|
234
252
|
|
|
235
253
|
---
|
|
236
254
|
|
|
237
255
|
## Writing your own component
|
|
238
256
|
|
|
239
|
-
A component for the React adapter is a React
|
|
257
|
+
A component for the React adapter is a React component typed as `NovaComponent<P>`:
|
|
240
258
|
|
|
241
259
|
```tsx
|
|
242
260
|
import type { NovaComponent } from '@niscorp/nova/adapters/react';
|
|
@@ -430,17 +448,20 @@ For React-level errors (a buggy component throwing during render), use `<NovaErr
|
|
|
430
448
|
```tsx
|
|
431
449
|
import { NovaErrorBoundary } from '@niscorp/nova/adapters/react';
|
|
432
450
|
|
|
433
|
-
<NovaErrorBoundary fallback={<div>Something broke
|
|
451
|
+
<NovaErrorBoundary fallback={(error) => <div>Something broke: {error.message}</div>}>
|
|
434
452
|
<CanvasView canvasId="main" />
|
|
435
453
|
</NovaErrorBoundary>
|
|
436
454
|
```
|
|
437
455
|
|
|
438
|
-
|
|
456
|
+
`fallback` is a function of the caught error; omitted, the boundary renders the error's message in a `<div data-nova-error-boundary role="alert">`. `onError(error, info)` reports the catch.
|
|
457
|
+
|
|
458
|
+
This is a real React class component (the only class in the package outside the error classes in `shared/errors.ts` — React still requires a class for an error boundary).
|
|
439
459
|
|
|
440
460
|
---
|
|
441
461
|
|
|
442
|
-
## React
|
|
462
|
+
## React compatibility
|
|
443
463
|
|
|
464
|
+
- **Version** — React 19 (`react` peer `^19.2.4`).
|
|
444
465
|
- **Strict mode** — fully supported. The hooks use `useSyncExternalStore` and the render-tree hook caches its snapshot via `useRef`, so dev-mode double-mounting doesn't break anything.
|
|
445
466
|
- **Concurrent rendering** — fully supported. `useSyncExternalStore` is tearing-safe by design.
|
|
446
467
|
- **Suspense** — not used as a loading model. Loading state is explicit data on the action (`{ loading: true }` as a regular field). A consumer can wrap nova components in `<Suspense>` but it never activates because nova never throws promises during render.
|
|
@@ -516,10 +537,14 @@ const SomeReactComponent = () => {
|
|
|
516
537
|
## Quick reference
|
|
517
538
|
|
|
518
539
|
```tsx
|
|
519
|
-
// Providers
|
|
520
|
-
<NovaShellProvider shell registry slotWrapper?>...</NovaShellProvider>
|
|
521
|
-
<NovaRenderProvider registry dispatch publish slotWrapper? fallback? textWrapper? errorMarker?>...</NovaRenderProvider>
|
|
522
|
-
|
|
540
|
+
// Providers
|
|
541
|
+
<NovaShellProvider shell registry? slotWrapper?>...</NovaShellProvider>
|
|
542
|
+
<NovaRenderProvider registry dispatch? publish? slotWrapper? fallback? textWrapper? errorMarker?>...</NovaRenderProvider>
|
|
543
|
+
|
|
544
|
+
// Mountable surfaces
|
|
545
|
+
<Nova.Layout layout data? components? registry? store? builtins? strict? onError? phrases? phraseKeys? onPhraseMiss? />
|
|
546
|
+
<Nova.Shell shell registry? slotWrapper? builtins? />
|
|
547
|
+
<Nova.Canvas id shell? registry? builtins? />
|
|
523
548
|
|
|
524
549
|
// Hooks
|
|
525
550
|
useShell() // → Shell (throws outside provider)
|
|
@@ -537,6 +562,7 @@ useSlotWrapper() // → SlotWrapper | undefined
|
|
|
537
562
|
|
|
538
563
|
// Render
|
|
539
564
|
<RenderTree nodes={...} />
|
|
565
|
+
<RenderNodeView node={...} />
|
|
540
566
|
|
|
541
567
|
// Slot wrapper (animation, gates, logging, error boundaries)
|
|
542
568
|
type SlotWrapper = FC<{
|
|
@@ -548,10 +574,10 @@ type SlotWrapper = FC<{
|
|
|
548
574
|
|
|
549
575
|
// Errors
|
|
550
576
|
<ErrorMarker code message />
|
|
551
|
-
<NovaErrorBoundary fallback
|
|
577
|
+
<NovaErrorBoundary fallback? onError?>...</NovaErrorBoundary> // fallback: (error) => ReactNode
|
|
552
578
|
|
|
553
579
|
// Component contract
|
|
554
|
-
type NovaComponent<P> = React.
|
|
580
|
+
type NovaComponent<P> = React.ComponentType<NovaComponentProps & P> & { meta?: ComponentMeta };
|
|
555
581
|
type NovaComponentProps = {
|
|
556
582
|
children?: ReactNode;
|
|
557
583
|
novaRef?: string;
|
|
@@ -559,4 +585,14 @@ type NovaComponentProps = {
|
|
|
559
585
|
};
|
|
560
586
|
```
|
|
561
587
|
|
|
588
|
+
## The Vue adapter
|
|
589
|
+
|
|
590
|
+
`@niscorp/nova/adapters/vue` (peer `vue` ^3.5, optional) is the same surface in Vue 3 render functions — no SFC compiler. The names match this guide: `NovaRenderProvider`, `NovaShellProvider`, `NovaShell`, `NovaCanvas`, `RenderTree`, `RenderNodeView`, `ErrorMarker`, `NovaErrorBoundary`, and every hook above as a composable. The differences:
|
|
591
|
+
|
|
592
|
+
- The shell-backed composables return a `Readonly<Ref<…>>` and take a ref or getter for their id (`useCanvas(() => props.id)`).
|
|
593
|
+
- The render context travels by provide/inject (`NovaRenderKey`, `NovaShellKey`); children reach a component as its default slot.
|
|
594
|
+
- There is no `Nova` namespace and no `NovaLayout`; `NovaRenderProvider` takes `fallback` but not `textWrapper` / `errorMarker`.
|
|
595
|
+
- `NovaErrorBoundary`'s `onError` receives Vue's info string.
|
|
596
|
+
- The kit is `registerNovaVueComponents(registry)` from `@niscorp/nova/adapters/vue/components`: the same nine names over the same props schemas.
|
|
597
|
+
|
|
562
598
|
For the layout language registered components consume, see `LAYOUT_DOCS.md`. For the action machinery the shell drives, see `ACTION_DOCS.md` and `SHELL_DOCS.md`.
|