@case-framework/survey-elements

Headless schemas and domain behavior for standard composable survey elements. This package has no React, editor, assistant, or network dependency.

import { Survey } from "@case-framework/survey-core";
import { defaultElementRegistry, createBuiltInElement } from "@case-framework/survey-elements";
import { SurveyEditor } from "@case-framework/survey-core/editor";

const editor = new SurveyEditor(Survey.blank(defaultElementRegistry));
const element = createBuiltInElement("text", new Set());
editor.insertElement(element); // ordinary content item with one element

See Composable architecture for the stored format, localization, lifecycle, and extension contracts. The root export provides all built-in definitions and the default registry. Family subpaths are /choice, /consent, /choice-matrix, and /form-matrix.

Breaking changes in 0.3

• Input presence is the element's required flag, and number/date range limits are min/max bounds (a literal or { expression, fallback? }). The required, min, max, minDate and maxDate validation rules and rule valueExpression are removed; use resolveNumberBound/resolveDateBound instead of isInputRequired/resolveInputDateBound.
• A bound whose expression has no value no longer fails the answer; it does not apply unless it has a fallback.
• Form matrix fields: mode is precision, cell override is fieldOverride, and the matrix naming prefix is variableNamePrefix (also on choice matrices).

Definitions and presets

Registered element types are information, text, number, date, boolean, choice, consent, choiceMatrix, and formMatrix. Presentations such as long text, slider, switch, radio, checkbox, and dropdown are ordinary configuration. Presets create data once; parsing never fills in new identities.

Open text answers default to 10,000 UTF-16 code units, including whitespace. An explicit maxLength validation rule replaces this limit, including in form matrix cells.

createBuiltInElement(preset, usedNames) allocates fresh owned IDs and available variable names. Pass names from the destination survey's slot registry, including computed matrix names. Insert through the shared editor commands to validate the whole result. Loading duplicate IDs/names does not repair them silently.

To compose a custom registry, construct recursive definitions with its shared body schema (createChoiceDefinition(body)). Definitions export their canonical schema, facts, compute, and validation behavior; they are not item wrapper classes.

Choice and consent

Radio/checkbox lists occupy a full row and may own option-triggered follow-up bodies. Dropdowns use normal input geometry and cannot own follow-ups. All choice answers store option IDs, independently of export codes and localized labels.

Disabled visible selections remain active. A disabled checkbox option is locked; a disabled single selection can be replaced by an enabled destination. Use visibility for answers that become inapplicable. Conditions, exclusivity patterns, and activation are evaluated by the shared engine.

Consent declares a boolean decision slot and retains inline/dialog presentation. It resolves an explicit or contextual title and inherited/custom/omitted subtitle. The existing UI is provided by survey-ui, separately from this definition.

Matrices

choiceMatrixDefinition declares stored row slots plus explicit computed score and sum slot IDs. Stored row answers contain option IDs. Missing, hidden, and non-scoring values produce no score; zero remains defined. The sum is absent when no active scored row contributes. Computed values are replayed for expressions and export and cannot be written or prefilled by participants.

Rows, options, score IDs, and sum IDs survive ordinary edits and moves. Copying remaps them. Content roles are keyed by the actual row/option/element owner, not concatenated translation-key strings. Matrix conditions use the same retained versus active response contract as other elements.

Existing matrix editing/presentation features remain: scored or unscored scales, non-scoring endpoint options, score presets/reversal, bipolar labels, responsive stacked/table presentation, row-label position, and horizontal scrolling. Outer composition geometry does not replace the matrix's internal layout.

formMatrixDefinition declares persistent row, column, and cell identities. Cells inherit complete column field settings unless overridden. Resetting an override keeps its identity. Structural helpers preserve/remap owned wording when creating or copying overrides.

Fields include text, number, date, dropdown, Yes/No, static content, and empty cells. Dropdowns store option IDs; dates store calendar strings with year, year-month, or year-month-day precision. Matrix controls retain their compact context-specific appearance. Hidden answers are retained until active projection; invalid answer types/domains are rejected rather than coerced.

Tests

pnpm test typechecks tests and runs source regressions. pnpm check also checks production types, builds the package, and runs the built-export smoke suite. Build survey-core first, or use the root dependency build command. Do not rebuild packages while the Next.js development host is running.