@case-framework/survey-core 0.7.0 → 0.9.0

package/README.md

@@ -1,178 +1,185 @@
 # @case-framework/survey-core
 
-Headless TypeScript core for defining, editing, running, and exporting surveys in the CASE ecosystem.
+Headless TypeScript contracts for defining, editing, running, and exporting CASE
+surveys. No React, network, persistence, or assistant dependency is required.
 
-## Intention
+See [Composable architecture](https://github.com/case-framework/case-survey-toolkit/blob/main/docs/composition-architecture.md) for the
+complete document, identity, localization, expression, and host contracts.
 
-`@case-framework/survey-core` is the domain/runtime layer behind CASE surveys. It is designed to:
+## Public entry points
 
-- Provide a framework-agnostic survey model.
-- Support custom item types through a plugin registry.
-- Evaluate display logic, validations, and template expressions at runtime.
-- Produce normalized responses and export-ready data (including CSV).
+- `@case-framework/survey-core`: schemas, `Survey`, element registration,
+  `SurveyStateGraph`, `SurveySession`, expressions, response values, and export.
+- `@case-framework/survey-core/editor`: `SurveyEditor`, field/history integration,
+  copy/remapping, and response naming.
+- `@case-framework/survey-core/editor/colors`: editor color helpers.
+- `@case-framework/survey-core/schema`: data schemas for protocol consumers.
 
-## Scope
+The survey format is version 3; submitted responses are version 2; retained
+participant session snapshots are version 1. Unsupported formats are rejected.
+There are no legacy readers or converters.
 
-This package includes:
+## Breaking changes
 
-- Survey model and serialization (`Survey`).
-- Item contracts and registry utilities (`SurveyItemCore`, `createItemCore`, `createFullRegistry`).
-- Runtime engine (`SurveyEngineCore`) for render order, conditions, template values, events, and responses.
-- Expression model + evaluator (`Expression`, `FunctionExpression`, `ExpressionEvaluator`, etc.).
-- Response models (`SurveyResponse`, `SurveyItemResponse`, `ResponseItem`).
-- Response export tooling (`SurveyResponseExporter`, CSV helpers, codebook generation).
-- Editor state/manipulation APIs via the `@case-framework/survey-core/editor` entrypoint.
+The composition cutover intentionally replaces these APIs; there are no aliases:
 
-This package does not include:
+- `SurveyEditor.undoRedo` is now `SurveyEditor.history`.
+- The former `survey`, `survey/utils`, `expressions`, and `engine` source barrels
+  are consolidated in the root export. Use the public entry points above.
+- Import `SURVEY_EDITOR_ITEM_COLORS` from `@case-framework/survey-core/editor/colors`,
+  rather than the package root.
 
-- UI rendering components.
-- Network or persistence layers.
-- App-level state management.
+Survey Mode must update its imports and history access when adopting this version.
 
-For UI integration, use `@case-framework/survey-ui` on top of this core package.
+## Load and run
 
-## Installation
-
-```bash
-pnpm add @case-framework/survey-core
+```ts
+import { Survey, SurveySession } from "@case-framework/survey-core";
+import { defaultElementRegistry } from "@case-framework/survey-items";
+
+const survey = Survey.parse(savedDefinition, defaultElementRegistry);
+const session = await SurveySession.create(survey, {
+  mode: "new",
+  binding: { sessionId: "session-1", definitionId: "release-1" },
+  context: { locale: "en" },
+});
+session.write([{ slotId: "name-slot", value: { type: "string", value: "Example" } }]);
+const submission = session.submission("response-1");
+const snapshot = session.snapshot();
+const resumed = await SurveySession.create(survey, {
+  mode: "resumed",
+  binding: { sessionId: "session-1", definitionId: "release-1" },
+  snapshot,
+});
 ```
 
-## Entrypoints
+The example slot must be declared by the loaded definition. Writes reject unknown
+slots, incompatible values, computed targets, and disabled controls. Hidden answers
+are retained but excluded from ordinary expressions and submission. Disabled
+visible answers remain active. Prefills run only for new sessions. Resume checks
+binding and restores retained values without reapplying prefills.
 
-- `@case-framework/survey-core`: runtime/model/expressions/exporter APIs.
-- `@case-framework/survey-core/editor`: editing APIs (`SurveyEditor`, undo/redo, copy/paste helpers).
+A host must authorize the participant and select the exact collecting definition.
+`validateSurveySubmission(survey, input, trustedContext, { definitionId })` rejects a
+response recorded against another definition, validates the envelope and domains,
+recomputes active answers/validation, and records server-owned context.
+Do not trust client-supplied visibility, disabling, or identity as authorization.
 
-## Usage
+## Editing and extension
 
-### 1. Define a custom item type and registry
+Elements are plain data with stateless definitions from `defineElement`. One
+annotated schema declares configuration, identities, references, wording, and
+follow-up bodies. `createElementRegistry` supplies the shared recursive body.
+See the architecture guide for a custom definition example.
 
 ```ts
-import {
-  SurveyItemCore,
-  ValueRefTypeLookup,
-  ValueType,
-  ItemTypeRegistry,
-} from "@case-framework/survey-core";
-
-type SingleChoiceConfig = {
-  id: string;
-  options: Array<{ id: string; key: string; type: string }>;
-};
-
-class SingleChoiceQuestionItemCore extends SurveyItemCore<
-  "singleChoiceQuestion",
-  SingleChoiceConfig
-> {
-  readonly type = "singleChoiceQuestion";
-
-  parseConfig(rawConfig: unknown): SingleChoiceConfig {
-    const cfg = (rawConfig ?? {}) as Partial<SingleChoiceConfig>;
-    return {
-      id: cfg.id ?? this.id,
-      options: cfg.options ?? [],
-    };
-  }
-
-  isInteractive(): boolean {
-    return true;
-  }
-
-  getAvailableResponseValueSlots(): ValueRefTypeLookup {
-    return {
-      [`${this.id}...get...${this.config.id}`]: ValueType.reference,
-      [`${this.id}...isDefined...${this.config.id}`]: ValueType.boolean,
-    };
-  }
-}
-
-const pluginRegistry: ItemTypeRegistry = {
-  singleChoiceQuestion: SingleChoiceQuestionItemCore,
-};
+import { SurveyEditor } from "@case-framework/survey-core/editor";
+import { createBuiltInElement } from "@case-framework/survey-items";
+
+const editor = new SurveyEditor(survey);
+const names = new Set(survey.slots.definitions.map((slot) => slot.variableName));
+const element = createBuiltInElement("text", names);
+const { itemId } = editor.insertElement(element);
+editor.setLocalizedContent({ scope: "content", ownerId: itemId, role: "title" }, "en", {
+  type: "plain",
+  content: "Your name",
+});
 ```
 
-### 2. Load a survey and run it with the engine
+Without a layout target, `insertElement` creates a standalone content item.
+User and assistant edits share the same transactions and undo/redo. Parsing and
+rendering never allocate IDs. Copies allocate/remap owned identities; moves keep
+them. `survey.slots`, `survey.owners`, and `survey.elements` are derived indexes.
 
-```ts
-import {
-  Survey,
-  SurveyEngineCore,
-  ResponseItem,
-  ValueType,
-  ReservedSurveyItemTypes,
-} from "@case-framework/survey-core";
-
-const survey = Survey.fromJson(
-  {
-    $schema:
-      "https://github.com/case-framework/case-survey-toolkit/packages/survey-core/schemas/survey-schema.json",
-    surveyItems: [
-      {
-        id: "root",
-        key: "root",
-        itemType: ReservedSurveyItemTypes.Group,
-        config: { isRoot: true, items: ["q1"] },
-      },
-      {
-        id: "q1",
-        key: "q1",
-        itemType: "singleChoiceQuestion",
-        config: {
-          id: "q1",
-          options: [
-            { id: "yes", key: "yes", type: "option" },
-            { id: "no", key: "no", type: "option" },
-          ],
-        },
-      },
-    ],
-  },
-  pluginRegistry,
-);
-
-const engine = new SurveyEngineCore(survey, { locale: "en" });
-
-// Set one item response (slot id == config.id in this example).
-engine.setResponse("q1", new ResponseItem([["q1", { type: ValueType.reference, value: "yes" }]]));
-
-const pages = engine.getSurveyPages("large");
-const responses = engine.getResponses();
-const events = engine.getEvents();
-```
+## Expressions
 
-### 3. Export responses to CSV
+Canonical JSON nodes replace runtime expression classes. Editor builders return
+these nodes directly with `getExpression()`. Array operand gaps are `null`.
+`collectExpressionDependencies` includes answer and disabled-state references;
+`visitExpression`, `transformExpression`, and `remapExpression` handle the grammar
+exhaustively. Never find or rewrite references by matching arbitrary JSON strings.
+Registered custom callbacks are not serialized expression behavior: hosts record
+custom values so server validation and export can replay the same context.
+
+`list_count(list, filter?)` counts array entries (a missing list counts as 0), optionally
+only those also present in a same-typed `filter` list. `if_else(condition, then, else?)`
+serializes as the `if` function: it evaluates only the chosen branch, returns missing for
+a missing condition, and takes its result type from the branches, which must match.
+
+## Export
 
 ```ts
 import { SurveyResponse, SurveyResponseExporter } from "@case-framework/survey-core";
 
-const response = new SurveyResponse("response-1", "v1");
-response.responses = new Map(responses.map((r) => [r.itemId, r]));
-response.submittedAt = Math.floor(Date.now() / 1000);
-
+const response = SurveyResponse.deserialize(submission);
 const exporter = new SurveyResponseExporter([
-  {
-    versionId: "v1",
-    surveyKey: survey.surveyKey ?? "survey",
-    survey,
-  },
+  { schema: survey, responses: [response], sourceId: "release-1" },
 ]);
-
-const csv = exporter.exportResponsesToCsv([response]);
+const csv = exporter.exportResponsesToCsv();
 ```
 
-### 4. Edit surveys with the editor entrypoint
+Responses store flat `answers[slotId]`, event/metadata state, and recorded context.
+The host supplies the exact definition in every export batch. Computed slots are
+replayed from active stored answers, not accepted as participant writes. Events use
+millisecond instants; calendar answers below use calendar strings.
+
+Names use unique lowercase snake_case (maximum 32 characters). Atomic naming edits
+use slot IDs or `{ elementId, prefix?, rows?, columns? }` for matrices. Export codes
+and variable names never change answer identity. Categorical values use declared
+option IDs, including dropdowns and matrix cells.
+
+`ExporterProfile` has `schemaVersion: 1`. Slot overrides use exact slot IDs;
+column headers/order use stable encoded column IDs. Existing categorical modes,
+boolean mappings, masks, date formatting, number precision, and duration units
+remain available. Missing answers are blank; answered empty selections differ
+from missing answers. Invalid codes, names, or profile targets are diagnostics.
+
+## Calendar dates
+
+Date responses and expression constants store calendar strings, not Unix timestamps:
+`{ type: "date", value: "2026-09-20" }`. Year (`"2026"`) and month (`"2026-09"`)
+precision are preserved; `date[]` stores arrays of these strings. Numeric dates and
+ISO date-time strings are rejected. This is a breaking response and expression API change;
+there is no implicit conversion of old timestamp data. Actual event timestamps retain their
+existing instant semantics.
+
+Use `const_date("2026-09-20")`, `response_date(ref)`, and the `date_eq`, `date_gt`,
+`date_gte`, `date_lt`, `date_lte`, `date_min`, `date_max` builders. Equality includes
+precision; ordering/min/max require matching precision. `date_add_days`,
+`date_add_months`, and `date_add_years` accept a date expression and signed integer
+number expression. They preserve precision and clamp month-end dates. Nonzero offsets
+cannot require finer precision than the input. `date_diff(a, b, unit)` returns the signed
+number of completed `"years"`, `"months"`, or `"days"` in a-b, comparing mixed precisions at
+the coarser one; a unit finer than that precision returns undefined. Missing values,
+ordering precision mismatches, and arithmetic outside years 0001–9999 return undefined.
+Calendar arithmetic uses date-fns on UTC dates, so results do not depend on the host timezone.
+
+`ctx_current_date()` reads the session's current date. A new session defaults it to the
+participant-local day at start (`context.currentDate`, `YYYY-MM-DD`), keeps it across
+context refreshes and resume, and records it in the response's `evaluationContext` for
+submission validation and export replay. Hosts may pass it explicitly. Age in years is
+`date_diff(ctx_current_date(), response_date(birthRef), "years")`.
+
+Presence is the element's `required` flag. Number and date inputs (and matrix fields) take
+`min`/`max` bounds that are a literal or an expression of the input's type, with an optional
+`fallback`. For example:
 
 ```ts
-import { SurveyEditor, CommitSource } from "@case-framework/survey-core/editor";
-
-const editor = new SurveyEditor(survey, { pluginRegistry });
+const min = {
+  expression: date_add_days(
+    response_date({ slotId: "start-slot", method: "get" }),
+    const_number(2),
+  ).getExpression()!,
+};
+```
 
-const newItem = survey.createItemFromRaw({
-  id: "q2",
-  key: "q2",
-  itemType: "singleChoiceQuestion",
-  config: { id: "q2", options: [] },
-});
+Bounds evaluate against current responses, including after the source answer changes.
+Date minimums use the start of their period, maximums the end; an answer's entire period
+must fit. Optional unanswered fields pass. A bound whose expression has no value does not
+apply unless it has a `fallback`; slider bounds from an expression require one. Other
+checks (lengths, pattern, email, url, integer, must be true) are element `validations`, and
+custom expression rules live on the content item. Registered domain validators receive an expression evaluator alongside the active-answer reader.
 
-editor.addItem({ parentId: survey.rootItem!.id }, newItem);
-editor.commit({ label: "Add q2", source: CommitSource.USER });
-```
+Default exports preserve the calendar string. Custom formatting and date templates are
+timezone-independent; partial dates retain their canonical value even if a pattern requests
+missing components. Use local Date adapters only at calendar-widget boundaries.

package/build/answer-types-DH0gv0Ea.d.mts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+//#region src/schema/answer-types.d.ts
+/** Tuple entries preserve opaque IDs such as __proto__ across JSON/schema roundtrips. */
+declare const answerTypeReservationsSchema: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodEnum<{
+  readonly string: "string";
+  readonly duration: "duration";
+  readonly reference: "reference";
+  readonly number: "number";
+  readonly boolean: "boolean";
+  readonly date: "date";
+  readonly stringArray: "string[]";
+  readonly durationArray: "duration[]";
+  readonly referenceArray: "reference[]";
+  readonly numberArray: "number[]";
+  readonly dateArray: "date[]";
+}>], null>>;
+type AnswerTypeReservations = z.infer<typeof answerTypeReservationsSchema>;
+//#endregion
+export { answerTypeReservationsSchema as n, AnswerTypeReservations as t };
+//# sourceMappingURL=answer-types-DH0gv0Ea.d.mts.map

package/build/answer-types-DH0gv0Ea.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-types-DH0gv0Ea.d.mts","names":[],"sources":["../src/schema/answer-types.ts"],"mappings":";;;cAIa,8BAA4B,EAAA,SAAA,EAAA,UAAA,EAAA,WAAA,EAAA;;;;;;;;;;;;;KAc7B,yBAAyB,EAAE,aAAa"}

package/build/answer-types-Dtm6MqZQ.mjs

@@ -0,0 +1,19 @@
+import { B as ValueType } from "./localization-1lzNpyFX.mjs";
+import { z } from "zod";
+//#region src/schema/answer-types.ts
+/** Tuple entries preserve opaque IDs such as __proto__ across JSON/schema roundtrips. */
+const answerTypeReservationsSchema = z.array(z.tuple([z.string().min(1), z.enum(ValueType)])).superRefine((entries, context) => {
+	const seen = /* @__PURE__ */ new Set();
+	entries.forEach(([id], index) => {
+		if (seen.has(id)) context.addIssue({
+			code: "custom",
+			path: [index, 0],
+			message: `Duplicate answer type reservation '${id}'`
+		});
+		seen.add(id);
+	});
+});
+//#endregion
+export { answerTypeReservationsSchema as t };
+
+//# sourceMappingURL=answer-types-Dtm6MqZQ.mjs.map

package/build/answer-types-Dtm6MqZQ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer-types-Dtm6MqZQ.mjs","names":[],"sources":["../src/schema/answer-types.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { ValueType } from \"../survey/responses/value-types\";\n\n/** Tuple entries preserve opaque IDs such as __proto__ across JSON/schema roundtrips. */\nexport const answerTypeReservationsSchema = z\n  .array(z.tuple([z.string().min(1), z.enum(ValueType)]))\n  .superRefine((entries, context) => {\n    const seen = new Set<string>();\n    entries.forEach(([id], index) => {\n      if (seen.has(id))\n        context.addIssue({\n          code: \"custom\",\n          path: [index, 0],\n          message: `Duplicate answer type reservation '${id}'`,\n        });\n      seen.add(id);\n    });\n  });\nexport type AnswerTypeReservations = z.infer<typeof answerTypeReservationsSchema>;\n"],"mappings":";;;;AAIA,MAAa,+BAA+B,EACzC,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CACtD,aAAa,SAAS,YAAY;CACjC,MAAM,uBAAO,IAAI,IAAY;CAC7B,QAAQ,SAAS,CAAC,KAAK,UAAU;EAC/B,IAAI,KAAK,IAAI,EAAE,GACb,QAAQ,SAAS;GACf,MAAM;GACN,MAAM,CAAC,OAAO,CAAC;GACf,SAAS,sCAAsC,GAAG;EACpD,CAAC;EACH,KAAK,IAAI,EAAE;CACb,CAAC;AACH,CAAC"}

package/build/editor/colors.d.mts

@@ -6,7 +6,6 @@
  * without enabling the assistant, while assistant proposals must validate
  * against the same values.
  */
-declare const SURVEY_EDITOR_ITEM_COLORS: readonly ["#404040", "#b91c1c", "#c2410c", "#a16207", "#4d7c0f", "#047857", "#0369a1", "#4338ca", "#7e22ce", "#86198f", "#be123c"];
+export declare const SURVEY_EDITOR_ITEM_COLORS: readonly ["#404040", "#b91c1c", "#c2410c", "#a16207", "#4d7c0f", "#047857", "#0369a1", "#4338ca", "#7e22ce", "#86198f", "#be123c"];
 //#endregion
-export { SURVEY_EDITOR_ITEM_COLORS };
 //# sourceMappingURL=colors.d.mts.map

package/build/editor/colors.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"colors.d.mts","names":[],"sources":["../../src/editor/item-colors.ts"],"mappings":";;AAOA;;;;;;cAAa,yBAAA"}
+{"version":3,"file":"colors.d.mts","names":[],"sources":["../../src/editor/item-colors.ts"],"mappings":";;;;;;;;qBAOa"}

package/build/editor/colors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"colors.mjs","names":[],"sources":["../../src/editor/item-colors.ts"],"sourcesContent":["/**\n * Editor-only item-color swatches persisted in `metadata.editorItemColor`.\n *\n * This is shared survey-editor configuration: hosts may render the editor\n * without enabling the assistant, while assistant proposals must validate\n * against the same values.\n */\nexport const SURVEY_EDITOR_ITEM_COLORS = [\n  \"#404040\",\n  \"#b91c1c\",\n  \"#c2410c\",\n  \"#a16207\",\n  \"#4d7c0f\",\n  \"#047857\",\n  \"#0369a1\",\n  \"#4338ca\",\n  \"#7e22ce\",\n  \"#86198f\",\n  \"#be123c\",\n] as const;\n"],"mappings":";;;;;;;;AAOA,MAAa,4BAA4B;CACvC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD"}
+{"version":3,"file":"colors.mjs","names":[],"sources":["../../src/editor/item-colors.ts"],"sourcesContent":["/**\n * Editor-only item-color swatches persisted in `metadata.editorItemColor`.\n *\n * This is shared survey-editor configuration: hosts may render the editor\n * without enabling the assistant, while assistant proposals must validate\n * against the same values.\n */\nexport const SURVEY_EDITOR_ITEM_COLORS = [\n  \"#404040\",\n  \"#b91c1c\",\n  \"#c2410c\",\n  \"#a16207\",\n  \"#4d7c0f\",\n  \"#047857\",\n  \"#0369a1\",\n  \"#4338ca\",\n  \"#7e22ce\",\n  \"#86198f\",\n  \"#be123c\",\n] as const;\n"],"mappings":";;;;;;;;AAOA,MAAa,4BAA4B;CACvC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF"}