@optionfactory/fml 9.0.0-rc23 → 9.0.0-rc25

package/dist/custom-elements.json

@@ -192,11 +192,11 @@
           "name": "Menu",
           "tagName": "ful-menu",
           "customElement": true,
-          "description": "A menu of commands on the native popover platform: the invoker named by for toggles it, light dismiss and Escape come from the browser, and the element adds the menu semantics and the keyboard protocol (roving focus with the arrows, Home and End, type-ahead, Enter and Space to activate, Escape and every close handing the focus back to the invoker). The items are the buttons and links written inside it, kept as they are and given their menuitem role; activation is the item's own click, which the menu only follows by closing.",
+          "description": "A menu of commands on the native popover platform: the invoker named by for toggles it, or, without for, one menu serves many invokers and showFor(invoker) opens it beside the one it is for. Light dismiss and Escape come from the browser, and the element adds the menu semantics and the keyboard protocol (roving focus with the arrows, Home and End, type-ahead, Enter and Space to activate, Escape and every close handing the focus back to the invoker). The items are the buttons and links written inside it, kept as they are and given their menuitem role; activation is the item's own click, which the menu only follows by closing.",
           "attributes": [
             {
               "name": "for",
-              "description": "The id of the invoker the menu belongs to: it toggles the menu, carries aria-haspopup and aria-expanded, and takes the focus back when the menu closes. Read once at the upgrade, so the invoker must already be in the page by then.",
+              "description": "The id of the invoker the menu belongs to: it toggles the menu, carries aria-haspopup and aria-expanded, and takes the focus back when the menu closes. Read once at the upgrade, so the invoker must already be in the page by then. Without it the menu is shared, opened by showFor(invoker).",
               "type": {
                 "text": "string"
               }
@@ -419,7 +419,7 @@
             },
             {
               "name": "submit:requested",
-              "description": "Fired after the submit was accepted, to let a listener resolve the response itself.",
+              "description": "Fired after the submit was accepted, to let a listener resolve the response itself. Register it through AsyncEvents.asyncOn: the form awaits only such a listener, and one added with addEventListener is not waited for.",
               "type": {
                 "text": "CustomEvent"
               }

package/dist/fml.iife.js

@@ -6963,6 +6963,11 @@ var fml = (function (exports) {
          * `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
@@ -7001,7 +7006,7 @@ var fml = (function (exports) {
                 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;
                     }
@@ -7459,6 +7464,14 @@ var fml = (function (exports) {
          *   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
@@ -7615,7 +7628,8 @@ var fml = (function (exports) {
      *
      * 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
@@ -7650,8 +7664,8 @@ var fml = (function (exports) {
             const form = document.createElement('form');
             this.form = form;
             form.setAttribute('novalidate', '');
-            Attributes.forward('form-', this, form);
             Attributes.set(form, 'autocomplete', this.declared('autocomplete'));
+            Attributes.forward('form-', this, form);
             form.replaceChildren(...this.childNodes);
             form.addEventListener('submit', async (e) => {
                 e.preventDefault();
@@ -10846,7 +10860,7 @@ var fml = (function (exports) {
                 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;
@@ -11839,7 +11853,9 @@ var fml = (function (exports) {
      * `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
@@ -11849,7 +11865,7 @@ var fml = (function (exports) {
         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) => {
@@ -11893,11 +11909,11 @@ var fml = (function (exports) {
                 case 'Space': {
                     evt.preventDefault();
                     item.click();
-                    invoker.focus();
+                    invoker()?.focus();
                     return;
                 }
                 case 'Escape': {
-                    invoker.focus();
+                    invoker()?.focus();
                     return;
                 }
             }
@@ -12122,7 +12138,7 @@ var fml = (function (exports) {
         }
         #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),
             });
@@ -13120,11 +13136,12 @@ var fml = (function (exports) {
          * `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) {
@@ -13137,7 +13154,7 @@ var fml = (function (exports) {
             try {
                 const delivered = await cb();
                 if (claim.stale) {
-                    return this.#section;
+                    return null;
                 }
                 this.#section.replaceChildren(delivered);
                 this.#loading?.setAttribute('hidden', '');
@@ -13383,11 +13400,12 @@ var fml = (function (exports) {
          *
          * 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) {
@@ -13677,12 +13695,13 @@ var fml = (function (exports) {
          * 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) {
@@ -13831,11 +13850,15 @@ var fml = (function (exports) {
     }
 
     /**
-     * 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
@@ -13845,34 +13868,44 @@ var fml = (function (exports) {
      * 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 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);
@@ -13881,6 +13914,43 @@ var fml = (function (exports) {
                 }
             });
         }
+        /**
+         * 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
@@ -13892,6 +13962,21 @@ var fml = (function (exports) {
         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]')]);