@selfhelp/sh2-shp-survey-js-mobile 0.3.0

package/src/runtime/controller.ts

@@ -0,0 +1,166 @@
+/*
+SPDX-FileCopyrightText: 2026 Humdek, University of Bern
+SPDX-License-Identifier: MPL-2.0
+*/
+/**
+ * SurveyJS WebView runtime controller.
+ *
+ * This is the DOM-free brain of the isolated WebView runtime: given a
+ * `survey-core` model and the typed bridge `post`, it owns the survey
+ * lifecycle WITHOUT touching the network. It emits intents
+ * (`SAVE_PROGRESS` / `SUBMIT_SURVEY` / `REQUEST_REDIRECT`) and reacts to the
+ * results the native host returns (`SUBMIT_RESULT` / `SESSION_EXPIRED` /
+ * `PROGRESS_SAVED` / `SET_LOCALE`).
+ *
+ * Keeping it framework- and DOM-free means the unit test drives a REAL
+ * `survey-core` model (fill -> validate -> complete) headlessly in Node and
+ * asserts the controller emits `SUBMIT_SURVEY` (never a `fetch`).
+ */
+
+import type { THostToWebviewMessage, TWebviewToHostMessage } from '../bridge/messages';
+import { BRIDGE_SOURCE } from '../bridge/messages';
+import type { IRuntimeSectionConfig } from '../styles/section';
+import { buildEnforcePayload, newResponseId } from './lifecycle';
+
+export type TRuntimeLifecycle =
+    | 'booting'
+    | 'loading'
+    | 'ready'
+    | 'submitting'
+    | 'submitted'
+    | 'locked'
+    | 'session-expired'
+    | 'error';
+
+export interface IRuntimeLifecycleDetail {
+    message?: string;
+    submittedAt?: string;
+}
+
+/** The slice of the `survey-core` `Model` the controller depends on. */
+export interface ISurveyModelLike {
+    data: Record<string, unknown>;
+    currentPageNo: number;
+    locale: string;
+    onCurrentPageChanged: { add(cb: () => void): void };
+    onComplete: { add(cb: (sender: ISurveyModelLike) => void): void };
+}
+
+export interface IControllerOptions {
+    config: IRuntimeSectionConfig;
+    post: (msg: TWebviewToHostMessage) => void;
+    onLifecycle: (lifecycle: TRuntimeLifecycle, detail?: IRuntimeLifecycleDetail) => void;
+    /** Response id restored from a server draft, if any. */
+    initialResponseId?: string | null;
+}
+
+export interface ISurveyRuntimeController {
+    attachModel(model: ISurveyModelLike): void;
+    handleHostMessage(msg: THostToWebviewMessage): void;
+    getResponseId(): string | null;
+    getLifecycle(): TRuntimeLifecycle;
+}
+
+/** True for an absolute URL with a scheme (`https://`, `mailto:`-style schemes). */
+export function isExternalRedirect(target: string): boolean {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(target);
+}
+
+export function createSurveyRuntimeController(options: IControllerOptions): ISurveyRuntimeController {
+    const { config, post, onLifecycle } = options;
+    let responseId: string | null = options.initialResponseId ?? null;
+    let lifecycle: TRuntimeLifecycle = 'booting';
+    let model: ISurveyModelLike | null = null;
+
+    function setLifecycle(next: TRuntimeLifecycle, detail?: IRuntimeLifecycleDetail): void {
+        lifecycle = next;
+        onLifecycle(next, detail);
+    }
+
+    function ensureResponseId(): string {
+        if (responseId === null) responseId = newResponseId();
+        return responseId;
+    }
+
+    function attachModel(nextModel: ISurveyModelLike): void {
+        model = nextModel;
+
+        nextModel.onCurrentPageChanged.add(() => {
+            post({
+                source: BRIDGE_SOURCE,
+                type: 'SAVE_PROGRESS',
+                responseId: ensureResponseId(),
+                pageNo: nextModel.currentPageNo,
+                data: nextModel.data,
+                locale: nextModel.locale,
+            });
+        });
+
+        nextModel.onComplete.add((sender) => {
+            setLifecycle('submitting');
+            const enforce = buildEnforcePayload(config, responseId, sender.currentPageNo);
+            post({
+                source: BRIDGE_SOURCE,
+                type: 'SUBMIT_SURVEY',
+                responseId,
+                data: sender.data,
+                enforce,
+            });
+        });
+
+        setLifecycle('ready');
+    }
+
+    function handleSubmitResult(msg: Extract<THostToWebviewMessage, { type: 'SUBMIT_RESULT' }>): void {
+        if (msg.ok) {
+            responseId = msg.responseId;
+            if (config.oncePerUser || config.oncePerSchedule) {
+                setLifecycle('locked');
+            } else {
+                setLifecycle('submitted', { submittedAt: msg.submittedAt });
+            }
+            if (config.redirectAtEnd) {
+                post({
+                    source: BRIDGE_SOURCE,
+                    type: 'REQUEST_REDIRECT',
+                    target: config.redirectAtEnd,
+                    external: isExternalRedirect(config.redirectAtEnd),
+                });
+            }
+            return;
+        }
+        if (msg.reason === 'already_submitted_once' || msg.reason === 'already_submitted_in_window') {
+            setLifecycle('locked');
+            return;
+        }
+        setLifecycle('error', { message: msg.message });
+    }
+
+    function handleHostMessage(msg: THostToWebviewMessage): void {
+        switch (msg.type) {
+            case 'SUBMIT_RESULT':
+                handleSubmitResult(msg);
+                return;
+            case 'SESSION_EXPIRED':
+                setLifecycle('session-expired');
+                return;
+            case 'PROGRESS_SAVED':
+                if (msg.responseId) responseId = msg.responseId;
+                return;
+            case 'SET_LOCALE':
+                if (model) model.locale = msg.locale;
+                return;
+            default:
+                // INIT / SURVEY_LOADED are consumed by the React app (it builds
+                // the model); the controller ignores them.
+                return;
+        }
+    }
+
+    return {
+        attachModel,
+        handleHostMessage,
+        getResponseId: () => responseId,
+        getLifecycle: () => lifecycle,
+    };
+}

package/src/runtime/lifecycle.ts

@@ -0,0 +1,118 @@
+/*
+SPDX-FileCopyrightText: 2026 Humdek, University of Bern
+SPDX-License-Identifier: MPL-2.0
+*/
+/**
+ * Pure, DOM-free SurveyJS lifecycle helpers shared by the WebView runtime
+ * controller and the host shell. These mirror the frontend runtime
+ * (`frontend/src/runtime/SurveyRuntime.tsx`) so mobile enforces the SAME
+ * once-per-user / schedule / redirect semantics as the web — the behaviour
+ * parity the plan requires.
+ *
+ * Nothing here touches `document`/`window` or `survey-react-ui`, so the unit
+ * tests run headless in Node against the real `survey-core` model.
+ */
+
+import type { IRuntimeSectionConfig } from '../styles/section';
+import type { ISubmissionEnforcePayload } from '../api/surveys';
+
+/** Build the `enforce` payload the backend re-validates the submission against. */
+export function buildEnforcePayload(
+    config: IRuntimeSectionConfig,
+    responseId: string | null,
+    pageNo: number,
+): ISubmissionEnforcePayload {
+    const scheduleWindow = config.oncePerSchedule
+        ? resolveScheduleWindow(config.startTime, config.endTime)
+        : null;
+    return {
+        oncePerUser: config.oncePerUser,
+        oncePerSchedule: config.oncePerSchedule,
+        allowAnonymous: config.allowAnonymous,
+        windowStart: scheduleWindow?.start ?? null,
+        windowEnd: scheduleWindow?.end ?? null,
+        responseId: responseId ?? undefined,
+        editMode: false,
+        progress: { pageNo, triggerType: 'finished' },
+    };
+}
+
+/** True when the current local time falls outside a configured daily window. */
+export function isOutsideSchedule(config: { startTime: string | null; endTime: string | null }): boolean {
+    if (!config.startTime || !config.endTime) return false;
+    if (config.startTime === '00:00' && config.endTime === '00:00') return false;
+    const start = parseClockTime(config.startTime);
+    const end = parseClockTime(config.endTime);
+    if (start === null || end === null) return false;
+    const now = new Date();
+    const minutesNow = now.getHours() * 60 + now.getMinutes();
+    if (start <= end) {
+        return minutesNow < start || minutesNow > end;
+    }
+    return minutesNow > end && minutesNow < start;
+}
+
+export function resolveScheduleWindow(
+    startTime: string | null,
+    endTime: string | null,
+): { start: string; end: string } | null {
+    const start = parseClockTimeParts(startTime);
+    const end = parseClockTimeParts(endTime);
+    if (!start || !end) return null;
+    const now = new Date();
+    const windowStart = new Date(now);
+    windowStart.setHours(start.hour, start.minute, 0, 0);
+    const windowEnd = new Date(now);
+    windowEnd.setHours(end.hour, end.minute, 0, 0);
+    if (windowStart.getTime() > windowEnd.getTime()) {
+        if (windowEnd.getTime() > now.getTime()) {
+            windowStart.setDate(windowStart.getDate() - 1);
+        } else {
+            windowEnd.setDate(windowEnd.getDate() + 1);
+        }
+    }
+    return { start: windowStart.toISOString(), end: windowEnd.toISOString() };
+}
+
+function parseClockTime(time: string | null): number | null {
+    const parts = parseClockTimeParts(time);
+    return parts ? parts.hour * 60 + parts.minute : null;
+}
+
+function parseClockTimeParts(time: string | null): { hour: number; minute: number } | null {
+    if (!time || !/^\d{1,2}:\d{2}$/.test(time)) return null;
+    const parts = time.split(':').map((part) => Number.parseInt(part, 10));
+    return { hour: parts[0] ?? 0, minute: parts[1] ?? 0 };
+}
+
+/** Generate a `R_...` response id; uses Web Crypto when available. */
+export function cryptoRandomHex(byteLength: number): string {
+    const bytes = new Uint8Array(byteLength);
+    const webCrypto = (globalThis as { crypto?: { getRandomValues?: (array: Uint8Array) => void } }).crypto;
+    if (webCrypto && typeof webCrypto.getRandomValues === 'function') {
+        webCrypto.getRandomValues(bytes);
+    } else {
+        for (let i = 0; i < byteLength; i++) bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('').toUpperCase();
+}
+
+export function newResponseId(): string {
+    return `R_${cryptoRandomHex(8)}`;
+}
+
+/**
+ * CMS status labels can arrive as editor HTML (`<p>…</p>`); the WebView shell
+ * surfaces plain text, so strip tags down to readable content.
+ */
+export function stripHtml(label: string | null): string | null {
+    const value = label?.trim() ?? '';
+    if (value === '') return null;
+    const text = value
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/<br\s*\/?>(?!$)/gi, ' ')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&nbsp;/gi, ' ')
+        .trim();
+    return text === '' ? null : text;
+}

package/src/styles/SurveyJsStyle.tsx

@@ -0,0 +1,347 @@
+/*
+SPDX-FileCopyrightText: 2026 Humdek, University of Bern
+SPDX-License-Identifier: MPL-2.0
+*/
+/**
+ * `surveyjs` mobile style — native host shell.
+ *
+ * Hosts the OFFICIAL SurveyJS web runtime (`survey-core` + `survey-react-ui`)
+ * inside an isolated, self-contained WebView (react-native-webview on native,
+ * an iframe on the Expo web export) and drives it with the typed postMessage
+ * bridge. This shell:
+ *   - owns ALL authenticated backend access via `@selfhelp/shared`
+ *     `MobileHostServices` (token + 401-refresh + session-expiry live in the
+ *     host; the WebView never sees the token);
+ *   - answers the runtime's intents (`LOAD_SURVEY` / `SAVE_PROGRESS` /
+ *     `SUBMIT_SURVEY`) by calling `/published`, `/progress`, `/submit` and
+ *     returning the result (`SURVEY_LOADED` / `PROGRESS_SAVED` /
+ *     `SUBMIT_RESULT` / `SESSION_EXPIRED`);
+ *   - sizes the WebView from `RESIZE`, handles `REQUEST_REDIRECT`, and renders
+ *     the loading / error / retry / session-expired chrome around it.
+ *
+ * The survey UI (questions, validation, completion) is owned entirely by
+ * SurveyJS inside the WebView. This shell only renders the outer chrome.
+ */
+
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { ActivityIndicator, Linking, Platform, Pressable, Text, View } from 'react-native';
+
+import { getMobileHostServices } from '@selfhelp/shared/plugin-sdk';
+import type { IMobileHostServices } from '@selfhelp/shared/plugin-sdk';
+
+import {
+    SurveyHostError,
+    fetchDraft,
+    loadPublishedSurvey,
+    saveProgress,
+    submitSurvey,
+} from '../api/surveys';
+import {
+    BRIDGE_SOURCE,
+    isWebviewToHostMessage,
+    type THostToWebviewMessage,
+    type TWebviewToHostMessage,
+} from '../bridge/messages';
+import { SURVEYJS_WEBVIEW_HTML } from '../webview/htmlAsset';
+import type { IWebViewTransportProps } from './transport/contract';
+import {
+    buildRuntimeConfigFromSection,
+    configToServerConfig,
+    extractSurveyId,
+    type ISectionLike,
+} from './section';
+
+export interface ISurveyJsStyleProps {
+    section: ISectionLike;
+    values?: Record<string, unknown>;
+}
+
+type TShellState =
+    | { kind: 'running' }
+    | { kind: 'session-expired' }
+    | { kind: 'error'; message: string };
+
+/**
+ * URLs the WebView itself may load — everything else is blocked. This is the
+ * navigation guard wired into the native transport's
+ * `onShouldStartLoadWithRequest`, so it is the enforcement point for "no
+ * arbitrary navigation / block unknown external URLs". Only the self-contained
+ * runtime document load is allowed (`source={{ html }}` resolves to
+ * `about:blank` on native, `about:srcdoc` in the web-export iframe; `data:` is
+ * permitted for inline assets the runtime may reference). Real redirects never
+ * happen via WebView navigation — the runtime emits `REQUEST_REDIRECT` and the
+ * native host performs the navigation. Exported for the WebView security tests.
+ */
+export function isAllowedWebViewUrl(url: string): boolean {
+    return url === '' || url === 'about:blank' || url.startsWith('data:') || url.startsWith('about:srcdoc');
+}
+
+function loadTransport(): React.ComponentType<IWebViewTransportProps> {
+    // Lazy-require the matching transport so the native module
+    // (react-native-webview) is never evaluated on web, and the DOM iframe is
+    // never evaluated on native. `require` is provided by the RN runtime.
+    if (Platform.OS === 'web') {
+        return (require('./transport/SurveyWebViewWeb') as {
+            SurveyWebViewWeb: React.ComponentType<IWebViewTransportProps>;
+        }).SurveyWebViewWeb;
+    }
+    return (require('./transport/SurveyWebViewNative') as {
+        SurveyWebViewNative: React.ComponentType<IWebViewTransportProps>;
+    }).SurveyWebViewNative;
+}
+
+function extractDraftData(payload: Record<string, unknown>): Record<string, unknown> {
+    const data = payload.data;
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        return data as Record<string, unknown>;
+    }
+    return {};
+}
+
+export function SurveyJsStyle({ section }: ISurveyJsStyleProps): React.ReactElement | null {
+    const surveyKey = useMemo(() => extractSurveyId(section), [section]);
+    const config = useMemo(() => buildRuntimeConfigFromSection(section), [section]);
+    const host = useMemo<IMobileHostServices | null>(() => getMobileHostServices(), []);
+
+    const [state, setState] = useState<TShellState>({ kind: 'running' });
+    const [height, setHeight] = useState<number>(320);
+    const [reloadKey, setReloadKey] = useState<number>(0);
+
+    const postRef = useRef<((json: string) => void) | null>(null);
+
+    const post = useCallback((message: THostToWebviewMessage): void => {
+        postRef.current?.(JSON.stringify(message));
+    }, []);
+
+    const handleRedirect = useCallback((target: string, external: boolean): void => {
+        if (Platform.OS === 'web') {
+            const location = (globalThis as { location?: { assign?: (t: string) => void } }).location;
+            if (location && typeof location.assign === 'function') {
+                location.assign(target);
+                return;
+            }
+        }
+        if (external) {
+            void Linking.openURL(target);
+            return;
+        }
+        // Internal CMS-keyword navigation on native needs the host router, which
+        // a decoupled plugin package cannot reach. Documented limitation: the
+        // completion screen stays visible instead.
+        console.warn(`[surveyjs] internal redirect "${target}" is not supported on native; staying on completion.`);
+    }, []);
+
+    const onIntent = useCallback(
+        async (message: TWebviewToHostMessage): Promise<void> => {
+            if (!host || !surveyKey) return;
+            switch (message.type) {
+                case 'READY':
+                    post({ source: BRIDGE_SOURCE, type: 'INIT', surveyKey, config, theme: null, locale: null });
+                    return;
+                case 'LOAD_SURVEY':
+                    try {
+                        const published = await loadPublishedSurvey(
+                            host,
+                            surveyKey,
+                            configToServerConfig(config),
+                            {},
+                        );
+                        let draft: { responseId: string; pageNo: number; data: Record<string, unknown> } | null =
+                            null;
+                        if (!config.restartOnRefresh && !published.state.lockoutReason) {
+                            try {
+                                const d = await fetchDraft(host, surveyKey, published.state.draft?.responseId);
+                                if (d) {
+                                    draft = {
+                                        responseId: d.responseId,
+                                        pageNo: d.pageNo,
+                                        data: extractDraftData(d.payload),
+                                    };
+                                }
+                            } catch {
+                                /* draft is best-effort; fall through with none */
+                            }
+                        }
+                        post({
+                            source: BRIDGE_SOURCE,
+                            type: 'SURVEY_LOADED',
+                            definition: published.definition,
+                            tokens: published.tokens,
+                            extraParams: published.extraParams,
+                            runtimeConfig: published.runtimeConfig,
+                            state: published.state,
+                            draft,
+                        });
+                    } catch (err) {
+                        handleHostError(err);
+                    }
+                    return;
+                case 'SAVE_PROGRESS':
+                    try {
+                        const saved = await saveProgress(host, surveyKey, {
+                            responseId: message.responseId,
+                            pageNo: message.pageNo,
+                            payload: { data: message.data, triggerType: 'updated', locale: message.locale ?? null },
+                        });
+                        post({ source: BRIDGE_SOURCE, type: 'PROGRESS_SAVED', ok: true, responseId: saved.responseId });
+                    } catch (err) {
+                        if (err instanceof SurveyHostError && err.sessionExpired) {
+                            post({ source: BRIDGE_SOURCE, type: 'SESSION_EXPIRED' });
+                            setState({ kind: 'session-expired' });
+                            return;
+                        }
+                        post({ source: BRIDGE_SOURCE, type: 'PROGRESS_SAVED', ok: false });
+                    }
+                    return;
+                case 'SUBMIT_SURVEY':
+                    try {
+                        const result = await submitSurvey(host, surveyKey, message.data, message.enforce);
+                        post({
+                            source: BRIDGE_SOURCE,
+                            type: 'SUBMIT_RESULT',
+                            ok: true,
+                            responseId: result.responseId,
+                            submittedAt: result.submittedAt,
+                        });
+                    } catch (err) {
+                        if (err instanceof SurveyHostError && err.sessionExpired) {
+                            post({ source: BRIDGE_SOURCE, type: 'SESSION_EXPIRED' });
+                            setState({ kind: 'session-expired' });
+                            return;
+                        }
+                        const reason = err instanceof SurveyHostError ? err.reason : undefined;
+                        post({
+                            source: BRIDGE_SOURCE,
+                            type: 'SUBMIT_RESULT',
+                            ok: false,
+                            reason,
+                            message: err instanceof Error ? err.message : 'Submission failed.',
+                        });
+                    }
+                    return;
+                case 'RESIZE':
+                    if (message.height > 0) setHeight(Math.ceil(message.height));
+                    return;
+                case 'REQUEST_REDIRECT':
+                    handleRedirect(message.target, message.external);
+                    return;
+                case 'RUNTIME_ERROR':
+                    setState({ kind: 'error', message: message.message });
+                    return;
+                case 'UNSUPPORTED':
+                    console.warn(`[surveyjs] unsupported feature in WebView runtime: ${message.feature}`);
+                    return;
+                default:
+                    return;
+            }
+
+            function handleHostError(err: unknown): void {
+                if (err instanceof SurveyHostError && err.sessionExpired) {
+                    setState({ kind: 'session-expired' });
+                    return;
+                }
+                setState({
+                    kind: 'error',
+                    message: err instanceof Error ? `Survey not available: ${err.message}` : 'Survey not available.',
+                });
+            }
+        },
+        [host, surveyKey, config, post, handleRedirect],
+    );
+
+    const onMessage = useCallback(
+        (raw: unknown): void => {
+            let parsed: unknown = raw;
+            if (typeof raw === 'string') {
+                try {
+                    parsed = JSON.parse(raw);
+                } catch {
+                    return;
+                }
+            }
+            if (isWebviewToHostMessage(parsed)) {
+                void onIntent(parsed);
+            }
+        },
+        [onIntent],
+    );
+
+    const setPost = useCallback((fn: (json: string) => void): void => {
+        postRef.current = fn;
+    }, []);
+
+    const retry = useCallback((): void => {
+        setState({ kind: 'running' });
+        setHeight(320);
+        setReloadKey((key) => key + 1);
+    }, []);
+
+    if (!surveyKey) {
+        return (
+            <Notice tone="warning" text="The SurveyJS section is missing a selected survey." />
+        );
+    }
+    if (!host) {
+        return (
+            <Notice
+                tone="warning"
+                text="SurveyJS needs a newer SelfHelp mobile app. Please update the app to take this survey."
+            />
+        );
+    }
+    if (state.kind === 'session-expired') {
+        return (
+            <Notice tone="neutral" text="Your session has expired. Please sign in again to continue." />
+        );
+    }
+    if (state.kind === 'error') {
+        return (
+            <View style={{ padding: 12, borderWidth: 1, borderColor: '#fa5252', borderRadius: 6, gap: 8 }}>
+                <Text style={{ color: '#c92a2a' }}>{state.message}</Text>
+                <Pressable
+                    onPress={retry}
+                    accessibilityRole="button"
+                    style={{ alignSelf: 'flex-start', paddingVertical: 6, paddingHorizontal: 12, backgroundColor: '#e9ecef', borderRadius: 6 }}
+                >
+                    <Text style={{ color: '#212529', fontWeight: '600' }}>Retry</Text>
+                </Pressable>
+            </View>
+        );
+    }
+
+    const Transport = loadTransport();
+    return (
+        <View style={{ paddingVertical: 8 }}>
+            <Transport
+                key={reloadKey}
+                html={SURVEYJS_WEBVIEW_HTML}
+                height={height}
+                onMessage={onMessage}
+                setPost={setPost}
+                isAllowedUrl={isAllowedWebViewUrl}
+            />
+        </View>
+    );
+}
+
+function Notice({ tone, text }: { tone: 'warning' | 'neutral'; text: string }): React.ReactElement {
+    const palette =
+        tone === 'warning'
+            ? { border: '#fab005', color: '#856404' }
+            : { border: '#dee2e6', color: '#495057' };
+    return (
+        <View style={{ padding: 12, borderWidth: 1, borderColor: palette.border, borderRadius: 6 }}>
+            <Text style={{ color: palette.color }}>{text}</Text>
+        </View>
+    );
+}
+
+/** Re-exported so the host can show a spinner consistently if it wants. */
+export function SurveyJsLoading(): React.ReactElement {
+    return (
+        <View style={{ paddingVertical: 16, alignItems: 'center' }}>
+            <ActivityIndicator />
+            <Text style={{ marginTop: 8, color: '#495057' }}>Loading survey…</Text>
+        </View>
+    );
+}