@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.
- package/CHANGELOG.md +48 -0
- package/README.md +56 -13
- package/SHELL_DOCS.md +13 -4
- package/dist/adapters/dom/index.cjs.map +1 -1
- package/dist/adapters/dom/index.js +2 -2
- package/dist/adapters/dom/server.js +2 -2
- package/dist/adapters/react/components/index.js +3 -3
- package/dist/adapters/react/index.cjs.map +1 -1
- package/dist/adapters/react/index.js +3 -3
- package/dist/adapters/tty/index.js +1 -1
- package/dist/adapters/vue/components/index.js +3 -3
- package/dist/adapters/vue/index.cjs.map +1 -1
- package/dist/adapters/vue/index.js +4 -4
- package/dist/{chunk-RYIIIXDX.js → chunk-DU2VIJAF.js} +57 -15
- package/dist/chunk-DU2VIJAF.js.map +1 -0
- package/dist/{chunk-VU6NNCEJ.js → chunk-F2H7WP6R.js} +4 -4
- package/dist/{chunk-VU6NNCEJ.js.map → chunk-F2H7WP6R.js.map} +1 -1
- package/dist/{chunk-QXQCPH33.js → chunk-G4LSLLGI.js} +4 -4
- package/dist/{chunk-QXQCPH33.js.map → chunk-G4LSLLGI.js.map} +1 -1
- package/dist/{chunk-MHW5VEIM.js → chunk-SVNK5NIK.js} +3 -3
- package/dist/{chunk-MHW5VEIM.js.map → chunk-SVNK5NIK.js.map} +1 -1
- package/dist/{chunk-UDCXGDLQ.js → chunk-VOD5JA4D.js} +3 -3
- package/dist/{chunk-UDCXGDLQ.js.map → chunk-VOD5JA4D.js.map} +1 -1
- package/dist/chunk-XQTI4Q4I.js +178 -0
- package/dist/chunk-XQTI4Q4I.js.map +1 -0
- package/dist/examples/index.cjs +1186 -0
- package/dist/examples/index.cjs.map +1 -0
- package/dist/examples/index.d.cts +63 -0
- package/dist/examples/index.d.ts +63 -0
- package/dist/examples/index.js +1158 -0
- package/dist/examples/index.js.map +1 -0
- package/dist/i18n/index.js +2 -176
- package/dist/i18n/index.js.map +1 -1
- package/dist/index.cjs +55 -12
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +5 -1
- package/dist/index.d.ts +5 -1
- package/dist/index.js +1 -1
- package/package.json +19 -8
- 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
|
-
|
|
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',
|
|
127
|
-
{ component: 'Button', ref: 'inc',
|
|
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:
|
|
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
|
-
|
|
142
|
-
|
|
137
|
+
shell.dispatch({ type: 'ui:click', ref: 'inc' });
|
|
138
|
+
console.dir(runtime?.render(), { depth: null });
|
|
143
139
|
```
|
|
144
140
|
|
|
145
|
-
|
|
146
|
-
|
|
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 `
|
|
532
|
+
### `shellView(shell)`, `shellSettled(shell)` and `shellIdle(shell)`
|
|
533
533
|
|
|
534
|
-
|
|
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
|
|
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
|