@fieldia/viewer 0.11.0 → 0.12.0

package/src/lib/viewer.mjs

@@ -1,5 +1,5 @@
 import { createForm, checkPage, isRightToLeft, localizePage, translatePage, wideColumns, MESSAGES, } from '@fieldia/core';
-import { browserPreferences, createWidget, drawIcon, installStyles, WIDGET_LABELS } from '@fieldia/widgets';
+import { browserPreferences, createWidget, displayValue, drawIcon, installStyles, readsAsText, readText, WIDGET_LABELS } from '@fieldia/widgets';
 import { findPage, pageDialogs } from './related.mjs';
 import { listView } from './list.mjs';
 import { applyLook } from './look.mjs';
@@ -7,6 +7,12 @@ import { labelPlace, planSection } from './place.mjs';
 import { setAttr, setHidden, setText } from './dom.mjs';
 import { openPage } from './open.mjs';
 import { sayer } from './say.mjs';
+import { tabStrip } from './tab-strip.mjs';
+import { valueWords } from './value-words.mjs';
+import { hotkeyOf, hotkeyOn } from './hotkeys.mjs';
+import { recordBar } from './record-bar.mjs';
+import { attachmentPreview } from './attachment-preview.mjs';
+import { installRecordStyles } from './record-styles.mjs';
 import { ownLocale, VIEWER_LABELS } from './labels.mjs';
 import { keepTabIn } from './focus-trap.mjs';
 export { VIEWER_LABELS, DEFAULT_LABELS } from './labels.mjs';
@@ -19,7 +25,8 @@ let mounts = 0;
 export function mountViewer(host, options) {
     const doc = host.ownerDocument;
     // The quick check of names and conditions: the full one, with its validation library, belongs where pages are made.
-    const checked = checkPage(options.page);
+    // A line's own form reads the record the line is on as parent.
+    const checked = checkPage(options.page, options.parent ? { parent: options.parent.fields } : {});
     if (!checked.ok) {
         throw new Error(`This page cannot be shown:\n${checked.issues.map((i) => `  ${i.path}: ${i.message}`).join('\n')}`);
     }
@@ -34,7 +41,7 @@ export function mountViewer(host, options) {
     };
     const locale = ownLocale(tag);
     const preferences = options.preferences ?? browserPreferences();
-    const dialogs = pageDialogs(options);
+    const dialogs = pageDialogs(options, (message, tone) => actionHost.say(message, tone));
     const ownsForm = !options.form;
     const labels = { ...VIEWER_LABELS[locale], ...options.labels };
     /**
@@ -43,7 +50,17 @@ export function mountViewer(host, options) {
      * 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),
+        open: (request) => openPage({
+            options,
+            place: host,
+            root,
+            title: (other) => shownAs(other).title || other.id,
+            back: labels.back,
+            missing: (id) => fill(labels.pageMissing, { page: id }),
+            say: (message, tone) => actionHost.say(message, tone),
+            post: (message) => form.post(message),
+            name: () => recordName() || labels.newRecord,
+        }, request),
         say: (message, tone) => say(message, tone),
         ask: (message) => confirm(message),
         show: (target) => {
@@ -51,6 +68,8 @@ export function mountViewer(host, options) {
             if (!show?.())
                 throw new Error(`No tab "${target}" can be shown here`);
         },
+        // A new tab opened apart from this page, or this one sent there.
+        openUrl: (url, newTab) => (newTab ? doc.defaultView?.open(url, '_blank', 'noopener,noreferrer') : doc.defaultView?.location.assign(url)),
         ...options.host,
     };
     const form = options.form ?? createForm({ ...options, page, host: actionHost, messages: options.messages ?? MESSAGES[locale] });
@@ -58,11 +77,17 @@ export function mountViewer(host, options) {
     const dir = options.dir ?? (tag && isRightToLeft(tag) ? 'rtl' : undefined);
     const prefix = `fd${++mounts}`;
     const updaters = [];
+    /**
+     * Where a part's updater goes as it is drawn: the form's own list, or the list
+     * of the tab it is drawn in, which runs only while that tab is shown.
+     */
+    let sink = updaters;
     const cleanups = [];
     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);
+    installRecordStyles(doc);
     function el(tag, attrs = {}, ...children) {
         const node = doc.createElement(tag);
         for (const [name, value] of Object.entries(attrs))
@@ -87,6 +112,8 @@ export function mountViewer(host, options) {
     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();
+    /** For each field in a tab, how to show its tab: a problem there is shown before the focus goes to it. */
+    const problemTabs = 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
@@ -111,6 +138,8 @@ export function mountViewer(host, options) {
         }
     }
     // ---- the parts -------------------------------------------------------
+    /** The fields that take the focus as the record opens, in the order they are drawn. */
+    const focusers = [];
     /** 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. */
@@ -133,13 +162,13 @@ export function mountViewer(host, options) {
         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 watch = (update) => sink.push(scope.root ? update : () => update(form.getState()));
+        /** A field with its label, help and messages. `place` is where labels sit where it is put; the title's own fields take none. */
+        function fieldItem(node, place) {
             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 });
+            const labelsAt = labelPlace(node, def.type, place);
+            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, 'data-focus': node.focus && scope.root ? '' : undefined });
             if (node.colspan)
                 wrapper.style.setProperty('--fd-span', String(node.colspan));
             const labelText = node.label ?? def.label;
@@ -151,11 +180,16 @@ export function mountViewer(host, options) {
                 label.append(mark);
             }
             const widget = createWidget({ form, name: node.field, field: def, node, id, document: doc, labels: widgetLabels, preferences, locale, dialogs }, options.widgets);
+            // The field that takes the focus as the record opens (Flectra's default_focus): the page's own, not a saved form's inside it.
+            if (node.focus && scope.root)
+                focusers.push({ wrapper, focus: () => widget.focus() });
             // 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);
-            }
+            const textBox = widget.element.matches(TEXT_BOX) ? widget.element : widget.element.querySelector(TEXT_BOX);
+            if (labelsAt === 'hidden' && !node.placeholder)
+                textBox?.setAttribute('placeholder', labelText);
+            // Words chosen by a condition (placeholderWhen), else what the box showed as it was drawn.
+            const drawnPlaceholder = textBox?.getAttribute('placeholder') ?? null;
+            const chosenPlaceholder = node.placeholderWhen?.length ? textBox : null;
             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
@@ -166,12 +200,24 @@ export function mountViewer(host, options) {
                 label.addEventListener('click', () => widget.focus());
             }
             const helpText = node.help ?? def.help;
-            const help = helpText ? el('div', { class: 'fd-help', id: `${id}-help` }, helpText) : null;
+            // Under the field, behind a (?) by its label, or both: the field's own way, else the page's.
+            const helpWay = node.helpShown ?? page.look?.helpShown ?? 'below';
+            const help = helpText && helpWay !== 'tooltip' ? el('div', { class: 'fd-help', id: `${id}-help` }, helpText) : null;
+            const tip = helpText && helpWay !== 'below' ? helpTip(`${id}-tip`, helpText, fill(labels.helpFor, { label: labelText })) : null;
+            // In the label, as Flectra's: a press on it does not move into the box. A label out of sight keeps it after the box.
+            if (tip && labelsAt === 'hidden')
+                widget.element.after(tip.element);
+            else if (tip)
+                label.append(tip.element);
             // 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);
+            // Read-only, as words in place of the box, when the page draws them so.
+            const asText = page.look?.readonlyShown === 'text' && readsAsText(def, node) ? readText({ document: doc, field: def, node, id, locale, labels: widgetLabels, dialogs }) : null;
+            if (asText)
+                widget.element.after(asText.element);
             if (widget.destroy)
                 cleanups.push(() => widget.destroy?.());
             // An answer rule's warning waits until the person leaves the field: no advice
@@ -187,10 +233,19 @@ export function mountViewer(host, options) {
                 // (a deleted line's button), and that redraw must finish first.
                 queueMicrotask(() => update(form.getState()));
             });
+            const toned = node.tones !== undefined || node.bold !== undefined;
             const update = (state) => {
                 const shown = form.node(node.id);
                 setHidden(wrapper, shown.invisible);
                 wrapper.classList.toggle('fd-required', shown.required);
+                // Its value's tone and bold while a condition holds: Flectra's decoration-* on a field.
+                if (toned) {
+                    const look = form.fieldTone(node.id);
+                    setAttr(wrapper, 'data-tone', look.tone);
+                    wrapper.classList.toggle('fd-value-bold', look.bold);
+                }
+                if (chosenPlaceholder)
+                    setAttr(chosenPlaceholder, 'placeholder', form.placeholder(node.id) ?? drawnPlaceholder);
                 const message = state.errors[node.field];
                 setHidden(error, !message);
                 setText(error, message ?? '');
@@ -208,34 +263,80 @@ export function mountViewer(host, options) {
                     wrapper.classList.toggle('fd-valid', valid);
                     mark.toggleAttribute('hidden', !valid);
                 }
+                const readonly = shown.readonly || locked || scope.locked();
+                if (asText) {
+                    setHidden(widget.element, readonly);
+                    setHidden(asText.element, !readonly);
+                    setAttr(wrapper, 'data-read-text', readonly ? '' : null);
+                    if (readonly)
+                        asText.update(state.values[node.field], state.values);
+                }
                 widget.update({
                     value: state.values[node.field],
                     values: state.values,
-                    readonly: shown.readonly || locked || scope.locked(),
+                    readonly,
                     required: shown.required,
                     invalid: !!message,
-                    describedBy: [help?.id, message ? error.id : undefined, warned ? warning.id : undefined].filter(Boolean).join(' ') || undefined,
+                    describedBy: [help?.id ?? tip?.bubble.id, message ? error.id : undefined, warned ? warning.id : undefined].filter(Boolean).join(' ') || undefined,
                 });
             };
             watch(update);
             return wrapper;
         }
+        /** A (?) that shows a field's help in a bubble: on hover, on focus, or kept open by a press — a tap — and gone with Escape. */
+        function helpTip(bubbleId, text, name) {
+            const bubble = el('span', { class: 'fd-help-bubble', role: 'tooltip', id: bubbleId, hidden: '' }, text);
+            const button = el('button', { type: 'button', class: 'fd-help-tip', 'aria-label': name, 'aria-expanded': 'false', 'aria-controls': bubbleId }, '?');
+            let kept = false;
+            const show = (open) => {
+                bubble.hidden = !open;
+                button.setAttribute('aria-expanded', String(open));
+            };
+            button.addEventListener('mouseenter', () => show(true));
+            button.addEventListener('mouseleave', () => show(kept));
+            button.addEventListener('focus', () => show(true));
+            button.addEventListener('blur', () => ((kept = false), show(false)));
+            button.addEventListener('click', (event) => {
+                event.preventDefault();
+                kept = !kept;
+                show(kept);
+            });
+            button.addEventListener('keydown', (event) => {
+                if (event.key !== 'Escape' || bubble.hidden)
+                    return;
+                // Escape closes the bubble, not the dialog the form is in.
+                event.stopPropagation();
+                kept = false;
+                show(false);
+            });
+            return { element: el('span', { class: 'fd-help-tip-wrap' }, button, bubble), bubble };
+        }
         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));
+            if (node.hotkey)
+                hotkeyOn(button, node.hotkey, 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;
+            // A header's button is drawn here too, never through item(): hidden at its widths the same way.
+            return hiddenOn(node, button);
         }
-        function textItem(node) {
+        function textItem(node, inline = false) {
             const style = node.style ?? 'paragraph';
-            const element = el(style === 'heading' ? 'h3' : 'p', { class: `fd-text-${style}`, 'data-node': node.id }, node.text);
+            // Its words, with the values of the fields they name.
+            const words = valueWords(doc, page.fields, node.text, locale);
+            const element = inline
+                ? el('span', { class: `fd-oneline-words fd-text-${style}`, 'data-node': node.id }, ...words.nodes)
+                : style === 'alert'
+                    ? el('div', { class: `fd-alert fd-text-alert fd-tone-${node.tone ?? 'info'}`, role: 'status', 'data-node': node.id }, el('span', { class: 'fd-alert-message' }, ...words.nodes))
+                    : el(style === 'heading' ? 'h3' : 'p', { class: `fd-text-${style}`, 'data-node': node.id }, ...words.nodes);
             spans(element, node.colspan);
             hideWhen(element, node.id);
+            watch((state) => words.update(state.values));
             return element;
         }
         function slotItem(node) {
@@ -254,6 +355,9 @@ export function mountViewer(host, options) {
             const box = el('div', { class: 'fd-grid' });
             if (columns !== null) {
                 box.style.setProperty('--fd-columns', String(wideColumns(columns)));
+                // Twelfths: eleven gaps between them, which shrink in a narrow column rather than push past it.
+                if (wideColumns(columns) === 12)
+                    box.setAttribute('data-twelfths', '');
                 // Counts given for the narrower widths replace the skin's own stacking there.
                 if (typeof columns === 'object') {
                     for (const width of ['medium', 'narrow']) {
@@ -268,7 +372,44 @@ export function mountViewer(host, options) {
             box.append(...children.map((child) => item(child, place)));
             return box;
         }
+        /**
+         * A row of twelfths led by a field whose label sits beside it, as Flectra's
+         * `<label/><div class="o_row">`: that label goes with the labels round it,
+         * and the parts share the room their values have.
+         */
+        function labelledRow(node, plan) {
+            const [first] = node.children;
+            if (!plan.arrangement || plan.at === 'tracks' || wideColumns(node.columns) !== 12 || node.children.length < 2 || first?.type !== 'field')
+                return null;
+            // One line of them: parts running past twelve twelfths are a column of fields, each with its own label.
+            if (node.children.reduce((sum, child) => sum + (child.colspan ?? 1), 0) > 12)
+                return null;
+            const type = page.fields[first.field]?.type;
+            const where = type ? labelPlace(first, type, plan.inner.labels) : 'hidden';
+            // The skin's place: beside in the underline skin, above in the outlined one, as the stylesheet says.
+            return where === undefined ? 'skin' : where === 'beside' ? 'beside' : null;
+        }
+        /**
+         * A line of parts, as Flectra's `<label/><div class="o_row">`: its title as
+         * the line's label, where the labels round it sit, and its parts after it,
+         * each as wide as it needs, its fields named for a screen reader.
+         */
+        function inlineItem(node, place) {
+            const line = el('div', { class: 'fd-field fd-oneline', 'data-node': node.id, 'data-style': 'inline', 'data-labels': place.labels });
+            spans(line, node.colspan);
+            const row = el('div', { class: 'fd-oneline-row', role: 'group' }, ...node.children.map((child) => item(child, { columns: 1, onPage: false, inline: true })));
+            if (node.title) {
+                const title = el('span', { class: 'fd-label', id: uid(`${node.id}-label`) }, node.title);
+                row.setAttribute('aria-labelledby', title.id);
+                line.append(title);
+            }
+            line.append(row);
+            hideWhen(line, node.id);
+            return line;
+        }
         function sectionItem(node, place) {
+            if (node.style === 'inline')
+                return inlineItem(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', {
@@ -279,6 +420,9 @@ export function mountViewer(host, options) {
                 'data-on-page': plan.style === 'card' && place.onPage ? '' : undefined,
             });
             spans(section, node.colspan);
+            const row = labelledRow(node, plan);
+            if (row)
+                section.setAttribute('data-row', row);
             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;
@@ -327,13 +471,39 @@ export function mountViewer(host, options) {
                 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 }));
+                const panel = el('div', { class: 'fd-tabpanel', role: 'tabpanel', id: panelId, 'aria-labelledby': tabId });
+                /**
+                 * A tab's parts are drawn when it is first shown, and kept up to date
+                 * only while it is shown: a page of many tabs costs one tab's work.
+                 */
+                const own = [];
+                let built = false;
+                const build = () => {
+                    if (built)
+                        return;
+                    built = true;
+                    const outer = sink;
+                    sink = own;
+                    try {
+                        // A tab's parts sit where the tabs do: on the page, or in the box round them.
+                        panel.append(grid(tab.children, 1, { columns: 1, onPage: place.onPage, labels: place.labels }));
+                    }
+                    finally {
+                        sink = outer;
+                    }
+                };
+                const open = () => !form.node(tab.id).invisible && (show(tab.id), true);
                 button.addEventListener('click', () => show(tab.id));
                 if (!tabs.has(tab.id))
-                    tabs.set(tab.id, () => !form.node(tab.id).invisible && (show(tab.id), true));
+                    tabs.set(tab.id, open);
+                // The fields it holds, to mark it while one has a problem and to open it at one.
+                const fields = fieldsIn(tab.children);
+                if (scope.root)
+                    for (const name of fields)
+                        if (!problemTabs.has(name))
+                            problemTabs.set(name, open);
                 list.append(button);
-                return { tab, button, panel };
+                return { tab, button, panel, own, build, fields };
             });
             list.addEventListener('keydown', (event) => {
                 const shown = parts.filter((p) => !p.button.hidden);
@@ -347,33 +517,76 @@ export function mountViewer(host, options) {
                 show(next.tab.id);
                 next.button.focus();
             });
-            box.append(list, ...parts.map((p) => p.panel));
-            watch(() => {
-                box.hidden = form.node(node.id).invisible;
+            // Too long for its room, the strip scrolls; the tab chosen, however, comes into sight in it.
+            const strip = tabStrip(list, el);
+            cleanups.push(strip.destroy);
+            box.append(strip.element, ...parts.map((p) => p.panel));
+            let shownKey = '';
+            let revealed = '';
+            watch((state) => {
+                const tabsHidden = form.node(node.id).invisible;
+                setHidden(box, tabsHidden);
                 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;
+                const errors = form.getState().errors;
                 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;
+                    setHidden(p.button, !shown.includes(p));
+                    setAttr(p.button, 'aria-selected', String(selected));
+                    if (p.button.tabIndex !== (selected ? 0 : -1))
+                        p.button.tabIndex = selected ? 0 : -1;
+                    setAttr(p.button, 'data-problem', p.fields.some((name) => errors[name]) ? '' : null);
+                    setHidden(p.panel, !selected);
+                    // The tab shown: drawn if it is new, and brought up to date — it was left alone while out of sight.
+                    if (selected && !tabsHidden) {
+                        p.build();
+                        for (const update of p.own)
+                            update(state);
+                    }
+                }
+                // Measured only when it can have changed: the strip's tabs, or the one chosen.
+                const key = shown.map((p) => p.tab.id).join(' ');
+                if (key !== shownKey) {
+                    shownKey = key;
+                    strip.measure();
+                }
+                if (active !== revealed && list.clientWidth) {
+                    revealed = active;
+                    const chosen = parts.find((p) => p.tab.id === active);
+                    if (chosen)
+                        strip.reveal(chosen.button);
                 }
             });
             return box;
         }
+        /** The fields a tab holds, in its sections and tabs inside it; a saved form placed in it keeps its own. */
+        function fieldsIn(children) {
+            return children.flatMap((child) => child.type === 'field' ? [child.field]
+                : child.type === 'section' ? fieldsIn(child.children)
+                    : child.type === 'tabs' ? child.children.flatMap((tab) => fieldsIn(tab.children))
+                        : []);
+        }
         function item(node, place) {
+            return hiddenOn(node, partItem(node, place));
+        }
+        /** A part hidden at some widths of the form (`hideOn`), as a phone's: the stylesheet hides it there. */
+        function hiddenOn(node, element) {
+            if (node.hideOn?.length)
+                element.dataset['hideOn'] = node.hideOn.join(' ');
+            return element;
+        }
+        function partItem(node, place) {
             switch (node.type) {
                 case 'field':
                     return fieldItem(node, place.labels);
                 case 'button':
                     return buttonItem(node);
                 case 'text':
-                    return textItem(node);
+                    return textItem(node, place.inline);
                 case 'slot':
                     return slotItem(node);
                 case 'section':
@@ -520,9 +733,12 @@ export function mountViewer(host, options) {
         else
             locked = false;
         root.toggleAttribute('data-readonly', locked);
+        // Conditions read `editing`: parts for editing only, or reading only, follow.
+        form.setEditing(!locked);
         render(form.getState());
     });
     root.toggleAttribute('data-readonly', locked);
+    form.setEditing(!locked);
     updaters.push(() => {
         if (!editSwitch)
             return;
@@ -620,7 +836,15 @@ export function mountViewer(host, options) {
             draftText.textContent = fill(labels.draftFound, { time: new Date(state.draft.savedAt).toLocaleString() });
     });
     function focusFirstProblem() {
-        const invalid = root.querySelector('[aria-invalid="true"]');
+        // A problem in a tab out of sight, or not drawn yet: its tab shown first, the first such in the page's order.
+        const seen = [...root.querySelectorAll('[aria-invalid="true"]')].find((e) => !e.closest('.fd-tabpanel[hidden]'));
+        if (!seen) {
+            const errors = form.getState().errors;
+            const first = [...problemTabs.keys()].find((name) => errors[name]);
+            if (first)
+                problemTabs.get(first)?.();
+        }
+        const invalid = [...root.querySelectorAll('[aria-invalid="true"]')].find((e) => !e.closest('.fd-tabpanel[hidden]')) ?? null;
         if (!invalid)
             return;
         for (let folded = invalid.closest('.fd-section-folded'); folded; folded = folded.parentElement?.closest('.fd-section-folded') ?? null) {
@@ -655,6 +879,52 @@ export function mountViewer(host, options) {
         content.hidden = false;
         done.hidden = true;
     });
+    /** The record's name, as the last of its breadcrumbs says it: its sheet's title field, else the page's title; empty for a new one. */
+    function recordName() {
+        const state = form.getState();
+        if (state.recordId == null)
+            return '';
+        const field = page.layout.type === 'sheet' ? page.layout.title?.field : undefined;
+        const name = field ? displayValue(page.fields[field], state.values[field], state.values, locale) : '';
+        return name || page.title || '';
+    }
+    /** The bar over a record — its breadcrumbs, its gear menu, its pager — or null when it would hold nothing. */
+    function topBar(toolbar) {
+        if (page.data.kind !== 'record')
+            return null;
+        const bar = recordBar({
+            doc,
+            el,
+            form,
+            toolbar,
+            records: options.records,
+            breadcrumbs: options.breadcrumbs,
+            labels,
+            icons: options.icons,
+            uid,
+            fill,
+            withIcon,
+            press,
+            name: recordName,
+            render: renderNow,
+            async leave() {
+                if (!form.getState().dirty.length)
+                    return true;
+                const saved = await form.save();
+                if (!saved) {
+                    if (!form.getState().saveProblem)
+                        announce(checkText(form.getState()));
+                    focusFirstProblem();
+                }
+                return saved;
+            },
+        });
+        if (!bar)
+            return null;
+        updaters.push(bar.update);
+        cleanups.push(bar.destroy);
+        return bar.element;
+    }
     function pageHead() {
         if (!page.title && !page.description)
             return null;
@@ -666,8 +936,20 @@ export function mountViewer(host, options) {
         return head;
     }
     // ---- the four page layouts ---------------------------------------------------
+    /**
+     * A page's own buttons at its foot, as a wizard's, in place of its Save and
+     * Discard; null when it has none, or when a dialog round it draws them.
+     */
+    function pageFooter(footer) {
+        if (!footer?.length || options.showActions === false)
+            return null;
+        return el('div', { class: 'fd-actions fd-actions-end fd-page-footer' }, status, ...footer.map(buttonItem));
+    }
     function sectionsLayout(node) {
         const box = el('div', { class: 'fd-sections', 'data-node': node.id }, ...node.children.map((child) => item(child, top(true))));
+        const own = pageFooter(node.footer);
+        if (own)
+            return el('div', {}, box, own);
         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') {
@@ -786,7 +1068,8 @@ export function mountViewer(host, options) {
         // Save and Discard lead the header bar, or close the sheet when the page puts them at its foot.
         const atFoot = page.actionsPosition === 'bottom';
         const foot = el('div', { class: 'fd-actions fd-actions-end fd-sheet-foot' });
-        if (options.showActions === false)
+        const own = pageFooter(node.footer);
+        if (options.showActions === false || own)
             actions.append(...(node.buttons ?? []).map(buttonItem));
         else if (atFoot) {
             actions.append(...(node.buttons ?? []).map(buttonItem));
@@ -807,31 +1090,89 @@ export function mountViewer(host, options) {
         if (node.statusbar && !underTitle)
             header.append(statusbar(node.statusbar));
         const card = el('div', { class: 'fd-card' });
-        if (node.ribbon) {
-            const ribbon = el('div', { class: `fd-ribbon fd-tone-${node.ribbon.tone ?? 'muted'}`, 'data-node': node.ribbon.id }, node.ribbon.label);
-            hideWhen(ribbon, node.ribbon.id);
-            // The ribbon is clipped to the card's corner by its own frame, so the card itself never clips: lists open past it.
-            card.append(el('div', { class: 'fd-ribbon-frame' }, ribbon));
+        const ribbons = [...(node.ribbon ? [node.ribbon] : []), ...(node.ribbons ?? [])];
+        if (ribbons.length) {
+            // The ribbons are clipped to the card's corner by their own frame, so the card itself never clips: lists open past it.
+            const frame = el('div', { class: 'fd-ribbon-frame' });
+            const drawn = ribbons.map((ribbon) => {
+                const element = el('div', { class: `fd-ribbon fd-tone-${ribbon.tone ?? 'muted'}`, 'data-node': ribbon.id, title: ribbon.tooltip }, ribbon.label);
+                frame.append(element);
+                return { ribbon, element };
+            });
+            // One corner, one ribbon: the first whose condition holds; its words from a field when the field holds any.
+            updaters.push((state) => {
+                let shown = false;
+                for (const { ribbon, element } of drawn) {
+                    const show = !shown && !form.node(ribbon.id).invisible;
+                    shown ||= show;
+                    setHidden(element, !show);
+                    if (!show)
+                        continue;
+                    const from = ribbon.labelField ? displayValue(page.fields[ribbon.labelField], state.values[ribbon.labelField], state.values, locale) : '';
+                    setText(element, from || ribbon.label);
+                }
+            });
+            card.append(frame);
         }
         if (node.statButtons?.length) {
             const stats = el('div', { class: 'fd-stats' });
+            /** A field's value as the field shows it: money with its currency, a date, a count grouped. */
+            const shownValue = (name, values) => name && page.fields[name] ? displayValue(page.fields[name], values[name], values, locale) : '';
             for (const stat of node.statButtons) {
                 const value = el('span', { class: 'fd-stat-value' });
+                const label = el('span', { class: 'fd-stat-label' }, stat.label);
+                // A second value with words of its own: the two one over the other, each after its words.
+                const second = stat.secondField && stat.secondLabel !== undefined ? { value: el('span', { class: 'fd-stat-value' }), label: el('span', { class: 'fd-stat-label' }, stat.secondLabel) } : null;
                 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]));
+                const words = second
+                    ? el('span', { class: 'fd-stat-words fd-stat-pair' }, el('span', { class: 'fd-stat-row' }, label, value), el('span', { class: 'fd-stat-row' }, second.label, second.value))
+                    : el('span', { class: 'fd-stat-words' }, value, label);
+                // Its help, as Flectra's help=: its tooltip, and its description for a screen reader — never its name.
+                const helpId = stat.help ? uid(`${stat.id}-help`) : undefined;
+                const button = el('button', { type: 'button', class: 'fd-stat', 'data-node': stat.id, title: stat.help || undefined, 'aria-describedby': helpId }, ...(icon ? [icon, words] : [words]));
+                if (helpId)
+                    stats.append(el('span', { class: 'fd-sr-only', id: helpId }, stat.help));
                 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;
-                    value.textContent = count === null || count === undefined ? '' : String(count);
+                    const values = state.values;
+                    const unit = shownValue(stat.unitField, values) || stat.unit || '';
+                    const first = shownValue(stat.field, values);
+                    const other = shownValue(stat.secondField, values);
+                    if (second) {
+                        setText(value, first);
+                        setText(second.value, [other, unit].filter(Boolean).join(' '));
+                    }
+                    else
+                        setText(value, [[first, other].filter(Boolean).join(' / '), first || other ? unit : ''].filter(Boolean).join(' '));
+                    setText(label, shownValue(stat.labelField, values) || stat.label);
                 });
                 stats.append(button);
             }
+            // No empty row while every button is hidden, as with the badges.
+            updaters.push(() => {
+                stats.hidden = [...stats.querySelectorAll(':scope > .fd-stat')].every((stat) => stat.hidden);
+            });
             card.append(stats);
         }
         for (const alert of node.alerts ?? []) {
-            const box = el('div', { class: `fd-alert fd-tone-${alert.tone ?? 'info'}`, role: 'status', 'data-node': alert.id }, el('span', { class: 'fd-alert-message' }, alert.message));
+            // Its words with the values they name, or a field's words while it holds any; its buttons after them, as links unless styled.
+            const words = valueWords(doc, page.fields, alert.message, locale);
+            const message = el('span', { class: 'fd-alert-message' }, ...words.nodes);
+            let fromField = false;
+            const box = el('div', { class: `fd-alert fd-tone-${alert.tone ?? 'info'}`, role: 'status', 'data-node': alert.id }, message);
+            if (alert.buttons?.length)
+                box.append(el('span', { class: 'fd-alert-actions' }, ...alert.buttons.map((button) => buttonItem({ ...button, style: button.style ?? 'link' }))));
+            updaters.push((state) => {
+                words.update(state.values);
+                const from = alert.messageField ? state.values[alert.messageField] : null;
+                const said = typeof from === 'string' ? from.trim() : '';
+                if (said)
+                    setText(message, said);
+                else if (fromField)
+                    message.replaceChildren(...words.nodes);
+                fromField = !!said;
+            });
             if (alert.dismissible) {
                 // Closed, it stays closed while the page is open, whatever its condition does.
                 let dismissed = false;
@@ -863,9 +1204,26 @@ export function mountViewer(host, options) {
         }
         if (node.title) {
             const title = el('div', { class: 'fd-title' });
+            // Words over the title, as Flectra's "Product Name" over its h1, naming its box.
+            if (node.title.label)
+                title.append(el('label', { class: 'fd-title-label', for: uid('#title') }, node.title.label));
             if (node.title.above?.length)
                 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 }));
+            const name = fieldItem({ type: 'field', id: '#title', field: node.title.field, placeholder: node.title.placeholder, ...(node.title.placeholderWhen ? { placeholderWhen: node.title.placeholderWhen } : {}), ...(node.title.focus ? { focus: true } : {}) });
+            // Fields on the title's line, before and after it: a priority star, a state's dot (Flectra's <h1>).
+            const before = node.title.before ?? [];
+            const after = node.title.after ?? [];
+            if (before.length || after.length) {
+                name.classList.add('fd-title-name');
+                const side = (part) => {
+                    const item = fieldItem(part);
+                    item.classList.add('fd-title-side');
+                    return item;
+                };
+                title.append(el('div', { class: 'fd-title-line' }, ...before.map(side), name, ...after.map(side)));
+            }
+            else
+                title.append(name);
             if (node.title.subtitleField)
                 title.append(fieldItem({ type: 'field', id: '#subtitle', field: node.title.subtitleField }));
             if (node.title.below?.length)
@@ -881,6 +1239,8 @@ 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, 1, top(false)));
+        if (own)
+            card.append(own);
         if (atFoot && options.showActions !== false) {
             card.append(foot);
             updaters.push((state) => {
@@ -888,11 +1248,22 @@ export function mountViewer(host, options) {
             });
         }
         const layout = el('div', { class: 'fd-sheet-layout' }, card);
+        if (node.attachmentPreview) {
+            // Beside the sheet on a wide form, the side panel then under the sheet; under the sheet on a narrow one.
+            const preview = attachmentPreview({ doc, el, form, page, node: node.attachmentPreview, dataSource: options.dataSource, labels, fill });
+            layout.classList.add('fd-has-preview');
+            layout.append(preview.element);
+            updaters.push(preview.update);
+            cleanups.push(preview.destroy);
+        }
         if (node.sidePanel) {
             layout.classList.add('fd-has-side');
+            if (node.sidePanelBeside)
+                layout.setAttribute('data-side-beside', node.sidePanelBeside);
             layout.append(el('aside', { class: 'fd-side' }, slotItem(node.sidePanel)));
         }
-        pageBox.append(header, layout);
+        const bar = topBar(node.toolbar);
+        pageBox.append(...(bar ? [bar] : []), header, layout);
         return pageBox;
     }
     /** The sheet header's statusbar: the same widget a form can place anywhere. */
@@ -901,9 +1272,18 @@ export function mountViewer(host, options) {
         const barOptions = { clickable: config.clickable === true };
         if (config.visibleStates)
             barOptions['visibleStates'] = config.visibleStates;
+        for (const key of ['durationsField', 'fold', 'saves'])
+            if (config[key] !== undefined)
+                barOptions[key] = config[key];
         const node = { type: 'field', id: '#statusbar', field: config.field, widget: 'statusbar', options: barOptions };
         const widget = createWidget({ form, name: config.field, field: def, node, id: uid('statusbar'), document: doc, labels: widgetLabels, preferences, locale, dialogs }, options.widgets);
-        updaters.push((state) => widget.update({ value: state.values[config.field], values: state.values, readonly: form.node('#statusbar').readonly || locked, required: false, invalid: false }));
+        if (widget.destroy)
+            cleanups.push(() => widget.destroy?.());
+        updaters.push((state) => {
+            // Hidden while its own condition holds, or from people outside its roles.
+            setHidden(widget.element, form.node('#statusbar').invisible);
+            widget.update({ value: state.values[config.field], values: state.values, readonly: form.node('#statusbar').readonly || locked, required: false, invalid: false });
+        });
         return widget.element;
     }
     let wizardForward = null;
@@ -932,6 +1312,7 @@ export function mountViewer(host, options) {
             icons: options.icons,
             preferences,
             onOpenRecord: options.onOpenRecord,
+            ...(options.listFilter ? { fixedFilter: options.listFilter } : {}),
         });
         cleanups.push(list.destroy);
         body = list.element;
@@ -939,7 +1320,9 @@ export function mountViewer(host, options) {
     else
         body = sectionsLayout(layout);
     const head = layout.type === 'sheet' ? null : pageHead();
-    content.append(...(head ? [head] : []), banner, draft, body);
+    // A record of sections or tabs has the bar the app fills — its breadcrumbs and pager — over its title.
+    const bar = layout.type === 'sections' || layout.type === 'tabs' ? topBar(undefined) : null;
+    content.append(...(bar ? [bar] : []), ...(head ? [head] : []), banner, draft, body);
     root.append(content, done, announcer);
     // The status leaves its place beside Save when the page wants it in a corner or across the top.
     if (options.saveStatus === 'toast') {
@@ -1014,6 +1397,46 @@ export function mountViewer(host, options) {
         event.preventDefault();
         nextField(from)?.focus();
     });
+    // ---- a button's key, with Alt -------------------------------------------------
+    /**
+     * Whether a key pressed with Alt is this form's: pressed in it (not in a
+     * form inside it, such as a dialog's), or — pressed outside any form — this
+     * is the first form on the page, or in the question or dialog on top of it.
+     */
+    function hotkeysHere(target) {
+        const inner = target instanceof Element ? target.closest('.fd-form') : null;
+        if (inner)
+            return inner === root && !root.querySelector(':scope > .fd-dialog-backdrop');
+        const modals = [...doc.querySelectorAll('[aria-modal="true"]')].filter((modal) => !modal.closest('[hidden]'));
+        const top = modals[modals.length - 1];
+        return (top ?? doc).querySelector('.fd-form') === root;
+    }
+    const onHotkey = (event) => {
+        if (event.key === 'Alt') {
+            if (hotkeysHere(event.target))
+                root.setAttribute('data-hotkeys', '');
+            return;
+        }
+        const key = hotkeyOf(event);
+        if (!key || !hotkeysHere(event.target))
+            return;
+        const button = [...root.querySelectorAll(`button[data-hotkey="${key}"]`)].find((b) => b.closest('.fd-form') === root && !b.closest('[hidden]') && !b.disabled && !b.hasAttribute('aria-busy'));
+        if (!button)
+            return;
+        event.preventDefault();
+        root.removeAttribute('data-hotkeys');
+        button.click();
+    };
+    const offHotkeys = () => root.removeAttribute('data-hotkeys');
+    const altUp = (event) => event.key === 'Alt' && offHotkeys();
+    doc.addEventListener('keydown', onHotkey);
+    doc.addEventListener('keyup', altUp);
+    doc.defaultView?.addEventListener('blur', offHotkeys);
+    cleanups.push(() => {
+        doc.removeEventListener('keydown', onHotkey);
+        doc.removeEventListener('keyup', altUp);
+        doc.defaultView?.removeEventListener('blur', offHotkeys);
+    });
     // ---- confirmation dialog -----------------------------------------------------
     /** A question with Cancel and OK, or with `withCancel` false a notice with OK alone. */
     function dialogConfirm(message, withCancel = true) {
@@ -1063,6 +1486,24 @@ export function mountViewer(host, options) {
     }));
     render(form.getState());
     mounted = true;
+    // As the record opens, its focused field takes the focus — the first shown — unless the person is busy elsewhere:
+    // only while nothing has the focus, or, the first time, while it is in this form (a dialog's first box).
+    let opened = false;
+    if (focusers.length) {
+        cleanups.push(form.on('open', () => {
+            const first = !opened;
+            opened = true;
+            queueMicrotask(() => {
+                if (gone || !root.isConnected || root.closest('[hidden]') || (typeof root.checkVisibility === 'function' && !root.checkVisibility()))
+                    return;
+                const active = doc.activeElement;
+                const free = !active || active === doc.body || active === doc.documentElement;
+                if (!free && !(first && root.contains(active)))
+                    return;
+                focusers.find((one) => !one.wrapper.closest('[hidden]'))?.focus();
+            });
+        }));
+    }
     if (form.getState().status === 'idle')
         void form.load();
     return {
@@ -1086,6 +1527,7 @@ export function mountViewer(host, options) {
         setReadonly(readonly) {
             locked = readonly;
             root.toggleAttribute('data-readonly', locked);
+            form.setEditing(!locked);
             render(form.getState());
         },
         isReadonly: () => locked,