@forming/react 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,790 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React, { useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { atPointer, JsonNumber, parseJson, stringifyJson } from '@forming/integrations/lossless-json';
+import { baseType, editorText, Icon, inputMode, MAX_LIST_ITEMS, pickerAccepts, ScalarListEditor, TemporalPicker, } from './editors.js';
+import { markdown } from './markdown.js';
+import { localized } from './format.js';
+export function createController(runtime, dispatch = event => runtime.dispatch(event), uploads) {
+    const listeners = new Set();
+    const editors = new Set();
+    let disposed = false;
+    const initial = runtime.view();
+    let snapshot = {
+        viewJson: initial,
+        view: parseJson(initial),
+        editorErrors: new Set(),
+        error: null,
+        reset: 0,
+    };
+    // A successful dispatch already returns the new view; reuse that text (and
+    // its parsed form) instead of rebuilding, reserializing and reparsing it.
+    function refresh(error = null, viewJson, view) {
+        if (disposed)
+            return;
+        const text = viewJson ?? runtime.view();
+        const parsed = view ?? (text === snapshot.viewJson ? snapshot.view : parseJson(text));
+        snapshot = { ...snapshot, viewJson: text, view: parsed, editorErrors: new Set(editors), error };
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        document: () => runtime.document(),
+        getSnapshot: () => snapshot,
+        subscribe(listener) {
+            if (!disposed)
+                listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        dispose() {
+            disposed = true;
+            listeners.clear();
+            editors.clear();
+        },
+        refresh: () => refresh(),
+        uploadsAvailable: !!uploads,
+        selectFiles(owner, files) {
+            if (disposed)
+                return;
+            if (!uploads) {
+                refresh('Configure an upload host to select files.');
+                return;
+            }
+            try {
+                const result = JSON.parse(uploads.select(owner, files));
+                refresh(result.status === 'error'
+                    ? (result.diagnostic?.message ?? 'The files could not be selected.')
+                    : result.uploadOutcome?.rejected?.length
+                        ? 'Some files exceed the allowed format or limits.'
+                        : null);
+            }
+            catch {
+                refresh('The files could not be selected.');
+            }
+        },
+        retryFile(owner, slot) {
+            if (disposed)
+                return;
+            if (!uploads)
+                return;
+            try {
+                const raw = uploads.retry(owner, slot);
+                const result = raw === null ? null : JSON.parse(raw);
+                refresh(result?.status === 'error' ? (result.diagnostic?.message ?? 'Reselect the file to retry.') : null);
+            }
+            catch {
+                refresh('The file could not be retried.');
+            }
+        },
+        editor(id, invalid) {
+            if (disposed)
+                return;
+            if (editors.has(id) === invalid)
+                return;
+            if (invalid) {
+                editors.add(id);
+                // A pending Submit must not publish the old value behind an invalid buffer.
+                dispatch('{"type":"submit.cancel"}');
+            }
+            else
+                editors.delete(id);
+            refresh();
+        },
+        send(event) {
+            if (disposed)
+                return false;
+            // Never submit the previous committed value while an invalid buffer is visible.
+            const resets = event.type === 'action' && snapshot.view.actions.find(action => action.id === event.id)?.type === 'reset';
+            if (editors.size && event.type === 'action' && !resets) {
+                refresh('Finish or clear the highlighted entries first.');
+                return false;
+            }
+            const result = dispatch(stringifyJson(event));
+            if (result === null) {
+                refresh();
+                return true;
+            } // Provider bridge may queue a reentrant event.
+            const parsed = parseJson(result);
+            if (parsed.status === 'error') {
+                refresh(parsed.diagnostic?.message ?? 'This change could not be applied.');
+                return false;
+            }
+            if (parsed.outcome === 'reset') {
+                editors.clear();
+                snapshot = { ...snapshot, reset: snapshot.reset + 1 };
+            }
+            refresh(null, result, parsed);
+            return true;
+        },
+    };
+}
+const defaultText = {
+    clear: 'Clear',
+    setNull: 'Set to null',
+    create: 'Add details',
+    add: 'Add item',
+    remove: 'Remove',
+    up: 'Move up',
+    down: 'Move down',
+    search: 'Search options',
+    more: 'Load more',
+    retry: 'Retry',
+    waiting: 'Checking…',
+    unavailable: 'This check is unavailable.',
+    choose: 'Choose an option',
+    chooseMany: 'Choose as many as you like',
+    invalid: 'Enter a complete value before continuing.',
+    unsupported: 'This field needs a supported editor.',
+    nullValue: 'Currently null',
+    shownAs: 'Shown in your locale as {value}',
+    reselect: 'Select the unfinished files again, or dismiss them.',
+    dismiss: 'Dismiss unfinished files',
+    uploading: 'Uploading…',
+    verified: 'Verified',
+    uploadFailed: 'This file could not be verified.',
+    uploadNotReady: 'Complete the required upload details first.',
+    issueSingle: '1 answer needs attention.',
+    issueCount: '{count} answers need attention.',
+    issueFirst: 'Go to the first',
+    step: 'Step {current} of {total}',
+    next: 'Continue',
+    back: 'Back',
+    pressEnter: 'Press Enter ↵',
+    counter: '{count} / {max}',
+};
+const additionalText = {
+    trueValue: 'Yes',
+    falseValue: 'No',
+    accept: 'I accept',
+    formUnavailable: 'The form could not be loaded.',
+};
+/** Field drawings by answer pointer and by exact annotation (package@version#export). */
+function fieldDrawings(extensions) {
+    const presenters = extensions?.presentation() ?? [];
+    return {
+        pointers: new Map(presenters.flatMap(p => [...(p.fields ?? new Map())])),
+        annotations: new Map(presenters.flatMap(p => [...(p.annotations ?? new Map())])),
+        decorations: new Map(presenters.flatMap(p => [...(p.decorations ?? new Map())])),
+    };
+}
+/** A ready-made plugin for selectable sections with a heading and body text.
+ * Field keys are answer pointers (e.g. /plan); values stay exact JSON values.
+ * Register it with createExtensions like any other plugin.
+ */
+export function choiceCards({ identity, fields, }) {
+    const entries = new Map(Object.entries(fields).map(([bind, cards]) => [
+        bind,
+        cards.map(({ value, ...presentation }) => ({ value: parseJson(stringifyJson(value)), ...presentation })),
+    ]));
+    return {
+        identity,
+        present: {
+            choice({ field, value }) {
+                const card = entries.get(field.bind ?? '')?.find(card => equal(card.value, value));
+                return card ? { title: card.title, description: card.description } : undefined;
+            },
+        },
+    };
+}
+// The registry already rejects duplicate identities and malformed hooks.
+function rendererPlugins(extensions) {
+    const handlers = (extensions?.presentation() ?? []).flatMap(p => (p.choice ? [p.choice] : []));
+    return (option) => {
+        let result;
+        for (const handler of handlers) {
+            const next = handler(option);
+            if (next === undefined)
+                continue;
+            if (!next ||
+                typeof next !== 'object' ||
+                (next.title !== undefined && typeof next.title !== 'string') ||
+                (next.description !== undefined && typeof next.description !== 'string'))
+                throw new TypeError('Choice presentation must contain plain text title and description.');
+            if (result !== undefined)
+                throw new TypeError('Multiple renderer plugins claim the same option.');
+            result = next;
+        }
+        return result;
+    };
+}
+// Controls whose own keys matter: Enter and letters must keep their native meaning there.
+function typing(target) {
+    if (target.isContentEditable || target.tagName === 'TEXTAREA' || target.tagName === 'SELECT')
+        return true;
+    return target.tagName === 'INPUT' && !['radio', 'checkbox', 'file'].includes(target.type);
+}
+function shown(value) {
+    return value === undefined ? '' : typeof value === 'string' ? value : stringifyJson(value);
+}
+function schemaFor(document, node) {
+    if (node.schemaPath)
+        return (atPointer(document, node.schemaPath) ?? {});
+    let schema = document;
+    for (const segment of (node.bind ?? '').slice(1).split('/'))
+        schema = schema.properties?.[segment.replaceAll('~1', '/').replaceAll('~0', '~')] ?? {};
+    return schema;
+}
+function numberKey(raw) {
+    const [mantissa, exponent = '0'] = raw.toLowerCase().split('e');
+    const negative = mantissa.startsWith('-'), unsigned = negative ? mantissa.slice(1) : mantissa;
+    const [whole, fraction = ''] = unsigned.split('.');
+    let digits = (whole + fraction).replace(/^0+/, '');
+    if (!digits)
+        return '0';
+    const trimmed = digits.replace(/0+$/, '');
+    const power = BigInt(exponent) - BigInt(fraction.length) + BigInt(digits.length - trimmed.length);
+    digits = trimmed;
+    return `${negative ? '-' : ''}${digits}e${power}`;
+}
+function equal(a, b) {
+    return a instanceof JsonNumber && b instanceof JsonNumber
+        ? numberKey(a.raw) === numberKey(b.raw)
+        : stringifyJson(a) === stringifyJson(b);
+}
+export function FormingForm({ controller, text: overrides, className, presentation = 'embedded', detail = 'standard', extensions, }) {
+    const presentChoice = useMemo(() => rendererPlugins(extensions), [extensions]);
+    const drawings = useMemo(() => fieldDrawings(extensions), [extensions]);
+    const snapshot = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    const view = snapshot.view;
+    const document = useMemo(() => parseJson(controller.document()), [controller]);
+    const form = view.form ?? document.form;
+    const text = { ...defaultText, ...additionalText, ...editorText, ...view.localization?.renderer, ...overrides };
+    const instanceId = useId();
+    const formRef = useRef(null);
+    const previousPage = useRef(view.navigation?.currentPage);
+    const focusInside = useRef(false);
+    useEffect(() => {
+        const changed = previousPage.current !== view.navigation?.currentPage;
+        previousPage.current = view.navigation?.currentPage;
+        // Do not steal focus on mount, locale changes or from a host's source editor.
+        if (changed && focusInside.current)
+            formRef.current?.querySelector('[data-forming-page]')?.focus();
+    }, [view.navigation?.currentPage]);
+    const states = new Map([...(view.validation?.fieldStates ?? []), ...(view.validation?.viewStates ?? [])].map(state => [
+        state.nodeId,
+        state,
+    ]));
+    // Page transitions slide with the direction of travel along the runtime's route.
+    const route = view.navigation?.route ?? [];
+    const pageIndex = route.indexOf(view.navigation?.currentPage ?? '');
+    const lastIndex = useRef(pageIndex);
+    const direction = useRef('forward');
+    // The core keeps errors revealed after a successful Next. A page someone has just
+    // arrived at stays quiet until they try to continue or submit from it.
+    const quietPage = useRef(null);
+    if (pageIndex !== lastIndex.current) {
+        direction.current = pageIndex >= 0 && pageIndex < lastIndex.current ? 'back' : 'forward';
+        lastIndex.current = pageIndex;
+        quietPage.current = view.navigation?.currentPage ?? null;
+    }
+    const revealed = view.errorsRevealed && (quietPage.current === null || quietPage.current !== view.navigation?.currentPage);
+    const activate = (id) => {
+        quietPage.current = null;
+        return controller.send({ type: 'action', id });
+    };
+    const context = {
+        presentChoice,
+        drawings,
+        controller,
+        snapshot,
+        view,
+        document,
+        text,
+        instanceId,
+        states,
+        presentation,
+        detail,
+        direction: direction.current,
+        revealed,
+    };
+    if (view.status !== 'ok')
+        return _jsx("div", { role: "alert", children: text.formUnavailable });
+    const pageNodes = (form.children ?? []).filter(node => node.type === 'page');
+    const steps = view.navigation.currentPage && route.length > 1
+        ? {
+            label: text.step
+                .replace('{current}', String(route.indexOf(view.navigation.currentPage) + 1))
+                .replace('{total}', String(route.length)),
+            pages: route.map(id => ({
+                id,
+                title: pageNodes.find(node => node.id === id)?.title ?? id,
+                visited: (view.navigation.history ?? []).includes(id),
+            })),
+        }
+        : null;
+    // Actions declared on the current page (Back/Continue/Send) sit apart from form-level ones.
+    const currentPage = pageNodes.find(node => node.id === view.navigation.currentPage);
+    const actionNodes = (node) => node.type === 'action' ? [node] : (node.children ?? []).flatMap(actionNodes);
+    const pageActionNodes = currentPage ? actionNodes(currentPage) : [];
+    const ownedByPage = new Set(pageActionNodes.map(node => node.id));
+    // Synthesized sequential navigation carries no authored label; use the renderer's text.
+    const implicitLabel = (action) => pageActionNodes.find(node => node.id === action.id)?.implicit
+        ? (text[action.type] ?? action.label)
+        : action.label;
+    // On paged forms the summary covers the questions in front of the respondent, not later pages.
+    const nodeIds = (node) => [node.id, ...(node.children ?? []).flatMap(nodeIds)];
+    const onPage = currentPage ? new Set(nodeIds(currentPage)) : null;
+    const pageIssues = view.validation.issues.filter(issue => !onPage || onPage.has(issue.nodeId));
+    const goToFirstIssue = () => {
+        const fields = new Map(Array.from(formRef.current?.querySelectorAll('[data-forming-node]') ?? []).map(field => [
+            field.dataset.formingNode,
+            field,
+        ]));
+        // A plugin can draw an entire group, so its children may have no DOM of their own.
+        const parents = new Map();
+        const visit = (node) => {
+            for (const child of node.children ?? []) {
+                parents.set(child.id, node.id);
+                visit(child);
+            }
+        };
+        visit(form);
+        for (const issue of pageIssues) {
+            let id = issue.nodeId;
+            while (id && !fields.has(id))
+                id = parents.get(id);
+            const field = id ? fields.get(id) : undefined;
+            if (!field)
+                continue;
+            const controls = Array.from(field.querySelectorAll('input:not([type="hidden"]), select, textarea, button, [tabindex]:not([tabindex="-1"])')).filter(control => !control.matches(':disabled, [aria-disabled="true"]') && !control.closest('[hidden], [inert]'));
+            const target = controls.find(control => control.getAttribute('aria-invalid') === 'true') ?? controls[0] ?? field;
+            target.focus({ preventScroll: true });
+            field.scrollIntoView?.({ block: 'center', inline: 'nearest' });
+            return;
+        }
+    };
+    const pageActions = view.actions.filter(action => ownedByPage.has(action.id));
+    const formActions = view.actions.filter(action => !ownedByPage.has(action.id));
+    // Unfinished editor buffers block every action but Reset.
+    const buffered = (action) => snapshot.editorErrors.size > 0 && action.type !== 'reset';
+    // A blocked Next/Submit/Validate still goes to the core, which reveals what is missing.
+    const reveals = (action) => ['next', 'submit', 'validate'].includes(action.type);
+    const available = (action) => !buffered(action) && (action.enabled || reveals(action));
+    // Enter moves forward: the page's Continue, otherwise Submit.
+    const primary = pageActions.find(action => action.type === 'next' && action.enabled && available(action)) ??
+        pageActions.find(action => action.type === 'next' && available(action)) ??
+        view.actions.find(action => action.type === 'submit' && available(action));
+    function shortcut(event) {
+        if (event.defaultPrevented || event.altKey || event.nativeEvent.isComposing)
+            return;
+        const target = event.target;
+        if (event.key === 'Enter') {
+            if (event.shiftKey || target.tagName === 'BUTTON' || target.tagName === 'A' || target.tagName === 'SELECT')
+                return;
+            if (target.tagName === 'INPUT' && ['file', 'search'].includes(target.type))
+                return;
+            // Textareas keep Enter for new lines; Cmd/Ctrl+Enter continues.
+            if (target.tagName === 'TEXTAREA' && !(event.metaKey || event.ctrlKey))
+                return;
+            event.preventDefault();
+            if (primary)
+                activate(primary.id);
+            return;
+        }
+        // A-H pick a choice card: in the focused question, or the page's only card question.
+        // Only focused presentation shows the letters, so only it answers to them.
+        if (presentation !== 'focused')
+            return;
+        if (event.ctrlKey || event.metaKey || !/^[a-h]$/i.test(event.key) || typing(target))
+            return;
+        const groups = formRef.current?.querySelectorAll('[data-forming-choices]') ?? [];
+        const group = target.closest('[data-forming-choices]') ?? (groups.length === 1 ? groups[0] : null);
+        const choice = group?.querySelector(`input[aria-keyshortcuts="${event.key.toUpperCase()}"]`);
+        if (!choice || choice.disabled)
+            return;
+        event.preventDefault();
+        choice.focus();
+        choice.click();
+    }
+    return (_jsxs("form", { ref: formRef, className: ['forming-form', className].filter(Boolean).join(' '), "data-forming-root": "", "data-presentation": presentation, onFocusCapture: () => {
+            focusInside.current = true;
+        }, onBlurCapture: event => {
+            if (event.relatedTarget && !event.currentTarget.contains(event.relatedTarget))
+                focusInside.current = false;
+        }, noValidate: true, lang: view.localization?.locale, dir: view.localization?.direction, onKeyDown: shortcut, onSubmit: event => {
+            event.preventDefault();
+            const submit = view.actions.find(action => action.type === 'submit' && action.enabled);
+            if (submit)
+                activate(submit.id);
+        }, children: [_jsxs("header", { "data-forming-header": "", children: [_jsx("h1", { children: form.title }), form.description && _jsx("p", { children: form.description })] }), steps && (
+            // Pages are steps: the runtime's route lists the pages this respondent will visit.
+            _jsxs("nav", { "data-forming-steps": "", "aria-label": steps.label, children: [_jsx("span", { "aria-live": "polite", children: steps.label }), _jsx("ol", { children: steps.pages.map((page, index) => (_jsxs("li", { "aria-current": page.id === view.navigation.currentPage ? 'step' : undefined, "data-visited": page.visited ? '' : undefined, children: [_jsx("span", { "data-forming-step-number": "", "aria-hidden": "true", children: index + 1 }), _jsx("span", { children: page.title })] }, page.id))) })] })), snapshot.error && _jsx("div", { role: "alert", children: snapshot.error }), form.children?.map(node => (_jsx(Tree, { node: node, context: context }, node.id))), view.submissionIntent?.state === 'waiting' && _jsx("p", { role: "status", children: text.waiting }), revealed && pageIssues.length > 0 && (
+            // Each field already shows its own message; this summary follows the
+            // fields and only offers a jump to the first one still needing attention.
+            _jsxs("p", { role: "alert", "data-forming-issues": "", children: [(new Set(pageIssues.map(issue => issue.nodeId)).size === 1 ? text.issueSingle : text.issueCount).replace('{count}', String(new Set(pageIssues.map(issue => issue.nodeId)).size)), ' ', _jsx("button", { type: "button", onClick: goToFirstIssue, children: text.issueFirst })] })), [pageActions, formActions].map((group, index) => group.length > 0 && (_jsx("div", { "data-forming-actions": index === 0 ? 'page' : 'form', children: group.map(action => (_jsxs(React.Fragment, { children: [_jsx("button", { type: "button", "data-action": action.type, "aria-keyshortcuts": action === primary ? 'Enter' : undefined, disabled: !available(action), "aria-disabled": !action.enabled && available(action) ? true : undefined, onClick: () => activate(action.id), children: implicitLabel(action) }), action === primary && presentation === 'focused' && (_jsx("span", { "data-forming-hint": "", "aria-hidden": "true", children: text.pressEnter }))] }, action.id))) }, index)))] }));
+}
+function Decorated({ node, context, children }) {
+    const decorations = (node.annotations ?? []).flatMap(annotation => {
+        const draw = context.drawings.decorations.get(`${annotation.package}#${annotation.export}`);
+        return draw ? [{ annotation, draw }] : [];
+    });
+    if (!decorations.length)
+        return _jsx(_Fragment, { children: children });
+    const content = (placement) => decorations.map(({ annotation, draw }) => (_jsx(React.Fragment, { children: draw({
+            node: { id: node.id, type: node.type, bind: node.bind, annotations: node.annotations },
+            annotation,
+            placement,
+        }) }, `${annotation.package}#${annotation.export}`)));
+    return (_jsxs("div", { "data-forming-decoration": "", style: { minWidth: 0 }, children: [content('before'), children, content('after')] }));
+}
+function Tree({ node, context }) {
+    if (node.type === 'action' || (node.type === 'page' && node.id !== context.view.navigation.currentPage))
+        return null;
+    if (node.type === 'field') {
+        if (!context.states.get(node.id)?.visible)
+            return null;
+        return (_jsx(Decorated, { node: node, context: context, children: _jsx(Field, { node: node, context: context }) }));
+    }
+    if (context.states.get(node.id)?.visible === false)
+        return null;
+    if (node.type === 'display')
+        return (_jsx(Decorated, { node: node, context: context, children: _jsxs("section", { "data-display": node.id, children: [(context.view.texts?.[node.id]?.title ?? node.title) && (_jsx("h2", { children: context.view.texts?.[node.id]?.title ?? node.title })), markdown(context.view.texts?.[node.id]?.content ?? node.content ?? '')] }) }));
+    const columns = node.type === 'grid'
+        ? Number(node.columns?.raw ?? '1')
+        : node.type === 'columns'
+            ? Math.max(1, node.children?.length ?? 1)
+            : undefined;
+    if (node.type === 'page')
+        return (_jsxs("section", { tabIndex: -1, "data-layout": "page", "data-forming-page": node.id, "data-direction": context.direction, "aria-labelledby": node.title ? context.instanceId + node.id + ':title' : undefined, children: [node.title && _jsx("h2", { id: context.instanceId + node.id + ':title', children: node.title }), node.description && _jsx("p", { children: node.description }), node.children?.map(child => (_jsx(Tree, { node: child, context: context }, child.id)))] }));
+    return (_jsxs("section", { "data-layout": node.type, style: columns
+            ? {
+                display: 'grid',
+                gridTemplateColumns: `repeat(auto-fit, minmax(min(100%, max(14rem, calc((100% - ${columns - 1}rem) / ${columns}))), 1fr))`,
+                gap: '1rem',
+                minWidth: 0,
+            }
+            : undefined, children: [node.title && _jsx("h2", { children: node.title }), node.children?.map(child => (_jsx(Tree, { node: child, context: context }, child.id)))] }));
+}
+function Field({ node, context }) {
+    const { controller, snapshot, view, document, text, instanceId } = context;
+    const state = context.states.get(node.id);
+    const schema = schemaFor(document, node);
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    const type = types.find(type => type !== 'null');
+    const value = atPointer(view.data, node.bind ?? '');
+    const stored = value === undefined ? 'missing' : stringifyJson(value);
+    const committed = value === null ? '' : shown(value);
+    const [buffer, setBuffer] = useState(committed);
+    const [localError, setLocalError] = useState(false);
+    const [editorReset, setEditorReset] = useState(0);
+    const [dragging, setDragging] = useState(false);
+    const composing = useRef(false);
+    useEffect(() => {
+        composing.current = false;
+        setBuffer(committed);
+        setLocalError(false);
+        controller.editor(node.id, false);
+    }, [stored, committed, snapshot.reset, controller, node.id]);
+    useEffect(() => () => controller.editor(node.id, false), [controller, node.id]);
+    useEffect(() => {
+        if (!state?.visible || !state.enabled || state.readonly) {
+            composing.current = false;
+            setBuffer(committed);
+            setLocalError(false);
+            controller.editor(node.id, false);
+        }
+    }, [state?.visible, state?.enabled, state?.readonly, committed, controller, node.id]);
+    if (!state?.visible || node.control === 'hidden')
+        return null;
+    const disabled = !state.enabled || state.readonly;
+    const id = instanceId + node.id;
+    // A missing required answer reports both a schema and a completeness issue;
+    // show the completeness wording once rather than both.
+    const own = view.validation.issues.filter(issue => issue.nodeId === node.id);
+    const issues = context.revealed
+        ? own
+            .filter(issue => !(issue.code === 'FORMING_REQUIRED' && own.some(other => other.code === 'FORMING_UNANSWERED')))
+            .filter((issue, index, all) => all.findIndex(other => other.message === issue.message) === index)
+        : [];
+    const slots = view.providerState?.slots.filter(slot => node.providers?.some(site => site.id === slot.site)) ?? [];
+    const help = node.description ?? schema.description;
+    const bad = localError || issues.length > 0;
+    const common = {
+        id,
+        disabled,
+        'aria-required': state.required,
+        'aria-invalid': bad,
+        'aria-describedby': `${id}:help ${id}:errors`,
+        placeholder: node.placeholder,
+    };
+    const composition = {
+        onCompositionStart: () => {
+            composing.current = true;
+            controller.editor(node.id, true);
+        },
+        onCompositionEnd: (event) => {
+            composing.current = false;
+            input(event.currentTarget.value);
+        },
+    };
+    function invalid(value) {
+        setLocalError(value);
+        controller.editor(node.id, value);
+    }
+    function commit(next) {
+        const ok = controller.send({ type: 'edit', id: node.id, value: next });
+        invalid(!ok);
+        return ok;
+    }
+    function input(raw) {
+        setBuffer(raw);
+        if (composing.current)
+            return;
+        if (type === 'number' || type === 'integer' || type === 'array') {
+            if (!raw.length) {
+                controller.send({ type: 'clear', id: node.id });
+                setLocalError(false);
+                controller.editor(node.id, false);
+                return;
+            }
+            try {
+                const parsed = type === 'array' ? parseJson(raw) : new JsonNumber(raw);
+                if (type === 'array' && !Array.isArray(parsed))
+                    throw new TypeError();
+                commit(parsed);
+            }
+            catch {
+                setLocalError(true);
+                controller.editor(node.id, true);
+            }
+        }
+        else
+            commit(raw);
+    }
+    // A plugin may draw this field, by pointer or through an annotation the form
+    // wrote on it; the core still checks every edit.
+    const annotated = (node.annotations ?? []).flatMap(annotation => {
+        const by = context.drawings.annotations.get(`${annotation.package}#${annotation.export}`);
+        return by ? [{ annotation, by }] : [];
+    });
+    const byPointer = node.bind ? context.drawings.pointers.get(node.bind) : undefined;
+    if (annotated.length + (byPointer ? 1 : 0) > 1)
+        throw new TypeError(`Two plugins draw ${node.bind ?? node.id}.`);
+    const first = annotated.at(0);
+    const draw = byPointer ?? first?.by;
+    const uploadOwner = node.file ? view.uploadState?.fields.find(f => !f.retired && f.node === node.id) : undefined;
+    // Part of an object goes to whichever placement of that part is visible and
+    // editable now: one answer can be drawn differently depending on others.
+    function partId(pointer) {
+        if (!pointer)
+            return node.id;
+        const target = (node.bind ?? '') + pointer;
+        const current = new Map(controller.getSnapshot().view.validation.fieldStates.map(s => [s.nodeId, s]));
+        const found = [];
+        (function walk(parent) {
+            for (const child of parent.children ?? []) {
+                if (child.bind === target)
+                    found.push(child);
+                walk(child);
+            }
+        })(node);
+        return found.find(child => {
+            const now = current.get(child.id);
+            return now?.visible && now.enabled && !now.readonly;
+        })?.id;
+    }
+    const drawing = draw && {
+        field: { id: node.id, bind: node.bind ?? '', title: node.title, description: help, type, file: !!node.file },
+        choices: node.options?.map(option => ({ ...option, label: option.label ?? shown(option.value) })) ??
+            (schema.items?.enum ?? schema.enum)?.map(value => ({ value, label: shown(value) })),
+        children: (node.children ?? []).flatMap(child => {
+            const childState = context.states.get(child.id);
+            if (child.type !== 'field' || !child.bind || !childState?.visible)
+                return [];
+            const childSchema = schemaFor(document, child);
+            return [
+                {
+                    pointer: child.bind.slice((node.bind ?? '').length),
+                    title: child.title ?? child.bind,
+                    value: atPointer(view.data, child.bind),
+                    choices: child.options?.map(option => ({ ...option, label: option.label ?? shown(option.value) })) ??
+                        childSchema.enum?.map(value => ({ value, label: shown(value) })) ??
+                        [],
+                    disabled: disabled || !childState.enabled,
+                    readonly: state.readonly || childState.readonly,
+                    required: childState.required,
+                    invalid: view.validation.issues.some(issue => issue.nodeId === child.id),
+                },
+            ];
+        }),
+        ...(first && !byPointer ? { annotation: first.annotation } : {}),
+        value,
+        set(next, pointer = '') {
+            if (!pointer)
+                return commit(next);
+            const target = partId(pointer);
+            return target !== undefined && controller.send({ type: 'edit', id: target, value: next });
+        },
+        clear(pointer = '') {
+            const target = partId(pointer);
+            return target !== undefined && controller.send({ type: 'clear', id: target });
+        },
+        selectFiles(files) {
+            if (uploadOwner && files.length)
+                controller.selectFiles(uploadOwner.owner, files);
+        },
+        filesReady: !!uploadOwner?.ready && controller.uploadsAvailable,
+        disabled,
+        readonly: state.readonly,
+        required: state.required,
+        invalid: bad,
+        inputId: id,
+        describedBy: `${id}:help ${id}:errors`,
+    };
+    // File fields: the drawing replaces only the picker; upload status stays below it.
+    const drawnFile = node.file && drawing && draw && (_jsx("div", { "data-forming-plugin": "", children: draw(drawing) }));
+    const optionsSite = node.providers?.find(site => site.kind === 'options');
+    const multi = node.control === 'multichoice' || (type === 'array' && !!schema.items?.enum);
+    const choices = node.options
+        ? [...node.options]
+        : ((multi ? schema.items?.enum : schema.enum)?.map(value => ({ value, label: shown(value) })) ?? []);
+    if (optionsSite)
+        for (const slot of slots.filter(s => s.operation.startsWith('options.')))
+            for (const option of slot.result?.items ?? [])
+                if (!choices.some(other => equal(other.value, option.value)))
+                    choices.push(option);
+    const selected = value === undefined || value === null ? [] : multi && Array.isArray(value) ? value : [value];
+    for (const saved of selected)
+        if ((node.options || optionsSite || schema.enum || multi) && !choices.some(option => equal(option.value, saved)))
+            choices.push({ value: saved, label: shown(saved), disabled: true });
+    const tokens = selected.map(selected => String(choices.findIndex(option => equal(option.value, selected))));
+    const choice = !!node.options || !!optionsSite || !!schema.enum || multi;
+    // Consent (a Boolean that must be true) is one box to tick, not a yes/no question.
+    const consent = type === 'boolean' && !choice && schema.const === true;
+    const cardOptions = consent
+        ? [{ value: true, label: text.accept }]
+        : type === 'boolean' && !choice
+            ? [
+                { value: true, label: text.trueValue },
+                { value: false, label: text.falseValue },
+            ]
+            : choices;
+    // Small local choices are native radios/checkboxes: keyboard-operable cards in
+    // focused mode, a compact list in embedded mode (a multi-select list box hides
+    // that several answers are allowed; a dropdown hides a handful of options).
+    // Remote/large lists retain search and select behavior; never auto-advance.
+    const focused = context.presentation === 'focused';
+    const presentations = cardOptions.map(option => context.presentChoice({
+        field: { id: node.id, bind: node.bind },
+        value: option.value,
+        label: option.label ?? shown(option.value),
+    }));
+    const richChoices = presentations.some(presentation => presentation !== undefined);
+    const cards = !optionsSite &&
+        !node.structure &&
+        !node.file &&
+        (choice || type === 'boolean') &&
+        cardOptions.length > 0 &&
+        (richChoices || cardOptions.length <= (focused || multi ? 8 : 5));
+    const scalarList = type === 'array' &&
+        !choice &&
+        !node.structure &&
+        (!Array.isArray(value) || value.length <= MAX_LIST_ITEMS) &&
+        ['string', 'integer', 'number', 'boolean'].includes(baseType(schema.items) ?? '');
+    const temporal = type === 'string' &&
+        ['date', 'forming-local-time', 'date-time'].includes(schema.format ?? '') &&
+        (!node.control || ['date', 'time', 'datetime'].includes(node.control));
+    const exact = context.detail === 'exact';
+    // Respondents edit dates and times with the pickers alone, unless saved text
+    // is something the pickers cannot show (then the portable text stays visible).
+    const standaloneTemporal = temporal && !exact && !localError && (!committed || pickerAccepts(committed, schema.format ?? ''));
+    // Locale rendering of the committed value; the exact text stays editable as is.
+    const localeText = !node.structure && !node.file && !localError && buffer === committed
+        ? localized(value, schema, view.localization?.locale ?? (typeof navigator === 'undefined' ? undefined : navigator.language))
+        : null;
+    // Outside exact mode, skip echoes that repeat what the control already shows.
+    const formatted = localeText && (exact || (localeText !== committed && !(standaloneTemporal && schema.format !== 'date-time')))
+        ? localeText
+        : null;
+    const maxLength = type === 'string' && !temporal && !choice && schema.maxLength !== undefined
+        ? Number(schema.maxLength instanceof JsonNumber ? schema.maxLength.raw : schema.maxLength)
+        : undefined;
+    const length = [...buffer].length;
+    // Long answers always show their budget; short ones once they approach it.
+    const counter = maxLength !== undefined && Number.isFinite(maxLength) && (node.control === 'textarea' || length >= maxLength * 0.8)
+        ? text.counter.replace('{count}', String(length)).replace('{max}', String(maxLength))
+        : null;
+    const resetKey = `${snapshot.reset}:${editorReset}`;
+    let editor;
+    // Plain single-control editors carry their Clear button inside the control
+    // (hosts style it as a trailing ×); composite editors keep it below.
+    const inline = !draw &&
+        !node.structure &&
+        !node.file &&
+        !scalarList &&
+        !cards &&
+        !temporal &&
+        !(choice && (optionsSite || multi)) &&
+        type !== undefined;
+    if (node.file) {
+        const owner = uploadOwner;
+        editor = (_jsxs(_Fragment, { children: [drawnFile || (_jsx("input", { ...common, type: "file", "data-dragging": dragging ? '' : undefined, onDragEnter: () => setDragging(true), onDragLeave: () => setDragging(false), onDrop: () => setDragging(false), multiple: node.file.multiple, accept: node.file.accept.join(','), disabled: disabled || !owner?.ready || !controller.uploadsAvailable, onChange: event => {
+                        const files = Array.from(event.currentTarget.files ?? []);
+                        event.currentTarget.value = '';
+                        if (owner && files.length)
+                            controller.selectFiles(owner.owner, files);
+                    } })), !owner?.ready && _jsx("p", { role: "status", children: text.uploadNotReady }), !controller.uploadsAvailable && _jsx("p", { role: "status", children: text.unsupported }), owner && Number(owner.reselect.raw) > 0 && (_jsxs("p", { children: [text.reselect, ' ', _jsx("button", { type: "button", "data-forming-tool": "", disabled: disabled, onClick: () => controller.send({ type: 'upload', owner: owner.owner, event: { type: 'reselect.dismiss' } }), children: text.dismiss })] })), _jsx("ul", { "data-forming-files": "", children: owner?.engine.slots
+                        .filter(s => s.state !== 'cancelled')
+                        .map(slot => (_jsxs("li", { "data-state": slot.state, children: [_jsx("span", { "data-forming-file-name": "", children: slot.file.name }), ' ', _jsx("span", { role: "status", "data-forming-badge": slot.state, children: slot.state === 'complete'
+                                    ? text.verified
+                                    : slot.state === 'failed'
+                                        ? text.uploadFailed
+                                        : slot.state === 'uploading'
+                                            ? text.uploading
+                                            : text.waiting }), ' ', _jsx("button", { type: "button", "data-forming-tool": "", disabled: disabled, onClick: () => controller.send({
+                                    type: 'upload',
+                                    owner: owner.owner,
+                                    event: { type: slot.committed ? 'remove' : 'cancel', slot: slot.id },
+                                }), children: text.remove }), slot.state === 'failed' && slot.error?.retryable && (_jsx("button", { type: "button", "data-forming-tool": "", disabled: disabled || !controller.uploadsAvailable, onClick: () => controller.retryFile(owner.owner, slot.id), children: text.retry }))] }, slot.id))) })] }));
+    }
+    else if (node.structure)
+        editor = (_jsxs(_Fragment, { children: [node.structure === 'object' && (value === undefined || value === null) ? (_jsxs("button", { type: "button", "data-forming-add": "", disabled: disabled, onClick: () => controller.send({ type: 'object.create', id: node.id }), children: [_jsx(Icon, { name: "plus" }), text.create] })) : (node.children?.map((child, index) => (_jsxs("div", { "data-forming-item": node.structure === 'repeat' ? '' : undefined, children: [node.structure === 'repeat' && (_jsxs("div", { "data-forming-item-header": "", children: [_jsxs("span", { "data-forming-item-title": "", children: [text.item, " ", index + 1] }), _jsxs("div", { "data-forming-item-tools": "", children: [_jsxs("button", { type: "button", disabled: disabled || index === 0, onClick: () => controller.send({ type: 'repeat.move', id: node.id, item: child.itemId, index: index - 1 }), children: [_jsx(Icon, { name: "up" }), _jsx("span", { children: text.up })] }), _jsxs("button", { type: "button", disabled: disabled || index === (node.children?.length ?? 0) - 1, onClick: () => controller.send({ type: 'repeat.move', id: node.id, item: child.itemId, index: index + 1 }), children: [_jsx(Icon, { name: "down" }), _jsx("span", { children: text.down })] }), _jsxs("button", { type: "button", "data-danger": "", disabled: disabled, onClick: () => controller.send({ type: 'repeat.remove', id: node.id, item: child.itemId }), children: [_jsx(Icon, { name: "trash" }), _jsx("span", { children: text.remove })] })] })] })), _jsx(Tree, { node: child, context: context })] }, child.id)))), node.structure === 'object' && value !== undefined && value !== null && !state.required && (_jsx("button", { type: "button", "data-forming-tool": "", disabled: disabled, "aria-label": `${text.remove} ${node.title ?? ''}`.trim(), onClick: () => controller.send({ type: 'clear', id: node.id }), children: text.remove })), node.structure === 'repeat' && (_jsxs("button", { type: "button", "data-forming-add": "", disabled: disabled, onClick: () => controller.send({ type: 'repeat.insert', id: node.id, index: node.children?.length ?? 0 }), children: [_jsx(Icon, { name: "plus" }), text.add] }))] }));
+    else if (cards)
+        editor = (_jsxs(_Fragment, { children: [multi && _jsx("p", { "data-forming-choice-hint": "", children: text.chooseMany }), _jsx("div", { "data-forming-choices": multi ? 'multiple' : 'single', "data-rich-choices": richChoices ? '' : undefined, children: cardOptions.map((option, index) => {
+                        const checked = selected.some(saved => equal(saved, option.value));
+                        const key = index < 8 ? String.fromCharCode(65 + index) : undefined;
+                        const presentation = presentations[index];
+                        return (_jsxs("label", { "data-forming-choice": "", "data-rich-choice": presentation ? '' : undefined, "data-selected": checked ? '' : undefined, children: [_jsx("input", { type: multi || consent ? 'checkbox' : 'radio', name: id, id: `${id}:choice:${index}`, value: shown(option.value), checked: checked, disabled: disabled || option.disabled || option.status === 'missing', "aria-keyshortcuts": focused ? key : undefined, "aria-required": !multi && state.required, "aria-invalid": bad, "aria-labelledby": presentation ? `${id}:choice:${index}:title` : undefined, "aria-describedby": `${id}:help ${id}:errors${presentation?.description ? ` ${id}:choice:${index}:description` : ''}`, onChange: () => 
+                                    // Unticking consent leaves it unanswered, so its "please accept" check applies.
+                                    consent && checked
+                                        ? controller.send({ type: 'clear', id: node.id })
+                                        : commit(multi
+                                            ? checked
+                                                ? selected.filter(saved => !equal(saved, option.value))
+                                                : [...selected, option.value]
+                                            : option.value) }), focused && key && (_jsx("kbd", { "data-forming-key": "", "aria-hidden": "true", children: key })), _jsx("span", { "data-forming-choice-content": "", children: presentation ? (_jsxs(_Fragment, { children: [_jsx("strong", { id: `${id}:choice:${index}:title`, children: presentation.title ?? option.label ?? shown(option.value) }), presentation.description && (_jsx("span", { "data-forming-choice-description": "", id: `${id}:choice:${index}:description`, children: presentation.description }))] })) : ((option.label ?? shown(option.value))) }), focused && checked && _jsx(Icon, { name: "check" })] }, index));
+                    }) })] }));
+    else if (choice)
+        editor = (_jsxs(_Fragment, { children: [optionsSite && (_jsxs("label", { "data-forming-search": "", children: [text.search, _jsx("input", { type: "search", disabled: disabled, onChange: event => controller.send({ type: 'provider.search', site: optionsSite.id, query: event.target.value }) })] })), _jsxs("select", { ...common, multiple: multi, value: multi ? tokens : (tokens[0] ?? ''), onChange: event => {
+                        if (!multi && event.target.value === '') {
+                            controller.send({ type: 'clear', id: node.id });
+                            return;
+                        }
+                        const values = Array.from(event.target.selectedOptions).map(option => choices[Number(option.value)].value);
+                        commit(multi ? values : values[0]);
+                    }, children: [!multi && _jsx("option", { value: "", children: text.choose }), choices.map((option, index) => (_jsx("option", { value: String(index), disabled: option.disabled || option.status === 'missing', children: option.label ?? shown(option.value) }, index)))] }), optionsSite && slots.some(slot => slot.operation === 'options.search' && slot.result?.nextCursor) && (_jsx("button", { type: "button", "data-forming-tool": "", disabled: disabled, onClick: () => controller.send({ type: 'provider.more', site: optionsSite.id }), children: text.more }))] }));
+    else if (scalarList)
+        editor = (_jsx(ScalarListEditor, { id: id, value: value, schema: schema.items, disabled: disabled, reset: resetKey, text: text, describedBy: common['aria-describedby'], commit: commit, invalid: invalid, exact: exact }));
+    else if (type === 'boolean')
+        editor = (_jsxs("select", { ...common, value: value === true ? 'true' : value === false ? 'false' : '', onChange: event => event.target.value ? commit(event.target.value === 'true') : controller.send({ type: 'clear', id: node.id }), children: [_jsx("option", { value: "", children: text.choose }), _jsx("option", { value: "true", children: text.trueValue }), _jsx("option", { value: "false", children: text.falseValue })] }));
+    else if (type === 'string' || type === 'number' || type === 'integer' || type === 'array')
+        editor = (_jsxs(_Fragment, { children: [standaloneTemporal ? null : node.control === 'textarea' || type === 'array' ? (_jsx("textarea", { ...common, ...composition, value: buffer, onChange: event => input(event.target.value) })) : (_jsx("input", { ...common, ...composition, type: node.control === 'password' ? 'password' : 'text', inputMode: inputMode(schema), value: buffer, onChange: event => input(event.target.value) })), temporal && (_jsx(TemporalPicker, { id: id, title: node.title ?? '', value: buffer, format: schema.format, disabled: disabled, reset: resetKey, text: text, describedBy: common['aria-describedby'], change: input, incomplete: () => invalid(true), standalone: standaloneTemporal }))] }));
+    else
+        editor = _jsx("p", { role: "alert", children: text.unsupported });
+    // Other fields: the drawing receives the built-in editor and decides where it
+    // goes, e.g. a search box above the usual address fields.
+    if (drawing && draw && !node.file)
+        editor = _jsx("div", { "data-forming-plugin": "", children: draw({ ...drawing, standard: editor }) });
+    const clearButton = !node.structure && !node.file && !draw && (_jsx("button", { type: "button", "data-forming-clear": "", "data-forming-tool": inline ? undefined : '', "aria-label": `${text.clear} ${node.title ?? ''}`.trim(), title: text.clear, disabled: disabled || (value === undefined && !buffer && !localError), onClick: () => {
+            if (controller.send({ type: 'clear', id: node.id })) {
+                setBuffer('');
+                invalid(false);
+                setEditorReset(value => value + 1);
+            }
+        }, children: inline ? _jsx(Icon, { name: "close" }) : text.clear }));
+    return (_jsxs("fieldset", { style: { minWidth: 0 }, "data-forming-field": "", "data-forming-node": node.id, "data-structure": node.structure, "data-invalid": bad ? '' : undefined, "data-readonly": state.readonly ? '' : undefined, id: node.structure || scalarList || cards ? id : undefined, tabIndex: -1, "aria-invalid": scalarList || cards ? bad : undefined, children: [node.structure || scalarList || cards ? (_jsxs("legend", { children: [node.title, state.required && (_jsx("span", { "data-forming-required": "", "aria-hidden": "true", children: ' *' }))] })) : (_jsxs("label", { htmlFor: standaloneTemporal ? `${id}:${schema.format === 'forming-local-time' ? 'time' : 'date'}` : id, children: [node.title, state.required && (_jsx("span", { "data-forming-required": "", "aria-hidden": "true", children: ' *' }))] })), inline ? (_jsxs("div", { "data-forming-control": "", children: [editor, clearButton] })) : (editor), _jsxs("p", { "data-forming-help": "", id: `${id}:help`, children: [help, exact && value === null ? ` ${text.nullValue}` : '', formatted && (_jsxs(_Fragment, { children: [help || (exact && value === null) ? ' ' : '', _jsx("span", { "data-forming-formatted": "", children: text.shownAs.replace('{value}', formatted) })] })), counter && (_jsx("span", { "data-forming-counter": "", "data-over": maxLength !== undefined && length > maxLength ? '' : undefined, children: counter }))] }), _jsxs("div", { "data-forming-errors": "", id: `${id}:errors`, "aria-live": "polite", children: [localError && _jsx("p", { children: text.invalid }), issues.map((issue, i) => (_jsx("p", { children: issue.message }, i)))] }), !inline && clearButton, exact && types.includes('null') && !node.structure && !node.file && (_jsx("button", { type: "button", "data-forming-tool": "", disabled: disabled, onClick: () => {
+                    if (commit(null))
+                        setEditorReset(value => value + 1);
+                }, children: text.setNull })), slots.map(slot => (_jsxs("div", { "data-forming-provider": slot.state, "aria-live": "polite", children: [['pending', 'scheduled'].includes(slot.state) && _jsx("span", { children: text.waiting }), slot.state === 'invalid' && _jsx("span", { children: slot.message }), slot.state === 'failed' && (_jsxs(_Fragment, { children: [_jsx("span", { children: slot.errorMessage ?? text.unavailable }), slot.error?.retryable && (_jsx("button", { type: "button", "data-forming-tool": "", disabled: disabled, onClick: () => controller.send({ type: 'provider.retry', site: slot.site, operation: slot.operation }), children: text.retry }))] }))] }, slot.site + slot.operation)))] }));
+}