@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/LAYOUT_DOCS.md
ADDED
|
@@ -0,0 +1,505 @@
|
|
|
1
|
+
# Layout — Author Guide
|
|
2
|
+
|
|
3
|
+
How to write nova layouts. A layout is a JSON tree describing what to render. The renderer walks it, resolves any bindings against a data object, and emits a `RenderNode[]` tree that a framework adapter (the React adapter ships with nova) turns into actual UI.
|
|
4
|
+
|
|
5
|
+
This guide is for **authoring** layouts. For the architecture (why it's JSON, how the unified resolver works, etc.) see `DESIGN.md`.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## A first layout
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { renderLayout, createComponentRegistry, createLayoutStore } from '@niscorp/nova';
|
|
13
|
+
import { registerNovaReactComponents } from '@niscorp/nova/adapters/react/components';
|
|
14
|
+
|
|
15
|
+
const registry = createComponentRegistry();
|
|
16
|
+
registerNovaReactComponents(registry);
|
|
17
|
+
const store = createLayoutStore();
|
|
18
|
+
|
|
19
|
+
const layout = {
|
|
20
|
+
component: 'Stack',
|
|
21
|
+
props: { direction: 'column', gap: 16, padding: 24 },
|
|
22
|
+
children: [
|
|
23
|
+
{ component: 'Text', props: { size: 'xl', weight: 'bold' }, children: 'Hello, {{$.name}}' },
|
|
24
|
+
{ component: 'Text', children: 'You have {{$.count}} new messages.' },
|
|
25
|
+
],
|
|
26
|
+
};
|
|
27
|
+
|
|
28
|
+
const data = { name: 'Ada', count: 3 };
|
|
29
|
+
|
|
30
|
+
const nodes = renderLayout(layout, data, {
|
|
31
|
+
store,
|
|
32
|
+
registry,
|
|
33
|
+
strict: false,
|
|
34
|
+
onError: console.error,
|
|
35
|
+
});
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
`nodes` is a `RenderNode[]` tree. Hand it to the React adapter (`<RenderTree nodes={nodes} />`) and it renders.
|
|
39
|
+
|
|
40
|
+
## Six node kinds
|
|
41
|
+
|
|
42
|
+
A `LayoutNode` is one of:
|
|
43
|
+
|
|
44
|
+
| Kind | What it does |
|
|
45
|
+
|---|---|
|
|
46
|
+
| **Component** | Instantiates a registered component |
|
|
47
|
+
| **Conditional** | Renders one of two branches based on a condition |
|
|
48
|
+
| **Loop** | Iterates an array and renders the body for each item |
|
|
49
|
+
| **LayoutRef** | Inlines another layout from the layout store |
|
|
50
|
+
| **Slot** | A placeholder a fragment-merge fills with the composing action's layout |
|
|
51
|
+
| **Primitive** | A bare string/number/boolean — rendered as text |
|
|
52
|
+
|
|
53
|
+
Plus arrays of any of the above (treated as a fragment).
|
|
54
|
+
|
|
55
|
+
That's it. Six things. Everything you write is a tree of those.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Component nodes
|
|
60
|
+
|
|
61
|
+
The most common one. References a component by name; the registry supplies the implementation.
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
{
|
|
65
|
+
component: 'Stack',
|
|
66
|
+
props: { direction: 'row', gap: 8 },
|
|
67
|
+
children: [
|
|
68
|
+
{ component: 'Text', children: 'left' },
|
|
69
|
+
{ component: 'Text', children: 'right' },
|
|
70
|
+
],
|
|
71
|
+
ref: 'header-stack', // optional — used by triggers and model binding
|
|
72
|
+
model: '$.draftValue', // optional — two-way data binding (see below)
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Fields
|
|
77
|
+
|
|
78
|
+
- **`component`** *(required)* — the registry name. Must match a name passed to `registry.register(name, ...)`.
|
|
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
|
+
- **`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.
|
|
82
|
+
- **`model`** *(optional)* — two-way binding path. See [Two-way binding](#two-way-binding).
|
|
83
|
+
|
|
84
|
+
### Resolved render output
|
|
85
|
+
|
|
86
|
+
A component node renders to a `RenderNode` of type `'component'`:
|
|
87
|
+
|
|
88
|
+
```ts
|
|
89
|
+
{
|
|
90
|
+
type: 'component',
|
|
91
|
+
name: 'Stack',
|
|
92
|
+
props: { direction: 'row', gap: 8 }, // values resolved against the data
|
|
93
|
+
children: [...], // recursive RenderNode[]
|
|
94
|
+
ref: 'header-stack', // if set on the source node
|
|
95
|
+
model: { ref: 'header-stack', path: 'draftValue' }, // if model was set
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The framework adapter (React) reads this and instantiates the React component with these props.
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Conditional nodes
|
|
104
|
+
|
|
105
|
+
Render one of two branches based on a condition.
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
{
|
|
109
|
+
if: '$.user.isLoggedIn',
|
|
110
|
+
then: { component: 'Text', children: 'Welcome back, {{$.user.name}}' },
|
|
111
|
+
else: { component: 'Text', children: 'Please log in.' },
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Fields
|
|
116
|
+
|
|
117
|
+
- **`if`** *(required)* — a binding evaluated for truthiness. Strings are bindings, primitives are themselves, objects can be `{$if}` directives. Truthiness rules: `null`, `undefined`, `false`, `0`, `''`, `[]`, `{}` are all falsy. Everything else is truthy.
|
|
118
|
+
- **`then`** *(required)* — `LayoutNode` rendered when the condition is truthy.
|
|
119
|
+
- **`else`** *(optional)* — `LayoutNode` rendered when the condition is falsy. If absent, an empty fragment is rendered.
|
|
120
|
+
|
|
121
|
+
### Conditionals inside other places
|
|
122
|
+
|
|
123
|
+
There are **two kinds of conditional** in nova:
|
|
124
|
+
|
|
125
|
+
1. **Conditional NODE** (this one) — appears in the layout tree as a sibling of components. Swaps whole subtrees.
|
|
126
|
+
2. **`{$if}` directive** — appears inside a value position (e.g. a prop value, a string content). See [Bindings — directives](#directives).
|
|
127
|
+
|
|
128
|
+
Use the node form when you're swapping whole UI sections. Use the directive form when you're picking a value for a single field.
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Loop nodes
|
|
133
|
+
|
|
134
|
+
Iterate an array and render the body once per item.
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
{
|
|
138
|
+
for: '$.users',
|
|
139
|
+
as: 'user',
|
|
140
|
+
do: {
|
|
141
|
+
component: 'Stack',
|
|
142
|
+
props: { direction: 'row', gap: 8 },
|
|
143
|
+
children: [
|
|
144
|
+
{ component: 'Text', children: '{{$user.name}}' },
|
|
145
|
+
{ component: 'Text', children: '({{$user.email}})' },
|
|
146
|
+
],
|
|
147
|
+
},
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Fields
|
|
152
|
+
|
|
153
|
+
- **`for`** *(required)* — a binding that resolves to an array. If it doesn't resolve to an array, the loop renders nothing (graceful empty).
|
|
154
|
+
- **`as`** *(required)* — the variable name used for the current item inside `do`. References as `$<name>` (no dot).
|
|
155
|
+
- **`key`** *(optional)* — a path on each item used for stable React keys when an adapter consumes the output. Currently informational; the React adapter falls back to index-based keys.
|
|
156
|
+
- **`do`** *(required)* — the `LayoutNode` rendered once per item, with the loop variable in scope.
|
|
157
|
+
|
|
158
|
+
### The `index` variable
|
|
159
|
+
|
|
160
|
+
Inside the loop body, the variable `index` is automatically bound to the current iteration index (0-based). Reference it as `$index`:
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
{
|
|
164
|
+
for: '$.items',
|
|
165
|
+
as: 'item',
|
|
166
|
+
do: { component: 'Text', children: '{{$index}}. {{$item.name}}' },
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### Empty arrays
|
|
171
|
+
|
|
172
|
+
If `for` resolves to `[]`, the loop renders nothing. To show fallback content, wrap the loop in a conditional:
|
|
173
|
+
|
|
174
|
+
```ts
|
|
175
|
+
{
|
|
176
|
+
if: '$.items.length',
|
|
177
|
+
then: { for: '$.items', as: 'item', do: { component: 'Text', children: '{{$item.name}}' } },
|
|
178
|
+
else: { component: 'Text', children: 'No items yet.' },
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## Layout refs
|
|
185
|
+
|
|
186
|
+
Reuse a stored layout by id. The referenced layout is inlined at the ref position with the current scope chain intact.
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
// Pre-populate the layout store:
|
|
190
|
+
store.set('user-card', {
|
|
191
|
+
component: 'Box',
|
|
192
|
+
props: { padding: 16, background: '#eef2ff', radius: 8 },
|
|
193
|
+
children: [
|
|
194
|
+
{ component: 'Text', props: { weight: 'bold' }, children: '{{$.name}}' },
|
|
195
|
+
{ component: 'Text', children: '{{$.email}}' },
|
|
196
|
+
],
|
|
197
|
+
});
|
|
198
|
+
|
|
199
|
+
// Use it from a layout:
|
|
200
|
+
{
|
|
201
|
+
component: 'Stack',
|
|
202
|
+
children: [
|
|
203
|
+
{ ref: 'user-card' },
|
|
204
|
+
{ ref: 'user-card' },
|
|
205
|
+
],
|
|
206
|
+
}
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Fields
|
|
210
|
+
|
|
211
|
+
- **`ref`** *(required)* — id of a layout previously stored via `store.set(id, layoutNode)`.
|
|
212
|
+
|
|
213
|
+
### Behavior
|
|
214
|
+
|
|
215
|
+
- 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.
|
|
216
|
+
- 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.
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## Slots
|
|
221
|
+
|
|
222
|
+
A placeholder that a fragment-merge fills.
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
{ slot: 'body' }
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Only meaningful inside an `ActionFragment`'s layout: when a fragment is composed with an action (a push/replace `with: [...]`), the fragment's `{ slot: 'body' }` node is replaced by the composing action's own layout. An unfilled slot renders nothing. See `ACTION_DOCS.md` for fragments.
|
|
229
|
+
|
|
230
|
+
(The shell's canvas layouts use registered slot *components* — `CanvasSlot` / `ActionSlot` — which are ordinary component nodes, not this node kind.)
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## Primitives
|
|
235
|
+
|
|
236
|
+
Bare strings, numbers, booleans, and `null` are valid layout nodes. They render as text content.
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
'Hello, world!' // → text 'Hello, world!'
|
|
240
|
+
42 // → text '42'
|
|
241
|
+
true // → text 'true'
|
|
242
|
+
null // → empty text
|
|
243
|
+
'Welcome, {{$.name}}!' // → text with interpolation
|
|
244
|
+
'$.message' // → text resolved from data
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
Strings get full binding treatment — templates and bare paths both work. This is how text content typically appears as the children of a component.
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## Bindings
|
|
252
|
+
|
|
253
|
+
The single most important concept. Every value in a layout that could be data-driven goes through the same resolver. There are three forms.
|
|
254
|
+
|
|
255
|
+
### 1. Bare path strings
|
|
256
|
+
|
|
257
|
+
A string starting with `$.` reads a value from the data object.
|
|
258
|
+
|
|
259
|
+
```ts
|
|
260
|
+
'$.user.name' // → data.user.name (raw value, type preserved)
|
|
261
|
+
'$.user.email'
|
|
262
|
+
'$.items.length' // → array length
|
|
263
|
+
'$item.name' // → reads `name` from the variable `item` in scope
|
|
264
|
+
'$index' // → loop iteration index
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
The raw value is returned with its type preserved — numbers stay numbers, arrays stay arrays.
|
|
268
|
+
|
|
269
|
+
**Path forms:**
|
|
270
|
+
- `$.foo.bar` — start from the data root, walk `foo` then `bar`
|
|
271
|
+
- `$foo` — read variable `foo` from the closest enclosing scope (loop variable, etc.)
|
|
272
|
+
- `$foo.bar` — read variable `foo`, walk `bar` on it
|
|
273
|
+
- `$index` — special: the loop iteration index
|
|
274
|
+
|
|
275
|
+
### 2. Template strings
|
|
276
|
+
|
|
277
|
+
A string with `{{...}}` patterns interpolates each expression and returns a string.
|
|
278
|
+
|
|
279
|
+
```ts
|
|
280
|
+
'Hello, {{$.user.name}}!' // → "Hello, Ada!"
|
|
281
|
+
'{{$.count}} items remaining' // → "3 items remaining"
|
|
282
|
+
'{{$.first}} {{$.last}}' // → "Ada Lovelace"
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Each `{{expr}}` is resolved against the scope and stringified. Numbers, booleans become their string form. Objects/arrays become JSON.
|
|
286
|
+
|
|
287
|
+
A string that is **exactly** `{{ expr }}` (one expression, nothing else) preserves the raw type — useful when you want to feed a number into a numeric prop:
|
|
288
|
+
|
|
289
|
+
```ts
|
|
290
|
+
{ component: 'Stack', props: { gap: '{{$.spacing}}' } }
|
|
291
|
+
// If $.spacing is 16, props.gap is the number 16, not the string "16".
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
### 3. Directives
|
|
295
|
+
|
|
296
|
+
Inside a value position (a prop value, a children string, etc.), you can use the `{$if, $then, $else}` directive object.
|
|
297
|
+
|
|
298
|
+
```ts
|
|
299
|
+
{
|
|
300
|
+
component: 'Text',
|
|
301
|
+
props: {
|
|
302
|
+
color: { $if: '$.isError', $then: '#dc2626', $else: '#16a34a' },
|
|
303
|
+
},
|
|
304
|
+
children: 'Status',
|
|
305
|
+
}
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
Truthiness rules are the same as conditional nodes.
|
|
309
|
+
|
|
310
|
+
**Why both `if` (node) and `$if` (directive)?** Different layers. The node form swaps whole UI subtrees. The directive form picks a single value. The node form lives in the layout tree; the directive form lives in the value space.
|
|
311
|
+
|
|
312
|
+
### What's NOT a binding
|
|
313
|
+
|
|
314
|
+
- Numbers, booleans, nulls — pass through unchanged
|
|
315
|
+
- Plain strings without `$` or `{{}}` — pass through unchanged
|
|
316
|
+
- Objects without `$if` — walked recursively, each value resolved
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
## Two-way binding
|
|
321
|
+
|
|
322
|
+
Set `model: '<path>'` on a component to wire it for two-way data binding. The renderer resolves the path against the current scope chain (so loop variables work) and emits a `model: { ref, path }` field on the rendered node. The React adapter installs an event listener that writes back to the data store when the component dispatches a `ui:model` event.
|
|
323
|
+
|
|
324
|
+
```ts
|
|
325
|
+
{
|
|
326
|
+
component: 'Input',
|
|
327
|
+
model: '$.draftName', // reads + writes data.draftName
|
|
328
|
+
props: { placeholder: 'Your name' },
|
|
329
|
+
}
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
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`.
|
|
333
|
+
|
|
334
|
+
### Loop case
|
|
335
|
+
|
|
336
|
+
`model: '$item.value'` inside a loop binds each iteration to its respective item's `value` field. The renderer materializes the absolute data path per iteration so each input writes to the right place.
|
|
337
|
+
|
|
338
|
+
```ts
|
|
339
|
+
{
|
|
340
|
+
for: '$.items',
|
|
341
|
+
as: 'item',
|
|
342
|
+
do: { component: 'Input', model: '$item.value' },
|
|
343
|
+
}
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Type into the second input → `data.items[1].value` updates → re-render shows the new value.
|
|
347
|
+
|
|
348
|
+
---
|
|
349
|
+
|
|
350
|
+
## Render context
|
|
351
|
+
|
|
352
|
+
`renderLayout(layout, data, ctx)` takes a context object:
|
|
353
|
+
|
|
354
|
+
```ts
|
|
355
|
+
{
|
|
356
|
+
store: LayoutStore, // for resolving LayoutRefs
|
|
357
|
+
registry: ComponentRegistry, // to validate component names
|
|
358
|
+
strict: boolean, // throw on errors vs return error nodes (default false)
|
|
359
|
+
onError: (error: NovaError) => void, // telemetry for non-strict errors
|
|
360
|
+
}
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
When `strict: false` (the default), errors during rendering are caught at each subtree boundary, surfaced via `onError`, and replaced with an error `RenderNode`. Sibling subtrees keep rendering. When `strict: true`, errors propagate.
|
|
364
|
+
|
|
365
|
+
### Errors the renderer can produce
|
|
366
|
+
|
|
367
|
+
- **`ComponentNotFoundError`** — `node.component` isn't registered.
|
|
368
|
+
- **`LayoutRefNotFoundError`** — `node.ref` isn't in the layout store.
|
|
369
|
+
- **`RenderError`** — anything else thrown during render (binding resolution, etc.).
|
|
370
|
+
|
|
371
|
+
All extend `NovaError` (see `DESIGN.md`).
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
## RenderNode output
|
|
376
|
+
|
|
377
|
+
The renderer emits `RenderNode[]` — a discriminated union:
|
|
378
|
+
|
|
379
|
+
```ts
|
|
380
|
+
type RenderNode =
|
|
381
|
+
| { type: 'text'; value: string }
|
|
382
|
+
| { type: 'fragment'; children: RenderNode[] }
|
|
383
|
+
| {
|
|
384
|
+
type: 'component';
|
|
385
|
+
name: string;
|
|
386
|
+
props: Record<string, unknown>;
|
|
387
|
+
children: RenderNode[];
|
|
388
|
+
ref?: string;
|
|
389
|
+
model?: { ref: string; path: string };
|
|
390
|
+
}
|
|
391
|
+
| { type: 'error'; code: string; message: string; nodeRef?: string };
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
This is the contract between the renderer and any framework adapter. The React adapter walks this tree and instantiates the registered React components. A future Vue adapter would do the same with Vue components.
|
|
395
|
+
|
|
396
|
+
---
|
|
397
|
+
|
|
398
|
+
## Components
|
|
399
|
+
|
|
400
|
+
A component is anything you put in the registry. The renderer doesn't know what they look like — that's the framework adapter's job. From the layout's perspective, a component is just a name + a props schema (optional).
|
|
401
|
+
|
|
402
|
+
### Registering a component
|
|
403
|
+
|
|
404
|
+
```ts
|
|
405
|
+
const registry = createComponentRegistry();
|
|
406
|
+
|
|
407
|
+
// Bare registration:
|
|
408
|
+
registry.register('MyButton', myButtonComponent);
|
|
409
|
+
|
|
410
|
+
// With meta (description + Zod props schema for introspection):
|
|
411
|
+
registry.register('MyButton', myButtonComponent, {
|
|
412
|
+
description: 'A clickable button.',
|
|
413
|
+
propsSchema: ButtonPropsSchema,
|
|
414
|
+
});
|
|
415
|
+
|
|
416
|
+
// Bulk registration:
|
|
417
|
+
registry.registerAll({
|
|
418
|
+
Stack,
|
|
419
|
+
Text,
|
|
420
|
+
Input,
|
|
421
|
+
Button,
|
|
422
|
+
Box,
|
|
423
|
+
});
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
### `registerAll` and static meta
|
|
427
|
+
|
|
428
|
+
If a component carries a static `.meta` property, `registerAll` picks it up automatically. Explicit meta in the call overrides static. See `REACT_DOCS.md` for the React-specific component shape.
|
|
429
|
+
|
|
430
|
+
### The default component set
|
|
431
|
+
|
|
432
|
+
`@niscorp/nova/adapters/react/components` ships nine headless React components:
|
|
433
|
+
|
|
434
|
+
- **`Stack`** — flex container with `direction`, `gap`, `align`, `justify`, `padding`, `wrap`
|
|
435
|
+
- **`Text`** — typography element with `as`, `size`, `weight`, `color`
|
|
436
|
+
- **`Input`** — text input bound via `model`; holds a local draft while focused and honours a `debounce` prop (ms) on `ui:model` dispatches
|
|
437
|
+
- **`Button`** — clickable button that dispatches `ui:click` with its `ref`
|
|
438
|
+
- **`Box`** — generic styling container
|
|
439
|
+
- **`Panel`** — titled container with optional `backRef`/`closeRef` header buttons
|
|
440
|
+
- **`JsonTree`** — collapsible JSON viewer (devtools' introspection primitive)
|
|
441
|
+
- **`CanvasSlot`** / **`ActionSlot`** — shell-aware slots used inside shell/canvas layouts; only usable under a `<NovaShellProvider>` (see `REACT_DOCS.md`)
|
|
442
|
+
|
|
443
|
+
Use `registerNovaReactComponents(registry)` to install all nine at once.
|
|
444
|
+
|
|
445
|
+
---
|
|
446
|
+
|
|
447
|
+
## Layout store
|
|
448
|
+
|
|
449
|
+
A simple keyed store for reusable layouts.
|
|
450
|
+
|
|
451
|
+
```ts
|
|
452
|
+
const store = createLayoutStore();
|
|
453
|
+
|
|
454
|
+
store.set('user-card', { component: 'Box', children: [...] });
|
|
455
|
+
store.get('user-card'); // → the stored layout, or undefined
|
|
456
|
+
store.has('user-card'); // → boolean
|
|
457
|
+
store.list(); // → array of stored ids
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
`set` validates the layout against `LayoutNodeSchema` and throws `DefinitionValidationError` if it doesn't parse. So you can't accidentally store an invalid layout.
|
|
461
|
+
|
|
462
|
+
---
|
|
463
|
+
|
|
464
|
+
## Errors
|
|
465
|
+
|
|
466
|
+
Layout-time errors all extend `NovaError`:
|
|
467
|
+
|
|
468
|
+
- **`ComponentNotFoundError`** — `{name: string}` context
|
|
469
|
+
- **`LayoutRefNotFoundError`** — `{ref: string}` context
|
|
470
|
+
- **`RenderError`** — generic wrapper for thrown exceptions during render
|
|
471
|
+
- **`DefinitionValidationError`** — when `layoutStore.set` rejects an invalid layout
|
|
472
|
+
|
|
473
|
+
In **strict mode** (`strict: true` on the render context) these throw. In **lax mode** (the default) the renderer catches them at each subtree boundary and emits a `{type: 'error', code, message, nodeRef?}` RenderNode in place of the broken subtree, then continues. Sibling subtrees are unaffected.
|
|
474
|
+
|
|
475
|
+
---
|
|
476
|
+
|
|
477
|
+
## Quick reference
|
|
478
|
+
|
|
479
|
+
```ts
|
|
480
|
+
// Component
|
|
481
|
+
{ component: string, props?: object, children?: LayoutNode | LayoutNode[], ref?: string, model?: string }
|
|
482
|
+
|
|
483
|
+
// Conditional (node form)
|
|
484
|
+
{ if: Resolvable, then: LayoutNode, else?: LayoutNode }
|
|
485
|
+
|
|
486
|
+
// Loop
|
|
487
|
+
{ for: Resolvable, as: string, key?: string, do: LayoutNode }
|
|
488
|
+
|
|
489
|
+
// LayoutRef
|
|
490
|
+
{ ref: string }
|
|
491
|
+
|
|
492
|
+
// Slot (inside an ActionFragment's layout)
|
|
493
|
+
{ slot: string }
|
|
494
|
+
|
|
495
|
+
// Primitive
|
|
496
|
+
'string' | 123 | true | false | null
|
|
497
|
+
|
|
498
|
+
// Array (fragment)
|
|
499
|
+
[LayoutNode, LayoutNode, ...]
|
|
500
|
+
|
|
501
|
+
// Conditional (directive form, used in value positions)
|
|
502
|
+
{ $if: Resolvable, $then: any, $else?: any }
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
For actions that drive data into the layout, see `ACTION_DOCS.md`. For wiring layouts into a React app, see `REACT_DOCS.md`.
|