@likerts/react-native 0.0.3

package/lib/index.d.ts

@@ -0,0 +1,118 @@
+export interface StructuredChoiceAnswer {
+    selected: string[];
+    otherText: Record<string, string>;
+}
+export type Answer = string | number | string[] | StructuredChoiceAnswer | Record<string, string | string[]> | Record<string, number>;
+export type QuestionType = 'single_choice' | 'multiple_choice' | 'scale' | 'text' | 'number' | 'date' | 'ranking' | 'matrix' | 'constant_sum';
+export type VisibilityOperator = 'equals' | 'not_equals' | 'includes' | 'not_includes' | 'answered' | 'not_answered';
+export interface VisibilityCondition {
+    questionId: string;
+    operator: VisibilityOperator;
+    value?: string | number;
+}
+export interface PageBranch {
+    when: VisibilityCondition;
+    goToPageId: string;
+}
+export interface SurveyPage {
+    id: string;
+    title?: string;
+    questionIds: string[];
+    branches?: PageBranch[];
+}
+export interface Choice {
+    id: string;
+    label: string;
+    other?: {
+        maxLength: number;
+    };
+    exclusive?: true;
+}
+export interface PromptItem {
+    id: string;
+    label: string;
+}
+export interface Question {
+    id: string;
+    type: QuestionType;
+    label: string;
+    required?: boolean;
+    options?: Choice[];
+    min?: number;
+    max?: number;
+    maxLength?: number;
+    preset?: 'nps' | 'yes_no';
+    labels?: Record<string, string>;
+    minSelections?: number;
+    maxSelections?: number;
+    visibleWhen?: VisibilityCondition;
+    presentation?: 'stars' | 'dropdown';
+    rows?: PromptItem[];
+    columns?: Choice[];
+    matrixMode?: 'single' | 'multiple';
+    items?: PromptItem[];
+    total?: number;
+}
+export interface Collection {
+    id: string;
+    surveyId: string;
+    version: number;
+    placement: string;
+    schema: {
+        schemaVersion: 1 | 2 | 3 | 4 | 5;
+        title: string;
+        questions: Question[];
+        pages?: SurveyPage[];
+    };
+}
+export interface Submission {
+    idempotencyKey: string;
+    answers: Record<string, Answer>;
+    metadata: Record<string, unknown>;
+}
+export interface Receipt {
+    responseId: string;
+    collectionId: string;
+    accepted: true;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface CollectionRequestOptions extends RequestOptions {
+    refresh?: boolean;
+}
+export declare const LIKERTS_SDK_CAPABILITY: Readonly<{
+    target: "react_native";
+    sdkVersion: "0.0.3";
+    schemaVersions: readonly [1, 2, 3, 4, 5];
+}>;
+export declare class LikertsError extends Error {
+    status: number;
+    response: string;
+    constructor(status: number, response: string);
+}
+/** Only a public collection credential belongs here. No administrative credentials. */
+export declare class LikertsClient {
+    private token;
+    private defaultTimeoutMs;
+    private cacheMaxAgeMs;
+    private baseURL;
+    private transport;
+    private collectionCache;
+    constructor(baseURL: string, token: string, transport?: typeof fetch | undefined, defaultTimeoutMs?: number, cacheMaxAgeMs?: number);
+    private request;
+    collection(id: string, options?: CollectionRequestOptions): Promise<Collection>;
+    clearCollectionCache(id?: string): void;
+    /** Retrying requires the same submission object, including its idempotencyKey. */
+    submit(id: string, submission: Submission, options?: RequestOptions): Promise<Receipt>;
+}
+export declare function conditionMatches(condition: VisibilityCondition, answer: Answer | undefined): boolean;
+export declare function visibleQuestionIds(questions: Question[], answers: Record<string, Answer>): Set<string>;
+export declare function visibleAnswers(questions: Question[], answers: Record<string, Answer>): Record<string, Answer>;
+export { SurveyFlow, pageRoute, routedAnswers } from './branching';
+export type { BranchingSchema, SurveyProgress } from './branching';
+export { Survey } from './Survey';
+export type { SurveyMessages, SurveyProps, SurveyStyles } from './Survey';
+export { SurveyHost } from './SurveyHost';
+export type { SurveyHostMessages, SurveyHostProps } from './SurveyHost';

package/lib/index.js

@@ -0,0 +1,107 @@
+export const LIKERTS_SDK_CAPABILITY = Object.freeze({ target: 'react_native', sdkVersion: '0.0.3', schemaVersions: [1, 2, 3, 4, 5] });
+export class LikertsError extends Error {
+    status;
+    response;
+    constructor(status, response) {
+        super(`Likerts request failed (${status})`);
+        this.status = status;
+        this.response = response;
+    }
+}
+function safeBaseURL(value) {
+    const url = new URL(value);
+    const loopback = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]';
+    if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) || url.username || url.password || url.search || url.hash)
+        throw new TypeError('Likerts base URL must use HTTPS (HTTP is limited to loopback development)');
+    return value.replace(/\/$/, '');
+}
+/** Only a public collection credential belongs here. No administrative credentials. */
+export class LikertsClient {
+    token;
+    defaultTimeoutMs;
+    cacheMaxAgeMs;
+    baseURL;
+    transport;
+    collectionCache = new Map();
+    constructor(baseURL, token, transport = undefined, defaultTimeoutMs = 15000, cacheMaxAgeMs = 300000) {
+        this.token = token;
+        this.defaultTimeoutMs = defaultTimeoutMs;
+        this.cacheMaxAgeMs = cacheMaxAgeMs;
+        this.baseURL = safeBaseURL(baseURL);
+        this.transport = transport ?? ((input, init) => globalThis.fetch(input, init));
+        if (!Number.isFinite(defaultTimeoutMs) || defaultTimeoutMs <= 0)
+            throw new TypeError('timeoutMs must be positive');
+        if (!Number.isFinite(cacheMaxAgeMs) || cacheMaxAgeMs < 0)
+            throw new TypeError('cacheMaxAgeMs must not be negative');
+    }
+    async request(path, body, options = {}) {
+        const timeoutMs = options.timeoutMs ?? this.defaultTimeoutMs;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            throw new TypeError('timeoutMs must be positive');
+        const controller = new AbortController();
+        const abort = () => controller.abort(options.signal?.reason);
+        if (options.signal?.aborted)
+            abort();
+        else
+            options.signal?.addEventListener('abort', abort, { once: true });
+        const timer = setTimeout(() => controller.abort(new Error('Likerts request timed out')), timeoutMs);
+        try {
+            const response = await this.transport(`${this.baseURL}${path}`, { method: body ? 'POST' : 'GET', redirect: 'error', signal: controller.signal, headers: { Authorization: `Bearer ${this.token}`, ...(body ? { 'Content-Type': 'application/json' } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+            if (!response.ok)
+                throw new LikertsError(response.status, await response.text());
+            return await response.json();
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+        }
+    }
+    async collection(id, options = {}) {
+        const cached = this.collectionCache.get(id);
+        if (!options.refresh && cached && Date.now() - cached.storedAt < this.cacheMaxAgeMs)
+            return cached.value;
+        try {
+            const c = await this.request(`/v1/collections/${encodeURIComponent(id)}`, undefined, options);
+            if (![1, 2, 3, 4, 5].includes(c.schema.schemaVersion))
+                throw new Error('Unsupported survey schema version');
+            if (cached && (cached.value.id !== c.id || cached.value.surveyId !== c.surveyId || cached.value.version !== c.version || cached.value.schema.schemaVersion !== c.schema.schemaVersion)) {
+                this.collectionCache.delete(id);
+                throw new Error('Collection binding changed');
+            }
+            this.collectionCache.set(id, { value: c, storedAt: Date.now() });
+            return c;
+        }
+        catch (error) {
+            this.collectionCache.delete(id);
+            throw error;
+        }
+    }
+    clearCollectionCache(id) { if (id)
+        this.collectionCache.delete(id);
+    else
+        this.collectionCache.clear(); }
+    /** Retrying requires the same submission object, including its idempotencyKey. */
+    async submit(id, submission, options) { const receipt = await this.request(`/v1/collections/${encodeURIComponent(id)}/responses`, submission, options); if (receipt.accepted !== true)
+        throw new Error('Invalid Likerts receipt'); return receipt; }
+}
+export function conditionMatches(condition, answer) { const selected = answer && typeof answer === 'object' && !Array.isArray(answer) && 'selected' in answer && Array.isArray(answer.selected) ? answer.selected : undefined; const objectAnswer = answer && typeof answer === 'object' && !Array.isArray(answer); const hasAnswer = answer !== undefined && (typeof answer !== 'string' || answer.trim() !== '') && (!Array.isArray(answer) || answer.length > 0) && (!objectAnswer || (selected ? selected.length > 0 : Object.keys(answer).length > 0)); if (condition.operator === 'answered')
+    return hasAnswer; if (condition.operator === 'not_answered')
+    return !hasAnswer; if (answer === undefined || answer === '')
+    return false; const scalar = selected?.length === 1 ? selected[0] : answer; if (condition.operator === 'equals')
+    return scalar === condition.value; if (condition.operator === 'not_equals')
+    return scalar !== condition.value; const values = selected ?? (Array.isArray(answer) ? answer : undefined); if (!values)
+    return false; if (condition.operator === 'includes')
+    return values.includes(String(condition.value)); if (condition.operator === 'not_includes')
+    return !values.includes(String(condition.value)); throw new Error('Unsupported visibility operator'); }
+export function visibleQuestionIds(questions, answers) { const byId = new Map(questions.map(q => [q.id, q])); const memo = new Map(); const active = new Set(); const visible = (q) => { const prior = memo.get(q.id); if (prior !== undefined)
+    return prior; if (active.has(q.id))
+    throw new Error('Conditional visibility cycle'); active.add(q.id); let result = true; if (q.visibleWhen) {
+    const source = byId.get(q.visibleWhen.questionId);
+    if (!source)
+        throw new Error('Conditional visibility references an unknown question');
+    result = conditionMatches(q.visibleWhen, visible(source) ? answers[source.id] : undefined);
+} active.delete(q.id); memo.set(q.id, result); return result; }; return new Set(questions.filter(visible).map(q => q.id)); }
+export function visibleAnswers(questions, answers) { const visible = visibleQuestionIds(questions, answers); return Object.fromEntries(Object.entries(answers).filter(([id]) => visible.has(id))); }
+export { SurveyFlow, pageRoute, routedAnswers } from './branching';
+export { Survey } from './Survey';
+export { SurveyHost } from './SurveyHost';

package/lib/offline.d.ts

@@ -0,0 +1,69 @@
+import type { Receipt, Submission } from './index';
+export type OfflineReason = 'invalid' | 'conflict' | 'unauthorized' | 'revoked' | 'deleted' | 'expired';
+export type OfflineState = 'pending' | 'blocked' | 'expired_local';
+export interface OfflineLimits {
+    maxRecords: number;
+    maxBytes: number;
+    maxAgeSeconds: number;
+}
+export interface OfflineStatus {
+    pending: number;
+    blockedByReason: Partial<Record<OfflineReason, number>>;
+    expiredLocal: number;
+    quarantined: number;
+    bytes: number;
+}
+export interface OfflineOutcome {
+    recordId: string;
+    outcome: 'accepted' | 'retry' | 'blocked' | 'expired_local' | 'quarantined' | 'credential_unavailable';
+    reason?: OfflineReason;
+    retryAfterSeconds?: number;
+}
+export interface FlushReport {
+    attempted: number;
+    accepted: number;
+    pending: number;
+    blocked: number;
+    expiredLocal: number;
+    quarantined: number;
+    cancelled: boolean;
+    outcomes: OfflineOutcome[];
+}
+export interface OpaqueQueueStore {
+    load(): Promise<Uint8Array[]>;
+    replace(records: readonly Uint8Array[]): Promise<void>;
+}
+export interface QueueCipher {
+    seal(cleartext: Uint8Array): Promise<Uint8Array>;
+    open(ciphertext: Uint8Array): Promise<Uint8Array>;
+}
+export interface OfflineSendResult {
+    status: number;
+    receipt?: Receipt;
+    retryAfterSeconds?: number;
+}
+export type OfflineSender = (collectionId: string, credential: string, submission: Submission, signal?: AbortSignal) => Promise<OfflineSendResult>;
+export interface NativeOfflineAdapter extends OpaqueQueueStore, QueueCipher {
+    readonly secureKeyProfile: 'keychain' | 'android_keystore';
+    readonly encryptedStorage: true;
+    createRecordId(): string;
+}
+export declare function openNativeOfflineQueue(adapter: NativeOfflineAdapter, sender: OfflineSender, configuration?: Partial<OfflineLimits>): OfflineQueue;
+export declare class OfflineQueue {
+    private store;
+    private cipher;
+    private sender;
+    private now;
+    private randomId;
+    private readonly configuration;
+    private flushing;
+    constructor(store: OpaqueQueueStore, cipher: QueueCipher, sender: OfflineSender, configuration?: Partial<OfflineLimits>, now?: () => number, randomId?: () => string);
+    private read;
+    private write;
+    enqueue(collectionId: string, submission: Submission): Promise<string>;
+    snapshot(): Promise<OfflineStatus>;
+    delete(recordId: string): Promise<void>;
+    deleteCollection(collectionId: string): Promise<number>;
+    purgeQuarantined(): Promise<number>;
+    flush(resolveCredential: (collectionId: string) => Promise<string | undefined>, signal?: AbortSignal): Promise<FlushReport>;
+}

package/lib/offline.js

@@ -0,0 +1,117 @@
+const DEFAULTS = { maxRecords: 1000, maxBytes: 10 * 1024 * 1024, maxAgeSeconds: 7 * 86400 }, HARD = { maxRecords: 10000, maxBytes: 100 * 1024 * 1024, maxAgeSeconds: 30 * 86400 }, MAX_RECORD = 65536;
+const encoder = new TextEncoder(), decoder = new TextDecoder();
+const canonical = (value) => JSON.stringify(value && typeof value === 'object' && !Array.isArray(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, JSON.parse(canonical(v))])) : Array.isArray(value) ? value.map(v => JSON.parse(canonical(v))) : value);
+const reason = (status) => ({ 400: 'invalid', 409: 'conflict', 401: 'unauthorized', 403: 'revoked', 404: 'deleted', 410: 'expired' }[status] ?? (status >= 400 && status < 500 && ![408, 425, 429].includes(status) ? 'invalid' : undefined));
+const retryable = (status) => [408, 425, 429].includes(status) || status >= 500;
+const limits = (value) => { const result = { ...DEFAULTS, ...value }; if (!Number.isSafeInteger(result.maxRecords) || result.maxRecords < 1 || result.maxRecords > HARD.maxRecords || !Number.isSafeInteger(result.maxBytes) || result.maxBytes < 1 || result.maxBytes > HARD.maxBytes || !Number.isSafeInteger(result.maxAgeSeconds) || result.maxAgeSeconds < 1 || result.maxAgeSeconds > HARD.maxAgeSeconds)
+    throw new RangeError('Offline queue limits exceed hard bounds'); return result; };
+export function openNativeOfflineQueue(adapter, sender, configuration = {}) { if (adapter.encryptedStorage !== true || !['keychain', 'android_keystore'].includes(adapter.secureKeyProfile))
+    throw new Error('A native encrypted storage and secure key adapter is required'); return new OfflineQueue(adapter, adapter, sender, configuration, undefined, () => adapter.createRecordId()); }
+export class OfflineQueue {
+    store;
+    cipher;
+    sender;
+    now;
+    randomId;
+    configuration;
+    flushing = false;
+    constructor(store, cipher, sender, configuration = {}, now = () => Date.now(), randomId = () => { throw new Error('A native secure random record ID adapter is required'); }) {
+        this.store = store;
+        this.cipher = cipher;
+        this.sender = sender;
+        this.now = now;
+        this.randomId = randomId;
+        this.configuration = limits(configuration);
+    }
+    async read() { const good = [], bad = []; for (const ciphertext of await this.store.load()) {
+        try {
+            good.push({ record: JSON.parse(decoder.decode(await this.cipher.open(ciphertext))), ciphertext });
+        }
+        catch {
+            bad.push(ciphertext);
+        }
+    } return { good, bad }; }
+    async write(records, bad) { await this.store.replace([...bad, ...await Promise.all(records.map(r => this.cipher.seal(encoder.encode(canonical(r)))))]); }
+    async enqueue(collectionId, submission) { if (!collectionId || !submission.idempotencyKey)
+        throw new TypeError('collectionId and idempotencyKey are required'); const submissionText = canonical(submission), byteSize = encoder.encode(submissionText).byteLength; if (byteSize > MAX_RECORD)
+        throw new RangeError('Offline record exceeds 64 KiB'); const { good, bad } = await this.read(), records = good.map(v => v.record), prior = records.find(r => JSON.parse(r.submissionText).idempotencyKey === submission.idempotencyKey); if (prior) {
+        if (prior.collectionId !== collectionId || prior.submissionText !== submissionText)
+            throw new Error('Offline idempotency conflict');
+        return prior.id;
+    } if (records.length >= this.configuration.maxRecords || records.reduce((sum, r) => sum + r.byteSize, 0) + byteSize > this.configuration.maxBytes)
+        throw new RangeError('Offline queue capacity exceeded'); const record = { id: this.randomId(), collectionId, submissionText, createdAt: this.now(), byteSize, attemptCount: 0, state: 'pending' }; await this.write([...records, record], bad); return record.id; }
+    async snapshot() { const { good, bad } = await this.read(), status = { pending: 0, blockedByReason: {}, expiredLocal: 0, quarantined: bad.length, bytes: 0 }; for (const { record: r } of good) {
+        status.bytes += r.byteSize;
+        if (r.state === 'pending')
+            status.pending++;
+        else if (r.state === 'expired_local')
+            status.expiredLocal++;
+        else if (r.reason)
+            status.blockedByReason[r.reason] = (status.blockedByReason[r.reason] ?? 0) + 1;
+    } return status; }
+    async delete(recordId) { const { good, bad } = await this.read(); await this.write(good.map(v => v.record).filter(r => r.id !== recordId), bad); }
+    async deleteCollection(collectionId) { const { good, bad } = await this.read(), kept = good.map(v => v.record).filter(r => r.collectionId !== collectionId); const count = good.length - kept.length; await this.write(kept, bad); return count; }
+    async purgeQuarantined() { const { good, bad } = await this.read(); await this.write(good.map(v => v.record), []); return bad.length; }
+    async flush(resolveCredential, signal) { if (this.flushing)
+        throw new Error('Offline flush already active'); this.flushing = true; const report = { attempted: 0, accepted: 0, pending: 0, blocked: 0, expiredLocal: 0, quarantined: 0, cancelled: false, outcomes: [] }; try {
+        const initial = await this.read(), initialRecords = initial.good.map(v => v.record);
+        let expiredChanged = false;
+        for (const record of initialRecords) {
+            if (record.state !== 'expired_local' && this.now() - record.createdAt > this.configuration.maxAgeSeconds * 1000) {
+                record.state = 'expired_local';
+                delete record.reason;
+                expiredChanged = true;
+            }
+        }
+        if (expiredChanged)
+            await this.write(initialRecords, initial.bad);
+        const ids = initialRecords.filter(r => r.state === 'pending').sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id)).map(r => r.id);
+        for (const id of ids) {
+            if (signal?.aborted) {
+                report.cancelled = true;
+                break;
+            }
+            const current = await this.read(), records = current.good.map(v => v.record), record = records.find(r => r.id === id);
+            if (!record || record.state !== 'pending')
+                continue;
+            const credential = await resolveCredential(record.collectionId);
+            if (!credential) {
+                report.pending++;
+                report.outcomes.push({ recordId: id, outcome: 'credential_unavailable' });
+                continue;
+            }
+            report.attempted++;
+            let result;
+            try {
+                result = await this.sender(record.collectionId, credential, JSON.parse(record.submissionText), signal);
+            }
+            catch { }
+            const fresh = await this.read(), updated = fresh.good.map(v => v.record), target = updated.find(r => r.id === id);
+            if (!target)
+                continue;
+            const receipt = result?.receipt;
+            if (result && result.status >= 200 && result.status < 300 && receipt?.accepted === true && receipt.collectionId === target.collectionId && receipt.responseId.length > 0) {
+                await this.write(updated.filter(r => r.id !== id), fresh.bad);
+                report.accepted++;
+                report.outcomes.push({ recordId: id, outcome: 'accepted' });
+                continue;
+            }
+            target.attemptCount++;
+            const terminal = result && reason(result.status);
+            if (terminal) {
+                target.state = 'blocked';
+                target.reason = terminal;
+                report.blocked++;
+                report.outcomes.push({ recordId: id, outcome: 'blocked', reason: terminal });
+            }
+            else {
+                report.pending++;
+                report.outcomes.push({ recordId: id, outcome: 'retry', ...(result?.retryAfterSeconds !== undefined && retryable(result.status) ? { retryAfterSeconds: Math.max(0, Math.min(86400, Math.floor(result.retryAfterSeconds))) } : {}) });
+            }
+            await this.write(updated, fresh.bad);
+        }
+    }
+    finally {
+        this.flushing = false;
+    } const final = await this.snapshot(); report.pending = final.pending; report.quarantined = final.quarantined; report.expiredLocal = final.expiredLocal; report.blocked = Object.values(final.blockedByReason).reduce((a, b) => a + (b ?? 0), 0); return report; }
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@likerts/react-native",
+  "version": "0.0.3",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "lib/index.js",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "jest --runInBand",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^19.2.3",
+    "react-native": ">=0.85 <0.88"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.0",
+    "@react-native/babel-preset": "0.86.3",
+    "@react-native/jest-preset": "0.86.3",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.2.0",
+    "@types/react-test-renderer": "^19.1.0",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
+    "react": "19.2.3",
+    "react-native": "0.86.3",
+    "react-test-renderer": "19.2.3",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT",
+  "files": [
+    "lib",
+    "src",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "types": "lib/index.d.ts",
+  "react-native": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "react-native": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./offline": {
+      "types": "./lib/offline.d.ts",
+      "react-native": "./src/offline.ts",
+      "default": "./lib/offline.js"
+    }
+  },
+  "description": "In-product survey collection for React Native with Likerts.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crosstabs/likerts.git",
+    "directory": "sdks/react-native"
+  },
+  "homepage": "https://likerts.com/docs",
+  "bugs": {
+    "url": "https://github.com/crosstabs/likerts/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "likerts",
+    "surveys",
+    "feedback",
+    "react-native"
+  ]
+}

package/src/Survey.tsx

@@ -0,0 +1,53 @@
+import {selectedChoices, otherTexts, toggleChoice, setOtherText, choiceError} from './choice-features';
+import React, {useEffect, useState} from 'react';
+import {AccessibilityInfo, Pressable, StyleProp, Text, TextInput, TextStyle, View, ViewStyle} from 'react-native';
+import {visibleAnswers,visibleQuestionIds} from './index';
+import {pageRoute,routedAnswers} from './branching';
+import {advancedAnswerError,allocationRemaining,moveRanking,rankingOrder,setAllocation,setMatrixChoice} from './advanced-questions';
+import type {Answer, Collection} from './index';
+
+export interface SurveyMessages {requiredSuffix:string;requiredError:string;selectionRangeError:string;selectionLimitHint:string;datePlaceholder:string;back:string;next:string;progress:string;submit:string;submitting:string;selectPlaceholder:string;otherError:string;moveUp:string;moveDown:string;remaining:string;advancedError:string}
+export interface SurveyStyles {container?:StyleProp<ViewStyle>;title?:StyleProp<TextStyle>;question?:StyleProp<ViewStyle>;label?:StyleProp<TextStyle>;choice?:StyleProp<ViewStyle>;choiceText?:StyleProp<TextStyle>;input?:StyleProp<TextStyle>;error?:StyleProp<TextStyle>;submit?:StyleProp<ViewStyle>;submitText?:StyleProp<TextStyle>}
+export interface SurveyProps {collection:Collection;onSubmit:(answers:Record<string,Answer>)=>void;disabled?:boolean;submitting?:boolean;initialAnswers?:Record<string,Answer>;onAnswersChange?:(answers:Record<string,Answer>)=>void;onValidationError?:(message:string)=>void;messages?:Partial<SurveyMessages>;styles?:SurveyStyles;testID?:string}
+
+const defaults:SurveyMessages={requiredSuffix:'required',requiredError:'{question}: an answer is required.',selectionRangeError:'{question}: select between {min} and {max} options.',selectionLimitHint:'Maximum selections reached',datePlaceholder:'YYYY-MM-DD',back:'Back',next:'Next',progress:'Page {current} of {total}',submit:'Submit',submitting:'Submitting…',selectPlaceholder:'Select an answer',otherError:'{question}: enter valid text for the selected Other option.',moveUp:'Move up',moveDown:'Move down',remaining:'{remaining} remaining',advancedError:'{question}: complete the answer.'};
+const format=(template:string,values:Record<string,string|number>)=>Object.entries(values).reduce((result,[key,value])=>result.replace(`{${key}}`,String(value)),template);
+
+/** Host owns network lifecycle, placement and dismissal; renderer checks selection bounds. */
+export function Survey({collection,onSubmit,disabled=false,submitting=false,initialAnswers={},onAnswersChange,onValidationError,messages:overrides,styles={},testID='likerts-survey'}:SurveyProps) {
+  const messages={...defaults};for(const key of Object.keys(defaults) as (keyof SurveyMessages)[]){const value=overrides?.[key];if(typeof value==='string')messages[key]=value}const blocked=disabled||submitting;
+  const pages=collection.schema.pages??[{id:'survey',questionIds:collection.schema.questions.map(q=>q.id)}];
+  const [answers,setAnswers]=useState<Record<string,Answer>>(()=>routedAnswers(collection.schema,{...initialAnswers}));const [error,setError]=useState('');const [openDropdowns,setOpenDropdowns]=useState<Record<string,boolean>>({});const [currentPage,setCurrentPage]=useState(0);const [history,setHistory]=useState([0]);
+  if (![1,2,3,4,5].includes(collection.schema.schemaVersion)) throw new Error('Unsupported survey schema version');
+  useEffect(()=>{const reset=routedAnswers(collection.schema,{...initialAnswers});setAnswers(reset);setCurrentPage(0);setHistory([0]);setOpenDropdowns({});setError('');onAnswersChange?.(reset);},[collection.id,collection.version]);
+  useEffect(()=>{if(error)AccessibilityInfo.announceForAccessibility(error);},[error]);
+  const update=(id:string,value:Answer|((current:Answer|undefined)=>Answer))=>{setAnswers(previous=>{const next=routedAnswers(collection.schema,{...previous,[id]:typeof value==='function'?value(previous[id]):value});const route=pageRoute(collection.schema,next);if(!route.includes(currentPage)){let shared=route[0]??0;for(let i=0;i<Math.min(history.length,route.length)&&history[i]===route[i];i++)shared=route[i];setCurrentPage(shared);setHistory(route.slice(0,route.indexOf(shared)+1));}onAnswersChange?.(next);return next});setError('')};
+  const fail=(message:string)=>{setError(message);onValidationError?.(message)};
+  const visible=visibleQuestionIds(collection.schema.questions,answers),currentQuestions=new Set(pages[currentPage]?.questionIds??[]),route=pageRoute(collection.schema,answers),routeIndex=route.indexOf(currentPage);
+  const advance=()=>{const result:Record<string,Answer>={};for(const q of collection.schema.questions){if(!visible.has(q.id)||!currentQuestions.has(q.id))continue;const value=answers[q.id];if(q.type==='ranking'||q.type==='matrix'||q.type==='constant_sum'){const code=advancedAnswerError(q,value);if(code){fail(format(code==='required'?messages.requiredError:messages.advancedError,{question:q.label}));return}if(value!==undefined)result[q.id]=value;continue}const isChoice=q.type==='single_choice'||q.type==='multiple_choice';if(value===undefined||value===''||(isChoice&&selectedChoices(value).length===0)||(Array.isArray(value)&&value.length===0)){if(q.required){fail(format(messages.requiredError,{question:q.label}));return}continue}if(isChoice){const code=choiceError(q,value);if(code){fail(format(code==='other'?messages.otherError:messages.selectionRangeError,{question:q.label,min:Math.max(q.required?1:0,q.minSelections??0),max:q.maxSelections??q.options?.length??0}));return}}result[q.id]=q.type==='number'||q.type==='scale'?Number(value):value}if(routeIndex+1<route.length){const next=route[routeIndex+1];setCurrentPage(next);setHistory(route.slice(0,routeIndex+2));return}onSubmit(routedAnswers(collection.schema,{...answers,...result}))};
+  return <View style={styles.container} testID={testID} accessibilityLabel={collection.schema.title}>
+    <Text style={styles.title} accessibilityRole="header" testID={`${testID}-title`}>{collection.schema.title}</Text>
+    {collection.schema.pages?<Text testID={`${testID}-progress`}>{format(messages.progress,{current:currentPage+1,total:pages.length})}</Text>:null}
+    {collection.schema.questions.filter(q=>visible.has(q.id)&&currentQuestions.has(q.id)).map(q=>{
+      const labelId=`${testID}-${q.id}-label`;const questionLabel=`${q.label}${q.required?`, ${messages.requiredSuffix}`:''}`;
+      return <View key={q.id} style={styles.question} testID={`${testID}-question-${q.id}`}>
+        <Text style={styles.label} nativeID={labelId}>{q.label}{q.required?` (${messages.requiredSuffix})`:''}</Text>
+        {q.type==='ranking'?rankingOrder(q,answers[q.id]).map((id,index)=>{const option=q.options?.find(value=>value.id===id)!;return <View key={id}><Text style={styles.choiceText}>{index+1}. {option.label}</Text><Pressable testID={`${testID}-${q.id}-${id}-up`} accessibilityRole="button" accessibilityLabel={`${messages.moveUp}: ${option.label}`} disabled={blocked||index===0} onPress={()=>update(q.id,current=>moveRanking(q,current,id,-1))}><Text>{messages.moveUp}</Text></Pressable><Pressable testID={`${testID}-${q.id}-${id}-down`} accessibilityRole="button" accessibilityLabel={`${messages.moveDown}: ${option.label}`} disabled={blocked||index===rankingOrder(q,answers[q.id]).length-1} onPress={()=>update(q.id,current=>moveRanking(q,current,id,1))}><Text>{messages.moveDown}</Text></Pressable></View>})
+        :q.type==='matrix'?(q.rows??[]).map(row=><View key={row.id}><Text style={styles.choiceText}>{row.label}</Text>{(q.columns??[]).map(column=>{const value=(answers[q.id] as Record<string,string|string[]>|undefined)?.[row.id],selected=Array.isArray(value)?value.includes(column.id):value===column.id;return <Pressable key={column.id} testID={`${testID}-${q.id}-${row.id}-${column.id}`} accessibilityRole={q.matrixMode==='single'?'radio':'checkbox'} accessibilityLabel={`${row.label}: ${column.label}`} accessibilityState={{checked:selected,disabled:blocked}} disabled={blocked} onPress={()=>update(q.id,current=>setMatrixChoice(q,current,row.id,column.id))}><Text>{selected?'✓ ':''}{column.label}</Text></Pressable>})}</View>)
+        :q.type==='constant_sum'?<>{(q.items??[]).map(item=><TextInput key={item.id} style={styles.input} testID={`${testID}-${q.id}-${item.id}`} accessibilityLabel={`${q.label}: ${item.label}`} keyboardType="number-pad" editable={!blocked} value={String((answers[q.id] as Record<string,number>|undefined)?.[item.id]??'')} onChangeText={value=>update(q.id,current=>setAllocation(current,item.id,Number(value)))}/>)}<Text accessibilityLiveRegion="polite" testID={`${testID}-${q.id}-remaining`}>{format(messages.remaining,{remaining:allocationRemaining(q,answers[q.id])})}</Text></>
+        :<>{q.presentation==='dropdown'?<Pressable style={styles.choice} testID={`${testID}-${q.id}-dropdown`} accessibilityRole="button" accessibilityLabel={`${q.label}: ${q.options?.find(o=>o.id===selectedChoices(answers[q.id])[0])?.label??messages.selectPlaceholder}`} accessibilityState={{expanded:!!openDropdowns[q.id],disabled:blocked}} disabled={blocked} onPress={()=>setOpenDropdowns(previous=>({...previous,[q.id]:!previous[q.id]}))}><Text style={styles.choiceText}>{q.options?.find(o=>o.id===selectedChoices(answers[q.id])[0])?.label??messages.selectPlaceholder}</Text></Pressable>:null}
+        {q.type==='single_choice'||q.type==='multiple_choice'?(q.presentation==='dropdown'&&!openDropdowns[q.id]?[]:q.options??[]).map(option=>{
+          const current=selectedChoices(answers[q.id]),selected=current.includes(option.id);const exclusive=current.some(id=>q.options?.some(o=>o.id===id&&o.exclusive));
+          const atLimit=q.type==='multiple_choice'&&!selected&&!option.exclusive&&!exclusive&&q.maxSelections!==undefined&&current.length>=q.maxSelections;const optionBlocked=blocked||atLimit;
+          return <Pressable key={option.id} style={styles.choice} testID={`${testID}-${q.id}-${option.id}`} disabled={optionBlocked} accessibilityLabel={`${q.label}: ${option.label}`} accessibilityHint={atLimit?messages.selectionLimitHint:undefined} accessibilityRole={q.type==='single_choice'?'radio':'checkbox'} accessibilityState={{checked:selected,disabled:optionBlocked}} onPress={()=>{if(!optionBlocked){update(q.id,current=>toggleChoice(q,current,option.id));if(q.presentation==='dropdown')setOpenDropdowns(previous=>({...previous,[q.id]:false}));}}}><Text style={styles.choiceText}>{selected?'✓ ':''}{option.label}</Text></Pressable>;
+        })
+        :q.type==='scale'&&(q.labels!==undefined||q.preset==='nps'||q.presentation==='stars')?Array.from({length:(q.max??0)-(q.min??0)+1},(_,i)=>(q.min??0)+i).map(value=>{const label=q.labels?.[String(value)]?`${value} — ${q.labels[String(value)]}`:String(value);return <Pressable key={value} style={styles.choice} testID={`${testID}-${q.id}-${value}`} disabled={blocked} accessibilityLabel={`${q.label}: ${label}`} accessibilityRole="radio" accessibilityState={{checked:answers[q.id]===value,disabled:blocked}} onPress={()=>{if(!blocked)update(q.id,value)}}><Text style={styles.choiceText}>{q.presentation==='stars'?'★'.repeat(value):label}</Text></Pressable>})
+        :<TextInput style={styles.input} testID={`${testID}-${q.id}`} accessibilityLabel={questionLabel} accessibilityLabelledBy={labelId} editable={!blocked} value={String(answers[q.id]??'')} multiline={q.type==='text'} maxLength={q.maxLength} placeholder={q.type==='date'?messages.datePlaceholder:undefined} keyboardType={q.type==='number'||q.type==='scale'?'numbers-and-punctuation':'default'} onChangeText={value=>update(q.id,value)}/>}</>}
+        {(q.options??[]).filter(o=>o.other!==undefined&&selectedChoices(answers[q.id]).includes(o.id)).map(option=><TextInput key={option.id} style={styles.input} testID={`${testID}-${q.id}-${option.id}-text`} accessibilityLabel={`${q.label}: ${option.label}`} editable={!blocked} value={otherTexts(answers[q.id])[option.id]??''} onChangeText={value=>update(q.id,current=>setOtherText(q,current,option.id,value))}/>)}
+
+      </View>})}
+    {error?<Text style={styles.error} testID={`${testID}-error`} accessibilityRole="alert" accessibilityLiveRegion="assertive">{error}</Text>:null}
+    {collection.schema.pages&&history.length>1?<Pressable style={styles.submit} testID={`${testID}-back`} disabled={blocked} accessibilityRole="button" onPress={()=>{if(!blocked){const next=history.slice(0,-1);setHistory(next);setCurrentPage(next[next.length-1]);setError('')}}}><Text style={styles.submitText}>{messages.back}</Text></Pressable>:null}
+    <Pressable style={styles.submit} testID={`${testID}-${routeIndex+1<route.length?'next':'submit'}`} disabled={blocked} accessibilityLabel={submitting?messages.submitting:routeIndex+1<route.length?messages.next:messages.submit} accessibilityRole="button" accessibilityState={{disabled:blocked,busy:submitting}} onPress={()=>{if(!blocked)advance()}}><Text style={styles.submitText}>{submitting?messages.submitting:routeIndex+1<route.length?messages.next:messages.submit}</Text></Pressable>
+  </View>;
+}

package/src/SurveyHost.tsx

@@ -0,0 +1,30 @@
+import React, {useEffect, useRef, useState} from 'react';
+import {Text} from 'react-native';
+import type {Answer, Collection, LikertsClient, Receipt, Submission} from './index';
+import {Survey, SurveyProps} from './Survey';
+
+export interface SurveyHostMessages {loading:string;loadError:string;submitError:string}
+export interface SurveyHostProps {
+  client:LikertsClient;collectionId:string;createIdempotencyKey:()=>string;metadata?:Record<string,unknown>;
+  onComplete:(receipt:Receipt)=>void;onError?:(error:unknown)=>void;refreshOnMount?:boolean;
+  messages?:Partial<SurveyHostMessages>;surveyProps?:Omit<SurveyProps,'collection'|'onSubmit'|'disabled'|'submitting'>;
+}
+const defaults:SurveyHostMessages={loading:'Loading survey…',loadError:'Could not load survey.',submitError:'Could not confirm submission. Try again without changing the answers.'};
+
+/** Optional host adapter: owns cancellable loading/submission while Survey remains usable on its own. */
+export function SurveyHost({client,collectionId,createIdempotencyKey,metadata={},onComplete,onError,refreshOnMount=false,messages:overrides,surveyProps={}}:SurveyHostProps){
+  const messages={...defaults};for(const key of Object.keys(defaults) as (keyof SurveyHostMessages)[]){const value=overrides?.[key];if(typeof value==='string')messages[key]=value}const [collection,setCollection]=useState<Collection>();const [error,setError]=useState('');const [submitting,setSubmitting]=useState(false);const [completed,setCompleted]=useState(false);
+  const pending=useRef<{serialized:string;submission:Submission}|undefined>(undefined);const generation=useRef(0);const activeSubmit=useRef<AbortController|undefined>(undefined);
+  useEffect(()=>{const current=++generation.current;const controller=new AbortController();activeSubmit.current?.abort();setCollection(undefined);setError('');setCompleted(false);pending.current=undefined;
+    client.collection(collectionId,{refresh:refreshOnMount,signal:controller.signal}).then(value=>{if(generation.current===current)setCollection(value)}).catch(cause=>{if(!controller.signal.aborted&&generation.current===current){setError(messages.loadError);onError?.(cause)}});
+    return()=>{generation.current++;controller.abort();activeSubmit.current?.abort()};
+  },[client,collectionId,refreshOnMount]);
+  const changed=(answers:Record<string,Answer>)=>{if(pending.current?.serialized!==JSON.stringify(answers))pending.current=undefined;surveyProps.onAnswersChange?.(answers)};
+  const submit=async(answers:Record<string,Answer>)=>{if(!collection||submitting||completed)return;const serialized=JSON.stringify(answers);if(!pending.current)pending.current={serialized,submission:{idempotencyKey:createIdempotencyKey(),answers:JSON.parse(serialized),metadata:JSON.parse(JSON.stringify(metadata))}};const current=++generation.current;const controller=new AbortController();activeSubmit.current=controller;setSubmitting(true);setError('');
+    try{const receipt=await client.submit(collection.id,pending.current.submission,{signal:controller.signal});if(generation.current===current){setCompleted(true);onComplete(receipt)}}
+    catch(cause){if(generation.current===current){setError(messages.submitError);onError?.(cause)}}
+    finally{if(activeSubmit.current===controller)activeSubmit.current=undefined;if(generation.current===current)setSubmitting(false)}
+  };
+  if(!collection)return <Text testID="likerts-host-status" accessibilityRole={error?'alert':undefined} accessibilityLiveRegion="polite">{error||messages.loading}</Text>;
+  return <><Survey {...surveyProps} collection={collection} onSubmit={submit} onAnswersChange={changed} disabled={completed} submitting={submitting}/>{error?<Text testID="likerts-host-error" accessibilityRole="alert" accessibilityLiveRegion="assertive">{error}</Text>:null}</>;
+}

package/src/advanced-questions.ts

@@ -0,0 +1,7 @@
+export type AdvancedItem={id:string;label:string};export type AdvancedQuestion={type:string;required?:boolean;options?:AdvancedItem[];rows?:AdvancedItem[];columns?:AdvancedItem[];matrixMode?:'single'|'multiple';items?:AdvancedItem[];total?:number};
+export const rankingOrder=(q:AdvancedQuestion,a:unknown):string[]=>Array.isArray(a)?a.filter((id):id is string=>typeof id==='string'):(q.options??[]).map(o=>o.id);
+export function moveRanking(q:AdvancedQuestion,a:unknown,id:string,offset:-1|1){const order=rankingOrder(q,a),from=order.indexOf(id);if(from<0)return order;const to=Math.max(0,Math.min(order.length-1,from+offset)),next=[...order];next.splice(from,1);next.splice(to,0,id);return next}
+export function setMatrixChoice(q:AdvancedQuestion,a:unknown,row:string,column:string):Record<string,string|string[]>{const current=a&&typeof a==='object'&&!Array.isArray(a)?a as Record<string,string|string[]>:{};if(q.matrixMode==='single')return{...current,[row]:column};const selected=Array.isArray(current[row])?current[row] as string[]:[],next=selected.includes(column)?selected.filter(id=>id!==column):[...selected,column],result={...current};if(next.length)result[row]=next;else delete result[row];return result}
+export function setAllocation(a:unknown,item:string,value:number):Record<string,number>{return{...(a&&typeof a==='object'&&!Array.isArray(a)?a as Record<string,number>:{}),[item]:value}}
+export function allocationRemaining(q:AdvancedQuestion,a:unknown){return(q.total??0)-Object.values(a&&typeof a==='object'&&!Array.isArray(a)?a as Record<string,number>:{}).reduce((sum,value)=>sum+(Number.isSafeInteger(value)?value:0),0)}
+export function advancedAnswerError(q:AdvancedQuestion,a:unknown):string|undefined{if(a===undefined)return q.required?'required':undefined;if(q.type==='ranking'){const ids=(q.options??[]).map(o=>o.id),v=Array.isArray(a)?a:[];return v.length===ids.length&&new Set(v).size===v.length&&v.every(id=>ids.includes(id))?undefined:'ranking'}if(!a||typeof a!=='object'||Array.isArray(a))return q.type;if(q.type==='matrix'){const rows=(q.rows??[]).map(o=>o.id),columns=(q.columns??[]).map(o=>o.id),entries=Object.entries(a);return entries.length&&(!q.required||entries.length===rows.length)&&entries.every(([row,value])=>rows.includes(row)&&(q.matrixMode==='single'?typeof value==='string'&&columns.includes(value):Array.isArray(value)&&value.length>0&&new Set(value).size===value.length&&value.every(id=>typeof id==='string'&&columns.includes(id))))?undefined:'matrix'}const items=(q.items??[]).map(o=>o.id),entries=Object.entries(a);return entries.length===items.length&&entries.every(([id,value])=>items.includes(id)&&Number.isSafeInteger(value)&&Number(value)>=0&&Number(value)<=(q.total??0))&&allocationRemaining(q,a)===0?undefined:'constant_sum'}

package/src/branching.ts

@@ -0,0 +1,8 @@
+import {conditionMatches,visibleAnswers} from './index';
+import type {Answer,Question,SurveyPage} from './index';
+export interface BranchingSchema{questions:Question[];pages?:SurveyPage[]}
+export interface SurveyProgress{current:number;total:number;visited:number}
+const pages=(schema:BranchingSchema):SurveyPage[]=>schema.pages??[{id:'survey',questionIds:schema.questions.map(q=>q.id)}];
+export function pageRoute(schema:BranchingSchema,answers:Record<string,Answer>):number[]{const all=pages(schema),ids=new Map(all.map((p,i)=>[p.id,i])),visible=visibleAnswers(schema.questions,answers),available=new Set<string>(),route:number[]=[];let current=0;while(current<all.length){route.push(current);all[current].questionIds.forEach(id=>available.add(id));const branch=all[current].branches?.find(b=>conditionMatches(b.when,available.has(b.when.questionId)?visible[b.when.questionId]:undefined));current=branch?ids.get(branch.goToPageId)??all.length:current+1;}return route}
+export function routedAnswers(schema:BranchingSchema,answers:Record<string,Answer>):Record<string,Answer>{let result=visibleAnswers(schema.questions,answers);const all=pages(schema);for(let pass=0;pass<=schema.questions.length;pass++){const reached=new Set(pageRoute(schema,result).flatMap(i=>all[i].questionIds));const filtered=visibleAnswers(schema.questions,Object.fromEntries(Object.entries(result).filter(([id])=>reached.has(id))));if(Object.keys(filtered).length===Object.keys(result).length)return filtered;result=filtered}throw new Error('Survey route did not stabilize')}
+export class SurveyFlow{private route:number[];private history:number[];private current:number;private values:Record<string,Answer>;constructor(readonly schema:BranchingSchema,initial:Record<string,Answer>={}){this.values=routedAnswers(schema,{...initial});this.route=pageRoute(schema,this.values);this.current=this.route[0]??0;this.history=[this.current]}get page():SurveyPage{return pages(this.schema)[this.current]}get answers():Record<string,Answer>{return {...this.values}}get progress():SurveyProgress{return{current:this.current+1,total:pages(this.schema).length,visited:this.history.length}}setAnswer(id:string,value:Answer|undefined):void{const old=this.history;if(value===undefined)delete this.values[id];else this.values[id]=value;this.values=routedAnswers(this.schema,this.values);this.route=pageRoute(this.schema,this.values);if(!this.route.includes(this.current)){let shared=this.route[0]??0;for(let i=0;i<Math.min(old.length,this.route.length)&&old[i]===this.route[i];i++)shared=this.route[i];this.current=shared}this.history=this.route.slice(0,this.route.indexOf(this.current)+1)}next():boolean{const at=this.route.indexOf(this.current);if(at<0||at+1>=this.route.length)return false;this.current=this.route[at+1];this.history=this.route.slice(0,at+2);return true}back():boolean{if(this.history.length<2)return false;this.history.pop();this.current=this.history[this.history.length-1];return true}}