@niscorp/nova 0.1.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 +552 -0
- package/ADAPTER.md +170 -0
- package/DESIGN.md +719 -0
- package/I18N_DOCS.md +224 -0
- package/LAYOUT_DOCS.md +505 -0
- package/LICENSE +202 -0
- package/REACT_DOCS.md +562 -0
- package/README.md +379 -0
- package/SHELL_DOCS.md +615 -0
- package/TERMINAL_DOCS.md +124 -0
- package/dist/adapters/dom/components/index.cjs +473 -0
- package/dist/adapters/dom/components/index.cjs.map +1 -0
- package/dist/adapters/dom/components/index.d.cts +48 -0
- package/dist/adapters/dom/components/index.d.ts +48 -0
- package/dist/adapters/dom/components/index.js +420 -0
- package/dist/adapters/dom/components/index.js.map +1 -0
- package/dist/adapters/dom/index.cjs +171 -0
- package/dist/adapters/dom/index.cjs.map +1 -0
- package/dist/adapters/dom/index.d.cts +29 -0
- package/dist/adapters/dom/index.d.ts +29 -0
- package/dist/adapters/dom/index.js +15 -0
- package/dist/adapters/dom/index.js.map +1 -0
- package/dist/adapters/dom/server.cjs +129 -0
- package/dist/adapters/dom/server.cjs.map +1 -0
- package/dist/adapters/dom/server.d.cts +15 -0
- package/dist/adapters/dom/server.d.ts +15 -0
- package/dist/adapters/dom/server.js +37 -0
- package/dist/adapters/dom/server.js.map +1 -0
- package/dist/adapters/ink/index.d.ts +75 -0
- package/dist/adapters/ink/index.js +472 -0
- package/dist/adapters/ink/index.js.map +1 -0
- package/dist/adapters/react/components/index.cjs +552 -0
- package/dist/adapters/react/components/index.cjs.map +1 -0
- package/dist/adapters/react/components/index.d.cts +30 -0
- package/dist/adapters/react/components/index.d.ts +30 -0
- package/dist/adapters/react/components/index.js +12 -0
- package/dist/adapters/react/components/index.js.map +1 -0
- package/dist/adapters/react/index.cjs +1526 -0
- package/dist/adapters/react/index.cjs.map +1 -0
- package/dist/adapters/react/index.d.cts +149 -0
- package/dist/adapters/react/index.d.ts +149 -0
- package/dist/adapters/react/index.js +12 -0
- package/dist/adapters/react/index.js.map +1 -0
- package/dist/adapters/tty/components/index.cjs +255 -0
- package/dist/adapters/tty/components/index.cjs.map +1 -0
- package/dist/adapters/tty/components/index.d.cts +40 -0
- package/dist/adapters/tty/components/index.d.ts +40 -0
- package/dist/adapters/tty/components/index.js +187 -0
- package/dist/adapters/tty/components/index.js.map +1 -0
- package/dist/adapters/tty/index.cjs +76 -0
- package/dist/adapters/tty/index.cjs.map +1 -0
- package/dist/adapters/tty/index.d.cts +47 -0
- package/dist/adapters/tty/index.d.ts +47 -0
- package/dist/adapters/tty/index.js +76 -0
- package/dist/adapters/tty/index.js.map +1 -0
- package/dist/adapters/vue/components/index.cjs +619 -0
- package/dist/adapters/vue/components/index.cjs.map +1 -0
- package/dist/adapters/vue/components/index.d.cts +224 -0
- package/dist/adapters/vue/components/index.d.ts +224 -0
- package/dist/adapters/vue/components/index.js +12 -0
- package/dist/adapters/vue/components/index.js.map +1 -0
- package/dist/adapters/vue/index.cjs +747 -0
- package/dist/adapters/vue/index.cjs.map +1 -0
- package/dist/adapters/vue/index.d.cts +98 -0
- package/dist/adapters/vue/index.d.ts +98 -0
- package/dist/adapters/vue/index.js +127 -0
- package/dist/adapters/vue/index.js.map +1 -0
- package/dist/agent/index.cjs +178 -0
- package/dist/agent/index.cjs.map +1 -0
- package/dist/agent/index.d.cts +28 -0
- package/dist/agent/index.d.ts +28 -0
- package/dist/agent/index.js +30 -0
- package/dist/agent/index.js.map +1 -0
- package/dist/chunk-2MNLEL45.js +47 -0
- package/dist/chunk-2MNLEL45.js.map +1 -0
- package/dist/chunk-3HGE3VWK.js +753 -0
- package/dist/chunk-3HGE3VWK.js.map +1 -0
- package/dist/chunk-4ZID7UX5.js +549 -0
- package/dist/chunk-4ZID7UX5.js.map +1 -0
- package/dist/chunk-7B3RDENH.js +1982 -0
- package/dist/chunk-7B3RDENH.js.map +1 -0
- package/dist/chunk-7S5BNPUS.js +54 -0
- package/dist/chunk-7S5BNPUS.js.map +1 -0
- package/dist/chunk-7TS3YVQR.js +114 -0
- package/dist/chunk-7TS3YVQR.js.map +1 -0
- package/dist/chunk-EG2RUXJN.js +266 -0
- package/dist/chunk-EG2RUXJN.js.map +1 -0
- package/dist/chunk-GVBBL36G.js +429 -0
- package/dist/chunk-GVBBL36G.js.map +1 -0
- package/dist/chunk-I5D2R5UA.js +753 -0
- package/dist/chunk-I5D2R5UA.js.map +1 -0
- package/dist/chunk-IGLCWXQ3.js +304 -0
- package/dist/chunk-IGLCWXQ3.js.map +1 -0
- package/dist/chunk-JI7ZRESP.js +64 -0
- package/dist/chunk-JI7ZRESP.js.map +1 -0
- package/dist/chunk-L5223LLX.js +31 -0
- package/dist/chunk-L5223LLX.js.map +1 -0
- package/dist/chunk-LA3BSEMX.js +1905 -0
- package/dist/chunk-LA3BSEMX.js.map +1 -0
- package/dist/chunk-OAMC6R6E.js +121 -0
- package/dist/chunk-OAMC6R6E.js.map +1 -0
- package/dist/chunk-OGD5CCMZ.js +62 -0
- package/dist/chunk-OGD5CCMZ.js.map +1 -0
- package/dist/chunk-PF4OJTYU.js +199 -0
- package/dist/chunk-PF4OJTYU.js.map +1 -0
- package/dist/chunk-PZ5AY32C.js +9 -0
- package/dist/chunk-PZ5AY32C.js.map +1 -0
- package/dist/chunk-RBU5PHN4.js +8 -0
- package/dist/chunk-RBU5PHN4.js.map +1 -0
- package/dist/chunk-RQB4PRPV.js +285 -0
- package/dist/chunk-RQB4PRPV.js.map +1 -0
- package/dist/chunk-V32EVEVM.js +464 -0
- package/dist/chunk-V32EVEVM.js.map +1 -0
- package/dist/chunk-ZITHBBF3.js +85 -0
- package/dist/chunk-ZITHBBF3.js.map +1 -0
- package/dist/devtools/index.cjs +1088 -0
- package/dist/devtools/index.cjs.map +1 -0
- package/dist/devtools/index.d.cts +33 -0
- package/dist/devtools/index.d.ts +33 -0
- package/dist/devtools/index.js +399 -0
- package/dist/devtools/index.js.map +1 -0
- package/dist/effects-CndX9K7D.d.cts +123 -0
- package/dist/effects-CndX9K7D.d.ts +123 -0
- package/dist/endpoints-CD-6Jl-H.d.ts +36 -0
- package/dist/endpoints-Dem-EdRx.d.cts +36 -0
- package/dist/i18n/index.cjs +299 -0
- package/dist/i18n/index.cjs.map +1 -0
- package/dist/i18n/index.d.cts +28 -0
- package/dist/i18n/index.d.ts +28 -0
- package/dist/i18n/index.js +180 -0
- package/dist/i18n/index.js.map +1 -0
- package/dist/index-CNfzSBe2.d.ts +93 -0
- package/dist/index-caZoXSwr.d.cts +93 -0
- package/dist/index.cjs +3723 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +144 -0
- package/dist/index.d.ts +144 -0
- package/dist/index.js +15 -0
- package/dist/index.js.map +1 -0
- package/dist/migrations/index.cjs +635 -0
- package/dist/migrations/index.cjs.map +1 -0
- package/dist/migrations/index.d.cts +97 -0
- package/dist/migrations/index.d.ts +97 -0
- package/dist/migrations/index.js +50 -0
- package/dist/migrations/index.js.map +1 -0
- package/dist/palette-CP0wd3bE.d.ts +15 -0
- package/dist/palette-lm0bU9i5.d.cts +15 -0
- package/dist/primitive-props-BH_EJWIe.d.cts +100 -0
- package/dist/primitive-props-BH_EJWIe.d.ts +100 -0
- package/dist/primitive-props-CGoJvmcH.d.cts +100 -0
- package/dist/primitive-props-CGoJvmcH.d.ts +100 -0
- package/dist/reflect/index.cjs +998 -0
- package/dist/reflect/index.cjs.map +1 -0
- package/dist/reflect/index.d.cts +125 -0
- package/dist/reflect/index.d.ts +125 -0
- package/dist/reflect/index.js +13 -0
- package/dist/reflect/index.js.map +1 -0
- package/dist/schemas-DPdeFlCT.d.cts +38 -0
- package/dist/schemas-DPdeFlCT.d.ts +38 -0
- package/dist/schemas-pMyyuXV7.d.cts +47 -0
- package/dist/schemas-pMyyuXV7.d.ts +47 -0
- package/dist/types-Boh9ckdG.d.ts +194 -0
- package/dist/types-Brc7v_pS.d.ts +198 -0
- package/dist/types-ByNSwtUV.d.cts +20 -0
- package/dist/types-DdltMfw7.d.ts +20 -0
- package/dist/types-De0KpxfI.d.cts +198 -0
- package/dist/types-DhHL0twe.d.ts +20 -0
- package/dist/types-Dv6JLmgo.d.cts +194 -0
- package/dist/types-Q80YtOQt.d.cts +20 -0
- package/package.json +237 -0
package/ADAPTER.md
ADDED
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# Nova adapter contract
|
|
2
|
+
|
|
3
|
+
Nova's core is framework-free. It renders layout trees into `RenderNode[]`
|
|
4
|
+
and owns all state, events, and subscriptions. An adapter binds that to a UI
|
|
5
|
+
framework. Adapters live under `src/adapters/`, one folder per framework with
|
|
6
|
+
its own export subpath. Five reference implementations ship: the React
|
|
7
|
+
adapter (`@niscorp/nova/adapters/react`), the Vue adapter
|
|
8
|
+
(`@niscorp/nova/adapters/vue` — Vue 3 render functions in plain TS, no SFC
|
|
9
|
+
compiler; provide/inject for the render context, composables bridging the
|
|
10
|
+
shell subscriptions into shallowRefs, children handed to a component as its
|
|
11
|
+
default slot, the same primitive kit at `/adapters/vue/components` over the
|
|
12
|
+
SAME props schemas as React's), the plain-DOM adapter
|
|
13
|
+
(`@niscorp/nova/adapters/dom`, `createDomView` — no framework at all), the
|
|
14
|
+
line-terminal adapter (`@niscorp/nova/adapters/tty`, `createTtyView` — a
|
|
15
|
+
pure render to `{ text, interactives }`; the host maps commands onto the
|
|
16
|
+
numbered interactives), and the full-screen terminal kit
|
|
17
|
+
(`@niscorp/nova/adapters/ink` — an Ink component vocabulary riding the React
|
|
18
|
+
adapter's walker; Tab cycles focus, Enter activates). A Svelte adapter is
|
|
19
|
+
a sibling folder, built the same way.
|
|
20
|
+
|
|
21
|
+
A react-shaped host that is not the DOM threads three optional seams through
|
|
22
|
+
`NovaRenderProvider`: `fallback` (unregistered names render their children
|
|
23
|
+
instead of an error marker), `textWrapper` (ink forbids bare strings outside
|
|
24
|
+
`<Text>`; the DOM renders them raw), and `errorMarker` (the default is a
|
|
25
|
+
`<span>`, which crashes a non-DOM renderer). Browser consumers omit all
|
|
26
|
+
three. A `ref`'d node rendered by a permissive fallback must still be
|
|
27
|
+
actionable — the TTY walker marks refs universally, so a kit-level fallback
|
|
28
|
+
(ink's) carries the focus + click convention itself.
|
|
29
|
+
|
|
30
|
+
An adapter imports only from `@niscorp/nova`'s public surface (plus its own
|
|
31
|
+
framework). Core never imports from an adapter.
|
|
32
|
+
|
|
33
|
+
## Obligations
|
|
34
|
+
|
|
35
|
+
An adapter must provide six things.
|
|
36
|
+
|
|
37
|
+
### 1. A RenderNode walker
|
|
38
|
+
|
|
39
|
+
Map `RenderNode[]` to framework elements:
|
|
40
|
+
|
|
41
|
+
- `text` → a text node.
|
|
42
|
+
- `fragment` → its children, keyless grouping.
|
|
43
|
+
- `error` → a visible marker carrying `code` and `message` (the React
|
|
44
|
+
adapter renders a `<span data-nova-error>`; match that convention).
|
|
45
|
+
- `component` → look the name up in the registry; unknown names render an
|
|
46
|
+
error marker with code `COMPONENT_NOT_FOUND`, never throw.
|
|
47
|
+
|
|
48
|
+
Inject framework props from the node using the core constants:
|
|
49
|
+
`node.model` → `NOVA_MODEL_PROP` (`{ ref, path }`), `node.ref` →
|
|
50
|
+
`NOVA_REF_PROP` (string). Spread `node.props` on top.
|
|
51
|
+
|
|
52
|
+
List identity comes from core's `renderNodeKey(node, index)`. Do not invent
|
|
53
|
+
key rules.
|
|
54
|
+
|
|
55
|
+
### 2. Dependency injection for registry, dispatch, publish
|
|
56
|
+
|
|
57
|
+
Rendered components never touch the shell. The adapter provides a component
|
|
58
|
+
registry, a `dispatch(event)` function, and a `publish(channel, payload)`
|
|
59
|
+
function through the framework's DI (React context, Vue provide/inject).
|
|
60
|
+
Without a shell, dispatch and publish are no-ops so static layouts render
|
|
61
|
+
with no event infrastructure.
|
|
62
|
+
|
|
63
|
+
### 3. Subscription bindings
|
|
64
|
+
|
|
65
|
+
Bridge core subscriptions into the framework's reactivity:
|
|
66
|
+
|
|
67
|
+
- `shell.onStateChange(handler)` — whole-shell snapshots.
|
|
68
|
+
- `shell.onCanvasChange(canvasId, handler)` — one canvas; the shell owns
|
|
69
|
+
the equality check and only fires on meaningful change.
|
|
70
|
+
- `runtime.onDataChange(handler)` / `runtime.onStatusChange(handler)` — one
|
|
71
|
+
action instance (via `shell.getRuntime(instanceId)`).
|
|
72
|
+
|
|
73
|
+
Trees come from `shell.getShellRenderTree()`, `shell.getCanvasRenderTree(id)`,
|
|
74
|
+
and `runtime.render()`. Recompute on the matching subscription, not on a
|
|
75
|
+
timer or a broader signal.
|
|
76
|
+
|
|
77
|
+
A remote renderer (a moss terminal) has no shell to subscribe to; it is
|
|
78
|
+
handed core's `RenderApi` instead — `frame()`, `canvasTree(canvasId)`,
|
|
79
|
+
`dispatch(canvasId, event)`, `publish(channel, payload?)` — and re-renders
|
|
80
|
+
when its host says so. The DOM adapter's `createDomView` consumes exactly
|
|
81
|
+
this shape.
|
|
82
|
+
|
|
83
|
+
A LOCAL shell is read as that same shape by core's `shellView(shell)` —
|
|
84
|
+
`{ api, subscribe }`: the shell's own trees as they stand, its own dispatch
|
|
85
|
+
(an event that names no origin goes to the canvas's active instance), and one
|
|
86
|
+
coalesced call per burst of changes. So an adapter written against `RenderApi`
|
|
87
|
+
draws a shell beside it with no second code path — the DOM adapter's
|
|
88
|
+
`mountShell(root, registry, shell)` is `createDomView` over a `shellView` —
|
|
89
|
+
and an empty canvas is `[]` either way (`canvasTreeOf`).
|
|
90
|
+
|
|
91
|
+
**Drawing to a string.** An adapter that can draw where there is no browser
|
|
92
|
+
lets a shell arrive as markup: React and Vue through their own server
|
|
93
|
+
renderers, the DOM adapter through `renderToString(registry, api, { window })`
|
|
94
|
+
(`@niscorp/nova/adapters/dom/server` — the host hands in a DOM; nova depends
|
|
95
|
+
on none). Await `shellSettled(shell)` first: an instance is `initializing`
|
|
96
|
+
until its mount hook has been awaited, so that is the moment the first screen
|
|
97
|
+
is whole. Adapters that adopt in place (React, Vue) hydrate over the markup; one
|
|
98
|
+
that rebuilds its root (DOM) replaces it with the same elements in one step.
|
|
99
|
+
|
|
100
|
+
### 4. Structural slots and the component vocabulary
|
|
101
|
+
|
|
102
|
+
Register two structural components under the core names `CANVAS_SLOT_NAME`
|
|
103
|
+
and `ACTION_SLOT_NAME` — the shell's default layouts reference them:
|
|
104
|
+
|
|
105
|
+
- **CanvasSlot** (`{ canvasId }`): renders that canvas's tree; nothing when
|
|
106
|
+
`canvasId` is missing.
|
|
107
|
+
- **ActionSlot** (`{ instanceId }`): renders that instance's tree; nothing
|
|
108
|
+
when `instanceId` is missing. Wrap the dispatch handed to the instance's
|
|
109
|
+
subtree with core's `scopeDispatch(dispatch, instanceId)` so its UI events
|
|
110
|
+
reach its own triggers only. Do not reimplement the stamping rule.
|
|
111
|
+
|
|
112
|
+
`flattenRenderTree` resolves `CanvasSlot` markers away, but the `ActionSlot`
|
|
113
|
+
marker *survives* flattening: it arrives as a component node with
|
|
114
|
+
`props: { instanceId, canvasId, definitionId }`, `key: instanceId`, and the
|
|
115
|
+
instance's rendered tree as children. An adapter rendering flattened (served)
|
|
116
|
+
trees must key by instance so a swap remounts, and may read the identity
|
|
117
|
+
props (a slot wrapper's seam).
|
|
118
|
+
|
|
119
|
+
The registered ActionSlot's `propsSchema` stays the *authoring* contract —
|
|
120
|
+
`instanceId` only. The flatten-stamped identity props are runtime output,
|
|
121
|
+
never authored, so they don't belong in the schema (the layout agent's
|
|
122
|
+
palette reads it as "props you may set"). Do not validate served trees
|
|
123
|
+
against registry schemas — that checks output against an authoring contract.
|
|
124
|
+
|
|
125
|
+
Ship the primitive vocabulary — Stack, Text, Input, Button, Box at minimum,
|
|
126
|
+
plus the introspection primitives Panel and JsonTree (nova's devtools compose
|
|
127
|
+
against them) — with static `meta` (description + props schema) so registries
|
|
128
|
+
and agent tooling can introspect them. The DOM kit additionally ships Row,
|
|
129
|
+
Grid, Checkbox, Textarea, and Table, with Select and Switch as aliases of
|
|
130
|
+
Input and Checkbox.
|
|
131
|
+
|
|
132
|
+
### 5. SlotWrapper persistence
|
|
133
|
+
|
|
134
|
+
If the adapter supports an app-supplied slot wrapper (animation, gating,
|
|
135
|
+
logging at the ActionSlot seam), the wrapper renders *persistently* — with
|
|
136
|
+
content or with none — so a presence-managing wrapper can animate an
|
|
137
|
+
instance leaving. The adapter hands the wrapper identity only (`canvasId`,
|
|
138
|
+
`instanceId`, the `ActionDefinition`), never live state; identity fields are
|
|
139
|
+
undefined while the slot is empty or exiting. Nova owns no timing.
|
|
140
|
+
|
|
141
|
+
### 6. Remote round-trip obligations
|
|
142
|
+
|
|
143
|
+
The shell may be authoritative over a socket (moss serves canvas trees down,
|
|
144
|
+
`NovaEvent`s up), so a bound input's echo is *asynchronous* — the tree carrying
|
|
145
|
+
the value you just typed arrives a round trip later. Two behaviours that a local
|
|
146
|
+
shell gets for free (its echo is synchronous) an adapter must implement itself,
|
|
147
|
+
or bound inputs drop keystrokes the moment the shell is remote:
|
|
148
|
+
|
|
149
|
+
- **Preserve the in-progress value of a focused input.** While a `model`-bound
|
|
150
|
+
input is focused, its local editing value is authoritative; an incoming tree
|
|
151
|
+
must not overwrite it. Release to the server value on blur. The React `Input`
|
|
152
|
+
holds a local `draft` (`null` = not editing, server wins); the DOM adapter
|
|
153
|
+
captures the focused element's value + caret and restores them across its full
|
|
154
|
+
rebuild (`captureFocus`/`restoreFocus`). Same rule, framework-shaped mechanism.
|
|
155
|
+
- **Honour the `debounce` prop on a `model`-bound node.** `props.debounce`
|
|
156
|
+
(milliseconds, default 0) coalesces `ui:model` dispatches; flush any pending
|
|
157
|
+
value on blur. Both reference adapters implement it — omitting it silently
|
|
158
|
+
makes a served `debounce` a no-op in your terminal, so the same layout behaves
|
|
159
|
+
differently across renderers.
|
|
160
|
+
|
|
161
|
+
These belong to *every* adapter because they are artifacts of the transport, not
|
|
162
|
+
of taste — unlike styling, hover, or animation, which *should* differ per kit.
|
|
163
|
+
The line is exactly that: an adapter shares nova's treatment of the round trip
|
|
164
|
+
and nothing about how pixels look.
|
|
165
|
+
|
|
166
|
+
A line renderer discharges both trivially: the TTY adapter has no focused
|
|
167
|
+
input (a `set <n> <text>` command is one atomic, complete value, so there is
|
|
168
|
+
no in-progress draft for an echo to clobber) and therefore nothing for
|
|
169
|
+
`debounce` to coalesce. The obligations bind any adapter that *does* hold
|
|
170
|
+
live input focus — a full-screen TUI included.
|