@niscorp/nova 0.5.2 → 0.6.0
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 +17 -10
- package/ADAPTER.md +22 -2
- package/CHANGELOG.md +116 -0
- package/DESIGN.md +36 -17
- package/I18N_DOCS.md +8 -3
- package/LAYOUT_DOCS.md +16 -4
- package/REACT_DOCS.md +3 -3
- package/README.md +22 -7
- package/SHELL_DOCS.md +10 -6
- package/dist/adapters/dom/components/index.cjs +46 -63
- package/dist/adapters/dom/components/index.cjs.map +1 -1
- package/dist/adapters/dom/components/index.d.cts +2 -2
- package/dist/adapters/dom/components/index.d.ts +2 -2
- package/dist/adapters/dom/components/index.js +11 -28
- package/dist/adapters/dom/components/index.js.map +1 -1
- package/dist/adapters/dom/index.cjs +10 -9
- package/dist/adapters/dom/index.d.cts +2 -2
- package/dist/adapters/dom/index.d.ts +2 -2
- package/dist/adapters/dom/index.js +8 -7
- package/dist/adapters/dom/server.cjs +9 -8
- 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 +8 -7
- package/dist/adapters/dom/server.js.map +1 -1
- package/dist/adapters/ink/index.js +49 -6
- package/dist/adapters/ink/index.js.map +1 -1
- package/dist/adapters/react/components/index.cjs +28 -27
- package/dist/adapters/react/components/index.d.cts +4 -4
- package/dist/adapters/react/components/index.d.ts +4 -4
- package/dist/adapters/react/components/index.js +9 -8
- package/dist/adapters/react/index.cjs +31 -30
- package/dist/adapters/react/index.d.cts +4 -4
- package/dist/adapters/react/index.d.ts +4 -4
- package/dist/adapters/react/index.js +9 -8
- package/dist/adapters/tty/components/index.cjs +35 -40
- package/dist/adapters/tty/components/index.cjs.map +1 -1
- package/dist/adapters/tty/components/index.d.cts +3 -2
- package/dist/adapters/tty/components/index.d.ts +3 -2
- package/dist/adapters/tty/components/index.js +6 -22
- package/dist/adapters/tty/components/index.js.map +1 -1
- package/dist/adapters/tty/index.cjs +11 -10
- package/dist/adapters/tty/index.cjs.map +1 -1
- package/dist/adapters/tty/index.d.cts +2 -2
- package/dist/adapters/tty/index.d.ts +2 -2
- package/dist/adapters/tty/index.js +9 -8
- package/dist/adapters/tty/index.js.map +1 -1
- package/dist/adapters/vue/components/index.cjs +28 -27
- package/dist/adapters/vue/components/index.d.cts +15 -12
- package/dist/adapters/vue/components/index.d.ts +15 -12
- package/dist/adapters/vue/components/index.js +9 -8
- package/dist/adapters/vue/index.cjs +37 -36
- package/dist/adapters/vue/index.cjs.map +1 -1
- package/dist/adapters/vue/index.d.cts +4 -4
- package/dist/adapters/vue/index.d.ts +4 -4
- package/dist/adapters/vue/index.js +10 -9
- package/dist/adapters/vue/index.js.map +1 -1
- package/dist/agent/index.d.cts +2 -2
- package/dist/agent/index.d.ts +2 -2
- package/dist/{chunk-57PZEPIK.js → chunk-2USXK2G4.js} +30 -9
- package/dist/chunk-2USXK2G4.js.map +1 -0
- package/dist/{chunk-RVU6YEHO.cjs → chunk-3TBQ2KGZ.cjs} +12 -12
- package/dist/chunk-3TBQ2KGZ.cjs.map +1 -0
- package/dist/{chunk-ZR54IVVS.cjs → chunk-67LZ6PTU.cjs} +21 -21
- package/dist/chunk-67LZ6PTU.cjs.map +1 -0
- package/dist/{chunk-QTJ4ZQRM.cjs → chunk-7BRC4PL4.cjs} +4 -3
- package/dist/chunk-7BRC4PL4.cjs.map +1 -0
- package/dist/{chunk-M2ZZUSH3.js → chunk-AXRTJAXB.js} +8 -8
- package/dist/chunk-AXRTJAXB.js.map +1 -0
- package/dist/chunk-BA77UJOE.cjs +21 -0
- package/dist/chunk-BA77UJOE.cjs.map +1 -0
- package/dist/{chunk-OY7SCFTJ.js → chunk-BRJ333QF.js} +138 -70
- package/dist/chunk-BRJ333QF.js.map +1 -0
- package/dist/{chunk-5T26T2EJ.cjs → chunk-F2DZ4JMO.cjs} +34 -14
- package/dist/chunk-F2DZ4JMO.cjs.map +1 -0
- package/dist/{chunk-A4GK3PLP.js → chunk-F2OEWTK6.js} +5 -5
- package/dist/chunk-F2OEWTK6.js.map +1 -0
- package/dist/chunk-GAWBA53C.js +20 -0
- package/dist/chunk-GAWBA53C.js.map +1 -0
- package/dist/{chunk-UIWTFU3M.cjs → chunk-J4HGCXLB.cjs} +49 -28
- package/dist/chunk-J4HGCXLB.cjs.map +1 -0
- package/dist/chunk-JAVBIVKK.js +27 -0
- package/dist/chunk-JAVBIVKK.js.map +1 -0
- package/dist/{chunk-VDB7VHFS.cjs → chunk-L63PCZNQ.cjs} +75 -60
- package/dist/chunk-L63PCZNQ.cjs.map +1 -0
- package/dist/{chunk-ITSVPZS5.cjs → chunk-LFKF2PMZ.cjs} +53 -29
- package/dist/chunk-LFKF2PMZ.cjs.map +1 -0
- package/dist/chunk-LMCCIFCH.js +15 -0
- package/dist/chunk-LMCCIFCH.js.map +1 -0
- package/dist/{chunk-E2PXYR3H.js → chunk-OT5M3N76.js} +43 -28
- package/dist/chunk-OT5M3N76.js.map +1 -0
- package/dist/{chunk-OWA5Z3WT.cjs → chunk-OWUKAB6M.cjs} +212 -144
- package/dist/chunk-OWUKAB6M.cjs.map +1 -0
- package/dist/{chunk-BML7HQPE.cjs → chunk-P6J3V26J.cjs} +7 -7
- package/dist/{chunk-BML7HQPE.cjs.map → chunk-P6J3V26J.cjs.map} +1 -1
- package/dist/{chunk-C63CBYD5.js → chunk-QERVED37.js} +4 -3
- package/dist/chunk-QERVED37.js.map +1 -0
- package/dist/{chunk-3XZODV7S.cjs → chunk-SB3MKJH2.cjs} +10 -7
- package/dist/chunk-SB3MKJH2.cjs.map +1 -0
- package/dist/{chunk-T33VE5XQ.js → chunk-SVL6SPO6.js} +28 -8
- package/dist/chunk-SVL6SPO6.js.map +1 -0
- package/dist/chunk-SYKWLQJZ.cjs +22 -0
- package/dist/chunk-SYKWLQJZ.cjs.map +1 -0
- package/dist/{chunk-G4OQ4PEO.js → chunk-WDTSKRH5.js} +19 -10
- package/dist/chunk-WDTSKRH5.js.map +1 -0
- package/dist/{chunk-CQZH3L3W.cjs → chunk-XBTAEOKJ.cjs} +51 -40
- package/dist/chunk-XBTAEOKJ.cjs.map +1 -0
- package/dist/{chunk-LAVCNLL3.js → chunk-Y4EE5XF3.js} +33 -9
- package/dist/chunk-Y4EE5XF3.js.map +1 -0
- package/dist/chunk-Y6DTXVKS.cjs +32 -0
- package/dist/chunk-Y6DTXVKS.cjs.map +1 -0
- package/dist/{chunk-GY3KNTNK.js → chunk-Y6UT7WA3.js} +3 -3
- package/dist/{chunk-GY3KNTNK.js.map → chunk-Y6UT7WA3.js.map} +1 -1
- package/dist/{chunk-6VHOMWNF.js → chunk-YMXFBHWZ.js} +8 -5
- package/dist/chunk-YMXFBHWZ.js.map +1 -0
- package/dist/devtools/index.cjs +8 -8
- package/dist/devtools/index.d.cts +2 -2
- package/dist/devtools/index.d.ts +2 -2
- package/dist/devtools/index.js +5 -5
- package/dist/document/index.cjs +4 -3
- package/dist/document/index.d.cts +4 -4
- package/dist/document/index.d.ts +4 -4
- package/dist/document/index.js +2 -1
- package/dist/examples/index.cjs +4 -4
- package/dist/examples/index.d.cts +2 -2
- package/dist/examples/index.d.ts +2 -2
- package/dist/examples/index.js +3 -3
- package/dist/{head-zznJvVEE.d.cts → head-HDTpptl2.d.cts} +2 -2
- package/dist/{head-CVjtToF8.d.ts → head-R4Jx_OVM.d.ts} +2 -2
- package/dist/i18n/index.cjs +13 -13
- package/dist/i18n/index.d.cts +2 -2
- package/dist/i18n/index.d.ts +2 -2
- package/dist/i18n/index.js +3 -3
- package/dist/index.cjs +69 -69
- package/dist/index.d.cts +6 -6
- package/dist/index.d.ts +6 -6
- package/dist/index.js +6 -6
- package/dist/migrations/index.cjs +4 -4
- package/dist/migrations/index.js +2 -2
- package/dist/{palette-CCxWSi3C.d.cts → palette-BTn4IRXK.d.cts} +1 -1
- package/dist/{palette-BZujb2rm.d.ts → palette-BmDclrlr.d.ts} +1 -1
- package/dist/{primitive-props-Cl5jiC8g.d.ts → primitive-props-BI8aHvma.d.cts} +1 -0
- package/dist/{primitive-props-Cl5jiC8g.d.cts → primitive-props-BI8aHvma.d.ts} +1 -0
- package/dist/reflect/index.cjs +23 -23
- package/dist/reflect/index.d.cts +2 -2
- package/dist/reflect/index.d.ts +2 -2
- package/dist/reflect/index.js +5 -5
- package/dist/{types-CJC8mnzl.d.ts → types-B5-GtEik.d.ts} +2 -0
- package/dist/{types-DOm2MKDk.d.ts → types-BEbjstbo.d.ts} +2 -1
- package/dist/{types-DzB3TAQj.d.cts → types-BLESXdu0.d.cts} +1 -1
- package/dist/{types-CWOom_fv.d.cts → types-C8OoE1EM.d.cts} +2 -1
- package/dist/{types-pbBIUNxw.d.ts → types-CbKiEDDH.d.ts} +1 -1
- package/dist/{types-D0x56Ya-.d.cts → types-CmIg-D2q.d.cts} +1 -1
- package/dist/{types-LXw2RJfH.d.ts → types-Lld1eifz.d.ts} +1 -1
- package/dist/{types-CR56luN7.d.cts → types-Wze4IlEM.d.cts} +2 -0
- package/package.json +7 -7
- package/dist/chunk-3XZODV7S.cjs.map +0 -1
- package/dist/chunk-57PZEPIK.js.map +0 -1
- package/dist/chunk-5T26T2EJ.cjs.map +0 -1
- package/dist/chunk-6VHOMWNF.js.map +0 -1
- package/dist/chunk-A4GK3PLP.js.map +0 -1
- package/dist/chunk-C63CBYD5.js.map +0 -1
- package/dist/chunk-CQZH3L3W.cjs.map +0 -1
- package/dist/chunk-E2PXYR3H.js.map +0 -1
- package/dist/chunk-G4OQ4PEO.js.map +0 -1
- package/dist/chunk-GQVJ5UAS.js +0 -8
- package/dist/chunk-GQVJ5UAS.js.map +0 -1
- package/dist/chunk-ITGR7P2B.cjs +0 -12
- package/dist/chunk-ITGR7P2B.cjs.map +0 -1
- package/dist/chunk-ITSVPZS5.cjs.map +0 -1
- package/dist/chunk-LAVCNLL3.js.map +0 -1
- package/dist/chunk-M2ZZUSH3.js.map +0 -1
- package/dist/chunk-OWA5Z3WT.cjs.map +0 -1
- package/dist/chunk-OY7SCFTJ.js.map +0 -1
- package/dist/chunk-QTJ4ZQRM.cjs.map +0 -1
- package/dist/chunk-RVU6YEHO.cjs.map +0 -1
- package/dist/chunk-T33VE5XQ.js.map +0 -1
- package/dist/chunk-UIWTFU3M.cjs.map +0 -1
- package/dist/chunk-VDB7VHFS.cjs.map +0 -1
- package/dist/chunk-ZR54IVVS.cjs.map +0 -1
package/ACTION_DOCS.md
CHANGED
|
@@ -194,7 +194,9 @@ Remove an element at a specific index.
|
|
|
194
194
|
{ removeAt: 'items', index: 2 } // remove third
|
|
195
195
|
```
|
|
196
196
|
|
|
197
|
-
The index can also be a template string (e.g. `"{{@event.payload}}"`) resolved before applying.
|
|
197
|
+
The index can also be a template string (e.g. `"{{@event.payload}}"`) resolved before applying. One that does not resolve to a whole number (a missing path, a fraction, a word) leaves the array as it is, and the steps after it run.
|
|
198
|
+
|
|
199
|
+
A negative index counts from the end, as in JavaScript's `splice`: `-1` removes the last element, and an index further back than the first element removes the first. An index computed as `-1` for "not found" therefore removes the last element: check the index before the step runs. An `index` template that resolves to a negative number is reported to `onError` (a `NovaError` with code `MUTATION_ERROR` naming the template) and then applied; a literal negative `index` is not reported. An index past the end removes nothing.
|
|
198
200
|
|
|
199
201
|
### `move`
|
|
200
202
|
|
|
@@ -205,7 +207,7 @@ Reorder an array element from one index to another.
|
|
|
205
207
|
{ move: 'items', from: '{{@event.payload}}', to: 0 }
|
|
206
208
|
```
|
|
207
209
|
|
|
208
|
-
`from` / `to` accept a number or a template string resolved before applying. An out-of-range `from` is a no-op; `to` is clamped into range.
|
|
210
|
+
`from` / `to` accept a number or a template string resolved before applying. An out-of-range `from` is a no-op; `to` is clamped into range. A template that does not resolve to a whole number leaves the array as it is.
|
|
209
211
|
|
|
210
212
|
### `clear`
|
|
211
213
|
|
|
@@ -250,7 +252,7 @@ Invoke a named endpoint. Optional `onSuccess` and `onError` step branches run af
|
|
|
250
252
|
}
|
|
251
253
|
```
|
|
252
254
|
|
|
253
|
-
The response is written to the endpoint's `target` before `onSuccess` runs; there is no implicit per-call response slot. If a newer call to the same endpoint has already landed, an older response arriving late does not overwrite `target` (its `onSuccess` still runs).
|
|
255
|
+
The response is written to the endpoint's `target` before `onSuccess` runs; there is no implicit per-call response slot. If a newer call to the same endpoint has already landed, an older response arriving late does not overwrite `target` (its `onSuccess` still runs), and an older failure arriving late does not overwrite `errorTarget` (its `onError` steps still run). A failure that comes back while a newer call is still on its way is written, as before.
|
|
254
256
|
|
|
255
257
|
The `onError` branch has access to a special **`@error`** scope inside templates: `{{@error.message}}`, `{{@error.status}}`, `{{@error.data}}`. Use it to surface error messages in the UI.
|
|
256
258
|
|
|
@@ -287,6 +289,8 @@ The `pop` effect uses `pop: true` (a literal boolean) to distinguish it from the
|
|
|
287
289
|
|
|
288
290
|
`push`, `replace`, and `resetTo` accept an optional `with: [...]` — ids of `ActionFragment`s composed into the action before it is instantiated. Each fragment wraps the action (the action's layout fills the fragment's `{ slot: 'body' }`) and contributes its triggers/data; the action wins on conflict.
|
|
289
291
|
|
|
292
|
+
A `push` (the effect or `shell.push`) to a canvas id the shell was not given creates that canvas. It is not in the shell layout: only a `CanvasSlot` naming it, or `getCanvasRenderTree`, shows it. Declare a canvas with `canvases` or `addCanvas`.
|
|
293
|
+
|
|
290
294
|
`input` values resolve against the current data plus the firing event, so a trigger can pass dynamic data to the action it opens — e.g. `input: { record: '@event.payload' }` or `input: { id: '@event.payload.todo_id' }`. `action` resolves the same way (`action: '{{@event.payload}}'` opens the action a binding names); a literal id passes through unchanged.
|
|
291
295
|
|
|
292
296
|
### `popTo`, `resetTo`
|
|
@@ -361,7 +365,6 @@ endpoints: {
|
|
|
361
365
|
method: 'POST',
|
|
362
366
|
headers: {
|
|
363
367
|
'content-type': 'application/json',
|
|
364
|
-
'authorization': 'Bearer {{$.token}}',
|
|
365
368
|
},
|
|
366
369
|
request: { name: { $ref: '$.user.name' }, email: { $ref: '$.user.email' } },
|
|
367
370
|
target: 'savedUser',
|
|
@@ -375,7 +378,7 @@ endpoints: {
|
|
|
375
378
|
- **`url`** *(required)* — template URL. Bindings work.
|
|
376
379
|
- **`method`** *(required)* — `GET` | `POST` | `PUT` | `PATCH` | `DELETE`.
|
|
377
380
|
- **`headers`** *(optional)* — object of header name → value. Values can be templated; names cannot.
|
|
378
|
-
- **`request`** *(optional)* — a transform config run by the **injected evaluator** (see below) over the action data to build the request body. Static parts are literal; dynamic parts use the evaluator's ops. A string result is sent as-is; anything else is JSON-stringified. Declaring `request` without an injected transform is a hard error — never a silent empty body.
|
|
381
|
+
- **`request`** *(optional)* — a transform config run by the **injected evaluator** (see below) over the action data to build the request body. Static parts are literal; dynamic parts use the evaluator's ops. A string result is sent as-is; anything else is JSON-stringified. Declaring `request` without an injected transform is a hard error — never a silent empty body. Not on a `GET`: fetch sends no body with a GET, so every call of it fails; the shell reports such an endpoint to `onError` as a `DefinitionValidationError` when `createShell` or `registerAction` loads the definition, and loads it as given.
|
|
379
382
|
- **`response`** *(optional)* — a transform config run by the injected evaluator over the reply **exactly as received** (`$` is the reply — object, array, or scalar; no wrapping) to produce the value stored at `target`. Declaring it without an injected transform is a hard error — never the unshaped reply.
|
|
380
383
|
- **`target`** *(optional)* — data path to write the (possibly transformed) response into on success. If unset, the response is discarded.
|
|
381
384
|
- **`errorTarget`** *(optional)* — data path to write the error info into on failure.
|
|
@@ -442,8 +445,8 @@ lifecycle: {
|
|
|
442
445
|
|
|
443
446
|
### When each fires
|
|
444
447
|
|
|
445
|
-
- **`mount`** — when the action is pushed onto a canvas (after `data` and `input` are merged and
|
|
446
|
-
- **`suspend`** — when another action is pushed on top on a `stack` canvas, this action transitions from `active` → `suspended
|
|
448
|
+
- **`mount`** — when the action is pushed onto a canvas (after `data` and `input` are merged, triggers attach and the instance is on its canvas, so a `push`, `pop` or `removeSelf` step in it acts from this instance; the instance is `initializing` until the hook completes), and **again on every resume**, before the `resume` hook. A suspended action ignores everything while backgrounded, so re-running `mount` is what brings its data current when it is revealed again. A `{ reload: true }` step re-runs it too.
|
|
449
|
+
- **`suspend`** — when another action is pushed on top on a `stack` canvas, this action transitions from `active` → `suspended` once the hook has run. Triggers stay attached but do not fire while suspended. A `mode: 'list'` canvas suspends nothing. If the action is revealed (or removed) before its `suspend` hook finishes, it stays `active` (or `unmounted`).
|
|
447
450
|
- **`resume`** — when the action above is popped, this action transitions from `suspended` → `active`. Runs after the re-run of `mount`.
|
|
448
451
|
- **`unmount`** — once, when the action is popped from the canvas (or the shell is disposed). In-flight steps are aborted and triggers detach BEFORE the unmount steps run; the unmount steps run on a fresh signal, so they can do their own async work.
|
|
449
452
|
|
|
@@ -472,7 +475,7 @@ const modalFrame: ActionFragment = {
|
|
|
472
475
|
|
|
473
476
|
Fields: `kind`, `id`, and optional `name`, `description`, `layout`, `data`, `triggers`, `endpoints`, `lifecycle` — the same shapes as on an action. A fragment has no `title` or `input`.
|
|
474
477
|
|
|
475
|
-
On merge (`composeAction(action, fragments)`): each fragment's layout wraps the layout so far, filling its `{ slot: 'body' }` — the last fragment listed is the outermost; a fragment whose `layout` is a
|
|
478
|
+
On merge (`composeAction(action, fragments)`): each fragment's layout wraps the layout so far, filling its `{ slot: 'body' }` with it — the last fragment listed is the outermost, and a layout so far that is a layout id fills the slot with a `{ ref }` to it, so the slot renders the stored layout; a fragment whose `layout` is a layout id replaces the layout instead of wrapping it. `data` and `endpoints` merge with the action winning on a clash (`data` is a shallow merge). Triggers concatenate, fragment first. Lifecycle steps concatenate per hook, fragment first. An unknown fragment id throws `UnknownFragmentError`.
|
|
476
479
|
|
|
477
480
|
---
|
|
478
481
|
|
|
@@ -511,7 +514,7 @@ onError: [
|
|
|
511
514
|
Fields available on `@error`:
|
|
512
515
|
- `message: string`
|
|
513
516
|
- `status: number` (HTTP status, or 0 for network/function errors)
|
|
514
|
-
- `data: unknown` (the response body if any)
|
|
517
|
+
- `data: unknown` (the response body if any: parsed JSON, or the text of a body that is not JSON when the response offers `clone()`, as a real `Response` does; without `clone`, or when the host already read the body, a non-JSON body leaves `data` empty)
|
|
515
518
|
- `timedOut?: boolean` (true if no reply arrived within the endpoint's wait)
|
|
516
519
|
|
|
517
520
|
A call aborted by an unmount is silent: `onError` does not run, `errorTarget` is not written, and nothing is reported to telemetry.
|
|
@@ -553,10 +556,14 @@ Action-time errors all extend `NovaError`:
|
|
|
553
556
|
- **`UnknownFragmentError`** — a `with: [...]` names a fragment the shell doesn't have
|
|
554
557
|
- **`UnknownFunctionError`** — a `call` to a function endpoint whose `fn` isn't registered, with no `onError` branch, in strict mode
|
|
555
558
|
- **`DefinitionValidationError`** — an action definition fails Zod validation at shell init
|
|
556
|
-
- **`MutationError`** — in strict mode, `push`, `pop`, `removeAt`, `move` or `clear` aimed at a path that is missing or of the wrong type. It is reported to `onError`, and the batch of mutations it was in is not applied. In lax mode the op is a no-op
|
|
559
|
+
- **`MutationError`** — in strict mode, `push`, `pop`, `removeAt`, `move` or `clear` aimed at a path that is missing or of the wrong type. It is reported to `onError`, and the batch of mutations it was in is not applied. In lax mode the op is a no-op, except `clear`, which removes the key (see `clear` above)
|
|
557
560
|
|
|
558
561
|
A runaway trigger chain is reported as a plain `NovaError` with code `RUNAWAY_CHAIN`.
|
|
559
562
|
|
|
563
|
+
In strict mode, a `call` outside a lifecycle hook that fails with no `onError` steps and no `errorTarget` to take it, or that names an endpoint the action does not have with no `onError` steps, is reported to `onError` as a plain `NovaError` with code `ENDPOINT_FAILED` (`endpoint 'save' failed: disk full`, `unknown endpoint: svae`). Nothing is thrown. In lax mode such a call stays silent.
|
|
564
|
+
|
|
565
|
+
In strict mode, a subscriber that throws (a runtime's `onDataChange` or `onStatusChange` handler, a shell's state, data or endpoint listener, a handler on a bus the shell created) is reported to `onError` as a plain `NovaError` with code `HANDLER_FAILED` and the thrown message. It is still caught: the other handlers run.
|
|
566
|
+
|
|
560
567
|
`DefinitionValidationError` always throws, from `createShell` / `registerAction`. `UnknownActionError` and `UnknownFragmentError` always throw from a direct `shell.push` / `shell.replace`; raised by a navigation step inside a trigger they route to `onError`. Lifecycle failures route to `onError`, and in strict mode also surface on the next shell call.
|
|
561
568
|
|
|
562
569
|
---
|
package/ADAPTER.md
CHANGED
|
@@ -110,7 +110,10 @@ Register two structural components under the core names `CANVAS_SLOT_NAME`
|
|
|
110
110
|
and `ACTION_SLOT_NAME` — the shell's default layouts reference them:
|
|
111
111
|
|
|
112
112
|
- **CanvasSlot** (`{ canvasId }`): renders that canvas's tree; nothing when
|
|
113
|
-
`canvasId` is missing.
|
|
113
|
+
`canvasId` is missing. A `CanvasSlot` inside the canvas it names would draw
|
|
114
|
+
that canvas forever: carry the canvases open on the way down, and draw an
|
|
115
|
+
error node there instead (`RENDER_ERROR: canvas "<id>" is placed inside
|
|
116
|
+
itself`), as nova's adapters do.
|
|
114
117
|
- **ActionSlot** (`{ instanceId }`): renders that instance's tree; nothing
|
|
115
118
|
when `instanceId` is missing. Wrap the dispatch handed to the instance's
|
|
116
119
|
subtree with core's `scopeDispatch(dispatch, instanceId)` so its UI events
|
|
@@ -180,6 +183,21 @@ or bound inputs drop keystrokes the moment the shell is remote:
|
|
|
180
183
|
value on blur. The React, Vue, DOM and Ink adapters implement it — omitting it silently
|
|
181
184
|
makes a served `debounce` a no-op in your terminal, so the same layout behaves
|
|
182
185
|
differently across renderers.
|
|
186
|
+
- **Honour `replaceDraftOnWrite` on a `model`-bound node.** With
|
|
187
|
+
`props.replaceDraftOnWrite === true`, a focused field still ignores a new
|
|
188
|
+
tree value equal to one it dispatched since it was focused (its echo), but
|
|
189
|
+
any other change of the tree value replaces the in-progress value, drops a
|
|
190
|
+
pending debounced dispatch (which would write the old text back), and puts
|
|
191
|
+
the caret at the end. Keep the values the field dispatched; empty the list
|
|
192
|
+
when the field is focused, when a tree value equals the last of them, and
|
|
193
|
+
when a value replaces the draft. Only a change of the tree value counts: a
|
|
194
|
+
write that leaves the stored value as it was reaches no adapter. So without
|
|
195
|
+
`debounce` (each keystroke already stored) a `set` of the model path to
|
|
196
|
+
`""` clears the field, but with `debounce`, while the typing still waits and
|
|
197
|
+
the stored value is still `""`, the same `set` does nothing, and leaving the
|
|
198
|
+
field then dispatches the typing. Without the prop, the first obligation
|
|
199
|
+
stands as written. The React, Vue, DOM and Ink adapters implement it; the
|
|
200
|
+
React, Vue and DOM ones are tested, Ink's is not.
|
|
183
201
|
|
|
184
202
|
These belong to *every* adapter because they are artifacts of the transport, not
|
|
185
203
|
of taste — unlike styling, hover, or animation, which *should* differ per kit.
|
|
@@ -305,7 +323,9 @@ close it; nothing has needed one yet.
|
|
|
305
323
|
element's, and stay with it. Once it is left, the next render shows the tree's
|
|
306
324
|
value again (the kit is asked for the field afresh, because how a value is
|
|
307
325
|
shown is the kit's business). A checkbox or a radio is not "typed in": the
|
|
308
|
-
tree's answer shows at once.
|
|
326
|
+
tree's answer shows at once. A field with `replaceDraftOnWrite` takes a
|
|
327
|
+
value that is not an echo of what it dispatched into the same element while
|
|
328
|
+
it is typed in, with the caret at the end.
|
|
309
329
|
- **A field that had to be built again while focused** (another of its props
|
|
310
330
|
changed) is given what was being typed, the caret, and focus.
|
|
311
331
|
- **Focus follows the element.** One that stayed has it still. One that was
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,121 @@
|
|
|
1
1
|
# @niscorp/nova
|
|
2
2
|
|
|
3
|
+
## 0.6.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 4b7d4a4: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on text such as `'$CAD only'` rendering empty, on such text not reaching `onPhraseMiss`, or wrote a condition that way: `{ if: '$count > 0', then, else }` (or a `$if: '$count > 0'` directive) with `count: 0` took `else` and now takes `then`, because the string is text, which is truthy.
|
|
8
|
+
|
|
9
|
+
A string that starts with `$` and a name followed by more words (`'$CAD only'`) is text: it renders as written, where it rendered empty, and, being text, is offered to the phrasebook (`onPhraseMiss` hears of it). Every path that resolved still resolves: `'$.x'` forms, `'$'` alone (the innermost scope), `'$USD'` (a path, empty when there is no `USD`), non-ASCII keys (`'$item.größe'`) and a path with trailing space. Only a data key with a space in it, read the `$name` way, is read differently.
|
|
10
|
+
|
|
11
|
+
- bf72478: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on `errorTarget.data` (or `@error.data`) being missing for a failed HTTP reply whose body is plain text. The message is unchanged. `FetchResponse` gains an optional `clone`.
|
|
12
|
+
|
|
13
|
+
A failed HTTP reply whose body is not JSON (`new Response('Service down for maintenance', { status: 503 })`) puts that text in `errorTarget.data` and `@error.data`, where `data` was missing: nova takes a copy of the response with `clone()` before reading it as JSON. A response without `clone` (a test fake), or one whose body the host already read, is read as before.
|
|
14
|
+
|
|
15
|
+
- e1db181: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on a fragment's slot showing the stored-layout id of the action it wraps as text.
|
|
16
|
+
|
|
17
|
+
A fragment around an action whose `layout` is a stored-layout id (`layout: 'invoice-body'`) renders the stored layout in its `{ slot: 'body' }`, where it rendered the id as text: `composeAction` fills the slot with `{ ref: 'invoice-body' }`, which the renderer resolves from the layout store. A fragment whose own layout is an id still replaces the layout composed so far. The fragment `layout` description says so.
|
|
18
|
+
|
|
19
|
+
- 241bd4d: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app builds a component list from the DOM or TTY kit's `registry.list()` and expects it without `CanvasSlot`.
|
|
20
|
+
|
|
21
|
+
The DOM and TTY kits' `defaultRegistry()` register `CanvasSlot`, so either kit works as the shell's registry, as the README shows: the default shell layout draws instead of `COMPONENT_NOT_FOUND: CanvasSlot`. Their walkers still draw a `CanvasSlot` themselves; the entry is there so the renderer accepts the name, as in the React and Vue kits. `registry.list()` of these two kits names one more component.
|
|
22
|
+
|
|
23
|
+
- 9f8e4b5: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on a late failure of an older call overwriting `errorTarget` after a newer call of the same endpoint already came back.
|
|
24
|
+
|
|
25
|
+
A failed call whose newer call of the same endpoint has already come back no longer writes `errorTarget`, the same rule a late success already follows for `target`. Search "a" (slow, fails), then "ab" (fast, succeeds): the rows show "ab" and the error stays empty, where the late failure wrote it. The call's `onError` steps still run. A failure that comes back while the newer call is still on its way is written, as before.
|
|
26
|
+
|
|
27
|
+
- 1b615d6: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a layout inside a loop writes through `model: '$.<as>.…'`, `'$.items'` or `'$.index'` and relied on the write landing on a root key of that name.
|
|
28
|
+
|
|
29
|
+
Inside a loop, a `model` written with `$.` writes where it reads: `model: '$.line.qty'` (with `as: 'line'`) writes the row it shows (`lines.0.qty`), where it wrote a root `line.qty` that no field shows. `model: '$.index'` binds nothing, as `model: '$index'` already did, where it wrote a root `index` while showing the loop index. A nested loop over `$.<as>.…` (`for: '$.g.items'` inside `for: '$.groups', as: 'g'`) binds its models into each group (`groups.1.items.0.v`), where every group bound `g.items.0.v`. What every layout shows is unchanged.
|
|
30
|
+
|
|
31
|
+
- e7edd95: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app reads `model.ref` from the render tree of a model-bound field that has its own `ref` inside a loop, and expects it to equal that `ref`; dispatching `ui:model` with the render tree's `model.ref`, as every kit does, keeps working.
|
|
32
|
+
|
|
33
|
+
A model-bound field with a `ref` inside a loop (`for: '$.lines', as: 'line', do: { component: 'Input', ref: 'qty', model: '$line.qty' }`) writes what is typed into its own row, where every row wrote the last one. Its render node's `model.ref` is `qty@lines.0.qty` (one per row, the same however many rows there are); its `ref` stays `qty`. Triggers on `ref: 'qty'` fire for every row and see `@event.ref` as `qty`, and a `ui:model` an app dispatches with `ref: 'qty'` still writes the last row. The longer name shows wherever a model ref is shown: adapters, devtools, the TTY command list, and the render trees moss sends to terminals.
|
|
34
|
+
|
|
35
|
+
- 0a46ff6: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on a mount hook's navigation acting from the instance below, on `getState`/`getCanvasState` leaving out an instance whose mount hook is running (a data-change listener that looks the instance up now finds it for the input written at mount), or on the first state snapshot after a push leaving it out.
|
|
36
|
+
|
|
37
|
+
A pushed (or replacing) instance is on its canvas, with its birth, origin and key recorded, before its `mount` hook starts. A `push`, `pop` or `removeSelf` step that runs at the start of a mount hook now acts from that instance: `push` lands above it, `removeSelf` and `pop` close it. A mount hook that pushes onto another canvas fires a first state snapshot that already shows the new instance on its own canvas.
|
|
38
|
+
|
|
39
|
+
A `suspend` whose hook finishes after the action was revealed again (a push and a pop before the suspend ended) or removed no longer sets `suspended`: the action on top stays `active` and its triggers fire.
|
|
40
|
+
|
|
41
|
+
- 59f314a: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app computes a negative `removeAt` index on purpose and does not want `onError` called for it; the data changes exactly as before.
|
|
42
|
+
|
|
43
|
+
A `removeAt` step whose `index` is a template that resolves to a negative number (`index: '{{$.found}}'` with `found = -1`, a search's "not found") is reported to `onError` as a `NovaError` with code `MUTATION_ERROR` (`removeAt: index {{$.found}} resolved to -1, …`), in strict and lax mode, and then applied as before: `-1` still removes the last element. A literal negative `index` is a deliberate "from the end" and is not reported.
|
|
44
|
+
|
|
45
|
+
The report never changes what runs: an `onError` that throws for it does not stop the step, the push or the next handler.
|
|
46
|
+
|
|
47
|
+
- 281108e: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app reads `constructor`, `toString`, `__proto__` or another name every object inherits through a binding (`{{$.x.constructor}}`), which now gives `undefined`.
|
|
48
|
+
|
|
49
|
+
One rule for names a record inherits: what it inherits from a prototype of its own counts, what every object inherits from `Object.prototype` does not. A `functions`, `endpoints`, phrasebook or reconcilers object made with `Object.create(base)` or as a class instance resolves the names it inherits, as in the last release. A data path no longer reads `Object.prototype`'s members: `$.x.constructor` is `undefined` where it rendered `function Object() { [native code] }`. A getter on a class the data carries still reads, and an endpoint with `fn: 'toString'` still fails as an unknown function.
|
|
50
|
+
|
|
51
|
+
- 7aef6a7: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app hands `NovaShell` or `NovaCanvas` a registry with no `CanvasSlot` and relied on React's `Text`, `Stack`, `Input`, `Button`, `Box`, `Panel`, `JsonTree` or `ActionSlot` replacing its own.
|
|
52
|
+
|
|
53
|
+
`NovaShell` and `NovaCanvas`, handed a registry with no `CanvasSlot`, add only the default React components the registry does not have, and replace none it has. The Ink kit's registry keeps Ink's `Text` and gets `CanvasSlot`. A registry that has `CanvasSlot` is untouched, as before.
|
|
54
|
+
|
|
55
|
+
- 79cf65c: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on a field with `model: '{{…}}'`, or inside a loop with `for: '{{…}}'`, writing nothing when typed into.
|
|
56
|
+
|
|
57
|
+
A `model` written as a single template (`model: '{{$.q}}'`) binds like the bare path, and a loop whose `for` is a single template (`for: '{{$.lines}}'`) keeps the bindings of the `model`s inside it: such fields write what is typed, and their render nodes carry `model` and `value`, where they bound nothing.
|
|
58
|
+
|
|
59
|
+
- e828562: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app runs its shell with `strict: true` and does not want `onError` called for failed calls nothing takes. Lax shells (the default) are unchanged. The exported `ErrorCode` type gains `'ENDPOINT_FAILED'`.
|
|
60
|
+
|
|
61
|
+
In strict mode, a `call` outside a lifecycle hook that fails with no `onError` steps and no `errorTarget`, or names an endpoint the action does not have with no `onError` steps, is reported to the shell's `onError` as a `NovaError` with the new code `ENDPOINT_FAILED` (`ErrorCodes.endpointFailed`). Nothing is thrown that was not thrown before; an unknown function still raises `UnknownFunctionError` in strict mode, and a lifecycle hook still raises `LifecycleError`.
|
|
62
|
+
|
|
63
|
+
The report never changes what runs: an `onError` that throws for it does not stop the step, the push or the next handler.
|
|
64
|
+
|
|
65
|
+
- 6b01a50: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app runs its shell with `strict: true` and does not want `onError` called for subscribers that throw. Lax shells (the default) and buses an app hands in are unchanged. The exported `ErrorCode` type gains `'HANDLER_FAILED'`.
|
|
66
|
+
|
|
67
|
+
In a strict shell, a subscriber that throws is reported to the shell's `onError` as a `NovaError` with the new code `HANDLER_FAILED` (`ErrorCodes.handlerFailed`) and the thrown message: `onStateChange`, `onDataChange` and `onEndpoint` listeners, handlers on the event and message bus the shell created itself, and each runtime's data and status subscribers. The throw is still caught, and the other handlers and the push or write that fired them go on.
|
|
68
|
+
|
|
69
|
+
The report never changes what runs: an `onError` that throws for it does not stop the step, the push or the next handler.
|
|
70
|
+
|
|
71
|
+
- 6eef458: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app's translations contain `$$`, `$&`, `` $` ``, `$'` or `$1` and relied on them being read as replacement patterns on text with spaces around it.
|
|
72
|
+
|
|
73
|
+
A translation applied to text with spaces around it goes in as written: "Price in dollars " with the translation "Preis in US$$" renders "Preis in US$$ ", where it rendered "Preis in US$ ". The same translation already rendered as written on text without spaces.
|
|
74
|
+
|
|
75
|
+
### Patch Changes
|
|
76
|
+
|
|
77
|
+
- b233463: `LayoutStore.resolveReferences` on a stored layout that refers to itself returns, leaving the inner `{ ref }` for the renderer, instead of overflowing the stack.
|
|
78
|
+
|
|
79
|
+
A canvas placed inside itself (a `CanvasSlot` naming the canvas it sits in) draws `RENDER_ERROR: canvas "<id>" is placed inside itself` where it comes back, in the TTY, DOM, React and Vue adapters, instead of overflowing the stack or running out of memory.
|
|
80
|
+
|
|
81
|
+
A `GET` endpoint with a `request` body, which fetch refuses on every call, is reported to `onError` as a `DefinitionValidationError` by `createShell` and `registerAction`; the definition still loads as before.
|
|
82
|
+
|
|
83
|
+
A bound `Input` takes `replaceDraftOnWrite: true`: while it is focused, a change of the value at its model path, other than an echo of a value it dispatched since it was focused, replaces what is typed and drops a pending debounced dispatch, in the DOM, React, Vue and Ink adapters (Ink's is not covered by a test). A write that leaves the stored value as it was changes nothing. Without the prop, a focused field keeps what is typed, as before.
|
|
84
|
+
|
|
85
|
+
Docs say what the code does: the event bus does not validate events; in lax mode `clear` on a missing or wrong-typed path removes the key; a negative `removeAt` index counts from the end; a push to an undeclared canvas creates a canvas the shell layout does not show; `removeAction` on a list canvas re-runs the mount and resume hooks of the card left last; inside a loop `$.index`, `$.items` and `$.<as>` read the loop's values, a lone `$` is the innermost scope, and `'$USD'` is a path. The endpoint example no longer sends a bearer token from action data.
|
|
86
|
+
|
|
87
|
+
- e2b9595: A name every object inherits (`toString`, `constructor`, `valueOf`) is no longer found as an action, fragment, endpoint, function, phrase, slot or directive; a removeAt or move index template that is no whole number leaves the array alone and the next steps run; a stored layout that comes back to itself renders a clear `RenderError` instead of overflowing the stack. An actions or fragments map keyed by something other than the id is now reported to `onError` (the shell still loads it), and the README lists what each adapter kit ships.
|
|
88
|
+
- Updated dependencies [48138de]
|
|
89
|
+
- Updated dependencies [da3037e]
|
|
90
|
+
- Updated dependencies [e957628]
|
|
91
|
+
- Updated dependencies [c30562a]
|
|
92
|
+
- Updated dependencies [efd2368]
|
|
93
|
+
- Updated dependencies [ca26810]
|
|
94
|
+
- Updated dependencies [800a541]
|
|
95
|
+
- Updated dependencies [9c5367b]
|
|
96
|
+
- Updated dependencies [322f241]
|
|
97
|
+
- Updated dependencies [a41edf9]
|
|
98
|
+
- Updated dependencies [eb4ffb9]
|
|
99
|
+
- Updated dependencies [ae647e8]
|
|
100
|
+
- Updated dependencies [2effb54]
|
|
101
|
+
- Updated dependencies [bd996ea]
|
|
102
|
+
- Updated dependencies [180787b]
|
|
103
|
+
- Updated dependencies [d53910e]
|
|
104
|
+
- Updated dependencies [276f457]
|
|
105
|
+
- Updated dependencies [413afbd]
|
|
106
|
+
- Updated dependencies [1f6d37d]
|
|
107
|
+
- Updated dependencies [d77baf9]
|
|
108
|
+
- Updated dependencies [3f92c52]
|
|
109
|
+
- Updated dependencies [841c010]
|
|
110
|
+
- Updated dependencies [d93170b]
|
|
111
|
+
- Updated dependencies [61b15e4]
|
|
112
|
+
- Updated dependencies [7e8f6d4]
|
|
113
|
+
- Updated dependencies [5c52ef5]
|
|
114
|
+
- Updated dependencies [66eb934]
|
|
115
|
+
- @niscorp/cortex@0.2.0
|
|
116
|
+
- @niscorp/prism@0.4.0
|
|
117
|
+
- @niscorp/strata@0.2.0
|
|
118
|
+
|
|
3
119
|
## 0.5.2
|
|
4
120
|
|
|
5
121
|
### Patch Changes
|
package/DESIGN.md
CHANGED
|
@@ -104,16 +104,18 @@ Resolution rules:
|
|
|
104
104
|
- **String, sole `{{ expr }}`** → returns the raw resolved value (preserves
|
|
105
105
|
type — number stays number, object stays object).
|
|
106
106
|
- **String, `"text {{expr}} text"`** → string interpolation.
|
|
107
|
-
- **String, bare `"$.path"` or `"$item.field"`** → raw resolved value.
|
|
107
|
+
- **String, bare `"$.path"` or `"$item.field"`** → raw resolved value. A
|
|
108
|
+
`$` name followed by more words (`"$CAD only"`) is text.
|
|
109
|
+
- **String, bare `@event…` / `@error…`** → raw resolved value, where that scope
|
|
110
|
+
is present (a trigger's steps, an `onError` list).
|
|
108
111
|
- **String, anything else** → returned literally.
|
|
109
|
-
- **Object `{ $if, $then, $else }
|
|
110
|
-
`$else`
|
|
112
|
+
- **Object with a directive key** → the directive: `{ $if, $then, $else }` is a
|
|
113
|
+
conditional (`$else` optional), `{ $eq: [a, b] }` strict equality,
|
|
114
|
+
`{ $exists: x }` whether `x` resolves to anything but undefined (null
|
|
115
|
+
counts), `{ $at: [array, index, field?] }` an element or one field of it,
|
|
116
|
+
`{ $prism: node }` a Prism node evaluated against the innermost scope.
|
|
111
117
|
- **Array** → walked recursively.
|
|
112
|
-
- **
|
|
113
|
-
|
|
114
|
-
The previous `BindingSchema` value-form objects (`{ template: ... }`,
|
|
115
|
-
`{ if, then, else }`) **no longer exist**. The unified resolver replaced
|
|
116
|
-
them.
|
|
118
|
+
- **Any other object** → walked recursively.
|
|
117
119
|
|
|
118
120
|
Scope chains are arrays of records, innermost first. `createScopeChain(data)`
|
|
119
121
|
returns `[data]`. Loops push a new scope on the front (`{ [as]: item }`).
|
|
@@ -128,8 +130,10 @@ runtime writes to it, the layout renderer reads from it via a narrow
|
|
|
128
130
|
|
|
129
131
|
### `shared/event-bus/`
|
|
130
132
|
|
|
131
|
-
Topic-based pub/sub.
|
|
132
|
-
|
|
133
|
+
Topic-based pub/sub. It does not validate events: a host that takes events
|
|
134
|
+
from outside parses them with `NovaEventSchema` before it emits them (moss
|
|
135
|
+
does, where a terminal's events arrive). Used for ambient UI events such as
|
|
136
|
+
`ui:model`. Handlers receive
|
|
133
137
|
typed `NovaEvent` payloads. Subscriptions return cleanup functions.
|
|
134
138
|
|
|
135
139
|
### `shared/message-bus/`
|
|
@@ -141,6 +145,14 @@ Trigger configs with a `message` field bind to this bus.
|
|
|
141
145
|
The two buses are **independent**. The previous `msg:<channel>` prefix
|
|
142
146
|
bridge through the event bus is gone.
|
|
143
147
|
|
|
148
|
+
A handler that throws never breaks a bus or a store: the event bus, the
|
|
149
|
+
message bus and the data store catch it and go on to the next handler.
|
|
150
|
+
`createEventBus`, `createMessageBus` and `createDataStore` take an optional
|
|
151
|
+
`{ onHandlerError }` that is handed what was caught. A strict shell wires it
|
|
152
|
+
to its `onError` (code `HANDLER_FAILED`) for the buses it creates itself,
|
|
153
|
+
its telemetry, and each runtime's data store and status subscribers; a bus
|
|
154
|
+
the app hands in is left as it is, and a lax shell reports nothing.
|
|
155
|
+
|
|
144
156
|
### `shared/ids.ts`, `shared/common.ts`
|
|
145
157
|
|
|
146
158
|
`createIdFactory(prefix)` for instance/shell ids; small type guards
|
|
@@ -299,7 +311,10 @@ every response lands as before and none is followed.
|
|
|
299
311
|
|
|
300
312
|
When the layout author writes `model: "$.user.name"` on a component, the
|
|
301
313
|
renderer emits `model: { ref, path: 'user.name' }` on the
|
|
302
|
-
`RenderComponentNode`.
|
|
314
|
+
`RenderComponentNode`. A field with a `ref` bound through a loop name
|
|
315
|
+
gets the per-row model ref `<ref>@<path>`; the runtime maps it to its
|
|
316
|
+
row, maps the written `ref` to the last row as before, and hands
|
|
317
|
+
triggers the event with the written `ref`. After every render, the runtime reconciles its
|
|
303
318
|
`ui:model` event-bus listeners against the live set of model refs:
|
|
304
319
|
|
|
305
320
|
- New ref → install a listener that, on `ui:model` events for that ref,
|
|
@@ -472,8 +487,10 @@ that spawns:
|
|
|
472
487
|
- **layout** — `fillSlots(fragment.layout, { body: action.layout })`: the
|
|
473
488
|
fragment is the outer chrome, the action's own layout is dropped into the
|
|
474
489
|
fragment's `{ slot: 'body' }` node. The fragment wraps; the action is the
|
|
475
|
-
innermost content.
|
|
476
|
-
|
|
490
|
+
innermost content. An action layout that is a layout id goes into the
|
|
491
|
+
slot as `{ ref: id }`, so the renderer draws the stored layout there.
|
|
492
|
+
Multiple fragments fold in array order (last listed is outermost). An
|
|
493
|
+
unfilled slot renders nothing.
|
|
477
494
|
- **data / endpoints** — shallow-merge, **action wins** on conflict.
|
|
478
495
|
- **triggers** — concat, fragment's first (so a fragment's `close`/`cancel`
|
|
479
496
|
and the action's `confirm` coexist; authors keep refs distinct).
|
|
@@ -502,12 +519,14 @@ work (v1 fills one `body` slot with the action's `layout`).
|
|
|
502
519
|
4. `spawn` calls `buildRuntime` → `createActionRuntime`. The runtime
|
|
503
520
|
builds its data store from `definition.data` merged with `input`,
|
|
504
521
|
creates an `AbortController`, registers triggers.
|
|
505
|
-
5. `
|
|
522
|
+
5. `spawn` pushes the new instance onto the canvas and records its
|
|
523
|
+
birth, origin and key, so a mount hook that navigates (`push`,
|
|
524
|
+
`pop`, `removeSelf`) finds its own instance on top.
|
|
525
|
+
6. `runtime.mount(input)` is fired and not awaited. It runs the
|
|
506
526
|
`mount` lifecycle hook via `runLifecycleHook`, then transitions to
|
|
507
527
|
`active`. Failures route through the strict/lax pipeline.
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
7. The adapter (when one exists) calls `runtime.render()` which returns
|
|
528
|
+
7. `fireState()` notifies state subscribers.
|
|
529
|
+
8. The adapter (when one exists) calls `runtime.render()` which returns
|
|
511
530
|
`RenderNode[]`. The runtime reconciles model bindings against the
|
|
512
531
|
produced tree.
|
|
513
532
|
|
package/I18N_DOCS.md
CHANGED
|
@@ -116,14 +116,19 @@ string.
|
|
|
116
116
|
rule, where a query manufactures a word and a read puts it on screen. There the
|
|
117
117
|
key is what protects data.
|
|
118
118
|
|
|
119
|
-
A string is a binding (`isBinding`) when it is `$` alone
|
|
120
|
-
followed by
|
|
121
|
-
|
|
119
|
+
A string is a binding (`isBinding`) when it is `$` alone, starts with `$.`, or
|
|
120
|
+
is `$` followed by a letter or `_` and no space before its end (so `'$CAD only'`
|
|
121
|
+
is a phrase), when it starts with `@` followed by a letter or `_` (an extra
|
|
122
|
+
scope such as `@event.payload.id`), or when it contains `{{`.
|
|
122
123
|
|
|
123
124
|
A phrase (`isPhrase`) is a non-blank string that is not a binding and holds at
|
|
124
125
|
least one letter. Only a phrase is harvested, looked up in the book or reported
|
|
125
126
|
as a miss: `12`, `100%` and `—` never are.
|
|
126
127
|
|
|
128
|
+
A phrase with spaces around it (`'Total '`) is looked up as itself first and
|
|
129
|
+
then trimmed; a translation found for the trimmed text goes in between the same
|
|
130
|
+
spaces, as written: `$$`, `$&` or `$1` in a translation render as they are.
|
|
131
|
+
|
|
127
132
|
## Counted phrases
|
|
128
133
|
|
|
129
134
|
A dictionary can hold "Standing". It can never hold "12 of 20" — two numbers
|
package/LAYOUT_DOCS.md
CHANGED
|
@@ -78,7 +78,7 @@ The most common one. References a component by name; the registry supplies the i
|
|
|
78
78
|
- **`component`** *(required)* — the registry name. Must match a name passed to `registry.register(name, ...)`.
|
|
79
79
|
- **`props`** *(optional)* — an object of props. **Every value is a binding** — strings starting with `$` are resolved as paths, strings with `{{...}}` are interpolated, plain values pass through. See [Bindings](#bindings).
|
|
80
80
|
- **`children`** *(optional)* — a single `LayoutNode` or an array of them. Components decide how to render their children slot.
|
|
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.
|
|
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. Inside a loop, a model-bound field with a `ref` gets the model ref `<ref>@<path>` (`qty@lines.0.qty`), one per row; its `ref` stays as written, and triggers on that ref still fire for every row.
|
|
82
82
|
- **`model`** *(optional)* — two-way binding path. See [Two-way binding](#two-way-binding).
|
|
83
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
84
|
|
|
@@ -219,6 +219,7 @@ store.set('user-card', {
|
|
|
219
219
|
|
|
220
220
|
- The referenced layout sees the **current scope** at the call site. Inside a loop, a `LayoutRef` reads from the loop variable just like an inline layout would.
|
|
221
221
|
- If the ref doesn't resolve, the renderer throws `LayoutRefNotFoundError`. In lax mode it's caught and replaced with an error RenderNode; in strict mode it propagates.
|
|
222
|
+
- A layout may refer to itself further down its data: a `tree` layout that loops over `$node.children` with `{ ref: 'tree' }` inside renders each level with `$node` bound to a child. A ref reached again where every binding reads what it read the last time the ref was entered would render the same thing forever: a layout `x` whose only child is `{ ref: 'x' }`, `x` → `y` → `x`, or `x` looping over `$.items` with `{ ref: 'x' }` inside. The renderer throws a `RenderError` naming the refs, `Layout ref "x" comes back to itself: x → y → x`, handled as any render error.
|
|
222
223
|
|
|
223
224
|
---
|
|
224
225
|
|
|
@@ -271,11 +272,16 @@ A string starting with `$.` reads a value from the data object.
|
|
|
271
272
|
|
|
272
273
|
The raw value is returned with its type preserved — numbers stay numbers, arrays stay arrays.
|
|
273
274
|
|
|
275
|
+
A path reads what a value has, or inherits from a prototype of its own (a getter on a class the data carries, `$.person.fullName`), and never what every object inherits: `$.x.constructor`, `$.x.toString` and `$.x.__proto__` are `undefined`.
|
|
276
|
+
|
|
274
277
|
**Path forms:**
|
|
275
|
-
- `$.foo.bar` — start from the data root, walk `foo` then `bar`
|
|
278
|
+
- `$.foo.bar` — start from the data root, walk `foo` then `bar`. Inside a loop, the loop's own names come first: `$.index`, `$.items` and `$.<as>` read the loop's values, not root keys of those names
|
|
276
279
|
- `$foo` — read variable `foo` from the closest enclosing scope (loop variable, etc.)
|
|
277
280
|
- `$foo.bar` — read variable `foo`, walk `bar` on it
|
|
278
281
|
- `$index` — special: the loop iteration index
|
|
282
|
+
- `$` alone — the whole innermost scope: the data root, or inside a loop the loop's own `{ <as>, index, items }`
|
|
283
|
+
|
|
284
|
+
A string that starts with `$` and then a letter or `_`, with no space before its end, is a path, never text: `'$USD'` reads a key `USD` and renders empty when there is none. When more words follow the name, it is text: `'$CAD only'` renders as written (and is offered to the phrasebook like other text). As a condition such text is truthy: `if: '$count > 0'` (or `$if:`) is not a comparison and always takes `then`; compare with `{ $prism: … }`. A label that is only a `$` word comes from data or a binding (`'{{$.label}}'`).
|
|
279
285
|
|
|
280
286
|
### 2. Template strings
|
|
281
287
|
|
|
@@ -349,6 +355,8 @@ Set `model: '<path>'` on a component to wire it for two-way data binding. The re
|
|
|
349
355
|
}
|
|
350
356
|
```
|
|
351
357
|
|
|
358
|
+
A `model` (and the `for` of a loop around it) written as one template, `'{{$.draftName}}'`, binds the same as the bare path.
|
|
359
|
+
|
|
352
360
|
The `Input` component built into `@niscorp/nova/adapters/react/components` already dispatches `ui:model` on change, so this just works. To wire your own component, see `REACT_DOCS.md`.
|
|
353
361
|
|
|
354
362
|
### Loop case
|
|
@@ -365,6 +373,8 @@ The `Input` component built into `@niscorp/nova/adapters/react/components` alrea
|
|
|
365
373
|
|
|
366
374
|
Type into the second input → `data.items[1].value` updates → re-render shows the new value.
|
|
367
375
|
|
|
376
|
+
`model: '$.item.value'` binds the same way: inside a loop, `$.` looks in the loop's own names (`index`, `items` and the `as` name) first, for writing as for reading. `model: '$.index'` and `model: '$index'` bind nothing — the loop index has no place in the data. Any other `$.name` is the data root's.
|
|
377
|
+
|
|
368
378
|
---
|
|
369
379
|
|
|
370
380
|
## Render context
|
|
@@ -391,7 +401,7 @@ When `strict: false` (the default), errors during rendering are caught at each s
|
|
|
391
401
|
|
|
392
402
|
- **`ComponentNotFoundError`** — `node.component` isn't registered.
|
|
393
403
|
- **`LayoutRefNotFoundError`** — `node.ref` isn't in the layout store.
|
|
394
|
-
- **`RenderError`** — anything else thrown during render (binding resolution, etc.).
|
|
404
|
+
- **`RenderError`** — a layout ref that comes back to itself with every binding reading as before, and anything else thrown during render (binding resolution, etc.).
|
|
395
405
|
|
|
396
406
|
All extend `NovaError` (see `DESIGN.md`).
|
|
397
407
|
|
|
@@ -467,7 +477,7 @@ If a component carries a static `.meta` property, `registerAll` picks it up auto
|
|
|
467
477
|
|
|
468
478
|
- **`Stack`** — flex container with `direction`, `gap`, `align`, `justify`, `padding`, `wrap`
|
|
469
479
|
- **`Text`** — typography element with `as`, `size`, `weight`, `color`
|
|
470
|
-
- **`Input`** — text input bound via `model`;
|
|
480
|
+
- **`Input`** — text input bound via `model`; while focused it shows a local draft of what is typed, and it honours a `debounce` prop (ms) on `ui:model` dispatches; with `replaceDraftOnWrite: true`, a change of the value at its model path while it is focused, other than an echo of what it dispatched, replaces what is typed (a write that leaves the stored value as it was changes nothing: see ADAPTER.md §6)
|
|
471
481
|
- **`Button`** — clickable button that dispatches `ui:click` with its `ref`
|
|
472
482
|
- **`Box`** — generic styling container
|
|
473
483
|
- **`Panel`** — titled container with optional `backRef`/`closeRef` header buttons
|
|
@@ -492,6 +502,8 @@ store.list(); // → array of stored ids
|
|
|
492
502
|
store.resolveReferences(layout); // → the layout with every { ref } it can resolve inlined
|
|
493
503
|
```
|
|
494
504
|
|
|
505
|
+
`resolveReferences` expands without data, so a `{ ref }` met again inside its own expansion (a tree whose rows use the same layout) is left as `{ ref }`; the renderer resolves it row by row.
|
|
506
|
+
|
|
495
507
|
`set` validates the layout against `LayoutNodeSchema` and throws `DefinitionValidationError` if it doesn't parse. So you can't accidentally store an invalid layout.
|
|
496
508
|
|
|
497
509
|
---
|
package/REACT_DOCS.md
CHANGED
|
@@ -140,8 +140,8 @@ Three components that hide the registry/provider/render-tree wiring. Each is als
|
|
|
140
140
|
```
|
|
141
141
|
|
|
142
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. A `layout` given as an id is read from `store`, so pass the `store` that holds it; an id it does not hold renders nothing.
|
|
143
|
-
- **`<Nova.Shell>`** — `shell`, `registry?` (default `shell.registry`), `slotWrapper?`, `builtins?` (default `true`:
|
|
144
|
-
- **`<Nova.Canvas>`** — `id`, plus optional `shell`, `registry?`, `builtins
|
|
143
|
+
- **`<Nova.Shell>`** — `shell`, `registry?` (default `shell.registry`), `slotWrapper?`, `builtins?` (default `true`: if `CanvasSlot` is missing, adds the default components the registry does not have, and replaces none it has). Renders the shell's canvasLayout.
|
|
144
|
+
- **`<Nova.Canvas>`** — `id`, plus optional `shell`, `registry?`, `builtins?` (as for `<Nova.Shell>`). With `shell` it provides its own `NovaShellProvider`; without, it must sit inside one. Renders that canvas's actionLayout.
|
|
145
145
|
|
|
146
146
|
---
|
|
147
147
|
|
|
@@ -341,7 +341,7 @@ registerNovaReactComponents(registry);
|
|
|
341
341
|
// Now Stack, Text, Input, Button, Box, Panel, JsonTree, CanvasSlot, ActionSlot are all registered.
|
|
342
342
|
```
|
|
343
343
|
|
|
344
|
-
`Input` is remote-safe: while focused it
|
|
344
|
+
`Input` is remote-safe: while focused it shows a local draft the incoming tree never overwrites, and a `debounce` prop (ms) coalesces `ui:model` dispatches, flushing on blur. With `replaceDraftOnWrite: true`, a change of the value at its model path while it is focused, other than an echo of a value it dispatched, replaces the draft and drops a pending debounced dispatch. A write that leaves the stored value as it was changes nothing, so with `debounce` a `set` to `""` while the typing still waits and the stored value is still `""` does not clear the field. See ADAPTER.md §6.
|
|
345
345
|
|
|
346
346
|
`CanvasSlot` and `ActionSlot` are shell-aware: they pull state from the React shell context and must only be used inside a `<NovaShellProvider>` (they are what shell/canvas layouts use to paint their regions).
|
|
347
347
|
|
package/README.md
CHANGED
|
@@ -29,12 +29,24 @@ no terminal. What consumes that tree is an adapter, and five ship here:
|
|
|
29
29
|
| `adapters/tty` | any terminal, line REPL | every interactive carries a `[n]` marker — type the number |
|
|
30
30
|
| `adapters/ink` | any terminal, full-screen | the same `[n]` markers, plus focus and live typing |
|
|
31
31
|
|
|
32
|
-
Same trees down, same `ui:click` / `ui:model` / `ui:key` events up —
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
An adapter is a walker plus a component kit of
|
|
32
|
+
Same trees down, same `ui:click` / `ui:model` / `ui:key` events up — every
|
|
33
|
+
walker takes the same tree, and a served host (see `@niscorp/moss`) cannot
|
|
34
|
+
tell them apart. The TTY numbering is computed once and shared: `[7]` is the
|
|
35
|
+
same interactive in the REPL and the TUI.
|
|
36
|
+
|
|
37
|
+
An adapter is a walker plus a component kit of domain-blind primitives. The
|
|
38
|
+
kits differ in what they ship, so an app renders unchanged in an adapter when
|
|
39
|
+
every component name it uses is in that kit or registered by the app; a name
|
|
40
|
+
the registry lacks draws a `COMPONENT_NOT_FOUND` marker.
|
|
41
|
+
|
|
42
|
+
| kit | components |
|
|
43
|
+
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
44
|
+
| `adapters/react/components`, `adapters/vue/components` | Stack, Text, Input, Button, Box, Panel, JsonTree, CanvasSlot, ActionSlot (9) |
|
|
45
|
+
| `adapters/dom/components` | Box, Row, Stack, Grid, Text, Button, Input, Textarea, Checkbox, Table, Panel, JsonTree, CanvasSlot, ActionSlot; Select (an Input), Switch (a Checkbox) |
|
|
46
|
+
| `adapters/tty/components` | the DOM kit's names plus Badge |
|
|
47
|
+
| `adapters/ink` | the TTY kit's names but CanvasSlot, with Textarea an Input |
|
|
48
|
+
|
|
49
|
+
The DOM and TTY walkers draw a `CanvasSlot` themselves; their kits register the name so the renderer accepts it, and either kit works as the shell's registry.
|
|
38
50
|
[ADAPTER.md](ADAPTER.md) is the whole contract; the terminal adapters' APIs
|
|
39
51
|
are in [TERMINAL_DOCS.md](TERMINAL_DOCS.md); a Svelte or react-native
|
|
40
52
|
adapter is a sibling folder, built the way the Vue one is.
|
|
@@ -387,7 +399,10 @@ configured path.
|
|
|
387
399
|
|
|
388
400
|
`model` paths inside loops are resolved to **absolute** paths
|
|
389
401
|
(`items.0.value`) by the renderer using its scope-path tracker, so
|
|
390
|
-
loop items round-trip correctly.
|
|
402
|
+
loop items round-trip correctly. A field with its own `ref` inside a
|
|
403
|
+
loop gets a model ref per row, `<ref>@<path>` (`qty@lines.0.qty`), so
|
|
404
|
+
each row writes its own path; its `ref`, and the ref a trigger matches
|
|
405
|
+
and `@event.ref` reads, stay `qty`.
|
|
391
406
|
|
|
392
407
|
---
|
|
393
408
|
|