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
package/lib/types.tsp CHANGED
@@ -36,32 +36,34 @@ model QuestionMeta {
36
36
  id: string;
37
37
 
38
38
  /**
39
- * The entity this question is asked *about* — the `entity` half of the id.
40
- * Declared as an enum member rather than inferred from the id so it autocompletes
41
- * and is checked; `entity-id-mismatch` reports the two disagreeing.
39
+ * The entity this question is asked *about* — the `entity` half of the id. A member of an
40
+ * enum declared with `@Meta.entities`, rather than inferred from the id, so it
41
+ * autocompletes and is checked; `entity-id-mismatch` reports the two disagreeing.
42
42
  *
43
43
  * Optional for now so the fold lands without rewriting every existing question in
44
44
  * one pass. It is present on all 279 questions in practice, so a linter rule should
45
45
  * promote it to mandatory once they carry it.
46
46
  */
47
- entity?: EntityName;
47
+ entity?: unknown;
48
48
 
49
49
  version?: string;
50
50
  status?: "draft" | "stable" | "deprecated";
51
51
  classification?: BlockClassification;
52
52
  }
53
53
 
54
- /** Portable identity, lifecycle, and source metadata for a form. */
54
+ /**
55
+ * A form's identity. A platform's own identity for the form, such as its name and version
56
+ * in a submission system, belongs to that platform's library, as a decorator of its own on
57
+ * the same model.
58
+ */
55
59
  model FormMeta {
56
- /** Semantic id — e.g. "key-contacts". */
60
+ /** Semantic id — e.g. "key-contacts". Also the published schema's id and directory. */
57
61
  id: string;
58
62
 
59
- legacyFormId?: int32;
60
63
  formName: string;
61
- shortFormName: string;
62
- formVersion: string;
63
- agencyCode?: string;
64
- ombNumber?: string;
64
+
65
+ /** Revision of the form. */
66
+ revision?: string;
65
67
  }
66
68
 
67
69
  /** Source-specific constraints applied where a reusable question is composed into a form. */
@@ -73,60 +75,6 @@ model ValidationConstraints {
73
75
  pattern?: string;
74
76
  }
75
77
 
76
- enum TagName {
77
- address,
78
- phone,
79
- email,
80
- identifier,
81
- name,
82
- title,
83
- person,
84
- organization,
85
- details,
86
- generic,
87
- money,
88
- count,
89
- attachment,
90
- narrative,
91
- date,
92
- role,
93
- }
94
-
95
- enum EntityName {
96
- primaryOrg,
97
- fiscalSponsor,
98
- poc,
99
- principalInvestigator,
100
- authorizedRepresentative,
101
- project,
102
- opportunity,
103
- application,
104
- generic,
105
- }
106
-
107
- /** Mirrors the SGG frontend's WidgetTypes union. */
108
- enum WidgetName {
109
- Attachment,
110
- AttachmentArray,
111
- Checkbox,
112
- EncodedCheckboxGroup,
113
- Text,
114
- TextArea,
115
- Radio,
116
- Select,
117
- MultiSelect,
118
- Print,
119
- PrintAttachment,
120
- FieldList,
121
- Table,
122
- Budget424aSectionA,
123
- Budget424aSectionB,
124
- Budget424aSectionC,
125
- Budget424aSectionD,
126
- Budget424aSectionE,
127
- Budget424aSectionF,
128
- }
129
-
130
78
  enum Op {
131
79
  Sum,
132
80
  Subtract,
package/lib/ui.tsp CHANGED
@@ -8,28 +8,45 @@ using TypeSpec.Reflection;
8
8
 
9
9
  namespace SimplerForms.UI;
10
10
 
11
- /** Declare the ordered section set for a block. */
12
- extern dec sections(target: Model, sections: Enum);
13
-
14
- /** Assign a property (and everything under it) to one section. */
15
- extern dec section(target: ModelProperty, section: valueof EnumMember);
11
+ /**
12
+ * This model is a presentation of `form`. Its properties are sections, in order.
13
+ *
14
+ * A property inside a section is one of three things. A field reference
15
+ * (`payee: Form.payee;`) places that field as its model lays it out. A model with
16
+ * `@UI.field` places that field with the changes it lists. A model without `@UI.field` is a
17
+ * new group of only what it lists.
18
+ */
19
+ extern dec layout(target: Model, form: Model);
16
20
 
17
21
  /**
18
- * Form-scoped override table, keyed by dotted path relative to the target.
19
- * Presentation keys stay local to the form. `enabledWhen` may name an exact sibling/root
20
- * response path and equality value when a form applies behavior to a shared question.
21
- * `visibleReadOnly: true` is valid only with `readOnly: true`: it renders a visible control
22
- * backed by a read-only JSON Schema occurrence. Plain `readOnly` retains the target's historic
23
- * hidden/null behavior for technical identifiers.
22
+ * Lay out one field's contents here. Entries inside are relative to the field's type, or
23
+ * its item type for a list. The field's unlisted children follow in their declared order.
24
24
  */
25
- extern dec overrides(
26
- target: Model | ModelProperty,
27
- patch: valueof Record<unknown>
28
- );
25
+ extern dec field(target: ModelProperty, field: ModelProperty);
26
+
27
+ /** Place the referenced field's children here instead of as a group of their own. */
28
+ extern dec flatten(target: ModelProperty);
29
29
 
30
- extern dec label(target: Model | Scalar | ModelProperty, text: valueof string);
30
+ extern dec label(
31
+ target: Model | Scalar | Enum | ModelProperty,
32
+ text: valueof string
33
+ );
31
34
  extern dec helpText(target: ModelProperty, text: valueof string);
32
- extern dec widget(target: ModelProperty, widget: valueof WidgetName);
35
+ /**
36
+ * Declare the widgets a program's renderers provide, as `@versioned` declares its versions.
37
+ * The set belongs to the consuming program, not to this library: declare it once, on any
38
+ * namespace, and `@UI.widget` accepts its members. A member's string value, when it has
39
+ * one, is the name emitted; otherwise its name is.
40
+ */
41
+ extern dec widgets(target: Namespace, widgets: Enum);
42
+
43
+ /**
44
+ * Render the property with a widget declared by `@UI.widgets`. On a property whose type is
45
+ * a question with fields of its own, the widget applies to the group those fields lay out as.
46
+ * On a scalar or model, it is the widget every property of that type renders with unless the
47
+ * property names its own; a scalar passes it to the scalars that extend it.
48
+ */
49
+ extern dec widget(target: ModelProperty | Scalar | Model, widget: EnumMember);
33
50
  /** Render source-approved checkbox choices while preserving one encoded wire value. */
34
51
  extern dec encodedCheckboxGroup(
35
52
  target: ModelProperty,
@@ -44,12 +61,38 @@ extern dec visibleWhen(
44
61
  source: ModelProperty,
45
62
  equals: valueof unknown
46
63
  );
64
+ /**
65
+ * Hide the field until the source is answered with a value other than `equals` -- so while the
66
+ * source equals it, and while the source is still unanswered.
67
+ *
68
+ * The negation of `visibleWhen`, for the reason `disabledWhen` negates `enabledWhen`: a rule
69
+ * stated against the complement of a value -- "Province applies unless Country is the US" --
70
+ * would otherwise have to list every other member of a code list.
71
+ */
72
+ extern dec hiddenWhen(
73
+ target: ModelProperty,
74
+ source: ModelProperty,
75
+ equals: valueof unknown
76
+ );
47
77
  /** Keep the field visible but enable it only while the predicate holds. */
48
78
  extern dec enabledWhen(
49
79
  target: ModelProperty,
50
80
  source: ModelProperty,
51
81
  equals: valueof unknown
52
82
  );
83
+ /**
84
+ * Keep the field visible but disable it while the predicate holds.
85
+ *
86
+ * The negation of `enabledWhen`, for source rules stated against the complement of a value
87
+ * -- "Province is inactive when Country is the US, active otherwise". Enumerating every
88
+ * other member of a code list instead would produce a condition no reviewer could check
89
+ * against the sentence it came from.
90
+ */
91
+ extern dec disabledWhen(
92
+ target: ModelProperty,
93
+ source: ModelProperty,
94
+ equals: valueof unknown
95
+ );
53
96
  /** Enable the field when the source equals any one of the supplied values. */
54
97
  extern dec enabledWhenAny(
55
98
  target: ModelProperty,
package/package.json CHANGED
@@ -1,8 +1,14 @@
1
1
  {
2
2
  "name": "simpler-forms",
3
- "version": "0.1.0-alpha.0",
3
+ "version": "0.1.0",
4
4
  "description": "A TypeSpec library for specifying forms once and emitting portable form artifacts.",
5
5
  "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/agilesix/simpler-forms.git"
9
+ },
10
+ "homepage": "https://github.com/agilesix/simpler-forms#readme",
11
+ "bugs": "https://github.com/agilesix/simpler-forms/issues",
6
12
  "type": "module",
7
13
  "main": "dist/src/index.js",
8
14
  "types": "dist/src/index.d.ts",
package/src/casing.ts ADDED
@@ -0,0 +1,172 @@
1
+ import type { ModelProperty, Namespace, Program } from "@typespec/compiler";
2
+ import { resolveEncodedName } from "@typespec/compiler";
3
+ import { reportDiagnostic } from "./lib.js";
4
+ import { modelProperties } from "./model.js";
5
+
6
+ /** How a property's TypeSpec name becomes its name in every emitted artifact. */
7
+ export type PropertyCasing = "preserve" | "snake";
8
+
9
+ /**
10
+ * `firstName` to `first_name`.
11
+ *
12
+ * A word starts at each capital that follows a lowercase letter or a digit, and at the last
13
+ * capital of a run that a lowercase letter follows, so an acronym is one word: `ombNumber`
14
+ * and `OMBNumber` both become `omb_number`, and `HTTPServer` becomes `http_server`. Digits
15
+ * stay with the word before them, so `street1` and `sf424Version` become `street1` and
16
+ * `sf424_version`. A name that is already snake case is unchanged.
17
+ */
18
+ export function snakeCase(name: string): string {
19
+ return name
20
+ .replace(/([a-z\d])([A-Z])/g, "$1_$2")
21
+ .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
22
+ .toLowerCase();
23
+ }
24
+
25
+ /**
26
+ * The name a property is emitted under.
27
+ *
28
+ * `@encodedName("application/json", ...)` wins over the casing, so a name the rule
29
+ * converts badly can be stated outright.
30
+ */
31
+ export function jsonPropertyName(
32
+ program: Program,
33
+ property: ModelProperty,
34
+ casing: PropertyCasing,
35
+ ): string {
36
+ const encoded = resolveEncodedName(program, property, "application/json");
37
+ if (encoded !== property.name) return encoded;
38
+ return casing === "snake" ? snakeCase(property.name) : property.name;
39
+ }
40
+
41
+ /**
42
+ * Renames properties in a finished artifact.
43
+ *
44
+ * The emitters build every artifact in TypeSpec names, which is also what an author writes in
45
+ * a string path, so the casing is applied once, after everything that resolves a path has run.
46
+ * One table maps each TypeSpec name to its emitted name across the whole program. That keeps
47
+ * renaming independent of where in an artifact a name appears, at the cost of requiring a name
48
+ * to be emitted the same way everywhere it is declared.
49
+ */
50
+ export class Casing {
51
+ private readonly names = new Map<string, string>();
52
+
53
+ constructor(
54
+ program: Program,
55
+ private readonly casing: PropertyCasing,
56
+ ) {
57
+ const declared = new Map<string, ModelProperty>();
58
+ const visit = (namespace: Namespace): void => {
59
+ for (const model of namespace.models.values()) {
60
+ const claimed = new Map<string, ModelProperty>();
61
+ for (const property of modelProperties(model)) {
62
+ const name = jsonPropertyName(program, property, casing);
63
+ const sibling = claimed.get(name);
64
+ if (sibling) {
65
+ reportDiagnostic(program, {
66
+ code: "property-casing-collision",
67
+ target: property,
68
+ format: {
69
+ model: model.name,
70
+ first: sibling.name,
71
+ second: property.name,
72
+ name,
73
+ },
74
+ });
75
+ } else claimed.set(name, property);
76
+
77
+ const elsewhere = declared.get(property.name);
78
+ const previous = this.names.get(property.name);
79
+ if (elsewhere && previous !== name) {
80
+ reportDiagnostic(program, {
81
+ code: "property-casing-inconsistent",
82
+ target: property,
83
+ format: {
84
+ property: property.name,
85
+ name,
86
+ other: `${elsewhere.model?.name}.${elsewhere.name}`,
87
+ otherName: previous!,
88
+ },
89
+ });
90
+ } else if (!elsewhere) {
91
+ declared.set(property.name, property);
92
+ this.names.set(property.name, name);
93
+ }
94
+ }
95
+ }
96
+ for (const child of namespace.namespaces.values()) visit(child);
97
+ };
98
+ visit(program.getGlobalNamespaceType());
99
+ // The stock emitter serializes an `@example` with encoded names already applied.
100
+ for (const name of [...this.names.values()]) this.names.set(name, name);
101
+ }
102
+
103
+ /** The name a property named `key` in TypeSpec is emitted under. */
104
+ name(key: string): string {
105
+ return (
106
+ this.names.get(key) ?? (this.casing === "snake" ? snakeCase(key) : key)
107
+ );
108
+ }
109
+
110
+ /** A JSON Schema or JSON Forms layout. */
111
+ json<T>(node: T): T {
112
+ if (Array.isArray(node)) return node.map((entry) => this.json(entry)) as T;
113
+ if (!isObject(node)) return node;
114
+ return Object.fromEntries(
115
+ Object.entries(node).map(([key, value]) => {
116
+ if (key === "properties" && isObject(value))
117
+ return [key, this.keys(value, (entry) => this.json(entry))];
118
+ if (key === "required" && Array.isArray(value))
119
+ return [key, value.map((name) => this.name(name))];
120
+ if (key === "scope" && typeof value === "string")
121
+ return [
122
+ key,
123
+ value.replace(/(?<=properties\/)[^/]+/g, (name) => this.name(name)),
124
+ ];
125
+ if (key === "examples" || key === "default" || key === "const")
126
+ return [key, this.instance(value)];
127
+ return [key, this.json(value)];
128
+ }),
129
+ ) as T;
130
+ }
131
+
132
+ /** A JSON Pointer such as `/keyContacts/[]/name`. */
133
+ pointer(path: string): string {
134
+ return path
135
+ .split("/")
136
+ .map((token, index) =>
137
+ index === 0 || token === "[]"
138
+ ? token
139
+ : escapePointer(this.name(unescapePointer(token))),
140
+ )
141
+ .join("/");
142
+ }
143
+
144
+ /** Data shaped like the schema, such as an `@example` value. */
145
+ private instance(value: unknown): unknown {
146
+ if (Array.isArray(value)) return value.map((entry) => this.instance(entry));
147
+ return isObject(value)
148
+ ? this.keys(value, (entry) => this.instance(entry))
149
+ : value;
150
+ }
151
+
152
+ private keys(
153
+ value: Record<string, unknown>,
154
+ inner: (entry: unknown) => unknown,
155
+ ): Record<string, unknown> {
156
+ return Object.fromEntries(
157
+ Object.entries(value).map(([name, entry]) => [
158
+ this.name(name),
159
+ inner(entry),
160
+ ]),
161
+ );
162
+ }
163
+ }
164
+
165
+ const isObject = (value: unknown): value is Record<string, unknown> =>
166
+ typeof value === "object" && value !== null && !Array.isArray(value);
167
+
168
+ const unescapePointer = (token: string) =>
169
+ token.replaceAll("~1", "/").replaceAll("~0", "~");
170
+
171
+ const escapePointer = (token: string) =>
172
+ token.replaceAll("~", "~0").replaceAll("/", "~1");
@@ -4,3 +4,4 @@ export { blockSchemaRef } from "./shared.js";
4
4
  export * from "./meta.js";
5
5
  export * from "./ui.js";
6
6
  export * from "./validation.js";
7
+ export * from "./mapping.js";
@@ -0,0 +1,57 @@
1
+ import type {
2
+ Enum,
3
+ EnumMember,
4
+ Model,
5
+ ModelProperty,
6
+ Namespace,
7
+ } from "@typespec/compiler";
8
+ import { stateKeys } from "../lib.js";
9
+ import type {
10
+ MappingFromLink,
11
+ MappingLink,
12
+ MappingPathLink,
13
+ } from "../model.js";
14
+ import { type Ctx, push, set } from "./shared.js";
15
+
16
+ export const $targets = (ctx: Ctx, target: Namespace, targets: Enum) =>
17
+ set(ctx, stateKeys.mappingTargets, target, targets);
18
+
19
+ /**
20
+ * Accumulated rather than overwritten: one model or property carries a link per mapping.
21
+ * Two links for the same mapping are reported by `$onValidate`, not here, so the check sees
22
+ * every decorator before it decides which one is the duplicate.
23
+ */
24
+ export const $to = (
25
+ ctx: Ctx,
26
+ target: Model | ModelProperty,
27
+ mapping: EnumMember,
28
+ mappedTo: Model | ModelProperty,
29
+ ) =>
30
+ push(ctx, stateKeys.mappedTo, target, {
31
+ mapping,
32
+ mappedTo,
33
+ } satisfies MappingLink);
34
+
35
+ export const $path = (
36
+ ctx: Ctx,
37
+ target: Model,
38
+ mapping: EnumMember,
39
+ sourcePath: string,
40
+ mappedTo: ModelProperty,
41
+ ) =>
42
+ push(ctx, stateKeys.mappingPaths, target, {
43
+ mapping,
44
+ sourcePath,
45
+ mappedTo,
46
+ } satisfies MappingPathLink);
47
+
48
+ export const $from = (
49
+ ctx: Ctx,
50
+ target: Model | ModelProperty,
51
+ mapping: EnumMember,
52
+ source: Model | ModelProperty,
53
+ ) =>
54
+ push(ctx, stateKeys.mappedFrom, target, {
55
+ mapping,
56
+ source,
57
+ } satisfies MappingFromLink);
@@ -1,11 +1,25 @@
1
- import type { 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 { stateKeys } from "../lib.js";
3
- import { type Ctx, enumName, plain, publishAs, set } from "./shared.js";
10
+ import { type Ctx, enumName, plain, publishAs, set, unwrap } from "./shared.js";
11
+
12
+ /** The name a declared enum member is emitted under: its string value, or its name. */
13
+ const memberName = (member: EnumMember) =>
14
+ typeof member.value === "string" ? member.value : member.name;
4
15
 
5
16
  /**
6
17
  * `@Meta.question`: the question's stable identity, the entity it is asked about, and
7
18
  * its classification. Also establishes the JSON Schema `$id`, so this is what makes a
8
19
  * model a question rather than an ordinary model.
20
+ *
21
+ * The entity is recorded as its name now and as the member itself for `$onValidate`, which
22
+ * checks it against the declared sets once every `@Meta.entities` has run.
9
23
  */
10
24
  export const $question = (ctx: Ctx, target: Model | Scalar, meta: unknown) => {
11
25
  const m = plain(ctx, meta) as {
@@ -13,14 +27,38 @@ export const $question = (ctx: Ctx, target: Model | Scalar, meta: unknown) => {
13
27
  entity?: unknown;
14
28
  classification?: unknown;
15
29
  };
16
- if (m.entity !== undefined) m.entity = enumName(m.entity);
30
+ const entity = entityMember(meta);
31
+ if (entity) {
32
+ m.entity = memberName(entity);
33
+ set(ctx, stateKeys.entity, target, m.entity);
34
+ set(ctx, stateKeys.entityMember, target, entity);
35
+ } else if (m.entity !== undefined) {
36
+ m.entity = enumName(m.entity);
37
+ }
17
38
  if (m.classification !== undefined)
18
39
  m.classification = enumName(m.classification);
19
40
  set(ctx, stateKeys.questionMeta, target, m);
20
41
  publishAs(ctx, target, m.id);
21
42
  };
22
43
 
23
- /** `@Meta.form`: the form's identity and the provenance of the paper form it mirrors. */
44
+ /** The enum member a question meta's `entity` names, read before it is made plain. */
45
+ function entityMember(meta: unknown): EnumMember | undefined {
46
+ const member = unwrap((meta as { entity?: unknown })?.entity) as any;
47
+ return member?.kind === "EnumMember" ? (member as EnumMember) : undefined;
48
+ }
49
+
50
+ /** `@Meta.tags`: the tags the program catalogues its questions by. */
51
+ export const $tags = (ctx: Ctx, target: Namespace, tags: Enum) =>
52
+ set(ctx, stateKeys.tagSets, target, tags);
53
+
54
+ /** `@Meta.entities`: the entities the program's questions are asked about. */
55
+ export const $entities = (ctx: Ctx, target: Namespace, entities: Enum) =>
56
+ set(ctx, stateKeys.entitySets, target, entities);
57
+
58
+ /**
59
+ * `@Meta.form`: a form an applicant opens, and the data it submits. Publishes the model's
60
+ * JSON Schema, as `@Meta.question` does, so a form is a block.
61
+ */
24
62
  export const $form = (ctx: Ctx, target: Model, meta: unknown) => {
25
63
  const m = plain(ctx, meta) as { id: string };
26
64
  set(ctx, stateKeys.formMeta, target, m);
@@ -32,13 +70,14 @@ export const $form = (ctx: Ctx, target: Model, meta: unknown) => {
32
70
  * constrained scalar with no question identity, so it stays a decorator of its own
33
71
  * rather than a field of the question meta.
34
72
  */
35
- export const $tag = (ctx: Ctx, target: Model | Scalar, ...tags: unknown[]) =>
36
- set(
37
- ctx,
38
- stateKeys.tags,
39
- target,
40
- tags.map((t) => enumName(t)),
41
- );
73
+ export const $tag = (
74
+ ctx: Ctx,
75
+ target: Model | Scalar,
76
+ ...tags: EnumMember[]
77
+ ) => {
78
+ set(ctx, stateKeys.tags, target, tags.map(memberName));
79
+ set(ctx, stateKeys.tagMembers, target, tags);
80
+ };
42
81
 
43
82
  /**
44
83
  * `@Meta.role`: why a field exists in a response -- applicant input, calculated output,
@@ -138,6 +138,19 @@ export function condition(source: ModelProperty, equals: unknown) {
138
138
  };
139
139
  }
140
140
 
141
+ /** `condition`, negated. The source and value are resolved identically. */
142
+ export function negatedCondition(
143
+ source: ModelProperty,
144
+ equals: unknown,
145
+ { requiresAnswer = false }: { requiresAnswer?: boolean } = {},
146
+ ) {
147
+ return {
148
+ ...condition(source, equals),
149
+ operator: "notEquals" as const,
150
+ ...(requiresAnswer ? { requiresAnswer } : {}),
151
+ };
152
+ }
153
+
141
154
  export function countCondition(
142
155
  ctx: Ctx,
143
156
  target: ModelProperty,