@fieldia/viewer 0.18.0 → 0.19.1

package/src/lib/viewer.mjs

@@ -1,5 +1,5 @@
 import { createForm, checkPage, isRightToLeft, localizePage, translatePage, wideColumns, MESSAGES, } from '@fieldia/core';
-import { browserPreferences, createWidget, displayValue, drawIcon, installStyles, readsAsText, readText, WIDGET_LABELS } from '@fieldia/widgets';
+import { browserPreferences, createWidget, displayValue, drawIcon, installStyles, readsAsText, readText, wearsQuiet, WIDGET_LABELS } from '@fieldia/widgets';
 import { findPage, pageDialogs } from './related.mjs';
 import { listView } from './list.mjs';
 import { applyLook, skinFor, wearTokens } from './look.mjs';
@@ -111,7 +111,7 @@ export function mountViewer(host, given) {
         return icon ? [icon, words] : [words];
     }
     const theme = options.theme ?? page.look?.theme;
-    const root = el('form', { class: 'fd-form', novalidate: '', 'data-fd-skin': skinFor(options.skin, theme), dir, lang: tag, 'data-max-width': page.maxWidth });
+    const root = el('form', { class: 'fd-form', novalidate: '', 'data-fd-skin': skinFor(options.skin ?? page.look?.skin, theme), dir, lang: tag, 'data-max-width': page.maxWidth });
     applyLook(root, theme ? { ...page.look, theme } : page.look);
     wearTokens(root, options.tokens);
     const confirm = options.confirm ?? dialogConfirm;
@@ -146,6 +146,8 @@ export function mountViewer(host, given) {
     // ---- the parts -------------------------------------------------------
     /** The fields that take the focus as the record opens, in the order they are drawn. */
     const focusers = [];
+    /** Each field's face, put on again when the form changes skin: quiet, or in its box. */
+    const faces = [];
     /** 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. */
@@ -169,8 +171,11 @@ export function mountViewer(host, given) {
         const uid = (id) => ownUid(scope.prefix + id);
         /** A part's updater, handed the state of the part's own form. */
         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) {
+        /**
+         * A field with its label, help and messages. `place` is where labels sit where it is put; the title's own fields take none.
+         * `around` says what the groups round it say of the quiet look: quiet or boxed, and why their fields are read-only.
+         */
+        function fieldItem(node, place, around = {}) {
             const def = page.fields[node.field];
             const id = uid(node.id);
             const labelsAt = labelPlace(node, def.type, place);
@@ -196,6 +201,39 @@ export function mountViewer(host, given) {
             // 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;
+            // The quiet look: its own word, else its group's, else the form's skin. In a quiet place its label is quiet; its value
+            // wears the look (data-quiet) unless its widget keeps its own face.
+            const quietOwn = node.quiet ?? around.quiet;
+            const wears = wearsQuiet(def, node);
+            const quietPlace = () => quietOwn ?? root.getAttribute('data-fd-skin') === 'quiet';
+            // Empty and quiet, it says what to add, unless the page gives it words of its own: "Add story points", or for a
+            // question "Your answer". A field of several boxes, each with its own label (an address), says it in none of them.
+            const ownWords = !!node.placeholder || labelsAt === 'hidden' || def.type === 'json' || def.type === 'properties';
+            const hint = quietHint(labelText, locale, labels);
+            const restWords = () => (!ownWords && wrapper.hasAttribute('data-quiet') ? hint : drawnPlaceholder);
+            // Where no box can hold a placeholder (a choice's blank, a state's words), the page's own words come first.
+            const blankWords = node.placeholder || (labelsAt === 'hidden' ? labelText : hint);
+            const quietSelect = widget.element instanceof HTMLSelectElement ? widget.element.querySelector(':scope > option[value=""]') : null;
+            const richText = widget.element.matches('.fd-richtext') ? widget.element : widget.element.querySelector(':scope > .fd-richtext');
+            const stateWords = widget.element.querySelector(':scope > .fd-dot-label');
+            const face = () => {
+                const place = quietPlace();
+                const quiet = wears && place;
+                wrapper.toggleAttribute('data-in-quiet', place);
+                wrapper.toggleAttribute('data-quiet', quiet);
+                if (textBox && !chosenPlaceholder)
+                    setAttr(textBox, 'placeholder', restWords());
+                if (quietSelect)
+                    quietSelect.textContent = quiet ? blankWords : '';
+                if (richText && !node.placeholder) {
+                    setAttr(richText, 'data-placeholder', quiet ? hint : null);
+                    setAttr(richText, 'aria-placeholder', quiet ? hint : null);
+                }
+                if (stateWords)
+                    setAttr(stateWords, 'data-hint', quiet ? blankWords : null);
+            };
+            faces.push(face);
+            face();
             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
@@ -205,7 +243,7 @@ export function mountViewer(host, given) {
                 named?.setAttribute('aria-labelledby', label.id);
                 // Not a press on its (?) or the help bubble beside it: they show the help, and must not open a picker's list.
                 label.addEventListener('click', (event) => {
-                    if (!event.target.closest?.('.fd-help-tip-wrap'))
+                    if (!event.target.closest?.('.fd-help-tip-wrap, .fd-lock-wrap'))
                         widget.focus();
                 });
             }
@@ -222,6 +260,33 @@ export function mountViewer(host, given) {
                 label.append(tip.element);
                 label.dir = 'auto';
             }
+            // A rule keeping it read-only: a lock by its label (after the box when the label is out of sight) in the quiet look,
+            // and in any skin when the page says why — why, it says in a bubble, as the (?) does, pointed at or focused. Made
+            // the first time it is needed: a field never locked has none.
+            const reason = node.readonlyReason ?? around.reason;
+            // Read-only by its nature — worked out from others, or always read-only where the page puts it — a value is shown,
+            // not locked: it has a lock only when the page says why.
+            const fixed = node.readonly === true || def.readonly === true || def.compute !== undefined;
+            let lock = null;
+            let lockMark = null;
+            let lockedNow = false;
+            const lockFor = () => {
+                if (lockMark)
+                    return lockMark;
+                const icon = drawIcon(doc, 'lock', options.icons) ?? '';
+                lock = reason ? bubbleTip(`${id}-lock`, reason, fill(labels.locked, { label: labelText }), 'fd-lock', icon) : null;
+                lockMark = lock?.element ?? el('span', { class: 'fd-lock-wrap' }, el('span', { class: 'fd-lock', 'aria-hidden': 'true' }, icon));
+                if (labelsAt === 'hidden')
+                    widget.element.after(lockMark);
+                else
+                    label.insertBefore(lockMark, tip && labelsAt !== 'after' ? tip.element : null);
+                return lockMark;
+            };
+            // Pointing at a locked quiet value, or focusing it, says why too.
+            const point = (on) => lock?.point(on && lockedNow && wrapper.hasAttribute('data-in-quiet'));
+            if (reason)
+                for (const [event, on] of [['mouseenter', true], ['mouseleave', false], ['focusin', true], ['focusout', false]])
+                    widget.element.addEventListener(event, () => point(on));
             // 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.
@@ -231,6 +296,9 @@ export function mountViewer(host, given) {
             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 (asText && reason)
+                for (const [event, on] of [['mouseenter', true], ['mouseleave', false]])
+                    asText.element.addEventListener(event, () => point(on));
             if (widget.destroy)
                 cleanups.push(() => widget.destroy?.());
             // An answer rule's warning waits until the person leaves the field: no advice
@@ -246,6 +314,22 @@ export function mountViewer(host, given) {
                 // (a deleted line's button), and that redraw must finish first.
                 queueMicrotask(() => update(form.getState()));
             });
+            // Quiet, Escape puts back the value the field had as it was entered — once its own list or calendar, if open, has
+            // taken the key — and only then is it left for the dialog round it. Leaving keeps the change, for Save.
+            let entered;
+            wrapper.addEventListener('focusin', (event) => {
+                if (!wrapper.contains(event.relatedTarget))
+                    entered = form.getState().values[node.field];
+            });
+            wrapper.addEventListener('keydown', (event) => {
+                if (event.key !== 'Escape' || event.defaultPrevented || !wrapper.hasAttribute('data-quiet'))
+                    return;
+                if (JSON.stringify(form.getState().values[node.field] ?? null) === JSON.stringify(entered ?? null))
+                    return;
+                event.preventDefault();
+                event.stopPropagation();
+                form.setValue(node.field, (entered ?? null));
+            });
             const toned = node.tones !== undefined || node.bold !== undefined;
             const update = (state) => {
                 const shown = form.node(node.id);
@@ -258,7 +342,7 @@ export function mountViewer(host, given) {
                     wrapper.classList.toggle('fd-value-bold', look.bold);
                 }
                 if (chosenPlaceholder)
-                    setAttr(chosenPlaceholder, 'placeholder', form.placeholder(node.id) ?? drawnPlaceholder);
+                    setAttr(chosenPlaceholder, 'placeholder', form.placeholder(node.id) ?? restWords());
                 const message = state.errors[node.field];
                 setHidden(error, !message);
                 setText(error, message ?? '');
@@ -277,6 +361,16 @@ export function mountViewer(host, given) {
                     mark.toggleAttribute('hidden', !valid);
                 }
                 const readonly = shown.readonly || locked || scope.locked();
+                // Locked by a rule, not by the whole form being read: its lock shows, in the quiet look or with its reason, and its words are muted.
+                const quiet = wrapper.hasAttribute('data-quiet');
+                lockedNow = readonly && !locked;
+                const showsLock = lockedNow && (!!reason || (wrapper.hasAttribute('data-in-quiet') && !fixed));
+                if (showsLock || lockMark)
+                    setHidden(lockFor(), !showsLock);
+                if (!lockedNow)
+                    point(false);
+                setAttr(wrapper, 'data-locked', quiet && showsLock ? '' : null);
+                setAttr(wrapper, 'data-empty', quiet && isBlank(state.values[node.field]) ? '' : null);
                 if (asText) {
                     setHidden(widget.element, readonly);
                     setHidden(asText.element, !readonly);
@@ -290,7 +384,7 @@ export function mountViewer(host, given) {
                     readonly,
                     required: shown.required,
                     invalid: !!message,
-                    describedBy: [help?.id ?? tip?.bubble.id, message ? error.id : undefined, warned ? warning.id : undefined].filter(Boolean).join(' ') || undefined,
+                    describedBy: [help?.id ?? tip?.bubble.id, lock && lockedNow ? lock.bubble.id : undefined, message ? error.id : undefined, warned ? warning.id : undefined].filter(Boolean).join(' ') || undefined,
                 });
             };
             watch(update);
@@ -298,8 +392,18 @@ export function mountViewer(host, given) {
         }
         /** 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) {
+            return bubbleTip(bubbleId, text, name, 'fd-help-tip', '?');
+        }
+        /**
+         * A small button with words in a bubble — a field's help behind its (?), why it is locked behind its lock — shown
+         * on hover, on focus, or kept open by a press, and gone with Escape. `point` shows it from elsewhere: its value pointed at.
+         */
+        function bubbleTip(bubbleId, text, name, kind, face) {
             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 }, '?');
+            const button = el('button', { type: 'button', class: kind, 'aria-label': name, 'aria-expanded': 'false', 'aria-controls': bubbleId }, face);
+            // A lock's reason is said as it is reached; the help waits to be asked for.
+            if (kind === 'fd-lock')
+                button.setAttribute('aria-describedby', bubbleId);
             let kept = false;
             const show = (open) => {
                 bubble.hidden = !open;
@@ -324,7 +428,7 @@ export function mountViewer(host, given) {
                 kept = false;
                 show(false);
             });
-            return { element: el('span', { class: 'fd-help-tip-wrap' }, button, bubble), bubble };
+            return { element: el('span', { class: kind === 'fd-lock' ? 'fd-lock-wrap' : 'fd-help-tip-wrap' }, button, bubble), bubble, point: (on) => show(on || kept) };
         }
         /** A bubble hangs from its (?): near the edge of a phone's screen it runs past it, so it is moved back in. */
         function keepOnScreen(bubble) {
@@ -423,7 +527,7 @@ export function mountViewer(host, given) {
             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' }, ...onelineRuns(node.children).map((run) => {
-                const parts = run.map((child) => item(child, { columns: 1, onPage: false, inline: true }));
+                const parts = run.map((child) => item(child, { columns: 1, onPage: false, inline: true, quiet: node.quiet ?? place.quiet, reason: node.readonlyReason ?? place.reason }));
                 return parts.length === 1 ? parts[0] : el('span', { class: 'fd-oneline-pair' }, ...parts);
             }));
             if (node.title) {
@@ -433,6 +537,10 @@ export function mountViewer(host, given) {
             }
             line.append(row);
             hideWhen(line, node.id);
+            // In a quiet place the line's label is quiet, as its fields' are.
+            const face = () => line.toggleAttribute('data-in-quiet', node.quiet ?? place.quiet ?? root.getAttribute('data-fd-skin') === 'quiet');
+            faces.push(face);
+            face();
             return line;
         }
         function sectionItem(node, place) {
@@ -514,7 +622,7 @@ export function mountViewer(host, given) {
                     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 }));
+                        panel.append(grid(tab.children, 1, { columns: 1, onPage: place.onPage, labels: place.labels, quiet: place.quiet, reason: place.reason }));
                     }
                     finally {
                         sink = outer;
@@ -610,7 +718,7 @@ export function mountViewer(host, given) {
         function partItem(node, place) {
             switch (node.type) {
                 case 'field':
-                    return fieldItem(node, place.labels);
+                    return fieldItem(node, place.labels, place);
                 case 'button':
                     return buttonItem(node);
                 case 'text':
@@ -731,7 +839,7 @@ export function mountViewer(host, given) {
                 });
                 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 }));
+                note.replaceWith(own.grid(layout.type === 'tabs' ? [layout] : layout.children, 1, { columns: 1, onPage: false, labels: place.labels, quiet: place.quiet }));
                 box.removeAttribute('aria-busy');
                 cleanups.push(inner.subscribe(renderNow));
                 if (mounted)
@@ -1549,6 +1657,13 @@ export function mountViewer(host, given) {
             actionHost.say(result.message ?? '', result.reason === 'app' ? 'danger' : 'warning');
     }));
     render(form.getState());
+    /** The form in another skin: each field's face put on again, and drawn again from the state. */
+    function refaced() {
+        for (const face of faces)
+            face();
+        if (mounted)
+            renderNow();
+    }
     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).
@@ -1575,13 +1690,15 @@ export function mountViewer(host, given) {
         element: root,
         setSkin(skin) {
             root.setAttribute('data-fd-skin', skin);
+            refaced();
         },
         setTheme(next) {
             if (next)
                 root.setAttribute('data-fd-theme', next);
             else
                 root.removeAttribute('data-fd-theme');
-            root.setAttribute('data-fd-skin', skinFor(options.skin, next ?? undefined));
+            root.setAttribute('data-fd-skin', skinFor(options.skin ?? page.look?.skin, next ?? undefined));
+            refaced();
         },
         setTokens(next) {
             options.tokens = next ?? undefined;
@@ -1626,6 +1743,22 @@ export function mountViewer(host, given) {
 }
 /** 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';
+/** Nothing in it: no value, empty words, nothing picked. */
+const isBlank = (value) => value === null || value === undefined || value === '' || (Array.isArray(value) && !value.length);
+/**
+ * A label inside a sentence, as "Add story points" says it: in English and French its first letter small, unless the
+ * word is a name such as "VAT"; German nouns, and Arabic, as written.
+ */
+function inSentence(label, locale) {
+    return (locale === 'en' || locale === 'fr') && /^\p{Lu}\p{Ll}/u.test(label) ? label[0].toLocaleLowerCase(locale) + label.slice(1) : label;
+}
+/**
+ * What an empty field in the quiet look says, by its label, in the viewer's
+ * words for `locale`: "Add story points", or for a question "Your answer".
+ */
+export function quietHint(label, locale, labels = VIEWER_LABELS[locale]) {
+    return /[?؟]\s*$/.test(label) ? labels.quietAnswer : labels.quietHint.replace('{label}', inSentence(label, locale));
+}
 /** 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']);
 /**