@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.
Files changed (170) hide show
  1. package/ACTION_DOCS.md +552 -0
  2. package/ADAPTER.md +170 -0
  3. package/DESIGN.md +719 -0
  4. package/I18N_DOCS.md +224 -0
  5. package/LAYOUT_DOCS.md +505 -0
  6. package/LICENSE +202 -0
  7. package/REACT_DOCS.md +562 -0
  8. package/README.md +379 -0
  9. package/SHELL_DOCS.md +615 -0
  10. package/TERMINAL_DOCS.md +124 -0
  11. package/dist/adapters/dom/components/index.cjs +473 -0
  12. package/dist/adapters/dom/components/index.cjs.map +1 -0
  13. package/dist/adapters/dom/components/index.d.cts +48 -0
  14. package/dist/adapters/dom/components/index.d.ts +48 -0
  15. package/dist/adapters/dom/components/index.js +420 -0
  16. package/dist/adapters/dom/components/index.js.map +1 -0
  17. package/dist/adapters/dom/index.cjs +171 -0
  18. package/dist/adapters/dom/index.cjs.map +1 -0
  19. package/dist/adapters/dom/index.d.cts +29 -0
  20. package/dist/adapters/dom/index.d.ts +29 -0
  21. package/dist/adapters/dom/index.js +15 -0
  22. package/dist/adapters/dom/index.js.map +1 -0
  23. package/dist/adapters/dom/server.cjs +129 -0
  24. package/dist/adapters/dom/server.cjs.map +1 -0
  25. package/dist/adapters/dom/server.d.cts +15 -0
  26. package/dist/adapters/dom/server.d.ts +15 -0
  27. package/dist/adapters/dom/server.js +37 -0
  28. package/dist/adapters/dom/server.js.map +1 -0
  29. package/dist/adapters/ink/index.d.ts +75 -0
  30. package/dist/adapters/ink/index.js +472 -0
  31. package/dist/adapters/ink/index.js.map +1 -0
  32. package/dist/adapters/react/components/index.cjs +552 -0
  33. package/dist/adapters/react/components/index.cjs.map +1 -0
  34. package/dist/adapters/react/components/index.d.cts +30 -0
  35. package/dist/adapters/react/components/index.d.ts +30 -0
  36. package/dist/adapters/react/components/index.js +12 -0
  37. package/dist/adapters/react/components/index.js.map +1 -0
  38. package/dist/adapters/react/index.cjs +1526 -0
  39. package/dist/adapters/react/index.cjs.map +1 -0
  40. package/dist/adapters/react/index.d.cts +149 -0
  41. package/dist/adapters/react/index.d.ts +149 -0
  42. package/dist/adapters/react/index.js +12 -0
  43. package/dist/adapters/react/index.js.map +1 -0
  44. package/dist/adapters/tty/components/index.cjs +255 -0
  45. package/dist/adapters/tty/components/index.cjs.map +1 -0
  46. package/dist/adapters/tty/components/index.d.cts +40 -0
  47. package/dist/adapters/tty/components/index.d.ts +40 -0
  48. package/dist/adapters/tty/components/index.js +187 -0
  49. package/dist/adapters/tty/components/index.js.map +1 -0
  50. package/dist/adapters/tty/index.cjs +76 -0
  51. package/dist/adapters/tty/index.cjs.map +1 -0
  52. package/dist/adapters/tty/index.d.cts +47 -0
  53. package/dist/adapters/tty/index.d.ts +47 -0
  54. package/dist/adapters/tty/index.js +76 -0
  55. package/dist/adapters/tty/index.js.map +1 -0
  56. package/dist/adapters/vue/components/index.cjs +619 -0
  57. package/dist/adapters/vue/components/index.cjs.map +1 -0
  58. package/dist/adapters/vue/components/index.d.cts +224 -0
  59. package/dist/adapters/vue/components/index.d.ts +224 -0
  60. package/dist/adapters/vue/components/index.js +12 -0
  61. package/dist/adapters/vue/components/index.js.map +1 -0
  62. package/dist/adapters/vue/index.cjs +747 -0
  63. package/dist/adapters/vue/index.cjs.map +1 -0
  64. package/dist/adapters/vue/index.d.cts +98 -0
  65. package/dist/adapters/vue/index.d.ts +98 -0
  66. package/dist/adapters/vue/index.js +127 -0
  67. package/dist/adapters/vue/index.js.map +1 -0
  68. package/dist/agent/index.cjs +178 -0
  69. package/dist/agent/index.cjs.map +1 -0
  70. package/dist/agent/index.d.cts +28 -0
  71. package/dist/agent/index.d.ts +28 -0
  72. package/dist/agent/index.js +30 -0
  73. package/dist/agent/index.js.map +1 -0
  74. package/dist/chunk-2MNLEL45.js +47 -0
  75. package/dist/chunk-2MNLEL45.js.map +1 -0
  76. package/dist/chunk-3HGE3VWK.js +753 -0
  77. package/dist/chunk-3HGE3VWK.js.map +1 -0
  78. package/dist/chunk-4ZID7UX5.js +549 -0
  79. package/dist/chunk-4ZID7UX5.js.map +1 -0
  80. package/dist/chunk-7B3RDENH.js +1982 -0
  81. package/dist/chunk-7B3RDENH.js.map +1 -0
  82. package/dist/chunk-7S5BNPUS.js +54 -0
  83. package/dist/chunk-7S5BNPUS.js.map +1 -0
  84. package/dist/chunk-7TS3YVQR.js +114 -0
  85. package/dist/chunk-7TS3YVQR.js.map +1 -0
  86. package/dist/chunk-EG2RUXJN.js +266 -0
  87. package/dist/chunk-EG2RUXJN.js.map +1 -0
  88. package/dist/chunk-GVBBL36G.js +429 -0
  89. package/dist/chunk-GVBBL36G.js.map +1 -0
  90. package/dist/chunk-I5D2R5UA.js +753 -0
  91. package/dist/chunk-I5D2R5UA.js.map +1 -0
  92. package/dist/chunk-IGLCWXQ3.js +304 -0
  93. package/dist/chunk-IGLCWXQ3.js.map +1 -0
  94. package/dist/chunk-JI7ZRESP.js +64 -0
  95. package/dist/chunk-JI7ZRESP.js.map +1 -0
  96. package/dist/chunk-L5223LLX.js +31 -0
  97. package/dist/chunk-L5223LLX.js.map +1 -0
  98. package/dist/chunk-LA3BSEMX.js +1905 -0
  99. package/dist/chunk-LA3BSEMX.js.map +1 -0
  100. package/dist/chunk-OAMC6R6E.js +121 -0
  101. package/dist/chunk-OAMC6R6E.js.map +1 -0
  102. package/dist/chunk-OGD5CCMZ.js +62 -0
  103. package/dist/chunk-OGD5CCMZ.js.map +1 -0
  104. package/dist/chunk-PF4OJTYU.js +199 -0
  105. package/dist/chunk-PF4OJTYU.js.map +1 -0
  106. package/dist/chunk-PZ5AY32C.js +9 -0
  107. package/dist/chunk-PZ5AY32C.js.map +1 -0
  108. package/dist/chunk-RBU5PHN4.js +8 -0
  109. package/dist/chunk-RBU5PHN4.js.map +1 -0
  110. package/dist/chunk-RQB4PRPV.js +285 -0
  111. package/dist/chunk-RQB4PRPV.js.map +1 -0
  112. package/dist/chunk-V32EVEVM.js +464 -0
  113. package/dist/chunk-V32EVEVM.js.map +1 -0
  114. package/dist/chunk-ZITHBBF3.js +85 -0
  115. package/dist/chunk-ZITHBBF3.js.map +1 -0
  116. package/dist/devtools/index.cjs +1088 -0
  117. package/dist/devtools/index.cjs.map +1 -0
  118. package/dist/devtools/index.d.cts +33 -0
  119. package/dist/devtools/index.d.ts +33 -0
  120. package/dist/devtools/index.js +399 -0
  121. package/dist/devtools/index.js.map +1 -0
  122. package/dist/effects-CndX9K7D.d.cts +123 -0
  123. package/dist/effects-CndX9K7D.d.ts +123 -0
  124. package/dist/endpoints-CD-6Jl-H.d.ts +36 -0
  125. package/dist/endpoints-Dem-EdRx.d.cts +36 -0
  126. package/dist/i18n/index.cjs +299 -0
  127. package/dist/i18n/index.cjs.map +1 -0
  128. package/dist/i18n/index.d.cts +28 -0
  129. package/dist/i18n/index.d.ts +28 -0
  130. package/dist/i18n/index.js +180 -0
  131. package/dist/i18n/index.js.map +1 -0
  132. package/dist/index-CNfzSBe2.d.ts +93 -0
  133. package/dist/index-caZoXSwr.d.cts +93 -0
  134. package/dist/index.cjs +3723 -0
  135. package/dist/index.cjs.map +1 -0
  136. package/dist/index.d.cts +144 -0
  137. package/dist/index.d.ts +144 -0
  138. package/dist/index.js +15 -0
  139. package/dist/index.js.map +1 -0
  140. package/dist/migrations/index.cjs +635 -0
  141. package/dist/migrations/index.cjs.map +1 -0
  142. package/dist/migrations/index.d.cts +97 -0
  143. package/dist/migrations/index.d.ts +97 -0
  144. package/dist/migrations/index.js +50 -0
  145. package/dist/migrations/index.js.map +1 -0
  146. package/dist/palette-CP0wd3bE.d.ts +15 -0
  147. package/dist/palette-lm0bU9i5.d.cts +15 -0
  148. package/dist/primitive-props-BH_EJWIe.d.cts +100 -0
  149. package/dist/primitive-props-BH_EJWIe.d.ts +100 -0
  150. package/dist/primitive-props-CGoJvmcH.d.cts +100 -0
  151. package/dist/primitive-props-CGoJvmcH.d.ts +100 -0
  152. package/dist/reflect/index.cjs +998 -0
  153. package/dist/reflect/index.cjs.map +1 -0
  154. package/dist/reflect/index.d.cts +125 -0
  155. package/dist/reflect/index.d.ts +125 -0
  156. package/dist/reflect/index.js +13 -0
  157. package/dist/reflect/index.js.map +1 -0
  158. package/dist/schemas-DPdeFlCT.d.cts +38 -0
  159. package/dist/schemas-DPdeFlCT.d.ts +38 -0
  160. package/dist/schemas-pMyyuXV7.d.cts +47 -0
  161. package/dist/schemas-pMyyuXV7.d.ts +47 -0
  162. package/dist/types-Boh9ckdG.d.ts +194 -0
  163. package/dist/types-Brc7v_pS.d.ts +198 -0
  164. package/dist/types-ByNSwtUV.d.cts +20 -0
  165. package/dist/types-DdltMfw7.d.ts +20 -0
  166. package/dist/types-De0KpxfI.d.cts +198 -0
  167. package/dist/types-DhHL0twe.d.ts +20 -0
  168. package/dist/types-Dv6JLmgo.d.cts +194 -0
  169. package/dist/types-Q80YtOQt.d.cts +20 -0
  170. 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`.