@optionfactory/fml 9.0.0-rc2 → 9.0.0-rc4

package/dist/ful.mjs

@@ -233,6 +233,48 @@ class Claims {
     }
 }
 
+/**
+ * The protocol by which content standing inside a field becomes part of the
+ * accessible description of that field's control.
+ *
+ * A field owns its control's `aria-describedby`: it is the only thing that
+ * knows which element the description belongs on, and it already writes the
+ * entry for its own error region. Content the author slotted into the field
+ * cannot write that attribute itself without becoming a second owner of it, and
+ * it cannot be wired by the field either, because a slotted custom element
+ * renders after the field has mounted and has nothing to point at when the
+ * field looks.
+ *
+ * So the content asks, once it has something to offer. `describable(el)`
+ * answers the nearest ancestor that accepts a description, and the caller hands
+ * its element to that ancestor's `describedBy`, which answers whether it was
+ * taken. Nothing here names a field or a tooltip: the relation is expressed as
+ * a capability, so the two ends need not import each other, which matters
+ * because the library's own arrow runs from the forms to the disclosures.
+ *
+ * The lookup lives here rather than at its one call site so the protocol has a
+ * name, a place to be documented and a single definition to change.
+ */
+
+/**
+ * @typedef {{ describedBy(el: HTMLElement): boolean }} Describable
+ */
+
+/**
+ * The nearest ancestor of `el` that accepts elements into the description of
+ * whatever it considers its control, or null when nothing in the ancestry does.
+ * @param {Element} el
+ * @returns {(Element & Describable) | null}
+ */
+const describable = (el) => {
+    for (let at = el.parentElement; at; at = at.parentElement) {
+        if (typeof (/** @type {any} */ (at).describedBy) === 'function') {
+            return /** @type {any} */ (at);
+        }
+    }
+    return null;
+};
+
 /**
  * Sleeping, debouncing and throttling. Debounce and throttle both return the
  * wrapped function together with a cancel function.
@@ -627,6 +669,9 @@ class Field extends ParsedElement {
     /** the role the element internals carry, 'presentation' unless the control is its own */
     static ROLE = 'presentation';
     #control;
+    #described;
+    #descriptions = [];
+    #errorId = null;
     #fieldError;
     #claims;
     #announces;
@@ -678,15 +723,18 @@ class Field extends ParsedElement {
                 true,
             );
         }
-        //the error region describes the control, or the host where there is no
+        //the description lands on the control, or on the host where there is no
         //single control to describe (a radio group's legend names its fieldset)
+        this.#described = described ?? control;
         if (error) {
-            (described ?? control).ariaDescribedByElements = [error];
+            //named for what it is, the generic id being for whoever brings no name
+            error.id = error.id || Attributes.uid('ful-field-error');
+            this.#errorId = error.id;
         }
+        //anything handed over before the field had a target lands here
+        this.#describe();
         if (label) {
-            control.ariaLabelledByElements = [label];
-            //a label that does not natively target the control still focuses it
-            label.addEventListener('click', () => this.focus());
+            Field.#name(this, label, control);
         }
         //the platform's implicit submission, stood in for where the field's own
         //protocol took it away: the inner controls carry form="", so Enter in one
@@ -719,6 +767,61 @@ class Field extends ParsedElement {
     static #submitsOnEnter(el) {
         return el instanceof HTMLInputElement && !['file', 'button', 'submit', 'reset', 'image'].includes(el.type);
     }
+    /**
+     * Adds an element to the accessible description of the field's control and
+     * answers whether the field took it.
+     *
+     * A field takes one whenever it is offered, before its own render as
+     * readily as after: content slotted into a field is a custom element of its
+     * own and may upgrade on either side of the field it stands in, which
+     * happens in both directions in practice, a tooltip beating an async select
+     * to its render while losing to a plain input. A description handed over
+     * early waits here and is written the moment the field has somewhere to
+     * write it, so the caller never has to know the order.
+     *
+     * The reference lands on the element handed over rather than on a wrapper
+     * around it: a hidden element is included in a description only where it is
+     * named directly, and content that reaches the description through a
+     * wrapper is skipped while it is hidden. A popover closed until someone
+     * opens it is exactly that, so the caller passes the popover itself.
+     *
+     * An attribute rather than `ariaDescribedByElements`: the property reflects
+     * to nothing, so the description would live in the accessibility tree alone
+     * and vanish entirely on a browser without aria element reflection.
+     *
+     * This is the field's half of the description protocol; `describable` in
+     * `ful/descriptions.mjs` is the half the content uses to find the field.
+     * @param {HTMLElement} el
+     * @returns {boolean}
+     */
+    describedBy(el) {
+        if (!el) {
+            return false;
+        }
+        if (!el.id) {
+            el.id = Attributes.uid('ful-described');
+        }
+        if (!this.#descriptions.includes(el.id)) {
+            this.#descriptions.push(el.id);
+        }
+        this.#describe();
+        return true;
+    }
+    /**
+     * Writes the description the field has collected, the error region last:
+     * the standing explanations are what the field always says, the problem is
+     * the news. The field owns the attribute outright rather than appending to
+     * whatever is there, so the order does not depend on who arrived when.
+     */
+    #describe() {
+        if (!this.#described) {
+            return;
+        }
+        const ids = [...this.#descriptions, this.#errorId].filter((id) => id);
+        if (ids.length) {
+            this.#described.setAttribute('aria-describedby', ids.join(' '));
+        }
+    }
     focus(options) {
         this.#control?.focus(options);
     }
@@ -775,6 +878,49 @@ class Field extends ParsedElement {
             }),
         );
     }
+    /** The html elements a label's `for` may point at, `input[type=hidden]` excepted. */
+    static #LABELABLE = new Set(['BUTTON', 'INPUT', 'METER', 'OUTPUT', 'PROGRESS', 'SELECT', 'TEXTAREA']);
+    /**
+     * Names the control from the field's label, natively wherever the platform
+     * allows it.
+     *
+     * `for` and `id` are the form the dom itself carries, so the association is
+     * there for anything reading the markup rather than the accessibility tree:
+     * an audit tool, the browser's autofill, a translation pass. It also makes
+     * the label's click reach the control the way it does in a plain form, which
+     * is focus for a text control and activation for a checkbox, so the field
+     * needs no handler of its own.
+     *
+     * A control the platform will not let a label target, a composite carrying
+     * `role="radiogroup"` among them, takes `aria-labelledby` instead. That is an
+     * attribute too, so the association is equally visible; what it does not carry
+     * is the label's click, which is why the handler stays on that path only.
+     *
+     * Neither branch uses `ariaLabelledByElements`. The property reflects to no
+     * attribute, so the name lived in the accessibility tree alone: nothing reading
+     * the dom saw it, and on a browser without aria element reflection the
+     * assignment is a silent expando and the field has no name at all.
+     * @param {any} field
+     * @param {HTMLElement} label
+     * @param {any} control
+     */
+    static #name(field, label, control) {
+        const labelable =
+            Field.#LABELABLE.has(control.tagName) && control.getAttribute('type') !== 'hidden';
+        if (!labelable) {
+            if (!label.id) {
+                label.id = Attributes.uid('ful-label');
+            }
+            control.setAttribute('aria-labelledby', label.id);
+            //aria-labelledby carries the name but not the label's click
+            label.addEventListener('click', () => field.focus());
+            return;
+        }
+        if (!control.id) {
+            control.id = Attributes.uid('ful-control');
+        }
+        label.setAttribute('for', control.id);
+    }
     /**
      * Whether the field's chrome should answer a gesture. Badges, dropzones,
      * menus and labels are not form controls, so their handlers must ask the
@@ -912,8 +1058,9 @@ class Field extends ParsedElement {
      *   three claims reach it
      * - `error` is the field's live region
      * - `label`, when given, names the control and focuses it on click
-     * - `described` moves the error's description off the control and onto
-     *   another element, the host where no single control can carry it
+     * - `described` moves the description off the control and onto another
+     *   element, the host where no single control can carry it: the error
+     *   region and anything `describedBy` is later handed both land there
      * - `claims` moves the three claims onto a wrapper the field disables as a
      *   whole, leaving focus and aria on the control
      * - `announces` is the element whose role carries `aria-readonly` and
@@ -1964,8 +2111,14 @@ const reportCallout = (popover, invoker) => {
     const box = invoker.getBoundingClientRect();
     const here = popover.getBoundingClientRect();
     //against the padding box, which is what a percentage inset resolves against
-    popover.style.setProperty('--ful-note-callout-inline', `${box.left + box.width / 2 - here.left - popover.clientLeft}px`);
-    popover.style.setProperty('--ful-note-callout-block', `${box.top + box.height / 2 - here.top - popover.clientTop}px`);
+    popover.style.setProperty(
+        '--ful-note-callout-inline',
+        `${box.left + box.width / 2 - here.left - popover.clientLeft}px`,
+    );
+    popover.style.setProperty(
+        '--ful-note-callout-block',
+        `${box.top + box.height / 2 - here.top - popover.clientTop}px`,
+    );
 };
 
 const place = (popover, anchored) => {
@@ -2069,67 +2222,93 @@ const schedule = () => {
 };
 
 /**
- * Wires an invoker/popover pair ful anchors through css: where the
- * platform lacks anchor positioning the popover is placed beside its
- * invoker whenever it opens, stretched to the invoker's width when
- * asked, and cleaned up when it closes. Where the css works the call
- * is a no-op.
- *
- * `handPlace` takes the placement here on every platform, which a popover
- * asks for when it needs to know where its invoker ended up: the note's
- * callout points at the invoker, and a pseudo-element cannot read an anchor
- * that is not inside its own containing block, so the note is measured rather
- * than placed by the css. Its stylesheet declares no position-area to match.
+ * CSS anchor positioning for a popover and the invoker it belongs to, with the
+ * hand-placed fallback for the platforms that do not have it.
  */
-const wireAnchoredPopover = (
-    invoker,
-    popover,
-    { prefix = 'ful-anchor', invoke = false, expanded = false, stretch = false, handPlace = false } = {},
-) => {
-    const uid = Attributes.uid(prefix);
-    if (invoke) {
-        //popovertarget needs a target that can be named
-        popover.id = popover.id || uid;
-        invoker.setAttribute('popovertarget', popover.id);
-    }
-    const anchor = `--${uid}`;
-    invoker.style.anchorName = anchor;
-    popover.style.positionAnchor = anchor;
-    if (expanded) {
-        invoker.setAttribute('aria-expanded', 'false');
+class Anchors {
+    /**
+     * Anchors a popover to its invoker.
+     *
+     * The invoker is given an `anchor-name` and the popover a `position-anchor`
+     * pointing at it, which is what a stylesheet needs to place the popover
+     * itself: the library's own menus say `top: anchor(bottom); left:
+     * anchor(left)`. **Writing that css is the caller's half of this.** Without
+     * it the popover lands wherever the user agent puts a popover, which is not
+     * beside the invoker.
+     *
+     * Where the platform has no anchor positioning the popover is placed here
+     * instead, beside the invoker whenever it opens, clamped into the viewport,
+     * following it on scroll and resize, and cleaned up on close. That placement
+     * draws the geometry the css above describes, so the two agree.
+     *
+     * @param {HTMLElement} invoker the element the popover belongs to
+     * @param {HTMLElement} popover the `[popover]` element to place
+     * @param {object} [options]
+     * @param {string} [options.prefix] prefixes the generated anchor name and id,
+     *   so the dom says which component a name belongs to
+     * @param {boolean} [options.invoke] points the invoker's `popovertarget` at
+     *   the popover, giving toggle and light dismiss with no script of your own
+     * @param {boolean} [options.expanded] keeps the invoker's `aria-expanded` in
+     *   step with the popover
+     * @param {boolean} [options.stretch] widens the popover to its invoker, which
+     *   is what a combobox dropdown wants
+     * @param {boolean} [options.handPlace] places here on every platform rather
+     *   than only as a fallback, which a popover asks for when it needs to know
+     *   where its invoker ended up: the tooltip's note points a callout at it, and
+     *   a pseudo-element cannot read an anchor outside its own containing block.
+     *   Such a popover declares no anchor placement in css, there being none to
+     *   agree with
+     */
+    static wire(
+        invoker,
+        popover,
+        { prefix = 'ful-anchor', invoke = false, expanded = false, stretch = false, handPlace = false } = {},
+    ) {
+        const uid = Attributes.uid(prefix);
+        if (invoke) {
+            //popovertarget needs a target that can be named
+            popover.id = popover.id || uid;
+            invoker.setAttribute('popovertarget', popover.id);
+        }
+        const anchor = `--${uid}`;
+        invoker.style.anchorName = anchor;
+        popover.style.positionAnchor = anchor;
+        if (expanded) {
+            invoker.setAttribute('aria-expanded', 'false');
+            popover.addEventListener('toggle', (/** @type any */ evt) => {
+                invoker.setAttribute('aria-expanded', evt.newState === 'open' ? 'true' : 'false');
+            });
+        }
+        //the naming above is what the stylesheet reads, so it happens either way:
+        //only the hand placement below is the fallback, and only for a popover that
+        //did not ask to be placed here whatever the platform offers
+        if (!handPlace && platformAnchors()) {
+            return;
+        }
+        const anchored = { invoker, stretch };
+        popover.addEventListener('beforetoggle', (/** @type any */ evt) => {
+            //placed before the showing, refined once laid out: the platform's
+            //centered or corner spot never paints
+            if (evt.newState === 'open') {
+                place(popover, anchored);
+            }
+        });
         popover.addEventListener('toggle', (/** @type any */ evt) => {
-            invoker.setAttribute('aria-expanded', evt.newState === 'open' ? 'true' : 'false');
+            if (evt.newState === 'open') {
+                open.set(popover, anchored);
+                place(popover, anchored);
+            } else {
+                open.delete(popover);
+                unplace(popover);
+            }
         });
-    }
-    //the naming above is what the stylesheet reads, so it happens either way:
-    //only the hand placement below is the fallback, and only for a popover that
-    //did not ask to be placed here whatever the platform offers
-    if (!handPlace && platformAnchors()) {
-        return;
-    }
-    const anchored = { invoker, stretch };
-    popover.addEventListener('beforetoggle', (/** @type any */ evt) => {
-        //placed before the showing, refined once laid out: the platform's
-        //centered or corner spot never paints
-        if (evt.newState === 'open') {
-            place(popover, anchored);
-        }
-    });
-    popover.addEventListener('toggle', (/** @type any */ evt) => {
-        if (evt.newState === 'open') {
-            open.set(popover, anchored);
-            place(popover, anchored);
-        } else {
-            open.delete(popover);
-            unplace(popover);
+        if (!reflowWired) {
+            reflowWired = true;
+            document.addEventListener('scroll', schedule, true);
+            window.addEventListener('resize', schedule);
         }
-    });
-    if (!reflowWired) {
-        reflowWired = true;
-        document.addEventListener('scroll', schedule, true);
-        window.addEventListener('resize', schedule);
     }
-};
+}
 
 /**
  * Fetches a select's whole vocabulary from a url and serves every later read
@@ -2658,7 +2837,7 @@ class Select extends Field {
         });
         //each pair carries its own anchor: two selects on a page must not share one
         const group = fragment.querySelector('ful-control-group');
-        wireAnchoredPopover(group, this.#ddmenu, { prefix: 'ful-select', stretch: true });
+        Anchors.wire(group, this.#ddmenu, { prefix: 'ful-select', stretch: true });
         [this.#dload, this.#abortdload] = Timing.throttle(400, () => this.#open());
         this.#wireChrome();
         this.#wireChips();
@@ -3248,16 +3427,10 @@ class Checkbox extends Field {
             evt.stopPropagation();
             this._notifyChange();
         });
+        //the base points the label at the input with for/id, so the click toggles
+        //the way it does in a plain form: the input's own change listener above
+        //carries the notification, and readonly is refused by the freeze below
         const label = fragment.querySelector('label');
-        //the label neither wraps the input nor targets it, so the toggle is the
-        //field's; the base adds the focus
-        label.addEventListener('click', () => {
-            if (!this._interactive()) {
-                return;
-            }
-            this.value = !this.value;
-            this._notifyChange();
-        });
         //a checkbox has no editable text to preserve, so readonly freezes the
         //whole choice, label click included: the container is the frozen piece
         return {
@@ -4036,7 +4209,7 @@ class ChoiceButton {
     #wire() {
         const button = this.#button;
         const menu = this.#menu;
-        wireAnchoredPopover(button, menu, { prefix: 'ful-filter-menu', invoke: true, expanded: true });
+        Anchors.wire(button, menu, { prefix: 'ful-filter-menu', invoke: true, expanded: true });
         menu.addEventListener('toggle', (/** @type any */ evt) => {
             if (evt.newState !== 'open') {
                 //give the invoker back the focus the menu had borrowed, without
@@ -4617,30 +4790,63 @@ const wireTargets = () => {
     });
 };
 
-/** An info icon button toggling a popover with a short explanation. */
+/**
+ * An info icon button toggling a popover with a short explanation.
+ *
+ * The marker is the page's `config.icon`, and the `icon` attribute names a
+ * `ful-icon` for the tooltip that means something other than plain information:
+ * a caveat, a warning, a setting. A name the library does not paint is the
+ * page's own, declared as `ful-icon[name='...'] { mask-image: ... }`.
+ *
+ * `describes` is for the tooltip standing in a field: the note becomes part of
+ * the accessible description of that field's control, so it is announced on
+ * reaching the field rather than only on opening the marker, and the marker
+ * leaves the tab order, so a form of hinted fields costs no extra keystrokes to
+ * walk. The marker stays clickable, and stays a tab stop wherever the note was
+ * not taken, a tooltip claiming `describes` outside a field among them: the
+ * stop only goes where something else delivers the content.
+ */
 class Tooltip extends ParsedElement {
     static slots = true;
-    static attributes = ['placement'];
+    static attributes = ['placement', 'icon', 'describes:presence'];
     static config = {
         icon: 'info-circle-fill',
     };
     static template = `
-        <button type="button" class="ful-tip" data-ref="trigger" data-tpl-aria-label="#l10n:t('info.tooltip')"><ful-icon data-tpl-name="config.icon" aria-hidden="true"></ful-icon></button>
+        <button type="button" class="ful-tip" data-ref="trigger" data-tpl-aria-label="#l10n:t('info.tooltip')"><ful-icon data-tpl-name="icon ?? config.icon" aria-hidden="true"></ful-icon></button>
         <ful-note popover data-ref="content">{{{{ slots.default }}}}</ful-note>
     `;
     render({ slots }) {
-        const fragment = this.template().withOverlay({ slots }).render();
+        const fragment = this.template().withOverlay({ slots, icon: this.declared('icon') }).render();
         const trigger = fragment.querySelector('[data-ref=trigger]');
         const content = fragment.querySelector('[data-ref=content]');
         //placed here rather than by the anchor css: the note draws a callout that
         //has to point at the trigger wherever the viewport left room for the note,
         //which is a measurement the stylesheet cannot make for a pseudo-element
-        wireAnchoredPopover(trigger, content, { prefix: 'ful-tooltip', invoke: true, expanded: true, handPlace: true });
-        const placement = this.declared('placement');
-        if (placement) {
-            content.setAttribute('placement', placement);
-        }
+        Anchors.wire(trigger, content, { prefix: 'ful-tooltip', invoke: true, expanded: true, handPlace: true });
+        //above the marker by default: a note opening downwards covers the control
+        //the marker explains, the marker riding the field's label
+        content.setAttribute('placement', this.declared('placement') ?? 'top');
         this.replaceChildren(fragment);
+        if (this.declared('describes')) {
+            Tooltip.#describe(this, trigger, content);
+        }
+    }
+    /**
+     * Offers the note to the field the tooltip stands in, and takes the trigger
+     * out of the tab order only where the offer was accepted: a note nothing
+     * carries is reachable by the keyboard through the marker alone, so
+     * dropping the stop there would leave it reachable by nothing at all.
+     *
+     * The offer goes through the description protocol rather than naming a
+     * field, the library's own arrow running from the forms to the disclosures.
+     */
+    static #describe(tooltip, trigger, content) {
+        if (!describable(tooltip)?.describedBy(content)) {
+            console.warn('a ful-tooltip declares describes but stands in nothing that takes a description', tooltip);
+            return;
+        }
+        trigger.tabIndex = -1;
     }
 }
 
@@ -4727,13 +4933,22 @@ class Dialog extends ParsedElement {
     }
 }
 
-/** A side panel drawer on the native dialog platform, update() owning its open-deliver cycle. */
+/**
+ * A side panel drawer on the native dialog platform, update() owning its
+ * open-deliver cycle.
+ *
+ * The `header` slot is content beside the title, before it: an icon, a badge, a
+ * status. It sits outside the heading rather than in it because `update()` sets
+ * the title through `textContent`, which would take anything nested there with
+ * it.
+ */
 class Drawer extends ParsedElement {
     static attributes = ['title', 'placement'];
     static slots = true;
     static template = `
         <dialog data-ref="dialog" class="ful-drawer">
             <header>
+                {{{{ slots.header }}}}
                 <h2 data-ref="title">{{ title }}</h2>
                 <button type="button" data-ref="close" data-tpl-aria-label="#l10n:t('drawer.close')"><ful-icon name="x-lg" aria-hidden="true"></ful-icon></button>
             </header>
@@ -5473,5 +5688,5 @@ class Plugin {
     }
 }
 
-export { Accordion, AsyncEvents, Bindings, BooleanFilter, Checkbox, Claims, CompareFilter, Dialog, Drawer, Dropdown, Field, Form, FormLoader, Input, InputFile, InputInstant, InputLocalDate, InputLocalTime, Instant, InstantFilter, LocalDate, LocalDateFilter, LocalStorage, NumberFilter, Pagination, Plugin, RadioGroup, Select, SelectLoader, SessionStorage, SortButton, Table, TableLoader, TableSchemaParser, Tabs, TextFilter, Timing, Toasts, Tooltip, VersionedLocalStorage, VersionedSessionStorage, Wizard };
+export { Accordion, Anchors, AsyncEvents, Bindings, BooleanFilter, Checkbox, Claims, CompareFilter, Dialog, Drawer, Dropdown, Field, Form, FormLoader, Input, InputFile, InputInstant, InputLocalDate, InputLocalTime, Instant, InstantFilter, LocalDate, LocalDateFilter, LocalStorage, NumberFilter, Pagination, Plugin, RadioGroup, Select, SelectLoader, SessionStorage, SortButton, Table, TableLoader, TableSchemaParser, Tabs, TextFilter, Timing, Toasts, Tooltip, VersionedLocalStorage, VersionedSessionStorage, Wizard, describable };
 //# sourceMappingURL=ful.mjs.map