@niscorp/loom 0.4.0 → 0.6.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 (79) hide show
  1. package/CHANGELOG.md +118 -0
  2. package/DESIGN.md +48 -10
  3. package/README.md +63 -11
  4. package/dist/{chunk-HHPSU7IA.js → chunk-3UI7CG24.js} +3 -4
  5. package/dist/chunk-3UI7CG24.js.map +1 -0
  6. package/dist/{chunk-LVDY6FUH.js → chunk-BYOKCNIJ.js} +3 -3
  7. package/dist/{chunk-LVDY6FUH.js.map → chunk-BYOKCNIJ.js.map} +1 -1
  8. package/dist/chunk-GXA57JFR.js +409 -0
  9. package/dist/chunk-GXA57JFR.js.map +1 -0
  10. package/dist/chunk-J5SYOIR2.js +100 -0
  11. package/dist/chunk-J5SYOIR2.js.map +1 -0
  12. package/dist/{chunk-VMOYMYMV.js → chunk-LAQIW27Q.js} +3 -3
  13. package/dist/chunk-LAQIW27Q.js.map +1 -0
  14. package/dist/{chunk-IQMWPPHW.js → chunk-OVTQEAV3.js} +290 -23
  15. package/dist/chunk-OVTQEAV3.js.map +1 -0
  16. package/dist/index.cjs +74 -32
  17. package/dist/index.cjs.map +1 -1
  18. package/dist/index.d.cts +9 -9
  19. package/dist/index.d.ts +9 -9
  20. package/dist/index.js +1 -4
  21. package/dist/loom-editor-DlNYrfT9.d.ts +15 -0
  22. package/dist/loom-editor-DtGAf8eH.d.cts +15 -0
  23. package/dist/plugins/nova/index.cjs +6 -3
  24. package/dist/plugins/nova/index.cjs.map +1 -1
  25. package/dist/plugins/nova/index.d.cts +1 -1
  26. package/dist/plugins/nova/index.d.ts +1 -1
  27. package/dist/plugins/nova/index.js +2 -3
  28. package/dist/plugins/nova/react/index.cjs +21 -7
  29. package/dist/plugins/nova/react/index.cjs.map +1 -1
  30. package/dist/plugins/nova/react/index.d.cts +2 -2
  31. package/dist/plugins/nova/react/index.d.ts +2 -2
  32. package/dist/plugins/nova/react/index.js +5 -5
  33. package/dist/plugins/nova/react/index.js.map +1 -1
  34. package/dist/plugins/prism/index.cjs +2 -0
  35. package/dist/plugins/prism/index.cjs.map +1 -1
  36. package/dist/plugins/prism/index.d.cts +1 -1
  37. package/dist/plugins/prism/index.d.ts +1 -1
  38. package/dist/plugins/prism/index.js +2 -2
  39. package/dist/plugins/prism/react/index.cjs +200 -189
  40. package/dist/plugins/prism/react/index.cjs.map +1 -1
  41. package/dist/plugins/prism/react/index.d.cts +3 -3
  42. package/dist/plugins/prism/react/index.d.ts +3 -3
  43. package/dist/plugins/prism/react/index.js +48 -108
  44. package/dist/plugins/prism/react/index.js.map +1 -1
  45. package/dist/plugins/vex/index.cjs +2 -0
  46. package/dist/plugins/vex/index.cjs.map +1 -1
  47. package/dist/plugins/vex/index.d.cts +1 -1
  48. package/dist/plugins/vex/index.d.ts +1 -1
  49. package/dist/plugins/vex/index.js +2 -2
  50. package/dist/plugins/vex/react/index.cjs +154 -96
  51. package/dist/plugins/vex/react/index.cjs.map +1 -1
  52. package/dist/plugins/vex/react/index.d.cts +3 -3
  53. package/dist/plugins/vex/react/index.d.ts +3 -3
  54. package/dist/plugins/vex/react/index.js +42 -29
  55. package/dist/plugins/vex/react/index.js.map +1 -1
  56. package/dist/react/index.cjs +153 -92
  57. package/dist/react/index.cjs.map +1 -1
  58. package/dist/react/index.d.cts +7 -3
  59. package/dist/react/index.d.ts +7 -3
  60. package/dist/react/index.js +3 -118
  61. package/dist/react/index.js.map +1 -1
  62. package/dist/{types-V5kJWZJn.d.ts → types-BWIIThEy.d.cts} +2 -0
  63. package/dist/{types-V5kJWZJn.d.cts → types-BWIIThEy.d.ts} +2 -0
  64. package/package.json +7 -7
  65. package/dist/chunk-27OMOR7I.js +0 -17
  66. package/dist/chunk-27OMOR7I.js.map +0 -1
  67. package/dist/chunk-67D727GH.js +0 -47
  68. package/dist/chunk-67D727GH.js.map +0 -1
  69. package/dist/chunk-BU5TULRP.js +0 -132
  70. package/dist/chunk-BU5TULRP.js.map +0 -1
  71. package/dist/chunk-DEZGKUTO.js +0 -170
  72. package/dist/chunk-DEZGKUTO.js.map +0 -1
  73. package/dist/chunk-HHPSU7IA.js.map +0 -1
  74. package/dist/chunk-IQMWPPHW.js.map +0 -1
  75. package/dist/chunk-OFKHIREC.js +0 -212
  76. package/dist/chunk-OFKHIREC.js.map +0 -1
  77. package/dist/chunk-VMOYMYMV.js.map +0 -1
  78. package/dist/loom-editor-BthwIGIZ.d.cts +0 -24
  79. package/dist/loom-editor-CHtjjiBp.d.ts +0 -24
package/CHANGELOG.md CHANGED
@@ -1,5 +1,123 @@
1
1
  # @niscorp/loom
2
2
 
3
+ ## 0.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 17614f1: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a host relied on an emptied number box writing `null` for a number whose schema does not take `null`; the key is now absent (a host that saves on change stores it as missing).
8
+
9
+ Emptying a number box leaves the number absent, so `z.number().optional()` accepts the document; it wrote `{"qty": null}`, which the schema refused. A number whose schema takes `null` (`.nullable()`) still gets `null`. `parse` marks such a field `nullable: true` (a new optional key on `FieldMeta`), `toNova` passes `nullable` and `integer` to `loom:number`, and the kit's number box steps by 1 for an integer and by any amount otherwise.
10
+
11
+ - 16ed5d1: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a host relied on the form of an object with a key that has a dot in it (`{ "a.b": string }`); its controls showed nothing and wrote `{ a: { b: … } }`.
12
+
13
+ An object with a key that has a dot in it is edited as JSON. It compiles to the raw JSON box (`loom:raw`) bound where the object stands, so an edit writes the right keys; `createLoomEditor` wraps such a root document as it wraps a non-object root. `toNova` used directly at the root without `rootKey` keeps the old form, as there is nothing to bind the box to: pass `rootKey`.
14
+
15
+ - 92e5048: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a host relied on the built-in select displaying its first option for an enum with no value (a test that reads the select's value, say); documents do not change.
16
+
17
+ A select whose value is none of its options shows a disabled "—" row, where it displayed the first option although the document had no value; choosing that first option then wrote nothing, as it was no change. Every real option is now a change and is written. The README note "A select has no row for "none"" is gone.
18
+
19
+ - 5ba5973: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a host relied on a `z.literal` field compiling to a raw JSON box that starts at `null`, or reads the `Field` model `parse` exports (a literal is now `{ kind: "enum", options, default }`, where it was `{ kind: "unknown" }`).
20
+
21
+ A `z.literal` field is a select of its value (or values) and starts at the first. A plain `z.union` of literal-tagged objects used to start with `{ kind: null, radius: 0 }`, which no branch accepts; it now starts with `{ kind: "circle", radius: 0 }`.
22
+
23
+ - 4b55797: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a host relied on a newly chosen Prism op in the editor getting its optional arguments filled in, on `includeOptional: false` or `empty` being ignored inside union branches, or on the exact `loom:field` node of an optional field (it now has a `model` and an `optional: true` prop; a host kit that registers its own `loom:field` gets them and can ignore them).
24
+
25
+ An optional field can be removed. Its `loom:field` wrapper is bound to the field's value and carries `optional: true`, and the kit's `LoomField` shows a Remove link beside the label while the field has a value; Remove writes the field back to absent, so `.optional()` accepts the document. The controls show as before, and typing into them adds the field again. `toNova`'s `includeOptional` and `empty` now apply inside union branches as well (`{ shape: { kind: "a" } }` with `includeOptional: false`, where it was `{ kind: "a", note: "" }`). In the Prism plugin a newly chosen op starts with its required arguments only — `$localeMoney`, `$localeDate` and `$round` start as `{}`, `$sortBy` as `{ as: "" }` — where it got `minorUnits: false, digits: 0`, `hour12: false, timeZone: ""` and the like, which changed what the op did; an optional argument that has a value shows a Remove link.
26
+
27
+ - 7692665: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless a host relied on a union showing its first branch for a stored value no branch recognises, or reads the `Field` model `parse` exports and relied on a branch's `key` pattern naming an optional key where the branch also has a required unique one.
28
+
29
+ A union shows the branch the value is, or shows the value as JSON. A stored value whose tag no branch has (`kind: "triangle"`) was labelled with the first branch, and editing wrote that branch's fields into it; with no fallback branch it now chooses none — the chooser shows "—" and the value is shown in the JSON editor until a branch is chosen. A structural union tells its branches apart by a key each requires, before an optional one, so `{ a: "x", t: "y" }` shows the second branch of `z.union([{ a: number, b?: number }, { a: string, note?: string, t: string }])`, not the first. A union of `z.lazy` branches is a union with a chooser, not a raw JSON box.
30
+
31
+ ### Patch Changes
32
+
33
+ - 8d3d2c6: Compiling a schema no longer crashes on a field whose own code throws on a missing value (a `z.preprocess` that trims its input): such a field is required.
34
+
35
+ A field named `toString` or `constructor` shows its validation message; the error tree read and wrote inherited names, so the message never appeared.
36
+
37
+ `onChange` and the editor's `change` event fire once for an edit the validation answers, where they fired twice with the same values (once for the edit, once for the validation it wrote back). Every other write is one call, as before.
38
+
39
+ The README says how to use `toNova` and `attachValidation` directly with a schema that has a top-level `_errors` field: compile it with `rootKey`, as the editor does.
40
+
41
+ The kit and the reference plugins draw their colours from CSS variables (`--loom-border`, `--loom-danger` and 23 more, listed in the README), each falling back to the colour used today, so nothing looks different until a host sets one.
42
+
43
+ - e11c912: Renaming a key to a name another entry has (a prism template field, a vex aggregate or compute alias) no longer deletes the other entry: what was typed stays on screen with "… is already a key" under it, and the rename is written once the name no longer clashes; "Add" in the vex aggregate and compute widgets picks a free alias; a vex compute operand can be typed as a decimal ("1." stays on screen).
44
+
45
+ The prism node chooser lists every prism op under a category, taken from prism's own example groups, so `$fill`, `$has`, `$walk`, the locale ops and others are no longer missing from it.
46
+
47
+ Two recursive documents in one plugin each render their own nested levels: a recursive template is named after its action (`loom:tree:<action id>:<n>`) instead of `loom:tree:<n>`.
48
+
49
+ A document with a top-level field named `_errors` keeps that field in the editor: it is no longer stripped, overwritten by the error tree and reported missing.
50
+
51
+ A stored document whose root is not an object (a list, a scalar, a tuple, a union) opens as it was stored even when its schema refuses it, as an object document already did; validation flags it. It used to open the schema's defaults, which a host saving on change wrote over the stored document.
52
+
53
+ `<LoomEditor>` calls the `onChange` of its latest render, not the one it mounted with.
54
+
55
+ A field with two defaults starts at the one zod applies (`.default('a').default('b')` starts at `'b'`), and a discriminated union branch whose discriminator is an enum is tagged with the first value of that enum instead of `undefined`.
56
+
57
+ `LoomEditorPlugin` is now written as `LoomPlugin` plus `components`, the same shape it had.
58
+
59
+ A stored document opens on the branch of a discriminated union whose discriminator allows its value, when that discriminator is an enum (`kind: 'box'` for `z.enum(['square', 'box'])`); a tag `Pattern` lists every allowed value in a new optional `values`. The README says a key with a dot in it is not edited correctly, which needs a change in Nova.
60
+
61
+ - Updated dependencies [4b7d4a4]
62
+ - Updated dependencies [bf72478]
63
+ - Updated dependencies [e1db181]
64
+ - Updated dependencies [241bd4d]
65
+ - Updated dependencies [9f8e4b5]
66
+ - Updated dependencies [1b615d6]
67
+ - Updated dependencies [e7edd95]
68
+ - Updated dependencies [0a46ff6]
69
+ - Updated dependencies [59f314a]
70
+ - Updated dependencies [281108e]
71
+ - Updated dependencies [b233463]
72
+ - Updated dependencies [e2b9595]
73
+ - Updated dependencies [7aef6a7]
74
+ - Updated dependencies [79cf65c]
75
+ - Updated dependencies [e828562]
76
+ - Updated dependencies [6b01a50]
77
+ - Updated dependencies [6eef458]
78
+ - Updated dependencies [a41edf9]
79
+ - Updated dependencies [eb4ffb9]
80
+ - Updated dependencies [ae647e8]
81
+ - Updated dependencies [2effb54]
82
+ - Updated dependencies [bd996ea]
83
+ - Updated dependencies [180787b]
84
+ - Updated dependencies [d53910e]
85
+ - Updated dependencies [276f457]
86
+ - Updated dependencies [413afbd]
87
+ - Updated dependencies [1f6d37d]
88
+ - Updated dependencies [d77baf9]
89
+ - Updated dependencies [3f92c52]
90
+ - Updated dependencies [841c010]
91
+ - Updated dependencies [d93170b]
92
+ - Updated dependencies [8b4d6cd]
93
+ - Updated dependencies [4c6300e]
94
+ - Updated dependencies [be6e7af]
95
+ - Updated dependencies [b1e314e]
96
+ - Updated dependencies [d8dc7d9]
97
+ - Updated dependencies [b2b2d8d]
98
+ - Updated dependencies [f995714]
99
+ - Updated dependencies [df44b8e]
100
+ - Updated dependencies [a002748]
101
+ - Updated dependencies [2233113]
102
+ - Updated dependencies [04f5821]
103
+ - @niscorp/nova@0.6.0
104
+ - @niscorp/prism@0.4.0
105
+ - @niscorp/vex@0.5.0
106
+
107
+ ## 0.5.0
108
+
109
+ ### Minor Changes
110
+
111
+ - 6a62604: `createDevtoolsFunctions` answers a list of `{ id, description, execute }`, and `FunctionDefinition` names that shape. **Breaking.**
112
+
113
+ BREAKING — approved by moccadroid, 2026-10-18: `createDevtoolsFunctions(config)` returned a map of handlers by name; it returns `FunctionDefinition[]`, each with a description of what it does and what to send. An app that spread the map into its functions spreads the list into the list its `functions(session)` answers: `functions: (session) => [...createDevtoolsFunctions({ shell: () => session.shell, definitions }), ...]`.
114
+
115
+ ### Patch Changes
116
+
117
+ - Updated dependencies [63b9ab5]
118
+ - Updated dependencies [6a62604]
119
+ - @niscorp/nova@0.5.0
120
+
3
121
  ## 0.4.0
4
122
 
5
123
  ### Minor Changes
package/DESIGN.md CHANGED
@@ -34,7 +34,11 @@ Zod schema ──parse──▶ Field model (IR) ──toNova──▶ { act
34
34
  (the IR — intermediate representation). Zod has many ways to express the same
35
35
  shape; `parse` collapses those into one tagged union so every later stage can
36
36
  dispatch on a single `kind`. The kinds are: `string`, `number`, `boolean`,
37
- `enum`, `object`, `array`, `tuple`, `union`, `self`, and `unknown`.
37
+ `enum`, `object`, `array`, `tuple`, `union`, `self`, and `unknown`. A
38
+ `z.literal` is an `enum` of its values whose `default` is the first, so it
39
+ starts at its value. A field whose schema takes `null` (`.nullable()`, under any
40
+ other wrapper) carries `nullable: true`: the number control writes `null` when
41
+ it is emptied only for such a field, and leaves any other number absent.
38
42
 
39
43
  This model is pure data. It knows nothing about Nova. It is *what Loom edits*,
40
44
  described independently of how it is rendered.
@@ -80,7 +84,9 @@ editor without touching the compiler.
80
84
  The vocabulary is deliberately small and stable
81
85
  ([roles.ts](./src/compile/roles.ts)): layout primitives (`box`, `group`,
82
86
  `array`, `array-item`, `variant`, `branch`), a field wrapper (`field` — label,
83
- description, error, required marker), controls (`text`, `number`, `checkbox`,
87
+ description, error, required marker; an optional field's wrapper is bound to
88
+ the field's value and carries `optional: true`, so the kit offers Remove while
89
+ it has one), controls (`text`, `number`, `checkbox`,
84
90
  `select`, `raw`), and list actions (`append`, `row-menu`). Structural shapes
85
91
  (objects, arrays, unions) are *compositions* of these roles, not roles of their
86
92
  own. An array is a `loom:array` holding one `loom:array-item` per element and
@@ -111,15 +117,21 @@ layout. Instead, `parse` records a `Pattern` for each branch — the one fact th
111
117
  recognizes it in a value:
112
118
 
113
119
  - `tag` — a shared field equals a literal (`z.discriminatedUnion`).
114
- - `key` — a field unique to this branch is present (a structural union).
120
+ - `key` — a field unique to this branch is present (a structural union). A
121
+ field the branch requires is preferred, since every value of the branch has
122
+ it; an optional one is used only when the branch requires none.
115
123
  - `type` — the value's own JS type is unique to this branch, e.g. a string or
116
124
  array among objects (a mixed union).
117
125
  - `fallback` — the single catch-all branch, selected only when nothing else
118
126
  matches (e.g. an unconstrained object among tagged operations).
119
127
 
120
- At render, the variant widget matches the current value against these patterns
121
- in plain JS and shows the branch that fits; choosing a different branch writes
122
- that branch's defaults into the document. Tagged, structural, and mixed unions
128
+ A branch is read as what it unwraps to, so a branch behind `z.lazy`, or an
129
+ optional one, is told apart like any other. At render, the variant widget
130
+ matches the current value against these patterns in plain JS and shows the
131
+ branch that fits; choosing a different branch writes that branch's defaults
132
+ into the document. A value that no branch matches, in a union with no fallback
133
+ branch, chooses none: the chooser shows "—" and the value is shown in the JSON
134
+ editor, so nothing is written into it until a branch is chosen. Tagged, structural, and mixed unions
123
135
  are one code path, and no union-specific concept leaks into Nova.
124
136
 
125
137
  ### Recursion
@@ -136,12 +148,14 @@ reads: a node without it gets no template.
136
148
  against `$item`; a `self` reference inside an array points back to that
137
149
  template, and Nova resolves it per render against the live data. The form is
138
150
  therefore exactly as deep as the document, and growing or shrinking it is an
139
- ordinary list write.
151
+ ordinary list write. A template is named after its action (`loom:tree:<action id>:<n>`),
152
+ so the forms of one editor, which share a layout store, never share a template.
140
153
 
141
154
  This covers recursion through a list. A self-reference that is not inside an
142
155
  array (`next: z.lazy(() => Stop).optional()`) has no list write to grow by: it
143
156
  compiles to `loom:raw`, a raw JSON box, as does every kind outside the model
144
- (records, literals, dates, transforms, intersections, a union no pattern tells
157
+ (records, dates, transforms, intersections, an object with a key that has a
158
+ dot in it, which Nova cannot bind, a union no pattern tells
145
159
  apart).
146
160
 
147
161
  ### Custom widgets
@@ -167,7 +181,9 @@ of truth. `attachValidation` runs the schema's `safeParse` (refinements and all)
167
181
  over the live document and writes the problems into a reserved `_errors` slot in
168
182
  the data, as a tree shaped like the document: a problem at `venue.hall` is the
169
183
  string at `_errors.venue.hall`. The `_errors` slot is stripped from the document
170
- Loom reports out.
184
+ Loom reports out. The editor places a document with a top-level field named
185
+ `_errors` one level down, as it places a document whose root is not an object,
186
+ so the slot and the field never meet.
171
187
 
172
188
  That tree, which `editor.validations` publishes per document, holds the messages
173
189
  a form shows. It is not the verdict on the document:
@@ -209,7 +225,10 @@ contributed by plugins. The flow:
209
225
  - `open(artifact)` selects the plugin named by `artifact.type` and compiles its
210
226
  documents into form canvases. The controller then publishes the live document
211
227
  values (`editor.documents`) and validation problems (`editor.validations`), and
212
- emits `change` / `open` events. `editor.plugin` is the selected plugin,
228
+ emits `change` / `open` events. `change` is emitted once for each write to a
229
+ form's data, with one exception: the validation an edit causes writes its
230
+ answer before the edit's own change has reached the editor, and that `change`
231
+ already carries the edit, so the edit's change is not emitted again. `editor.plugin` is the selected plugin,
213
232
  `undefined` before the first `open`. The default canvas layout is a row of
214
233
  `loom:column` nodes, one holding the forms and one holding every other canvas;
215
234
  `loom:column` is the kit's sized column, with `grow` (default 1), its
@@ -230,6 +249,13 @@ to a single control, which has no document root to bind to. The controller wraps
230
249
  such a document under an internal key so its control has a real path, and unwraps
231
250
  it before publishing — so the wrapping never reaches a plugin or a consumer.
232
251
 
252
+ A seed opens as it was stored, whatever its schema says of it, and validation
253
+ flags what is wrong after the first edit: `<LoomEditor>` reports the documents on
254
+ mount, so a host that saves on every change would otherwise overwrite a stored
255
+ document with the schema's defaults before anybody touched it. The one seed that
256
+ opens the defaults is one that is not an object, for a document whose root is an
257
+ object: a form of fields has no place to show it.
258
+
233
259
  ### Plugins
234
260
 
235
261
  A plugin's core descriptor is small:
@@ -268,6 +294,18 @@ The controller produces the structure and
268
294
  drives the shell; React only mounts it and supplies components. A Vue surface
269
295
  later would be the same controller with a Vue kit.
270
296
 
297
+ ## How the code is laid out
298
+
299
+ Each directory under `src/` is reached through its `index.ts`: `compile/` (the
300
+ compiler: `parse`, `toNova`, roles, the field model), `editor/` (the editor
301
+ host), `react/` (the React surface), and `react/kit/` for the kit's parts the
302
+ plugins draw with (`JsonEditor`, `KeyInput`, `JsonPane`, the menus, `COLORS`).
303
+ Each plugin under `plugins/` is reached through its `index.ts` and its
304
+ `react/index.ts`. Those of `prism`, `vex` and `nova` are entry points of the
305
+ package (`@niscorp/loom/plugins/<name>` and `…/react`); `jsonviewer` and
306
+ `validation` are not, and reach a host through `defaultPlugins`. `validate.ts`
307
+ sits beside `src/index.ts`, so `pnpm check:modules` does not cover loom.
308
+
271
309
  ## Locked decisions
272
310
 
273
311
  These are settled, with the reason each is held.
package/README.md CHANGED
@@ -51,12 +51,20 @@ const { action, layouts } = toNova(parse(schema));
51
51
  ```
52
52
 
53
53
  A new document starts from each field's empty value: `''`, `0`, `false`, `[]`,
54
- the schema's default where it has one, and `null` for a kind Loom does not
55
- model. A required enum with no default is left out. These can fail the schema
54
+ the schema's default where it has one, a literal's own value, and `null` for a
55
+ kind Loom does not model. A required enum with no default is left out. These can fail the schema
56
56
  (`''` is not an email, `0` is not `min(1)`, `null` is not a record), and
57
57
  optional fields get them too. `toNova(model, { empty, includeOptional })`
58
- changes both: `empty` supplies a kind's starting value, `includeOptional: false`
59
- leaves optional fields out.
58
+ changes both, in every branch of a union too: `empty` supplies a kind's
59
+ starting value, `includeOptional: false` leaves optional fields out. In a form,
60
+ an optional field that has a value shows a **Remove** link beside its label,
61
+ which writes the field back to absent; its controls stay, and typing into them
62
+ adds it again. A field is optional when its schema accepts a missing
63
+ value; one whose own code throws on a missing value (a `z.preprocess` that trims
64
+ its input) is required. An emptied number box leaves the number absent, or
65
+ `null` where the schema takes `null`. An enum with no `.default()` starts with no
66
+ value in the document, and its select shows a disabled "—" until an option is
67
+ chosen.
60
68
 
61
69
  The other options: `value` is the document to edit, used as given in place of
62
70
  that starting document. `id` is the id of the action `toNova` returns (default
@@ -65,7 +73,10 @@ that starting document. `id` is the id of the action `toNova` returns (default
65
73
  root is not an object (a union, a scalar, an array): its one control binds at
66
74
  `$.<rootKey>` and the document is `{ [rootKey]: value }`, which you unwrap when
67
75
  you read it. Without `rootKey` a control at the root is bound to nothing, and
68
- `toNova` throws when the starting document is not an object. An `empty` entry
76
+ `toNova` throws when the starting document is not an object. `attachValidation`
77
+ writes its error tree into the document under `_errors`, so a schema with a
78
+ top-level `_errors` field is compiled with `rootKey` and validated as
79
+ `z.object({ [rootKey]: schema })`, as the editor does. An `empty` entry
69
80
  is a function `(field, options) => value`, and a field with a schema default
70
81
  keeps the default.
71
82
 
@@ -95,11 +106,12 @@ import { prism } from '@niscorp/loom/plugins/prism/react';
95
106
  - `artifact` says what to edit. `type` names the plugin that handles it;
96
107
  `documents` seeds the starting values (omit it to start from the schema's
97
108
  defaults).
98
- - `onChange` fires with the live document values on every edit.
109
+ - `onChange` fires once per edit, with the live document values; the one
110
+ passed on the latest render is the one called.
99
111
  - To switch to a different artifact, give the element a new React `key`.
100
112
  `plugins` and `artifact` are read once, when the element mounts.
101
113
 
102
- Two things the built-in kit draws are worth knowing before you rely on them:
114
+ Two things are worth knowing before you rely on them:
103
115
 
104
116
  - **Messages follow edits.** The inline messages and the Validations pane show
105
117
  what the schema said after the last edit. They are empty until the first one,
@@ -107,9 +119,13 @@ Two things the built-in kit draws are worth knowing before you rely on them:
107
119
  `path`) is shown nowhere, and a problem in a list row shows in the Validations
108
120
  pane only. They are not the verdict on a document; the schema is
109
121
  ([DESIGN.md](./DESIGN.md), "Validation").
110
- - **A select has no row for "none".** An enum with no `.default()` starts with no
111
- value in the document, and the select displays its first option all the same.
112
- Give the enum a `.default()` and the two start out agreeing.
122
+ - **An object with a key that has a dot in it is edited as JSON.** Nova reads
123
+ a binding path by splitting it at each `.`, so a field such as `"a.b"` cannot
124
+ be bound to a control of its own. Its object is compiled to the raw JSON box,
125
+ bound where the object stands, and an edit there writes the right keys. The
126
+ editor wraps such a root document as it wraps a non-object root. `toNova`
127
+ used directly at the root without `rootKey` has nothing to bind the box to and
128
+ keeps the controls, which bind the wrong place: pass `rootKey`.
113
129
 
114
130
  A **plugin** wires one domain into the editor. It contributes the schemas to edit
115
131
  (its *documents*), optional custom field widgets, and usually a preview. The three
@@ -117,7 +133,9 @@ reference plugins:
117
133
 
118
134
  - `prism({ input })` — edit a [Prism](../prism) transform config; the preview
119
135
  applies it to `input` and shows the output. `schema` replaces the schema of
120
- the `config` document (default: Prism's `NodeSchema`).
136
+ the `config` document (default: Prism's `NodeSchema`). An op chosen in the
137
+ editor starts with its required arguments only (`$localeMoney` starts as
138
+ `{}`), and an optional argument that has a value shows a Remove link.
121
139
  - `vex({ run, db })` — edit a [Vex](../vex) query; the preview runs it with `run`
122
140
  and shows the rows. Pass `db` to get column-aware field pickers. The artifact
123
141
  is `{ type: 'vex', documents: { query } }`; `schema` replaces the schema of
@@ -132,6 +150,40 @@ reference plugins:
132
150
  renders `layout` against; it has no schema, and its form has one control per
133
151
  key of the `data` the artifact carries.
134
152
 
153
+ ### Colours
154
+
155
+ The kit and the reference plugins draw every colour from a CSS variable, with
156
+ the colour Loom uses when it is not set. Set one on any element around the
157
+ editor to restyle what is inside it:
158
+
159
+ | Variable | Default | Used for |
160
+ |---|---|---|
161
+ | `--loom-border` | `#d1d5db` | inputs, buttons, menus, list frames |
162
+ | `--loom-border-subtle` | `#e5e7eb` | panels, groups, table heads |
163
+ | `--loom-border-faint` | `#f1f5f9` | lines between table rows |
164
+ | `--loom-surface` | `#fff` | buttons, menus, popovers, a preview's output |
165
+ | `--loom-surface-muted` | `#f9fafb` | panel and table heads, a muted preview |
166
+ | `--loom-fill` | `#f3f4f6` | add and Vex control buttons, a hovered menu item or op |
167
+ | `--loom-text` | `#111827` | group titles |
168
+ | `--loom-text-body` | `#1f2937` | a preview's output |
169
+ | `--loom-label` | `#374151` | field labels, panel heads |
170
+ | `--loom-muted` | `#6b7280` | descriptions, empty previews, table heads |
171
+ | `--loom-faint` | `#9ca3af` | a disabled menu item, op tags in the Prism chooser |
172
+ | `--loom-accent` | `#1d4ed8` | the active op in the Prism chooser, a field's Remove link |
173
+ | `--loom-accent-fill` | `#eff6ff` | behind the active op in the Prism chooser |
174
+ | `--loom-danger` | `#dc2626` | a field's message, the required mark, a refused name or JSON |
175
+ | `--loom-danger-text` | `#991b1b` | a preview's error |
176
+ | `--loom-danger-fill` | `#fef2f2` | behind JSON that does not parse, a preview's error |
177
+ | `--loom-danger-border` | `#fecaca` | around a Vex preview's error |
178
+ | `--loom-warning-text` | `#92400e` | a Vex preview's warning |
179
+ | `--loom-warning-fill` | `#fffbeb` | behind a Vex preview's warning |
180
+ | `--loom-warning-border` | `#fde68a` | around a Vex preview's warning |
181
+ | `--loom-shadow` | `rgba(0,0,0,0.12)` | the shadow of menus and Vex pickers |
182
+ | `--loom-shadow-strong` | `rgba(0,0,0,0.14)` | the shadow of the Prism chooser |
183
+ | `--loom-stage` | `#0c0c18` | the Nova preview's background |
184
+ | `--loom-stage-glow` | `#1b1b3a` | the light in the Nova preview's background |
185
+ | `--loom-stage-border` | `#2a2a4a` | around the Nova preview |
186
+
135
187
  ## Entry points
136
188
 
137
189
  | Import | What it gives you |
@@ -1,5 +1,4 @@
1
- import { isRecord } from './chunk-DEZGKUTO.js';
2
- import { mountView } from './chunk-27OMOR7I.js';
1
+ import { isRecord, mountView } from './chunk-OVTQEAV3.js';
3
2
  import { z } from 'zod';
4
3
 
5
4
  var layoutSchema = (manifest) => {
@@ -55,5 +54,5 @@ var novaPlugin = (config) => ({
55
54
  });
56
55
 
57
56
  export { PREVIEW, layoutSchema, novaPlugin };
58
- //# sourceMappingURL=chunk-HHPSU7IA.js.map
59
- //# sourceMappingURL=chunk-HHPSU7IA.js.map
57
+ //# sourceMappingURL=chunk-3UI7CG24.js.map
58
+ //# sourceMappingURL=chunk-3UI7CG24.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/plugins/nova/schema.ts","../src/plugins/nova/data.layout.ts","../src/plugins/nova/preview.layout.ts","../src/plugins/nova/preview.action.ts","../src/plugins/nova/index.ts"],"names":[],"mappings":";;;AAIO,IAAM,YAAA,GAAe,CAAC,QAAA,KAAqD;AAChF,EAAA,MAAM,CAAC,KAAA,EAAO,GAAG,IAAI,CAAA,GAAI,QAAA;AACzB,EAAA,IAAI,KAAA,KAAU,MAAA,EAAW,MAAM,IAAI,MAAM,oCAAoC,CAAA;AAE7E,EAAA,MAAM,KAAA,GAAiB,CAAA,CAAE,IAAA,CAAK,MAAM,UAAU,CAAA;AAC9C,EAAA,MAAM,MAAA,GAAS,CAAC,SAAA,KACd,CAAA,CAAE,MAAA,CAAO;AAAA,IACP,SAAA,EAAW,CAAA,CAAE,OAAA,CAAQ,SAAA,CAAU,IAAI,CAAA;AAAA,IACnC,OAAO,SAAA,CAAU,KAAA;AAAA,IACjB,GAAI,SAAA,CAAU,SAAA,KAAc,IAAA,GAAO,EAAE,QAAA,EAAU,CAAA,CAAE,KAAA,CAAM,KAAK,CAAA,EAAE,GAAI;AAAC,GACpE,CAAA;AAEH,EAAA,MAAM,UAAA,GAAa,CAAA,CAAE,kBAAA,CAAmB,WAAA,EAAa,CAAC,MAAA,CAAO,KAAK,CAAA,EAAG,GAAG,IAAA,CAAK,GAAA,CAAI,MAAM,CAAC,CAAC,CAAA;AACzF,EAAA,OAAO,UAAA;AACT;;;ACfA,IAAM,QAAA,GAAW,CAAC,GAAA,EAAa,KAAA,MAAgC;AAAA,EAC7D,SAAA,EAAW,YAAA;AAAA,EACX,KAAA,EAAO,EAAE,KAAA,EAAO,GAAA,EAAI;AAAA,EACpB,QAAA,EAAU,CAAC,EAAE,SAAA,EAAW,OAAO,KAAA,KAAU,QAAA,GAAW,WAAA,GAAc,UAAA,EAAY,KAAA,EAAO,CAAA,EAAA,EAAK,GAAG,IAAI;AACnG,CAAA,CAAA;AAEO,IAAM,UAAA,GAAa,CAAC,KAAA,KAA+B;AACxD,EAAA,MAAM,IAAA,GAAO,QAAA,CAAS,KAAK,CAAA,GAAI,QAAQ,EAAC;AACxC,EAAA,OAAO;AAAA,IACL,SAAA,EAAW,OAAA;AAAA,IACX,KAAA,EAAO,EAAE,SAAA,EAAW,QAAA,EAAU,KAAK,EAAA,EAAG;AAAA,IACtC,QAAA,EAAU,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA,CAAE,GAAA,CAAI,CAAC,GAAA,KAAQ,QAAA,CAAS,GAAA,EAAK,IAAA,CAAK,GAAG,CAAC,CAAC;AAAA,GACnE;AACF,CAAA;;;ACdO,IAAM,OAAA,GAAU;AAEhB,IAAM,aAAA,GAA4B;AAAA,EACvC,SAAA,EAAW,OAAA;AAAA,EACX,KAAA,EAAO,EAAE,SAAA,EAAW,aAAA;AACtB,CAAA;;;ACJO,IAAM,aAAA,GAAkC;AAAA,EAC7C,EAAA,EAAI,OAAA;AAAA,EACJ,MAAA,EAAQ,aAAA;AAAA,EACR,IAAA,EAAM,EAAE,SAAA,EAAW,EAAC;AACtB,CAAA;;;ACGO,IAAM,UAAA,GAAa,CAAC,MAAA,MAA0C;AAAA,EACnE,IAAA,EAAM,MAAA;AAAA,EACN,SAAA,EAAW;AAAA,IACT,MAAA,EAAQ,YAAA,CAAa,MAAA,CAAO,QAAQ,CAAA;AAAA,IACpC,IAAA,EAAM;AAAA,GACR;AAAA,EACA,KAAA,EAAO,CAAC,MAAA,KAAW,SAAA,CAAU,MAAA,EAAQ,aAAA,EAAe,CAAC,CAAA,MAAO,EAAE,SAAA,EAAW,CAAA,CAAE,SAAA,EAAU,CAAE;AACzF,CAAA","file":"chunk-3UI7CG24.js","sourcesContent":["import { z, type ZodType } from 'zod';\n\nexport type NovaComponentShape = { name: string; props: ZodType; container?: boolean };\n\nexport const layoutSchema = (manifest: readonly NovaComponentShape[]): ZodType => {\n const [first, ...rest] = manifest;\n if (first === undefined) throw new Error('nova plugin: the manifest is empty');\n\n const recur: ZodType = z.lazy(() => layoutNode);\n const branch = (component: NovaComponentShape) =>\n z.object({\n component: z.literal(component.name),\n props: component.props,\n ...(component.container === true ? { children: z.array(recur) } : {}),\n });\n\n const layoutNode = z.discriminatedUnion('component', [branch(first), ...rest.map(branch)]);\n return layoutNode;\n};\n","import type { LayoutNode } from '@niscorp/nova';\nimport { isRecord } from '@compile';\n\nconst fieldFor = (key: string, value: unknown): LayoutNode => ({\n component: 'loom:field',\n props: { label: key },\n children: [{ component: typeof value === 'string' ? 'loom:text' : 'loom:raw', model: `$.${key}` }],\n});\n\nexport const dataLayout = (value: unknown): LayoutNode => {\n const data = isRecord(value) ? value : {};\n return {\n component: 'Stack',\n props: { direction: 'column', gap: 12 },\n children: Object.keys(data).map((key) => fieldFor(key, data[key])),\n };\n};\n","import type { LayoutNode } from '@niscorp/nova';\n\nexport const PREVIEW = 'nova:preview';\n\nexport const previewLayout: LayoutNode = {\n component: PREVIEW,\n props: { documents: '$.documents' },\n};\n","import type { ActionDefinition } from '@niscorp/nova';\nimport { previewLayout, PREVIEW } from './preview.layout.js';\n\nexport const previewAction: ActionDefinition = {\n id: PREVIEW,\n layout: previewLayout,\n data: { documents: {} },\n};\n","import { mountView, type LoomPlugin } from '@editor';\nimport { layoutSchema, type NovaComponentShape } from './schema.js';\nimport { dataLayout } from './data.layout.js';\nimport { previewAction } from './preview.action.js';\n\nexport { PREVIEW } from './preview.layout.js';\nexport { layoutSchema, type NovaComponentShape } from './schema.js';\n\nexport type NovaPluginConfig = { manifest: readonly NovaComponentShape[] };\n\nexport const novaPlugin = (config: NovaPluginConfig): LoomPlugin => ({\n name: 'nova',\n documents: {\n layout: layoutSchema(config.manifest),\n data: dataLayout,\n },\n mount: (editor) => mountView(editor, previewAction, (e) => ({ documents: e.documents })),\n});\n"]}
@@ -1,4 +1,4 @@
1
- import { mountView } from './chunk-27OMOR7I.js';
1
+ import { mountView } from './chunk-OVTQEAV3.js';
2
2
  import { NodeSchema } from '@niscorp/prism';
3
3
 
4
4
  // src/plugins/prism/preview.layout.ts
@@ -25,5 +25,5 @@ var prismPlugin = (options) => ({
25
25
  });
26
26
 
27
27
  export { NODE, PREVIEW, prismPlugin };
28
- //# sourceMappingURL=chunk-LVDY6FUH.js.map
29
- //# sourceMappingURL=chunk-LVDY6FUH.js.map
28
+ //# sourceMappingURL=chunk-BYOKCNIJ.js.map
29
+ //# sourceMappingURL=chunk-BYOKCNIJ.js.map
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/plugins/prism/preview.layout.ts","../src/plugins/prism/preview.action.ts","../src/plugins/prism/index.ts"],"names":[],"mappings":";;;;AAEO,IAAM,OAAA,GAAU;AAEhB,IAAM,aAAA,GAA4B;AAAA,EACvC,SAAA,EAAW,OAAA;AAAA,EACX,KAAA,EAAO,EAAE,MAAA,EAAQ,UAAA;AACnB,CAAA;;;ACJO,IAAM,aAAA,GAAkC;AAAA,EAC7C,EAAA,EAAI,OAAA;AAAA,EACJ,MAAA,EAAQ,aAAA;AAAA,EACR,IAAA,EAAM,EAAE,MAAA,EAAQ,IAAA;AAClB,CAAA;;;ACEO,IAAM,IAAA,GAAO;AAOb,IAAM,WAAA,GAAc,CAAC,OAAA,MAA6C;AAAA,EACvE,IAAA,EAAM,OAAA;AAAA,EACN,SAAA,EAAW,EAAE,MAAA,EAAQ,OAAA,CAAQ,UAAW,UAAA,EAAuB;AAAA,EAC/D,OAAA,EAAS,CAAC,EAAE,IAAA,EAAM,MAAM,KAAA,EAAO,CAAC,KAAA,KAAU,KAAA,CAAM,IAAA,KAAS,OAAA,IAAW,KAAA,CAAM,IAAA,KAAS,IAAI,CAAA;AAAA,EACvF,KAAA,EAAO,CAAC,MAAA,KACN,SAAA,CAAU,QAAQ,aAAA,EAAe,CAAC,CAAA,MAAO,EAAE,MAAA,EAAS,CAAA,CAAE,SAAA,CAAsC,QAAQ,GAAE,CAAE;AAC5G,CAAA","file":"chunk-LVDY6FUH.js","sourcesContent":["import type { LayoutNode } from '@niscorp/nova';\n\nexport const PREVIEW = 'prism:preview';\n\nexport const previewLayout: LayoutNode = {\n component: PREVIEW,\n props: { config: '$.config' },\n};\n","import type { ActionDefinition } from '@niscorp/nova';\nimport { previewLayout, PREVIEW } from './preview.layout.js';\n\nexport const previewAction: ActionDefinition = {\n id: PREVIEW,\n layout: previewLayout,\n data: { config: null },\n};\n","import type { ZodType } from 'zod';\nimport { NodeSchema, type Config, type JsonObject, type JsonValue } from '@niscorp/prism';\nimport { mountView } from '@editor/view';\nimport type { LoomPlugin } from '@editor/types';\nimport { previewAction } from './preview.action.js';\n\nexport { PREVIEW } from './preview.layout.js';\nexport type { Config, JsonObject, JsonValue };\n\nexport const NODE = 'prism:node';\n\nexport type PrismPluginOptions = {\n input: JsonObject;\n schema?: ZodType;\n};\n\nexport const prismPlugin = (options: PrismPluginOptions): LoomPlugin => ({\n name: 'prism',\n documents: { config: options.schema ?? (NodeSchema as ZodType) },\n widgets: [{ role: NODE, match: (field) => field.kind === 'union' && field.path === '' }],\n mount: (editor) =>\n mountView(editor, previewAction, (e) => ({ config: (e.documents as Record<string, unknown>)['config'] })),\n});\n"]}
1
+ {"version":3,"sources":["../src/plugins/prism/preview.layout.ts","../src/plugins/prism/preview.action.ts","../src/plugins/prism/index.ts"],"names":[],"mappings":";;;;AAEO,IAAM,OAAA,GAAU;AAEhB,IAAM,aAAA,GAA4B;AAAA,EACvC,SAAA,EAAW,OAAA;AAAA,EACX,KAAA,EAAO,EAAE,MAAA,EAAQ,UAAA;AACnB,CAAA;;;ACJO,IAAM,aAAA,GAAkC;AAAA,EAC7C,EAAA,EAAI,OAAA;AAAA,EACJ,MAAA,EAAQ,aAAA;AAAA,EACR,IAAA,EAAM,EAAE,MAAA,EAAQ,IAAA;AAClB,CAAA;;;ACCO,IAAM,IAAA,GAAO;AAOb,IAAM,WAAA,GAAc,CAAC,OAAA,MAA6C;AAAA,EACvE,IAAA,EAAM,OAAA;AAAA,EACN,SAAA,EAAW,EAAE,MAAA,EAAQ,OAAA,CAAQ,UAAW,UAAA,EAAuB;AAAA,EAC/D,OAAA,EAAS,CAAC,EAAE,IAAA,EAAM,MAAM,KAAA,EAAO,CAAC,KAAA,KAAU,KAAA,CAAM,IAAA,KAAS,OAAA,IAAW,KAAA,CAAM,IAAA,KAAS,IAAI,CAAA;AAAA,EACvF,KAAA,EAAO,CAAC,MAAA,KACN,SAAA,CAAU,QAAQ,aAAA,EAAe,CAAC,CAAA,MAAO,EAAE,MAAA,EAAS,CAAA,CAAE,SAAA,CAAsC,QAAQ,GAAE,CAAE;AAC5G,CAAA","file":"chunk-BYOKCNIJ.js","sourcesContent":["import type { LayoutNode } from '@niscorp/nova';\n\nexport const PREVIEW = 'prism:preview';\n\nexport const previewLayout: LayoutNode = {\n component: PREVIEW,\n props: { config: '$.config' },\n};\n","import type { ActionDefinition } from '@niscorp/nova';\nimport { previewLayout, PREVIEW } from './preview.layout.js';\n\nexport const previewAction: ActionDefinition = {\n id: PREVIEW,\n layout: previewLayout,\n data: { config: null },\n};\n","import type { ZodType } from 'zod';\nimport { NodeSchema, type Config, type JsonObject, type JsonValue } from '@niscorp/prism';\nimport { mountView, type LoomPlugin } from '@editor';\nimport { previewAction } from './preview.action.js';\n\nexport { PREVIEW } from './preview.layout.js';\nexport type { Config, JsonObject, JsonValue };\n\nexport const NODE = 'prism:node';\n\nexport type PrismPluginOptions = {\n input: JsonObject;\n schema?: ZodType;\n};\n\nexport const prismPlugin = (options: PrismPluginOptions): LoomPlugin => ({\n name: 'prism',\n documents: { config: options.schema ?? (NodeSchema as ZodType) },\n widgets: [{ role: NODE, match: (field) => field.kind === 'union' && field.path === '' }],\n mount: (editor) =>\n mountView(editor, previewAction, (e) => ({ config: (e.documents as Record<string, unknown>)['config'] })),\n});\n"]}