@optionfactory/fml 9.0.0-rc2 → 9.0.0-rc3

package/dist/ful.d.mts

@@ -539,6 +539,52 @@ declare class InputFile extends Input {
     get dropzone(): any;
     set dropzone(v: any);
 }
+/**
+ * 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.
+ */
+declare 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: HTMLElement, popover: HTMLElement, { prefix, invoke, expanded, stretch, handPlace }?: {
+        prefix?: string;
+        invoke?: boolean;
+        expanded?: boolean;
+        stretch?: boolean;
+        handPlace?: boolean;
+    }): void;
+}
 /**
  * Fetches a select's whole vocabulary from a url and serves every later read
  * from it. Concurrent callers share one request, the options may be cached in
@@ -991,7 +1037,15 @@ declare class Dialog extends ParsedElement {
     refresh(): Promise<any[] | undefined>;
     close(result: any): void;
 }
-/** 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.
+ */
 declare class Drawer extends ParsedElement {
     #private;
     static attributes: string[];
@@ -1141,6 +1195,6 @@ declare class Plugin {
     });
     configure(registry: any): void;
 }
-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 };
 
 export as namespace ful;

package/dist/ful.iife.js

@@ -681,12 +681,16 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
             //the error region describes the control, or the host where there is no
             //single control to describe (a radio group's legend names its fieldset)
             if (error) {
-                (described ?? control).ariaDescribedByElements = [error];
+                //an attribute, not the aria element property: the property reflects to
+                //nothing, so the description lived in the accessibility tree alone and
+                //vanished entirely on a browser without aria element reflection
+                if (!error.id) {
+                    error.id = index_mjs.Attributes.uid('ful-field-error');
+                }
+                (described ?? control).setAttribute('aria-describedby', error.id);
             }
             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
@@ -775,6 +779,49 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                 }),
             );
         }
+        /** 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 = index_mjs.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 = index_mjs.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
@@ -1964,8 +2011,14 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         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 +2122,93 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
     };
 
     /**
-     * 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 = index_mjs.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 = index_mjs.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 +2737,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
             });
             //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 +3327,10 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                 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 +4109,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         #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
@@ -4635,7 +4708,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
             //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 });
+            Anchors.wire(trigger, content, { prefix: 'ful-tooltip', invoke: true, expanded: true, handPlace: true });
             const placement = this.declared('placement');
             if (placement) {
                 content.setAttribute('placement', placement);
@@ -4727,13 +4800,22 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         }
     }
 
-    /** 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 index_mjs.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>
@@ -5474,6 +5556,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
     }
 
     exports.Accordion = Accordion;
+    exports.Anchors = Anchors;
     exports.AsyncEvents = AsyncEvents;
     exports.Bindings = Bindings;
     exports.BooleanFilter = BooleanFilter;