@optionfactory/fml 9.0.0-rc14 → 9.0.0-rc15

package/dist/ful.d.mts

@@ -664,8 +664,9 @@ declare class Anchors {
      * start-aligned, clamped into the viewport; `flip` moves it above the
      * anchor where the viewport leaves no room below, as the css
      * `position-try-fallbacks` the paired popovers declare. A popover not
-     * already open is shown before it is placed, so the first position anybody
-     * sees is the right one.
+     * already open is shown and placed before the call returns, so the first
+     * position anybody sees is the right one and the caller can move the focus
+     * into it on the next line.
      *
      * @param {HTMLElement} popover the `[popover]` element to show, or an
      *   already-shown element to place
@@ -1228,13 +1229,19 @@ declare class Dialog extends ParsedElement {
      *
      * The body is text or a node: a string is never read as markup, an
      * `innerHTML` sink being a thing the library does not carry. Each button is
-     * a `[result, label, className?]` tuple, rendered as its answer.
+     * a `[result, label, className?]` tuple rendered as its answer, or a node
+     * the caller has built itself, which is how a button carries anything a
+     * tuple cannot say and how a footer gets a spacer.
      * @param {string} header
      * @param {string|Node} body
-     * @param {[string, string, string?][]} [buttons]
+     * @param {([string, string, string?]|Node)[]} [buttons]
+     * @param {{ className?: string }} [options] `className` dresses the dialog,
+     *   the way a declared `ful-dialog` is given one to size it
      * @returns {Promise<DialogOutcome>}
      */
-    static ask(header: string, body: string | Node, buttons?: [string, string, string?][]): Promise<DialogOutcome>;
+    static ask(header: string, body: string | Node, buttons?: ([string, string, string?] | Node)[], { className }?: {
+        className?: string;
+    }): Promise<DialogOutcome>;
     /**
      * Asks a yes/no question, resolving with the confirm button's answer:
      * the cancel button, the close button and Escape all answer false, a
@@ -1242,11 +1249,14 @@ declare class Dialog extends ParsedElement {
      * @param {string} header
      * @param {string|Node} body
      * @param {{ confirm?: string, cancel?: string }} [labels] overriding the localized defaults
+     * @param {{ className?: string }} [options] as `ask` takes them
      * @returns {Promise<boolean>}
      */
     static confirm(header: string, body: string | Node, labels?: {
         confirm?: string;
         cancel?: string;
+    }, options?: {
+        className?: string;
     }): Promise<boolean>;
 }
 /**
@@ -1284,6 +1294,26 @@ declare class Drawer extends ParsedElement {
     open(): void;
     close(): void;
 }
+/**
+ * A menu of commands on the native popover platform: the invoker named by
+ * `for` toggles it and light dismiss and Escape come from the browser, while
+ * the element adds the menu semantics and the keyboard protocol.
+ *
+ * The items are the buttons and links written inside it, kept as they are and
+ * given their menu role and their place in the roving focus. Activation is the
+ * item's own click, which the element only follows by closing.
+ */
+declare class Menu extends ParsedElement {
+    #private;
+    static attributes: string[];
+    render(): void;
+    /**
+     * The commands, in the order the arrows walk them: the menu's own buttons
+     * and links, minus the disabled and hidden ones, which keep their role and
+     * leave the walk.
+     */
+    get items(): HTMLElement[];
+}
 /** A transient feedback region: each show() stacks a toast that retires on its own timer. */
 declare class Toasts extends ParsedElement {
     #private;
@@ -1412,6 +1442,6 @@ declare class Plugin {
     });
     configure(registry: any): void;
 }
-export { Accordion, Anchors, AsyncEvents, Bindings, BooleanFilter, Checkbox, Claims, CompareFilter, Dialog, Drawer, Dropdown, Field, Form, FormLoader, InFilter, 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 };
+export { Accordion, Anchors, AsyncEvents, Bindings, BooleanFilter, Checkbox, Claims, CompareFilter, Dialog, Drawer, Dropdown, Field, Form, FormLoader, InFilter, Input, InputFile, InputInstant, InputLocalDate, InputLocalTime, Instant, InstantFilter, LocalDate, LocalDateFilter, LocalStorage, Menu, NumberFilter, Pagination, Plugin, RadioGroup, Select, SelectLoader, SessionStorage, SortButton, Table, TableLoader, TableSchemaParser, Tabs, TextFilter, Timing, Toasts, Tooltip, VersionedLocalStorage, VersionedSessionStorage, Wizard, describable };
 
 export as namespace ful;

package/dist/ful.iife.js

@@ -2304,7 +2304,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
 
     const showOncePlaced = (popover, anchored) => {
         popover.style.visibility = 'hidden';
-        requestAnimationFrame(() => {
+        queueMicrotask(() => {
             if (popover.matches(':popover-open')) {
                 place(popover, anchored);
             }
@@ -2443,8 +2443,9 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
          * start-aligned, clamped into the viewport; `flip` moves it above the
          * anchor where the viewport leaves no room below, as the css
          * `position-try-fallbacks` the paired popovers declare. A popover not
-         * already open is shown before it is placed, so the first position anybody
-         * sees is the right one.
+         * already open is shown and placed before the call returns, so the first
+         * position anybody sees is the right one and the caller can move the focus
+         * into it on the next line.
          *
          * @param {HTMLElement} popover the `[popover]` element to show, or an
          *   already-shown element to place
@@ -2470,16 +2471,10 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                 popover.style.left = `${clamp(box.left, PAD, Math.max(PAD, viewport.clientWidth - here.width - PAD))}px`;
                 popover.style.top = `${clamp(top, PAD, Math.max(PAD, viewport.clientHeight - here.height - PAD))}px`;
             };
-            if (popover.matches(':popover-open') || typeof popover.showPopover !== 'function') {
-                placeShown();
-                return popover;
-            }
-            popover.style.visibility = 'hidden';
-            popover.showPopover();
-            requestAnimationFrame(() => {
-                placeShown();
-                popover.style.removeProperty('visibility');
-            });
+            if (typeof popover.showPopover === 'function' && !popover.matches(':popover-open')) {
+                popover.showPopover();
+            }
+            placeShown();
             return popover;
         }
     }
@@ -2771,6 +2766,11 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
             //from the host when it gave one, since it has to set aria-controls before
             //this element upgrades
             this.#menu.id = this.declared('listbox') || index_mjs.Attributes.uid('ful-listbox');
+            this.#menu.addEventListener('mousedown', (evt) => {
+                if (evt.target.closest('li')) {
+                    evt.preventDefault();
+                }
+            });
             this.#menu.addEventListener('click', (evt) => {
                 evt.stopPropagation();
                 const li = evt.target.closest('li');
@@ -2778,7 +2778,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                     this.hide();
                     return;
                 }
-                if (li.hasAttribute('aria-disabled')) {
+                if (li.matches('[aria-disabled="true"]')) {
                     return;
                 }
                 this.#change(li);
@@ -2787,8 +2787,8 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         }
         #selected() {
             return (
-                this.#menu?.querySelector('[selected]:not([aria-disabled])') ??
-                this.#menu?.querySelector('li:not([aria-disabled])') ??
+                this.#menu?.querySelector('[selected]:not([aria-disabled="true"])') ??
+                this.#menu?.querySelector('li:not([aria-disabled="true"])') ??
                 null
             );
         }
@@ -2830,7 +2830,11 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                 li.setAttribute('aria-selected', picked ? 'true' : 'false');
                 //metadata.disabled refuses the entry, metadata.reason saying why
                 const disabled = !!entry?.metadata?.disabled;
-                li.toggleAttribute('aria-disabled', disabled);
+                if (disabled) {
+                    li.setAttribute('aria-disabled', 'true');
+                } else {
+                    li.removeAttribute('aria-disabled');
+                }
                 if (disabled && entry.metadata.reason) {
                     li.setAttribute('title', String(entry.metadata.reason));
                 } else {
@@ -2919,7 +2923,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         }
         #walk(from, forward) {
             for (let li = from; li; li = li[`${forward ? 'next' : 'previous'}ElementSibling`]) {
-                if (!li.hasAttribute('aria-disabled')) {
+                if (!li.matches('[aria-disabled="true"]')) {
                     return li;
                 }
             }
@@ -4363,15 +4367,110 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         }
     }
 
+    /** how long a type-ahead buffer stands before the next character starts a new search */
+    const TYPEAHEAD_WINDOW = 500;
+
+    /**
+     * The keyboard protocol of a menu popover: the focus moving into the menu as it
+     * opens and back to the invoker as it closes, roving focus over the items with
+     * the arrows, Home and End, type-ahead over their text, and Enter and Space
+     * activating the focused one.
+     *
+     * The menu owns what an item is: `items` answers them in the order they are
+     * walked, read on every gesture so a menu that fills itself later needs no
+     * rewiring, and `current` names the one an opening focuses, the first otherwise.
+     *
+     * @param {HTMLElement} invoker the element the menu belongs to, and where the focus goes back
+     * @param {HTMLElement} menu the `[popover]` holding the items
+     * @param {{items: () => HTMLElement[], current?: () => HTMLElement|null|undefined}} conf
+     */
+    const wireMenuKeys = (invoker, menu, { items, current = () => null }) => {
+        let typed = '';
+        let typedAt = 0;
+        menu.addEventListener('toggle', (/** @type any */ evt) => {
+            if (evt.newState !== 'open') {
+                //give the invoker back the focus the menu had borrowed, without
+                //stealing it from wherever else the close came from
+                if (menu.contains(document.activeElement)) {
+                    invoker.focus();
+                }
+                return;
+            }
+            const all = items();
+            (current() ?? all[0])?.focus();
+        });
+        menu.addEventListener('keydown', (evt) => {
+            const target = /** @type HTMLElement */ (evt.target);
+            const all = items();
+            const item = all.find((candidate) => candidate === target || candidate.contains(target));
+            if (!item) {
+                return;
+            }
+            const at = all.indexOf(item);
+            switch (evt.code) {
+                case 'ArrowDown': {
+                    evt.preventDefault();
+                    all[(at + 1) % all.length]?.focus();
+                    return;
+                }
+                case 'ArrowUp': {
+                    evt.preventDefault();
+                    all[(at - 1 + all.length) % all.length]?.focus();
+                    return;
+                }
+                case 'Home': {
+                    evt.preventDefault();
+                    all[0]?.focus();
+                    return;
+                }
+                case 'End': {
+                    evt.preventDefault();
+                    all[all.length - 1]?.focus();
+                    return;
+                }
+                case 'Enter':
+                case 'Space': {
+                    evt.preventDefault();
+                    item.click();
+                    invoker.focus();
+                    return;
+                }
+                case 'Escape': {
+                    //the platform's close request hides the menu, the focus is placed
+                    //on the invoker before the focused item is detached from it
+                    invoker.focus();
+                    return;
+                }
+            }
+            if (evt.key.length !== 1 || evt.ctrlKey || evt.altKey || evt.metaKey) {
+                return;
+            }
+            const now = Date.now();
+            typed = now - typedAt > TYPEAHEAD_WINDOW ? evt.key : typed + evt.key;
+            typedAt = now;
+            const wanted = typed.toLowerCase();
+            const repeated = [...wanted].every((character) => character === wanted[0]);
+            const search = repeated ? wanted[0] : wanted;
+            const from = repeated ? at + 1 : at;
+            const found = [...all.slice(from), ...all.slice(0, from)].find((candidate) =>
+                (candidate.textContent ?? '').trim().toLowerCase().startsWith(search),
+            );
+            if (found) {
+                evt.preventDefault();
+                found.focus();
+            }
+        });
+    };
+
     /**
      * An invoker button paired with the `ul[popover][role=menu]` that follows it:
      * the chrome behind every filter's operator, sensitivity and boolean value.
      *
      * It fills the menu from a vocabulary, wires it the first time more than one
      * choice survives the whitelist, pins the button to a static glyph when a
-     * single one does, owns the roving focus and the Escape/Enter handling, and
-     * keeps the button's value, glyph and aria-label in step. A pick that changes
-     * the value calls back; the host decides what that means.
+     * single one does, takes the shared menu keyboard protocol, and keeps the
+     * button's value, glyph and aria-label in step. A pick that changes the value
+     * calls back; the host decides what that means.
      *
      * The button's `value` attribute is the store, as it is for a native control:
      * the menu protocol finds the current item by it, and nothing mirrors it.
@@ -4529,64 +4628,10 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
             return Array.from(this.#menu.querySelectorAll('li > a'), (a) => /** @type HTMLAnchorElement */ (a));
         }
         #wire() {
-            const button = this.#button;
-            const menu = this.#menu;
-            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
-                    //stealing it from wherever else the close came from
-                    if (menu.contains(document.activeElement)) {
-                        button.focus();
-                    }
-                    return;
-                }
-                const items = this.#items();
-                (items.find((a) => a.getAttribute('value') === this.value) ?? items[0])?.focus();
-            });
-            menu.addEventListener('keydown', (evt) => {
-                const target = /** @type HTMLElement */ (evt.target);
-                const item = /** @type HTMLAnchorElement | null */ (target.closest('li > a'));
-                if (!item) {
-                    return;
-                }
-                const items = this.#items();
-                const at = items.indexOf(item);
-                switch (evt.code) {
-                    case 'ArrowDown': {
-                        evt.preventDefault();
-                        items[(at + 1) % items.length]?.focus();
-                        break;
-                    }
-                    case 'ArrowUp': {
-                        evt.preventDefault();
-                        items[(at - 1 + items.length) % items.length]?.focus();
-                        break;
-                    }
-                    case 'Home': {
-                        evt.preventDefault();
-                        items[0]?.focus();
-                        break;
-                    }
-                    case 'End': {
-                        evt.preventDefault();
-                        items[items.length - 1]?.focus();
-                        break;
-                    }
-                    case 'Enter':
-                    case 'Space': {
-                        evt.preventDefault();
-                        item.click();
-                        button.focus();
-                        break;
-                    }
-                    case 'Escape': {
-                        //the platform's close request hides the menu, the focus is placed
-                        //on the invoker before the focused item is detached from it
-                        button.focus();
-                        break;
-                    }
-                }
+            Anchors.wire(this.#button, this.#menu, { prefix: 'ful-filter-menu', invoke: true, expanded: true });
+            wireMenuKeys(this.#button, this.#menu, {
+                items: () => this.#items(),
+                current: () => this.#items().find((a) => a.getAttribute('value') === this.value),
             });
         }
     }
@@ -5561,15 +5606,22 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
          *
          * The body is text or a node: a string is never read as markup, an
          * `innerHTML` sink being a thing the library does not carry. Each button is
-         * a `[result, label, className?]` tuple, rendered as its answer.
+         * a `[result, label, className?]` tuple rendered as its answer, or a node
+         * the caller has built itself, which is how a button carries anything a
+         * tuple cannot say and how a footer gets a spacer.
          * @param {string} header
          * @param {string|Node} body
-         * @param {[string, string, string?][]} [buttons]
+         * @param {([string, string, string?]|Node)[]} [buttons]
+         * @param {{ className?: string }} [options] `className` dresses the dialog,
+         *   the way a declared `ful-dialog` is given one to size it
          * @returns {Promise<DialogOutcome>}
          */
-        static async ask(header, body, buttons = []) {
+        static async ask(header, body, buttons = [], { className } = {}) {
             const dialog = document.createElement('ful-dialog');
             dialog.setAttribute('header', header);
+            if (className) {
+                dialog.className = className;
+            }
             if (typeof body === 'string') {
                 dialog.textContent = body;
             } else if (body) {
@@ -5580,12 +5632,17 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
             if (buttons.length > 0) {
                 const choices = document.createElement('template');
                 choices.setAttribute('slot', 'buttons');
-                for (const [result, label, className] of buttons) {
+                for (const choice of buttons) {
+                    if (choice instanceof Node) {
+                        choices.content.append(choice);
+                        continue;
+                    }
+                    const [result, label, buttonClass] = choice;
                     const button = document.createElement('button');
                     button.type = 'button';
                     button.dataset.result = result;
-                    if (className) {
-                        button.className = className;
+                    if (buttonClass) {
+                        button.className = buttonClass;
                     }
                     button.textContent = label;
                     choices.content.append(button);
@@ -5607,13 +5664,19 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
          * @param {string} header
          * @param {string|Node} body
          * @param {{ confirm?: string, cancel?: string }} [labels] overriding the localized defaults
+         * @param {{ className?: string }} [options] as `ask` takes them
          * @returns {Promise<boolean>}
          */
-        static async confirm(header, body, labels = {}) {
-            const outcome = await Dialog.ask(header, body, [
-                ['cancel', labels.cancel ?? index_mjs.Localization.of().t('dialog.cancel')],
-                ['confirm', labels.confirm ?? index_mjs.Localization.of().t('dialog.confirm'), 'ful-button'],
-            ]);
+        static async confirm(header, body, labels = {}, options = {}) {
+            const outcome = await Dialog.ask(
+                header,
+                body,
+                [
+                    ['cancel', labels.cancel ?? index_mjs.Localization.of().t('dialog.cancel')],
+                    ['confirm', labels.confirm ?? index_mjs.Localization.of().t('dialog.confirm'), 'ful-button'],
+                ],
+                options,
+            );
             return !outcome.dismissed && outcome.result === 'confirm';
         }
     }
@@ -5820,6 +5883,65 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         }
     }
 
+    /**
+     * A menu of commands on the native popover platform: the invoker named by
+     * `for` toggles it and light dismiss and Escape come from the browser, while
+     * the element adds the menu semantics and the keyboard protocol.
+     *
+     * The items are the buttons and links written inside it, kept as they are and
+     * given their menu role and their place in the roving focus. Activation is the
+     * item's own click, which the element only follows by closing.
+     */
+    class Menu extends index_mjs.ParsedElement {
+        static attributes = ['for'];
+        render() {
+            const named = this.declared('for');
+            const invoker = named ? document.getElementById(named) : null;
+            if (!invoker) {
+                throw new Error(
+                    `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 });
+            this.#mark();
+            this.addEventListener('click', (evt) => {
+                const target = /** @type HTMLElement */ (evt.target);
+                if (this.items.some((item) => item === target || item.contains(target))) {
+                    this.hidePopover();
+                }
+            });
+        }
+        /**
+         * The commands, in the order the arrows walk them: the menu's own buttons
+         * and links, minus the disabled and hidden ones, which keep their role and
+         * leave the walk.
+         */
+        get items() {
+            return this.#mark().filter((item) => !item.hasAttribute('disabled') && !item.hasAttribute('hidden'));
+        }
+        /**
+         * Gives every button and link of the menu its item role and takes it out of
+         * the tab order, and answers them. Read on every gesture as well as at the
+         * render, so a menu a page fills or empties later needs no rewiring.
+         */
+        #mark() {
+            const all = /** @type HTMLElement[] */ ([...this.querySelectorAll(':scope > button, :scope > a[href]')]);
+            for (const item of all) {
+                if (!item.hasAttribute('role')) {
+                    item.setAttribute('role', 'menuitem');
+                }
+                item.tabIndex = -1;
+            }
+            return all;
+        }
+    }
+
     const SEVERITIES = ['info', 'success', 'warning', 'error'];
 
     //the regions alive in the document: the show-toast listener is wired once and
@@ -6465,6 +6587,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                 .defineElement('ful-tooltip', Tooltip)
                 .defineElement('ful-dialog', Dialog)
                 .defineElement('ful-drawer', Drawer)
+                .defineElement('ful-menu', Menu)
                 .defineElement('ful-toasts', Toasts)
                 .defineElement('ful-tabs', Tabs)
                 .defineElement('ful-accordion', Accordion)
@@ -6529,6 +6652,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
     exports.LocalDate = LocalDate;
     exports.LocalDateFilter = LocalDateFilter;
     exports.LocalStorage = LocalStorage;
+    exports.Menu = Menu;
     exports.NumberFilter = NumberFilter;
     exports.Pagination = Pagination;
     exports.Plugin = Plugin;