simpler-forms 0.1.0-alpha.1 → 0.2.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 (89) hide show
  1. package/README.md +300 -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 +17 -0
  9. package/dist/src/decorators/mapping.js +122 -0
  10. package/dist/src/decorators/mapping.js.map +1 -0
  11. package/dist/src/decorators/meta.d.ts +15 -5
  12. package/dist/src/decorators/meta.js +31 -4
  13. package/dist/src/decorators/meta.js.map +1 -1
  14. package/dist/src/decorators/shared.d.ts +2 -2
  15. package/dist/src/decorators/shared.js.map +1 -1
  16. package/dist/src/decorators/ui.d.ts +14 -12
  17. package/dist/src/decorators/ui.js +20 -43
  18. package/dist/src/decorators/ui.js.map +1 -1
  19. package/dist/src/emitter.d.ts +8 -0
  20. package/dist/src/emitter.js +55 -16
  21. package/dist/src/emitter.js.map +1 -1
  22. package/dist/src/emitters/block-ui.d.ts +14 -3
  23. package/dist/src/emitters/block-ui.js +81 -119
  24. package/dist/src/emitters/block-ui.js.map +1 -1
  25. package/dist/src/emitters/layout-ui.d.ts +12 -0
  26. package/dist/src/emitters/layout-ui.js +225 -0
  27. package/dist/src/emitters/layout-ui.js.map +1 -0
  28. package/dist/src/emitters/overlay.d.ts +10 -8
  29. package/dist/src/emitters/overlay.js +30 -105
  30. package/dist/src/emitters/overlay.js.map +1 -1
  31. package/dist/src/forms.d.ts +23 -0
  32. package/dist/src/forms.js +54 -0
  33. package/dist/src/forms.js.map +1 -0
  34. package/dist/src/index.d.ts +22 -8
  35. package/dist/src/index.js +17 -3
  36. package/dist/src/index.js.map +1 -1
  37. package/dist/src/layout.d.ts +50 -0
  38. package/dist/src/layout.js +397 -0
  39. package/dist/src/layout.js.map +1 -0
  40. package/dist/src/lib.d.ts +585 -39
  41. package/dist/src/lib.js +258 -15
  42. package/dist/src/lib.js.map +1 -1
  43. package/dist/src/linter.js +8 -43
  44. package/dist/src/linter.js.map +1 -1
  45. package/dist/src/mapping-from.d.ts +21 -0
  46. package/dist/src/mapping-from.js +169 -0
  47. package/dist/src/mapping-from.js.map +1 -0
  48. package/dist/src/mapping.d.ts +65 -0
  49. package/dist/src/mapping.js +209 -0
  50. package/dist/src/mapping.js.map +1 -0
  51. package/dist/src/model.d.ts +143 -23
  52. package/dist/src/model.js +108 -21
  53. package/dist/src/model.js.map +1 -1
  54. package/dist/src/public.d.ts +20 -4
  55. package/dist/src/public.js +28 -4
  56. package/dist/src/public.js.map +1 -1
  57. package/dist/src/validate.d.ts +2 -1
  58. package/dist/src/validate.js +208 -58
  59. package/dist/src/validate.js.map +1 -1
  60. package/lib/main.tsp +1 -0
  61. package/lib/mapping.tsp +173 -0
  62. package/lib/meta.tsp +25 -6
  63. package/lib/types.tsp +24 -63
  64. package/lib/ui.tsp +34 -17
  65. package/package.json +17 -11
  66. package/src/casing.ts +172 -0
  67. package/src/decorators/index.ts +1 -0
  68. package/src/decorators/mapping.ts +200 -0
  69. package/src/decorators/meta.ts +56 -13
  70. package/src/decorators/shared.ts +6 -1
  71. package/src/decorators/ui.ts +43 -59
  72. package/src/emitter.ts +76 -16
  73. package/src/emitters/block-ui.ts +83 -135
  74. package/src/emitters/layout-ui.ts +280 -0
  75. package/src/emitters/overlay.ts +43 -116
  76. package/src/forms.ts +82 -0
  77. package/src/index.ts +17 -3
  78. package/src/layout.ts +592 -0
  79. package/src/lib.ts +264 -15
  80. package/src/linter.ts +17 -49
  81. package/src/mapping-from.ts +216 -0
  82. package/src/mapping.ts +358 -0
  83. package/src/model.ts +287 -46
  84. package/src/public.ts +60 -6
  85. package/src/validate.ts +221 -60
  86. package/dist/src/emitters/override-condition.d.ts +0 -12
  87. package/dist/src/emitters/override-condition.js +0 -25
  88. package/dist/src/emitters/override-condition.js.map +0 -1
  89. package/src/emitters/override-condition.ts +0 -37
@@ -19,12 +19,15 @@ import {
19
19
  } from "../model.js";
20
20
 
21
21
  /**
22
- * The parts of a block's JSON Schema that `@typespec/json-schema` cannot produce.
23
- *
24
- * Two of them. Conditional requiredness, from `@Validation.requiredWhen`. And the
25
- * presentation a *form* puts on a member of a question it composes, from `@UI.overrides` --
26
- * SF-424 calls the authorized representative's phone "AOR Telephone Number" where the
27
- * question calls it "Telephone Number", and that belongs to the form.
22
+ * Whether a model's schema has a definition of its own in `$defs`, written with its own
23
+ * overlay, so what it requires shouldn't be repeated beside each `$ref` to it.
24
+ */
25
+ export type OwnsDefinition = (model: Model) => boolean;
26
+
27
+ /**
28
+ * The parts of a block's JSON Schema that `@typespec/json-schema` cannot produce: what the
29
+ * `@Validation.*` decorators require, and the help text, read-only status and choice
30
+ * contracts the `@UI.*` decorators carry into the schema.
28
31
  *
29
32
  * Everything else -- types, constraints, enums, arrays, `required`, `$ref` composition,
30
33
  * `extends` as `allOf` -- comes from the stock emitter. The build merges this over it.
@@ -32,6 +35,7 @@ import {
32
35
  export function emitSchemaOverlay(
33
36
  program: Program,
34
37
  block: Block,
38
+ ownsDefinition: OwnsDefinition = () => false,
35
39
  ): Record<string, unknown> | undefined {
36
40
  if (block.model.kind !== "Model") return undefined;
37
41
  const model = block.model;
@@ -39,17 +43,19 @@ export function emitSchemaOverlay(
39
43
  program,
40
44
  orderedProps(program, block),
41
45
  );
42
- const patches = overriddenPresentation(block);
43
46
  const readOnly = readOnlyAnnotations(program, model);
44
47
  const helpText = helpTextAnnotations(program, model);
45
48
  const constraints = constraintAnnotations(program, model);
46
- const cardinality = cardinalityAnnotations(program, model);
49
+ const cardinality = cardinalityAnnotations(program, model, ownsDefinition);
47
50
  const encodedCheckboxes = encodedCheckboxAnnotations(program, model);
48
- const exclusiveValues = exclusiveValueAnnotations(program, model);
51
+ const exclusiveValues = exclusiveValueAnnotations(
52
+ program,
53
+ model,
54
+ ownsDefinition,
55
+ );
49
56
  const alternatives = atLeastOneAnnotations(program, model);
50
57
  const parts = [
51
58
  conditionals,
52
- patches,
53
59
  readOnly,
54
60
  helpText,
55
61
  constraints,
@@ -66,15 +72,16 @@ export function emitSchemaOverlay(
66
72
  export function emitModelOverlay(
67
73
  program: Program,
68
74
  model: Model,
75
+ ownsDefinition: OwnsDefinition = () => false,
69
76
  ): Record<string, unknown> | undefined {
70
77
  const parts = [
71
78
  conditionalValidation(program, [...model.properties.values()]),
72
79
  readOnlyAnnotations(program, model),
73
80
  helpTextAnnotations(program, model),
74
81
  constraintAnnotations(program, model),
75
- cardinalityAnnotations(program, model),
82
+ cardinalityAnnotations(program, model, ownsDefinition),
76
83
  encodedCheckboxAnnotations(program, model),
77
- exclusiveValueAnnotations(program, model),
84
+ exclusiveValueAnnotations(program, model, ownsDefinition),
78
85
  atLeastOneAnnotations(program, model),
79
86
  ].filter(Boolean) as Record<string, unknown>[];
80
87
  return parts.length ? parts.reduce(merge, {}) : undefined;
@@ -88,6 +95,7 @@ export function emitModelOverlay(
88
95
  function exclusiveValueAnnotations(
89
96
  program: Program,
90
97
  model: Model,
98
+ ownsDefinition: OwnsDefinition,
91
99
  seen = new Set<Model>(),
92
100
  ): Record<string, unknown> | undefined {
93
101
  if (seen.has(model)) return undefined;
@@ -106,13 +114,18 @@ function exclusiveValueAnnotations(
106
114
  };
107
115
  }
108
116
  const child = childModel(property.type);
109
- // Published questions own intrinsic exclusivity in their own schema. Do not repeat the
110
- // same constraint beside each form occurrence's $ref; only local unpublished capture
111
- // models need recursive projection.
112
- if (child && !readBlock(program, child.model)) {
117
+ // Published questions, and local models with a `$defs` definition of their own, carry
118
+ // their exclusivity in that schema. Don't repeat it beside each `$ref`; only a model
119
+ // inlined where it's used needs it projected.
120
+ if (
121
+ child &&
122
+ !readBlock(program, child.model) &&
123
+ !ownsDefinition(child.model)
124
+ ) {
113
125
  const nested = exclusiveValueAnnotations(
114
126
  program,
115
127
  child.model,
128
+ ownsDefinition,
116
129
  new Set(seen),
117
130
  );
118
131
  if (nested)
@@ -147,6 +160,7 @@ function atLeastOneAnnotations(
147
160
  function cardinalityAnnotations(
148
161
  program: Program,
149
162
  model: Model,
163
+ ownsDefinition: OwnsDefinition,
150
164
  seen = new Set<Model>(),
151
165
  ): Record<string, unknown> | undefined {
152
166
  if (seen.has(model)) return undefined;
@@ -194,14 +208,22 @@ function cardinalityAnnotations(
194
208
  ),
195
209
  );
196
210
  const child = childModel(property.type);
197
- // A published question owns its intrinsic cardinality in its own schema. Crossing
198
- // that reference boundary would copy the same constraints beside every occurrence
199
- // `$ref`, causing validators to report each missing path twice. Local unpublished
200
- // models still need recursive projection because they have no standalone artifact.
201
- if (child && !readBlock(program, child.model)) {
211
+ // The paths of a list's own decorators name fields of its items, so its patch
212
+ // constrains each item, as its nested patch below does.
213
+ if (child?.repeated && Object.keys(patch).length) patch = { items: patch };
214
+ // A published question, or a local model with a `$defs` definition of its own, owns its
215
+ // cardinality in that schema. Crossing that reference boundary would copy the same
216
+ // constraints beside every `$ref`, causing validators to report each missing path
217
+ // twice. Only a model inlined where it's used needs them projected.
218
+ if (
219
+ child &&
220
+ !readBlock(program, child.model) &&
221
+ !ownsDefinition(child.model)
222
+ ) {
202
223
  const nested = cardinalityAnnotations(
203
224
  program,
204
225
  child.model,
226
+ ownsDefinition,
205
227
  new Set(seen),
206
228
  );
207
229
  if (nested)
@@ -474,101 +496,6 @@ function conditionSchema(
474
496
  return nested;
475
497
  }
476
498
 
477
- /**
478
- * A form's own label and help text for a member of a question it composes.
479
- *
480
- * The member's schema is behind a `$ref`, so the patch goes beside it: a second `allOf`
481
- * branch naming the member. A consumer that resolves the reference sees the question's
482
- * wording, then the form's on top -- which is the order that makes the form win.
483
- */
484
- function overriddenPresentation(
485
- block: Block,
486
- ): Record<string, unknown> | undefined {
487
- const patches: Record<string, Record<string, unknown>> = {};
488
- for (const [path, override] of Object.entries(block.overrides)) {
489
- const presentation: Record<string, unknown> = {};
490
- if (typeof override.label === "string") presentation.title = override.label;
491
- if (typeof override.helpText === "string")
492
- presentation.description = override.helpText;
493
- if (override.readOnly === true) presentation.readOnly = true;
494
- if (!Object.keys(presentation).length) continue;
495
-
496
- const [head, ...rest] = path.split(".");
497
- if (!rest.length && override.readOnly !== true) {
498
- // A root property is declared in this block, so `@UI.label` already covers it.
499
- continue;
500
- }
501
- const property = modelProperty(block.model as Model, head);
502
- const child = property ? childModel(property.type) : undefined;
503
- let patch =
504
- rest.length && child
505
- ? nestPresentation(child.model, rest, presentation)
506
- : rest.length
507
- ? nest(rest, presentation)
508
- : presentation;
509
- if (rest.length && child?.repeated) patch = { items: patch };
510
- patches[head] = merge(patches[head] ?? {}, patch);
511
- }
512
- if (!Object.keys(patches).length) return undefined;
513
- return {
514
- properties: Object.fromEntries(
515
- Object.entries(patches).map(([name, patch]) => [
516
- name,
517
- { allOf: [patch] },
518
- ]),
519
- ),
520
- };
521
- }
522
-
523
- /** Find one own or inherited property, preferring the derived declaration. */
524
- function modelProperty(model: Model, name: string): ModelProperty | undefined {
525
- for (
526
- let current: Model | undefined = model;
527
- current;
528
- current = current.baseModel
529
- ) {
530
- const property = current.properties.get(name);
531
- if (property) return property;
532
- }
533
- return undefined;
534
- }
535
-
536
- /**
537
- * Nest one form-scoped presentation patch through the addressed model shape.
538
- *
539
- * Arrays require an `items` boundary in JSON Schema even though the authoring
540
- * path deliberately omits array syntax (`reports.total`, not `reports[].total`).
541
- */
542
- function nestPresentation(
543
- model: Model,
544
- steps: string[],
545
- leaf: Record<string, unknown>,
546
- ): Record<string, unknown> {
547
- const [step, ...rest] = steps;
548
- if (!step) return leaf;
549
- const property = modelProperty(model, step);
550
- const child = property ? childModel(property.type) : undefined;
551
- let nested =
552
- rest.length && child
553
- ? nestPresentation(child.model, rest, leaf)
554
- : rest.length
555
- ? nest(rest, leaf)
556
- : leaf;
557
- if (rest.length && child?.repeated) nested = { items: nested };
558
- return { properties: { [step]: nested } };
559
- }
560
-
561
- /** `["phone"], {title}` becomes `{properties: {phone: {title}}}`. */
562
- function nest(
563
- steps: string[],
564
- leaf: Record<string, unknown>,
565
- ): Record<string, unknown> {
566
- return steps.reduceRight<Record<string, unknown>>(
567
- (inner, step) => ({ properties: { [step]: inner } }),
568
- leaf,
569
- );
570
- }
571
-
572
499
  function merge(
573
500
  a: Record<string, unknown>,
574
501
  b: Record<string, unknown>,
package/src/forms.ts ADDED
@@ -0,0 +1,82 @@
1
+ import type { Diagnostic, Model, Program } from "@typespec/compiler";
2
+ import { createDiagnostic } from "./lib.js";
3
+ import {
4
+ type Block,
5
+ type FormMeta,
6
+ allFormMetas,
7
+ allLayouts,
8
+ modelFormMeta,
9
+ readBlock,
10
+ } from "./model.js";
11
+
12
+ /** One form an applicant opens, published under its id. */
13
+ export interface PublishedForm {
14
+ id: string;
15
+ /** The model carrying `@Meta.form`, whose schema the form publishes. */
16
+ model: Model;
17
+ meta: FormMeta;
18
+ block: Block;
19
+ /** The `@UI.layout` presenting the form, when its own fields do not lay it out. */
20
+ layout?: Model;
21
+ }
22
+
23
+ /**
24
+ * Every `@Meta.form` that can be published, and the problems that stop the others.
25
+ *
26
+ * A form's fields lay it out, unless one `@UI.layout` model presents it. A layout of a
27
+ * model with no `@Meta.form` is reported, and so is a form with two layouts, which is not
28
+ * published. Two forms with one id are reported as `duplicate-block-id`.
29
+ */
30
+ export function resolveForms(program: Program): {
31
+ forms: PublishedForm[];
32
+ problems: Diagnostic[];
33
+ } {
34
+ const forms: PublishedForm[] = [];
35
+ const problems: Diagnostic[] = [];
36
+
37
+ const layoutsOf = new Map<Model, Model[]>();
38
+ for (const [layout, presented] of allLayouts(program)) {
39
+ if (!modelFormMeta(program, presented)) {
40
+ problems.push(
41
+ createDiagnostic({
42
+ code: "layout-not-form",
43
+ target: layout,
44
+ format: { name: layout.name, presented: presented.name },
45
+ }),
46
+ );
47
+ continue;
48
+ }
49
+ layoutsOf.set(presented, [...(layoutsOf.get(presented) ?? []), layout]);
50
+ }
51
+
52
+ const ids = new Set<string>();
53
+ for (const [model, meta] of allFormMetas(program)) {
54
+ const layouts = layoutsOf.get(model) ?? [];
55
+ if (layouts.length > 1) {
56
+ for (const target of layouts)
57
+ problems.push(
58
+ createDiagnostic({
59
+ code: "layout-duplicate",
60
+ target,
61
+ format: {
62
+ form: model.name,
63
+ first: layouts[0].name,
64
+ second: layouts[1].name,
65
+ },
66
+ }),
67
+ );
68
+ continue;
69
+ }
70
+ if (ids.has(meta.id)) continue;
71
+ ids.add(meta.id);
72
+ forms.push({
73
+ id: meta.id,
74
+ model,
75
+ meta,
76
+ block: readBlock(program, model)!,
77
+ ...(layouts.length ? { layout: layouts[0] } : {}),
78
+ });
79
+ }
80
+
81
+ return { forms, problems };
82
+ }
package/src/index.ts CHANGED
@@ -14,15 +14,18 @@ export const $decorators = {
14
14
  "SimplerForms.Meta": {
15
15
  question: d.$question,
16
16
  form: d.$form,
17
+ tags: d.$tags,
18
+ entities: d.$entities,
17
19
  tag: d.$tag,
18
20
  role: d.$role,
19
21
  },
20
22
  "SimplerForms.UI": {
21
- sections: d.$sections,
22
- section: d.$section,
23
- overrides: d.$overrides,
23
+ layout: d.$layout,
24
+ field: d.$field,
25
+ flatten: d.$flatten,
24
26
  label: d.$label,
25
27
  helpText: d.$helpText,
28
+ widgets: d.$widgets,
26
29
  widget: d.$widget,
27
30
  encodedCheckboxGroup: d.$encodedCheckboxGroup,
28
31
  order: d.$order,
@@ -58,4 +61,15 @@ export const $decorators = {
58
61
  evaluationOrder: d.$evaluationOrder,
59
62
  totals: d.$totals,
60
63
  },
64
+ "SimplerForms.Mapping": {
65
+ targets: d.$targets,
66
+ transforms: d.$transforms,
67
+ transform: d.$transform,
68
+ match: d.$match,
69
+ required: d.$required,
70
+ when: d.$when,
71
+ to: d.$to,
72
+ path: d.$path,
73
+ from: d.$from,
74
+ },
61
75
  };