@fieldia/viewer 0.9.2 → 0.11.0

package/src/lib/viewer.mjs

@@ -1,8 +1,14 @@
-import { createForm, checkPage, translatePage, wideColumns, MESSAGES, } from '@fieldia/core';
+import { createForm, checkPage, isRightToLeft, localizePage, translatePage, wideColumns, MESSAGES, } from '@fieldia/core';
 import { browserPreferences, createWidget, drawIcon, installStyles, WIDGET_LABELS } from '@fieldia/widgets';
-import { pageDialogs } from './related.mjs';
+import { findPage, pageDialogs } from './related.mjs';
 import { listView } from './list.mjs';
-import { VIEWER_LABELS } from './labels.mjs';
+import { applyLook } from './look.mjs';
+import { labelPlace, planSection } from './place.mjs';
+import { setAttr, setHidden, setText } from './dom.mjs';
+import { openPage } from './open.mjs';
+import { sayer } from './say.mjs';
+import { ownLocale, VIEWER_LABELS } from './labels.mjs';
+import { keepTabIn } from './focus-trap.mjs';
 export { VIEWER_LABELS, DEFAULT_LABELS } from './labels.mjs';
 let mounts = 0;
 /**
@@ -17,19 +23,44 @@ export function mountViewer(host, options) {
     if (!checked.ok) {
         throw new Error(`This page cannot be shown:\n${checked.issues.map((i) => `  ${i.path}: ${i.message}`).join('\n')}`);
     }
-    const page = options.translate ? translatePage(checked.page, options.translate) : checked.page;
-    const locale = options.locale ?? 'en';
+    // The page's own words in its language first; the app's translator over what is left.
+    const tag = options.locale ?? checked.page.language;
+    const localized = tag ? localizePage(checked.page, tag) : checked.page;
+    const page = options.translate ? translatePage(localized, options.translate) : localized;
+    /** Another page as this one is shown: in its language, through the app's translator. */
+    const shownAs = (other) => {
+        const own = tag ? localizePage(other, tag) : other;
+        return options.translate ? translatePage(own, options.translate) : own;
+    };
+    const locale = ownLocale(tag);
     const preferences = options.preferences ?? browserPreferences();
     const dialogs = pageDialogs(options);
     const ownsForm = !options.form;
-    const form = options.form ?? createForm({ ...options, page, messages: options.messages ?? MESSAGES[locale] });
     const labels = { ...VIEWER_LABELS[locale], ...options.labels };
+    /**
+     * What the page's steps ask of the screen: a page opened, words said, a
+     * question asked, a tab shown — the viewer's own, under the app's. A form
+     * made elsewhere (`form`) keeps the host it was made with.
+     */
+    const actionHost = {
+        open: (request) => openPage({ options, place: host, root, title: (other) => shownAs(other).title || other.id, back: labels.back, missing: (id) => fill(labels.pageMissing, { page: id }) }, request),
+        say: (message, tone) => say(message, tone),
+        ask: (message) => confirm(message),
+        show: (target) => {
+            const show = tabs.get(target);
+            if (!show?.())
+                throw new Error(`No tab "${target}" can be shown here`);
+        },
+        ...options.host,
+    };
+    const form = options.form ?? createForm({ ...options, page, host: actionHost, messages: options.messages ?? MESSAGES[locale] });
     const widgetLabels = WIDGET_LABELS[locale];
-    const dir = options.dir ?? (locale === 'ar' ? 'rtl' : undefined);
+    const dir = options.dir ?? (tag && isRightToLeft(tag) ? 'rtl' : undefined);
     const prefix = `fd${++mounts}`;
     const updaters = [];
     const cleanups = [];
-    const uid = (id) => `${prefix}-${id.replace(/[^A-Za-z0-9_-]/g, '_')}`;
+    const ownUid = (id) => `${prefix}-${id.replace(/[^A-Za-z0-9_-]/g, '_')}`;
+    const uid = ownUid;
     const fill = (template, values) => template.replace(/\{(\w+)\}/g, (_, key) => String(values[key] ?? ''));
     installStyles(doc);
     function el(tag, attrs = {}, ...children) {
@@ -40,217 +71,434 @@ export function mountViewer(host, options) {
         node.append(...children);
         return node;
     }
-    /** Words with the icon a page names before them, when there is such an icon. */
+    /**
+     * Words with the icon a page names before them, when there is such an icon.
+     * The words sit in a <bdi>: left as written on a page of the other direction,
+     * they still run their own way, the icon still before them.
+     */
     function withIcon(name, text) {
         const icon = drawIcon(doc, name, options.icons);
-        return icon ? [icon, text] : [text];
+        const words = el('bdi', {}, text);
+        return icon ? [icon, words] : [words];
     }
-    const root = el('form', { class: 'fd-form', novalidate: '', 'data-fd-skin': options.skin ?? 'underline', dir, lang: options.locale, 'data-max-width': page.maxWidth });
+    const root = el('form', { class: 'fd-form', novalidate: '', 'data-fd-skin': options.skin ?? 'underline', dir, lang: tag, 'data-max-width': page.maxWidth });
+    applyLook(root, page.look);
     const confirm = options.confirm ?? dialogConfirm;
+    const say = sayer(root, el, labels.dismiss);
+    /** The tabs a step can show, by id: each shows its tab, false when it is hidden. */
+    const tabs = new Map();
+    /**
+     * A press runs its steps one run at a time: the button busy meanwhile, and
+     * not pressed again. A check or a save that stops it takes the focus to the
+     * first problem, and says which fields, as Save does.
+     */
+    async function press(button, run) {
+        if (button.hasAttribute('aria-busy'))
+            return;
+        button.setAttribute('aria-busy', 'true');
+        button.setAttribute('aria-disabled', 'true');
+        try {
+            const { reason } = await run();
+            if (reason === 'check' || reason === 'save') {
+                if (!form.getState().saveProblem)
+                    announce(checkText(form.getState()));
+                focusFirstProblem();
+            }
+        }
+        finally {
+            button.removeAttribute('aria-busy');
+            button.removeAttribute('aria-disabled');
+        }
+    }
     // ---- the parts -------------------------------------------------------
-    function fieldItem(node) {
-        const def = page.fields[node.field];
-        const id = uid(node.id);
-        const wrapper = el('div', { class: 'fd-field', 'data-node': node.id, 'data-field': node.field, 'data-type': def.type });
-        if (node.colspan)
-            wrapper.style.setProperty('--fd-span', String(node.colspan));
-        const label = el('label', { class: 'fd-label', id: `${id}-label`, for: id }, node.label ?? def.label);
-        // The ✓ of a field filled in right; never on a yes/no box, a table or a file, where it would say nothing.
-        const mark = options.showValid && !NO_VALID_MARK.has(def.type) ? drawIcon(doc, 'check') : null;
-        if (mark) {
-            mark.classList.add('fd-valid-mark');
-            label.append(mark);
-        }
-        const widget = createWidget({ form, name: node.field, field: def, node, id, document: doc, labels: widgetLabels, preferences, locale, dialogs }, options.widgets);
-        if (!['INPUT', 'SELECT', 'TEXTAREA'].includes(widget.element.tagName)) {
-            // `for` stays: a custom field that puts the id on its own input is
-            // labelled natively. Only a wrapper with a role (a radio group, say) may
-            // carry a name; ARIA forbids naming a plain div or span.
-            if (widget.element.getAttribute('role'))
-                widget.element.setAttribute('aria-labelledby', label.id);
-            label.addEventListener('click', () => widget.focus());
-        }
-        const helpText = node.help ?? def.help;
-        const help = helpText ? el('div', { class: 'fd-help', id: `${id}-help` }, helpText) : null;
-        // Not an alert of its own: a refused save is announced once, naming every field to look at.
-        const error = el('div', { class: 'fd-error', id: `${id}-error`, hidden: '' });
-        // A warning from the data source's onchange, beside the field whose change brought it.
-        const warning = el('div', { class: 'fd-warning', role: 'status', hidden: '' });
-        wrapper.append(label, widget.element, ...(help ? [help] : []), error, warning);
-        if (widget.destroy)
-            cleanups.push(() => widget.destroy?.());
-        updaters.push((state) => {
-            const shown = form.node(node.id);
-            wrapper.hidden = shown.invisible;
-            wrapper.classList.toggle('fd-required', shown.required);
-            const message = state.errors[node.field];
-            error.hidden = !message;
-            error.textContent = message ?? '';
-            const warned = state.warning && state.warningField === node.field ? state.warning : '';
-            warning.hidden = !warned;
-            warning.textContent = warned;
+    /** Folded sections, and how to open each: a problem inside one has to be seen. */
+    const folds = new Map();
+    /** Every part drawn again from the state of the page shown. */
+    const renderNow = () => render(form.getState());
+    /** Set once the viewer is on the page; set again when it is taken away. */
+    let mounted = false;
+    let gone = false;
+    /** The columns a part spans in the grid it sits in; the stylesheet keeps it within the columns there at each width. */
+    function spans(element, colspan) {
+        if (colspan)
+            element.style.setProperty('--fd-span', String(colspan));
+    }
+    /** Where the parts of a page, a tab or a step sit: one column, the page's labels. */
+    const top = (onPage) => ({ columns: 1, onPage, labels: page.look?.labels });
+    /**
+     * The parts of one page, drawn with its own form: the page shown, or a saved
+     * form placed in it. Inside, `form` and `page` are the scope's.
+     */
+    function drawer(scope) {
+        const { form, page } = scope;
+        const uid = (id) => ownUid(scope.prefix + id);
+        /** A part's updater, handed the state of the part's own form. */
+        const watch = (update) => updaters.push(scope.root ? update : () => update(form.getState()));
+        /** A field with its label, help and messages. `labels` is where labels sit where it is put; the title's own fields take none. */
+        function fieldItem(node, labels) {
+            const def = page.fields[node.field];
+            const id = uid(node.id);
+            const labelsAt = labelPlace(node, def.type, labels);
+            const wrapper = el('div', { class: 'fd-field', 'data-node': node.id, 'data-field': node.field, 'data-path': scope.path + node.field, 'data-type': def.type, 'data-labels': labelsAt });
+            if (node.colspan)
+                wrapper.style.setProperty('--fd-span', String(node.colspan));
+            const labelText = node.label ?? def.label;
+            const label = el('label', { class: 'fd-label', id: `${id}-label`, for: id }, labelText);
+            // The ✓ of a field filled in right; never on a yes/no box, a table or a file, where it would say nothing.
+            const mark = options.showValid && !NO_VALID_MARK.has(def.type) ? drawIcon(doc, 'check') : null;
             if (mark) {
-                const value = state.values[node.field];
-                const filled = value !== null && value !== undefined && value !== '' && !(Array.isArray(value) && !value.length);
-                const valid = !shown.readonly && !message && filled && state.dirty.includes(node.field) && form.problem(node.field) === null;
-                wrapper.classList.toggle('fd-valid', valid);
-                mark.toggleAttribute('hidden', !valid);
+                mark.classList.add('fd-valid-mark');
+                label.append(mark);
+            }
+            const widget = createWidget({ form, name: node.field, field: def, node, id, document: doc, labels: widgetLabels, preferences, locale, dialogs }, options.widgets);
+            // A label kept out of sight still names the box; the empty box shows it instead, unless the page gives it words of its own.
+            if (labelsAt === 'hidden' && !node.placeholder) {
+                const box = widget.element.matches(TEXT_BOX) ? widget.element : widget.element.querySelector(TEXT_BOX);
+                box?.setAttribute('placeholder', labelText);
+            }
+            if (!['INPUT', 'SELECT', 'TEXTAREA'].includes(widget.element.tagName)) {
+                // `for` stays: a custom field that puts the id on its own input is
+                // labelled natively. Only a wrapper with a role (a radio group, say) may
+                // carry a name; ARIA forbids naming a plain div or span.
+                // A group inside a box of its own (a radio group with "Clear selection" under it) is named too.
+                const named = widget.element.getAttribute('role') ? widget.element : widget.element.querySelector(`[id="${id}"][role]`);
+                named?.setAttribute('aria-labelledby', label.id);
+                label.addEventListener('click', () => widget.focus());
             }
-            widget.update({
-                value: state.values[node.field],
-                values: state.values,
-                readonly: shown.readonly || locked,
-                required: shown.required,
-                invalid: !!message,
-                describedBy: [help?.id, message ? error.id : undefined].filter(Boolean).join(' ') || undefined,
+            const helpText = node.help ?? def.help;
+            const help = helpText ? el('div', { class: 'fd-help', id: `${id}-help` }, helpText) : null;
+            // Not an alert of its own: a refused save is announced once, naming every field to look at.
+            const error = el('div', { class: 'fd-error', id: `${id}-error`, hidden: '' });
+            // A warning from an answer rule, and one from the data source's onchange beside the field whose change brought it.
+            const warning = el('div', { class: 'fd-warning', id: `${id}-warning`, role: 'status', hidden: '' });
+            wrapper.append(...(labelsAt === 'after' ? [widget.element, label] : [label, widget.element]), ...(help ? [help] : []), error, warning);
+            if (widget.destroy)
+                cleanups.push(() => widget.destroy?.());
+            // An answer rule's warning waits until the person leaves the field: no advice
+            // mid-word. One already shown stays while they put it right, and goes once they have.
+            let typing = false;
+            let advice = '';
+            wrapper.addEventListener('focusin', () => (typing = true));
+            wrapper.addEventListener('focusout', (event) => {
+                if (wrapper.contains(event.relatedTarget))
+                    return;
+                typing = false;
+                // Not at once: focus also leaves when a redraw removes the focused part
+                // (a deleted line's button), and that redraw must finish first.
+                queueMicrotask(() => update(form.getState()));
             });
-        });
-        return wrapper;
-    }
-    function hideWhen(element, id) {
-        updaters.push(() => {
-            element.hidden = form.node(id).invisible;
-        });
-    }
-    function buttonItem(node) {
-        const button = el('button', { type: 'button', class: `fd-button fd-button-${node.style ?? 'secondary'}`, 'data-node': node.id }, ...withIcon(node.icon, node.label));
-        button.addEventListener('click', async () => {
-            if (node.confirm && !(await confirm(node.confirm)))
-                return;
-            await form.runAction(node.id);
-        });
-        hideWhen(button, node.id);
-        return button;
-    }
-    function textItem(node) {
-        const style = node.style ?? 'paragraph';
-        const element = el(style === 'heading' ? 'h3' : 'p', { class: `fd-text-${style}`, 'data-node': node.id }, node.text);
-        hideWhen(element, node.id);
-        return element;
-    }
-    function slotItem(node) {
-        const element = el('div', { class: 'fd-slot', 'data-slot': node.name, 'data-node': node.id });
-        const cleanup = options.slots?.[node.name]?.(element, { form, name: node.name });
-        if (cleanup)
-            cleanups.push(cleanup);
-        hideWhen(element, node.id);
-        return element;
-    }
-    function grid(children, columns = 1) {
-        const box = el('div', { class: 'fd-grid' });
-        box.style.setProperty('--fd-columns', String(wideColumns(columns)));
-        // Counts given for the narrower widths replace the skin's own stacking there.
-        if (typeof columns === 'object') {
-            for (const width of ['medium', 'narrow']) {
-                const count = columns[width];
-                if (count === undefined)
-                    continue;
-                box.setAttribute(`data-columns-${width}`, String(count));
-                box.style.setProperty(`--fd-columns-${width}`, String(count));
+            const update = (state) => {
+                const shown = form.node(node.id);
+                setHidden(wrapper, shown.invisible);
+                wrapper.classList.toggle('fd-required', shown.required);
+                const message = state.errors[node.field];
+                setHidden(error, !message);
+                setText(error, message ?? '');
+                const now = state.warnings[node.field] ?? '';
+                if (!typing || !now)
+                    advice = now;
+                // An error shown says enough: the rule's warning gives way to it.
+                const warned = [message ? '' : advice, state.warning && state.warningField === node.field ? state.warning : ''].filter(Boolean).join(' ');
+                setHidden(warning, !warned);
+                setText(warning, warned);
+                if (mark) {
+                    const value = state.values[node.field];
+                    const filled = value !== null && value !== undefined && value !== '' && !(Array.isArray(value) && !value.length);
+                    const valid = !shown.readonly && !message && filled && state.dirty.includes(node.field) && form.problem(node.field) === null;
+                    wrapper.classList.toggle('fd-valid', valid);
+                    mark.toggleAttribute('hidden', !valid);
+                }
+                widget.update({
+                    value: state.values[node.field],
+                    values: state.values,
+                    readonly: shown.readonly || locked || scope.locked(),
+                    required: shown.required,
+                    invalid: !!message,
+                    describedBy: [help?.id, message ? error.id : undefined, warned ? warning.id : undefined].filter(Boolean).join(' ') || undefined,
+                });
+            };
+            watch(update);
+            return wrapper;
+        }
+        function hideWhen(element, id) {
+            watch(() => setHidden(element, form.node(id).invisible));
+        }
+        function buttonItem(node) {
+            const button = el('button', { type: 'button', class: `fd-button fd-button-${node.style ?? 'secondary'}`, 'data-node': node.id }, ...withIcon(node.icon, node.label));
+            spans(button, node.colspan);
+            // Its confirmation, then its steps: the form asks, through the viewer.
+            button.addEventListener('click', () => void press(button, () => form.runAction(node.id)));
+            hideWhen(button, node.id);
+            return button;
+        }
+        function textItem(node) {
+            const style = node.style ?? 'paragraph';
+            const element = el(style === 'heading' ? 'h3' : 'p', { class: `fd-text-${style}`, 'data-node': node.id }, node.text);
+            spans(element, node.colspan);
+            hideWhen(element, node.id);
+            return element;
+        }
+        function slotItem(node) {
+            const element = el('div', { class: 'fd-slot', 'data-slot': node.name, 'data-node': node.id });
+            const cleanup = options.slots?.[node.name]?.(element, { form, name: node.name });
+            if (cleanup)
+                cleanups.push(cleanup);
+            hideWhen(element, node.id);
+            return element;
+        }
+        /**
+         * A grid of parts. With `columns` null, it has none of its own: it lays its
+         * parts on the columns of the grid round it (an arrangement on its tracks).
+         */
+        function grid(children, columns, place) {
+            const box = el('div', { class: 'fd-grid' });
+            if (columns !== null) {
+                box.style.setProperty('--fd-columns', String(wideColumns(columns)));
+                // Counts given for the narrower widths replace the skin's own stacking there.
+                if (typeof columns === 'object') {
+                    for (const width of ['medium', 'narrow']) {
+                        const count = columns[width];
+                        if (count === undefined)
+                            continue;
+                        box.setAttribute(`data-columns-${width}`, String(count));
+                        box.style.setProperty(`--fd-columns-${width}`, String(count));
+                    }
+                }
             }
+            box.append(...children.map((child) => item(child, place)));
+            return box;
         }
-        box.append(...children.map(item));
-        return box;
-    }
-    /** Folded sections, and how to open each: a problem inside one has to be seen. */
-    const folds = new Map();
-    function sectionItem(node) {
-        const section = el('fieldset', { class: 'fd-section', 'data-node': node.id });
-        const description = node.description ? el('p', { class: 'fd-section-description' }, node.description) : null;
-        const content = grid(node.children, node.columns);
-        if (node.title && node.collapsible) {
-            content.id = uid(`${node.id}-content`);
-            const toggle = el('button', { type: 'button', class: 'fd-section-toggle', 'aria-controls': content.id }, el('span', { class: 'fd-section-chevron', 'aria-hidden': 'true' }), ...withIcon(node.icon, node.title));
-            let open = node.collapsed !== true;
-            const show = (next) => {
-                open = next;
-                toggle.setAttribute('aria-expanded', String(open));
-                content.hidden = !open;
-                if (description)
-                    description.hidden = !open;
-                section.classList.toggle('fd-section-folded', !open);
+        function sectionItem(node, place) {
+            const plan = planSection(node, place);
+            // An arrangement is no group to name, and a fieldset cannot lay its parts on the columns round it.
+            const section = el(plan.arrangement ? 'div' : 'fieldset', {
+                class: 'fd-section',
+                'data-node': node.id,
+                'data-style': plan.style,
+                'data-place': plan.at,
+                'data-on-page': plan.style === 'card' && place.onPage ? '' : undefined,
+            });
+            spans(section, node.colspan);
+            if (node.labelWidth)
+                section.style.setProperty('--fd-label-width', `${node.labelWidth}px`);
+            const description = node.description ? el('p', { class: 'fd-section-description' }, node.description) : null;
+            const content = grid(node.children, plan.at === 'tracks' ? null : node.columns, plan.inner);
+            if (node.title && node.collapsible) {
+                content.id = uid(`${node.id}-content`);
+                const toggle = el('button', { type: 'button', class: 'fd-section-toggle', 'aria-controls': content.id }, el('span', { class: 'fd-section-chevron', 'aria-hidden': 'true' }), ...withIcon(node.icon, node.title));
+                let open = node.collapsed !== true;
+                const show = (next) => {
+                    open = next;
+                    toggle.setAttribute('aria-expanded', String(open));
+                    content.hidden = !open;
+                    if (description)
+                        description.hidden = !open;
+                    section.classList.toggle('fd-section-folded', !open);
+                };
+                toggle.addEventListener('click', () => show(!open));
+                folds.set(section, () => show(true));
+                show(open);
+                section.append(el('legend', { class: 'fd-section-title' }, toggle));
+            }
+            else if (node.title) {
+                section.append(el('legend', { class: 'fd-section-title' }, ...withIcon(node.icon, node.title)));
+            }
+            if (description)
+                section.append(description);
+            section.append(content);
+            hideWhen(section, node.id);
+            return section;
+        }
+        function tabsItem(node, place) {
+            const box = el('div', { class: 'fd-tabs', 'data-node': node.id });
+            spans(box, node.colspan);
+            const list = el('div', { class: 'fd-tablist', role: 'tablist' });
+            // The tab someone picked. Until they pick, the first visible tab is open —
+            // a tab hidden while the record loads must not leave its neighbour open.
+            let picked = null;
+            let active = node.children[0].id;
+            /** A tab shown, by a person or a step: the page's steps for it run. */
+            const show = (tab) => {
+                picked = active = tab;
+                renderNow();
+                form.shown(tab);
             };
-            toggle.addEventListener('click', () => show(!open));
-            folds.set(section, () => show(true));
-            show(open);
-            section.append(el('legend', { class: 'fd-section-title' }, toggle));
-        }
-        else if (node.title) {
-            section.append(el('legend', { class: 'fd-section-title' }, ...withIcon(node.icon, node.title)));
-        }
-        if (description)
-            section.append(description);
-        section.append(content);
-        hideWhen(section, node.id);
-        return section;
-    }
-    function tabsItem(node) {
-        const box = el('div', { class: 'fd-tabs', 'data-node': node.id });
-        const list = el('div', { class: 'fd-tablist', role: 'tablist' });
-        // The tab someone picked. Until they pick, the first visible tab is open —
-        // a tab hidden while the record loads must not leave its neighbour open.
-        let picked = null;
-        let active = node.children[0].id;
-        const parts = node.children.map((tab) => {
-            const tabId = uid(`${tab.id}-tab`);
-            const panelId = uid(`${tab.id}-panel`);
-            const button = el('button', { type: 'button', class: 'fd-tab', role: 'tab', id: tabId, 'aria-controls': panelId, 'data-node': tab.id }, ...withIcon(tab.icon, tab.label));
-            const panel = el('div', { class: 'fd-tabpanel', role: 'tabpanel', id: panelId, 'aria-labelledby': tabId }, grid(tab.children));
-            button.addEventListener('click', () => {
-                picked = active = tab.id;
-                render(form.getState());
+            const parts = node.children.map((tab) => {
+                const tabId = uid(`${tab.id}-tab`);
+                const panelId = uid(`${tab.id}-panel`);
+                const button = el('button', { type: 'button', class: 'fd-tab', role: 'tab', id: tabId, 'aria-controls': panelId, 'data-node': tab.id }, ...withIcon(tab.icon, tab.label));
+                // A tab's parts sit where the tabs do: on the page, or in the box round them.
+                const panel = el('div', { class: 'fd-tabpanel', role: 'tabpanel', id: panelId, 'aria-labelledby': tabId }, grid(tab.children, 1, { columns: 1, onPage: place.onPage, labels: place.labels }));
+                button.addEventListener('click', () => show(tab.id));
+                if (!tabs.has(tab.id))
+                    tabs.set(tab.id, () => !form.node(tab.id).invisible && (show(tab.id), true));
+                list.append(button);
+                return { tab, button, panel };
             });
-            list.append(button);
-            return { tab, button, panel };
-        });
-        list.addEventListener('keydown', (event) => {
-            const shown = parts.filter((p) => !p.button.hidden);
-            const at = shown.findIndex((p) => p.tab.id === active);
-            const move = { ArrowRight: 1, ArrowLeft: -1, Home: -at, End: shown.length - 1 - at }[event.key];
-            if (move === undefined || at === -1)
-                return;
-            event.preventDefault();
-            const rtl = root.getAttribute('dir') === 'rtl' && (event.key === 'ArrowRight' || event.key === 'ArrowLeft');
-            const next = shown[(at + (rtl ? -move : move) + shown.length) % shown.length];
-            picked = active = next.tab.id;
-            render(form.getState());
-            next.button.focus();
-        });
-        box.append(list, ...parts.map((p) => p.panel));
-        updaters.push(() => {
-            box.hidden = form.node(node.id).invisible;
-            const shown = parts.filter((p) => !form.node(p.tab.id).invisible);
-            const keep = picked !== null && shown.some((p) => p.tab.id === picked);
-            if (keep)
-                active = picked;
-            else if (shown.length)
-                active = shown[0].tab.id;
-            for (const p of parts) {
-                const selected = p.tab.id === active;
-                p.button.hidden = !shown.includes(p);
-                p.button.setAttribute('aria-selected', String(selected));
-                p.button.tabIndex = selected ? 0 : -1;
-                p.panel.hidden = !selected;
+            list.addEventListener('keydown', (event) => {
+                const shown = parts.filter((p) => !p.button.hidden);
+                const at = shown.findIndex((p) => p.tab.id === active);
+                const move = { ArrowRight: 1, ArrowLeft: -1, Home: -at, End: shown.length - 1 - at }[event.key];
+                if (move === undefined || at === -1)
+                    return;
+                event.preventDefault();
+                const rtl = root.getAttribute('dir') === 'rtl' && (event.key === 'ArrowRight' || event.key === 'ArrowLeft');
+                const next = shown[(at + (rtl ? -move : move) + shown.length) % shown.length];
+                show(next.tab.id);
+                next.button.focus();
+            });
+            box.append(list, ...parts.map((p) => p.panel));
+            watch(() => {
+                box.hidden = form.node(node.id).invisible;
+                const shown = parts.filter((p) => !form.node(p.tab.id).invisible);
+                const keep = picked !== null && shown.some((p) => p.tab.id === picked);
+                if (keep)
+                    active = picked;
+                else if (shown.length)
+                    active = shown[0].tab.id;
+                for (const p of parts) {
+                    const selected = p.tab.id === active;
+                    p.button.hidden = !shown.includes(p);
+                    p.button.setAttribute('aria-selected', String(selected));
+                    p.button.tabIndex = selected ? 0 : -1;
+                    p.panel.hidden = !selected;
+                }
+            });
+            return box;
+        }
+        function item(node, place) {
+            switch (node.type) {
+                case 'field':
+                    return fieldItem(node, place.labels);
+                case 'button':
+                    return buttonItem(node);
+                case 'text':
+                    return textItem(node);
+                case 'slot':
+                    return slotItem(node);
+                case 'section':
+                    return sectionItem(node, place);
+                case 'tabs':
+                    return tabsItem(node, place);
+                case 'divider':
+                case 'spacer':
+                case 'image':
+                    return blockItem(node);
+                case 'form':
+                    return formItem(node, place);
             }
-        });
-        return box;
-    }
-    function item(node) {
-        switch (node.type) {
-            case 'field':
-                return fieldItem(node);
-            case 'button':
-                return buttonItem(node);
-            case 'text':
-                return textItem(node);
-            case 'slot':
-                return slotItem(node);
-            case 'section':
-                return sectionItem(node);
-            case 'tabs':
-                return tabsItem(node);
         }
+        /** A line across the row, empty room, or a picture: shown and hidden by its rule like any part. */
+        function blockItem(node) {
+            const element = node.type === 'divider' ? el('hr', { class: 'fd-divider', 'data-node': node.id })
+                : node.type === 'spacer' ? el('div', { class: 'fd-block fd-spacer', 'aria-hidden': 'true', 'data-node': node.id })
+                    : figure(node);
+            if (node.type !== 'divider' && node.colspan)
+                element.style.setProperty('--fd-span', String(node.colspan));
+            hideWhen(element, node.id);
+            return element;
+        }
+        /** A picture as wide and where its page says, opening its link in a new tab — a web or mail address only — its caption under it. */
+        function figure(node) {
+            const image = el('img', { class: 'fd-image', src: node.src, alt: node.alt, loading: 'lazy' });
+            const href = node.href && /^(https?:\/\/|mailto:)/i.test(node.href) ? node.href : undefined;
+            const element = el('figure', { class: 'fd-block fd-figure', 'data-node': node.id, 'data-align': node.align }, href ? el('a', { href, target: '_blank', rel: 'noopener noreferrer' }, image) : image, ...(node.caption ? [el('figcaption', { class: 'fd-caption' }, node.caption)] : []));
+            const width = typeof node.width === 'number' ? `${node.width}px` : node.width && { small: '160px', medium: '320px', large: '480px', full: '100%' }[node.width];
+            if (width)
+                element.style.setProperty('--fd-image-width', width);
+            return element;
+        }
+        /**
+         * A saved form placed here, drawn from the page the app gives for its id
+         * with a form of its own inside this one. A quiet placeholder while the
+         * page comes; words in its place when it cannot be found, would hold
+         * itself, or cannot sit in a form.
+         */
+        function formItem(node, place) {
+            const box = el('fieldset', {
+                class: 'fd-section fd-form-part',
+                'data-node': node.id,
+                'data-style': 'card',
+                'data-on-page': place.onPage ? '' : undefined,
+                'aria-busy': 'true',
+            });
+            spans(box, node.colspan);
+            const note = el('p', { class: 'fd-form-part-note' }, labels.loading);
+            box.append(note);
+            hideWhen(box, node.id);
+            const refuse = (words) => {
+                box.removeAttribute('aria-busy');
+                note.textContent = words;
+                note.classList.add('fd-form-part-problem');
+            };
+            const draw = (found) => {
+                if (gone)
+                    return;
+                if (!found)
+                    return refuse(fill(labels.formMissing, { page: node.page }));
+                const saved = shownAs(found);
+                const name = saved.title || found.id;
+                const at = scope.chain.findIndex((p) => p.id === found.id);
+                if (at !== -1)
+                    return refuse(fill(labels.formInItself, { page: name, chain: [...scope.chain.slice(at).map((p) => p.title), name].join(' → ') }));
+                if (found.layout.type !== 'sections' && found.layout.type !== 'tabs')
+                    return refuse(fill(labels.formNotPlaceable, { page: name }));
+                const checked = checkPage(saved);
+                let inner;
+                try {
+                    if (!checked.ok)
+                        throw new Error(checked.issues.map((i) => `${i.path}: ${i.message}`).join('; '));
+                    inner = form.embed(node.id, saved);
+                }
+                catch (error) {
+                    console.warn(`Fieldia: the saved form "${found.id}" cannot be shown: ${error.message}`);
+                    return refuse(fill(labels.formBroken, { page: name }));
+                }
+                const title = node.title ?? saved.title ?? '';
+                box.setAttribute('data-title', title);
+                if (title)
+                    box.prepend(el('legend', { class: 'fd-section-title' }, ...withIcon(undefined, title)));
+                const own = drawer({
+                    root: false,
+                    form: inner,
+                    page: saved,
+                    prefix: `${scope.prefix}${node.id}-`,
+                    chain: [...scope.chain, { id: found.id, title: name }],
+                    locked: () => scope.locked() || form.node(node.id).readonly,
+                    path: `${scope.path}${node.name}.`,
+                });
+                const layout = saved.layout;
+                // Its parts sit in the part's box: a card there draws none of its own.
+                note.replaceWith(own.grid(layout.type === 'tabs' ? [layout] : layout.children, 1, { columns: 1, onPage: false, labels: place.labels }));
+                box.removeAttribute('aria-busy');
+                cleanups.push(inner.subscribe(renderNow));
+                if (mounted)
+                    renderNow();
+            };
+            let asked;
+            try {
+                asked = findPage(options, node.version === undefined ? { id: node.page } : { id: node.page, version: node.version });
+            }
+            catch {
+                asked = null;
+            }
+            if (asked instanceof Promise)
+                asked.then(draw, () => draw(null));
+            else
+                draw(asked);
+            return box;
+        }
+        return { item, grid, fieldItem, buttonItem, hideWhen, slotItem };
     }
+    const { item, grid, fieldItem, buttonItem, hideWhen, slotItem } = drawer({
+        root: true,
+        form,
+        page,
+        prefix: '',
+        chain: [{ id: page.id, title: page.title || page.id }],
+        locked: () => false,
+        path: '',
+    });
     // ---- shared chrome ----------------------------------------------------------
     /** The whole form locked: every field read-only, no Save; buttons still run. */
     let locked = options.readonly === true;
@@ -287,18 +535,27 @@ export function mountViewer(host, options) {
     retry.addEventListener('click', () => void submitOrSave());
     const status = el('div', { class: 'fd-status-box' }, statusText, retry);
     const notDone = () => (page.data.kind === 'responses' ? labels.notSent : labels.notSaved);
-    /** "Not saved. Check: Email, Phone": the fields with a problem, in the order they show. */
+    /**
+     * "Not saved. Check: Email, Phone": the fields with a problem, in the order
+     * they show; one inside a saved form with that form's title, "Street (Home address)".
+     */
     function checkText(state) {
-        const names = [];
+        const fieldsShown = [...root.querySelectorAll('.fd-field[data-path]')];
+        const found = [];
         for (const key of Object.keys(state.errors)) {
-            const field = key.split('.')[0];
-            const shown = root.querySelector(`.fd-field[data-field="${field}"]:not([hidden]) > .fd-label`);
-            const name = shown?.firstChild?.textContent ?? page.fields[field]?.label ?? field;
-            if (!names.includes(name))
-                names.push(name);
-        }
-        const inOrder = [...root.querySelectorAll('.fd-field[data-field] > .fd-label')].map((label) => label.firstChild?.textContent ?? '');
-        names.sort((a, b) => (inOrder.indexOf(a) + 1 || Infinity) - (inOrder.indexOf(b) + 1 || Infinity));
+            // The field itself, or — for a line's — the table it is in.
+            let shown;
+            for (let path = key; path && !shown; path = path.slice(0, Math.max(0, path.lastIndexOf('.')))) {
+                shown = fieldsShown.find((field) => field.getAttribute('data-path') === path && !field.hidden);
+            }
+            const first = key.split('.')[0];
+            const label = shown?.querySelector(':scope > .fd-label')?.firstChild?.textContent ?? page.fields[first]?.label ?? first;
+            const within = shown?.closest('.fd-form-part')?.getAttribute('data-title');
+            const name = within ? `${label} (${within})` : label;
+            if (!found.some((f) => f.name === name))
+                found.push({ name, at: shown ? fieldsShown.indexOf(shown) : Infinity });
+        }
+        const names = found.sort((a, b) => a.at - b.at).map((f) => f.name);
         return names.length ? fill(labels.checkFields, { what: notDone(), fields: names.join(', ') }) : notDone();
     }
     let quietTimer;
@@ -310,8 +567,10 @@ export function mountViewer(host, options) {
                     : state.status === 'error' && problem ? (problem.kind === 'fields' ? checkText(state) : problem.kind === 'other' ? problem.message : notDone())
                         : state.status === 'error' ? state.error ?? ''
                             : '';
-        statusText.textContent = text;
-        retry.hidden = !(state.status === 'error' && problem?.kind === 'other');
+        // A problem is said once, at once, by the announcer (or the banner, or a dialog): the status shows it and keeps quiet.
+        setAttr(statusText, 'aria-live', state.status === 'error' && problem ? 'off' : 'polite');
+        setText(statusText, text);
+        setHidden(retry, !(state.status === 'error' && problem?.kind === 'other'));
         statusText.classList.toggle('fd-status-error', state.status === 'error');
         statusText.classList.toggle('fd-status-saved', state.status === 'saved');
         // A toast shows while there is something to say, and lets "Saved" go after a moment.
@@ -356,7 +615,7 @@ export function mountViewer(host, options) {
     discardDraft.addEventListener('click', () => form.discardDraft());
     draft.append(draftText, restore, discardDraft);
     updaters.push((state) => {
-        draft.hidden = !state.draft;
+        setHidden(draft, !state.draft);
         if (state.draft)
             draftText.textContent = fill(labels.draftFound, { time: new Date(state.draft.savedAt).toLocaleString() });
     });
@@ -408,7 +667,7 @@ export function mountViewer(host, options) {
     }
     // ---- the four page layouts ---------------------------------------------------
     function sectionsLayout(node) {
-        const box = el('div', { class: 'fd-sections', 'data-node': node.id }, ...node.children.map(item));
+        const box = el('div', { class: 'fd-sections', 'data-node': node.id }, ...node.children.map((child) => item(child, top(true))));
         const action = el('button', { type: 'submit', class: 'fd-button fd-button-primary' }, page.data.kind === 'responses' ? labels.submit : labels.save);
         const actions = el('div', { class: 'fd-actions fd-actions-end' }, status, action);
         if (page.data.kind === 'record') {
@@ -418,12 +677,12 @@ export function mountViewer(host, options) {
             actions.insertBefore(discard, action);
             updaters.push((state) => {
                 const dirty = state.dirty.length > 0 && state.status !== 'saving' && !locked;
-                action.hidden = !dirty;
-                discard.hidden = !dirty;
+                setHidden(action, !dirty);
+                setHidden(discard, !dirty);
             });
         }
         else
-            updaters.push(() => (action.hidden = locked));
+            updaters.push(() => setHidden(action, locked));
         if (editSwitch)
             actions.prepend(editSwitch);
         if (options.showActions === false)
@@ -461,7 +720,8 @@ export function mountViewer(host, options) {
             panel.append(el('h2', { class: 'fd-step-title', id: uid(`${step.id}-title`) }, ...withIcon(step.icon, step.label)));
             if (step.description)
                 panel.append(el('p', { class: 'fd-section-description' }, step.description));
-            panel.append(grid(step.children));
+            // The step is the box: a card in it draws none of its own.
+            panel.append(grid(step.children, 1, top(false)));
             box.append(panel);
             return { step, panel };
         });
@@ -560,7 +820,7 @@ export function mountViewer(host, options) {
                 const icon = drawIcon(doc, stat.icon, options.icons);
                 const words = el('span', { class: 'fd-stat-words' }, value, el('span', { class: 'fd-stat-label' }, stat.label));
                 const button = el('button', { type: 'button', class: 'fd-stat', 'data-node': stat.id }, ...(icon ? [icon, words] : [words]));
-                button.addEventListener('click', () => void form.runAction(stat.id));
+                button.addEventListener('click', () => void press(button, () => form.runAction(stat.id)));
                 updaters.push((state) => {
                     button.hidden = form.node(stat.id).invisible;
                     const count = stat.field ? state.values[stat.field] : null;
@@ -604,12 +864,12 @@ export function mountViewer(host, options) {
         if (node.title) {
             const title = el('div', { class: 'fd-title' });
             if (node.title.above?.length)
-                title.append(el('div', { class: 'fd-title-above' }, ...node.title.above.map(fieldItem)));
+                title.append(el('div', { class: 'fd-title-above' }, ...node.title.above.map((part) => fieldItem(part))));
             title.append(fieldItem({ type: 'field', id: '#title', field: node.title.field, placeholder: node.title.placeholder }));
             if (node.title.subtitleField)
                 title.append(fieldItem({ type: 'field', id: '#subtitle', field: node.title.subtitleField }));
             if (node.title.below?.length)
-                title.append(el('div', { class: 'fd-title-below' }, ...node.title.below.map(fieldItem)));
+                title.append(el('div', { class: 'fd-title-below' }, ...node.title.below.map((part) => fieldItem(part))));
             const row = el('div', { class: 'fd-title-row' }, title);
             if (node.title.avatarField) {
                 const avatar = fieldItem({ type: 'field', id: '#avatar', field: node.title.avatarField });
@@ -620,7 +880,7 @@ export function mountViewer(host, options) {
         }
         if (node.statusbar && underTitle)
             card.append(el('div', { class: 'fd-title-statusbar' }, statusbar(node.statusbar)));
-        card.append(grid(node.children));
+        card.append(grid(node.children, 1, top(false)));
         if (atFoot && options.showActions !== false) {
             card.append(foot);
             updaters.push((state) => {
@@ -666,7 +926,7 @@ export function mountViewer(host, options) {
             labels,
             locale,
             fill,
-            confirm,
+            press,
             withIcon,
             uid,
             icons: options.icons,
@@ -763,15 +1023,27 @@ export function mountViewer(host, options) {
             const ok = el('button', { type: 'button', class: 'fd-button fd-button-primary' }, labels.ok);
             const dialog = el('div', { class: 'fd-dialog', role: 'alertdialog', 'aria-modal': 'true', 'aria-labelledby': text.id }, text, el('div', { class: 'fd-actions fd-actions-end' }, ...(withCancel ? [cancel, ok] : [ok])));
             const backdrop = el('div', { class: 'fd-dialog-backdrop' }, dialog);
+            const doc = root.ownerDocument;
+            const opener = doc.activeElement;
             const close = (answer) => {
                 backdrop.remove();
+                // Back to what had focus when it asked; or, when that let go of it — Save hides while it saves — to Save, shown again.
+                const shown = (e) => !!e && e !== doc.body && e.isConnected && !e.closest('[hidden]');
+                const back = shown(opener) ? opener : root.querySelector('button[type="submit"]:not([hidden])');
+                back?.focus();
                 resolve(answer);
             };
             cancel.addEventListener('click', () => close(false));
             ok.addEventListener('click', () => close(true));
+            // Its keys are its own: Escape answers No here, and closes no dialog or panel under it.
             backdrop.addEventListener('keydown', (event) => {
-                if (event.key === 'Escape')
+                event.stopPropagation();
+                if (event.key === 'Escape') {
+                    event.preventDefault();
                     close(false);
+                }
+                else
+                    keepTabIn(dialog, event);
             });
             root.append(backdrop);
             ok.focus();
@@ -784,7 +1056,13 @@ export function mountViewer(host, options) {
     }
     host.append(root);
     const unsubscribe = form.subscribe(render);
+    // A run that could not go on says why: a step that cannot run here, or what the app threw. A stop with words the form says itself.
+    cleanups.push(form.on('run', ({ result }) => {
+        if (result.reason === 'cannot' || (result.reason === 'app' && result.error !== undefined))
+            actionHost.say(result.message ?? '', result.reason === 'app' ? 'danger' : 'warning');
+    }));
     render(form.getState());
+    mounted = true;
     if (form.getState().status === 'idle')
         void form.load();
     return {
@@ -811,7 +1089,15 @@ export function mountViewer(host, options) {
             render(form.getState());
         },
         isReadonly: () => locked,
+        on: (event, listener) => {
+            const off = form.on(event, listener);
+            cleanups.push(off);
+            return off;
+        },
+        setValues: (values) => form.setValues(values),
+        run: (steps, context) => form.run(steps, context),
         destroy() {
+            gone = true;
             unsubscribe();
             for (const cleanup of cleanups)
                 cleanup();
@@ -821,6 +1107,8 @@ export function mountViewer(host, options) {
         },
     };
 }
+/** The boxes a label can be shown in, as the words of an empty box. */
+const TEXT_BOX = 'input:not([type="checkbox"]):not([type="radio"]):not([type="file"]):not([type="hidden"]), textarea';
 /** Fields whose ✓ would say nothing: a yes/no box is never wrong, a table or a file has its own look. */
 const NO_VALID_MARK = new Set(['boolean', 'one2many', 'binary', 'image', 'html', 'json', 'properties']);
 //# sourceMappingURL=viewer.mjs.map