@niscorp/loom 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 (76) hide show
  1. package/DESIGN.md +253 -0
  2. package/LICENSE +202 -0
  3. package/README.md +101 -0
  4. package/dist/chunk-A3UOFGL4.js +29 -0
  5. package/dist/chunk-A3UOFGL4.js.map +1 -0
  6. package/dist/chunk-D743DI5J.js +17 -0
  7. package/dist/chunk-D743DI5J.js.map +1 -0
  8. package/dist/chunk-DWQWPBBV.js +63 -0
  9. package/dist/chunk-DWQWPBBV.js.map +1 -0
  10. package/dist/chunk-LWY5TG7M.js +208 -0
  11. package/dist/chunk-LWY5TG7M.js.map +1 -0
  12. package/dist/chunk-MIRMQPUE.js +132 -0
  13. package/dist/chunk-MIRMQPUE.js.map +1 -0
  14. package/dist/chunk-PTXRAWJX.js +58 -0
  15. package/dist/chunk-PTXRAWJX.js.map +1 -0
  16. package/dist/chunk-TV4U22MY.js +176 -0
  17. package/dist/chunk-TV4U22MY.js.map +1 -0
  18. package/dist/chunk-X7PCPONB.js +380 -0
  19. package/dist/chunk-X7PCPONB.js.map +1 -0
  20. package/dist/chunk-XTY7XO5C.js +61 -0
  21. package/dist/chunk-XTY7XO5C.js.map +1 -0
  22. package/dist/index.cjs +630 -0
  23. package/dist/index.cjs.map +1 -0
  24. package/dist/index.d.cts +40 -0
  25. package/dist/index.d.ts +40 -0
  26. package/dist/index.js +6 -0
  27. package/dist/index.js.map +1 -0
  28. package/dist/loom-editor-CQ_GI4IA.d.cts +27 -0
  29. package/dist/loom-editor-D5SBQ4_F.d.ts +27 -0
  30. package/dist/plugins/nova/index.cjs +81 -0
  31. package/dist/plugins/nova/index.cjs.map +1 -0
  32. package/dist/plugins/nova/index.d.cts +14 -0
  33. package/dist/plugins/nova/index.d.ts +14 -0
  34. package/dist/plugins/nova/index.js +5 -0
  35. package/dist/plugins/nova/index.js.map +1 -0
  36. package/dist/plugins/nova/react/index.cjs +107 -0
  37. package/dist/plugins/nova/react/index.cjs.map +1 -0
  38. package/dist/plugins/nova/react/index.d.cts +17 -0
  39. package/dist/plugins/nova/react/index.d.ts +17 -0
  40. package/dist/plugins/nova/react/index.js +36 -0
  41. package/dist/plugins/nova/react/index.js.map +1 -0
  42. package/dist/plugins/prism/index.cjs +48 -0
  43. package/dist/plugins/prism/index.cjs.map +1 -0
  44. package/dist/plugins/prism/index.d.cts +18 -0
  45. package/dist/plugins/prism/index.d.ts +18 -0
  46. package/dist/plugins/prism/index.js +4 -0
  47. package/dist/plugins/prism/index.js.map +1 -0
  48. package/dist/plugins/prism/react/index.cjs +744 -0
  49. package/dist/plugins/prism/react/index.cjs.map +1 -0
  50. package/dist/plugins/prism/react/index.d.cts +12 -0
  51. package/dist/plugins/prism/react/index.d.ts +12 -0
  52. package/dist/plugins/prism/react/index.js +419 -0
  53. package/dist/plugins/prism/react/index.js.map +1 -0
  54. package/dist/plugins/vex/index.cjs +67 -0
  55. package/dist/plugins/vex/index.cjs.map +1 -0
  56. package/dist/plugins/vex/index.d.cts +25 -0
  57. package/dist/plugins/vex/index.d.ts +25 -0
  58. package/dist/plugins/vex/index.js +4 -0
  59. package/dist/plugins/vex/index.js.map +1 -0
  60. package/dist/plugins/vex/react/index.cjs +432 -0
  61. package/dist/plugins/vex/react/index.cjs.map +1 -0
  62. package/dist/plugins/vex/react/index.d.cts +13 -0
  63. package/dist/plugins/vex/react/index.d.ts +13 -0
  64. package/dist/plugins/vex/react/index.js +296 -0
  65. package/dist/plugins/vex/react/index.js.map +1 -0
  66. package/dist/react/index.cjs +1076 -0
  67. package/dist/react/index.cjs.map +1 -0
  68. package/dist/react/index.d.cts +82 -0
  69. package/dist/react/index.d.ts +82 -0
  70. package/dist/react/index.js +120 -0
  71. package/dist/react/index.js.map +1 -0
  72. package/dist/schema--OhtatTX.d.cts +10 -0
  73. package/dist/schema--OhtatTX.d.ts +10 -0
  74. package/dist/types-BonjN3CB.d.cts +144 -0
  75. package/dist/types-BonjN3CB.d.ts +144 -0
  76. package/package.json +144 -0
package/DESIGN.md ADDED
@@ -0,0 +1,253 @@
1
+ # Loom — Design
2
+
3
+ This document explains how Loom is built and why. For how to use it, see
4
+ [README.md](./README.md). For Nova itself, see [../nova](../nova); the few Nova
5
+ terms Loom depends on are defined here as they come up.
6
+
7
+ ## What Loom is
8
+
9
+ Loom turns a schema into an editing UI. The input is a [Zod](https://zod.dev)
10
+ schema — every artifact in this stack is defined in Zod, so Loom takes Zod
11
+ directly. The output is a UI, built on Nova, that edits JSON conforming to that
12
+ schema. Point Loom at a different schema and you get a different editor; the
13
+ machinery is the same.
14
+
15
+ It has two parts that can be used separately:
16
+
17
+ - **The compiler** turns a schema into a Nova editor. This is the core.
18
+ - **The editor host** assembles compiled forms, previews, and panes into one
19
+ integrated surface, loaded from plugins.
20
+
21
+ The compiler is the foundation; the host is built on top of it.
22
+
23
+ ## The compiler
24
+
25
+ Compilation is two stages with a data structure between them.
26
+
27
+ ```
28
+ Zod schema ──parse──▶ Field model (IR) ──toNova──▶ { action, layouts }
29
+ ```
30
+
31
+ ### Stage 1: parse — schema to field model
32
+
33
+ `parse` walks a Zod schema and normalizes it into a flat model of `Field` nodes
34
+ (the IR — intermediate representation). Zod has many ways to express the same
35
+ shape; `parse` collapses those into one tagged union so every later stage can
36
+ dispatch on a single `kind`. The kinds are: `string`, `number`, `boolean`,
37
+ `enum`, `object`, `array`, `tuple`, `union`, `self`, and `unknown`.
38
+
39
+ This model is pure data. It knows nothing about Nova. It is *what Loom edits*,
40
+ described independently of how it is rendered.
41
+
42
+ ### Stage 2: toNova — field model to Nova editor
43
+
44
+ `toNova` turns the model into a Nova **editor**, which is two things:
45
+
46
+ - an **action** — Nova's unit of state plus layout. Its `data` is the document
47
+ being edited.
48
+ - the **layouts** it references — Nova layouts are declarative trees of
49
+ components. A simple schema needs only the one inside the action; a recursive
50
+ schema also needs named templates (see [Recursion](#recursion)).
51
+
52
+ Each field becomes a control bound to a path in the document by a *binding
53
+ expression*: `$.name` at the root, `$item` inside an array loop. Binding is how
54
+ Nova connects a control to a slot in the data — when the control changes, Nova
55
+ writes that slot. So editing the form mutates the document in place, and because
56
+ the document was shaped from the schema, it stays valid.
57
+
58
+ `toNova` is the only part of Loom that speaks Nova. Everything Nova-specific
59
+ lives here.
60
+
61
+ ### The field model is the seam
62
+
63
+ The model sits between the two stages on purpose. `parse` depends only on Zod;
64
+ `toNova` depends only on the model and Nova. Neither knows about the other. That
65
+ boundary is where alternatives attach without disturbing the rest: a second
66
+ front end (some other schema language producing a `Field`) would feed `toNova`
67
+ unchanged, and a second back end (rendering the model some other way) would
68
+ consume `parse` unchanged. Today there is one of each, but the split keeps that
69
+ door open and keeps each half small.
70
+
71
+ ### Roles: the widget vocabulary
72
+
73
+ `toNova` does not emit concrete components. It emits **roles** — abstract names
74
+ like `loom:text`, `loom:select`, `loom:array`, `loom:variant`. A *kit* registers
75
+ a real component under each role. Swapping the kit re-skins every compiled
76
+ editor without touching the compiler.
77
+
78
+ The vocabulary is deliberately small and stable
79
+ ([roles.ts](./src/compile/roles.ts)): layout primitives (`box`, `group`,
80
+ `array`, `array-item`, `variant`, `branch`), a field wrapper (`field` — label,
81
+ description, error, required marker), controls (`text`, `number`, `checkbox`,
82
+ `select`, `raw`), and list actions (`append`, `row-menu`). Structural shapes
83
+ (objects, arrays, unions) are *compositions* of these roles, not roles of their
84
+ own. New variations ride as props rather than new roles.
85
+
86
+ ### Editing is model writes only
87
+
88
+ Every edit — including adding, removing, and reordering list items — is a write
89
+ to the bound data through Nova's standard binding pipeline. Loom emits no Nova
90
+ action triggers and no behavior-bearing buttons.
91
+
92
+ - `append` writes a default element onto the array it binds.
93
+ - `row-menu` (move, remove, and wrap/unwrap for recursive lists) reads `$items`
94
+ — the whole array — and `$index`, and writes back the new array.
95
+
96
+ Both work at any nesting depth, because the bound path is resolved by Nova per
97
+ render rather than baked in at compile time. Keeping editing to data writes is
98
+ what lets the same compiled layout drive a list of any length and a tree of any
99
+ depth.
100
+
101
+ ### Unions: discrimination happens in JS
102
+
103
+ A union (a value that can be one of several shapes) compiles to one chooser plus
104
+ the editors for each branch. Which branch is active is **not** encoded in the
105
+ layout. Instead, `parse` records a `Pattern` for each branch — the one fact that
106
+ recognizes it in a value:
107
+
108
+ - `tag` — a shared field equals a literal (`z.discriminatedUnion`).
109
+ - `key` — a field unique to this branch is present (a structural union).
110
+ - `type` — the value's own JS type is unique to this branch, e.g. a string or
111
+ array among objects (a mixed union).
112
+ - `fallback` — the single catch-all branch, selected only when nothing else
113
+ matches (e.g. an unconstrained object among tagged operations).
114
+
115
+ At render, the variant widget matches the current value against these patterns
116
+ in plain JS and shows the branch that fits; choosing a different branch writes
117
+ that branch's defaults into the document. Tagged, structural, and mixed unions
118
+ are one code path, and no union-specific concept leaks into Nova.
119
+
120
+ ### Recursion
121
+
122
+ Several schemas in this stack are recursive — a Nova layout nests layouts, a
123
+ filter nests filters. A schema like that is infinitely deep, but a document is
124
+ not, so Loom follows the document, not the schema.
125
+
126
+ `parse` stops when it re-enters a type it is already inside and marks the
127
+ back-edge with a `self` node, yielding a finite model from an infinite schema.
128
+ `toNova` emits the recursive shape once as a named layout template authored
129
+ against `$item`; the `self` reference points back to that template, and Nova
130
+ resolves it per render against the live data. The form is therefore exactly as
131
+ deep as the document, and growing or shrinking it is an ordinary list write.
132
+
133
+ ### Custom widgets
134
+
135
+ A plugin can replace a field's default control with its own — a Vex field-path
136
+ picker, a Prism node editor. A widget is a matcher plus a component: the matcher
137
+ (`{ role, match }`) tests a field by where it sits (its `kind` and dot-path
138
+ within its scope), the compiler applies the first match and emits that field
139
+ under the given role, and the kit supplies the component for that role. Matching
140
+ is structural and resolved at compile time. Because a recursive template
141
+ restarts the path, matchers target by suffix and stay depth-agnostic. The
142
+ component, and any data it needs, lives in the React layer — the compiler only
143
+ records which role a field uses.
144
+
145
+ ### Validation
146
+
147
+ Loom validates with the same schema it compiled from — there is no second source
148
+ of truth. `attachValidation` runs the schema's `safeParse` (refinements and all)
149
+ over the live document and writes any problems into a reserved `_errors` slot in
150
+ the data; each field binds its own error slot, so messages show inline. The
151
+ `_errors` slot is stripped from the document Loom reports out.
152
+
153
+ ## The editor host
154
+
155
+ `createLoomEditor` is the controller behind the integrated surface. Like the
156
+ compiler, it is framework-free.
157
+
158
+ It owns one Nova **shell** — Nova's container for multiple **canvases** (render
159
+ targets), each holding an action — built empty. Everything visible is
160
+ contributed by plugins. The flow:
161
+
162
+ - `loadPlugin(plugin)` registers a plugin and calls its `mount(editor)` hook,
163
+ handing it the live editor. Through `mount` a plugin can add canvases, register
164
+ actions, arrange the canvas layout, or load further plugins.
165
+ - `open(artifact)` selects the plugin named by `artifact.type` and compiles its
166
+ documents into form canvases. The controller then publishes the live document
167
+ values (`editor.documents`) and validation problems (`editor.validations`), and
168
+ emits `change` / `open` events.
169
+
170
+ ### Documents
171
+
172
+ A plugin declares one or more named **documents** — the things to edit. A
173
+ document is usually a Zod schema, which the controller compiles with `toNova`. It
174
+ can instead be a function `(value) => layout` for a freeform document that has no
175
+ fixed schema (the Nova plugin's `data`, whose shape depends on which bindings the
176
+ layout uses); the plugin builds the layout itself, and the controller still seeds
177
+ and tracks the value.
178
+
179
+ A schema whose root is not an object (a union, a scalar, a bare array) compiles
180
+ to a single control, which has no document root to bind to. The controller wraps
181
+ such a document under an internal key so its control has a real path, and unwraps
182
+ it before publishing — so the wrapping never reaches a plugin or a consumer.
183
+
184
+ ### Plugins
185
+
186
+ A plugin's core descriptor is small:
187
+
188
+ ```ts
189
+ type LoomPlugin = {
190
+ name: string;
191
+ documents: Record<string, Document>; // schema (compiled) or freeform layout
192
+ widgets?: WidgetBinding[]; // { role, match } — custom field widgets
193
+ mount?: (editor: LoomEditor) => void; // lifecycle hook over the live shell
194
+ };
195
+ ```
196
+
197
+ The render components — previews, widget components, view panes — are not part
198
+ of this core. They live in the plugin's React surface and are registered with the
199
+ kit by role. A plugin therefore splits the same way the package does: a
200
+ framework-free core (`@niscorp/loom/plugins/vex`) and a React surface
201
+ (`@niscorp/loom/plugins/vex/react`) that adds the components.
202
+
203
+ The default Data and Validations JSON panes are themselves plugins. The host
204
+ holds no domain knowledge; it loads what it is given, in order, last load wins.
205
+
206
+ ### The React surface
207
+
208
+ `<LoomEditor>` builds a component registry from the loaded plugins' components,
209
+ creates the controller against it, loads the plugins, opens the artifact, and
210
+ renders the shell with `<NovaShell>`. The controller produces the structure and
211
+ drives the shell; React only mounts it and supplies components. A Vue surface
212
+ later would be the same controller with a Vue kit.
213
+
214
+ ## Locked decisions
215
+
216
+ These are settled, with the reason each is held.
217
+
218
+ 1. **Built on Nova, deliberately.** The only intentionally non-Nova code is the
219
+ thin React mount and the components a plugin registers. All structure — forms,
220
+ panes, the canvas layout — is Nova. Loom is how we find where Nova needs to
221
+ grow: when Nova cannot express something, the fix is to grow Nova or drop a
222
+ plugin widget in at the marked seam, not to route around Nova.
223
+
224
+ 2. **Zod is the only input.** Loom reads types, formats, optionality, and labels
225
+ straight off the Zod schema, with no intermediate JSON Schema layer. The same
226
+ schema is the validation truth. We do not add another input format until
227
+ something concrete needs it.
228
+
229
+ 3. **Headless core, framework surface.** `parse`, `toNova`, and
230
+ `createLoomEditor` are Nova-only and produce data and a driven shell;
231
+ `@niscorp/loom/react` mounts the result and supplies the kit. The same split
232
+ applies to each plugin. This keeps the logic testable without a UI framework
233
+ and leaves room for other surfaces.
234
+
235
+ 4. **Editing is model writes only.** No action triggers, no behavior-bearing
236
+ buttons; add, remove, and reorder are data writes through Nova's binding
237
+ pipeline (see above). This is what makes arrays and recursion work uniformly
238
+ at any depth.
239
+
240
+ 5. **Unions and recursion are solved by reading the data, not the schema.** The
241
+ document decides which union branch shows and how deep the form goes; the
242
+ schema only says what is addable and what the options are.
243
+
244
+ ## Kept open (not built)
245
+
246
+ - **AI plugin (Cortex).** An optional plugin: a Cortex agent whose output schema
247
+ *is* the schema being edited (or a JSON-Patch over it), so it cannot emit an
248
+ invalid artifact, proposing a reviewable diff. Everything is JSON and schemas,
249
+ so it slots in later without reshaping the core.
250
+ - **Editable raw view.** A synced, editable raw-JSON view beside the visual
251
+ editor. Today the JSON panes are read-only.
252
+ - **Loom Studio.** A layer above the single-artifact editor for working on many
253
+ artifacts at once.
package/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
package/README.md ADDED
@@ -0,0 +1,101 @@
1
+ # @niscorp/loom
2
+
3
+ Loom builds editing UIs from schemas. Give it a [Zod](https://zod.dev) schema
4
+ and it produces a form that views, creates, and edits JSON matching that schema.
5
+ The form is built from the schema's structure — nested objects become nested
6
+ sections, arrays get add and remove controls, unions become a type picker plus
7
+ the fields for the chosen type — so editing the form always produces valid data.
8
+ There is no hand-written form code and no raw text box.
9
+
10
+ The forms render on [Nova](../nova), this stack's layout engine. Loom compiles a
11
+ schema into a Nova layout; Nova draws it and routes each edit back into the data.
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ pnpm add @niscorp/loom @niscorp/nova zod
17
+ ```
18
+
19
+ `@niscorp/nova` is required. The React surface (`@niscorp/loom/react`) also needs
20
+ `react`. Domain plugins each need their own library — `@niscorp/vex` for the Vex
21
+ plugin, `@niscorp/prism` for the Prism plugin. All three are optional: a consumer
22
+ that only uses the compiler installs none of them.
23
+
24
+ ## Two ways to use Loom
25
+
26
+ ### The compiler — turn a schema into a Nova editor
27
+
28
+ `parse` reads a schema into a field model. `toNova` turns that model into a Nova
29
+ editor: an action that holds the data being edited, plus the layouts that render
30
+ it.
31
+
32
+ ```ts
33
+ import { parse, toNova } from '@niscorp/loom';
34
+ import { z } from 'zod';
35
+
36
+ const schema = z.object({
37
+ name: z.string(),
38
+ age: z.number().int(),
39
+ tags: z.array(z.string()),
40
+ });
41
+
42
+ const { action, layouts } = toNova(parse(schema));
43
+ // `action.data` is the document being edited; hand `action` and `layouts`
44
+ // to a Nova runtime to render the form. Every edit writes `action.data`
45
+ // in place, and the data stays valid against `schema`.
46
+ ```
47
+
48
+ This half is headless — no React, no DOM. Use it when you have your own Nova host
49
+ or only need the compiled output.
50
+
51
+ ### The editor — a ready-made React surface
52
+
53
+ `<LoomEditor>` is the integrated surface. It loads a set of plugins, compiles
54
+ each plugin's schemas into forms, and renders everything as one Nova shell: the
55
+ forms on the left, a live preview and JSON panes alongside.
56
+
57
+ ```tsx
58
+ import { LoomEditor, defaultPlugins } from '@niscorp/loom/react';
59
+ import { prism } from '@niscorp/loom/plugins/prism/react';
60
+
61
+ <LoomEditor
62
+ plugins={[...defaultPlugins(), prism({ input })]}
63
+ artifact={{ type: 'prism', documents: { config } }}
64
+ onChange={(documents) => console.log(documents)}
65
+ />;
66
+ ```
67
+
68
+ - `plugins` is the loaded set. They load in order, and a later plugin can
69
+ override or remove an earlier one. `defaultPlugins()` adds the Data and
70
+ Validations JSON panes — spread it **first** so domain plugins load after it.
71
+ - `artifact` says what to edit. `type` names the plugin that handles it;
72
+ `documents` seeds the starting values (omit it to start from the schema's
73
+ defaults).
74
+ - `onChange` fires with the live document values on every edit.
75
+ - To switch to a different artifact, give the element a new React `key`.
76
+
77
+ A **plugin** wires one domain into the editor. It contributes the schemas to edit
78
+ (its *documents*), optional custom field widgets, and usually a preview. The two
79
+ reference plugins:
80
+
81
+ - `prism({ input })` — edit a [Prism](../prism) transform config; the preview
82
+ applies it to `input` and shows the output.
83
+ - `vex({ run, db })` — edit a [Vex](../vex) query; the preview runs it with `run`
84
+ and shows the rows. Pass `db` to get column-aware field pickers.
85
+
86
+ ## Entry points
87
+
88
+ | Import | What it gives you |
89
+ |---|---|
90
+ | `@niscorp/loom` | The compiler (`parse`, `toNova`), the editor controller (`createLoomEditor`), and the types. Headless. |
91
+ | `@niscorp/loom/react` | `<LoomEditor>`, `defaultPlugins()`, and the widget kit. |
92
+ | `@niscorp/loom/plugins/{vex,nova,prism}` | A domain plugin's framework-free core. |
93
+ | `@niscorp/loom/plugins/{vex,nova,prism}/react` | A domain plugin's React surface (preview and widget components). |
94
+
95
+ ## Documentation
96
+
97
+ - [DESIGN.md](./DESIGN.md) — how Loom is built and why. Read it before the source.
98
+
99
+ ## License
100
+
101
+ MIT
@@ -0,0 +1,29 @@
1
+ import { mountView } from './chunk-D743DI5J.js';
2
+ import { NodeSchema } from '@niscorp/prism';
3
+
4
+ // src/plugins/prism/preview.layout.ts
5
+ var PREVIEW = "prism:preview";
6
+ var previewLayout = {
7
+ component: PREVIEW,
8
+ props: { config: "$.config" }
9
+ };
10
+
11
+ // src/plugins/prism/preview.action.ts
12
+ var previewAction = {
13
+ id: PREVIEW,
14
+ layout: previewLayout,
15
+ data: { config: null }
16
+ };
17
+
18
+ // src/plugins/prism/index.ts
19
+ var NODE = "prism:node";
20
+ var prismPlugin = (options) => ({
21
+ name: "prism",
22
+ documents: { config: options.schema ?? NodeSchema },
23
+ widgets: [{ role: NODE, match: (field) => field.kind === "union" && field.path === "" }],
24
+ mount: (editor) => mountView(editor, previewAction, (e) => ({ config: e.documents["config"] }))
25
+ });
26
+
27
+ export { NODE, PREVIEW, prismPlugin };
28
+ //# sourceMappingURL=chunk-A3UOFGL4.js.map
29
+ //# sourceMappingURL=chunk-A3UOFGL4.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/plugins/prism/preview.layout.ts","../src/plugins/prism/preview.action.ts","../src/plugins/prism/index.ts"],"names":[],"mappings":";;;;AAKO,IAAM,OAAA,GAAU;AAIhB,IAAM,aAAA,GAA4B;AAAA,EACvC,SAAA,EAAW,OAAA;AAAA,EACX,KAAA,EAAO,EAAE,MAAA,EAAQ,UAAA;AACnB,CAAA;;;ACPO,IAAM,aAAA,GAAkC;AAAA,EAC7C,EAAA,EAAI,OAAA;AAAA,EACJ,MAAA,EAAQ,aAAA;AAAA,EACR,IAAA,EAAM,EAAE,MAAA,EAAQ,IAAA;AAClB,CAAA;;;ACiBO,IAAM,IAAA,GAAO;AASb,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-A3UOFGL4.js","sourcesContent":["import type { LayoutNode } from '@niscorp/nova';\n\n// The preview view's id, one string for one view: the component name, the action\n// id, and the canvas id. The framework surface registers the component under it;\n// the core's mount references it.\nexport const PREVIEW = 'prism:preview';\n\n// The preview layout: one component bound to the live `config` document. The\n// component applies the config to a sample input and shows the output.\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\n// The preview canvas's action: the preview layout over a `config` slot the mount\n// keeps in sync with the live config document. Canvas id equals the action id.\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\n// @niscorp/loom/plugins/prism — the Prism plugin (framework-free).\n//\n// Loom edits one document, a Prism config (a recursive union of transform\n// operations). The plugin declares it and contributes a preview canvas that\n// applies the config to a sample input and shows the output. The per-framework\n// surface (./react) supplies the preview component; this core supplies the\n// schema and the mount.\n//\n// The edited schema is Prism's `NodeSchema`, not `ConfigSchema`. The two are\n// equivalent (`ConfigSchema = NodeSchema.describe(...)`), but `NodeSchema` is the\n// stable lazy the recursive fields point back to, so it compiles to a single\n// recursive union instead of unrolling one redundant level.\n\nexport { PREVIEW } from './preview.layout.js';\nexport type { Config, JsonObject, JsonValue };\n\n// The role the recursive node editor renders under. The match is framework-free\n// (it lives here); the React surface supplies the component. It claims the\n// document root: the whole config is one Prism node, edited by one recursive\n// widget rather than Loom's static field compilation.\nexport const NODE = 'prism:node';\n\nexport type PrismPluginOptions = {\n /** Sample source data the edited config is applied to in the preview. */\n input: JsonObject;\n /** Override the edited schema; defaults to Prism's `NodeSchema`. */\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"]}
@@ -0,0 +1,17 @@
1
+ // src/editor/view.ts
2
+ var mountView = (editor, action, read) => {
3
+ const { shell } = editor;
4
+ shell.registerAction(action);
5
+ shell.addCanvas({ id: action.id, initial: action.id });
6
+ const instance = shell.getCanvasState(action.id).active?.id;
7
+ if (instance === void 0) return;
8
+ const sync = () => {
9
+ shell.getRuntime(instance)?.setData(read(editor));
10
+ };
11
+ editor.on("change", sync);
12
+ sync();
13
+ };
14
+
15
+ export { mountView };
16
+ //# sourceMappingURL=chunk-D743DI5J.js.map
17
+ //# sourceMappingURL=chunk-D743DI5J.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/editor/view.ts"],"names":[],"mappings":";AAQO,IAAM,SAAA,GAAY,CACvB,MAAA,EACA,MAAA,EACA,IAAA,KACS;AACT,EAAA,MAAM,EAAE,OAAM,GAAI,MAAA;AAClB,EAAA,KAAA,CAAM,eAAe,MAAM,CAAA;AAC3B,EAAA,KAAA,CAAM,SAAA,CAAU,EAAE,EAAA,EAAI,MAAA,CAAO,IAAI,OAAA,EAAS,MAAA,CAAO,IAAI,CAAA;AACrD,EAAA,MAAM,WAAW,KAAA,CAAM,cAAA,CAAe,MAAA,CAAO,EAAE,EAAE,MAAA,EAAQ,EAAA;AACzD,EAAA,IAAI,aAAa,MAAA,EAAW;AAC5B,EAAA,MAAM,OAAO,MAAY;AACvB,IAAA,KAAA,CAAM,WAAW,QAAQ,CAAA,EAAG,OAAA,CAAQ,IAAA,CAAK,MAAM,CAAC,CAAA;AAAA,EAClD,CAAA;AACA,EAAA,MAAA,CAAO,EAAA,CAAG,UAAU,IAAI,CAAA;AACxB,EAAA,IAAA,EAAK;AACP","file":"chunk-D743DI5J.js","sourcesContent":["import type { ActionDefinition } from '@niscorp/nova';\nimport type { LoomEditor } from './types.js';\n\n// Mount a view canvas: register `action`, add a canvas that renders it, and keep\n// its data in sync with the editor's live state — `read(editor)` is pushed onto\n// the canvas on every `change`. The canvas id is the action id. Used by the\n// default plugins (jsonviewer, validation) and any domain preview; the contributor\n// owns the canvas, so a later plugin can `shell.removeCanvas(action.id)` to drop it.\nexport const mountView = (\n editor: LoomEditor,\n action: ActionDefinition,\n read: (editor: LoomEditor) => Record<string, unknown>,\n): void => {\n const { shell } = editor;\n shell.registerAction(action);\n shell.addCanvas({ id: action.id, initial: action.id });\n const instance = shell.getCanvasState(action.id).active?.id;\n if (instance === undefined) return;\n const sync = (): void => {\n shell.getRuntime(instance)?.setData(read(editor));\n };\n editor.on('change', sync);\n sync();\n};\n"]}