simpler-forms 0.1.0-alpha.0 → 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 (90) 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/shared.d.ts +10 -0
  15. package/dist/src/decorators/shared.js +8 -0
  16. package/dist/src/decorators/shared.js.map +1 -1
  17. package/dist/src/decorators/ui.d.ts +33 -12
  18. package/dist/src/decorators/ui.js +39 -43
  19. package/dist/src/decorators/ui.js.map +1 -1
  20. package/dist/src/emitter.d.ts +8 -0
  21. package/dist/src/emitter.js +48 -13
  22. package/dist/src/emitter.js.map +1 -1
  23. package/dist/src/emitters/block-ui.d.ts +17 -3
  24. package/dist/src/emitters/block-ui.js +144 -124
  25. package/dist/src/emitters/block-ui.js.map +1 -1
  26. package/dist/src/emitters/layout-ui.d.ts +12 -0
  27. package/dist/src/emitters/layout-ui.js +225 -0
  28. package/dist/src/emitters/layout-ui.js.map +1 -0
  29. package/dist/src/emitters/overlay.d.ts +3 -6
  30. package/dist/src/emitters/overlay.js +3 -86
  31. package/dist/src/emitters/overlay.js.map +1 -1
  32. package/dist/src/forms.d.ts +23 -0
  33. package/dist/src/forms.js +54 -0
  34. package/dist/src/forms.js.map +1 -0
  35. package/dist/src/index.d.ts +17 -6
  36. package/dist/src/index.js +14 -3
  37. package/dist/src/index.js.map +1 -1
  38. package/dist/src/layout.d.ts +50 -0
  39. package/dist/src/layout.js +397 -0
  40. package/dist/src/layout.js.map +1 -0
  41. package/dist/src/lib.d.ts +485 -39
  42. package/dist/src/lib.js +216 -16
  43. package/dist/src/lib.js.map +1 -1
  44. package/dist/src/linter.js +2 -41
  45. package/dist/src/linter.js.map +1 -1
  46. package/dist/src/mapping-from.d.ts +20 -0
  47. package/dist/src/mapping-from.js +149 -0
  48. package/dist/src/mapping-from.js.map +1 -0
  49. package/dist/src/mapping.d.ts +58 -0
  50. package/dist/src/mapping.js +209 -0
  51. package/dist/src/mapping.js.map +1 -0
  52. package/dist/src/model.d.ts +87 -9
  53. package/dist/src/model.js +65 -10
  54. package/dist/src/model.js.map +1 -1
  55. package/dist/src/public.d.ts +19 -3
  56. package/dist/src/public.js +27 -3
  57. package/dist/src/public.js.map +1 -1
  58. package/dist/src/validate.d.ts +2 -1
  59. package/dist/src/validate.js +181 -59
  60. package/dist/src/validate.js.map +1 -1
  61. package/lib/main.tsp +1 -0
  62. package/lib/mapping.tsp +71 -0
  63. package/lib/meta.tsp +23 -4
  64. package/lib/types.tsp +13 -65
  65. package/lib/ui.tsp +60 -17
  66. package/package.json +7 -1
  67. package/src/casing.ts +172 -0
  68. package/src/decorators/index.ts +1 -0
  69. package/src/decorators/mapping.ts +57 -0
  70. package/src/decorators/meta.ts +50 -11
  71. package/src/decorators/shared.ts +13 -0
  72. package/src/decorators/ui.ts +81 -59
  73. package/src/emitter.ts +59 -13
  74. package/src/emitters/block-ui.ts +156 -140
  75. package/src/emitters/layout-ui.ts +280 -0
  76. package/src/emitters/overlay.ts +3 -103
  77. package/src/forms.ts +82 -0
  78. package/src/index.ts +14 -3
  79. package/src/layout.ts +592 -0
  80. package/src/lib.ts +222 -16
  81. package/src/linter.ts +1 -42
  82. package/src/mapping-from.ts +193 -0
  83. package/src/mapping.ts +351 -0
  84. package/src/model.ts +192 -24
  85. package/src/public.ts +50 -5
  86. package/src/validate.ts +189 -60
  87. package/dist/src/emitters/override-condition.d.ts +0 -12
  88. package/dist/src/emitters/override-condition.js +0 -25
  89. package/dist/src/emitters/override-condition.js.map +0 -1
  90. package/src/emitters/override-condition.ts +0 -37
@@ -1,75 +1,42 @@
1
- import type { Enum, Model, ModelProperty, Scalar } from "@typespec/compiler";
1
+ import type {
2
+ Enum,
3
+ EnumMember,
4
+ Model,
5
+ ModelProperty,
6
+ Namespace,
7
+ Scalar,
8
+ } from "@typespec/compiler";
2
9
  import { $summary } from "@typespec/compiler";
3
10
  import { stateKeys } from "../lib.js";
4
11
  import {
5
12
  type Ctx,
6
13
  condition,
7
14
  countCondition,
8
- enumName,
9
15
  literal,
16
+ negatedCondition,
10
17
  plain,
11
18
  push,
12
19
  set,
13
20
  } from "./shared.js";
14
21
 
15
- // --- sections -------------------------------------------------------------
22
+ // --- layouts --------------------------------------------------------------
16
23
 
17
- export const $sections = (ctx: Ctx, target: Model, sections: Enum) =>
18
- set(ctx, stateKeys.sections, target, sections);
24
+ export const $layout = (ctx: Ctx, target: Model, form: Model) =>
25
+ set(ctx, stateKeys.layout, target, form);
19
26
 
20
27
  /**
21
- * `valueof EnumMember` arrives as a value, not the member type, so resolve the
22
- * member's name and label here rather than in the emitters.
28
+ * Records the argument's syntax as well as the property it resolves to. A reference to a
29
+ * nested occurrence (`Form.payee::type.address`) resolves to the declaration, so the
30
+ * syntax is the only place the occurrence's path survives.
23
31
  */
24
- export const $section = (ctx: Ctx, target: ModelProperty, section: unknown) =>
25
- set(ctx, stateKeys.section, target, sectionRef(section));
26
-
27
- export function sectionRef(v: unknown): { name: string; label?: string } {
28
- const m = v as any;
29
- if (m && typeof m === "object") {
30
- if (m.name)
31
- return {
32
- name: String(m.name),
33
- label: m.value ? String(m.value) : undefined,
34
- };
35
- if (m.value?.name) {
36
- return {
37
- name: String(m.value.name),
38
- label: m.value.value ? String(m.value.value) : undefined,
39
- };
40
- }
41
- }
42
- return { name: String(v) };
43
- }
44
-
45
- // --- form-scoped overrides ------------------------------------------------
46
-
47
- function overridePlain(value: unknown): unknown {
48
- const candidate = value as any;
49
- if (
50
- candidate &&
51
- typeof candidate === "object" &&
52
- candidate.entityKind === "Value"
53
- ) {
54
- return literal(candidate);
55
- }
56
- if (Array.isArray(value)) return value.map(overridePlain);
57
- if (value && typeof value === "object") {
58
- return Object.fromEntries(
59
- Object.entries(value).map(([key, nested]) => [
60
- key,
61
- overridePlain(nested),
62
- ]),
63
- );
64
- }
65
- return value;
66
- }
67
-
68
- export const $overrides = (
69
- ctx: Ctx,
70
- target: Model | ModelProperty,
71
- patch: unknown,
72
- ) => set(ctx, stateKeys.overrides, target, overridePlain(plain(ctx, patch)));
32
+ export const $field = (ctx: Ctx, target: ModelProperty, field: ModelProperty) =>
33
+ set(ctx, stateKeys.layoutField, target, {
34
+ field,
35
+ node: ctx.getArgumentTarget(0),
36
+ });
37
+
38
+ export const $flatten = (ctx: Ctx, target: ModelProperty) =>
39
+ set(ctx, stateKeys.flatten, target, true);
73
40
 
74
41
  // --- presentation ---------------------------------------------------------
75
42
 
@@ -80,7 +47,7 @@ export const $overrides = (
80
47
  */
81
48
  export const $label = (
82
49
  ctx: Ctx,
83
- target: Model | Scalar | ModelProperty,
50
+ target: Model | Scalar | Enum | ModelProperty,
84
51
  text: string,
85
52
  ) => {
86
53
  set(ctx, stateKeys.label, target, text);
@@ -94,8 +61,26 @@ export const $label = (
94
61
  export const $helpText = (ctx: Ctx, target: ModelProperty, text: string) =>
95
62
  set(ctx, stateKeys.helpText, target, text);
96
63
 
97
- export const $widget = (ctx: Ctx, target: ModelProperty, widget: unknown) =>
98
- set(ctx, stateKeys.widget, target, enumName(widget));
64
+ export const $widgets = (ctx: Ctx, target: Namespace, widgets: Enum) =>
65
+ set(ctx, stateKeys.widgets, target, widgets);
66
+
67
+ /**
68
+ * Records the emitted name now and the member itself for `$onValidate`, which checks it
69
+ * against the declared sets once every `@UI.widgets` has run.
70
+ */
71
+ export const $widget = (
72
+ ctx: Ctx,
73
+ target: ModelProperty | Scalar | Model,
74
+ widget: EnumMember,
75
+ ) => {
76
+ set(
77
+ ctx,
78
+ stateKeys.widget,
79
+ target,
80
+ typeof widget.value === "string" ? widget.value : widget.name,
81
+ );
82
+ set(ctx, stateKeys.widgetMember, target, widget);
83
+ };
99
84
 
100
85
  export const $encodedCheckboxGroup = (
101
86
  ctx: Ctx,
@@ -129,6 +114,28 @@ export const $visibleWhen = (
129
114
  equals: unknown,
130
115
  ) => push(ctx, stateKeys.visibleWhen, target, condition(source, equals));
131
116
 
117
+ /**
118
+ * Hide the field until the source is answered with a value other than `equals`.
119
+ *
120
+ * Recorded as a negated `visibleWhen`, as `disabledWhen` is a negated `enabledWhen`, so every
121
+ * consumer that already reads visibility handles it unchanged. Unlike `disabledWhen`, the
122
+ * field also stays hidden while the source is unanswered: a field kept for the complement of a
123
+ * value -- Province, for a country other than the US -- has nothing to apply to until a value
124
+ * is chosen.
125
+ */
126
+ export const $hiddenWhen = (
127
+ ctx: Ctx,
128
+ target: ModelProperty,
129
+ source: ModelProperty,
130
+ equals: unknown,
131
+ ) =>
132
+ push(
133
+ ctx,
134
+ stateKeys.visibleWhen,
135
+ target,
136
+ negatedCondition(source, equals, { requiresAnswer: true }),
137
+ );
138
+
132
139
  export const $enabledWhen = (
133
140
  ctx: Ctx,
134
141
  target: ModelProperty,
@@ -136,6 +143,21 @@ export const $enabledWhen = (
136
143
  equals: unknown,
137
144
  ) => push(ctx, stateKeys.enabledWhen, target, condition(source, equals));
138
145
 
146
+ /**
147
+ * Disable the field while the predicate holds, and enable it otherwise.
148
+ *
149
+ * Recorded as a negated `enabledWhen` rather than as a state of its own, so every consumer
150
+ * that already reads enablement gets this for free and cannot disagree with it about which
151
+ * of the two states is the default. `@UI.disabledWhen(X.province, X.country, CountryCode.USA)`
152
+ * and a hypothetical `enabledWhen(country != USA)` are the same recorded condition.
153
+ */
154
+ export const $disabledWhen = (
155
+ ctx: Ctx,
156
+ target: ModelProperty,
157
+ source: ModelProperty,
158
+ equals: unknown,
159
+ ) => push(ctx, stateKeys.enabledWhen, target, negatedCondition(source, equals));
160
+
139
161
  export const $enabledWhenAny = (
140
162
  ctx: Ctx,
141
163
  target: ModelProperty,
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) &&
@@ -1,20 +1,29 @@
1
- import type { Program } from "@typespec/compiler";
1
+ import type { Model, ModelProperty, Program } from "@typespec/compiler";
2
2
  import { getDoc } from "@typespec/compiler";
3
3
  import {
4
4
  AtomicCondition,
5
5
  Block,
6
6
  Condition,
7
7
  childBlock,
8
- orderedProps,
8
+ modelLabel,
9
+ modelOrder,
10
+ modelProperties,
9
11
  propEnabledWhen,
10
12
  propLabel,
13
+ propOmit,
11
14
  propReadOnly,
12
15
  propReadOnlyWhen,
13
- propSection,
14
16
  propVisibleWhen,
15
17
  propWidget,
18
+ readBlock,
16
19
  } from "../model.js";
17
- import { normalizedOverrideEnabledWhen } from "./override-condition.js";
20
+
21
+ /** An answered value: not null, not blank, not an empty list. */
22
+ const answeredSchema = {
23
+ not: {
24
+ anyOf: [{ type: "null" }, { const: "" }, { type: "array", maxItems: 0 }],
25
+ },
26
+ };
18
27
 
19
28
  const conditionSchema = (
20
29
  condition: AtomicCondition,
@@ -24,16 +33,12 @@ const conditionSchema = (
24
33
  : condition.operator === "countAtLeast"
25
34
  ? { type: "array", minItems: condition.minimum }
26
35
  : condition.operator === "present"
27
- ? {
28
- not: {
29
- anyOf: [
30
- { type: "null" },
31
- { const: "" },
32
- { type: "array", maxItems: 0 },
33
- ],
34
- },
35
- }
36
- : { const: condition.value };
36
+ ? answeredSchema
37
+ : condition.operator === "notEquals"
38
+ ? condition.requiresAnswer
39
+ ? { allOf: [answeredSchema, { not: { const: condition.value } }] }
40
+ : { not: { const: condition.value } }
41
+ : { const: condition.value };
37
42
 
38
43
  /** A condition over the block root, used only for the bounded cross-field disjunction. */
39
44
  const rootConditionSchema = (
@@ -46,7 +51,9 @@ const rootConditionSchema = (
46
51
  return schema;
47
52
  };
48
53
 
49
- const jsonFormsCondition = (condition: Condition): Record<string, unknown> =>
54
+ export const jsonFormsCondition = (
55
+ condition: Condition,
56
+ ): Record<string, unknown> =>
50
57
  condition.operator === "any"
51
58
  ? {
52
59
  scope: "#",
@@ -55,6 +62,10 @@ const jsonFormsCondition = (condition: Condition): Record<string, unknown> =>
55
62
  : {
56
63
  scope: `#/${condition.sourcePath.map((step) => `properties/${step}`).join("/")}`,
57
64
  schema: conditionSchema(condition),
65
+ // JSON Forms passes a condition whose source is absent unless told otherwise.
66
+ ...(condition.operator === "notEquals" && condition.requiresAnswer
67
+ ? { failWhenUndefined: true }
68
+ : {}),
58
69
  };
59
70
 
60
71
  export interface UiNode {
@@ -67,56 +78,6 @@ export interface UiNode {
67
78
  rule?: Record<string, unknown>;
68
79
  }
69
80
 
70
- type Overrides = Record<string, Record<string, unknown>>;
71
-
72
- /** Convert a canonical JSON Forms scope into the dotted path addressed by @UI.overrides. */
73
- const dataPathFromScope = (scope: string): string | undefined => {
74
- if (!scope.startsWith("#/properties/")) return undefined;
75
- const tokens = scope.slice(2).split("/");
76
- const path: string[] = [];
77
- for (let index = 0; index < tokens.length;) {
78
- if (tokens[index] !== "properties" || !tokens[index + 1]) return undefined;
79
- path.push(tokens[index + 1]);
80
- index += 2;
81
- if (tokens[index] === "items") index += 1;
82
- }
83
- return path.join(".");
84
- };
85
-
86
- /** Emit the portable JSON Forms equivalent of a form-scoped enabledWhen override. */
87
- const overrideEnabledRule = (
88
- override: Record<string, unknown>,
89
- ): Record<string, unknown> | undefined => {
90
- const condition = normalizedOverrideEnabledWhen(override);
91
- if (!condition) return undefined;
92
- const scope = `#/${condition.sourcePath.map((step) => `properties/${step}`).join("/")}`;
93
- const schema =
94
- condition.operator === "in"
95
- ? { enum: condition.values }
96
- : { const: condition.value };
97
- return { effect: "ENABLE", condition: { scope, schema } };
98
- };
99
-
100
- /** Apply occurrence-specific behavior after recursively composing canonical child UI trees. */
101
- const applyOverrides = (node: UiNode, overrides: Overrides): UiNode => {
102
- const out: UiNode = { ...node };
103
- if (typeof node.scope === "string") {
104
- const path = dataPathFromScope(node.scope);
105
- const rule = path ? overrideEnabledRule(overrides[path] ?? {}) : undefined;
106
- if (rule && node.rule) {
107
- throw new Error(
108
- `@UI.overrides enabledWhen collides with intrinsic UI behavior at ${path}`,
109
- );
110
- }
111
- if (rule) out.rule = rule;
112
- }
113
- if (node.elements)
114
- out.elements = node.elements.map((child) =>
115
- applyOverrides(child, overrides),
116
- );
117
- return out;
118
- };
119
-
120
81
  /** Re-prefix every Control scope so a child's tree sits under `propName`. */
121
82
  export function rescopeUi(node: UiNode, propName: string): UiNode {
122
83
  const out: UiNode = { ...node };
@@ -154,101 +115,156 @@ export function rescopeUi(node: UiNode, propName: string): UiNode {
154
115
  }
155
116
 
156
117
  /**
157
- * The canonical UI artifact for one block. Scopes are relative to this block's own
158
- * root, so it renders standalone; children are incorporated and re-scoped.
118
+ * Every property a model's answers carry, inherited ones included, in `@UI.order`.
119
+ *
120
+ * Not `orderedProps`, which keeps a question to its own properties because its JSON Schema
121
+ * composes the base through `allOf`. A layout has no `allOf` to fall back on: a question
122
+ * whose fields are all inherited -- `primary-org/address` extends `generics/address` and adds
123
+ * none -- would lay out as an empty group, and a form-local extension could not interleave
124
+ * its fields with the ones it inherits.
159
125
  */
160
- export function emitBlockUi(program: Program, block: Block): UiNode {
161
- // A single-value question renders as one Control at its own root.
162
- if (block.scalar) {
163
- const node: UiNode = { type: "Control", scope: "#" };
164
- if (block.label) node.label = block.label;
165
- return node;
166
- }
126
+ function layoutProps(program: Program, model: Model): ModelProperty[] {
127
+ const props = modelProperties(model).filter((p) => !propOmit(program, p));
128
+ const order = modelOrder(program, model);
129
+ if (!order) return props;
130
+ const byName = new Map(props.map((p) => [p.name, p]));
131
+ const out = order
132
+ .map((n) => byName.get(n))
133
+ .filter(Boolean) as ModelProperty[];
134
+ for (const p of props) if (!out.includes(p)) out.push(p);
135
+ return out;
136
+ }
167
137
 
168
- const nodeForProperty = (
169
- prop: ReturnType<typeof orderedProps>[number],
170
- ): UiNode => {
171
- const child = childBlock(program, prop);
172
- if (child && !child.scalar) {
173
- return rescopeUi(emitBlockUi(program, child), prop.name);
174
- }
138
+ /** What laying out a model needs, which a block has and a form-local model can supply. */
139
+ type LayoutSource = Pick<Block, "model" | "scalar" | "label" | "doc">;
175
140
 
176
- const node: UiNode = {
177
- type: "Control",
178
- scope: `#/properties/${prop.name}`,
179
- };
180
- const label = propLabel(program, prop);
181
- if (label) node.label = label;
141
+ /** A model laid out as a block would be, whether or not it is one. */
142
+ export const layoutSource = (program: Program, model: Model): LayoutSource =>
143
+ readBlock(program, model) ?? {
144
+ model,
145
+ scalar: false,
146
+ label: modelLabel(program, model),
147
+ doc: getDoc(program, model),
148
+ };
149
+
150
+ /**
151
+ * The layout of one entry of a repeated property, which JSON Forms reads from a list
152
+ * control's `options.detail`. Its scopes are relative to the entry rather than the form, so
153
+ * it is not re-scoped when the list is composed into a larger block.
154
+ *
155
+ * Without it a renderer has nothing to order the entry's fields by but the item schema, and
156
+ * a composed item spreads its fields across `allOf` branches.
157
+ */
158
+ function itemDetail(program: Program, prop: ModelProperty): UiNode | undefined {
159
+ const type = prop.type;
160
+ if (type.kind !== "Model" || !type.indexer) return undefined;
161
+ const item = type.indexer.value;
162
+ // A list of scalars has no fields of its own to lay out.
163
+ if (item.kind !== "Model") return undefined;
164
+ return emitBlockUi(program, layoutSource(program, item));
165
+ }
182
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
+
179
+ /**
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.
185
+ */
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);
183
193
  const widget = propWidget(program, prop);
184
- if (widget) node.options = { ...(node.options ?? {}), widget };
185
- if (propReadOnly(program, prop))
186
- node.options = { ...(node.options ?? {}), readonly: true };
194
+ if (description || widget)
195
+ group.options = {
196
+ ...(group.options ?? {}),
197
+ ...(description ? { description } : {}),
198
+ ...(widget ? { widget } : {}),
199
+ };
200
+ return group;
201
+ }
202
+
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;
209
+
210
+ const detail = itemDetail(program, prop);
211
+ if (detail) node.options = { ...(node.options ?? {}), detail };
187
212
 
188
- const conds = propVisibleWhen(program, prop);
189
- if (conds.length === 1) {
190
- const c = conds[0];
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 };
217
+
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];
191
229
  node.rule = {
192
- effect: "SHOW",
230
+ effect: "ENABLE",
193
231
  condition: jsonFormsCondition(c),
194
232
  };
195
233
  } else {
196
- const enabled = propEnabledWhen(program, prop);
197
- if (enabled.length === 1) {
198
- const c = enabled[0];
234
+ const readOnly = propReadOnlyWhen(program, prop);
235
+ if (readOnly.length === 1) {
236
+ const c = readOnly[0];
199
237
  node.rule = {
200
- effect: "ENABLE",
238
+ effect: "DISABLE",
201
239
  condition: jsonFormsCondition(c),
202
240
  };
203
- } else {
204
- const readOnly = propReadOnlyWhen(program, prop);
205
- if (readOnly.length === 1) {
206
- const c = readOnly[0];
207
- node.rule = {
208
- effect: "DISABLE",
209
- condition: jsonFormsCondition(c),
210
- };
211
- }
212
241
  }
213
242
  }
243
+ }
214
244
 
215
- return node;
216
- };
245
+ return node;
246
+ }
217
247
 
218
- const props = orderedProps(program, block);
219
- const elements: UiNode[] = [];
220
- const documentedStaticSections = block.sections
221
- ? [...block.sections.members.values()].filter(
222
- (member) =>
223
- getDoc(program, member) &&
224
- !props.some(
225
- (prop) => propSection(program, prop)?.name === member.name,
226
- ),
227
- )
228
- : [];
229
-
230
- if (documentedStaticSections.length && block.sections) {
231
- const emitted = new Set<string>();
232
- for (const member of block.sections.members.values()) {
233
- const description = getDoc(program, member);
234
- const members = props.filter(
235
- (prop) => propSection(program, prop)?.name === member.name,
236
- );
237
- if (!members.length && description)
238
- elements.push({ type: "Label", text: description });
239
- for (const prop of members) {
240
- elements.push(nodeForProperty(prop));
241
- emitted.add(prop.name);
242
- }
243
- }
244
- for (const prop of props)
245
- if (!emitted.has(prop.name)) elements.push(nodeForProperty(prop));
246
- } else {
247
- elements.push(...props.map(nodeForProperty));
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;
257
+ return node;
248
258
  }
249
259
 
260
+ const nodeForProperty = (prop: ModelProperty) => propertyUi(program, prop);
261
+
262
+ const props =
263
+ block.model.kind === "Model" ? layoutProps(program, block.model) : [];
264
+ const elements = props.map(nodeForProperty);
265
+
250
266
  const group: UiNode = { type: "Group", elements };
251
267
  if (block.label) group.label = block.label;
252
268
  else if (block.doc) group.label = block.doc;
253
- return applyOverrides(group, block.overrides);
269
+ return group;
254
270
  }