@niscorp/nova 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/CHANGELOG.md +48 -0
  2. package/README.md +56 -13
  3. package/SHELL_DOCS.md +13 -4
  4. package/dist/adapters/dom/index.cjs.map +1 -1
  5. package/dist/adapters/dom/index.js +2 -2
  6. package/dist/adapters/dom/server.js +2 -2
  7. package/dist/adapters/react/components/index.js +3 -3
  8. package/dist/adapters/react/index.cjs.map +1 -1
  9. package/dist/adapters/react/index.js +3 -3
  10. package/dist/adapters/tty/index.js +1 -1
  11. package/dist/adapters/vue/components/index.js +3 -3
  12. package/dist/adapters/vue/index.cjs.map +1 -1
  13. package/dist/adapters/vue/index.js +4 -4
  14. package/dist/{chunk-RYIIIXDX.js → chunk-DU2VIJAF.js} +57 -15
  15. package/dist/chunk-DU2VIJAF.js.map +1 -0
  16. package/dist/{chunk-VU6NNCEJ.js → chunk-F2H7WP6R.js} +4 -4
  17. package/dist/{chunk-VU6NNCEJ.js.map → chunk-F2H7WP6R.js.map} +1 -1
  18. package/dist/{chunk-QXQCPH33.js → chunk-G4LSLLGI.js} +4 -4
  19. package/dist/{chunk-QXQCPH33.js.map → chunk-G4LSLLGI.js.map} +1 -1
  20. package/dist/{chunk-MHW5VEIM.js → chunk-SVNK5NIK.js} +3 -3
  21. package/dist/{chunk-MHW5VEIM.js.map → chunk-SVNK5NIK.js.map} +1 -1
  22. package/dist/{chunk-UDCXGDLQ.js → chunk-VOD5JA4D.js} +3 -3
  23. package/dist/{chunk-UDCXGDLQ.js.map → chunk-VOD5JA4D.js.map} +1 -1
  24. package/dist/chunk-XQTI4Q4I.js +178 -0
  25. package/dist/chunk-XQTI4Q4I.js.map +1 -0
  26. package/dist/examples/index.cjs +1186 -0
  27. package/dist/examples/index.cjs.map +1 -0
  28. package/dist/examples/index.d.cts +63 -0
  29. package/dist/examples/index.d.ts +63 -0
  30. package/dist/examples/index.js +1158 -0
  31. package/dist/examples/index.js.map +1 -0
  32. package/dist/i18n/index.js +2 -176
  33. package/dist/i18n/index.js.map +1 -1
  34. package/dist/index.cjs +55 -12
  35. package/dist/index.cjs.map +1 -1
  36. package/dist/index.d.cts +5 -1
  37. package/dist/index.d.ts +5 -1
  38. package/dist/index.js +1 -1
  39. package/package.json +19 -8
  40. package/dist/chunk-RYIIIXDX.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,53 @@
1
1
  # @niscorp/nova
2
2
 
3
+ ## 0.2.1
4
+
5
+ ### Patch Changes
6
+
7
+ - fe30458: Every package exports its `package.json`, so an app can say which version of a package it runs by reading it from the package:
8
+
9
+ ```ts
10
+ import prism from '@niscorp/prism/package.json' with { type: 'json' };
11
+ prism.version; // the version that is installed, not the range that asked for it
12
+ ```
13
+
14
+ Until now the `exports` map hid it, and the only way to the version was a path into `node_modules`. `check:packages` installs the tarballs and reads every package's version this way.
15
+
16
+ **What to change:** nothing. An app that read a version by path can read it by name.
17
+
18
+ - 353b3c3: `@niscorp/nova/examples` — the reference as data. `NOVA_EXAMPLES` is 42 examples, in six groups (`NOVA_EXAMPLE_GROUPS`): the layout grammar (12), actions at work (7), endpoints (5), composition with fragments (5), shells (8) and i18n (5).
19
+
20
+ An example is a small app, what is done to it, and what it must then say: `{ id, group, title, description, action | shell, fragments?, layouts?, replies?, fetches?, phrases?, phraseKeys?, stage?, presses, expected }`. `action` is one action alone on one canvas (an example of the layout grammar is an action with no triggers); `shell` is several actions on several canvases. `replies` and `fetches` say what its endpoints are answered, so an example comes to the same thing wherever it is run. `presses` is what is done: a press, something typed, or the host changing the language. `expected` is every piece of text the screen then holds (its text, and what stands in props at a prose key), the one action's data, which actions stand on each canvas, and what was sent to each URL.
21
+
22
+ Every id an example brings begins with its own, so a host can hold all of them in one shell. The examples a host puts on its stage name only the plain components every kit has (`Stack`, `Text`, `Button`, `Input`) and nova's two slots, with no prop about looks, so whoever shows them draws them with its own kit. An example with `stage: false` (the five on i18n) is shown as what it comes to. The package's tests run each one and hold it to its `expected`.
23
+
24
+ Not in it: the adapters' own seams (`slotWrapper`), the look of nova's default components, and the harvest functions of `@niscorp/nova/i18n`, which are called, not mounted.
25
+
26
+ **What to change:** nothing.
27
+
28
+ - 7222c7d: The README's quick example runs as written. It registered no components, so it printed an error node (`COMPONENT_NOT_FOUND: Component not found in registry: Box`) where its comment promised the tree — and with components registered, `console.log` would still have printed the tree's children as `[Object]`. It now takes the terminal kit (`defaultRegistry()` from `@niscorp/nova/adapters/tty/components`), writes its text as children, the way the kits draw it, sends one press, and prints the whole tree; what it prints is in the README. No code changed.
29
+
30
+ **What to change:** nothing.
31
+
32
+ - c8982c2: `shellIdle(shell, { waitMs?, stopped? })` — a wait for what a press set going.
33
+
34
+ `shellSettled` answers once nothing is mounting. That is the first screen being whole, and it says nothing about what happens afterwards: a trigger's steps run detached from the event that fired them, so after `dispatch` it can answer `true` while the call the press made is still out. Anything that pressed and then read the screen had to sleep.
35
+
36
+ `shellIdle` resolves `true` once nothing is mounting **and** no chain the shell started is still running: no trigger's steps, no `emit` on its way to its listeners and what they then call, no hook a navigation started — including the re-read of an action a `pop` reveals, which runs while that action is already `active`. It takes the options `shellSettled` takes, with the same default wait, and resolves `false` when the wait runs out.
37
+
38
+ ```ts
39
+ shell.dispatch({ type: 'ui:click', ref: 'save', origin });
40
+ await shellIdle(shell, { waitMs: 5000 }); // the call has answered, and what it chained to has run
41
+ ```
42
+
43
+ It is about the shell's own work. It does not wait for the next body of a read the shell is following (a reactive read answers again when somebody else writes; `shell.onDataChange` says when), nor for anything outside the shell that an endpoint set going. A call that never answers holds it until the call's own timeout fails it.
44
+
45
+ `shellSettled` is unchanged, and still asks about mounts alone: a page is read whenever it is asked for, also while a long call is out, and that read should not wait on it.
46
+
47
+ `ActionRuntimeConfig` gains an optional `onChain`, which is how a runtime reports what it starts and does not await; a shell made by `createShell` wires it.
48
+
49
+ **What to change:** nothing. A check that slept after a press can await `shellIdle` instead.
50
+
3
51
  ## 0.2.0
4
52
 
5
53
  ### Minor Changes
package/README.md CHANGED
@@ -103,12 +103,8 @@ Explicitly out of scope right now:
103
103
  ## Quick example
104
104
 
105
105
  ```ts
106
- import {
107
- createShell,
108
- createComponentRegistry,
109
- createLayoutStore,
110
- type ActionDefinition,
111
- } from '@niscorp/nova';
106
+ import { createShell, createLayoutStore, type ActionDefinition } from '@niscorp/nova';
107
+ import { defaultRegistry } from '@niscorp/nova/adapters/tty/components';
112
108
 
113
109
  const counter: ActionDefinition = {
114
110
  id: 'counter',
@@ -123,27 +119,57 @@ const counter: ActionDefinition = {
123
119
  layout: {
124
120
  component: 'Box',
125
121
  children: [
126
- { component: 'Text', props: { value: '{{$.count}}' } },
127
- { component: 'Button', ref: 'inc', props: { label: '+1' } },
122
+ { component: 'Text', children: 'Count: {{$.count}}' },
123
+ { component: 'Button', ref: 'inc', children: '+1' },
128
124
  ],
129
125
  },
130
126
  };
131
127
 
132
128
  const shell = createShell({
133
129
  canvases: [{ id: 'main' }],
134
- registry: createComponentRegistry(),
130
+ registry: defaultRegistry(),
135
131
  layoutStore: createLayoutStore(),
136
132
  actions: { counter },
137
133
  });
138
134
 
139
135
  const id = shell.push('main', 'counter');
140
136
  const runtime = shell.getRuntime(id);
141
- console.log(runtime?.render());
142
- // → RenderNode[] tree describing the Box / Text / Button
137
+ shell.dispatch({ type: 'ui:click', ref: 'inc' });
138
+ console.dir(runtime?.render(), { depth: null });
143
139
  ```
144
140
 
145
- There is no React in that example. A framework adapter would consume
146
- the same `RenderNode[]` and produce real elements.
141
+ It prints the `RenderNode[]` tree, after the press:
142
+
143
+ ```
144
+ [
145
+ {
146
+ type: 'component',
147
+ name: 'Box',
148
+ props: {},
149
+ children: [
150
+ {
151
+ type: 'component',
152
+ name: 'Text',
153
+ props: {},
154
+ children: [ { type: 'text', value: 'Count: 1' } ]
155
+ },
156
+ {
157
+ type: 'component',
158
+ name: 'Button',
159
+ props: {},
160
+ children: [ { type: 'text', value: '+1' } ],
161
+ ref: 'inc'
162
+ }
163
+ ]
164
+ }
165
+ ]
166
+ ```
167
+
168
+ There is no React in that example, and no browser. The registry is empty
169
+ until a kit is registered, and a layout that names a component it does not
170
+ hold renders an error node (`COMPONENT_NOT_FOUND`) in its place;
171
+ `defaultRegistry()` is the terminal kit. A framework adapter would consume the
172
+ same `RenderNode[]` and produce real elements.
147
173
 
148
174
  ---
149
175
 
@@ -453,6 +479,23 @@ one, and checks every captured lab-app document still upgrades and parses.
453
479
 
454
480
  ---
455
481
 
482
+ ## Examples
483
+
484
+ `@niscorp/nova/examples` exports the reference as data. `NOVA_EXAMPLES` is a list of small apps, each with what is done to it and what it must then say; `NOVA_EXAMPLE_GROUPS` names the groups they come in (layouts, actions, endpoints, composition, shells, i18n), in reading order.
485
+
486
+ ```ts
487
+ import { NOVA_EXAMPLES } from '@niscorp/nova/examples';
488
+
489
+ const counter = NOVA_EXAMPLES.find((example) => example.id === 'counter');
490
+ // counter.action is an ActionDefinition: mount it in a shell and draw it with your own kit
491
+ // counter.presses: [{ ref: 'more' }, { ref: 'more' }, { ref: 'fewer' }]
492
+ // counter.expected: { data: { count: 1 }, says: ['Count: 1', 'One more', 'One fewer'] }
493
+ ```
494
+
495
+ An example is one action alone on a canvas (`action`) or a small shell (`shell`: canvases, actions, and how the canvases are arranged). Beside either stand what it needs from its host: `fragments`, stored `layouts`, a phrase book (`phrases`, `phraseKeys`), and what its endpoints are answered (`replies` for `fn:`, `fetches` for a URL). Every id an example brings begins with the example's own, so a host can hold all of them in one shell.
496
+
497
+ The examples name only the plain components every kit has (`Stack`, `Text`, `Button`, `Input`) and nova's two slots, with no prop about looks. One that says `stage: false` (the ones on i18n) cannot simply be mounted beside a host's own screens, and is shown as what it comes to. The package's tests run each one, so what they say is what this version does.
498
+
456
499
  ## Building / dev
457
500
 
458
501
  ```bash
package/SHELL_DOCS.md CHANGED
@@ -529,12 +529,12 @@ useEffect(() => {
529
529
 
530
530
  Always dispose shells you create — they hold references to runtimes which hold references to event listeners.
531
531
 
532
- ### `shellView(shell)` and `shellSettled(shell)`
532
+ ### `shellView(shell)`, `shellSettled(shell)` and `shellIdle(shell)`
533
533
 
534
- Two helpers beside the shell, for anything that draws one.
534
+ Three helpers beside the shell: for anything that draws one, and for anything that presses something on one and reads what came of it.
535
535
 
536
536
  ```ts
537
- import { shellView, shellSettled } from '@niscorp/nova';
537
+ import { shellView, shellSettled, shellIdle } from '@niscorp/nova';
538
538
 
539
539
  const { api, subscribe } = shellView(shell); // the shell, as a RenderApi
540
540
  api.frame(); // the shell layout's tree
@@ -543,12 +543,21 @@ api.dispatch('main', { type: 'ui:click', ref: 'save' }); // to the canvas's ac
543
543
  const stop = subscribe(() => redraw()); // once per burst of changes
544
544
 
545
545
  const whole = await shellSettled(shell, { waitMs: 300 }); // true: nothing is still mounting
546
+
547
+ api.dispatch('main', { type: 'ui:click', ref: 'save' });
548
+ const done = await shellIdle(shell, { waitMs: 5000 }); // true: what the press set going has finished
546
549
  ```
547
550
 
548
- `api.dispatch` stamps an event that names no `origin` with the canvas's active instance; `api.publish(channel, payload?)` is `shell.publish`. `shellSettled` also takes `stopped?: () => boolean` — once it answers `true` the wait ends with `false`.
551
+ `api.dispatch` stamps an event that names no `origin` with the canvas's active instance; `api.publish(channel, payload?)` is `shell.publish`. `shellSettled` and `shellIdle` also take `stopped?: () => boolean` — once it answers `true` the wait ends with `false`.
549
552
 
550
553
  `shellView` is what lets an adapter written against `RenderApi` (the DOM and TTY adapters, a moss terminal) draw a shell that lives beside it. `shellSettled` resolves `true` once no instance is `initializing` — every mount hook, and what it chained to, has been awaited — and `false` if `waitMs` (default 300) runs out first. It is the moment to draw a shell to markup, and the moment for the page's own shell to adopt it.
551
554
 
555
+ `shellSettled` asks about mounts and nothing else. A trigger's steps run detached from the event that fired them, so after a press it can answer `true` while the call the press made is still out. `shellIdle` is the wider question: nothing is mounting **and** no chain the shell started is still running — no trigger's steps, no `emit` on its way to its listeners (and what they then call), no re-read of an action a `pop` revealed. It is what a check awaits after `dispatch` instead of sleeping, and what anything that runs an action for somebody else awaits before it reads the screen. Same options, same default wait, `false` when the wait runs out.
556
+
557
+ Two things it does not wait for, because they are not this shell's work: the next body of a read the shell is **following** (a reactive read under moss answers again when somebody writes — wait for that with `shell.onDataChange`), and anything outside the shell that an endpoint set going. A call that never answers holds it until the call's own timeout fails it (30s by default; an endpoint's `timeoutMs` wins), so pass the `waitMs` you mean.
558
+
559
+ `shellSettled` is deliberately not widened to this. A page is read whenever it is asked for, also while a long call is out, and that read should not wait on it.
560
+
552
561
  ---
553
562
 
554
563
  ## Multi-canvas patterns