@optionfactory/fml 9.0.0-rc30 → 9.0.0-rc31

package/dist/ful.mjs

@@ -1,4 +1,4 @@
-import { ParsedElement, Attributes, Rendering, Localization, BoundedCache, Fragments, Templates, Nodes } from './ftl.mjs';
+import { ParsedElement, Attributes, Fragments, Rendering, Localization, BoundedCache, Templates, Nodes } from './ftl.mjs';
 import { Failure, HttpClient } from './httpc.mjs';
 
 /**
@@ -798,12 +798,13 @@ class Bindings {
  *
  * The claim setters, the validity protocol and the aria wiring all act on the
  * pieces, so a field with no native control returns a focusable piece of its
- * own chrome as the control. The claims, `value` and `focus()` are the
- * members that tolerate a not yet rendered element: before the render the
- * `value` getter answers what the rendered field would answer from its current
- * declared state, and a value written then is held and applied by the render
- * (see `_holdValue`). The other members need the pieces and so work only after
- * the render.
+ * own chrome as the control. The claims, `value`, `focus()` and
+ * `setCustomValidity` are the members that tolerate a not yet rendered
+ * element: before the render the `value` getter answers what the rendered
+ * field would answer from its current declared state, a value written then is
+ * held and applied by the render (see `_holdValue`), and a problem reported
+ * then is shown by it. The other members need the pieces and so work only
+ * after the render.
  *
  * The inner controls carry `form=""`, so the host is the only element the form
  * sees. Enter pressed in an inner `<input>` of any type but `file`, `button`,
@@ -841,6 +842,8 @@ class Field extends ParsedElement {
     #also = [];
     /** @type {{ value: any } | null} the value written before the render, which the render applies */
     #held = null;
+    /** @type {{ error: string, context?: string } | null} the problem reported before the render, which the render shows */
+    #reported = null;
     /** Sets the internals' role from the subclass's `static ROLE`. */
     constructor() {
         super();
@@ -905,6 +908,11 @@ class Field extends ParsedElement {
             this.#pendingFocus = null;
             control.focus(options);
         }
+        if (this.#reported !== null) {
+            const { error, context } = this.#reported;
+            this.#reported = null;
+            this.setCustomValidity(error, context);
+        }
     }
     /**
      * @param {EventTarget} el
@@ -984,11 +992,17 @@ class Field extends ParsedElement {
      * field owning a whole subtree overrides this to route the message to the
      * inner control the path names.
      *
-     * Needs the render: before it there is no error region to write to.
+     * Before the render there is no error region to write to: a message is
+     * kept (the last one wins) and shown once the field has rendered, and a
+     * clear drops the one kept. A field whose render failed shows nothing.
      * @param {string} [error] the message, empty or missing to clear
      * @param {string} [context] the path below this field's name, '' on an exact match
      */
     setCustomValidity(error, context) {
+        if (!this.#fieldError) {
+            this.#reported = error ? { error, context } : null;
+            return;
+        }
         Attributes.set(this.#announces ?? this.#control, 'aria-invalid', error ? 'true' : null);
         if (!error) {
             this.internals.setValidity({});
@@ -1199,11 +1213,16 @@ class Field extends ParsedElement {
     /**
      * Calls `_build(conf)` and wires the pieces it answers. When `_build`
      * returns a promise the pieces are wired once it settles; a field that
-     * builds synchronously renders synchronously.
+     * builds synchronously renders synchronously. A default slot holding
+     * nothing but whitespace is emptied first, so the label it becomes is
+     * `:empty` and takes no row.
      * @param {{ slots: Record<string, DocumentFragment> | undefined }} conf
      * @returns {void | Promise<void>}
      */
     render(conf) {
+        if (conf.slots?.default && Fragments.isBlank(conf.slots.default)) {
+            conf.slots.default.replaceChildren();
+        }
         const built = /** @type {any} */ (this._build(conf));
         if (built instanceof Promise) {
             return built.then((pieces) => this.#wire(pieces));
@@ -2543,7 +2562,8 @@ class InputInstant extends Input {
  * size and count limits it declares.
  *
  * The `dropzone` and `item-list` attributes show the dropzone and the list of
- * chosen files. A `dropzone` slot replaces the default dropzone's content, and
+ * chosen files, and `no-input` takes the picker control out of sight, leaving
+ * it to the keyboard and to assistive technology. A `dropzone` slot replaces the default dropzone's content, and
  * an `items` slot holding a template replaces the stock item, rendered with the
  * same `files` overlay so that it reads the File objects it lists. Clicking the
  * dropzone opens the picker, and the host carries a `dragover` attribute while
@@ -2586,6 +2606,7 @@ class InputFile extends Input {
         'multiple:presence',
         'item-list:presence',
         'dropzone:presence',
+        'no-input:presence',
         'max-files:number',
         'max-file-size:number',
         'max-total-size:number',
@@ -2837,7 +2858,7 @@ class InputFile extends Input {
      * @returns {string[]|string|null}
      */
     get value() {
-        const names = Array.from(this._input.files).map((f) => f.name);
+        const names = Array.from(this.files).map((f) => f.name);
         return this.multiple ? names : (names[0] ?? null);
     }
     /**
@@ -2860,7 +2881,7 @@ class InputFile extends Input {
      * The size of the selected files together, in bytes.
      * @returns {number}
      */
-    get totalsize() {
+    get totalSize() {
         return Array.from(this.files).reduce((a, f) => a + f.size, 0);
     }
     #maxFiles;
@@ -2935,6 +2956,23 @@ class InputFile extends Input {
         this.#useDropzone = v;
         this.reflectTo('dropzone', v);
     }
+    #noInput;
+    /**
+     * Whether the picker control is taken out of sight, the dropzone and the
+     * item list carrying the field alone; the stylesheet hides it from the
+     * reflected `no-input` attribute. The control stays in the tab order and
+     * keeps the label, the description and the error, and the dropzone shows
+     * the focus ring while it holds the focus.
+     * @returns {boolean}
+     */
+    get noInput() {
+        return this.#noInput;
+    }
+    /** @param {boolean} v */
+    set noInput(v) {
+        this.#noInput = v;
+        this.reflectTo('no-input', v);
+    }
 }
 
 /** the viewport's breathing room when clamping, in pixels */
@@ -4698,9 +4736,7 @@ class RadioGroup extends Field {
     static ROLE = 'radiogroup';
     static template = `
         <fieldset>
-            <legend>
-                {{{{ slots.default }}}}
-            </legend>
+            <legend>{{{{ slots.default }}}}</legend>
             <header data-tpl-if="slots.header">
                 {{{{ slots.header }}}}
             </header>
@@ -4748,6 +4784,9 @@ class RadioGroup extends Field {
         radioEls.forEach((el) => {
             el.remove();
         });
+        if (Fragments.isBlank(slots.default)) {
+            slots.default.replaceChildren();
+        }
         const fragment = this.template().withOverlay({ name, slots, inputsAndLabels }).render();
         this.#fieldset = /** @type HTMLElement */ (fragment.firstElementChild);
         this.#firstRadio = fragment.querySelector('input[type=radio]');
@@ -4903,6 +4942,10 @@ class Checkbox extends Field {
  * current `order` in the cycle `asc`, `desc`, `null`. The button does not
  * change its own `order`: whoever handles the event sets it, which `ful-table`
  * does once the sorted page has loaded.
+ *
+ * The stylesheet draws an up arrow for `asc` and a down arrow for `desc`. An
+ * unsorted button shows the up arrow dimmed, `asc` being the order its first
+ * activation asks for.
  */
 class SortButton extends ParsedElement {
     static attributes = ['sorter'];
@@ -5479,18 +5522,19 @@ class Table extends ParsedElement {
      * writing the size is not a request to start loading, which is what
      * `autoload` and `reload()` are for. A write that does not change the size
      * does nothing. A write made before the render is replaced by the declared
-     * `page-size` when the table renders.
+     * `page-size` when the table renders, or by ten when that is not a number
+     * above zero.
      *
      * The reload is not awaited: a failure shows the error panel and its
      * rejection is unhandled.
      * @param {number|string|null|undefined} value a number or a string of
      * one, such as a select's value; absent or null is the default of ten,
      * so removing the attribute restores it, and a value that is not a
-     * number is ignored
+     * finite number above zero is ignored
      */
     set pageSize(value) {
         const size = Number(value ?? 10);
-        if (Number.isNaN(size) || size === this.#latestRequest.pageRequest.size) {
+        if (!Number.isFinite(size) || size <= 0 || size === this.#latestRequest.pageRequest.size) {
             return;
         }
         this.#latestRequest = { ...this.#latestRequest, pageRequest: { page: 0, size } };
@@ -5609,10 +5653,11 @@ class Table extends ParsedElement {
         await Rendering.waitForChildren(this);
 
         const maybeForm = /** @type any */ (Nodes.queryChildren(this, 'ful-form'));
+        const declaredSize = this.declared('page-size');
         this.#latestRequest = {
             pageRequest: {
                 page: 0,
-                size: this.declared('page-size') ?? 10,
+                size: Number.isFinite(declaredSize) && declaredSize > 0 ? declaredSize : 10,
             },
             sortRequest: schema.sort,
             filterRequest: maybeForm?.values ?? {},
@@ -5696,7 +5741,10 @@ class Table extends ParsedElement {
      * `aria-busy` is removed, `load:failure` is dispatched (bubbling, not
      * cancelable) with `detail` set to
      * `{ pageRequest, sortRequest, filterRequest, exception }`, and the
-     * returned promise rejects with the same error.
+     * returned promise rejects with the same error. An answer the table cannot
+     * page fails the same way, with an error saying so: one whose `size` is
+     * not a number, as a response of another shape read without a
+     * `response-mapper` is, or a page size of zero.
      *
      * A load started after this one supersedes it: when this one's answer or
      * failure arrives it changes nothing, dispatches nothing and resolves;
@@ -5724,6 +5772,11 @@ class Table extends ParsedElement {
                 return;
             }
             lastPage = Math.max(0, Math.ceil(pageResponse.size / pageRequest.size) - 1);
+            if (!Number.isFinite(lastPage)) {
+                throw new Error(
+                    `ful-table cannot page the loader's answer: it needs { data, size }, size being the total number of rows, and got a size of ${pageResponse.size} for pages of ${pageRequest.size}. A response of another shape needs a response-mapper`,
+                );
+            }
             if (pageRequest.page <= lastPage) {
                 this.#latestRequest = { pageRequest, sortRequest, filterRequest };
                 this.#loaded = true;
@@ -6989,8 +7042,10 @@ class Tooltip extends ParsedElement {
  * failure's problems, one per line, or its message when it carries none.
  */
 class SectionRequests {
-    /** @type {WeakSet<Element>} */
+    /** @type {WeakSet<Element>} the sections a first delivery succeeded for */
     #entered = new WeakSet();
+    /** @type {WeakSet<Element>} the sections whose first delivery is in flight */
+    #entering = new WeakSet();
     /** @type {WeakMap<Element, Claims>} */
     #claims = new WeakMap();
 
@@ -6999,9 +7054,12 @@ class SectionRequests {
      * is given, then `section:requested:<name>` when a name is given, each
      * bubbling from `host` with the same detail `{ name, section, index, first }`,
      * and awaits every answer attached to any of them. `first` is true until a
-     * request for the section is answered by at least one listener, so a request
-     * nobody listened to does not spend it. A request with answers removes the
-     * error a previous failure painted before it waits.
+     * delivery of the section succeeds: a request nobody listened to does not
+     * spend it, and neither does one whose answers failed, so the next request
+     * is a first one again. While a first delivery is in flight a newer request
+     * for the same section carries `first` false, so the content is not
+     * delivered twice. A request with answers removes the error a previous
+     * failure painted before it waits.
      * @param {Element} host the component the events are dispatched on
      * @param {Element} section the element the answers deliver into
      * @param {string|null} name the section's `data-step`, when it has one
@@ -7012,7 +7070,7 @@ class SectionRequests {
      * problems in the section unless a newer request superseded this one
      */
     async request(host, section, name, index) {
-        const first = !this.#entered.has(section);
+        const first = !this.#entered.has(section) && !this.#entering.has(section);
         const detail = { name, section, index, first };
         const types = [
             'section:requested',
@@ -7030,7 +7088,9 @@ class SectionRequests {
         if (promises.length === 0) {
             return undefined;
         }
-        this.#entered.add(section);
+        if (first) {
+            this.#entering.add(section);
+        }
         let claims = this.#claims.get(section);
         if (!claims) {
             claims = new Claims();
@@ -7046,13 +7106,20 @@ class SectionRequests {
             }
         });
         try {
-            return await Promise.all(promises);
+            const answers = await Promise.all(promises);
+            if (first) {
+                this.#entered.add(section);
+            }
+            return answers;
         } catch (cause) {
             if (owned()) {
                 this.#paintError(section, cause);
             }
             throw cause;
         } finally {
+            if (first) {
+                this.#entering.delete(section);
+            }
             cancelAnimationFrame(frame);
             if (owned()) {
                 section.toggleAttribute('loading', false);
@@ -7169,15 +7236,27 @@ class DialogSections {
     /**
      * Calls `dismiss` when a press and its release both land on the backdrop,
      * so a selection dragged out of the panel and released outside does not.
+     * The backdrop is where the pointer is outside the dialog's rectangle: a
+     * part of the panel no child covers, the room around the error section
+     * for one, is the panel.
      * @param {() => void} dismiss
      */
     onBackdrop(dismiss) {
+        const onBackdrop = (/** @type MouseEvent */ e) => {
+            if (e.target !== this.#dialog) {
+                return false;
+            }
+            const panel = this.#dialog.getBoundingClientRect();
+            return (
+                e.clientX < panel.left || e.clientX > panel.right || e.clientY < panel.top || e.clientY > panel.bottom
+            );
+        };
         let pressedOutside = false;
         this.#dialog.addEventListener('mousedown', (e) => {
-            pressedOutside = e.target === this.#dialog;
+            pressedOutside = onBackdrop(e);
         });
         this.#dialog.addEventListener('click', (e) => {
-            if (pressedOutside && e.target === this.#dialog) {
+            if (pressedOutside && onBackdrop(e)) {
                 dismiss();
             }
         });
@@ -7454,7 +7533,7 @@ class Dialog extends ParsedElement {
      * opening, hides the error and loading sections, and dispatches
      * `section:requested` on the element (bubbling, with
      * `detail: { section, first, name: null, index: null }`, `section` being
-     * the body and `first` true only on the first answered request), so a
+     * the body and `first` true until a delivery succeeds), so a
      * listener can fill the body. A failed request is painted into the body
      * and does not reject. On a dialog already open nothing is shown or
      * requested, and the call waits for the same ending as the calls before it;
@@ -7706,11 +7785,7 @@ class Drawer extends ParsedElement {
     #answer = null;
     #resolvers = [];
     #closing = false;
-    #slideOutEnded = (/** @type AnimationEvent */ e) => {
-        if (e.target === this.#dialog) {
-            this.#closeNow();
-        }
-    };
+    #slides = new Claims();
     /**
      * @param {{ slots: Record<string, DocumentFragment> }} c
      */
@@ -7837,7 +7912,7 @@ class Drawer extends ParsedElement {
      * opening, hides the error and loading sections, and dispatches
      * `section:requested` on the element (bubbling, with
      * `detail: { section, first, name: null, index: null }`, `section` being
-     * the content section and `first` true only on the first answered request),
+     * the content section and `first` true until a delivery succeeds),
      * so a listener can fill the content. A failed request is painted into the
      * content section and does not reject. On a drawer already open nothing is
      * shown or requested, except that one sliding out stops and stays open,
@@ -7888,11 +7963,13 @@ class Drawer extends ParsedElement {
     /**
      * Slides the drawer out and closes it when the animation ends, setting the
      * `closing` attribute on the native dialog meanwhile; the `close` event is
-     * dispatched then, after this call has returned. Where the user prefers
-     * reduced motion, or no animation runs, it closes at once. A non-empty
-     * result answers as the button carrying that `data-result` would; no
-     * result, or an empty one, is a dismissal. Does nothing on a drawer that is
-     * closed or already sliding out.
+     * dispatched then, after this call has returned. An animation the page
+     * cancels, by hiding the drawer or an ancestor of it, closes it as one
+     * that ended does. Where the user prefers reduced motion, or no animation
+     * runs, it closes at once. A non-empty result answers as the button
+     * carrying that `data-result` would; no result, or an empty one, is a
+     * dismissal. Does nothing on a drawer that is closed or already sliding
+     * out.
      * @param {string} [result]
      */
     close(result) {
@@ -7907,12 +7984,18 @@ class Drawer extends ParsedElement {
             return;
         }
         this.#dialog.setAttribute('closing', '');
-        if (this.#dialog.getAnimations().length === 0) {
+        const animations = this.#dialog.getAnimations();
+        if (animations.length === 0) {
             this.#closeNow();
             return;
         }
         this.#closing = true;
-        this.#dialog.addEventListener('animationend', this.#slideOutEnded);
+        const slide = this.#slides.take();
+        Promise.allSettled(animations.map((animation) => animation.finished)).then(() => {
+            if (!slide.stale) {
+                this.#closeNow();
+            }
+        });
     }
     #closeNow() {
         this.#stopSlidingOut();
@@ -7920,7 +8003,7 @@ class Drawer extends ParsedElement {
     }
     #stopSlidingOut() {
         this.#closing = false;
-        this.#dialog.removeEventListener('animationend', this.#slideOutEnded);
+        this.#slides.invalidate();
         this.#dialog.removeAttribute('closing');
     }
     /** @returns {boolean} whether this call is the one that opened the modal */
@@ -8465,7 +8548,7 @@ class Tabs extends ParsedElement {
     }
     /**
      * Fires the section requests again for a panel, whether it is visible or
-     * not, with `first` false once an earlier request was answered.
+     * not, with `first` false once an earlier delivery succeeded.
      * @param {number | Element} ref the panel's index, or the panel itself
      * @returns {Promise<any[] | undefined> | undefined} a promise resolving to
      * the answers, or to undefined when nobody listened or the delivery
@@ -8688,7 +8771,7 @@ class Wizard extends ParsedElement {
     }
     /**
      * Fires the section requests again for a section, whether it is current or
-     * not, with `first` false once an earlier request was answered.
+     * not, with `first` false once an earlier delivery succeeded.
      * @param {string | Element} ref the section's `data-step`, or the section
      * itself
      * @returns {Promise<any[] | undefined> | undefined} a promise resolving to
@@ -8967,8 +9050,11 @@ class Plugin {
     /**
      * @param {{ language?: string, translations?: Record<string, any>, httpClient?: HttpClient }} [options]
      * `language` is fixed for the page: a full BCP-47 tag or a primary subtag,
-     * defaulting to `navigator.language`, then to 'en'. Its primary subtag,
-     * lowercased, picks the built-in translations (en, it, es, fr); the messages
+     * defaulting to `navigator.language`, then to 'en', an empty one included.
+     * It is canonicalized (`IT-it` and `it_IT` both read `it-IT`), and one that
+     * is no language tag at all throws here, rather than at the first message
+     * or number formatted in it. Its primary subtag picks the built-in
+     * translations (en, it, es, fr); the messages
      * are the english ones, overridden by that language's, overridden by
      * `translations`, so a language without built-in translations reads in
      * english. `translations` is a flat map of keys to messages: reword built-in
@@ -8976,9 +9062,18 @@ class Plugin {
      * `httpClient` is the client every ful component fetches through, registered
      * as the `http-client` component; without one, `configure` builds a client
      * that sends the csrf token and navigates to '/' on a 401 response.
+     * @throws {RangeError} when `language` is not a language tag
      */
     constructor(options = {}) {
-        this.#language = options.language ?? navigator?.language ?? 'en';
+        const language = options.language || navigator?.language || 'en';
+        try {
+            // unicode locale identifiers separate subtags with an underscore too, Intl takes the dash alone
+            this.#language = Intl.getCanonicalLocales(String(language).replaceAll('_', '-'))[0];
+        } catch {
+            throw new RangeError(
+                `Plugin: language '${language}' is not a language tag: pass a BCP-47 tag such as 'it' or 'it-IT', or leave it out for the browser's language`,
+            );
+        }
         this.#translations = options.translations ?? {};
         this.#httpClient = options.httpClient ?? null;
     }
@@ -8987,7 +9082,7 @@ class Plugin {
      * Defines on `registry` the `l10n` module, the `http-client` component,
      * every `ful-*` element, the `loaders:select`, `loaders:form` and
      * `loaders:table` components, and an overlay publishing `l10n` (the merged
-     * messages) and `locale` (the `language` as given) to every template.
+     * messages) and `locale` (the `language`, canonicalized) to every template.
      * @param {{ defineModule(name: string, module: any): any, defineComponent(name: string, component: any): any, defineElement(tag: string, klass: CustomElementConstructor): any, defineOverlay(...data: any[]): any }} registry
      * the ftl `Registry`, each of those methods answering the registry itself
      * @returns {void}
@@ -8995,7 +9090,7 @@ class Plugin {
     configure(registry) {
         const httpClient =
             this.#httpClient ?? HttpClient.builder().withCsrfToken().withRedirectOnUnauthorized('/').build();
-        const language = this.#language.split('-')[0].toLowerCase();
+        const language = this.#language.split('-')[0];
         const l10n = { ...BUILTIN.en, ...BUILTIN[language], ...this.#translations };
         registry
             .defineModule('l10n', Localization)
@@ -9039,5 +9134,5 @@ class Plugin {
     }
 }
 
-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, PageLeave, 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, PageLeave, Pagination, Plugin, RadioGroup, Select, SelectLoader, SessionStorage, SortButton, Table, TableLoader, Tabs, TextFilter, Timing, Toasts, Tooltip, VersionedLocalStorage, VersionedSessionStorage, Wizard, describable };
 //# sourceMappingURL=ful.mjs.map