@optionfactory/fml 9.0.0-rc19 → 9.0.0-rc20

package/dist/ful.d.mts

@@ -123,6 +123,20 @@ declare class AsyncEvents {
      */
     static mixInto(...classes: Function[]): void;
 }
+/**
+ * Asks before the page is left, through the browser's own `beforeunload`
+ * prompt.
+ */
+declare class PageLeave {
+    /**
+     * Asks before the page is left while `isDirty()` answers true, until
+     * `signal` aborts. The browser words the prompt, and asks only once the
+     * user has interacted with the page.
+     * @param {() => boolean} isDirty
+     * @param {AbortSignal} [signal]
+     */
+    static guard(isDirty: () => boolean, signal?: AbortSignal): void;
+}
 export type Claim = {
     readonly stale: boolean;
 };
@@ -722,6 +736,10 @@ declare class FormLoader {
  *
  * A native submit, by a button or by Enter in a field, is stopped and runs
  * `submit` instead.
+ *
+ * `track-changes` keeps track of the edits not saved yet (see `dirty`), and
+ * `guard-leave`, which implies it, asks before the page is left while there
+ * are any.
  */
 declare class Form extends ParsedElement {
     #private;
@@ -731,6 +749,8 @@ declare class Form extends ParsedElement {
     form: any;
     /** Builds the native form and moves the element's children into it. */
     render(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     /**
      * Runs the submit pipeline, with the spinner up for its whole length:
      *
@@ -747,7 +767,9 @@ declare class Form extends ParsedElement {
      *    loader's `submit` as its third argument. A listener may replace
      *    `request` on the detail
      * 6. has the loader `submit` the request and `transform` the response
-     * 7. fires `submit:success` with `{ submitter, values, request, response }`,
+     * 7. under `track-changes`, commits the values extracted at step 2 (see
+     *    `commit`): an edit made while the submit was in flight stays unsaved
+     * 8. fires `submit:success` with `{ submitter, values, request, response }`,
      *    `response` being the transformed one
      *
      * Anything thrown from step 1 on, a missing loader or a throwing mapper
@@ -763,8 +785,43 @@ declare class Form extends ParsedElement {
      * @returns {Promise<void>} settling once the submit has finished, whatever its outcome
      */
     submit(submitter?: HTMLElement): Promise<void>;
-    /** Resets the native form, each field returning to its default value. */
+    /**
+     * Resets the native form, each field returning to its default value. Under
+     * `track-changes` every control counts as edited: the form is dirty if the
+     * defaults differ from what was last committed.
+     */
     reset(): void;
+    /**
+     * Whether, under `track-changes`, a control the user edited since the last
+     * commit holds a value other than the one committed. An edit is what the
+     * controls report as one: an `input` or a `change` bubbling from a control
+     * of this form (0019), so assigning `value`, a select's vocabulary dropping
+     * a key or a section delivering its fields is not one, and an edit undone
+     * is no longer dirty. A control the last commit did not see compares with
+     * its value when it was first focused. Always false without
+     * `track-changes`.
+     *
+     * While dirty, the host matches `:state(dirty)` and the submit buttons of
+     * this form carry `data-ful-dirty`; a change of the state dispatches
+     * `dirty:change` with `{ dirty }`. Both are refreshed at the next frame
+     * after an edit, while the property is exact at any time.
+     * @returns {boolean}
+     */
+    get dirty(): boolean;
+    /**
+     * Records the values of the controls as saved, so that the form is no
+     * longer dirty. A submit commits by itself on success, and the form
+     * commits once its fields have rendered: a page calls this for a save of
+     * its own, or after writing the values it loaded. Does nothing without
+     * `track-changes`.
+     */
+    commit(): void;
+    /**
+     * Counts a control as edited by the user, for a value the page writes on
+     * the user's behalf: assigning `value` reports nothing, as 0019 wants.
+     * @param {Element} el the control, or an element inside it
+     */
+    edited(el: Element): void;
     /**
      * Marks the form busy or releases it. Calls nest: only the first
      * `spinner(true)` and the matching last `spinner(false)` act, so a caller's
@@ -840,7 +897,9 @@ declare class Form extends ParsedElement {
  *   datetime-local, month or week control fires its native `change` while its
  *   segments are typed, as soon as they make a valid value; for those the field
  *   reports when the control is left or Enter is pressed, at once for a value
- *   picked from the browser's picker, and never a half-typed value.
+ *   picked from the browser's picker, never with the dates a year passes
+ *   through while it is typed. A control left incomplete reads as `null`, as
+ *   the native one does.
  *
  * A subclass template may render more than one control, as the compare filters
  * render the two bounds of a range: the first is `_input`, the one the field is
@@ -3364,6 +3423,6 @@ declare class Plugin {
         defineOverlay(...data: any[]): 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, Menu, 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, PageLeave, 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

@@ -231,6 +231,31 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
         }
     }
 
+    /**
+     * Asks before the page is left, through the browser's own `beforeunload`
+     * prompt.
+     */
+    class PageLeave {
+        /**
+         * Asks before the page is left while `isDirty()` answers true, until
+         * `signal` aborts. The browser words the prompt, and asks only once the
+         * user has interacted with the page.
+         * @param {() => boolean} isDirty
+         * @param {AbortSignal} [signal]
+         */
+        static guard(isDirty, signal) {
+            window.addEventListener(
+                'beforeunload',
+                (evt) => {
+                    if (isDirty()) {
+                        evt.preventDefault();
+                    }
+                },
+                { signal },
+            );
+        }
+    }
+
     /**
      * A hold on one generation of a `Claims`: `stale` turns true once a later
      * `take()` or `invalidate()` on it starts a newer generation.
@@ -1318,6 +1343,10 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
      *
      * A native submit, by a button or by Enter in a field, is stopped and runs
      * `submit` instead.
+     *
+     * `track-changes` keeps track of the edits not saved yet (see `dirty`), and
+     * `guard-leave`, which implies it, asks before the page is left while there
+     * are any.
      */
     class Form extends index_mjs.ParsedElement {
         /** Read once at the upgrade: changing one afterwards has no effect. */
@@ -1330,6 +1359,8 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
             'clear-invalid-on-change:presence',
             'scroll-on-error:presence',
             'autocomplete',
+            'track-changes:presence',
+            'guard-leave:presence',
         ];
         /** The native form holding the fields, created by the render. */
         form;
@@ -1367,6 +1398,27 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                 });
             }
             this.replaceChildren(form);
+            this.#tracking = this.declared('track-changes') || this.declared('guard-leave');
+            if (!this.#tracking) {
+                return;
+            }
+            this.addEventListener('input', (evt) => this.#touch(evt.target));
+            this.addEventListener('change', (evt) => this.#touch(evt.target));
+            this.addEventListener('focusin', (evt) => this.#focus(evt.target));
+            index_mjs.Rendering.waitForChildren(this)
+                .catch(() => undefined)
+                .then(() => this.commit());
+            this.#guard();
+        }
+        connectedCallback() {
+            super.connectedCallback();
+            if (this.#tracking) {
+                this.#guard();
+            }
+        }
+        disconnectedCallback() {
+            this.#leave?.abort();
+            this.#leave = null;
         }
         #submitting = false;
         /**
@@ -1385,7 +1437,9 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
          *    loader's `submit` as its third argument. A listener may replace
          *    `request` on the detail
          * 6. has the loader `submit` the request and `transform` the response
-         * 7. fires `submit:success` with `{ submitter, values, request, response }`,
+         * 7. under `track-changes`, commits the values extracted at step 2 (see
+         *    `commit`): an edit made while the submit was in flight stays unsaved
+         * 8. fires `submit:success` with `{ submitter, values, request, response }`,
          *    `response` being the transformed one
          *
          * Anything thrown from step 1 on, a missing loader or a throwing mapper
@@ -1411,6 +1465,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
             try {
                 const loader = this.component(this.declared('loader') ?? 'loaders:form').create(this);
                 values = Bindings.extractFrom(this.form, submitter);
+                const submitted = this.#tracking ? { saved: this.#snapshot(), upTo: this.#sequence } : null;
                 request = await loader.prepare(values, this);
                 const se = new CustomEvent('submit', {
                     bubbles: true,
@@ -1431,6 +1486,9 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
 
                 response = await loader.submit(request, this, response);
                 const mapped = await loader.transform(response, this);
+                if (submitted) {
+                    this.#commitFrom(submitted.saved, submitted.upTo);
+                }
                 this.dispatchEvent(
                     new CustomEvent('submit:success', {
                         bubbles: true,
@@ -1456,9 +1514,208 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
                 this.spinner(false);
             }
         }
-        /** Resets the native form, each field returning to its default value. */
+        /**
+         * Resets the native form, each field returning to its default value. Under
+         * `track-changes` every control counts as edited: the form is dirty if the
+         * defaults differ from what was last committed.
+         */
         reset() {
             this.form.reset();
+            if (!this.#tracking) {
+                return;
+            }
+            for (const name of new Set([...this.#saved.keys(), ...this.#snapshot().keys()])) {
+                this.#edits.set(name, ++this.#sequence);
+            }
+            this.#refresh();
+        }
+        /** name → the serialized values the last commit recorded */
+        #saved = new Map();
+        /** name → the serialized values when first focused, for a name the last commit did not see */
+        #focused = new Map();
+        /** name → the sequence number of its latest edit since the last commit */
+        #edits = new Map();
+        #sequence = 0;
+        #wasDirty = false;
+        #frame = 0;
+        /** @type {AbortController|null} */
+        #leave = null;
+        #tracking = false;
+        /**
+         * Whether, under `track-changes`, a control the user edited since the last
+         * commit holds a value other than the one committed. An edit is what the
+         * controls report as one: an `input` or a `change` bubbling from a control
+         * of this form (0019), so assigning `value`, a select's vocabulary dropping
+         * a key or a section delivering its fields is not one, and an edit undone
+         * is no longer dirty. A control the last commit did not see compares with
+         * its value when it was first focused. Always false without
+         * `track-changes`.
+         *
+         * While dirty, the host matches `:state(dirty)` and the submit buttons of
+         * this form carry `data-ful-dirty`; a change of the state dispatches
+         * `dirty:change` with `{ dirty }`. Both are refreshed at the next frame
+         * after an edit, while the property is exact at any time.
+         * @returns {boolean}
+         */
+        get dirty() {
+            if (!this.#tracking) {
+                return false;
+            }
+            for (const name of this.#edits.keys()) {
+                const now = this.#valuesOf(name);
+                if (!this.#saved.has(name) && now === '[]') {
+                    continue;
+                }
+                const was = this.#saved.get(name) ?? this.#focused.get(name);
+                if (was !== now) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        /**
+         * Records the values of the controls as saved, so that the form is no
+         * longer dirty. A submit commits by itself on success, and the form
+         * commits once its fields have rendered: a page calls this for a save of
+         * its own, or after writing the values it loaded. Does nothing without
+         * `track-changes`.
+         */
+        commit() {
+            if (this.#tracking) {
+                this.#commitFrom(this.#snapshot(), this.#sequence);
+            }
+        }
+        /**
+         * Counts a control as edited by the user, for a value the page writes on
+         * the user's behalf: assigning `value` reports nothing, as 0019 wants.
+         * @param {Element} el the control, or an element inside it
+         */
+        edited(el) {
+            this.#touch(el);
+        }
+        /**
+         * @param {Map<string, string>} saved
+         * @param {number} upTo the sequence number of the latest edit the values include
+         */
+        #commitFrom(saved, upTo) {
+            this.#saved = saved;
+            for (const [name, sequence] of this.#edits) {
+                if (sequence <= upTo) {
+                    this.#edits.delete(name);
+                }
+            }
+            for (const name of this.#focused.keys()) {
+                if (saved.has(name)) {
+                    this.#focused.delete(name);
+                }
+            }
+            this.#refresh();
+        }
+        /**
+         * The named control of this form `target` is or sits in, if any: a field's
+         * inner control is unnamed or carries `form=""`, a control of a form nested
+         * in this one, like a table's filters, belongs to that form, and a
+         * form-associated element with no `form` property answers its owner
+         * through `internals.form`.
+         * @param {any} target
+         * @returns {string|null} its name
+         */
+        #nameOf(target) {
+            for (let el = target; el && el !== this; el = el.parentElement) {
+                if ((el.form ?? el.internals?.form) === this.form && el.hasAttribute('name')) {
+                    return el.getAttribute('name');
+                }
+            }
+            return null;
+        }
+        /** @param {EventTarget|null} target */
+        #touch(target) {
+            if (!this.#tracking) {
+                return;
+            }
+            const name = this.#nameOf(target);
+            if (name === null) {
+                return;
+            }
+            this.#edits.set(name, ++this.#sequence);
+            if (this.#frame === 0) {
+                this.#frame = requestAnimationFrame(() => this.#refresh());
+            }
+        }
+        /** @param {EventTarget|null} target */
+        #focus(target) {
+            const name = this.#nameOf(target);
+            if (name !== null && !this.#saved.has(name) && !this.#focused.has(name)) {
+                this.#focused.set(name, this.#valuesOf(name));
+            }
+        }
+        /**
+         * The controls that contribute to the values, as `Bindings.extractFrom`
+         * reads them, with no submitter.
+         * @returns {any[]}
+         */
+        #contributing() {
+            return Array.from(this.form.elements).filter(
+                (el) =>
+                    el.hasAttribute('name') &&
+                    !['submit', 'reset', 'button'].includes(/** @type {any} */ (el).type) &&
+                    !el.matches(':disabled'),
+            );
+        }
+        /** @returns {Map<string, string>} each name to its serialized values */
+        #snapshot() {
+            /** @type {Map<string, any[]>} */
+            const values = new Map();
+            for (const el of this.#contributing()) {
+                const name = el.getAttribute('name');
+                values.set(name, [...(values.get(name) ?? []), Bindings.extract(el)]);
+            }
+            return new Map(Array.from(values, ([name, vs]) => [name, JSON.stringify(vs)]));
+        }
+        /**
+         * @param {string} name
+         * @returns {string} the serialized values of the controls carrying it
+         */
+        #valuesOf(name) {
+            return JSON.stringify(
+                this.#contributing()
+                    .filter((el) => el.getAttribute('name') === name)
+                    .map((el) => Bindings.extract(el)),
+            );
+        }
+        #refresh() {
+            cancelAnimationFrame(this.#frame);
+            this.#frame = 0;
+            const dirty = this.dirty;
+            this.querySelectorAll('button').forEach((el) => {
+                const button = /** @type HTMLButtonElement */ (el);
+                if (button.form === this.form && button.type === 'submit') {
+                    button.toggleAttribute('data-ful-dirty', dirty);
+                }
+            });
+            if (dirty === this.#wasDirty) {
+                return;
+            }
+            this.#wasDirty = dirty;
+            if (dirty) {
+                this.internals.states.add('dirty');
+            } else {
+                this.internals.states.delete('dirty');
+            }
+            this.dispatchEvent(
+                new CustomEvent('dirty:change', {
+                    bubbles: true,
+                    cancelable: false,
+                    detail: { dirty },
+                }),
+            );
+        }
+        #guard() {
+            if (!this.declared('guard-leave') || this.#leave) {
+                return;
+            }
+            this.#leave = new AbortController();
+            PageLeave.guard(() => this.dirty, this.#leave.signal);
         }
         #spinning = 0;
         /**
@@ -1646,7 +1903,9 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
      *   datetime-local, month or week control fires its native `change` while its
      *   segments are typed, as soon as they make a valid value; for those the field
      *   reports when the control is left or Enter is pressed, at once for a value
-     *   picked from the browser's picker, and never a half-typed value.
+     *   picked from the browser's picker, never with the dates a year passes
+     *   through while it is typed. A control left incomplete reads as `null`, as
+     *   the native one does.
      *
      * A subclass template may render more than one control, as the compare filters
      * render the two bounds of a range: the first is `_input`, the one the field is
@@ -8057,6 +8316,7 @@ var ful = (function (exports, index_mjs, index_mjs$1) {
     exports.LocalStorage = LocalStorage;
     exports.Menu = Menu;
     exports.NumberFilter = NumberFilter;
+    exports.PageLeave = PageLeave;
     exports.Pagination = Pagination;
     exports.Plugin = Plugin;
     exports.RadioGroup = RadioGroup;