@case-framework/survey-assistant 0.1.0

package/dist/references/expressions.md

@@ -0,0 +1,301 @@
+# Expressions, Conditions, Validations, Prefills
+
+Use `survey_expression` for expression work. It is the expression capability bundle:
+- `action: "context"` returns available response refs and optional existing expression locations.
+- `action: "prepare"` validates expression refs/return types and registers a candidate change set.
+- Prefer this tool over hand-written raw JSON Patch for expression-bearing locations.
+
+## JsonExpression
+
+Expression JSON has four node types:
+
+```json
+{ "type": "const", "value": { "type": "boolean", "value": true } }
+{ "type": "responseVariable", "variableRef": "<itemId>...get...<slotId>" }
+{ "type": "contextVariable", "contextType": "locale" }
+{ "type": "function", "functionName": "and", "arguments": [] }
+```
+
+Optional `editorConfig` can contain `usedTemplate`, `label`, and `description`.
+
+## Response Values And Variables
+
+Response values are typed objects:
+- string: `{ "type": "string", "value": "abc" }`
+- number: `{ "type": "number", "value": 42 }`
+- boolean: `{ "type": "boolean", "value": true }`
+- date: `{ "type": "date", "value": 1767225600000 }`
+- duration: `{ "type": "duration", "value": 3, "unit": "days" }`
+- reference: `{ "type": "reference", "value": "<optionId>" }`
+- arrays use `string[]`, `number[]`, `date[]`, `duration[]`, `reference[]`.
+
+Response variable refs use this exact string format:
+`<itemId>...<method>...<slotId>`
+
+Methods:
+- `get`: returns the current slot value.
+- `isDefined`: returns boolean true when a response exists.
+
+Never invent response refs. Use the current context response-slots scope or item details.
+The live snapshot is immutable for the whole assistant response. `survey_change` validates and
+registers a candidate; it does not change what later tools can inspect. The browser applies authorized change sets
+only after the response completes successfully. A validated candidate is intended for apply if the turn succeeds;
+it is not a dry run. For a
+request that creates dependent items, plan the complete structure first, put the source create
+operation before its dependents, and embed each dependent expression directly in its
+`create-item.item` object in one `survey_change` call. Do not create the items with
+`survey_change` and then call `survey_expression`: live inspection cannot see unapplied items
+during the same turn.
+
+Each response slot defined by a source item's config is available as
+`<sourceItemId>...get...<slotId>`, with a boolean presence check at
+`<sourceItemId>...isDefined...<slotId>`. Use the slot's actual value type to choose the
+function and constant. For example, a single-choice `reference` slot uses `eq` with a
+`reference` const; this is only one typed case, not a restriction on source item types.
+Always check the response slot value type before choosing a function:
+- Single-choice choice items return `reference`; compare them with `eq` and a `reference` const.
+- Multiple-choice choice items return `reference[]`; check selected options with `list_contains` and a `reference` const.
+- `list_contains` must receive `string[]` + `string` or `reference[]` + `reference`. Never use it with a single `reference` response.
+
+Context variable types are `locale`, `participantFlag`, `customValue`, and `customExpression`.
+
+## Functions
+
+Boolean: `and`, `or`, `not`.
+List containment: `list_contains`.
+Equality/comparison: `eq`, `gt`, `gte`, `lt`, `lte`, `in_range`.
+Numeric aggregation: `sum`, `min`, `max`.
+String equality: `str_eq`.
+Date equality: `date_eq`.
+
+Example: show an item when option "yes" is selected on choice item q1:
+
+```json
+{
+  "type": "function",
+  "functionName": "eq",
+  "arguments": [
+    { "type": "responseVariable", "variableRef": "q1...get...q1" },
+    { "type": "const", "value": { "type": "reference", "value": "yes" } }
+  ]
+}
+```
+
+Example: multiple-select contains option "apple" when the inspected response slot type is `reference[]`:
+
+```json
+{
+  "type": "function",
+  "functionName": "list_contains",
+  "arguments": [
+    { "type": "responseVariable", "variableRef": "q2...get...q2" },
+    { "type": "const", "value": { "type": "reference", "value": "apple" } }
+  ]
+}
+```
+
+## New Items With Dependencies
+
+For a newly created source and dependent, use this operation order and expression placement.
+This pattern is item-type independent: `displayConditions` is a sibling of `config` on the
+raw item, never inside `config` or `translations`.
+
+```json
+[
+  {
+    "kind": "create-item",
+    "target": { "parentItemId": "<parent-group-id-or-key>" },
+    "item": {
+      "id": "routing_choice",
+      "key": "routing_choice",
+      "itemType": "choiceItem",
+      "config": {
+        "id": "routing_choice",
+        "maxSelection": 1,
+        "shuffleOptions": false,
+        "options": [
+          { "id": "option_a", "key": "option_a" },
+          { "id": "option_b", "key": "option_b" }
+        ]
+      }
+    },
+    "translations": [
+      { "locale": "en", "contentKey": "title", "plainText": "Choose an option" },
+      { "locale": "en", "contentKey": "options.option_a.label", "plainText": "Option A" },
+      { "locale": "en", "contentKey": "options.option_b.label", "plainText": "Option B" }
+    ]
+  },
+  {
+    "kind": "create-item",
+    "target": { "parentItemId": "<parent-group-id-or-key>" },
+    "item": {
+      "id": "follow_up_a",
+      "key": "follow_up_a",
+      "itemType": "choiceItem",
+      "config": {
+        "id": "follow_up_a",
+        "maxSelection": 1,
+        "shuffleOptions": false,
+        "options": [
+          { "id": "yes", "key": "yes" },
+          { "id": "no", "key": "no" }
+        ]
+      },
+      "displayConditions": {
+        "root": {
+          "type": "function",
+          "functionName": "eq",
+          "arguments": [
+            { "type": "responseVariable", "variableRef": "routing_choice...get...routing_choice" },
+            { "type": "const", "value": { "type": "reference", "value": "option_a" } }
+          ]
+        }
+      }
+    },
+    "translations": [
+      { "locale": "en", "contentKey": "title", "plainText": "Follow-up for option A" },
+      { "locale": "en", "contentKey": "options.yes.label", "plainText": "Yes" },
+      { "locale": "en", "contentKey": "options.no.label", "plainText": "No" }
+    ]
+  },
+  {
+    "kind": "create-item",
+    "target": { "parentItemId": "<parent-group-id-or-key>" },
+    "item": {
+      "id": "follow_up_b",
+      "key": "follow_up_b",
+      "itemType": "choiceItem",
+      "config": {
+        "id": "follow_up_b",
+        "maxSelection": 1,
+        "shuffleOptions": false,
+        "options": [
+          { "id": "yes", "key": "yes" },
+          { "id": "no", "key": "no" }
+        ]
+      },
+      "displayConditions": {
+        "root": {
+          "type": "function",
+          "functionName": "eq",
+          "arguments": [
+            { "type": "responseVariable", "variableRef": "routing_choice...get...routing_choice" },
+            { "type": "const", "value": { "type": "reference", "value": "option_b" } }
+          ]
+        }
+      }
+    },
+    "translations": [
+      { "locale": "en", "contentKey": "title", "plainText": "Follow-up for option B" },
+      { "locale": "en", "contentKey": "options.yes.label", "plainText": "Yes" },
+      { "locale": "en", "contentKey": "options.no.label", "plainText": "No" }
+    ]
+  }
+]
+```
+
+Use the same placement on other interactive item types; only their `itemType`, `config`, and
+translations change. The validator makes response slots from earlier creates available to later
+creates in this one operations array.
+
+## survey_expression Mutations
+
+Item visibility:
+
+```json
+{
+  "kind": "set-item-display-condition",
+  "itemId": "followup_yes",
+  "expression": {
+    "type": "function",
+    "functionName": "eq",
+    "arguments": [
+      { "type": "responseVariable", "variableRef": "q1...get...q1" },
+      { "type": "const", "value": { "type": "reference", "value": "yes" } }
+    ]
+  }
+}
+```
+
+Component visibility:
+`set-component-display-condition` with `itemId`, `componentId`, and a boolean `expression`.
+For choice options the component id is usually the option id. For form fields or field groups, inspect item details/raw JSON first.
+
+Component disabled state:
+`set-component-disabled-condition` with `itemId`, `componentId`, and a boolean `expression`.
+
+Validation expressions:
+`set-validation-expression` with `itemId`, `validationKey`, and a boolean `expression`.
+Add a matching validation message translation when respondents need visible feedback.
+
+Prefills:
+`set-prefill` with `itemId` and a full prefill object. `when`, when present, must return boolean.
+Prefill source can be `static`, `expression`, `templateValue`, or `previousResponse`.
+
+Template values:
+`set-template-value` with `templateKey` and `templateValue`.
+The template expression should match `returnType`; `date2string` also needs `dateFormat`.
+
+Clear operations:
+`clear-item-display-condition`, `clear-component-display-condition`,
+`clear-component-disabled-condition`, `clear-validation-expression`,
+`clear-prefill`, and `clear-template-value`.
+
+## Storage Locations
+
+Item display condition:
+`/surveyItems/<itemIndex>/displayConditions/root`
+
+Component display condition:
+`/surveyItems/<itemIndex>/displayConditions/components/<componentId>`
+
+Component disabled condition:
+`/surveyItems/<itemIndex>/disabledConditions/components/<componentId>`
+
+Item validation expression:
+`/surveyItems/<itemIndex>/validations/<validationKey>`
+
+Prefills:
+`/surveyItems/<itemIndex>/prefills`
+
+Template values:
+`/templateValues/<templateValueKey>`
+
+## Prefills
+
+Prefill shape:
+
+```json
+{
+  "id": "prefill-1",
+  "target": { "type": "itemResponse" },
+  "when": { "type": "const", "value": { "type": "boolean", "value": true } },
+  "apply": "ifEmpty",
+  "source": { "type": "static", "value": { "type": "string", "value": "x" } }
+}
+```
+
+Targets:
+- `{ "type": "itemResponse" }`
+- `{ "type": "field", "fieldId": "<fieldId>" }`
+- `{ "type": "embeddedField", "optionId": "<optionId>", "fieldId": "<fieldId>" }`
+
+Sources:
+- `static`: direct ResponseValue.
+- `expression`: JsonExpression.
+- `templateValue`: `{ "key": "<templateValueKey>" }`.
+- `previousResponse`: `{ "ref": { "surveyKey"?, "itemId", "target"? }, "ifUnsupported": "skip" }`.
+
+## Template Values
+
+Template value shape:
+
+```json
+{
+  "type": "default",
+  "returnType": "string",
+  "expression": { "type": "const", "value": { "type": "string", "value": "x" } }
+}
+```
+
+Date formatting template values use `type: "date2string"`, `returnType: "string"`, and `dateFormat`.

package/dist/references/item-types.md

@@ -0,0 +1,364 @@
+# Item Types
+
+Use current context to confirm which item types are available in the registry. The default registry includes these deterministically creatable types.
+
+## group
+
+Structure/container item:
+
+```json
+{
+  "itemType": "group",
+  "config": { "items": [], "shuffleItems": false }
+}
+```
+
+Root group additionally has `config.isRoot: true`. Non-root groups should not have `isRoot`.
+Visible group title uses content key `title`.
+
+Use a group when its children form a meaningful, independently managed section or require a shared hierarchy. Do not create a group solely to render an isolated heading or a paragraph; use an `infoItem` for explanatory content and a `page-break` when a respondent page boundary is intended. A non-root group must be created empty. In the same validated proposal, create it first and then create each child with that group id in `target.parentItemId`; do not pre-populate `config.items` or use a raw patch for ordinary group creation.
+
+## Editor Presentation
+
+Every item has three distinct naming/presentation surfaces:
+- `key`: stable coding key used in expressions and response paths. Change it with `update-item-key`.
+- `metadata.itemLabel`: internal editor label, not shown to respondents. Change it with `update-item-label`.
+- `metadata.editorItemColor`: editor-only color swatch, not shown to respondents. Change it with `update-item-color`.
+
+Across editor views, an unqualified request for labels on one or more items/questions means `metadata.itemLabel`, including the visible \"Add label...\" editor control. It does not mean respondent-facing question titles, option labels, or form-field labels unless the user says so. Do not ask for clarification when the requested item set is clear; inspect/search to resolve that set when needed. Clarify only if the request explicitly spans multiple label surfaces.
+
+`update-item-color.color` must be one of the editor palette values: `#404040` (gray), `#b91c1c` (red), `#c2410c` (orange), `#a16207` (amber), `#4d7c0f` (green), `#047857` (teal), `#0369a1` (blue), `#4338ca` (indigo), `#7e22ce` (violet), `#86198f` (magenta), or `#be123c` (rose). Use it only when the user asks for editor organization or color; it must not be used to imply respondent-facing meaning.
+
+## page-break
+
+Page-break/structural item. It has no response slots. Visible title uses content key `title`.
+
+## infoItem
+
+Non-interactive content item. Config is normally an empty object. Visible body text uses content key `content`.
+For plain text, create or update `content` with typed translation operations.
+For formatted text, create or update `content` with typed translation operations using a `richText` `content` value; see rich-text-content.md.
+
+## choiceItem
+
+Interactive choice question:
+
+```json
+{
+  "itemType": "choiceItem",
+  "config": {
+    "id": "<itemId>",
+    "maxSelection": 1,
+    "shuffleOptions": false,
+    "options": [
+      { "id": "fuji", "key": "FUJI" }
+    ]
+  }
+}
+```
+
+Choice conventions:
+- `maxSelection: 1` means single select.
+- `maxSelection: null` means multiple select with no cap.
+- `maxSelection: n` means multiple select capped at n selections.
+- If the user says "multiple choice", "multiple answer", "select all that apply", "choose all", or "checkboxes", create a `choiceItem` with `maxSelection: null` unless the user gives a specific cap.
+- If the user says "choose up to N", "select at most N", or "maximum N", create a `choiceItem` with `maxSelection: N`.
+- If the user says "single choice", "choose one", or options are mutually exclusive by wording, create a `choiceItem` with `maxSelection: 1`.
+- `options[].id` is the stable option id.
+- `options[].key` is optional but should be stable and coding-friendly. When you provide it, use lowercase snake-style keys such as `other` or `opt_1`, matching the editor's choice key normalization.
+- `options[].hasDisplayCondition` is an optional boolean used by the editor to mark options that participate in branching/display logic.
+- Option labels are translations at `options.<optionId>.label`.
+- Do not use provider-specific label metadata such as `labelKey`. CASE resolves every respondent-visible option label from `options.<optionId>.label` translations.
+- CASE choice options do not currently have a separate visible option-description field. If source material has an option-specific parenthetical/note, include it in the option label or move it to nearby question content. The `survey_change` normalizer preserves shorthand `option.note`, `option.description`, `option.helpText`, and `option.footnoteMarker` by folding them into the label translation.
+- If an option has an embedded form, do not duplicate trailing completion words in both the option label and field label. The normalizer strips trailing `, namelijk`, `, please specify`, `, specify`, `, explain`, and `, toelichting` from embedded-form option labels before validation.
+- The main response slot is `<itemId>...get...<config.id>`; normally `config.id` equals item id.
+- Single select returns `reference`; multiple select returns `reference[]`.
+
+Embedded option forms:
+- There is no `allowOther` flag in the current choice item model. Do not use `allowOther` to create free-text "Other" inputs.
+- CRITICAL — exact key name: the field on the option object is `embeddedForm` (singular, one object). It is NEVER `embeddedForms` (plural) and NEVER an array. The option's recognized keys are only: `id`, `key`, `label`, `hasDisplayCondition`, `embeddedFormItemId`, `embeddedForm`. Any other key (including a typo'd/pluralized `embeddedForms`) is silently dropped during validation — no error is raised, the field simply never appears, and you must not report the change as successful if you are not certain you used the exact singular key.
+- CRITICAL — exact shape: `embeddedForm` fields are never listed directly as `embeddedForm.fields`. They must be nested inside `embeddedForm.fieldGroups`, an array of groups, each with its own `fields` array: `{ "id": "...", "fieldGroups": [ { "id": "...", "fields": [ { "id": "...", "type": "input", "controller": { "type": "input", ... } } ] } ] }`. A top-level `fields` array with no `fieldGroups` wrapper will not render anything.
+- CRITICAL — `embeddedForm` is a FLAT object with exactly two meaningful keys: `id` and `fieldGroups`. Do NOT invent an envelope like `{ "itemType": "formItem", "config": { "fields": [...] } }` — that is not a real shape, it is not schema-validated so it fails silently (no error, no visible field, the option just behaves as if it had no embedded form at all). There is no `itemType`/`config` wrapper anywhere inside `embeddedForm`; `fieldGroups` sits directly on the `embeddedForm` object itself.
+- CRITICAL — always set an explicit `id` on any option that will have an `embeddedForm` (e.g. `"id": "other"`, lowercase, coding-friendly). If you omit `id`, one is auto-generated from `label` and PRESERVES THE EXACT CASE of the label text (e.g. label "Other" auto-generates id "Other", not "other") — you cannot reliably predict it, and every embedded-form translation content key (`embeddedForms.<optionId>...`) and response slot (`embedded.<optionId>...`) must match that exact generated id, including case. Setting an explicit lowercase `id` yourself removes this guesswork entirely.
+- To attach input controls to a choice option, put an `embeddedForm` on that option. It uses the same `FormItemConfig` shape as a `formItem` (`id` + `fieldGroups`), but it is embedded directly on the option object — it is never a separate `formItem` sibling and never uses `embeddedFormItemId` unless you are intentionally referencing a shared/reusable form item defined elsewhere (rare; prefer inline `embeddedForm`).
+- The embedded form renders only while that option is selected. When the option is deselected, existing embedded responses are cleared after user confirmation.
+- Embedded form translation keys are prefixed with `embeddedForms.<optionId>`; for example `embeddedForms.other.fields.other_text.label`. Note this translation content-key prefix IS plural (`embeddedForms`) even though the config field on the option is singular (`embeddedForm`) — these are two different things; do not confuse them.
+- Embedded form response slots are `embedded.<optionId>.<fieldKey>`; for example `embedded.other.other_text`.
+- Use `create-item` with embedded form config and matching translations when creating a new choice item. For an existing choice option, first call `survey_inspect` with `action: "raw-json"` and the choice item reference; copy the returned survey-root item path (for example `/surveyItems/<choiceIndex>`) rather than constructing a path from `/config`. Then use one `survey-json-patch` operation with one plural `patches` array for every related configuration and translation update until a dedicated typed helper exists.
+- MANDATORY: every embedded form field needs a matching `embeddedForms.<optionId>.fields.<fieldId>.label` translation entry in the SAME operation that creates it. There is no fallback/derived label text — a field without this translation renders with no visible label (only its raw type, e.g. "Input") to respondents. Before returning a create-item or raw-patch result, check that you added exactly one label translation per embedded form field you defined.
+
+Example "Other, please specify" option:
+
+```json
+{
+  "id": "other",
+  "key": "other",
+  "embeddedForm": {
+    "id": "other",
+    "fieldGroups": [
+      {
+        "id": "other_details",
+        "layout": { "base": 1, "xs": 1, "sm": 1, "md": 1, "xl": 1 },
+        "fields": [
+          {
+            "id": "other_text",
+            "key": "other_text",
+            "type": "input",
+            "required": true,
+            "controller": { "type": "input", "inputMode": "text" },
+            "validations": []
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Matching translation keys on the choice item:
+- `options.other.label`: "Other"
+- `embeddedForms.other.fields.other_text.label`: "Please specify"
+- Optional placeholder: `embeddedForms.other.fields.other_text.placeholder`
+- Additional embedded field content keys follow the same form-field families as a top-level form item, for example:
+  - `embeddedForms.other.fields.other_text.description`
+  - `embeddedForms.other.fields.other_text.error`
+  - `embeddedForms.other.fields.other_text.unit`
+  - `embeddedForms.other.fields.other_text.checkedLabel`
+  - `embeddedForms.other.fields.other_text.uncheckedLabel`
+  - `embeddedForms.other.fields.other_text.options.<optionId>.label`
+  - `embeddedForms.other.fields.other_text.validations.<validationId>.message`
+  - `embeddedForms.other.fieldGroups.<groupId>.title`
+  - `embeddedForms.other.fieldGroups.<groupId>.description`
+
+### Full worked example: create a choiceItem with an embedded "Other" text field
+
+One `create-item` operation carries the whole item plus every translation it needs — the option labels AND the embedded form field label:
+
+```json
+{
+  "kind": "create-item",
+  "target": { "parentItemId": "<root-group-id-or-key>", "index": 1 },
+  "item": {
+    "id": "choice_2",
+    "key": "choice_2",
+    "itemType": "choiceItem",
+    "config": {
+      "id": "choice_2",
+      "maxSelection": 1,
+      "shuffleOptions": false,
+      "options": [
+        { "id": "strawberry", "key": "strawberry" },
+        { "id": "blueberry", "key": "blueberry" },
+        {
+          "id": "other",
+          "key": "other",
+          "embeddedForm": {
+            "id": "other",
+            "fieldGroups": [
+              {
+                "id": "other_details",
+                "layout": { "base": 1, "xs": 1, "sm": 1, "md": 1, "xl": 1 },
+                "fields": [
+                  {
+                    "id": "other_text",
+                    "key": "other_text",
+                    "type": "input",
+                    "required": true,
+                    "controller": { "type": "input", "inputMode": "text" },
+                    "validations": []
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    }
+  },
+  "translations": [
+    { "locale": "en", "contentKey": "title", "plainText": "Favorite berry" },
+    { "locale": "en", "contentKey": "options.strawberry.label", "plainText": "Strawberry" },
+    { "locale": "en", "contentKey": "options.blueberry.label", "plainText": "Blueberry" },
+    { "locale": "en", "contentKey": "options.other.label", "plainText": "Other" },
+    { "locale": "en", "contentKey": "embeddedForms.other.fields.other_text.label", "plainText": "Please specify" }
+  ]
+}
+```
+
+Notice `config.id` equals the item id, every option has a label translation, and the embedded field has its own label translation under the `embeddedForms.other.*` prefix — omitting any one of these leaves that piece of UI blank.
+
+### Full worked example: create a multiple choice question
+
+Use `maxSelection: null` for "select all that apply" / checkbox-style questions:
+
+```json
+{
+  "kind": "create-item",
+  "target": { "parentItemId": "<root-group-id-or-key>", "index": 1 },
+  "item": {
+    "id": "industries_worked",
+    "key": "industries_worked",
+    "itemType": "choiceItem",
+    "config": {
+      "id": "industries_worked",
+      "maxSelection": null,
+      "shuffleOptions": false,
+      "options": [
+        { "id": "healthcare", "key": "HEALTHCARE" },
+        { "id": "education", "key": "EDUCATION" },
+        { "id": "food_service", "key": "FOOD_SERVICE" }
+      ]
+    }
+  },
+  "translations": [
+    { "locale": "en", "contentKey": "title", "plainText": "Which industries have you worked in? Select all that apply." },
+    { "locale": "en", "contentKey": "options.healthcare.label", "plainText": "Healthcare" },
+    { "locale": "en", "contentKey": "options.education.label", "plainText": "Education" },
+    { "locale": "en", "contentKey": "options.food_service.label", "plainText": "Food service" }
+  ]
+}
+```
+
+## formItem
+
+Interactive form question:
+
+```json
+{
+  "itemType": "formItem",
+  "config": {
+    "id": "<itemId>",
+    "fieldGroups": [
+      {
+        "id": "main",
+        "layout": { "base": 1, "xs": 1, "sm": 1, "md": 1, "xl": 1 },
+        "fields": []
+      }
+    ]
+  }
+}
+```
+
+CRITICAL — the item's `config` object has exactly two meaningful keys: `id` and `fieldGroups`. `fieldGroups` sits directly on `config` — never nest it under another wrapper, and never put a top-level `fields` array directly on `config` (fields must be inside a `fieldGroups` entry). Fields need at least one non-empty `fieldGroups` entry with an actual `fields` array to be useful; an empty `fieldGroups: [{ "fields": [] }]` is only a starting scaffold, not a finished item.
+
+Field group config:
+- `id`: stable group id.
+- `hasDisplayCondition`: optional boolean used by the editor to mark groups that participate in branching/display logic.
+- `layout`: column counts by container breakpoint, using positive integers 1 through 4.
+
+Example field group layout:
+
+```json
+{
+  "id": "main",
+  "hasDisplayCondition": true,
+  "layout": { "base": 1, "xs": 1, "sm": 2, "md": 2, "xl": 3 },
+  "fields": []
+}
+```
+
+Field group translations:
+- `fieldGroups.<groupId>.title`
+- `fieldGroups.<groupId>.description`
+
+Field shape:
+
+```json
+{
+  "id": "age",
+  "key": "AGE",
+  "type": "number",
+  "required": true,
+  "controller": { "type": "number", "step": 1 },
+  "validations": []
+}
+```
+
+Field types and default controllers:
+- `input`: `{ "type": "input", "inputMode": "text" }`
+- `textarea`: `{ "type": "textarea", "rows": 3 }`
+- `number`: `{ "type": "number", "step": 1 }`
+- `datepicker`: `{ "type": "datepicker", "mode": "year-month-day" }`
+- `switch`: `{ "type": "switch", "defaultChecked": false }`
+- `select`: `{ "type": "select", "options": [] }`
+- `slider`: `{ "type": "slider", "min": 0, "max": 100, "step": 1, "defaultValue": 50, "showValue": true }`
+
+Supported controller properties by type:
+- `input`: `placeholder`, `inputMode`, `autocomplete`
+- `textarea`: `placeholder`, `rows`
+- `number`: `placeholder`, `step`, `unit`, `defaultValue`
+- `datepicker`: `placeholder`, `mode` where mode is `year`, `year-month`, or `year-month-day`
+- `switch`: `checkedLabel`, `uncheckedLabel`, `defaultChecked`
+- `select`: `placeholder`, `allowClear`, `options`
+- `slider`: `min`, `max`, `step`, `defaultValue`, `showValue`
+
+Select controller option shape:
+
+```json
+{ "id": "weekly", "value": "weekly" }
+```
+
+Visible select-option labels do NOT live in the controller config. They live in translations at `fields.<fieldId>.options.<optionId>.label`.
+If a select controller option has `id: "minder_7_dagen", value: "minder_7_dagen"`, the visible Dutch label still needs a separate translation such as `fields.<fieldId>.options.minder_7_dagen.label`: "minder dan 7 dagen". Without this translation, respondents see the raw key/value in the dropdown.
+
+Field translation keys:
+- `fields.<fieldId>.label`
+- `fields.<fieldId>.description`
+- `fields.<fieldId>.error`
+- `fields.<fieldId>.placeholder`
+- `fields.<fieldId>.unit`
+- `fields.<fieldId>.checkedLabel`
+- `fields.<fieldId>.uncheckedLabel`
+- `fields.<fieldId>.options.<optionId>.label`
+- `fields.<fieldId>.validations.<validationId>.message`
+
+Validation configs use `{ "id", "type", "value"?, "message"? }`.
+Supported validation types: `required`, `minLength`, `maxLength`, `pattern`, `email`, `url`, `integer`, `min`, `max`, `minDate`, `maxDate`, `mustBeTrue`.
+
+MANDATORY: every field needs a matching `fields.<fieldId>.label` translation entry in the SAME operation that creates it. There is no fallback/derived label text — a field without this translation renders with no visible label (only its raw type, e.g. "Input") to respondents. Before returning a create-item or raw-patch result, check that you added exactly one label translation per field you defined.
+MANDATORY: every `select` option needs a matching `fields.<fieldId>.options.<optionId>.label` translation entry in the SAME operation that creates it. Do not rely on `controller.options[].label`; generated survey JSON strips option labels from config and restores them from translations. Missing select option translations render raw values such as `minder_7_dagen`.
+
+### Full worked example: create a formItem with two fields
+
+```json
+{
+  "kind": "create-item",
+  "target": { "parentItemId": "<root-group-id-or-key>", "index": 1 },
+  "item": {
+    "id": "form_1",
+    "key": "form_1",
+    "itemType": "formItem",
+    "config": {
+      "id": "form_1",
+      "fieldGroups": [
+        {
+          "id": "main",
+          "layout": { "base": 1, "xs": 1, "sm": 1, "md": 1, "xl": 1 },
+          "fields": [
+            {
+              "id": "age",
+              "key": "AGE",
+              "type": "number",
+              "required": true,
+              "controller": { "type": "number", "step": 1 },
+              "validations": []
+            },
+            {
+              "id": "comments",
+              "key": "COMMENTS",
+              "type": "textarea",
+              "controller": { "type": "textarea", "rows": 3 },
+              "validations": []
+            }
+          ]
+        }
+      ]
+    }
+  },
+  "translations": [
+    { "locale": "en", "contentKey": "title", "plainText": "About you" },
+    { "locale": "en", "contentKey": "fields.age.label", "plainText": "Your age" },
+    { "locale": "en", "contentKey": "fields.comments.label", "plainText": "Any comments?" }
+  ]
+}
+```