simpler-forms 0.1.0-alpha.1 → 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 (86) hide show
  1. package/README.md +221 -76
  2. package/dist/src/casing.d.ts +43 -0
  3. package/dist/src/casing.js +146 -0
  4. package/dist/src/casing.js.map +1 -0
  5. package/dist/src/decorators/index.d.ts +1 -0
  6. package/dist/src/decorators/index.js +1 -0
  7. package/dist/src/decorators/index.js.map +1 -1
  8. package/dist/src/decorators/mapping.d.ts +11 -0
  9. package/dist/src/decorators/mapping.js +22 -0
  10. package/dist/src/decorators/mapping.js.map +1 -0
  11. package/dist/src/decorators/meta.d.ts +13 -3
  12. package/dist/src/decorators/meta.js +31 -4
  13. package/dist/src/decorators/meta.js.map +1 -1
  14. package/dist/src/decorators/ui.d.ts +14 -12
  15. package/dist/src/decorators/ui.js +20 -43
  16. package/dist/src/decorators/ui.js.map +1 -1
  17. package/dist/src/emitter.d.ts +8 -0
  18. package/dist/src/emitter.js +48 -13
  19. package/dist/src/emitter.js.map +1 -1
  20. package/dist/src/emitters/block-ui.d.ts +14 -3
  21. package/dist/src/emitters/block-ui.js +81 -119
  22. package/dist/src/emitters/block-ui.js.map +1 -1
  23. package/dist/src/emitters/layout-ui.d.ts +12 -0
  24. package/dist/src/emitters/layout-ui.js +225 -0
  25. package/dist/src/emitters/layout-ui.js.map +1 -0
  26. package/dist/src/emitters/overlay.d.ts +3 -6
  27. package/dist/src/emitters/overlay.js +3 -86
  28. package/dist/src/emitters/overlay.js.map +1 -1
  29. package/dist/src/forms.d.ts +23 -0
  30. package/dist/src/forms.js +54 -0
  31. package/dist/src/forms.js.map +1 -0
  32. package/dist/src/index.d.ts +15 -6
  33. package/dist/src/index.js +12 -3
  34. package/dist/src/index.js.map +1 -1
  35. package/dist/src/layout.d.ts +50 -0
  36. package/dist/src/layout.js +397 -0
  37. package/dist/src/layout.js.map +1 -0
  38. package/dist/src/lib.d.ts +485 -39
  39. package/dist/src/lib.js +215 -15
  40. package/dist/src/lib.js.map +1 -1
  41. package/dist/src/linter.js +2 -41
  42. package/dist/src/linter.js.map +1 -1
  43. package/dist/src/mapping-from.d.ts +20 -0
  44. package/dist/src/mapping-from.js +149 -0
  45. package/dist/src/mapping-from.js.map +1 -0
  46. package/dist/src/mapping.d.ts +58 -0
  47. package/dist/src/mapping.js +209 -0
  48. package/dist/src/mapping.js.map +1 -0
  49. package/dist/src/model.d.ts +69 -17
  50. package/dist/src/model.js +65 -19
  51. package/dist/src/model.js.map +1 -1
  52. package/dist/src/public.d.ts +20 -4
  53. package/dist/src/public.js +28 -4
  54. package/dist/src/public.js.map +1 -1
  55. package/dist/src/validate.d.ts +2 -1
  56. package/dist/src/validate.js +180 -58
  57. package/dist/src/validate.js.map +1 -1
  58. package/lib/main.tsp +1 -0
  59. package/lib/mapping.tsp +71 -0
  60. package/lib/meta.tsp +23 -4
  61. package/lib/types.tsp +13 -65
  62. package/lib/ui.tsp +34 -17
  63. package/package.json +7 -1
  64. package/src/casing.ts +172 -0
  65. package/src/decorators/index.ts +1 -0
  66. package/src/decorators/mapping.ts +57 -0
  67. package/src/decorators/meta.ts +50 -11
  68. package/src/decorators/ui.ts +43 -59
  69. package/src/emitter.ts +59 -13
  70. package/src/emitters/block-ui.ts +83 -135
  71. package/src/emitters/layout-ui.ts +280 -0
  72. package/src/emitters/overlay.ts +3 -103
  73. package/src/forms.ts +82 -0
  74. package/src/index.ts +12 -3
  75. package/src/layout.ts +592 -0
  76. package/src/lib.ts +221 -15
  77. package/src/linter.ts +1 -42
  78. package/src/mapping-from.ts +193 -0
  79. package/src/mapping.ts +351 -0
  80. package/src/model.ts +170 -37
  81. package/src/public.ts +50 -6
  82. package/src/validate.ts +188 -59
  83. package/dist/src/emitters/override-condition.d.ts +0 -12
  84. package/dist/src/emitters/override-condition.js +0 -25
  85. package/dist/src/emitters/override-condition.js.map +0 -1
  86. package/src/emitters/override-condition.ts +0 -37
package/src/emitter.ts CHANGED
@@ -11,11 +11,15 @@ import {
11
11
  getId,
12
12
  } from "@typespec/json-schema";
13
13
  import { allBlocks, type Block } from "./model.js";
14
+ import { type PublishedForm, resolveForms } from "./forms.js";
14
15
  import { reportDiagnostic } from "./lib.js";
15
16
  import { blockSchemaRef } from "./decorators/index.js";
16
17
  import { emitModelOverlay, emitSchemaOverlay } from "./emitters/overlay.js";
17
18
  import { emitBlockUi } from "./emitters/block-ui.js";
19
+ import { emitLayoutUi } from "./emitters/layout-ui.js";
20
+ import { resolveLayout } from "./layout.js";
18
21
  import { emitBlockIndex } from "./emitters/block-index.js";
22
+ import { Casing, type PropertyCasing } from "./casing.js";
19
23
 
20
24
  export interface FormSpecOptions {
21
25
  /**
@@ -24,6 +28,13 @@ export interface FormSpecOptions {
24
28
  * its `@Meta.question.id`, not its URI.
25
29
  */
26
30
  "base-uri"?: string;
31
+ /**
32
+ * How a property's TypeSpec name is written in every artifact: `preserve` (the default)
33
+ * keeps it, `snake` converts `firstName` to `first_name`. String paths in decorators are
34
+ * still written in TypeSpec names, and `@encodedName("application/json", ...)` overrides
35
+ * the casing for one property.
36
+ */
37
+ "property-casing"?: PropertyCasing;
27
38
  }
28
39
 
29
40
  const STAGING = ".json-schema";
@@ -60,6 +71,9 @@ export async function $onEmit(
60
71
  byFile.set(name, doc);
61
72
  if (doc.$id) byId.set(doc.$id, doc);
62
73
  }
74
+ // The staged schemas are an intermediate in TypeSpec names, not an artifact, so they must
75
+ // not be left beside the published ones.
76
+ await program.host.rm(stagingDir, { recursive: true });
63
77
 
64
78
  const baseUri = context.options?.["base-uri"];
65
79
  const write = (rel: string, value: unknown) =>
@@ -68,7 +82,13 @@ export async function $onEmit(
68
82
  content: JSON.stringify(value, null, 2) + "\n",
69
83
  });
70
84
 
85
+ const casing = new Casing(
86
+ program,
87
+ context.options?.["property-casing"] ?? "preserve",
88
+ );
89
+
71
90
  const blocks = allBlocks(program);
91
+ const { forms } = resolveForms(program);
72
92
  const modelsByName = indexModels(program.getGlobalNamespaceType());
73
93
  const refToDir = new Map(
74
94
  blocks.map((b) => [
@@ -78,6 +98,9 @@ export async function $onEmit(
78
98
  );
79
99
 
80
100
  for (const block of blocks) {
101
+ // A form that cannot be published, such as one with two layouts, writes nothing.
102
+ const form = forms.find((f) => f.model === block.model);
103
+ if (block.kind === "form" && !form) continue;
81
104
  const dir = refToDir.get(blockSchemaRef(block.id))!;
82
105
  const stock = byId.get(resolvedSchemaId(program, block));
83
106
  if (!stock) {
@@ -110,24 +133,43 @@ export async function $onEmit(
110
133
  const overlay = emitSchemaOverlay(program, block);
111
134
  if (overlay) schema = mergeSchema(schema, overlay);
112
135
 
113
- await write(`${dir}/schema.json`, schema);
114
- await write(`${dir}/ui.json`, emitBlockUi(program, block));
115
- await write(`${dir}/index.json`, emitBlockIndex(program, block));
136
+ const index = emitBlockIndex(program, block);
137
+ if (Array.isArray(index.fieldOccurrences))
138
+ index.fieldOccurrences = index.fieldOccurrences
139
+ .map((entry) => ({ ...entry, path: casing.pointer(entry.path) }))
140
+ .sort((a, b) => a.path.localeCompare(b.path));
116
141
 
117
- if (block.kind === "form") {
118
- await write(`${dir}/manifest.json`, {
119
- contract: "resolved-form-package/v1",
120
- form: block.meta,
121
- artifacts: {
122
- "schema.json": "generated",
123
- "ui.json": "generated",
124
- "index.json": "generated",
125
- },
126
- });
142
+ if (block.kind === "question") {
143
+ await write(`${dir}/schema.json`, casing.json(schema));
144
+ await write(`${dir}/ui.json`, casing.json(emitBlockUi(program, block)));
145
+ await write(`${dir}/index.json`, index);
146
+ continue;
127
147
  }
148
+
149
+ // A form's title is its own, in its manifest; its schema carries none.
150
+ const { title: _title, ...formSchema } = schema;
151
+ await write(`${dir}/schema.json`, casing.json(formSchema));
152
+ await write(`${dir}/ui.json`, casing.json(formUi(program, form!)));
153
+ await write(`${dir}/index.json`, index);
154
+ await write(`${dir}/manifest.json`, {
155
+ contract: "resolved-form-package/v1",
156
+ form: form!.meta,
157
+ artifacts: {
158
+ "schema.json": "generated",
159
+ "ui.json": "generated",
160
+ "index.json": "generated",
161
+ },
162
+ });
128
163
  }
129
164
  }
130
165
 
166
+ /** A form's UI: its layout's, or its own fields' presentation. */
167
+ function formUi(program: Program, form: PublishedForm) {
168
+ return form.layout
169
+ ? emitLayoutUi(program, resolveLayout(program, form.layout, form.model)).ui
170
+ : emitBlockUi(program, form.block);
171
+ }
172
+
131
173
  /**
132
174
  * The `$id` the stock emitter actually wrote for a block.
133
175
  *
@@ -247,6 +289,10 @@ function mergeSchema(a: Json, b: Json): Json {
247
289
  for (const [key, value] of Object.entries(b)) {
248
290
  if (key === "allOf" && Array.isArray(out.allOf)) {
249
291
  out.allOf = [...out.allOf, ...value];
292
+ } else if (key === "required" && Array.isArray(out.required)) {
293
+ // Requiredness only adds: a model-level @Validation.requiredPaths keeps what the model
294
+ // already requires.
295
+ out.required = [...new Set([...out.required, ...value])];
250
296
  } else if (
251
297
  key === "properties" &&
252
298
  isObject(out.properties) &&
@@ -7,19 +7,16 @@ import {
7
7
  childBlock,
8
8
  modelLabel,
9
9
  modelOrder,
10
- modelOverrides,
11
10
  modelProperties,
12
11
  propEnabledWhen,
13
12
  propLabel,
14
13
  propOmit,
15
14
  propReadOnly,
16
15
  propReadOnlyWhen,
17
- propSection,
18
16
  propVisibleWhen,
19
17
  propWidget,
20
18
  readBlock,
21
19
  } from "../model.js";
22
- import { normalizedOverrideEnabledWhen } from "./override-condition.js";
23
20
 
24
21
  /** An answered value: not null, not blank, not an empty list. */
25
22
  const answeredSchema = {
@@ -54,7 +51,9 @@ const rootConditionSchema = (
54
51
  return schema;
55
52
  };
56
53
 
57
- const jsonFormsCondition = (condition: Condition): Record<string, unknown> =>
54
+ export const jsonFormsCondition = (
55
+ condition: Condition,
56
+ ): Record<string, unknown> =>
58
57
  condition.operator === "any"
59
58
  ? {
60
59
  scope: "#",
@@ -79,56 +78,6 @@ export interface UiNode {
79
78
  rule?: Record<string, unknown>;
80
79
  }
81
80
 
82
- type Overrides = Record<string, Record<string, unknown>>;
83
-
84
- /** Convert a canonical JSON Forms scope into the dotted path addressed by @UI.overrides. */
85
- const dataPathFromScope = (scope: string): string | undefined => {
86
- if (!scope.startsWith("#/properties/")) return undefined;
87
- const tokens = scope.slice(2).split("/");
88
- const path: string[] = [];
89
- for (let index = 0; index < tokens.length;) {
90
- if (tokens[index] !== "properties" || !tokens[index + 1]) return undefined;
91
- path.push(tokens[index + 1]);
92
- index += 2;
93
- if (tokens[index] === "items") index += 1;
94
- }
95
- return path.join(".");
96
- };
97
-
98
- /** Emit the portable JSON Forms equivalent of a form-scoped enabledWhen override. */
99
- const overrideEnabledRule = (
100
- override: Record<string, unknown>,
101
- ): Record<string, unknown> | undefined => {
102
- const condition = normalizedOverrideEnabledWhen(override);
103
- if (!condition) return undefined;
104
- const scope = `#/${condition.sourcePath.map((step) => `properties/${step}`).join("/")}`;
105
- const schema =
106
- condition.operator === "in"
107
- ? { enum: condition.values }
108
- : { const: condition.value };
109
- return { effect: "ENABLE", condition: { scope, schema } };
110
- };
111
-
112
- /** Apply occurrence-specific behavior after recursively composing canonical child UI trees. */
113
- const applyOverrides = (node: UiNode, overrides: Overrides): UiNode => {
114
- const out: UiNode = { ...node };
115
- if (typeof node.scope === "string") {
116
- const path = dataPathFromScope(node.scope);
117
- const rule = path ? overrideEnabledRule(overrides[path] ?? {}) : undefined;
118
- if (rule && node.rule) {
119
- throw new Error(
120
- `@UI.overrides enabledWhen collides with intrinsic UI behavior at ${path}`,
121
- );
122
- }
123
- if (rule) out.rule = rule;
124
- }
125
- if (node.elements)
126
- out.elements = node.elements.map((child) =>
127
- applyOverrides(child, overrides),
128
- );
129
- return out;
130
- };
131
-
132
81
  /** Re-prefix every Control scope so a child's tree sits under `propName`. */
133
82
  export function rescopeUi(node: UiNode, propName: string): UiNode {
134
83
  const out: UiNode = { ...node };
@@ -187,19 +136,15 @@ function layoutProps(program: Program, model: Model): ModelProperty[] {
187
136
  }
188
137
 
189
138
  /** What laying out a model needs, which a block has and a form-local model can supply. */
190
- type LayoutSource = Pick<
191
- Block,
192
- "model" | "scalar" | "label" | "doc" | "sections" | "overrides"
193
- >;
139
+ type LayoutSource = Pick<Block, "model" | "scalar" | "label" | "doc">;
194
140
 
195
141
  /** A model laid out as a block would be, whether or not it is one. */
196
- const layoutSource = (program: Program, model: Model): LayoutSource =>
142
+ export const layoutSource = (program: Program, model: Model): LayoutSource =>
197
143
  readBlock(program, model) ?? {
198
144
  model,
199
145
  scalar: false,
200
146
  label: modelLabel(program, model),
201
147
  doc: getDoc(program, model),
202
- overrides: modelOverrides(program, model),
203
148
  };
204
149
 
205
150
  /**
@@ -219,104 +164,107 @@ function itemDetail(program: Program, prop: ModelProperty): UiNode | undefined {
219
164
  return emitBlockUi(program, layoutSource(program, item));
220
165
  }
221
166
 
167
+ /** The model a property's fields lay out from: a composed question, or a model of the form's own. */
168
+ function fieldSource(
169
+ program: Program,
170
+ prop: ModelProperty,
171
+ ): LayoutSource | undefined {
172
+ const child = childBlock(program, prop);
173
+ if (child) return child.scalar ? undefined : child;
174
+ const type = prop.type;
175
+ if (type.kind !== "Model" || type.indexer) return undefined;
176
+ return layoutSource(program, type);
177
+ }
178
+
222
179
  /**
223
- * The canonical UI artifact for one block. Scopes are relative to this block's own
224
- * root, so it renders standalone; children are incorporated and re-scoped.
180
+ * One property as its model lays it out, scoped to that model: a Group of a composed
181
+ * question's fields, or of a model the form declares itself, or a Control.
182
+ *
183
+ * A Group takes the property's label before the question's, and the property's doc comment
184
+ * as its description, so a question asked in several roles is told apart by role.
225
185
  */
226
- export function emitBlockUi(program: Program, block: LayoutSource): UiNode {
227
- // A single-value question renders as one Control at its own root.
228
- if (block.scalar) {
229
- const node: UiNode = { type: "Control", scope: "#" };
230
- if (block.label) node.label = block.label;
231
- return node;
186
+ export function propertyUi(program: Program, prop: ModelProperty): UiNode {
187
+ const child = fieldSource(program, prop);
188
+ if (child) {
189
+ const group = rescopeUi(emitBlockUi(program, child), prop.name);
190
+ const label = propLabel(program, prop);
191
+ if (label) group.label = label;
192
+ const description = getDoc(program, prop);
193
+ const widget = propWidget(program, prop);
194
+ if (description || widget)
195
+ group.options = {
196
+ ...(group.options ?? {}),
197
+ ...(description ? { description } : {}),
198
+ ...(widget ? { widget } : {}),
199
+ };
200
+ return group;
232
201
  }
233
202
 
234
- const nodeForProperty = (prop: ModelProperty): UiNode => {
235
- const child = childBlock(program, prop);
236
- if (child && !child.scalar) {
237
- return rescopeUi(emitBlockUi(program, child), prop.name);
238
- }
239
-
240
- const node: UiNode = {
241
- type: "Control",
242
- scope: `#/properties/${prop.name}`,
243
- };
244
- const label = propLabel(program, prop);
245
- if (label) node.label = label;
203
+ const node: UiNode = {
204
+ type: "Control",
205
+ scope: `#/properties/${prop.name}`,
206
+ };
207
+ const label = propLabel(program, prop);
208
+ if (label) node.label = label;
246
209
 
247
- const detail = itemDetail(program, prop);
248
- if (detail) node.options = { ...(node.options ?? {}), detail };
210
+ const detail = itemDetail(program, prop);
211
+ if (detail) node.options = { ...(node.options ?? {}), detail };
249
212
 
250
- const widget = propWidget(program, prop);
251
- if (widget) node.options = { ...(node.options ?? {}), widget };
252
- if (propReadOnly(program, prop))
253
- node.options = { ...(node.options ?? {}), readonly: true };
213
+ const widget = propWidget(program, prop);
214
+ if (widget) node.options = { ...(node.options ?? {}), widget };
215
+ if (propReadOnly(program, prop))
216
+ node.options = { ...(node.options ?? {}), readonly: true };
254
217
 
255
- const conds = propVisibleWhen(program, prop);
256
- if (conds.length === 1) {
257
- const c = conds[0];
218
+ const conds = propVisibleWhen(program, prop);
219
+ if (conds.length === 1) {
220
+ const c = conds[0];
221
+ node.rule = {
222
+ effect: "SHOW",
223
+ condition: jsonFormsCondition(c),
224
+ };
225
+ } else {
226
+ const enabled = propEnabledWhen(program, prop);
227
+ if (enabled.length === 1) {
228
+ const c = enabled[0];
258
229
  node.rule = {
259
- effect: "SHOW",
230
+ effect: "ENABLE",
260
231
  condition: jsonFormsCondition(c),
261
232
  };
262
233
  } else {
263
- const enabled = propEnabledWhen(program, prop);
264
- if (enabled.length === 1) {
265
- const c = enabled[0];
234
+ const readOnly = propReadOnlyWhen(program, prop);
235
+ if (readOnly.length === 1) {
236
+ const c = readOnly[0];
266
237
  node.rule = {
267
- effect: "ENABLE",
238
+ effect: "DISABLE",
268
239
  condition: jsonFormsCondition(c),
269
240
  };
270
- } else {
271
- const readOnly = propReadOnlyWhen(program, prop);
272
- if (readOnly.length === 1) {
273
- const c = readOnly[0];
274
- node.rule = {
275
- effect: "DISABLE",
276
- condition: jsonFormsCondition(c),
277
- };
278
- }
279
241
  }
280
242
  }
243
+ }
244
+
245
+ return node;
246
+ }
281
247
 
248
+ /**
249
+ * The canonical UI artifact for one block. Scopes are relative to this block's own
250
+ * root, so it renders standalone; children are incorporated and re-scoped.
251
+ */
252
+ export function emitBlockUi(program: Program, block: LayoutSource): UiNode {
253
+ // A single-value question renders as one Control at its own root.
254
+ if (block.scalar) {
255
+ const node: UiNode = { type: "Control", scope: "#" };
256
+ if (block.label) node.label = block.label;
282
257
  return node;
283
- };
258
+ }
259
+
260
+ const nodeForProperty = (prop: ModelProperty) => propertyUi(program, prop);
284
261
 
285
262
  const props =
286
263
  block.model.kind === "Model" ? layoutProps(program, block.model) : [];
287
- const elements: UiNode[] = [];
288
- const documentedStaticSections = block.sections
289
- ? [...block.sections.members.values()].filter(
290
- (member) =>
291
- getDoc(program, member) &&
292
- !props.some(
293
- (prop) => propSection(program, prop)?.name === member.name,
294
- ),
295
- )
296
- : [];
297
-
298
- if (documentedStaticSections.length && block.sections) {
299
- const emitted = new Set<string>();
300
- for (const member of block.sections.members.values()) {
301
- const description = getDoc(program, member);
302
- const members = props.filter(
303
- (prop) => propSection(program, prop)?.name === member.name,
304
- );
305
- if (!members.length && description)
306
- elements.push({ type: "Label", text: description });
307
- for (const prop of members) {
308
- elements.push(nodeForProperty(prop));
309
- emitted.add(prop.name);
310
- }
311
- }
312
- for (const prop of props)
313
- if (!emitted.has(prop.name)) elements.push(nodeForProperty(prop));
314
- } else {
315
- elements.push(...props.map(nodeForProperty));
316
- }
264
+ const elements = props.map(nodeForProperty);
317
265
 
318
266
  const group: UiNode = { type: "Group", elements };
319
267
  if (block.label) group.label = block.label;
320
268
  else if (block.doc) group.label = block.doc;
321
- return applyOverrides(group, block.overrides);
269
+ return group;
322
270
  }