@case-framework/survey-assistant 0.8.0 → 0.9.0

package/dist/references/expressions.md

@@ -10,16 +10,17 @@ Use `survey_expression` for expression work. It is the expression capability bun
 
 ## JsonExpression
 
-Expression JSON has four node types:
+Expression JSON has five node types:
 
 ```json
 { "type": "const", "value": { "type": "boolean", "value": true } }
 { "type": "responseVariable", "variableRef": { "slotId": "<slotId>", "method": "get" } }
 { "type": "contextVariable", "contextType": "locale" }
 { "type": "function", "functionName": "and", "arguments": [] }
+{ "type": "ownerState", "state": "disabled", "targetRef": { "ownerId": "<ownerId>" } }
 ```
 
-Optional `editorConfig` can contain `usedTemplate`, `label`, and `description`.
+Optional `editorConfig` contains only `usedTemplate`, `label`, and `description`; unknown keys are rejected. Missing argument-array operands are `null`, preserving their positions across JSON round trips. Required gaps are unfinished expressions, not false values. Optional single children such as a context key are omitted properties.
 
 ## Response Values And Variables
 
@@ -57,8 +58,7 @@ component's visibility. Repair rejected changes using the returned retry linkage
 Hidden answers remain stored for the session and return when shown again, but are unavailable
 to expressions, validation, scoring and submission while hidden. `get` returns undefined and
 `isDefined` returns false for an inactive answer. This includes hidden groups, matrix rows,
-form groups, hidden choice options and unselected embedded fields. Display conditions with
-undefined or non-boolean results hide their target. Visibility cannot use `customExpression`
+semantic sections, hidden choice options and unselected follow-up inputs. With no visibility condition the target is visible. An authored visibility expression returning missing or false makes it inactive; a defined non-boolean result is inactive with a diagnostic. Visibility cannot use `customExpression`
 callbacks; supply serialized `customValue` context instead.
 
 Never invent response refs. Use the current context response-slots scope or item details.
@@ -87,15 +87,30 @@ Always check the response slot value type before choosing a function:
 - 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`.
+Context variable types are `locale`, `currentDate`, `participantFlag`, and `customValue`.
+`{ "type": "contextVariable", "contextType": "currentDate" }` returns the participant's current
+day as a full `date`. It takes no key; the host fixes it when the session starts and records it with
+the response, so submission validation and export replay see the same day. Opaque callbacks (`customExpression`) are not part of the grammar; use recorded custom values so player, submission validation and export replay agree.
 
 ## Functions
 
 Boolean: `and`, `or`, `not`.
 List containment: `list_contains`.
+List counting: `list_count(list)` returns the number of entries in any array value;
+`list_count(list, filter)` counts only entries that also appear in `filter`, a list of the same
+type. A missing list (for example an unanswered multiple choice) counts as `0`; use `isDefined`
+to tell unanswered from none selected. For "at least two of these options selected":
+`gte(list_count(<reference[] ref>, const(reference[], ["<optionId>", ...])), const(number, 2))`.
+Filter option ids must be declared option identities, as with `list_contains`.
 Equality/comparison: `eq`, `gt`, `gte`, `lt`, `lte`, `in_range`.
 Numeric aggregation: `sum`, `min`, `max`.
 String equality: `str_eq`.
+Conditional value: `if(condition, then, else)` returns `then` when the boolean condition is true
+and `else` when it is false; only the chosen branch is evaluated. `else` is optional (missing when
+omitted), and a missing condition returns missing rather than `else`. The result type is the
+branches' type: both branches must have the same type, and the usage checks it like any other
+result (e.g. a score uses number branches, a visibility condition boolean branches). Nest `if`
+calls for more than two cases, e.g. `if(c1, a, if(c2, b, c))`.
 Calendar dates use `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`; numeric timestamps and date-time strings are invalid. Preserve the answer's precision.
 
 Date comparisons: `date_eq`, `date_gt`, `date_gte`, `date_lt`, `date_lte` (two date arguments).
@@ -104,18 +119,34 @@ Equality includes precision; ordering requires matching precision and returns un
 `date_add_days`, `date_add_months`, `date_add_years` take a date and a signed integer number.
 Offsets retain precision; month/year offsets clamp to the last day of the destination month.
 Nonzero day offsets require full dates, nonzero month offsets require at least month precision.
-`date_diff(a, b)` returns signed `a - b`, in days for full dates, months for month values,
-or years for year values. Both arguments must have matching precision. Missing arguments' values
-propagate undefined; do not use timestamps or divide by seconds to calculate calendar differences.
-
-Form and form-matrix `minDate` / `maxDate` rules can use `valueExpression` instead of `value`.
-Use a date response reference or date arithmetic expression. For example, a latest date seven days
-after another answer uses `date_add_days(responseVariable(...), const(number, 7))`.
-Use the form-field or matrix configuration operation to set these field rules. The normal expression
-operations remain appropriate for item validations, prefills, and display conditions.
-Bounds are inclusive: minimum uses the start of its calendar period, maximum uses its end.
-The entire answer period must fit within the bound. An unanswered optional date remains valid;
-a supplied answer with an unresolved bound fails validation until the source is available.
+`date_diff(a, b, unit)` returns the signed number of completed units in `a - b`. `unit` is a
+required string const: `"years"`, `"months"`, or `"days"`. Mixed precisions are compared at the
+coarser one (a year-only birth date gives calendar-year differences), and a unit finer than that
+precision returns undefined. Missing values propagate undefined; do not use timestamps or divide
+days to calculate ages. Age in years:
+`date_diff(contextVariable(currentDate), responseVariable(<birth date>), const(string, "years"))`.
+For an "at least N years old" check, use `gte(date_diff(...), const(number, N))`, which works
+for every birth-date precision. The anniversary form
+`date_lte(date_add_years(<birth date>, N), currentDate)` only works for full `YYYY-MM-DD` birth
+dates: for a year or month birth date it compares mismatched precisions and returns undefined.
+For full dates the two agree except on February 29 birthdays, which reach an anniversary on
+February 28 with the anniversary form and on March 1 with `date_diff`.
+
+Number and date inputs (and form-matrix number/date fields) take `min` / `max` bounds that are a
+literal or `{expression, fallback?}`. Use a response reference or arithmetic expression of the
+input's type. For example, a latest date seven days after another answer uses
+`date_add_days(responseVariable(...), const(number, 7))`. When the expression has no value (for
+example the referenced answer is empty), the bound does not apply, unless it has a `fallback`.
+Slider bounds from an expression require a `fallback`.
+Use set-config-expression with path `/min/expression` or `/max/expression` relative to the element
+config; an existing literal bound becomes the fallback. clear-config-expression on the same path
+restores the fallback, or removes a bound without one. The normal expression operations remain
+appropriate for item validations, prefills, and display conditions.
+Date bounds are inclusive: minimum uses the start of its calendar period, maximum uses its end.
+The entire answer period must fit within the bound. An unanswered optional date remains valid.
+A bound whose expression has no value does not apply, unless it has a `fallback`; then the
+fallback applies. Fixed bounds and fallbacks must leave at least one valid answer at the input's
+precision.
 
 Example: show an item when option "yes" is selected on choice item q1:
 
@@ -169,51 +200,72 @@ Example: multiple-select contains option "apple" when the inspected response slo
 
 ## 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`.
+For a newly created source and dependent, use this operation order and expression placement. This pattern is element-type independent: `visibility` is on its owner, beside `config`, never inside translations. A flow item condition applies to its complete body; an element condition applies only to that element. Replace `<root-group-id>` with the inspected root group ID.
 
 ```json
 [
   {
     "kind": "create-item",
     "target": {
-      "parentItemId": "<parent-group-id>"
+      "parentItemId": "<root-group-id>"
     },
     "item": {
-      "id": "routing_choice",
-      "itemType": "choiceItem",
+      "id": "routing",
+      "itemType": "content",
       "config": {
-        "id": "routing_choice",
-        "maxSelection": 1,
-        "shuffleOptions": false,
-        "options": [
-          {
-            "id": "option_a",
-            "code": "option_a"
-          },
-          {
-            "id": "option_b",
-            "code": "option_b"
-          }
-        ],
-        "variableName": "routing_choice"
+        "body": {
+          "blocks": [
+            {
+              "kind": "layout",
+              "id": "routing-layout",
+              "layout": {
+                "mode": "automatic",
+                "maxColumns": 1
+              },
+              "elements": [
+                {
+                  "kind": "element",
+                  "id": "routing-choice",
+                  "elementType": "choice",
+                  "config": {
+                    "slotId": "routing-slot",
+                    "variableName": "routing_choice",
+                    "presentation": "radio",
+                    "options": [
+                      {
+                        "id": "routing-a",
+                        "code": "A"
+                      },
+                      {
+                        "id": "routing-b",
+                        "code": "B"
+                      }
+                    ]
+                  }
+                }
+              ]
+            }
+          ]
+        }
       }
     },
     "translations": [
       {
+        "ownerId": "routing",
+        "role": "title",
         "locale": "en",
-        "contentKey": "title",
         "plainText": "Choose an option"
       },
       {
+        "ownerId": "routing-a",
+        "role": "label",
         "locale": "en",
-        "contentKey": "options.option_a.label",
         "plainText": "Option A"
       },
       {
+        "ownerId": "routing-b",
+        "role": "label",
         "locale": "en",
-        "contentKey": "options.option_b.label",
         "plainText": "Option B"
       }
     ]
@@ -221,259 +273,184 @@ raw item, never inside `config` or `translations`.
   {
     "kind": "create-item",
     "target": {
-      "parentItemId": "<parent-group-id>"
+      "parentItemId": "<root-group-id>"
     },
     "item": {
-      "id": "follow_up_a",
-      "itemType": "choiceItem",
+      "id": "routing-followup-a",
+      "itemType": "content",
       "config": {
-        "id": "follow_up_a",
-        "maxSelection": 1,
-        "shuffleOptions": false,
-        "options": [
-          {
-            "id": "yes",
-            "code": "yes"
-          },
-          {
-            "id": "no",
-            "code": "no"
-          }
-        ],
-        "variableName": "follow_up_a"
-      },
-      "displayConditions": {
-        "root": {
-          "type": "function",
-          "functionName": "eq",
-          "arguments": [
+        "body": {
+          "blocks": [
             {
-              "type": "responseVariable",
-              "variableRef": {
-                "slotId": "routing_choice",
-                "method": "get"
-              }
-            },
-            {
-              "type": "const",
-              "value": {
-                "type": "reference",
-                "value": "option_a"
-              }
+              "kind": "layout",
+              "id": "routing-followup-a-layout",
+              "layout": {
+                "mode": "automatic",
+                "maxColumns": 1
+              },
+              "elements": [
+                {
+                  "kind": "element",
+                  "id": "routing-followup-a-text",
+                  "elementType": "text",
+                  "config": {
+                    "slotId": "routing-followup-a-slot",
+                    "variableName": "followup_a",
+                    "presentation": "long"
+                  }
+                }
+              ]
             }
           ]
         }
+      },
+      "visibility": {
+        "type": "function",
+        "functionName": "eq",
+        "arguments": [
+          {
+            "type": "responseVariable",
+            "variableRef": {
+              "slotId": "routing-slot",
+              "method": "get"
+            }
+          },
+          {
+            "type": "const",
+            "value": {
+              "type": "reference",
+              "value": "routing-a"
+            }
+          }
+        ]
       }
     },
     "translations": [
       {
+        "ownerId": "routing-followup-a",
+        "role": "title",
         "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"
+        "plainText": "Details for option A"
       }
     ]
   },
   {
     "kind": "create-item",
     "target": {
-      "parentItemId": "<parent-group-id>"
+      "parentItemId": "<root-group-id>"
     },
     "item": {
-      "id": "follow_up_b",
-      "itemType": "choiceItem",
+      "id": "routing-followup-b",
+      "itemType": "content",
       "config": {
-        "id": "follow_up_b",
-        "maxSelection": 1,
-        "shuffleOptions": false,
-        "options": [
-          {
-            "id": "yes",
-            "code": "yes"
-          },
-          {
-            "id": "no",
-            "code": "no"
-          }
-        ],
-        "variableName": "follow_up_b"
-      },
-      "displayConditions": {
-        "root": {
-          "type": "function",
-          "functionName": "eq",
-          "arguments": [
-            {
-              "type": "responseVariable",
-              "variableRef": {
-                "slotId": "routing_choice",
-                "method": "get"
-              }
-            },
+        "body": {
+          "blocks": [
             {
-              "type": "const",
-              "value": {
-                "type": "reference",
-                "value": "option_b"
-              }
+              "kind": "layout",
+              "id": "routing-followup-b-layout",
+              "layout": {
+                "mode": "automatic",
+                "maxColumns": 1
+              },
+              "elements": [
+                {
+                  "kind": "element",
+                  "id": "routing-followup-b-text",
+                  "elementType": "text",
+                  "config": {
+                    "slotId": "routing-followup-b-slot",
+                    "variableName": "followup_b",
+                    "presentation": "long"
+                  }
+                }
+              ]
             }
           ]
         }
+      },
+      "visibility": {
+        "type": "function",
+        "functionName": "eq",
+        "arguments": [
+          {
+            "type": "responseVariable",
+            "variableRef": {
+              "slotId": "routing-slot",
+              "method": "get"
+            }
+          },
+          {
+            "type": "const",
+            "value": {
+              "type": "reference",
+              "value": "routing-b"
+            }
+          }
+        ]
       }
     },
     "translations": [
       {
+        "ownerId": "routing-followup-b",
+        "role": "title",
         "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"
+        "plainText": "Details for option B"
       }
     ]
   }
 ]
 ```
 
-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
+The validator makes response slots from earlier creates available to later creates in this one operations array. This example creates separate conditional questions. For content directly below a radio/checkbox option, use an option-inline follow-up instead; it already has an activation gate.
 
-The shapes below are the canonical mutations. Send the complete array once as `mutations`; the
-server validates every entry against these canonical shapes before changing the request-scoped
-draft.
+## Disabled state and applicability
 
-Item visibility:
+`ownerState` with `state: "disabled"` is the stored form of `isDisabled(owner)`. It reads the configured and inherited disabling of an inspected structural owner. It always returns boolean. It does not report visibility, answer presence or whether a choice cap permits a change. Answer and state dependencies share one cycle-checked graph. A parent reading its own child's disabled state is cyclic because the child inherits from that parent.
 
-```json
-{
-  "kind": "set-item-display-condition",
-  "itemId": "followup_yes",
-  "expression": {
-    "type": "function",
-    "functionName": "eq",
-    "arguments": [
-      {
-        "type": "responseVariable",
-        "variableRef": {
-          "slotId": "q1",
-          "method": "get"
-        }
-      },
-      {
-        "type": "const",
-        "value": {
-          "type": "reference",
-          "value": "yes"
-        }
-      }
-    ]
-  }
-}
-```
+Active disabled answers are retained, readable in expressions and submitted. Participant writes are rejected while the whole input or an ancestor is disabled; initialization has its separate engine-owned path. Validation cannot block on targets the participant cannot change. Disabled checkbox options are locked; single-choice replacement can leave a disabled selection for an enabled destination. Hidden answers remain unavailable instead. Use visibility for “not applicable” and disabled for locking, not as a way of removing answers from data.
 
-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.
+“Selected and enabled” is an authoring shortcut expanded into `and(selectionTest, not(ownerState(...)))`. Use eq for single choice, list_contains for checkbox selection. It is not a new persisted function. Disabled ancestors also make this false, including intentionally read-only prefilled items. Do not use the shortcut where the condition should still honor such answers. Mutual selected-and-enabled disabling may create a cycle; ordinary selection-based exclusivity avoids adding that state loop.
 
-Component disabled state:
-`set-component-disabled-condition` with `itemId`, `componentId`, and a boolean `expression`.
+## Creation and expression mutations
 
-Validation expressions:
-`set-validation-expression` with `itemId`, `validationKey`, and a boolean `expression`.
-Add a matching validation message translation when respondents need visible feedback.
+Create source owners before their dependents. New owners may carry `visibility`, `disabled`, prefills and validation expressions in their creation payloads. For existing owners, use `survey_expression` with these mutations:
 
-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`.
+- `set-condition`: `ownerId`, `property` (`visibility` or `disabled`), boolean `expression`.
+- `clear-condition`: the same owner and property; absent visibility means visible and absent disabling means enabled, subject to ancestors.
+- `set-config-expression`: `elementId`, inspected config-relative JSON Pointer `path`, and `expression`. The exact field must be declared as an expression by the installed element schema, including custom definitions.
+- `clear-config-expression`: the same element and path; schema-required fields cannot be cleared.
+- `set-validation-rule`: `itemId` and complete `rule` (`id`, nonempty `targets` slot IDs, boolean `expression`, optional boolean `when`, optional `phase: page|submit`). Its localized message belongs to that rule ID's `message` role.
+- `remove-validation-rule`: `itemId`, `ruleId`.
+- `set-prefill`: `elementId`, `slotId`, complete `prefill`.
+- `clear-prefill`: `elementId`, `slotId`, `prefillId`.
+- `set-template-value`: `templateKey`, complete `templateValue`.
+- `clear-template-value`: `templateKey`.
 
-Template values:
-`set-template-value` with `templateKey` and `templateValue`.
-The template expression should match `returnType`; `date2string` also needs `dateFormat`.
+Inspect exact owner IDs and expression locations. Conditions live directly on their annotated owner; prefills live at `element.prefills[slotId]`; validation rules live in `contentItem.config.validationRules`. Never reconstruct a location from a display label or old component path. Rules target slots owned by their item and cannot block when no target is active and changeable.
 
-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>`
+Page rules that read another item's answers can prevent reaching those answers on a later page. Inspect the shared `cross-item-page-rule` advisory; use submit-phase validation or an explicit unanswered-dependency condition when appropriate. Do not silently change an existing rule's phase.
 
 ## Prefills
 
-Prefill shape:
+Prefills initialize **once** when creating a new session, including hidden inputs, disabled inputs and closed follow-ups. They do not reapply while answering, after clearing a field, or on resume. A resumed session restores its versioned snapshot without new prefill lookups. Hiding/disabling retains initialized and participant-entered answers. Never use repeated prefilling to enforce exclusivity.
+
+A prefill has `id`, optional boolean `when`, optional `apply: "ifEmpty"`, and `source`. Its target is the surrounding element's slot key, not an itemResponse/field/embeddedField descriptor.
 
 ```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"
-    }
+  "kind": "set-prefill",
+  "elementId": "name-input",
+  "slotId": "name-slot",
+  "prefill": {
+    "id": "name-initial",
+    "source": { "type": "static", "value": { "type": "string", "value": "Example" } }
   }
 }
 ```
 
-Targets:
-
-- `{ "type": "itemResponse" }`
-- `{ "type": "field", "fieldId": "<fieldId>" }`
-- `{ "type": "embeddedField", "optionId": "<optionId>", "fieldId": "<fieldId>" }`
-
-Sources:
+Sources are static typed value, expression, templateValue key, or previousResponse with `ref: {surveyKey?, slotId}` and optional `ifUnsupported: "skip"`. Inspect host capabilities before depending on previous responses. Values must match the target slot's domain; scores/computed slots are not prefill targets. Prefill dependencies also participate in cycle checking.
 
-- `static`: direct ResponseValue.
-- `expression`: JsonExpression.
-- `templateValue`: `{ "key": "<templateValueKey>" }`.
-- `previousResponse`: `{ "ref": { "surveyKey"?, "itemId", "target"? }, "ifUnsupported": "skip" }`.
+Do not assume a host provides previous responses. Survey Mode currently does not; it rejects publication with a required unsupported source. Use `ifUnsupported: "skip"` only when omitting that initial value is intentional. Invalid derived prefill values are skipped with a located diagnostic and later candidates may apply; do not treat that as permission to author incompatible values.
 
 ## Template Values
 
@@ -493,7 +470,7 @@ Template value shape:
 }
 ```
 
-Date formatting template values use `type: "date2string"`, `returnType: "string"`, and `dateFormat`.
+Date formatting template values use `type: "formatDate"`, `returnType: "string"`, and `dateFormat`.
 
 ## Bounded context and atomic batches