@fieldia/viewer 0.9.1 → 0.10.0

package/src/lib/viewer.mjs

@@ -1,8 +1,12 @@
-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 { 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 { ownLocale, VIEWER_LABELS } from './labels.mjs';
+import { keepTabIn } from './focus-trap.mjs';
 export { VIEWER_LABELS, DEFAULT_LABELS } from './labels.mjs';
 let mounts = 0;
 /**
@@ -17,15 +21,18 @@ 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;
+    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 };
     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 = [];
@@ -40,21 +47,30 @@ 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;
     // ---- the parts -------------------------------------------------------
-    function fieldItem(node) {
+    /** 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 wrapper = el('div', { class: 'fd-field', 'data-node': node.id, 'data-field': node.field, 'data-type': def.type });
+        const labelsAt = labelPlace(node, def.type, labels);
+        const wrapper = el('div', { class: 'fd-field', 'data-node': node.id, 'data-field': node.field, 'data-type': def.type, 'data-labels': labelsAt });
         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);
+        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) {
@@ -62,33 +78,56 @@ 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);
+        // 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.
-            if (widget.element.getAttribute('role'))
-                widget.element.setAttribute('aria-labelledby', label.id);
+            // 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());
         }
         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);
+        // 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?.());
-        updaters.push((state) => {
+        // 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()));
+        });
+        const update = (state) => {
             const shown = form.node(node.id);
-            wrapper.hidden = shown.invisible;
+            setHidden(wrapper, 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;
+            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);
@@ -102,18 +141,18 @@ export function mountViewer(host, options) {
                 readonly: shown.readonly || locked,
                 required: shown.required,
                 invalid: !!message,
-                describedBy: [help?.id, message ? error.id : undefined].filter(Boolean).join(' ') || undefined,
+                describedBy: [help?.id, message ? error.id : undefined, warned ? warning.id : undefined].filter(Boolean).join(' ') || undefined,
             });
-        });
+        };
+        updaters.push(update);
         return wrapper;
     }
     function hideWhen(element, id) {
-        updaters.push(() => {
-            element.hidden = form.node(id).invisible;
-        });
+        updaters.push(() => 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);
         button.addEventListener('click', async () => {
             if (node.confirm && !(await confirm(node.confirm)))
                 return;
@@ -125,6 +164,7 @@ export function mountViewer(host, options) {
     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;
     }
@@ -136,28 +176,52 @@ export function mountViewer(host, options) {
         hideWhen(element, node.id);
         return element;
     }
-    function grid(children, columns = 1) {
+    /** 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));
+    }
+    /**
+     * 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' });
-        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));
+        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(item));
+        box.append(...children.map((child) => item(child, place)));
         return box;
     }
+    /** 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 });
     /** 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 });
+    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, node.columns);
+        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));
@@ -184,8 +248,9 @@ export function mountViewer(host, options) {
         hideWhen(section, node.id);
         return section;
     }
-    function tabsItem(node) {
+    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.
@@ -195,7 +260,8 @@ 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));
-            const panel = el('div', { class: 'fd-tabpanel', role: 'tabpanel', id: panelId, 'aria-labelledby': tabId }, grid(tab.children));
+            // 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', () => {
                 picked = active = tab.id;
                 render(form.getState());
@@ -235,10 +301,10 @@ export function mountViewer(host, options) {
         });
         return box;
     }
-    function item(node) {
+    function item(node, place) {
         switch (node.type) {
             case 'field':
-                return fieldItem(node);
+                return fieldItem(node, place.labels);
             case 'button':
                 return buttonItem(node);
             case 'text':
@@ -246,11 +312,35 @@ export function mountViewer(host, options) {
             case 'slot':
                 return slotItem(node);
             case 'section':
-                return sectionItem(node);
+                return sectionItem(node, place);
             case 'tabs':
-                return tabsItem(node);
+                return tabsItem(node, place);
+            case 'divider':
+            case 'spacer':
+            case 'image':
+                return blockItem(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;
+    }
     // ---- shared chrome ----------------------------------------------------------
     /** The whole form locked: every field read-only, no Save; buttons still run. */
     let locked = options.readonly === true;
@@ -310,8 +400,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 +448,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 +500,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 +510,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 +553,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 };
         });
@@ -604,12 +697,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 +713,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) => {
@@ -763,8 +856,14 @@ 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));
@@ -772,6 +871,8 @@ export function mountViewer(host, options) {
             backdrop.addEventListener('keydown', (event) => {
                 if (event.key === 'Escape')
                     close(false);
+                else
+                    keepTabIn(dialog, event);
             });
             root.append(backdrop);
             ok.focus();
@@ -821,6 +922,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