@optionfactory/fml 9.0.0-rc23 → 9.0.0-rc25

package/dist/ful.d.mts

@@ -363,6 +363,11 @@ declare class Bindings {
      * `rest` being the remainder of the path (`''` on an exact match) that a
      * composite can use to route the problem to an inner control.
      *
+     * A control counts only when it can show a problem, through a
+     * `setCustomValidity` of its own: a form-associated element that has none is
+     * skipped, so its problems fall to a shorter prefix or to the banner instead
+     * of being dropped.
+     *
      * Every other problem, and a field problem naming no control, is shown in
      * each `ful-errors` banner of the form: the banner gets `role="alert"`, is
      * revealed and holds the reasons one per line. With no such problem the
@@ -616,6 +621,14 @@ declare class Field extends ParsedElement {
      *   accessibility tree.
      * - `also` are further controls that mirror `disabled` and `readOnly`
      *   beside the claim target.
+     *
+     * The pieces are elements the field rendered itself, native controls or
+     * wrappers of its own. A ful field is not one: it has no `readOnly`, its
+     * host's role takes no aria, and a label's `for` names its host rather than
+     * its control. A composite built from ful fields answers the inner field as
+     * `control`, which forwards `focus()`, lets it render its own label with
+     * `label` and `announces` null, and forwards the claims in its setters,
+     * calling super first.
      * @param {{ slots: Record<string, DocumentFragment> | undefined }} conf
      * @returns {any} the pieces, or a promise of them
      * @throws {Error} when the subclass does not implement it
@@ -727,7 +740,8 @@ declare class FormLoader {
  *
  * Attributes on the host starting with `form-` are forwarded, without the
  * prefix, to the native form. `autocomplete` is copied onto the native form as
- * well and stays on the host, the fields reading it from either.
+ * well and stays on the host, the fields reading it from either; a
+ * `form-autocomplete` has the last word on the native form.
  * `clear-invalid-on-change` clears the custom validity of a field of this form
  * when a `change` event bubbles from it; the field's form is read from its
  * `form` property, or from `internals.form` for a form-associated element
@@ -2931,14 +2945,15 @@ declare class Dialog extends ParsedElement {
      *
      * No `section:requested` is dispatched, and no `ask()` waiter is added:
      * listen for the `close` event to learn how the dialog ended. When a newer
-     * `update()` starts before the callback settles, this call paints nothing:
-     * it resolves with the body regardless, and still rejects with the
-     * callback's error.
+     * `update()` starts before the callback settles, this call paints nothing
+     * and resolves `null`, the body being the newer call's; it still rejects
+     * with the callback's error.
      * @param {() => Node|string|Promise<Node|string>} cb producing the body content
-     * @returns {Promise<Element>} the body section, in the document
+     * @returns {Promise<Element|null>} the body section, in the document, or
+     * `null` for a call a newer one overtook
      * @throws {any} what the callback threw or rejected with
      */
-    update(cb: () => Node | string | Promise<Node | string>): Promise<Element>;
+    update(cb: () => Node | string | Promise<Node | string>): Promise<Element | null>;
     /**
      * Dispatches `section:requested` for the body again, as `ask()` does,
      * whether the dialog is open or closed. A failed request is painted into
@@ -3067,15 +3082,16 @@ declare class Drawer extends ParsedElement {
      * which has `role="alert"`, and the content is hidden.
      *
      * No `section:requested` is dispatched. When a newer `update()` starts
-     * before the callback settles, this call paints nothing: it resolves with
-     * the content section regardless, and still rejects with the callback's
-     * error.
+     * before the callback settles, this call paints nothing and resolves
+     * `null`, the content section being the newer call's; it still rejects with
+     * the callback's error.
      * @param {string} header the title, set as text
      * @param {() => Node|string|Promise<Node|string>} cb producing the content
-     * @returns {Promise<Element>} the content section, in the document
+     * @returns {Promise<Element|null>} the content section, in the document, or
+     * `null` for a call a newer one overtook
      * @throws {any} what the callback threw or rejected with
      */
-    update(header: string, cb: () => Node | string | Promise<Node | string>): Promise<Element>;
+    update(header: string, cb: () => Node | string | Promise<Node | string>): Promise<Element | null>;
     /**
      * Dispatches `section:requested` for the content again, as `open()` does,
      * whether the drawer is open or closed. A failed request is painted into
@@ -3145,11 +3161,15 @@ declare class Drawer extends ParsedElement {
     close(result?: string): void;
 }
 /**
- * A menu of commands on the native popover platform, opened by the element
- * whose id `for` names. The menu is the popover itself: light dismiss and
- * Escape come from the browser, and it is anchored to its invoker through
+ * A menu of commands on the native popover platform. The menu is the popover
+ * itself: light dismiss and Escape come from the browser.
+ *
+ * A menu naming an invoker by id through `for` belongs to that element: the
+ * invoker toggles it, and it is anchored to the invoker through
  * `Anchors.wire`, placed in script where the platform has no css anchor
- * positioning.
+ * positioning. A menu without `for` is shared: one menu serves many
+ * invokers, such as the "more" button of every row of a list, and a page
+ * opens it beside the invoker it is for with `showFor(invoker)`.
  *
  * The items are the buttons and `a[href]` links written as its direct
  * children, kept as they are. Activation is the item's own click, which the
@@ -3159,7 +3179,8 @@ declare class Drawer extends ParsedElement {
  * The keyboard is the ARIA menu protocol: the focus moves to the
  * first item as the menu opens, the arrows, Home and End walk the items,
  * typing searches their text, Enter and Space activate the focused one, and
- * Escape and a close from inside the menu hand the focus back to the invoker.
+ * Escape and a close from inside the menu hand the focus back to the invoker
+ * that opened it.
  */
 declare class Menu extends ParsedElement {
     #private;
@@ -3167,13 +3188,27 @@ declare class Menu extends ParsedElement {
     static attributes: string[];
     /**
      * Gives the menu the `menu` role and an empty `popover` attribute unless
-     * it already has one, gives the invoker `aria-haspopup="menu"`, an
-     * `aria-expanded` kept in step, and the toggle of the menu, and marks the
-     * items. `for` is read here, once.
+     * it already has one, and marks the items. With `for`, read here once, it
+     * also gives the invoker `aria-haspopup="menu"`, an `aria-expanded` kept
+     * in step, and the toggle of the menu.
      * @returns {void}
-     * @throws {Error} when `for` names no element in the document at the render
+     * @throws {Error} when `for` is given and names no element in the document at the render
      */
     render(): void;
+    /**
+     * Opens a shared menu, one without `for`, beside `invoker`, or moves it
+     * there when it is open for another one. The menu goes below the invoker,
+     * or above it where there is no room below, and is placed once, as
+     * `Anchors.show` places it. The invoker gets `aria-haspopup="menu"` and an
+     * `aria-expanded` that reads true until the menu closes, and the focus
+     * goes back to it on Escape. A call for the invoker whose press has just
+     * closed the menu does nothing, so a second click on the same button
+     * closes the menu rather than opening it again.
+     * @param {HTMLElement} invoker the element the menu opens for
+     * @returns {void}
+     * @throws {Error} when the menu names its invoker through `for`
+     */
+    showFor(invoker: HTMLElement): void;
     /**
      * The commands, in the order the arrows walk them: the menu's direct
      * `button` and `a[href]` children, minus those carrying a `disabled` or

package/dist/ful.iife.js

@@ -693,6 +693,11 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
          * `rest` being the remainder of the path (`''` on an exact match) that a
          * composite can use to route the problem to an inner control.
          *
+         * A control counts only when it can show a problem, through a
+         * `setCustomValidity` of its own: a form-associated element that has none is
+         * skipped, so its problems fall to a shorter prefix or to the banner instead
+         * of being dropped.
+         *
          * Every other problem, and a field problem naming no control, is shown in
          * each `ful-errors` banner of the form: the banner gets `role="alert"`, is
          * revealed and holds the reasons one per line. With no such problem the
@@ -731,7 +736,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                 const parts = name.split('.');
                 for (let i = parts.length; i !== 0; --i) {
                     const prefix = parts.slice(0, i).join('.');
-                    const targets = named.get(prefix) ?? [];
+                    const targets = (named.get(prefix) ?? []).filter((el) => typeof el.setCustomValidity === 'function');
                     if (targets.length === 0) {
                         continue;
                     }
@@ -1189,6 +1194,14 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
          *   accessibility tree.
          * - `also` are further controls that mirror `disabled` and `readOnly`
          *   beside the claim target.
+         *
+         * The pieces are elements the field rendered itself, native controls or
+         * wrappers of its own. A ful field is not one: it has no `readOnly`, its
+         * host's role takes no aria, and a label's `for` names its host rather than
+         * its control. A composite built from ful fields answers the inner field as
+         * `control`, which forwards `focus()`, lets it render its own label with
+         * `label` and `announces` null, and forwards the claims in its setters,
+         * calling super first.
          * @param {{ slots: Record<string, DocumentFragment> | undefined }} conf
          * @returns {any} the pieces, or a promise of them
          * @throws {Error} when the subclass does not implement it
@@ -1345,7 +1358,8 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
      *
      * Attributes on the host starting with `form-` are forwarded, without the
      * prefix, to the native form. `autocomplete` is copied onto the native form as
-     * well and stays on the host, the fields reading it from either.
+     * well and stays on the host, the fields reading it from either; a
+     * `form-autocomplete` has the last word on the native form.
      * `clear-invalid-on-change` clears the custom validity of a field of this form
      * when a `change` event bubbles from it; the field's form is read from its
      * `form` property, or from `internals.form` for a form-associated element
@@ -1380,8 +1394,8 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
             const form = document.createElement('form');
             this.form = form;
             form.setAttribute('novalidate', '');
-            index_mjs.Attributes.forward('form-', this, form);
             index_mjs.Attributes.set(form, 'autocomplete', this.declared('autocomplete'));
+            index_mjs.Attributes.forward('form-', this, form);
             form.replaceChildren(...this.childNodes);
             form.addEventListener('submit', async (e) => {
                 e.preventDefault();
@@ -4576,7 +4590,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                 return;
             }
             /** @type {HTMLInputElement|null} */
-            const el = this.querySelector(`input[type=radio][value=${CSS.escape(String(value))}]`);
+            const el = this.querySelector(`input[type=radio][value="${CSS.escape(String(value))}"]`);
             if (el === null) {
                 clear();
                 return;
@@ -5569,7 +5583,9 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
      * `items` answers the items in the order they are walked, and is called on
      * every gesture, so a menu that fills itself later needs no rewiring.
      *
-     * @param {HTMLElement} invoker the element the menu belongs to, and where the focus goes back
+     * @param {() => HTMLElement|null} invoker answers the element the menu belongs to
+     *   now, where the focus goes back; called on every gesture, so a menu shared
+     *   by several invokers hands the focus back to the one that opened it
      * @param {HTMLElement} menu the `[popover]` holding the items
      * @param {{items: () => HTMLElement[], current?: () => HTMLElement|null|undefined}} conf
      *   `items` answers the items; `current` answers the item an opening focuses
@@ -5579,7 +5595,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         let typedAt = 0;
         menu.addEventListener('beforetoggle', (/** @type any */ evt) => {
             if (evt.newState === 'closed' && menu.contains(document.activeElement)) {
-                invoker.focus();
+                invoker()?.focus();
             }
         });
         menu.addEventListener('toggle', (/** @type any */ evt) => {
@@ -5623,11 +5639,11 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                 case 'Space': {
                     evt.preventDefault();
                     item.click();
-                    invoker.focus();
+                    invoker()?.focus();
                     return;
                 }
                 case 'Escape': {
-                    invoker.focus();
+                    invoker()?.focus();
                     return;
                 }
             }
@@ -5852,7 +5868,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         }
         #wire() {
             Anchors.wire(this.#button, this.#menu, { prefix: 'ful-filter-menu', invoke: true, expanded: true });
-            wireMenuKeys(this.#button, this.#menu, {
+            wireMenuKeys(() => this.#button, this.#menu, {
                 items: () => this.#items(),
                 current: () => this.#items().find((a) => a.getAttribute('value') === this.value),
             });
@@ -6850,11 +6866,12 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
          * `show`, and fills the content with what the callback resolves to. A
          * rejection is shown, as the problems' reasons, in the error section, and
          * the content is hidden. When a newer `update()` starts before the callback
-         * settles, this call paints nothing: it resolves with the section regardless,
-         * and still rejects with the callback's error.
+         * settles, this call paints nothing and resolves `null`, the section being
+         * the newer call's; it still rejects with the callback's error.
          * @param {() => Node|string|Promise<Node|string>} cb producing the content
          * @param {() => void} show opens the dialog when it is closed
-         * @returns {Promise<HTMLElement>} the content section
+         * @returns {Promise<HTMLElement|null>} the content section, or `null` for a
+         * call a newer one overtook
          * @throws {any} what the callback threw or rejected with
          */
         async update(cb, show) {
@@ -6867,7 +6884,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
             try {
                 const delivered = await cb();
                 if (claim.stale) {
-                    return this.#section;
+                    return null;
                 }
                 this.#section.replaceChildren(delivered);
                 this.#loading?.setAttribute('hidden', '');
@@ -7113,11 +7130,12 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
          *
          * No `section:requested` is dispatched, and no `ask()` waiter is added:
          * listen for the `close` event to learn how the dialog ended. When a newer
-         * `update()` starts before the callback settles, this call paints nothing:
-         * it resolves with the body regardless, and still rejects with the
-         * callback's error.
+         * `update()` starts before the callback settles, this call paints nothing
+         * and resolves `null`, the body being the newer call's; it still rejects
+         * with the callback's error.
          * @param {() => Node|string|Promise<Node|string>} cb producing the body content
-         * @returns {Promise<Element>} the body section, in the document
+         * @returns {Promise<Element|null>} the body section, in the document, or
+         * `null` for a call a newer one overtook
          * @throws {any} what the callback threw or rejected with
          */
         async update(cb) {
@@ -7407,12 +7425,13 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
          * which has `role="alert"`, and the content is hidden.
          *
          * No `section:requested` is dispatched. When a newer `update()` starts
-         * before the callback settles, this call paints nothing: it resolves with
-         * the content section regardless, and still rejects with the callback's
-         * error.
+         * before the callback settles, this call paints nothing and resolves
+         * `null`, the content section being the newer call's; it still rejects with
+         * the callback's error.
          * @param {string} header the title, set as text
          * @param {() => Node|string|Promise<Node|string>} cb producing the content
-         * @returns {Promise<Element>} the content section, in the document
+         * @returns {Promise<Element|null>} the content section, in the document, or
+         * `null` for a call a newer one overtook
          * @throws {any} what the callback threw or rejected with
          */
         async update(header, cb) {
@@ -7561,11 +7580,15 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
     }
 
     /**
-     * A menu of commands on the native popover platform, opened by the element
-     * whose id `for` names. The menu is the popover itself: light dismiss and
-     * Escape come from the browser, and it is anchored to its invoker through
+     * A menu of commands on the native popover platform. The menu is the popover
+     * itself: light dismiss and Escape come from the browser.
+     *
+     * A menu naming an invoker by id through `for` belongs to that element: the
+     * invoker toggles it, and it is anchored to the invoker through
      * `Anchors.wire`, placed in script where the platform has no css anchor
-     * positioning.
+     * positioning. A menu without `for` is shared: one menu serves many
+     * invokers, such as the "more" button of every row of a list, and a page
+     * opens it beside the invoker it is for with `showFor(invoker)`.
      *
      * The items are the buttons and `a[href]` links written as its direct
      * children, kept as they are. Activation is the item's own click, which the
@@ -7575,34 +7598,44 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
      * The keyboard is the ARIA menu protocol: the focus moves to the
      * first item as the menu opens, the arrows, Home and End walk the items,
      * typing searches their text, Enter and Space activate the focused one, and
-     * Escape and a close from inside the menu hand the focus back to the invoker.
+     * Escape and a close from inside the menu hand the focus back to the invoker
+     * that opened it.
      */
     class Menu extends index_mjs.ParsedElement {
         /** @type {string[]} */
         static attributes = ['for'];
+        /** @type {HTMLElement|null} */
+        #invoker = null;
+        /** @type {HTMLElement|null} */
+        #pressed = null;
         /**
          * Gives the menu the `menu` role and an empty `popover` attribute unless
-         * it already has one, gives the invoker `aria-haspopup="menu"`, an
-         * `aria-expanded` kept in step, and the toggle of the menu, and marks the
-         * items. `for` is read here, once.
+         * it already has one, and marks the items. With `for`, read here once, it
+         * also gives the invoker `aria-haspopup="menu"`, an `aria-expanded` kept
+         * in step, and the toggle of the menu.
          * @returns {void}
-         * @throws {Error} when `for` names no element in the document at the render
+         * @throws {Error} when `for` is given and names no element in the document at the render
          */
         render() {
             const named = this.declared('for');
             const invoker = named ? document.getElementById(named) : null;
-            if (!invoker) {
+            if (named && !invoker) {
                 throw new Error(
-                    `ful-menu names no invoker: for="${named ?? ''}" must name an element already in the page when the menu upgrades`,
+                    `ful-menu names no invoker: for="${named}" must name an element already in the page when the menu upgrades`,
                 );
             }
             this.setAttribute('role', 'menu');
             if (!this.hasAttribute('popover')) {
                 this.setAttribute('popover', '');
             }
-            invoker.setAttribute('aria-haspopup', 'menu');
-            Anchors.wire(invoker, this, { prefix: 'ful-menu', invoke: true, expanded: true });
-            wireMenuKeys(invoker, this, { items: () => this.items });
+            if (invoker) {
+                this.#invoker = invoker;
+                invoker.setAttribute('aria-haspopup', 'menu');
+                Anchors.wire(invoker, this, { prefix: 'ful-menu', invoke: true, expanded: true });
+            } else {
+                this.#wireShared();
+            }
+            wireMenuKeys(() => this.#invoker, this, { items: () => this.items });
             this.#mark();
             this.addEventListener('click', (evt) => {
                 const target = /** @type HTMLElement */ (evt.target);
@@ -7611,6 +7644,43 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                 }
             });
         }
+        /**
+         * Opens a shared menu, one without `for`, beside `invoker`, or moves it
+         * there when it is open for another one. The menu goes below the invoker,
+         * or above it where there is no room below, and is placed once, as
+         * `Anchors.show` places it. The invoker gets `aria-haspopup="menu"` and an
+         * `aria-expanded` that reads true until the menu closes, and the focus
+         * goes back to it on Escape. A call for the invoker whose press has just
+         * closed the menu does nothing, so a second click on the same button
+         * closes the menu rather than opening it again.
+         * @param {HTMLElement} invoker the element the menu opens for
+         * @returns {void}
+         * @throws {Error} when the menu names its invoker through `for`
+         */
+        showFor(invoker) {
+            if (this.declared('for')) {
+                throw new Error('ful-menu: showFor serves a menu without for; a menu with for is opened by its invoker');
+            }
+            const pressed = this.#pressed;
+            this.#pressed = null;
+            if (pressed === invoker) {
+                return;
+            }
+            if (this.#invoker && this.#invoker !== invoker) {
+                this.#invoker.setAttribute('aria-expanded', 'false');
+            }
+            this.#invoker = invoker;
+            invoker.setAttribute('aria-haspopup', 'menu');
+            invoker.setAttribute('aria-expanded', 'true');
+            //the previous placement wrote margin: 0 inline, hiding the stylesheet's gap
+            this.style.margin = '';
+            const gap = Number.parseFloat(getComputedStyle(this).marginBlockStart) || 0;
+            const moving = this.matches(':popover-open');
+            Anchors.show(this, invoker, { flip: true, gap });
+            if (moving) {
+                this.items[0]?.focus();
+            }
+        }
         /**
          * The commands, in the order the arrows walk them: the menu's direct
          * `button` and `a[href]` children, minus those carrying a `disabled` or
@@ -7622,6 +7692,21 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         get items() {
             return this.#mark().filter((item) => !item.hasAttribute('disabled') && !item.hasAttribute('hidden'));
         }
+        #wireShared() {
+            document.addEventListener(
+                'pointerdown',
+                (evt) => {
+                    const target = /** @type Node */ (evt.target);
+                    this.#pressed = this.matches(':popover-open') && this.#invoker?.contains(target) ? this.#invoker : null;
+                },
+                true,
+            );
+            this.addEventListener('toggle', (/** @type any */ evt) => {
+                if (evt.newState === 'closed') {
+                    this.#invoker?.setAttribute('aria-expanded', 'false');
+                }
+            });
+        }
         /** @returns {HTMLElement[]} every item, disabled and hidden ones included, once marked */
         #mark() {
             const all = /** @type HTMLElement[] */ ([...this.querySelectorAll(':scope > button, :scope > a[href]')]);