@likerts/react-native 0.0.3

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.0.3 — 2026-09-09
+
+- Schema 5 adds ranking, single/multiple matrix and exact-total constant-sum questions with bounded answer schemas.
+- Native controls use explicit rank movement, stacked matrix rows and an announced constant-sum remainder.
+
+## 0.0.2 — 2026-09-09
+
+- Schema 3 adds conditional visibility, structured Other text, exclusive None choices, stars and dropdown presentations. Existing schema 1/2 answers remain compatible.
+- Schema 4 adds pages, forward routing, page validation, Back/Next navigation, progress and removal of skipped answers.
+- Host-controlled triggers, submission and distribution remain unchanged. No package publication.
+
+## 0.0.1 — 2026-09-08
+
+- Collection-only client and six-type native renderer with NPS/yes-no, labels and selection bounds.
+- Cancellable SurveyHost adapter preserves submission intent after ambiguous failures; host supplies its key generator.
+- React Native source entry, compiled library/type declarations and customer-controlled checkout trigger example.
+
+Local evaluation artifact for the recorded React Native 0.85–0.87 matrix. Publication and physical-device release checks remain separate.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Likerts contributors
+
+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/README.md

@@ -0,0 +1,68 @@
+# Likerts React Native SDK
+
+## Install
+
+Install a published version from npm:
+
+```sh
+npm install @likerts/react-native
+```
+
+You can also use the installable tarballs from the [community release](https://github.com/crosstabs/likerts/releases/tag/community-v0.1.0).
+
+## Install the current source
+
+The free community edition supports schemas 1–5. Clone the repository and run these commands from its root:
+
+```sh
+npm ci --prefix sdks/react-native
+npm run build --prefix sdks/react-native
+cd sdks/react-native
+npm pack
+```
+
+From a host app on the supported React/React Native matrix, run `npm install /absolute/path/to/likerts/sdks/react-native/likerts-react-native-0.0.3.tgz` to install the tarball you just built. The package supplies a React Native source entry for Metro and compiled TypeScript declarations. It has no native module, autolinking step or pod installation of its own. React and React Native remain host peer dependencies. Frozen archives under `releases/` predate the free edition; build current source rather than installing those historical packages.
+
+Import `LikertsClient` and `SurveyHost` from `@likerts/react-native`. `examples/CheckoutFeedback.tsx` shows host-controlled eligibility, a feedback button, dismissal and completion. Supply the host runtime's cryptographically strong key generator and a collection-only token; no management credential belongs in the bundle. Repository build/test commands below are for SDK contributors.
+
+The package provides a public collection client, a native `Survey` renderer and an optional `SurveyHost` adapter. Administrative credentials do not belong in an iOS or Android bundle.
+
+`Survey` is the lower-level component. The app owns loading, submission, errors and dismissal. It accepts translated operational messages, typed native style slots, initial answers, answer-change and validation callbacks, and a stable `testID` prefix. Controls expose question-qualified accessibility labels, selected/disabled/busy state and announced validation errors. Changing the collection identity resets answers and validation state.
+
+`SurveyHost` is a small host-app adapter for teams that want the SDK to connect the client and renderer. It cancels collection loading and an active submission when its screen unmounts, keeps the same submission and idempotency key after an ambiguous failure, clears that pending intent when answers change, and invokes `onComplete` once after a valid receipt.
+
+```tsx
+const client = new LikertsClient('https://feedback.example.com', publicCollectionToken);
+
+<SurveyHost
+  client={client}
+  collectionId={collectionId}
+  createIdempotencyKey={() => randomUUIDFromYourNativeRuntime()}
+  metadata={{screen: 'receipt'}}
+  onComplete={() => navigation.goBack()}
+  onError={reportError}
+  surveyProps={{
+    messages: {submit: 'Send feedback', requiredSuffix: 'required'},
+    styles: {container: styles.survey, submit: styles.primaryButton},
+    testID: 'checkout-feedback',
+  }}
+/>
+```
+
+The host supplies the key generator because React Native runtime crypto support varies. Create a key for one intended submission and preserve it across ambiguous retries. The adapter does this automatically.
+
+## Supported framework matrix
+
+| React Native | React | Android/iOS renderer contract | Status |
+|---|---|---|---|
+| 0.85.x | 19.2.3 | TypeScript and Jest native-component integration | Passed on 0.85.0 |
+| 0.86.x | 19.2.3 | TypeScript and Jest native-component integration | Passed on 0.86.3; locked development baseline |
+| 0.87.x | 19.2.3 | TypeScript and Jest native-component integration | Passed on 0.87.0 |
+
+Run `scripts/check-react-native-matrix.sh` from the repository root to reinstall and test all three exact baselines. The suite exercises both `Platform.OS` values and native accessibility/control props. These checks do not claim App Store/Play device certification; physical-device release rehearsal remains part of the cross-platform release gate. Separate [Android and iOS native-host runners](native-host/README.md) embed the real RN 0.86.3 renderer and exercise validation, accessibility state and exact advanced-question answers. They passed on an API-35 ARM64 emulator and iOS 26.4 simulator; they do not establish hosted networking, offline adapters or every OS/framework version.
+
+React Native 0.85+ requires a supported Node release; this repository uses Node 22. The package uses public React Native component APIs and the New Architecture compatible surface only.
+
+Schema 3 choice semantics are documented in [CHOICE-FEATURES.md](../../contracts/CHOICE-FEATURES.md): Other answers carry separate selected IDs and text; None is exclusive; stars retain numeric answers and dropdowns retain option IDs.
+
+Schema 5 adds the bounded advanced families in [ADVANCED-QUESTIONS.md](../../contracts/ADVANCED-QUESTIONS.md). Ranking uses explicit accessible Move up/down controls. Matrix rows are stacked for narrow screens and emit row-to-column ID maps. Constant-sum inputs announce the remaining amount and emit every item ID only when integer allocations equal the configured total.

package/examples/CheckoutFeedback.tsx

@@ -0,0 +1,18 @@
+import React, {useState} from 'react';
+import {Button, View} from 'react-native';
+import {LikertsClient, SurveyHost, type Receipt} from '@likerts/react-native';
+
+export function CheckoutFeedback({client, collectionId, eligible, createIdempotencyKey, onComplete}: {
+  client: LikertsClient; collectionId: string; eligible: boolean;
+  createIdempotencyKey: () => string; onComplete: (receipt: Receipt) => void;
+}) {
+  const [visible, setVisible] = useState(false);
+  if (!eligible) return null;
+  return <View>
+    <Button title="Give feedback" onPress={() => setVisible(true)} />
+    {visible && <SurveyHost client={client} collectionId={collectionId}
+      createIdempotencyKey={createIdempotencyKey} metadata={{placement: 'receipt'}}
+      onComplete={receipt => {setVisible(false); onComplete(receipt);}} />}
+    {visible && <Button title="Dismiss" onPress={() => setVisible(false)} />}
+  </View>;
+}

package/lib/Survey.d.ts

@@ -0,0 +1,47 @@
+import React from 'react';
+import { StyleProp, TextStyle, ViewStyle } from 'react-native';
+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;
+}
+/** Host owns network lifecycle, placement and dismissal; renderer checks selection bounds. */
+export declare function Survey({ collection, onSubmit, disabled, submitting, initialAnswers, onAnswersChange, onValidationError, messages: overrides, styles, testID }: SurveyProps): React.JSX.Element;

package/lib/Survey.js

@@ -0,0 +1,102 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { selectedChoices, otherTexts, toggleChoice, setOtherText, choiceError } from './choice-features';
+import { useEffect, useState } from 'react';
+import { AccessibilityInfo, Pressable, Text, TextInput, View } from 'react-native';
+import { visibleQuestionIds } from './index';
+import { pageRoute, routedAnswers } from './branching';
+import { advancedAnswerError, allocationRemaining, moveRanking, rankingOrder, setAllocation, setMatrixChoice } from './advanced-questions';
+const defaults = { 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, values) => 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' }) {
+    const messages = { ...defaults };
+    for (const key of Object.keys(defaults)) {
+        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(() => routedAnswers(collection.schema, { ...initialAnswers }));
+    const [error, setError] = useState('');
+    const [openDropdowns, setOpenDropdowns] = useState({});
+    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, value) => { 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) => { 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 = {}; 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 _jsxs(View, { style: styles.container, testID: testID, accessibilityLabel: collection.schema.title, children: [_jsx(Text, { style: styles.title, accessibilityRole: "header", testID: `${testID}-title`, children: collection.schema.title }), collection.schema.pages ? _jsx(Text, { testID: `${testID}-progress`, children: format(messages.progress, { current: currentPage + 1, total: pages.length }) }) : 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 _jsxs(View, { style: styles.question, testID: `${testID}-question-${q.id}`, children: [_jsxs(Text, { style: styles.label, nativeID: labelId, children: [q.label, q.required ? ` (${messages.requiredSuffix})` : ''] }), q.type === 'ranking' ? rankingOrder(q, answers[q.id]).map((id, index) => { const option = q.options?.find(value => value.id === id); return _jsxs(View, { children: [_jsxs(Text, { style: styles.choiceText, children: [index + 1, ". ", option.label] }), _jsx(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)), children: _jsx(Text, { children: messages.moveUp }) }), _jsx(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)), children: _jsx(Text, { children: messages.moveDown }) })] }, id); })
+                            : q.type === 'matrix' ? (q.rows ?? []).map(row => _jsxs(View, { children: [_jsx(Text, { style: styles.choiceText, children: row.label }), (q.columns ?? []).map(column => { const value = answers[q.id]?.[row.id], selected = Array.isArray(value) ? value.includes(column.id) : value === column.id; return _jsx(Pressable, { 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)), children: _jsxs(Text, { children: [selected ? '✓ ' : '', column.label] }) }, column.id); })] }, row.id))
+                                : q.type === 'constant_sum' ? _jsxs(_Fragment, { children: [(q.items ?? []).map(item => _jsx(TextInput, { style: styles.input, testID: `${testID}-${q.id}-${item.id}`, accessibilityLabel: `${q.label}: ${item.label}`, keyboardType: "number-pad", editable: !blocked, value: String(answers[q.id]?.[item.id] ?? ''), onChangeText: value => update(q.id, current => setAllocation(current, item.id, Number(value))) }, item.id)), _jsx(Text, { accessibilityLiveRegion: "polite", testID: `${testID}-${q.id}-remaining`, children: format(messages.remaining, { remaining: allocationRemaining(q, answers[q.id]) }) })] })
+                                    : _jsxs(_Fragment, { children: [q.presentation === 'dropdown' ? _jsx(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] })), children: _jsx(Text, { style: styles.choiceText, children: q.options?.find(o => o.id === selectedChoices(answers[q.id])[0])?.label ?? messages.selectPlaceholder }) }) : 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 _jsx(Pressable, { 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 }));
+                                                    } }, children: _jsxs(Text, { style: styles.choiceText, children: [selected ? '✓ ' : '', option.label] }) }, option.id);
+                                            })
+                                                : 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 _jsx(Pressable, { 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); }, children: _jsx(Text, { style: styles.choiceText, children: q.presentation === 'stars' ? '★'.repeat(value) : label }) }, value); })
+                                                    : _jsx(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 => _jsx(TextInput, { 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)) }, option.id))] }, q.id);
+            }), error ? _jsx(Text, { style: styles.error, testID: `${testID}-error`, accessibilityRole: "alert", accessibilityLiveRegion: "assertive", children: error }) : null, collection.schema.pages && history.length > 1 ? _jsx(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('');
+                } }, children: _jsx(Text, { style: styles.submitText, children: messages.back }) }) : null, _jsx(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(); }, children: _jsx(Text, { style: styles.submitText, children: submitting ? messages.submitting : routeIndex + 1 < route.length ? messages.next : messages.submit }) })] });
+}

package/lib/SurveyHost.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+import type { LikertsClient, Receipt } from './index';
+import { 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'>;
+}
+/** Optional host adapter: owns cancellable loading/submission while Survey remains usable on its own. */
+export declare function SurveyHost({ client, collectionId, createIdempotencyKey, metadata, onComplete, onError, refreshOnMount, messages: overrides, surveyProps }: SurveyHostProps): React.JSX.Element;

package/lib/SurveyHost.js

@@ -0,0 +1,72 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { Text } from 'react-native';
+import { Survey } from './Survey';
+const defaults = { 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 = {} }) {
+    const messages = { ...defaults };
+    for (const key of Object.keys(defaults)) {
+        const value = overrides?.[key];
+        if (typeof value === 'string')
+            messages[key] = value;
+    }
+    const [collection, setCollection] = useState();
+    const [error, setError] = useState('');
+    const [submitting, setSubmitting] = useState(false);
+    const [completed, setCompleted] = useState(false);
+    const pending = useRef(undefined);
+    const generation = useRef(0);
+    const activeSubmit = useRef(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) => { if (pending.current?.serialized !== JSON.stringify(answers))
+        pending.current = undefined; surveyProps.onAnswersChange?.(answers); };
+    const submit = async (answers) => {
+        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 _jsx(Text, { testID: "likerts-host-status", accessibilityRole: error ? 'alert' : undefined, accessibilityLiveRegion: "polite", children: error || messages.loading });
+    return _jsxs(_Fragment, { children: [_jsx(Survey, { ...surveyProps, collection: collection, onSubmit: submit, onAnswersChange: changed, disabled: completed, submitting: submitting }), error ? _jsx(Text, { testID: "likerts-host-error", accessibilityRole: "alert", accessibilityLiveRegion: "assertive", children: error }) : null] });
+}

package/lib/advanced-questions.d.ts

@@ -0,0 +1,20 @@
+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 declare const rankingOrder: (q: AdvancedQuestion, a: unknown) => string[];
+export declare function moveRanking(q: AdvancedQuestion, a: unknown, id: string, offset: -1 | 1): string[];
+export declare function setMatrixChoice(q: AdvancedQuestion, a: unknown, row: string, column: string): Record<string, string | string[]>;
+export declare function setAllocation(a: unknown, item: string, value: number): Record<string, number>;
+export declare function allocationRemaining(q: AdvancedQuestion, a: unknown): number;
+export declare function advancedAnswerError(q: AdvancedQuestion, a: unknown): string | undefined;

package/lib/advanced-questions.js

@@ -0,0 +1,19 @@
+export const rankingOrder = (q, a) => Array.isArray(a) ? a.filter((id) => typeof id === 'string') : (q.options ?? []).map(o => o.id);
+export function moveRanking(q, a, id, offset) { 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, a, row, column) { const current = a && typeof a === 'object' && !Array.isArray(a) ? a : {}; if (q.matrixMode === 'single')
+    return { ...current, [row]: column }; const selected = Array.isArray(current[row]) ? current[row] : [], 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, item, value) { return { ...(a && typeof a === 'object' && !Array.isArray(a) ? a : {}), [item]: value }; }
+export function allocationRemaining(q, a) { return (q.total ?? 0) - Object.values(a && typeof a === 'object' && !Array.isArray(a) ? a : {}).reduce((sum, value) => sum + (Number.isSafeInteger(value) ? value : 0), 0); }
+export function advancedAnswerError(q, a) { 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/lib/branching.d.ts

@@ -0,0 +1,26 @@
+import type { Answer, Question, SurveyPage } from './index';
+export interface BranchingSchema {
+    questions: Question[];
+    pages?: SurveyPage[];
+}
+export interface SurveyProgress {
+    current: number;
+    total: number;
+    visited: number;
+}
+export declare function pageRoute(schema: BranchingSchema, answers: Record<string, Answer>): number[];
+export declare function routedAnswers(schema: BranchingSchema, answers: Record<string, Answer>): Record<string, Answer>;
+export declare class SurveyFlow {
+    readonly schema: BranchingSchema;
+    private route;
+    private history;
+    private current;
+    private values;
+    constructor(schema: BranchingSchema, initial?: Record<string, Answer>);
+    get page(): SurveyPage;
+    get answers(): Record<string, Answer>;
+    get progress(): SurveyProgress;
+    setAnswer(id: string, value: Answer | undefined): void;
+    next(): boolean;
+    back(): boolean;
+}

package/lib/branching.js

@@ -0,0 +1,45 @@
+import { conditionMatches, visibleAnswers } from './index';
+const pages = (schema) => schema.pages ?? [{ id: 'survey', questionIds: schema.questions.map(q => q.id) }];
+export function pageRoute(schema, answers) { const all = pages(schema), ids = new Map(all.map((p, i) => [p.id, i])), visible = visibleAnswers(schema.questions, answers), available = new Set(), route = []; 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, answers) { 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 {
+    schema;
+    route;
+    history;
+    current;
+    values;
+    constructor(schema, initial = {}) {
+        this.schema = schema;
+        this.values = routedAnswers(schema, { ...initial });
+        this.route = pageRoute(schema, this.values);
+        this.current = this.route[0] ?? 0;
+        this.history = [this.current];
+    }
+    get page() { return pages(this.schema)[this.current]; }
+    get answers() { return { ...this.values }; }
+    get progress() { return { current: this.current + 1, total: pages(this.schema).length, visited: this.history.length }; }
+    setAnswer(id, value) { 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() { 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() { if (this.history.length < 2)
+        return false; this.history.pop(); this.current = this.history[this.history.length - 1]; return true; }
+}

package/lib/choice-features.d.ts

@@ -0,0 +1,9 @@
+import type { Answer, Question } from './index';
+/** Selected option IDs have the same meaning across legacy and structured answers. */
+export declare function selectedChoices(value: unknown): string[];
+export declare function otherTexts(value: unknown): Record<string, string>;
+export declare function choiceAnswer(q: Question, selected: string[], text?: Record<string, string>): Answer;
+export declare function toggleChoice(q: Question, value: unknown, id: string): Answer;
+export declare function setOtherText(q: Question, value: unknown, id: string, text: string): Answer;
+/** Local feedback only; the server validates every accepted answer again. */
+export declare function choiceError(q: Question, value: unknown): 'required' | 'range' | 'other' | 'invalid' | undefined;

package/lib/choice-features.js

@@ -0,0 +1,59 @@
+/** Selected option IDs have the same meaning across legacy and structured answers. */
+export function selectedChoices(value) {
+    if (typeof value === 'string')
+        return value ? [value] : [];
+    if (Array.isArray(value))
+        return value.filter((v) => typeof v === 'string');
+    if (value && typeof value === 'object' && 'selected' in value && Array.isArray(value.selected))
+        return value.selected.filter((v) => typeof v === 'string');
+    return [];
+}
+export function otherTexts(value) {
+    if (!value || typeof value !== 'object' || !('otherText' in value) || !value.otherText || typeof value.otherText !== 'object' || Array.isArray(value.otherText))
+        return {};
+    return Object.fromEntries(Object.entries(value.otherText).filter((entry) => typeof entry[1] === 'string'));
+}
+export function choiceAnswer(q, selected, text = {}) {
+    if (q.options?.some(o => o.other !== undefined))
+        return { selected: [...selected], otherText: Object.fromEntries((q.options ?? []).filter(o => o.other !== undefined && selected.includes(o.id)).map(o => [o.id, text[o.id] ?? ''])) };
+    return q.type === 'single_choice' ? selected[0] ?? '' : [...selected];
+}
+export function toggleChoice(q, value, id) {
+    const option = q.options?.find(o => o.id === id);
+    if (!option)
+        throw new TypeError('Unknown choice');
+    const current = selectedChoices(value);
+    const selected = q.type === 'single_choice' ? [id] : current.includes(id) ? current.filter(v => v !== id) : option.exclusive ? [id] : [...current.filter(v => !q.options?.find(o => o.id === v)?.exclusive), id];
+    return choiceAnswer(q, selected, otherTexts(value));
+}
+export function setOtherText(q, value, id, text) {
+    return choiceAnswer(q, selectedChoices(value), { ...otherTexts(value), [id]: text });
+}
+/** Local feedback only; the server validates every accepted answer again. */
+export function choiceError(q, value) {
+    if (value === undefined || value === '')
+        return q.required ? 'required' : undefined;
+    const hasOther = q.options?.some(o => o.other !== undefined);
+    if (hasOther) {
+        if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length !== 2 || !('selected' in value) || !Array.isArray(value.selected) || !value.selected.every(v => typeof v === 'string') || !('otherText' in value) || !value.otherText || typeof value.otherText !== 'object' || Array.isArray(value.otherText))
+            return 'invalid';
+    }
+    else if (q.type === 'single_choice' ? typeof value !== 'string' : !Array.isArray(value) || !value.every(v => typeof v === 'string'))
+        return 'invalid';
+    const selected = selectedChoices(value);
+    if (new Set(selected).size !== selected.length || selected.some(id => !q.options?.some(o => o.id === id)))
+        return 'invalid';
+    const exclusive = selected.some(id => q.options?.some(o => o.id === id && o.exclusive));
+    if (exclusive && selected.length !== 1)
+        return 'invalid';
+    if (q.type === 'single_choice' ? selected.length !== 1 : selected.length > (q.maxSelections ?? q.options?.length ?? 0) || (!exclusive && selected.length < Math.max(q.required ? 1 : 0, q.minSelections ?? 0)))
+        return 'range';
+    if (hasOther) {
+        const text = otherTexts(value), expected = (q.options ?? []).filter(o => o.other !== undefined && selected.includes(o.id));
+        if (Object.keys(value.otherText).length !== expected.length)
+            return 'other';
+        if (expected.some(o => typeof text[o.id] !== 'string' || !text[o.id].trim() || Array.from(text[o.id]).length > o.other.maxLength))
+            return 'other';
+    }
+    return undefined;
+}