@cxpinsight/survey-spec 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CXPinsight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -12,5 +12,9 @@
  */
 export { evaluateExpression, evaluateCondition, isParseable } from './expressionEval';
 export { resolveVariable } from './resolveVariable';
+export { splitIntoPages } from './pageFlow';
+export { validateAnswer } from './validate';
+export type { ValidatableQuestion } from './validate';
+export type { Page, PageItem, PageFlowOptions, FlowQuestion, FlowSection } from './pageFlow';
 export type { AnswersMap, VariablesMap, EvalContext } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC7F,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveVariable = exports.isParseable = exports.evaluateCondition = exports.evaluateExpression = void 0;
+exports.validateAnswer = exports.splitIntoPages = exports.resolveVariable = exports.isParseable = exports.evaluateCondition = exports.evaluateExpression = void 0;
 /**
  * @cxpinsight/survey-spec
  *
@@ -19,3 +19,7 @@ Object.defineProperty(exports, "evaluateCondition", { enumerable: true, get: fun
 Object.defineProperty(exports, "isParseable", { enumerable: true, get: function () { return expressionEval_1.isParseable; } });
 var resolveVariable_1 = require("./resolveVariable");
 Object.defineProperty(exports, "resolveVariable", { enumerable: true, get: function () { return resolveVariable_1.resolveVariable; } });
+var pageFlow_1 = require("./pageFlow");
+Object.defineProperty(exports, "splitIntoPages", { enumerable: true, get: function () { return pageFlow_1.splitIntoPages; } });
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "validateAnswer", { enumerable: true, get: function () { return validate_1.validateAnswer; } });

package/dist/pageFlow.d.ts

@@ -0,0 +1,49 @@
+import type { EvalContext } from './types';
+export interface FlowQuestion {
+    id: string;
+    type?: string;
+    /** Multi-flow (spec §28). Undefined means the root flow. */
+    flow?: string;
+}
+export interface FlowSection {
+    id: string;
+    questionIds?: string[];
+    hidden?: boolean;
+    showWhen?: string;
+    hideWhen?: string;
+    /** true → its own page. Absent/false → an inline heading in the current page. */
+    pageBreak?: boolean;
+}
+export type PageItem<Q extends FlowQuestion = FlowQuestion, S extends FlowSection = FlowSection> = {
+    kind: 'question';
+    question: Q;
+} | {
+    kind: 'section-heading';
+    section: S;
+};
+export interface Page<Q extends FlowQuestion = FlowQuestion, S extends FlowSection = FlowSection> {
+    section?: S;
+    items: PageItem<Q, S>[];
+    questions: Q[];
+}
+export interface PageFlowOptions {
+    /**
+     * Multi-flow filter. `undefined` = the root flow (a root respondent never
+     * sees fork questions inline); a string = that named flow; `null` bypasses
+     * the filter entirely, which mobile uses for cross-flow lookups such as
+     * resolving a `rejoinAt` target.
+     */
+    flow?: string | null;
+    presentationMode?: string;
+    /**
+     * Typeform / conversation only. See the header: this is an open product
+     * decision, carried as a parameter so neither channel changes under the
+     * other's rule before it is made.
+     */
+    typeformSections?: 'per-section' | 'per-question';
+}
+export declare function splitIntoPages<Q extends FlowQuestion = FlowQuestion, S extends FlowSection = FlowSection>(survey: {
+    questions?: Q[];
+    sections?: S[];
+}, ctx: EvalContext, options?: PageFlowOptions): Page<Q, S>[];
+//# sourceMappingURL=pageFlow.d.ts.map

package/dist/pageFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pageFlow.d.ts","sourceRoot":"","sources":["../src/pageFlow.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAK3C,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,CAAC,SAAS,WAAW,GAAG,WAAW,IAC3F;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,CAAC,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAE5C,MAAM,WAAW,IAAI,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,EAAE,CAAC,SAAS,WAAW,GAAG,WAAW;IAC9F,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACxB,SAAS,EAAE,CAAC,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,aAAa,GAAG,cAAc,CAAC;CACnD;AAoBD,wBAAgB,cAAc,CAC5B,CAAC,SAAS,YAAY,GAAG,YAAY,EACrC,CAAC,SAAS,WAAW,GAAG,WAAW,EAEnC,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAA;CAAE,EAC3C,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,eAAoB,GAC5B,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAyEd"}

package/dist/pageFlow.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitIntoPages = splitIntoPages;
+/**
+ * Page flow — how a flat `questions[]` plus a `sections[]` overlay becomes pages.
+ *
+ * This was written three times and the implementations disagreed on 6 of 17
+ * fixtures (`tools/survey-conformance/pageFlow.js`). The differences were not
+ * cosmetic: a survey with a loose question before a section was asked in a
+ * DIFFERENT ORDER on React than on mobile, and the answers were recorded as
+ * though it were the same instrument.
+ *
+ * ## What this module settles, and what it deliberately does not
+ *
+ * Two of the three divergences were bugs and are closed here:
+ *
+ *  1. **Page order follows QUESTION order.** A section is emitted when the walk
+ *     first reaches a question that belongs to it. Mobile previously walked
+ *     `sections[]` and appended unclaimed questions at the end, so section order
+ *     in the definition — which the builder does not treat as meaningful — could
+ *     reorder the survey.
+ *
+ *  2. **Section conditions are evaluated.** `showWhen` / `hideWhen` on a section
+ *     are honoured, not just `hidden`. Mobile ignored them, so a section
+ *     conditioned away still split pages there.
+ *
+ * The third is a product decision, not a defect, so it is a PARAMETER rather
+ * than a silent choice: in typeform and conversation modes, does a section
+ * become one page, or does each of its questions get its own? React has always
+ * done per-section; mobile has always done per-question, and says so in its own
+ * comments. Encoding either one here would change page counts on live surveys
+ * for whichever channel lost, so `typeformSections` carries the difference in
+ * the open until someone decides.
+ */
+const expressionEval_1 = require("./expressionEval");
+const isPageBreak = (q) => String(q.type || '').toLowerCase() === 'pagebreak';
+/** Sections that survive `hidden`, `showWhen` and `hideWhen`, keyed for lookup. */
+function activeSections(sections, ctx) {
+    const claimed = new Map();
+    const active = new Map();
+    for (const s of sections) {
+        if (s.hidden === true)
+            continue;
+        if (!(0, expressionEval_1.evaluateCondition)(s.showWhen, ctx))
+            continue;
+        if (s.hideWhen && (0, expressionEval_1.evaluateCondition)(s.hideWhen, ctx))
+            continue;
+        for (const id of s.questionIds || [])
+            claimed.set(id, s.id);
+        active.set(s.id, s);
+    }
+    // A question claimed by a SKIPPED section is deliberately left unclaimed, so
+    // it falls through into whichever page it lands in rather than disappearing.
+    return { claimed, active };
+}
+function splitIntoPages(survey, ctx, options = {}) {
+    const { flow, presentationMode, typeformSections = 'per-section' } = options;
+    const raw = survey.questions || [];
+    const all = flow === null
+        ? raw
+        : raw.filter((q) => (q.flow || undefined) === (flow || undefined));
+    const sections = survey.sections || [];
+    const { claimed, active } = activeSections(sections, ctx);
+    if (presentationMode === 'typeform' || presentationMode === 'conversation') {
+        const pages = [];
+        const emitted = new Set();
+        for (const q of all) {
+            if (isPageBreak(q))
+                continue;
+            const sid = typeformSections === 'per-section' ? claimed.get(q.id) : undefined;
+            if (sid) {
+                if (emitted.has(sid))
+                    continue;
+                const section = active.get(sid);
+                if (!section)
+                    continue;
+                const qs = all.filter((qq) => claimed.get(qq.id) === sid && !isPageBreak(qq));
+                pages.push({ section, items: qs.map((qq) => ({ kind: 'question', question: qq })), questions: qs });
+                emitted.add(sid);
+            }
+            else {
+                pages.push({ items: [{ kind: 'question', question: q }], questions: [q] });
+            }
+        }
+        return pages;
+    }
+    const pages = [];
+    const emitted = new Set();
+    let current = [];
+    const flush = () => {
+        if (!current.length)
+            return;
+        pages.push({
+            items: current,
+            questions: current
+                .filter((it) => it.kind === 'question')
+                .map((it) => it.question),
+        });
+        current = [];
+    };
+    for (const q of all) {
+        // A pageBreak splits the current page and never renders itself. One inside
+        // a section is ignored — the section already controls its own boundary.
+        if (isPageBreak(q)) {
+            if (!claimed.has(q.id))
+                flush();
+            continue;
+        }
+        const sid = claimed.get(q.id);
+        if (!sid) {
+            current.push({ kind: 'question', question: q });
+            continue;
+        }
+        if (emitted.has(sid))
+            continue;
+        const section = active.get(sid);
+        if (!section)
+            continue;
+        const qs = all.filter((qq) => claimed.get(qq.id) === sid && !isPageBreak(qq));
+        if (section.pageBreak === true) {
+            flush();
+            pages.push({ section, items: qs.map((qq) => ({ kind: 'question', question: qq })), questions: qs });
+        }
+        else {
+            current.push({ kind: 'section-heading', section });
+            for (const qq of qs)
+                current.push({ kind: 'question', question: qq });
+        }
+        emitted.add(sid);
+    }
+    flush();
+    return pages;
+}

package/dist/validate.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Answer validation — whether a respondent may submit.
+ *
+ * A divergence here means the same answer is accepted on one channel and
+ * rejected on another. The respondent hits a wall that does not exist for
+ * someone who arrived by a different route, and an analyst comparing the two
+ * sets of responses is comparing two instruments.
+ *
+ * There were three implementations and all three disagreed:
+ *
+ *   • The WEB SDK had none. `survey.js` checked emptiness inline at the Next
+ *     button and nothing else, so it accepted 8 of 32 answers the others
+ *     rejected — including whitespace against a required question, `nope` as an
+ *     email address, and any string against `minLength`.
+ *
+ *   • REACT and MOBILE agreed on 26 fixtures and still differed, because every
+ *     one of those fixtures used `type: 'text'` with an `inputType`. React's
+ *     dispatcher has no case for `email`, `number`, `csat` or `ces` as question
+ *     TYPES, so a question of `type: 'email'` was format-checked on the phone
+ *     and waved through on a link.
+ *
+ * This module is the union, and each half was chosen for a reason:
+ *
+ *   • `isEmpty` is React's, because it is type-aware. The web renderer's values
+ *     are compound — `{ choice }`, `{ choices }`, `{ text, attachments }` — and
+ *     mobile's primitives pass through the same code unharmed. Mobile's
+ *     primitive-only version would have called `{ choice: undefined }` non-empty
+ *     and let a blank required radio through.
+ *
+ *   • The type dispatcher is mobile's, because it is the superset, and the
+ *     effective format is derived from `inputType || type` so `type: 'email'`
+ *     validates as an email whether or not the author also set an inputType.
+ *
+ * Order is spec §8 and it matters: required, then type-specific format, then
+ * the author's `rules[]`. An empty answer should read "this is required", not
+ * "that is not a valid email" — which sounds like the shape is wrong rather
+ * than the field being blank.
+ */
+export interface ValidatableQuestion {
+    type?: string;
+    inputType?: string;
+    required?: boolean;
+    isRequired?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    minValue?: number;
+    maxValue?: number;
+    minCount?: number;
+    maxCount?: number;
+    rules?: unknown;
+}
+/** Null when the answer is valid; otherwise the message to show. */
+export declare function validateAnswer(question: ValidatableQuestion, value: unknown): string | null;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAYH,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,mBAAmB,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgB3F"}

package/dist/validate.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * Answer validation — whether a respondent may submit.
+ *
+ * A divergence here means the same answer is accepted on one channel and
+ * rejected on another. The respondent hits a wall that does not exist for
+ * someone who arrived by a different route, and an analyst comparing the two
+ * sets of responses is comparing two instruments.
+ *
+ * There were three implementations and all three disagreed:
+ *
+ *   • The WEB SDK had none. `survey.js` checked emptiness inline at the Next
+ *     button and nothing else, so it accepted 8 of 32 answers the others
+ *     rejected — including whitespace against a required question, `nope` as an
+ *     email address, and any string against `minLength`.
+ *
+ *   • REACT and MOBILE agreed on 26 fixtures and still differed, because every
+ *     one of those fixtures used `type: 'text'` with an `inputType`. React's
+ *     dispatcher has no case for `email`, `number`, `csat` or `ces` as question
+ *     TYPES, so a question of `type: 'email'` was format-checked on the phone
+ *     and waved through on a link.
+ *
+ * This module is the union, and each half was chosen for a reason:
+ *
+ *   • `isEmpty` is React's, because it is type-aware. The web renderer's values
+ *     are compound — `{ choice }`, `{ choices }`, `{ text, attachments }` — and
+ *     mobile's primitives pass through the same code unharmed. Mobile's
+ *     primitive-only version would have called `{ choice: undefined }` non-empty
+ *     and let a blank required radio through.
+ *
+ *   • The type dispatcher is mobile's, because it is the superset, and the
+ *     effective format is derived from `inputType || type` so `type: 'email'`
+ *     validates as an email whether or not the author also set an inputType.
+ *
+ * Order is spec §8 and it matters: required, then type-specific format, then
+ * the author's `rules[]`. An empty answer should read "this is required", not
+ * "that is not a valid email" — which sounds like the shape is wrong rather
+ * than the field being blank.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAnswer = validateAnswer;
+/**
+ * Practical email format — matches what the HTML5 email validator accepts.
+ * Not RFC 5322-strict: that regex is a page long and rejects addresses real
+ * mail servers deliver to every day.
+ */
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/** URL with a scheme. No guessing at whether `http://` was meant. */
+const URL_RE = /^https?:\/\/[\w.\-]+(?:\.[\w.\-]+)+(?:[/?#][^\s]*)?$/i;
+/** Null when the answer is valid; otherwise the message to show. */
+function validateAnswer(question, value) {
+    // BOTH spellings. The v1 vocabulary and the builder both emit `isRequired`,
+    // and a renderer reading only `required` let a required question be submitted
+    // blank while the other channels rejected it.
+    const empty = isEmpty(question, value);
+    if ((question.required || question.isRequired) && empty) {
+        return 'This field is required';
+    }
+    // An optional field left blank is valid. Complaining about the shape of an
+    // answer nobody gave is noise.
+    if (empty)
+        return null;
+    const typeErr = validateByType(question, value);
+    if (typeErr)
+        return typeErr;
+    return validateRules(question, value);
+}
+/**
+ * Emptiness, per value shape.
+ *
+ * `0` and `false` are ANSWERS. A rating of zero and a "no" on a yes/no question
+ * are both real responses, and treating them as blank rejects a respondent who
+ * answered.
+ */
+function isEmpty(question, value) {
+    if (value === undefined || value === null)
+        return true;
+    if (typeof value === 'string')
+        return value.trim() === '';
+    if (typeof value === 'number')
+        return Number.isNaN(value);
+    if (typeof value === 'boolean')
+        return false;
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (typeof value === 'object') {
+        const v = value;
+        if (question.type === 'radio')
+            return !v.choice;
+        if (question.type === 'checkbox') {
+            return !Array.isArray(v.choices) || v.choices.length === 0;
+        }
+        if (question.type === 'multiText') {
+            return Object.values(v).every((x) => x === undefined || x === null || (typeof x === 'string' && x.trim() === ''));
+        }
+        if (question.type === 'text' || question.type === 'comment') {
+            // allowAttachments makes this { text, attachments }. Empty means both:
+            // a respondent who attached a file and typed nothing has answered.
+            const textEmpty = typeof v.text !== 'string' || v.text.trim() === '';
+            const noFiles = !Array.isArray(v.attachments) || v.attachments.length === 0;
+            return textEmpty && noFiles;
+        }
+        // matrixDropdown / matrixDynamic / panelDynamic / signature — any content
+        // counts as answered.
+        return Object.keys(v).length === 0;
+    }
+    return false;
+}
+function validateByType(question, value) {
+    switch (question.type) {
+        case 'text':
+        case 'comment':
+        case 'email':
+        case 'number':
+            return validateTextish(question, value);
+        case 'checkbox':
+            return validateCheckbox(question, value);
+        case 'rating':
+        case 'csat':
+        case 'ces':
+        case 'nps':
+            return validateNumericRange(question, value);
+        default:
+            return null;
+    }
+}
+function validateTextish(question, value) {
+    // Unwrap the compound { text, attachments } shape the web renderer uses.
+    let raw;
+    if (typeof value === 'string') {
+        raw = value;
+    }
+    else if (value && typeof value === 'object' && 'text' in value) {
+        const t = value.text;
+        raw = typeof t === 'string' ? t : '';
+    }
+    else {
+        raw = String(value ?? '');
+    }
+    const trimmed = raw.trim();
+    // An author who picks the "Email" question type has declared the format just
+    // as much as one who sets inputType on a text question.
+    const inputType = question.inputType
+        || (question.type === 'email' ? 'email' : question.type === 'number' ? 'number' : undefined);
+    if (inputType === 'email' && !EMAIL_RE.test(trimmed)) {
+        return 'Please enter a valid email address (e.g., you@example.com)';
+    }
+    if (inputType === 'url' && !URL_RE.test(trimmed)) {
+        return 'Please enter a full URL, including https://';
+    }
+    if (inputType === 'number' && Number.isNaN(Number(trimmed))) {
+        return 'Please enter a number';
+    }
+    if (inputType === 'tel' && !/^[\d\s+\-()]{3,}$/.test(trimmed)) {
+        // Deliberately permissive. Country-specific phone validation inline is a
+        // losing game that mostly rejects real numbers.
+        return 'Please enter a valid phone number';
+    }
+    if (typeof question.maxLength === 'number' && trimmed.length > question.maxLength) {
+        return `Please keep this under ${question.maxLength} characters`;
+    }
+    if (typeof question.minLength === 'number' && trimmed.length < question.minLength) {
+        return `Please enter at least ${question.minLength} characters`;
+    }
+    return null;
+}
+function validateCheckbox(question, value) {
+    // Web sends { choices }, mobile sends an array. Both are the same answer.
+    const choices = Array.isArray(value)
+        ? value
+        : (value && typeof value === 'object' && Array.isArray(value.choices)
+            ? value.choices
+            : []);
+    const count = choices.length;
+    if (typeof question.minCount === 'number' && count < question.minCount) {
+        return `Please select at least ${question.minCount}`;
+    }
+    if (typeof question.maxCount === 'number' && count > question.maxCount) {
+        return `Please select at most ${question.maxCount}`;
+    }
+    return null;
+}
+function validateNumericRange(question, value) {
+    if (typeof value !== 'number')
+        return null;
+    if (typeof question.minValue === 'number' && value < question.minValue) {
+        return `Must be at least ${question.minValue}`;
+    }
+    if (typeof question.maxValue === 'number' && value > question.maxValue) {
+        return `Must be at most ${question.maxValue}`;
+    }
+    return null;
+}
+function validateRules(question, value) {
+    const rules = Array.isArray(question.rules) ? question.rules : [];
+    if (rules.length === 0)
+        return null;
+    const str = typeof value === 'string' ? value : String(value ?? '');
+    for (const r of rules) {
+        const err = applyRule(r, str);
+        // The author's own message wins when they wrote one.
+        if (err)
+            return r.message || err;
+    }
+    return null;
+}
+function applyRule(rule, str) {
+    switch (rule.type) {
+        case 'minLength':
+            return typeof rule.value === 'number' && str.length < rule.value
+                ? `At least ${rule.value} characters` : null;
+        case 'maxLength':
+            return typeof rule.value === 'number' && str.length > rule.value
+                ? `At most ${rule.value} characters` : null;
+        case 'min':
+            return typeof rule.value === 'number' && Number(str) < rule.value
+                ? `Must be at least ${rule.value}` : null;
+        case 'max':
+            return typeof rule.value === 'number' && Number(str) > rule.value
+                ? `Must be at most ${rule.value}` : null;
+        case 'email':
+            return EMAIL_RE.test(str) ? null : 'Please enter a valid email address';
+        case 'url':
+            return URL_RE.test(str) ? null : 'Please enter a valid URL';
+        case 'pattern': {
+            if (typeof rule.value !== 'string')
+                return null;
+            try {
+                // An unparseable pattern is an authoring mistake. Failing OPEN is
+                // deliberate: blocking every respondent on a survey because of a typo
+                // in a regex is worse than letting the answer through.
+                return new RegExp(rule.value).test(str) ? null : "Format doesn't match";
+            }
+            catch {
+                return null;
+            }
+        }
+        default:
+            // Unknown rule types skip rather than block — the spec can add one
+            // before every renderer knows about it.
+            return null;
+    }
+}

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@cxpinsight/survey-spec",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The survey specification the renderers share — expression evaluation first. Source of truth for behaviour that must be identical on web, links and mobile.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist/",
-    "src/",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "node --test test/*.test.js",
-    "prepublishOnly": "npm run typecheck && npm run build"
+    "prepublishOnly": "node scripts/check-toolchain.js && npm run typecheck && npm run build"
   },
   "devDependencies": {
     "typescript": ">=5.0.0"

package/src/expressionEval.d.ts

@@ -1,7 +0,0 @@
-export type { AnswersMap, VariablesMap, EvalContext } from './types';
-import type { EvalContext } from './types';
-export declare function evaluateExpression(source: string, ctx: EvalContext): unknown;
-export declare function evaluateCondition(source: string | undefined, ctx: EvalContext): boolean;
-/** Whether `source` parses at all, independent of what it evaluates to. */
-export declare function isParseable(source: string | undefined): boolean;
-//# sourceMappingURL=expressionEval.d.ts.map

package/src/expressionEval.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"expressionEval.d.ts","sourceRoot":"","sources":["expressionEval.ts"],"names":[],"mappings":"AAwBA,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAY5E;AAID,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAcvF;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAS/D"}