@case-framework/survey-assistant 0.7.0 → 0.9.0

package/dist/references/element-types.md

@@ -0,0 +1,189 @@
+# Element authoring
+
+Use the live registry capability and generated schema as the configuration authority. These notes explain behavior; they are not a second schema. A content item containing one element is the default way to author an ordinary question. Use `insert-preset` for a configured starting point, then inspect allocated IDs before editing or referencing it. Multiple elements, layouts and sections are available when the content actually requires them.
+
+## group
+
+A flow group is a hierarchy/container with `config: {items: [], shuffleItems: false}`. Only the existing root has `isRoot: true`. Create a non-root group empty, then add children in parent-before-child order. Groups have no respondent-facing content roles; use their editor label for author organization. For a visible heading, add a content item with a title or an information element. Use groups for meaningful nested survey structure, information elements for standalone explanation and page breaks for page boundaries. Within a single content item, use semantic sections rather than flow groups.
+
+## Editor Presentation
+
+Every item has three distinct naming/presentation surfaces:
+
+- `editorName`: resolved display name returned by inspection; use the persistent item ID for edits. Response coding belongs to slots, not item names; change it with `update-response-settings`.
+- `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 input 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 provided in the `survey_change` tool contract. 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 or respondent-facing content roles. Use an editor label to identify it while authoring. If a visible page heading is needed, place it on a content item following the break.
+
+## information
+
+Display-only rich content in owner role `body`, with no response slot. It occupies a full row. Use for standalone explanation or instructions within a composed item. Keep actual respondent prompts as inputs; blanks in source documents are not decorative text. Item title/subtitle/footer remain separate optional surfaces.
+
+## text
+
+A string input with `presentation: "short"` or `"long"`, persistent `slotId` and coding `variableName`. Optional purpose is text/email/tel/url/password; multiline rows and browser autocomplete are independent settings. Roles include label, help, placeholder and validation message. A placeholder never replaces an accessible label. Port source instructions as help or item subtitle, preserving existing constraints. Use required and the supported validation rules rather than a prose-only requirement.
+
+## number
+
+A numeric input or slider with a persistent slot and variable name. Preserve step, minimum, maximum, value display and localized unit. Slider presentation does not change response identity or type. Pick bounds and units from the user or source; do not invent constraints. Put domain limits in `min`/`max` (a number or `{expression, fallback?}`) and use the `integer` validation for whole numbers.
+
+## date
+
+Reuse the calendar input with `precision` of `year`, `year-month` or `year-month-day`. Answers are calendar strings `YYYY`, `YYYY-MM`, `YYYY-MM-DD`, never timestamps. Precision, regional display format and survey language are separate. Preserve configured precision, localized parser messages and inclusive bounds. Config `min`/`max` bounds are a calendar string or `{expression, fallback?}` relative to another answer; use calendar arithmetic, not timestamp conversion.
+
+## boolean
+
+A boolean response with switch or radio presentation. False is an answer, not missing; use explicit comparisons when a condition means Yes. Localized yes/no labels are element roles. A standalone boolean and a matrix boolean share response semantics, but their context-specific UI and validation presentation differ.
+
+## choice
+
+Use `presentation: "radio"`, `"checkbox"` or `"dropdown"`. If the user says “multiple choice”, “multiple answer”, “select all that apply”, “choose all”, or “checkboxes”, use checkbox with `maxSelection: null` unless they give a cap. “Choose up to N” uses checkbox with `maxSelection: N`, even for N=1. “Single choice” or “choose one” uses radio; an explicit dropdown request uses dropdown. Radio and dropdown answers are `reference`; checkboxes return `reference[]`. Options have stable IDs, optional export codes and localized label/description owner roles. Checkboxes require `maxSelection` (null for unlimited or a positive cap). Radio/dropdown configuration has no maxSelection field.
+
+Radio and checkbox lists take a full row and may own option-inline follow-ups. Dropdowns may share a layout row and cannot own follow-ups. Every option needs visible localized wording; codes and IDs are not fallback labels. Preserve ordered scales, endpoints, shuffling and coding conventions. Use matrix elements for repeated common scales when appropriate.
+
+Create the requested presentation directly. When explicitly changing an existing radio/dropdown to checkbox or the reverse, the answer type changes: assign a fresh `slotId` and inspect and repair dependencies; existing responses are not converted. Radio/dropdown changes retain the slot ID. Keep option IDs and translations, remove dropdown-only placement when changing to a full-width list, and never drop follow-ups to force a dropdown conversion. Radio lists permit clearing; preserve that behavior with `allowClear: true` when converting one to a dropdown.
+
+Use visibility for options that become inapplicable: hidden selections are retained locally but excluded from active answers and submission. Disabled visible options retain active selections. Disabled checkboxes are locked both ways; enabled options can still change if the cap permits. A disabled radio/dropdown selection may be replaced by an enabled destination, but cannot be directly cleared while locked. Disabling the element or ancestors locks the whole choice.
+
+Exclusivity is authored through expressions, with no special exclusive-option feature. In valid states the selected side must remain enabled so it can be deselected. For “None of these”, disable it when any ordinary option is selected and disable ordinary options when None is selected. Conflicting prefills or changing earlier answers can lock a checked option. Audit checkbox disabling that reads outside its own selection and prefer visibility when the real intent is inapplicability. Do not silently clear answers to fix a conflict.
+
+`isDisabled` state reads can support selected-and-enabled conditions, but do not automatically add them to mutual disabling rules: that can create a real cycle. Inherited disabled states count, so a deliberately read-only prefilled answer is still selected but will fail a selected-and-enabled test. Ordinary answer comparisons usually fit such read-only cases.
+
+## consent
+
+Use one consent element for each independent permission. A containing item or section supplies a title and optional supporting introduction; the consent element owns its full `body` translation and records an explicit agreement or refusal. Both title and body are needed in each participant language, with an explicit element label or unambiguous enclosing title. Use an information element for information that does not ask for a decision.
+
+Organize the participant-facing content in the owner-role content surfaces:
+
+- `title` on the containing item/section: the main heading identifying the agreement or permission. Prefer the supplied document's main heading when available. This field stays visible on the question card and names the dialog unless `label` overrides it; do not put the only title inside the body.
+- `subtitle` on the containing item, or `description` on the containing section: an optional brief introduction or reading instruction directly below the title. Leave it out when no separate introduction is needed.
+- `label`: optional rich consent-specific heading. Empty inherits the nearest appropriate section/item title in the same locale. Supply only when a distinct local heading is useful; it appears above the inline document or in the dialog summary and dialog heading.
+- `subtitle` on the consent element: optional rich consent-specific introduction, used only with `config.subtitleMode="custom"`.
+- `body`: the actual content the participant needs to read before deciding, including the agreement, terms, or explanation of the permission. It is the document itself, not a description, summary, or instruction to read an absent document. Avoid repeating the question title as an opening body heading; retain meaningful section headings, paragraphs, lists, and links within the document. Follow an explicit request to preserve the source verbatim.
+
+Follow supplied content: preserve its terms and meaning instead of replacing it with generic wording, silently changing its meaning, or adding unrequested provisions. When helping create new wording, be proactive: write useful, concrete draft terms and make reasonable creative choices from the available context. Do the useful work first, then identify the result as a draft and explain material assumptions or missing details in your reply. Do not present invented wording as facts or as a document supplied by the user. Use placeholders sparingly for details the user must supply, while still drafting the substantive content. Do not fill `body` with only a description of a document or a statement agreeing to unspecified terms elsewhere. Ask a focused question before acting only when useful progress is blocked, such as when exact reproduction requires unavailable source text. Missing optional details are a reason to note gaps afterward, not to delay a useful draft.
+
+Config supports `presentation`: `"inline"` (preset default) or `"dialog"`, and `subtitleMode`: `"inherit"` (preset default), `"custom"`, or `"none"`. Subtitle mode applies to all languages. Inherit uses the semantic context subtitle; custom uses `subtitle` on the consent element for the current locale (empty stays absent); none omits the consent subtitle. The question subtitle remains visible in every mode. Inherited title/subtitle are not repeated inline or in the dialog summary, but are shown inside the dialog. Custom titles also identify the inline consent and dialog summary. Custom subtitles appear above the inline document or inside the dialog, never in the dialog summary.
+
+Optional plain `acceptLabel` and `declineLabel` translations override choice wording. `unansweredLabel`, `acceptedLabel`, and `declinedLabel` override dialog status; `reviewLabel` and `changeLabel` override dialog actions. Empty values use the host UI defaults. Close, missing-title and unavailable-information messages belong to host player localization; do not create item translations for them. Languages without host translations require host localization for those generic messages. There is no separate decision heading. Without existing response data there is no automatic selection. Consent supports the ordinary initial-response and element-owned prefill paths using the boolean slot identified by `config.slotId`. There is no `required` setting or config effects list. Closing the dialog leaves the answer unchanged.
+
+The element has a persistent `id`; config has an independent persistent `slotId`, plus an editable `variableName` (for example `research_consent`). Presets allocate IDs; complete authored nodes supply explicit IDs. Inspect preset results before referencing them. Boolean true means agreement, false means refusal, and absence means unanswered. Compare `{ "slotId": "<config.slotId>", "method": "get" }` with a boolean constant. `isDefined` tests either recorded decision. Never use the literal `accepted` as a universal slot ID.
+
+To show a section only after agreement, place the agreement expression on the dependent item's, group's or section's `visibility` expression. Hiding retains previously entered answers in the session but omits hidden items from submission and subsequent exports; showing the section again restores them. Navigation rules target explicit slots on their content item and must not require a particular consent decision unless the user requested that rule.
+
+## choiceMatrix
+
+Toolbox presets have exact server-supported IDs on `insert-preset.presetId`:
+
+| User wording           | presetId                   | Actual toolbox defaults                              |
+| ---------------------- | -------------------------- | ---------------------------------------------------- |
+| Yes / No matrix        | `choiceMatrix.yesNo`       | Yes, No; scores 1, 2                                 |
+| 5-point scale / Likert | `choiceMatrix.fivePoint`   | Strongly disagree through Strongly agree; scores 1–5 |
+| 7-point scale / Likert | `choiceMatrix.sevenPoint`  | Seven agreement options; scores 1–7                  |
+| 5-point bipolar scale  | `choiceMatrix.bipolarFive` | Five numbered options, scores 1–5, `bipolar: true`   |
+
+These are editable starting configurations, not fixed measurement instruments. Use `insert-preset` with `elementType: "choiceMatrix"`, the advertised preset ID, locale and flow/layout target. The bipolar preset does NOT imply scores −2…2: request those scores explicitly when wanted. Labels come from the shared toolbox factory (English, Dutch, German). Inspect the result before editing generated IDs. If custom anchors and rows are already known, author the complete element directly with explicit IDs and translations in one create/insert operation. Existing toolbox elements are ordinary matrices and remain editable.
+
+Match the response wording to the question's construct: agreement labels answer statements, while liking, satisfaction, frequency and intensity need corresponding anchors. Preserve exact toolbox wording when the user explicitly requests those defaults. When custom anchors are already known, include the complete ordered `element.config.options` with explicit stable IDs, scores and matching `label` translations on each option owner in the creation operation; these define the custom scale. This creates the intended scale directly without a second pass over generated IDs. For later edits, copy the existing IDs exactly and preserve them.
+
+Use a choice matrix for several row statements sharing the same categorical scale. Persistent IDs identify the element, rows, options, per-row computed scores and total. `variableNamePrefix` and each `rowName` derive survey-wide unique names: `<variableNamePrefix>_<rowName>`, `<variableNamePrefix>_<rowName>_score` and `<variableNamePrefix>_sum`. Inspect declared slots; do not synthesize IDs from those names.
+
+```json
+{
+  "id": "wellbeing_matrix",
+  "kind": "element",
+  "elementType": "choiceMatrix",
+  "config": {
+    "variableNamePrefix": "wellbeing",
+    "sumSlotId": "wellbeing_total",
+    "rows": [{ "id": "sleep_answer", "scoreSlotId": "sleep_score", "rowName": "sleep" }],
+    "options": [
+      { "id": "never", "code": "never", "score": 0 },
+      { "id": "always", "code": "always", "score": 4 }
+    ],
+    "layout": "automatic"
+  }
+}
+```
+
+Create with a containing item `title`, and `label` roles on `sleep_answer`, `never` and `always`. Option scores are numeric scoring semantics; codes are export strings and labels are translated wording. Supply all scores or leave them all absent. Optional `leadingNonScoring`/`trailingNonScoring` each hold ONE `{id, code?}` object (never an array and never a score). Each participates in answers but not scoring. There is at most one leading and one trailing non-scoring choice; a second at the same end requires an explicit product decision, not silently overwriting the first. Optional bipolar endpoints use `startLabel`/`endLabel` on the matrix element. Layout accepts `automatic`, `stacked` or `matrix`; `rowLabelPosition` accepts `beside` or `above`.
+
+Stored row answers are `reference` values containing exact option IDs. Computed score and sum slots are read-only and excluded from default exports unless explicitly included. A non-scoring or unanswered row has no score; a numeric score of zero is a defined score. The sum is absent when no visible rows have scored answers. Required rows use `required: true`. Use config patches for structural row/option/layout edits, translations for visible text, and `update-response-settings` for naming components, export codes and formats. Preserve surviving IDs. Reinspect expression diagnostics after removing slots/options.
+
+### Editing a choice matrix
+
+Inspect the current config before choosing array indices. Put all related patches and new translations in one `patch-element-config` operation. Example adding a final “Don't know” answer:
+
+```json
+{
+  "kind": "patch-element-config",
+  "elementId": "<inspected element ID>",
+  "patches": [
+    { "op": "add", "path": "/trailingNonScoring", "value": { "id": "dont_know", "code": "DK" } }
+  ],
+  "translations": [
+    { "locale": "en", "ownerId": "dont_know", "role": "label", "plainText": "Don't know" }
+  ]
+}
+```
+
+- Add a row at `/rows/-` with fresh `id`, `scoreSlotId`, unique `rowName` and its `label` role translation. Duplicate by copying the row settings and all relevant locales into NEW IDs. Keep surviving IDs unchanged.
+- Remove rows/options with `remove` at the inspected index; reorder with `move` or replace the complete inspected array without changing IDs. `copy` alone duplicates IDs and is invalid. Remove or repair dependent expressions in the same turn.
+- Add scale options at `/options/-` with `id`, optional `code`, and a score if the existing scale is scored. Include the option owner's `label` role. To disable scoring, remove every scale score in one operation. To reverse scoring, reverse score VALUES in the existing options; do not reorder options or labels. For zero-based/one-based/bipolar scoring, assign 0…n−1 / 1…n / −(n−1)/2…(n−1)/2 to all scale options in one patch. Non-scoring choices stay outside this array.
+- Add or remove `/leadingNonScoring` or `/trailingNonScoring` as object properties. To move a non-scoring option from one end to the other, preserve its ID and label. To switch an option between scale and non-scoring roles, move the same ID atomically and add/remove its score appropriately.
+- Set `/bipolar` true and translate `startLabel` and `endLabel` on the matrix element for endpoints. Set `/rowLabelPosition` to `beside` or `above`. Layout and positive `stackingBreakpoint` affect presentation, not responses.
+- Row display conditions use `survey_expression` mutation `set-condition` with `ownerId` equal to the row ID and `property: "visibility"`; required-row messages use the row owner's `message` role. Whole-question visibility uses `set-condition` on the item/element owner. Use only targets declared by the installed matrix schema; never infer support from an arbitrary property in raw JSON.
+
+## formMatrix
+
+Use a form matrix for independent row/column cells, with a column-level field type and optional cell `fieldOverride`s. Names derive from `<variableNamePrefix>_<rowName>_<columnName>`; IDs and existing answers survive naming, ordering and layout edits. Every row/column intersection needs a persistent cell object, including static or empty cells, although only interactive cells declare response slots.
+
+```json
+{
+  "id": "visits_matrix",
+  "kind": "element",
+  "elementType": "formMatrix",
+  "config": {
+    "variableNamePrefix": "visits",
+    "rows": [{ "id": "visit_row", "rowName": "baseline" }],
+    "columns": [
+      {
+        "id": "weight_column",
+        "columnName": "weight_kg",
+        "field": { "type": "number", "unit": "kg", "validations": [] }
+      }
+    ],
+    "cells": [{ "id": "baseline_weight", "rowId": "visit_row", "columnId": "weight_column" }],
+    "layout": "automatic"
+  }
+}
+```
+
+Translate the containing item `title`, row `label`, column `label`, and cell-specific `label`/`description` when needed. Field types are `text` (optional multiline), `number` (step/unit), `date` (`precision` `year`, `year-month`, `year-month-day`), `dropdown` (options `[{id,code}]`), `boolean`, `static`, `empty`. Interactive field definitions carry `validations: []` and optional `required`. Dropdown answers contain option IDs; visible option labels use the option owner's `label` role. Cell `fieldOverride`s use the same field schema. Static cells use the cell owner's `content` role. Use the capability's declared content surfaces for localization.
+
+### Editing a form matrix
+
+Config patches handle structural cells, overrides, columns and rows. Every structural edit must produce a complete rectangle in ONE `patch-element-config` operation.
+
+A field-type change that changes a cell's answer value type needs a fresh cell ID. Replace only affected input cells, including inherited column defaults; preserve cells with unchanged effective types or independent overrides. Moving an input to an empty/static cell also retires its answer ID. Preserve owner content in every locale and explicitly repair references, prefills and export settings. Inspect before patching; do not reuse an old ID for a different answer type.
+
+- For multi-row/column duplication, inspect the current arrays first, then construct the complete desired rows, columns and cells while retaining all surviving objects and IDs. Replacing these arrays together can be clearer than a long chain of index-sensitive patches. A duplicate is an addition; never rename or repurpose its source. Keep existing coding unchanged; choose short coding components for new units.
+  Before constructing the patch, map EVERY new cell to its source cell by row and column. Copy the complete source object, including its override and conditions, then remap identities and coordinates; apply explicitly requested differences last. Do not start duplicates from bare `{id,rowId,columnId}` cells: those are appropriate only for genuinely new, default-inheriting cells.
+  For example, when copying row A to B AND column X to Y, three cells copy A/X: A/Y, B/X and B/Y. If A/X has an independent dropdown override, all three copies need that override, each with fresh option/rule IDs and the source translations. B/Y must not fall back to Y's default field just because both coordinates are new. Unchanged existing cells keep their original IDs and settings.
+  After applying the patch, compare each mapped cell's effective field and owner content with its source, including the new row/new column intersection. Schema validation proves the rectangle is legal, not that its content was faithfully copied.
+- Adding a row also adds one fresh `{id,rowId,columnId}` cell per existing column; adding a column adds a cell for every row. Removing a row/column removes its associated cells in the same patch. The executor automatically cleans translations owned by removed components in every locale; inspect the result before attempting any extra raw translation removals. Reordering rows/columns changes only array order; preserve cell IDs and coordinates.
+- A column's `field` defines inherited settings. A cell `fieldOverride` is a COMPLETE field definition, not a partial patch; use `add` at `/cells/<index>/fieldOverride` when absent, or replace it when already present. Its content belongs to the cell ID. Reset it with `remove` to inherit the column again. Static and empty cells remain in `cells`, but have no response slot. Changes that preserve the answer value type retain cell IDs; retyping follows the fresh-ID rule above, including when resetting an override changes the effective type.
+- Shared field content belongs to the column owner's role; overridden content belongs to the cell owner's role. Column headers always use the column owner's `label` role. Roles are `label`, `description`, `placeholder`, `message`, `content`, `yesLabel`, `noLabel`. Static text belongs to the column owner's `content` role when inherited or the cell owner's `content` role when overridden. Number `unit` is a config string, not a content key.
+- Dropdown fields use `options: [{id,code}]`, with globally distinct component IDs and the option owner's `label` role translations. For an independent cell override copied from a shared dropdown, allocate new option and validation IDs and copy their translations in all existing locales. Reusing column-owned option/rule IDs in an override is invalid. Duplicate rows/columns the same way: new unit and cell IDs; deep-copy every existing override with new option/rule IDs and translated content. An override on the source must remain an override on the duplicate; omitting it silently changes that cell to the column default. After duplication, compare source and destination effective field types, settings, option codes and translated content, allowing only explicitly requested differences.
+- Interactive fields can provide `validations: []` when no constraints are needed. Required is the field's boolean `required` property. Text validations: `minLength`, `maxLength`, `pattern`; number: `integer`; boolean: `mustBeTrue`; date and dropdown have no additional rules. Each rule has a fresh `id`, `type`, and a `value` where needed. Number and date fields take range bounds as field properties `min`/`max`, each a literal (number, or calendar string matching precision such as `2026-09`) or `{expression, fallback?}`. A bound whose expression has no value is ignored unless it has a `fallback`. Rule messages are the rule owner's `message` role; required and bound messages are the field owner's `message` role. Fixed minimum cannot exceed maximum.
+- Column `width` and `rowLabelWidth` accept `{mode:"default"}`, `{mode:"fixed",pixels:160}`, or `{mode:"fit",minPixels:120}` (numeric minima 48). Layout is `automatic`, `stacked`, or `matrix`; `stackingBreakpoint` is a positive pixel width. Boolean arrangement is `horizontal` or `vertical`; text uses `multiline`; dates use `precision`; numbers use `step` and `unit`.
+- Put new visible translations inside the patch operation; blank or incorrect namespaces are rejected. For row visibility, use `survey_expression` mutation `set-condition` with the row `ownerId` and `property: "visibility"`. Whole-question visibility uses `set-condition` on the item/element owner. Inspect the declared condition targets before adding other component conditions. Hidden-row answers are retained in the session and restored when shown, but excluded from expressions, validation, scoring and submission while hidden.
+
+Coding uses one matrix naming edit with `elementId`, `prefix` (written to `variableNamePrefix`), `rows` and/or `columns`; never set arbitrary names or headers on derived cells. A shared dropdown code change affects all cells using that option set. Keep numeric scores, identities and translated wording separate from coding changes.