@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/REACT_DOCS.md
ADDED
|
@@ -0,0 +1,562 @@
|
|
|
1
|
+
# React Adapter — Author Guide
|
|
2
|
+
|
|
3
|
+
How to use nova in a React app. The React adapter is a separate subpath: `@niscorp/nova/adapters/react`. The core (`@niscorp/nova`) is framework-agnostic and never imports React. The adapter is the glue that turns nova's `RenderNode[]` output into actual React elements.
|
|
4
|
+
|
|
5
|
+
This guide is for **using** nova in React. For nova's framework-agnostic core, see `LAYOUT_DOCS.md`, `ACTION_DOCS.md`, and `SHELL_DOCS.md`.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pnpm add @niscorp/nova
|
|
13
|
+
# React + react-dom are peer deps; you almost certainly already have them.
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
`@niscorp/nova/adapters/react` is the same package, accessed via the subpath export. No separate install.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## A first React app
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
import { createShell, createComponentRegistry, createLayoutStore } from '@niscorp/nova';
|
|
24
|
+
import { NovaShellProvider, useCanvas, useRenderTree, RenderTree } from '@niscorp/nova/adapters/react';
|
|
25
|
+
import { registerNovaReactComponents } from '@niscorp/nova/adapters/react/components';
|
|
26
|
+
import { useEffect, useState } from 'react';
|
|
27
|
+
|
|
28
|
+
const counter = {
|
|
29
|
+
id: 'counter',
|
|
30
|
+
data: { count: 0 },
|
|
31
|
+
layout: {
|
|
32
|
+
component: 'Stack',
|
|
33
|
+
props: { direction: 'column', gap: 16, padding: 24 },
|
|
34
|
+
children: [
|
|
35
|
+
{ component: 'Text', props: { size: 'xl', weight: 'bold' }, children: 'Count: {{$.count}}' },
|
|
36
|
+
{ component: 'Button', ref: 'inc', children: 'Increment' },
|
|
37
|
+
],
|
|
38
|
+
},
|
|
39
|
+
triggers: [
|
|
40
|
+
{ event: 'ui:click', ref: 'inc', do: [{ increment: 'count' }] },
|
|
41
|
+
],
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
const App = () => {
|
|
45
|
+
const [shell] = useState(() => {
|
|
46
|
+
const registry = createComponentRegistry();
|
|
47
|
+
registerNovaReactComponents(registry);
|
|
48
|
+
const layoutStore = createLayoutStore();
|
|
49
|
+
return {
|
|
50
|
+
shell: createShell({
|
|
51
|
+
canvases: [{ id: 'main' }],
|
|
52
|
+
registry,
|
|
53
|
+
layoutStore,
|
|
54
|
+
actions: { counter },
|
|
55
|
+
}),
|
|
56
|
+
registry,
|
|
57
|
+
};
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
useEffect(() => {
|
|
61
|
+
shell.shell.push('main', 'counter');
|
|
62
|
+
return () => shell.shell.dispose();
|
|
63
|
+
}, [shell]);
|
|
64
|
+
|
|
65
|
+
return (
|
|
66
|
+
<NovaShellProvider shell={shell.shell} registry={shell.registry}>
|
|
67
|
+
<CanvasView canvasId="main" />
|
|
68
|
+
</NovaShellProvider>
|
|
69
|
+
);
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
const CanvasView = ({ canvasId }: { canvasId: string }) => {
|
|
73
|
+
const canvas = useCanvas(canvasId);
|
|
74
|
+
const tree = useRenderTree(canvas.active?.id ?? '');
|
|
75
|
+
return <RenderTree nodes={tree} />;
|
|
76
|
+
};
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
This is a complete working React + nova counter. Click the button, the count goes up, the text re-renders.
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## The two providers
|
|
84
|
+
|
|
85
|
+
The React adapter has **two providers** because there are two ways to use nova in a React app:
|
|
86
|
+
|
|
87
|
+
### `<NovaShellProvider>` — full shell mode
|
|
88
|
+
|
|
89
|
+
Use this when you have a `Shell`. The provider wires the shell's dispatch/publish into the render context so components can emit events back to the shell. Most apps use this.
|
|
90
|
+
|
|
91
|
+
```tsx
|
|
92
|
+
<NovaShellProvider shell={shell} registry={registry}>
|
|
93
|
+
<CanvasView canvasId="main" />
|
|
94
|
+
</NovaShellProvider>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Props:
|
|
98
|
+
- **`shell`** — a `Shell` instance
|
|
99
|
+
- **`registry`** — the component registry. Same instance you passed to `createShell`.
|
|
100
|
+
- **`children`** — the React subtree that uses nova hooks.
|
|
101
|
+
|
|
102
|
+
### `<NovaRenderProvider>` — render-only mode
|
|
103
|
+
|
|
104
|
+
Use this when you want to render a layout without a shell — for previews, tests, or the showroom. You supply the dispatch and publish functions yourself (or pass no-ops).
|
|
105
|
+
|
|
106
|
+
```tsx
|
|
107
|
+
<NovaRenderProvider
|
|
108
|
+
registry={registry}
|
|
109
|
+
dispatch={(event) => console.log('dispatch:', event)}
|
|
110
|
+
publish={(channel, payload) => console.log('publish:', channel, payload)}
|
|
111
|
+
>
|
|
112
|
+
<RenderTree nodes={someStaticRenderTree} />
|
|
113
|
+
</NovaRenderProvider>
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Props:
|
|
117
|
+
- **`registry`** — the component registry
|
|
118
|
+
- **`dispatch`** — function to receive events from components
|
|
119
|
+
- **`publish`** — function to receive message bus publishes from components
|
|
120
|
+
- **`fallback?`** — renderer for unregistered component names; omit for
|
|
121
|
+
strict `COMPONENT_NOT_FOUND` markers
|
|
122
|
+
- **`textWrapper?`** / **`errorMarker?`** — host-specific leaf renderers.
|
|
123
|
+
The defaults render a text node as a bare string and an error node as a
|
|
124
|
+
`<span>`; a react host that is not the DOM (ink) supplies both — bare
|
|
125
|
+
strings and DOM tags crash it. Browser consumers omit them.
|
|
126
|
+
- **`children`** — the React subtree
|
|
127
|
+
|
|
128
|
+
This is what the showroom uses for layout-only stories that don't need a shell.
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Hooks
|
|
133
|
+
|
|
134
|
+
All hooks must be called inside one of the providers above.
|
|
135
|
+
|
|
136
|
+
### `useShell()`
|
|
137
|
+
|
|
138
|
+
Returns the active `Shell`. Throws if called outside a `<NovaShellProvider>`.
|
|
139
|
+
|
|
140
|
+
```tsx
|
|
141
|
+
const shell = useShell();
|
|
142
|
+
shell.dispatch({ type: 'ui:click', ref: 'manual' });
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### `useShellState()`
|
|
146
|
+
|
|
147
|
+
Returns the current `StateSnapshot`. Re-renders the calling component whenever any canvas changes. Backed by `useSyncExternalStore` so it's tearing-safe under React concurrent rendering.
|
|
148
|
+
|
|
149
|
+
```tsx
|
|
150
|
+
const state = useShellState();
|
|
151
|
+
const mainStack = state.canvases.main?.stack ?? [];
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### `useCanvas(canvasId)`
|
|
155
|
+
|
|
156
|
+
Returns the `CanvasState` for one canvas. Re-renders only when this specific canvas's stack or active instance changes.
|
|
157
|
+
|
|
158
|
+
```tsx
|
|
159
|
+
const canvas = useCanvas('main');
|
|
160
|
+
const activeId = canvas.active?.id;
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### `useActionData(instanceId)`
|
|
164
|
+
|
|
165
|
+
Returns the live data for an action instance. Re-renders whenever that instance's data changes. Returns `undefined` if the instance doesn't exist.
|
|
166
|
+
|
|
167
|
+
```tsx
|
|
168
|
+
const data = useActionData(activeId);
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### `useActionStatus(instanceId)`
|
|
172
|
+
|
|
173
|
+
Returns the action's status (`'initializing' | 'active' | 'suspended' | 'unmounted'`).
|
|
174
|
+
|
|
175
|
+
```tsx
|
|
176
|
+
const status = useActionStatus(activeId);
|
|
177
|
+
if (status === 'initializing') return <Spinner />;
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### `useRenderTree(instanceId)`
|
|
181
|
+
|
|
182
|
+
Returns the live `RenderNode[]` for an action instance. Re-computes whenever the instance's data changes. **The result is referentially stable** when the data hasn't changed — important for React's `useSyncExternalStore` and for downstream memoization.
|
|
183
|
+
|
|
184
|
+
```tsx
|
|
185
|
+
const tree = useRenderTree(activeId);
|
|
186
|
+
return <RenderTree nodes={tree} />;
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### `useShellRenderTree()` / `useCanvasRenderTree(canvasId)`
|
|
190
|
+
|
|
191
|
+
Return the live `RenderNode[]` for the shell's canvasLayout, or for one canvas's actionLayout. Re-compute on shell state change; the result is referentially stable while nothing changed. `useCanvasRenderTree(undefined)` returns a stable empty array. These are what `CanvasSlot`-style chrome uses; most apps render through `CanvasSlot`/`ActionSlot` components instead.
|
|
192
|
+
|
|
193
|
+
```tsx
|
|
194
|
+
const frame = useShellRenderTree();
|
|
195
|
+
const canvasTree = useCanvasRenderTree('main');
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### `useNovaDispatch()` / `useNovaPublish()`
|
|
199
|
+
|
|
200
|
+
Inside a registered component, call these to send events back to the shell. They read from the render context, not the shell context, so they work in both `NovaShellProvider` and `NovaRenderProvider` modes.
|
|
201
|
+
|
|
202
|
+
```tsx
|
|
203
|
+
const Button: NovaComponent<{ label?: string }> = ({ label, novaRef, children }) => {
|
|
204
|
+
const dispatch = useNovaDispatch();
|
|
205
|
+
return (
|
|
206
|
+
<button onClick={() => novaRef && dispatch({ type: 'ui:click', ref: novaRef })}>
|
|
207
|
+
{label ?? children}
|
|
208
|
+
</button>
|
|
209
|
+
);
|
|
210
|
+
};
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### `useNovaRegistry()`
|
|
214
|
+
|
|
215
|
+
Returns the active component registry. Useful for components that need to look up other components by name.
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## `<RenderTree>` and component instantiation
|
|
220
|
+
|
|
221
|
+
`<RenderTree nodes={...} />` walks a `RenderNode[]` array and renders each node. It dispatches:
|
|
222
|
+
|
|
223
|
+
- `text` nodes → render their `value` as text
|
|
224
|
+
- `fragment` nodes → recurse into children
|
|
225
|
+
- `error` nodes → render via `<ErrorMarker>`
|
|
226
|
+
- `component` nodes → look up the component in the registry and instantiate it
|
|
227
|
+
|
|
228
|
+
```tsx
|
|
229
|
+
const tree = useRenderTree(activeId);
|
|
230
|
+
return <RenderTree nodes={tree} />;
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
That's the entire React-side rendering pipeline. Everything else is the components themselves.
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## Writing your own component
|
|
238
|
+
|
|
239
|
+
A component for the React adapter is a React function component typed as `NovaComponent<P>`:
|
|
240
|
+
|
|
241
|
+
```tsx
|
|
242
|
+
import type { NovaComponent } from '@niscorp/nova/adapters/react';
|
|
243
|
+
import { z } from 'zod';
|
|
244
|
+
|
|
245
|
+
const MyButtonPropsSchema = z.object({
|
|
246
|
+
label: z.string().optional().describe('Button label.'),
|
|
247
|
+
variant: z.enum(['primary', 'secondary']).optional().describe('Visual variant.'),
|
|
248
|
+
}).strict();
|
|
249
|
+
|
|
250
|
+
type MyButtonProps = z.infer<typeof MyButtonPropsSchema>;
|
|
251
|
+
|
|
252
|
+
export const MyButton: NovaComponent<MyButtonProps> = ({
|
|
253
|
+
label,
|
|
254
|
+
variant,
|
|
255
|
+
novaRef,
|
|
256
|
+
novaModel,
|
|
257
|
+
children,
|
|
258
|
+
}) => {
|
|
259
|
+
// Component implementation...
|
|
260
|
+
return <button>{label ?? children}</button>;
|
|
261
|
+
};
|
|
262
|
+
|
|
263
|
+
// Static meta — picked up by registerAll() automatically.
|
|
264
|
+
MyButton.meta = {
|
|
265
|
+
description: 'A clickable button.',
|
|
266
|
+
propsSchema: MyButtonPropsSchema,
|
|
267
|
+
};
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
### Framework-injected props
|
|
271
|
+
|
|
272
|
+
The renderer adds these props to every component automatically (in addition to whatever `props` the layout supplied):
|
|
273
|
+
|
|
274
|
+
- **`children?: ReactNode`** — child slot
|
|
275
|
+
- **`novaRef?: string`** — the layout node's `ref` field, if set. Use this when dispatching events.
|
|
276
|
+
- **`novaModel?: { ref: string; path: string }`** — present when the layout used `model:` on this node. Indicates the component is two-way bound. Read it to know whether to dispatch `ui:model` events on change.
|
|
277
|
+
|
|
278
|
+
### Dispatching events
|
|
279
|
+
|
|
280
|
+
Components emit events back to the shell via `useNovaDispatch`:
|
|
281
|
+
|
|
282
|
+
```tsx
|
|
283
|
+
const dispatch = useNovaDispatch();
|
|
284
|
+
|
|
285
|
+
// On click
|
|
286
|
+
<button onClick={() => novaRef && dispatch({ type: 'ui:click', ref: novaRef })}>...</button>
|
|
287
|
+
|
|
288
|
+
// On input change (two-way binding)
|
|
289
|
+
<input
|
|
290
|
+
value={value}
|
|
291
|
+
onChange={(e) => {
|
|
292
|
+
if (novaModel) {
|
|
293
|
+
dispatch({ type: 'ui:model', ref: novaModel.ref, payload: e.target.value });
|
|
294
|
+
}
|
|
295
|
+
}}
|
|
296
|
+
/>
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
The shell routes these to triggers with matching `event:` and `ref:` fields. If your component is `model:`-bound, the runtime auto-installs a listener that converts `ui:model` events into `set` mutations on the bound path — no trigger needed.
|
|
300
|
+
|
|
301
|
+
### Registering
|
|
302
|
+
|
|
303
|
+
```ts
|
|
304
|
+
import { createComponentRegistry } from '@niscorp/nova';
|
|
305
|
+
import { MyButton } from './my-button';
|
|
306
|
+
|
|
307
|
+
const registry = createComponentRegistry();
|
|
308
|
+
registry.register('MyButton', MyButton);
|
|
309
|
+
|
|
310
|
+
// Or batch with the static meta picked up automatically:
|
|
311
|
+
registry.registerAll({ MyButton });
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
### The default component set
|
|
315
|
+
|
|
316
|
+
`@niscorp/nova/adapters/react/components` ships nine components and a registration helper:
|
|
317
|
+
|
|
318
|
+
```ts
|
|
319
|
+
import { registerNovaReactComponents } from '@niscorp/nova/adapters/react/components';
|
|
320
|
+
|
|
321
|
+
const registry = createComponentRegistry();
|
|
322
|
+
registerNovaReactComponents(registry);
|
|
323
|
+
// Now Stack, Text, Input, Button, Box, Panel, JsonTree, CanvasSlot, ActionSlot are all registered.
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
`Input` is remote-safe: while focused it holds a local draft the incoming tree never overwrites, and a `debounce` prop (ms) coalesces `ui:model` dispatches, flushing on blur. See ADAPTER.md §6.
|
|
327
|
+
|
|
328
|
+
`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).
|
|
329
|
+
|
|
330
|
+
You can mix the default set with your own:
|
|
331
|
+
|
|
332
|
+
```ts
|
|
333
|
+
const registry = createComponentRegistry();
|
|
334
|
+
registerNovaReactComponents(registry);
|
|
335
|
+
registry.register('MyButton', MyButton);
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## The `slotWrapper` seam
|
|
341
|
+
|
|
342
|
+
`slotWrapper` is the one pluggable point for wrapping an action instance's content as it mounts and unmounts. It's how you add **animation**, an **auth / feature gate**, **logging**, or an **error boundary** to a nova UI — without nova owning any of that logic.
|
|
343
|
+
|
|
344
|
+
Pass it to `<Nova.Shell>` (or to `NovaShellProvider` / `NovaRenderProvider` directly):
|
|
345
|
+
|
|
346
|
+
```tsx
|
|
347
|
+
<Nova.Shell shell={shell} slotWrapper={MySlotWrapper} />
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
Nova renders **every action instance's content** through it, at the `ActionSlot` seam — the single place an instance's content appears and disappears. (`ActionSlot` is what a canvas's action layout uses to render its active instance; it's how the shell paints each canvas.) `CanvasSlot` is a router, not a content seam, so it is *not* wrapped — there is exactly one place a `slotWrapper` lives.
|
|
351
|
+
|
|
352
|
+
### The contract
|
|
353
|
+
|
|
354
|
+
```tsx
|
|
355
|
+
import type { SlotWrapper } from '@niscorp/nova/adapters/react';
|
|
356
|
+
|
|
357
|
+
const MySlotWrapper: SlotWrapper = ({ canvasId, instanceId, action, children }) => {
|
|
358
|
+
// Decide what to render for this slot.
|
|
359
|
+
return <>{children}</>;
|
|
360
|
+
};
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
Nova hands the wrapper **identity, never live state**:
|
|
364
|
+
|
|
365
|
+
- **`canvasId`** — which canvas the instance lives in. Route by region: "animate `detail`", "gate `admin`".
|
|
366
|
+
- **`action`** — the full `ActionDefinition`. Route by action: gate on `action.id`, read `action.name`, etc.
|
|
367
|
+
- **`instanceId`** — the instance id. Use it as a React `key` for presence/animation.
|
|
368
|
+
- **`children`** — the rendered content, or `null`.
|
|
369
|
+
|
|
370
|
+
All three identity fields are `undefined` while a slot is **empty or exiting** (the instance is gone). A presence-managing wrapper captured them when the content was present.
|
|
371
|
+
|
|
372
|
+
> **Identity, not state.** The wrapper deliberately does *not* receive the action's live data — that would turn a presence/gate seam into a reactive render path. A wrapper that needs data reads it with a hook itself.
|
|
373
|
+
|
|
374
|
+
With no `slotWrapper`, rendering is unchanged — the default is a transparent passthrough.
|
|
375
|
+
|
|
376
|
+
### What nova owns here: nothing but the seam
|
|
377
|
+
|
|
378
|
+
No animation logic, no timing, no `animationend`, no transition names, and **no layout/JSON changes**. The animation library (framer-motion, react-transition-group, plain CSS), the durations, the easing, the gate policy — all live in your wrapper, app-side. Swap framer for CSS and nova doesn't change. Policy is keyed off `canvasId` / `action.id` in *your* code, never on the `ActionDefinition` schema (it's `.strict()`) or in the layout an author — or a model — writes.
|
|
379
|
+
|
|
380
|
+
### Example: animate one region
|
|
381
|
+
|
|
382
|
+
```tsx
|
|
383
|
+
const AnimatedSlot: SlotWrapper = ({ canvasId, instanceId, children }) => {
|
|
384
|
+
if (canvasId !== 'main') return <>{children}</>; // only the main region animates
|
|
385
|
+
return <div key={instanceId} className="slide-in">{children}</div>; // fresh key replays the enter
|
|
386
|
+
};
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
```css
|
|
390
|
+
@keyframes slide-in { from { opacity: 0; transform: translateY(10px) } }
|
|
391
|
+
.slide-in { animation: slide-in 240ms ease-out }
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
That's a CSS *enter*. A full *exit* (animate out on close) is the same seam plus a presence library: nova renders the wrapper persistently (`children` becomes `null` while the instance is exiting), so an `AnimatePresence` / `TransitionGroup` inside your wrapper can hold the leaving content and animate it out on its own clock — nova never waits and never signals completion.
|
|
395
|
+
|
|
396
|
+
### Example: an auth / feature gate
|
|
397
|
+
|
|
398
|
+
```tsx
|
|
399
|
+
const AuthGate: SlotWrapper = ({ action, children }) => {
|
|
400
|
+
const authed = useContext(AuthContext); // your app state, not nova data
|
|
401
|
+
if (action?.id.startsWith('secret') && !authed) {
|
|
402
|
+
return <Locked name={action.name} />; // a fallback instead of the content
|
|
403
|
+
}
|
|
404
|
+
return <>{children}</>;
|
|
405
|
+
};
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
The same seam, used as a gate: the wrapper decides whether to render the content or a fallback, keyed off the `ActionDefinition`. A generated layout that invents a brand-new canvas flows through the *same* wrapper and hits its default branch automatically — there is nothing to register per slot.
|
|
409
|
+
|
|
410
|
+
### `useSlotWrapper()`
|
|
411
|
+
|
|
412
|
+
Reads the active `slotWrapper` from render context (or `undefined`). You rarely call it directly — `ActionSlot` does — but it's there if you build your own slot rendering.
|
|
413
|
+
|
|
414
|
+
Both examples above ship as runnable demos in the showroom under **Slot wrappers**.
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
|
|
418
|
+
## Error handling
|
|
419
|
+
|
|
420
|
+
The renderer can produce error nodes when in lax mode (the default). The React adapter renders them via the `ErrorMarker` component:
|
|
421
|
+
|
|
422
|
+
```tsx
|
|
423
|
+
import { ErrorMarker } from '@niscorp/nova/adapters/react';
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
You don't usually need to use this directly — `<RenderTree>` handles error nodes internally. The output is a `<span data-nova-error="CODE">...</span>` element you can style with CSS.
|
|
427
|
+
|
|
428
|
+
For React-level errors (a buggy component throwing during render), use `<NovaErrorBoundary>`:
|
|
429
|
+
|
|
430
|
+
```tsx
|
|
431
|
+
import { NovaErrorBoundary } from '@niscorp/nova/adapters/react';
|
|
432
|
+
|
|
433
|
+
<NovaErrorBoundary fallback={<div>Something broke.</div>}>
|
|
434
|
+
<CanvasView canvasId="main" />
|
|
435
|
+
</NovaErrorBoundary>
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
This is a real React class component (the only class in the package — React 18 still requires class boundaries).
|
|
439
|
+
|
|
440
|
+
---
|
|
441
|
+
|
|
442
|
+
## React 18+ compatibility
|
|
443
|
+
|
|
444
|
+
- **Strict mode** — fully supported. The hooks use `useSyncExternalStore` and the render-tree hook caches its snapshot via `useRef`, so dev-mode double-mounting doesn't break anything.
|
|
445
|
+
- **Concurrent rendering** — fully supported. `useSyncExternalStore` is tearing-safe by design.
|
|
446
|
+
- **Suspense** — not used as a loading model. Loading state is explicit data on the action (`{ loading: true }` as a regular field). A consumer can wrap nova components in `<Suspense>` but it never activates because nova never throws promises during render.
|
|
447
|
+
- **SSR** — supported. The shell-backed hooks and `<NovaShell>` draw under `react-dom/server` (each hook hands `useSyncExternalStore` the shell's own value as its server snapshot), and `hydrateRoot` adopts that markup over a second boot of the same shell. Draw the WHOLE first screen on both sides: `await shellSettled(shell)` before `renderToString`, and again in the page before `hydrateRoot` — see below. A served tree needs no hooks at all — `NovaRenderProvider` + `RenderTree` over values (a frame and per-canvas trees) is store-free, and is the path `@niscorp/moss/terminal/react/server` draws through.
|
|
448
|
+
- **React Server Components** — not tested. The hooks are client-only.
|
|
449
|
+
|
|
450
|
+
### A shell drawn ahead of time
|
|
451
|
+
|
|
452
|
+
An app whose shell lives in the page can still arrive as markup. The same boot runs twice — once where there is no browser, once in the page:
|
|
453
|
+
|
|
454
|
+
```tsx
|
|
455
|
+
// at build (or per request) — no browser
|
|
456
|
+
const shell = boot();
|
|
457
|
+
await shellSettled(shell); // the first screen is whole
|
|
458
|
+
const html = renderToString(<NovaShell shell={shell} />);
|
|
459
|
+
|
|
460
|
+
// in the page — #root already holds `html`
|
|
461
|
+
const shell = boot();
|
|
462
|
+
await shellSettled(shell); // reach the same screen first
|
|
463
|
+
hydrateRoot(root, <NovaShell shell={shell} />); // the same elements, now alive
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
Three things make the two draws agree, and a build should check all of them (`nisc build` does): the boot is deterministic (pass `instanceIdFn` if an instance id reaches the markup; no `Math.random()`, no wall clock in a transform), the screen is settled on both sides, and whatever the mount hooks read answers the same in the page as it did at build. A read that answers differently — a date that has moved on — is drawn again by the page's shell, and React says so in the console.
|
|
467
|
+
|
|
468
|
+
---
|
|
469
|
+
|
|
470
|
+
## Common patterns
|
|
471
|
+
|
|
472
|
+
### Render the active action of a canvas
|
|
473
|
+
|
|
474
|
+
```tsx
|
|
475
|
+
const ActiveCanvas = ({ canvasId }: { canvasId: string }) => {
|
|
476
|
+
const canvas = useCanvas(canvasId);
|
|
477
|
+
const tree = useRenderTree(canvas.active?.id ?? '');
|
|
478
|
+
return <RenderTree nodes={tree} />;
|
|
479
|
+
};
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
### Render multiple canvases side by side
|
|
483
|
+
|
|
484
|
+
```tsx
|
|
485
|
+
const App = () => (
|
|
486
|
+
<NovaShellProvider shell={shell} registry={registry}>
|
|
487
|
+
<div style={{ display: 'flex' }}>
|
|
488
|
+
<ActiveCanvas canvasId="nav" />
|
|
489
|
+
<ActiveCanvas canvasId="content" />
|
|
490
|
+
</div>
|
|
491
|
+
</NovaShellProvider>
|
|
492
|
+
);
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
### Read live data alongside the canvas
|
|
496
|
+
|
|
497
|
+
```tsx
|
|
498
|
+
const Header = ({ canvasId }: { canvasId: string }) => {
|
|
499
|
+
const canvas = useCanvas(canvasId);
|
|
500
|
+
const data = useActionData(canvas.active?.id ?? '');
|
|
501
|
+
return <h1>{data?.['title'] as string ?? 'Untitled'}</h1>;
|
|
502
|
+
};
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
### Push from outside nova (a router event, a websocket message, etc.)
|
|
506
|
+
|
|
507
|
+
```tsx
|
|
508
|
+
const SomeReactComponent = () => {
|
|
509
|
+
const shell = useShell();
|
|
510
|
+
return <button onClick={() => shell.push('main', 'login')}>Log in</button>;
|
|
511
|
+
};
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
---
|
|
515
|
+
|
|
516
|
+
## Quick reference
|
|
517
|
+
|
|
518
|
+
```tsx
|
|
519
|
+
// Providers (all accept an optional slotWrapper)
|
|
520
|
+
<NovaShellProvider shell registry slotWrapper?>...</NovaShellProvider>
|
|
521
|
+
<NovaRenderProvider registry dispatch publish slotWrapper? fallback? textWrapper? errorMarker?>...</NovaRenderProvider>
|
|
522
|
+
<Nova.Shell shell slotWrapper? />
|
|
523
|
+
|
|
524
|
+
// Hooks
|
|
525
|
+
useShell() // → Shell (throws outside provider)
|
|
526
|
+
useShellState() // → StateSnapshot (subscribes)
|
|
527
|
+
useCanvas(canvasId) // → CanvasState (subscribes to canvas)
|
|
528
|
+
useActionData(instanceId) // → data | undefined
|
|
529
|
+
useActionStatus(instanceId) // → ActionStatus | undefined
|
|
530
|
+
useRenderTree(instanceId) // → RenderNode[]
|
|
531
|
+
useShellRenderTree() // → RenderNode[] (the canvasLayout)
|
|
532
|
+
useCanvasRenderTree(canvasId) // → RenderNode[] (one canvas's actionLayout)
|
|
533
|
+
useNovaDispatch() // → (event) => void
|
|
534
|
+
useNovaPublish() // → (channel, payload?) => void
|
|
535
|
+
useNovaRegistry() // → ComponentRegistry
|
|
536
|
+
useSlotWrapper() // → SlotWrapper | undefined
|
|
537
|
+
|
|
538
|
+
// Render
|
|
539
|
+
<RenderTree nodes={...} />
|
|
540
|
+
|
|
541
|
+
// Slot wrapper (animation, gates, logging, error boundaries)
|
|
542
|
+
type SlotWrapper = FC<{
|
|
543
|
+
canvasId?: string; // undefined while the slot is empty/exiting
|
|
544
|
+
instanceId?: string;
|
|
545
|
+
action?: ActionDefinition;
|
|
546
|
+
children?: ReactNode;
|
|
547
|
+
}>;
|
|
548
|
+
|
|
549
|
+
// Errors
|
|
550
|
+
<ErrorMarker code message />
|
|
551
|
+
<NovaErrorBoundary fallback>...</NovaErrorBoundary>
|
|
552
|
+
|
|
553
|
+
// Component contract
|
|
554
|
+
type NovaComponent<P> = React.FC<NovaComponentProps & P> & { meta?: ComponentMeta };
|
|
555
|
+
type NovaComponentProps = {
|
|
556
|
+
children?: ReactNode;
|
|
557
|
+
novaRef?: string;
|
|
558
|
+
novaModel?: { ref: string; path: string };
|
|
559
|
+
};
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
For the layout language registered components consume, see `LAYOUT_DOCS.md`. For the action machinery the shell drives, see `ACTION_DOCS.md` and `SHELL_DOCS.md`.
|