@optionfactory/fml 9.0.0-rc3 → 9.0.0-rc5

package/dist/ful.d.mts

@@ -102,6 +102,41 @@ declare class Claims {
     /** Supersedes every claim without holding a new one. */
     invalidate(): void;
 }
+export type Describable = {
+    describedBy(el: HTMLElement): boolean;
+};
+/**
+ * The protocol by which content standing inside a field becomes part of the
+ * accessible description of that field's control.
+ *
+ * A field owns its control's `aria-describedby`: it is the only thing that
+ * knows which element the description belongs on, and it already writes the
+ * entry for its own error region. Content the author slotted into the field
+ * cannot write that attribute itself without becoming a second owner of it, and
+ * it cannot be wired by the field either, because a slotted custom element
+ * renders after the field has mounted and has nothing to point at when the
+ * field looks.
+ *
+ * So the content asks, once it has something to offer. `describable(el)`
+ * answers the nearest ancestor that accepts a description, and the caller hands
+ * its element to that ancestor's `describedBy`, which answers whether it was
+ * taken. Nothing here names a field or a tooltip: the relation is expressed as
+ * a capability, so the two ends need not import each other, which matters
+ * because the library's own arrow runs from the forms to the disclosures.
+ *
+ * The lookup lives here rather than at its one call site so the protocol has a
+ * name, a place to be documented and a single definition to change.
+ */
+/**
+ * @typedef {{ describedBy(el: HTMLElement): boolean }} Describable
+ */
+/**
+ * The nearest ancestor of `el` that accepts elements into the description of
+ * whatever it considers its control, or null when nothing in the ancestry does.
+ * @param {Element} el
+ * @returns {(Element & Describable) | null}
+ */
+declare const describable: (el: Element) => (Element & Describable) | null;
 /**
  * Sleeping, debouncing and throttling. Debounce and throttle both return the
  * wrapped function together with a cancel function.
@@ -226,6 +261,34 @@ declare class Field extends ParsedElement {
     /** the role the element internals carry, 'presentation' unless the control is its own */
     static ROLE: string;
     constructor();
+    /**
+     * Adds an element to the accessible description of the field's control and
+     * answers whether the field took it.
+     *
+     * A field takes one whenever it is offered, before its own render as
+     * readily as after: content slotted into a field is a custom element of its
+     * own and may upgrade on either side of the field it stands in, which
+     * happens in both directions in practice, a tooltip beating an async select
+     * to its render while losing to a plain input. A description handed over
+     * early waits here and is written the moment the field has somewhere to
+     * write it, so the caller never has to know the order.
+     *
+     * The reference lands on the element handed over rather than on a wrapper
+     * around it: a hidden element is included in a description only where it is
+     * named directly, and content that reaches the description through a
+     * wrapper is skipped while it is hidden. A popover closed until someone
+     * opens it is exactly that, so the caller passes the popover itself.
+     *
+     * An attribute rather than `ariaDescribedByElements`: the property reflects
+     * to nothing, so the description would live in the accessibility tree alone
+     * and vanish entirely on a browser without aria element reflection.
+     *
+     * This is the field's half of the description protocol; `describable` in
+     * `ful/descriptions.mjs` is the half the content uses to find the field.
+     * @param {HTMLElement} el
+     * @returns {boolean}
+     */
+    describedBy(el: HTMLElement): boolean;
     focus(options: any): void;
     /**
      * Clears or reports one validation problem: the text lands on the field's
@@ -336,8 +399,9 @@ declare class Field extends ParsedElement {
      *   three claims reach it
      * - `error` is the field's live region
      * - `label`, when given, names the control and focuses it on click
-     * - `described` moves the error's description off the control and onto
-     *   another element, the host where no single control can carry it
+     * - `described` moves the description off the control and onto another
+     *   element, the host where no single control can carry it: the error
+     *   region and anything `describedBy` is later handed both land there
      * - `claims` moves the three claims onto a wrapper the field disables as a
      *   whole, leaving focus and aria on the control
      * - `announces` is the element whose role carries `aria-readonly` and
@@ -1005,8 +1069,24 @@ declare class BooleanFilter extends Field {
     get disabled(): boolean;
     set disabled(d: boolean);
 }
-/** An info icon button toggling a popover with a short explanation. */
+/**
+ * An info icon button toggling a popover with a short explanation.
+ *
+ * The marker is the page's `config.icon`, and the `icon` attribute names a
+ * `ful-icon` for the tooltip that means something other than plain information:
+ * a caveat, a warning, a setting. A name the library does not paint is the
+ * page's own, declared as `ful-icon[name='...'] { mask-image: ... }`.
+ *
+ * `describes` is for the tooltip standing in a field: the note becomes part of
+ * the accessible description of that field's control, so it is announced on
+ * reaching the field rather than only on opening the marker, and the marker
+ * leaves the tab order, so a form of hinted fields costs no extra keystrokes to
+ * walk. The marker stays clickable, and stays a tab stop wherever the note was
+ * not taken, a tooltip claiming `describes` outside a field among them: the
+ * stop only goes where something else delivers the content.
+ */
 declare class Tooltip extends ParsedElement {
+    #private;
     static slots: boolean;
     static attributes: string[];
     static config: {
@@ -1017,7 +1097,26 @@ declare class Tooltip extends ParsedElement {
         slots: any;
     }): void;
 }
-/** A modal dialog on the native platform, open()/ask() resolving with the closer's data-result. */
+/**
+ * A modal dialog on the native platform, open()/ask() resolving with the
+ * closer's data-result.
+ *
+ * The header carries a close button, as the drawer's does: Escape dismisses a
+ * modal on its own, but nothing says so, and a dialog whose only exit is a key
+ * you have to know about leaves a pointer with nowhere to go. It answers the way
+ * Escape does, with null.
+ *
+ * `requires-answer` is for the dialog that must be answered: the close button is not
+ * rendered and Escape is refused, so the only way out is a button that carries a
+ * result. It has to be both, a close button withheld while Escape still worked
+ * being decoration rather than a rule.
+ *
+ * The chrome is reachable by class as well as by tag, so a plain `<dialog
+ * class="ful-dialog">` written by a page gets the same look whatever its
+ * structure: the tag form matches a direct child, and `ful-dialog-header`,
+ * `ful-dialog-body` and `ful-dialog-footer` match at any depth, which is what a
+ * dialog whose content is wrapped in a form needs.
+ */
 declare class Dialog extends ParsedElement {
     #private;
     static attributes: string[];
@@ -1195,6 +1294,6 @@ declare class Plugin {
     });
     configure(registry: any): void;
 }
-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 { Accordion, Anchors, AsyncEvents, Bindings, BooleanFilter, Checkbox, Claims, CompareFilter, Dialog, Drawer, Dropdown, Field, Form, FormLoader, Input, InputFile, InputInstant, InputLocalDate, InputLocalTime, Instant, InstantFilter, LocalDate, LocalDateFilter, LocalStorage, NumberFilter, Pagination, Plugin, RadioGroup, Select, SelectLoader, SessionStorage, SortButton, Table, TableLoader, TableSchemaParser, Tabs, TextFilter, Timing, Toasts, Tooltip, VersionedLocalStorage, VersionedSessionStorage, Wizard, describable };
 
 export as namespace ful;

package/dist/ful.iife.js

@@ -233,6 +233,48 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         }
     }
 
+    /**
+     * The protocol by which content standing inside a field becomes part of the
+     * accessible description of that field's control.
+     *
+     * A field owns its control's `aria-describedby`: it is the only thing that
+     * knows which element the description belongs on, and it already writes the
+     * entry for its own error region. Content the author slotted into the field
+     * cannot write that attribute itself without becoming a second owner of it, and
+     * it cannot be wired by the field either, because a slotted custom element
+     * renders after the field has mounted and has nothing to point at when the
+     * field looks.
+     *
+     * So the content asks, once it has something to offer. `describable(el)`
+     * answers the nearest ancestor that accepts a description, and the caller hands
+     * its element to that ancestor's `describedBy`, which answers whether it was
+     * taken. Nothing here names a field or a tooltip: the relation is expressed as
+     * a capability, so the two ends need not import each other, which matters
+     * because the library's own arrow runs from the forms to the disclosures.
+     *
+     * The lookup lives here rather than at its one call site so the protocol has a
+     * name, a place to be documented and a single definition to change.
+     */
+
+    /**
+     * @typedef {{ describedBy(el: HTMLElement): boolean }} Describable
+     */
+
+    /**
+     * The nearest ancestor of `el` that accepts elements into the description of
+     * whatever it considers its control, or null when nothing in the ancestry does.
+     * @param {Element} el
+     * @returns {(Element & Describable) | null}
+     */
+    const describable = (el) => {
+        for (let at = el.parentElement; at; at = at.parentElement) {
+            if (typeof (/** @type {any} */ (at).describedBy) === 'function') {
+                return /** @type {any} */ (at);
+            }
+        }
+        return null;
+    };
+
     /**
      * Sleeping, debouncing and throttling. Debounce and throttle both return the
      * wrapped function together with a cancel function.
@@ -627,6 +669,9 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         /** the role the element internals carry, 'presentation' unless the control is its own */
         static ROLE = 'presentation';
         #control;
+        #described;
+        #descriptions = [];
+        #errorId = null;
         #fieldError;
         #claims;
         #announces;
@@ -678,17 +723,16 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                     true,
                 );
             }
-            //the error region describes the control, or the host where there is no
+            //the description lands on the control, or on the host where there is no
             //single control to describe (a radio group's legend names its fieldset)
+            this.#described = described ?? control;
             if (error) {
-                //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);
+                //named for what it is, the generic id being for whoever brings no name
+                error.id = error.id || index_mjs.Attributes.uid('ful-field-error');
+                this.#errorId = error.id;
             }
+            //anything handed over before the field had a target lands here
+            this.#describe();
             if (label) {
                 Field.#name(this, label, control);
             }
@@ -723,6 +767,61 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         static #submitsOnEnter(el) {
             return el instanceof HTMLInputElement && !['file', 'button', 'submit', 'reset', 'image'].includes(el.type);
         }
+        /**
+         * Adds an element to the accessible description of the field's control and
+         * answers whether the field took it.
+         *
+         * A field takes one whenever it is offered, before its own render as
+         * readily as after: content slotted into a field is a custom element of its
+         * own and may upgrade on either side of the field it stands in, which
+         * happens in both directions in practice, a tooltip beating an async select
+         * to its render while losing to a plain input. A description handed over
+         * early waits here and is written the moment the field has somewhere to
+         * write it, so the caller never has to know the order.
+         *
+         * The reference lands on the element handed over rather than on a wrapper
+         * around it: a hidden element is included in a description only where it is
+         * named directly, and content that reaches the description through a
+         * wrapper is skipped while it is hidden. A popover closed until someone
+         * opens it is exactly that, so the caller passes the popover itself.
+         *
+         * An attribute rather than `ariaDescribedByElements`: the property reflects
+         * to nothing, so the description would live in the accessibility tree alone
+         * and vanish entirely on a browser without aria element reflection.
+         *
+         * This is the field's half of the description protocol; `describable` in
+         * `ful/descriptions.mjs` is the half the content uses to find the field.
+         * @param {HTMLElement} el
+         * @returns {boolean}
+         */
+        describedBy(el) {
+            if (!el) {
+                return false;
+            }
+            if (!el.id) {
+                el.id = index_mjs.Attributes.uid('ful-described');
+            }
+            if (!this.#descriptions.includes(el.id)) {
+                this.#descriptions.push(el.id);
+            }
+            this.#describe();
+            return true;
+        }
+        /**
+         * Writes the description the field has collected, the error region last:
+         * the standing explanations are what the field always says, the problem is
+         * the news. The field owns the attribute outright rather than appending to
+         * whatever is there, so the order does not depend on who arrived when.
+         */
+        #describe() {
+            if (!this.#described) {
+                return;
+            }
+            const ids = [...this.#descriptions, this.#errorId].filter((id) => id);
+            if (ids.length) {
+                this.#described.setAttribute('aria-describedby', ids.join(' '));
+            }
+        }
         focus(options) {
             this.#control?.focus(options);
         }
@@ -959,8 +1058,9 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
          *   three claims reach it
          * - `error` is the field's live region
          * - `label`, when given, names the control and focuses it on click
-         * - `described` moves the error's description off the control and onto
-         *   another element, the host where no single control can carry it
+         * - `described` moves the description off the control and onto another
+         *   element, the host where no single control can carry it: the error
+         *   region and anything `describedBy` is later handed both land there
          * - `claims` moves the three claims onto a wrapper the field disables as a
          *   whole, leaving focus and aria on the control
          * - `announces` is the element whose role carries `aria-readonly` and
@@ -4690,42 +4790,97 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         });
     };
 
-    /** An info icon button toggling a popover with a short explanation. */
+    /**
+     * An info icon button toggling a popover with a short explanation.
+     *
+     * The marker is the page's `config.icon`, and the `icon` attribute names a
+     * `ful-icon` for the tooltip that means something other than plain information:
+     * a caveat, a warning, a setting. A name the library does not paint is the
+     * page's own, declared as `ful-icon[name='...'] { mask-image: ... }`.
+     *
+     * `describes` is for the tooltip standing in a field: the note becomes part of
+     * the accessible description of that field's control, so it is announced on
+     * reaching the field rather than only on opening the marker, and the marker
+     * leaves the tab order, so a form of hinted fields costs no extra keystrokes to
+     * walk. The marker stays clickable, and stays a tab stop wherever the note was
+     * not taken, a tooltip claiming `describes` outside a field among them: the
+     * stop only goes where something else delivers the content.
+     */
     class Tooltip extends index_mjs.ParsedElement {
         static slots = true;
-        static attributes = ['placement'];
+        static attributes = ['placement', 'icon', 'describes:presence'];
         static config = {
             icon: 'info-circle-fill',
         };
         static template = `
-        <button type="button" class="ful-tip" data-ref="trigger" data-tpl-aria-label="#l10n:t('info.tooltip')"><ful-icon data-tpl-name="config.icon" aria-hidden="true"></ful-icon></button>
+        <button type="button" class="ful-tip" data-ref="trigger" data-tpl-aria-label="#l10n:t('info.tooltip')"><ful-icon data-tpl-name="icon ?? config.icon" aria-hidden="true"></ful-icon></button>
         <ful-note popover data-ref="content">{{{{ slots.default }}}}</ful-note>
     `;
         render({ slots }) {
-            const fragment = this.template().withOverlay({ slots }).render();
+            const fragment = this.template().withOverlay({ slots, icon: this.declared('icon') }).render();
             const trigger = fragment.querySelector('[data-ref=trigger]');
             const content = fragment.querySelector('[data-ref=content]');
             //placed here rather than by the anchor css: the note draws a callout that
             //has to point at the trigger wherever the viewport left room for the note,
             //which is a measurement the stylesheet cannot make for a pseudo-element
             Anchors.wire(trigger, content, { prefix: 'ful-tooltip', invoke: true, expanded: true, handPlace: true });
-            const placement = this.declared('placement');
-            if (placement) {
-                content.setAttribute('placement', placement);
-            }
+            //above the marker by default: a note opening downwards covers the control
+            //the marker explains, the marker riding the field's label
+            content.setAttribute('placement', this.declared('placement') ?? 'top');
             this.replaceChildren(fragment);
+            if (this.declared('describes')) {
+                Tooltip.#describe(this, trigger, content);
+            }
+        }
+        /**
+         * Offers the note to the field the tooltip stands in, and takes the trigger
+         * out of the tab order only where the offer was accepted: a note nothing
+         * carries is reachable by the keyboard through the marker alone, so
+         * dropping the stop there would leave it reachable by nothing at all.
+         *
+         * The offer goes through the description protocol rather than naming a
+         * field, the library's own arrow running from the forms to the disclosures.
+         */
+        static #describe(tooltip, trigger, content) {
+            if (!describable(tooltip)?.describedBy(content)) {
+                console.warn('a ful-tooltip declares describes but stands in nothing that takes a description', tooltip);
+                return;
+            }
+            trigger.tabIndex = -1;
         }
     }
 
-    /** A modal dialog on the native platform, open()/ask() resolving with the closer's data-result. */
+    /**
+     * A modal dialog on the native platform, open()/ask() resolving with the
+     * closer's data-result.
+     *
+     * The header carries a close button, as the drawer's does: Escape dismisses a
+     * modal on its own, but nothing says so, and a dialog whose only exit is a key
+     * you have to know about leaves a pointer with nowhere to go. It answers the way
+     * Escape does, with null.
+     *
+     * `requires-answer` is for the dialog that must be answered: the close button is not
+     * rendered and Escape is refused, so the only way out is a button that carries a
+     * result. It has to be both, a close button withheld while Escape still worked
+     * being decoration rather than a rule.
+     *
+     * The chrome is reachable by class as well as by tag, so a plain `<dialog
+     * class="ful-dialog">` written by a page gets the same look whatever its
+     * structure: the tag form matches a direct child, and `ful-dialog-header`,
+     * `ful-dialog-body` and `ful-dialog-footer` match at any depth, which is what a
+     * dialog whose content is wrapped in a form needs.
+     */
     class Dialog extends index_mjs.ParsedElement {
-        static attributes = ['header'];
+        static attributes = ['header', 'requires-answer:presence'];
         static slots = true;
         static template = `
         <dialog data-ref="dialog" class="ful-dialog">
-            <header data-tpl-if="header"><h2>{{ header }}</h2></header>
-            <div data-ref="body">{{{{ slots.default }}}}</div>
-            <footer>
+            <header data-tpl-if="header || !requiresAnswer" class="ful-dialog-header">
+                <h2 data-tpl-if="header">{{ header }}</h2>
+                <button data-tpl-if="!requiresAnswer" type="button" data-ref="close" data-tpl-aria-label="#l10n:t('dialog.close')"><ful-icon name="x-lg" aria-hidden="true"></ful-icon></button>
+            </header>
+            <div data-ref="body" class="ful-dialog-body">{{{{ slots.default }}}}</div>
+            <footer class="ful-dialog-footer">
                 <button type="button" data-ref="acknowledge" data-result="acknowledged" data-tpl-if="!slots.buttons" data-tpl-aria-label="#l10n:t('dialog.acknowledge')">{{ #l10n:t('dialog.acknowledge') }}</button>
                 {{{{ slots.buttons }}}}
             </footer>
@@ -4736,8 +4891,9 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         #requests = new SectionRequests();
         #resolvers = [];
         render({ slots }) {
+            const requiresAnswer = this.declared('requires-answer');
             const fragment = this.template()
-                .withOverlay({ slots, header: this.declared('header') ?? '' })
+                .withOverlay({ slots, header: this.declared('header') ?? '', requiresAnswer })
                 .render();
             this.#dialog = fragment.querySelector('[data-ref=dialog]');
             this.#body = fragment.querySelector('[data-ref=body]');
@@ -4755,6 +4911,17 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                     this.#dialog.close(result);
                 }
             });
+            //dismissal, not an answer: the waiters are settled with null, as Escape does.
+            //Optional because a subclass overriding the template owns what it renders
+            fragment
+                .querySelector('[data-ref=close]')
+                ?.addEventListener('click', () => this.#dialog.close(''));
+            if (requiresAnswer) {
+                //the platform's own dismissal, refused where the dialog must be
+                //answered: cancel fires for Escape and for a close request the
+                //browser makes on its own, and preventing it leaves the dialog open
+                this.#dialog.addEventListener('cancel', (/** @type any */ e) => e.preventDefault());
+            }
             this.replaceChildren(fragment);
             wireTargets();
         }
@@ -5343,6 +5510,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         'filters.boolean.false': 'No',
         'info.tooltip': 'More information',
         'dialog.acknowledge': 'Got it',
+        'dialog.close': 'Close',
         'drawer.close': 'Close',
         'spinner.loading': 'Loading…',
         'toast.region': 'Notifications',
@@ -5384,6 +5552,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         'filters.boolean.false': 'No',
         'info.tooltip': 'Maggiori informazioni',
         'dialog.acknowledge': 'Ho capito',
+        'dialog.close': 'Chiudi',
         'drawer.close': 'Chiudi',
         'spinner.loading': 'Caricamento…',
         'toast.region': 'Notifiche',
@@ -5425,6 +5594,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         'filters.boolean.false': 'No',
         'info.tooltip': 'Más información',
         'dialog.acknowledge': 'Entendido',
+        'dialog.close': 'Cerrar',
         'drawer.close': 'Cerrar',
         'spinner.loading': 'Cargando…',
         'toast.region': 'Notificaciones',
@@ -5469,6 +5639,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         'filters.boolean.false': 'Non',
         'info.tooltip': 'Plus d’informations',
         'dialog.acknowledge': 'J’ai compris',
+        'dialog.close': 'Fermer',
         'drawer.close': 'Fermer',
         'spinner.loading': 'Chargement…',
         'toast.region': 'Notifications',
@@ -5598,6 +5769,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
     exports.VersionedLocalStorage = VersionedLocalStorage;
     exports.VersionedSessionStorage = VersionedSessionStorage;
     exports.Wizard = Wizard;
+    exports.describable = describable;
 
     return exports;