entasis 0.11.0 → 0.12.0

package/dist/utils/usePressAndHold.svelte.d.ts

@@ -0,0 +1,38 @@
+import type { Attachment } from 'svelte/attachments';
+/** Milliseconds between the press and the first repeat. */
+export declare const PRESS_AND_HOLD_DELAY = 400;
+/** Milliseconds between repeats. */
+export declare const PRESS_AND_HOLD_INTERVAL = 60;
+export type PressAndHoldOptions = {
+    /**
+     * One step. Runs on the press and then on every repeat; return `false` to stop repeating, for
+     * example when the value reached a bound. Receives the event that started the hold.
+     */
+    onStep: (event: Event) => boolean | void;
+    /**
+     * Checked before every step. While it returns true no hold starts, and a running one stops as
+     * soon as it does (disabled or read-only mid-hold).
+     */
+    disabled?: () => boolean;
+    /** Milliseconds between the press and the first repeat. Default `PRESS_AND_HOLD_DELAY`. */
+    delay?: number;
+    /** Milliseconds between repeats. Default `PRESS_AND_HOLD_INTERVAL`. */
+    interval?: number;
+    /** Touch travel in px that turns the press into a scroll and stops it. Default 8. */
+    scrollDistance?: number;
+    /** The press ended: the pointer was released or cancelled. */
+    onStop?: () => void;
+};
+/**
+ * Press-and-hold repetition for stepper buttons. A mouse or pen press steps at once, then repeats
+ * after `delay` every `interval` until the pointer is released or cancelled, the step returns
+ * `false` or `disabled` turns true; moving off the button pauses it and coming back resumes. A
+ * touch press waits briefly so a scroll that starts on the button never steps, and a quick tap is
+ * left to the button's click. Pair the attachment with `shouldSkipClick` in the click handler so
+ * the click after a press does not step twice while keyboard activation still steps once.
+ */
+export declare const usePressAndHold: (options: PressAndHoldOptions) => {
+    attachment: Attachment<HTMLElement>;
+    shouldSkipClick: (event: MouseEvent) => boolean;
+    stop: () => void;
+};

package/dist/utils/usePressAndHold.svelte.js

@@ -0,0 +1,191 @@
+import { onDestroy, untrack } from 'svelte';
+import { on } from 'svelte/events';
+/** Milliseconds between the press and the first repeat. */
+export const PRESS_AND_HOLD_DELAY = 400;
+/** Milliseconds between repeats. */
+export const PRESS_AND_HOLD_INTERVAL = 60;
+/** Touch travel in px that turns a press into a scroll. */
+const SCROLL_DISTANCE = 8;
+/** A touch press waits this long before it counts as a hold rather than the start of a scroll. */
+const TOUCH_INTENT_MS = 50;
+/** More touch moves than this during the intent wait read as a scroll or a pinch. */
+const MAX_TOUCH_INTENT_MOVES = 3;
+/**
+ * Press-and-hold repetition for stepper buttons. A mouse or pen press steps at once, then repeats
+ * after `delay` every `interval` until the pointer is released or cancelled, the step returns
+ * `false` or `disabled` turns true; moving off the button pauses it and coming back resumes. A
+ * touch press waits briefly so a scroll that starts on the button never steps, and a quick tap is
+ * left to the button's click. Pair the attachment with `shouldSkipClick` in the click handler so
+ * the click after a press does not step twice while keyboard activation still steps once.
+ */
+export const usePressAndHold = (options) => {
+    let pressed = false;
+    let pointerType = '';
+    let ignoreClick = false;
+    let downX = 0;
+    let downY = 0;
+    let touchMoves = 0;
+    let intentTimer = null;
+    /** The pending step: the first repeat after `delay`, then each one after `interval`. */
+    let stepTimer = null;
+    let offContextMenu = null;
+    let offRelease = null;
+    const isTouch = (type) => type === 'touch';
+    const isDisabled = () => options.disabled?.() === true;
+    /** Stops stepping; a pressed pointer can still resume it by coming back onto the button. */
+    const stopRepeating = () => {
+        if (stepTimer !== null)
+            clearTimeout(stepTimer);
+        stepTimer = null;
+        offContextMenu?.();
+        offContextMenu = null;
+    };
+    const clearIntent = () => {
+        if (intentTimer !== null)
+            clearTimeout(intentTimer);
+        intentTimer = null;
+        touchMoves = 0;
+    };
+    const start = (event) => {
+        stopRepeating();
+        if (isDisabled())
+            return;
+        // A long touch press would otherwise open the browser's context menu over the button.
+        offContextMenu = on(window, 'contextmenu', (contextEvent) => contextEvent.preventDefault());
+        if (options.onStep(event) === false) {
+            stopRepeating();
+            return;
+        }
+        const interval = options.interval ?? PRESS_AND_HOLD_INTERVAL;
+        const repeat = () => {
+            stepTimer = null;
+            if (isDisabled() || options.onStep(event) === false) {
+                stopRepeating();
+                return;
+            }
+            stepTimer = setTimeout(repeat, interval);
+        };
+        // Repeating starts once the delay has passed: its first step lands an interval later.
+        stepTimer = setTimeout(() => {
+            stepTimer = setTimeout(repeat, interval);
+        }, options.delay ?? PRESS_AND_HOLD_DELAY);
+    };
+    const release = () => {
+        if (!pressed && offRelease === null)
+            return;
+        pressed = false;
+        clearIntent();
+        stopRepeating();
+        offRelease?.();
+        offRelease = null;
+        options.onStop?.();
+    };
+    /** Stops a running hold now, as a release would. */
+    const stop = () => release();
+    const down = (event) => {
+        if (event.defaultPrevented || event.button !== 0 || isDisabled())
+            return;
+        release();
+        pressed = true;
+        pointerType = event.pointerType;
+        ignoreClick = false;
+        downX = event.clientX;
+        downY = event.clientY;
+        // The release can land anywhere; an ancestor stopping it is covered by the node's own listener.
+        const offUp = on(window, 'pointerup', release);
+        const offCancel = on(window, 'pointercancel', release);
+        offRelease = () => {
+            offUp();
+            offCancel();
+        };
+        if (!isTouch(event.pointerType)) {
+            // Mouse and pen: step now, and keep the press from selecting text.
+            event.preventDefault();
+            start(event);
+            return;
+        }
+        clearIntent();
+        intentTimer = setTimeout(() => {
+            const moves = touchMoves;
+            clearIntent();
+            if (!pressed || moves > MAX_TOUCH_INTENT_MOVES)
+                return;
+            start(event);
+            // The click a touch hold ends with must not step once more.
+            ignoreClick = true;
+        }, TOUCH_INTENT_MS);
+    };
+    const move = (event) => {
+        if (!pressed || !isTouch(event.pointerType))
+            return;
+        touchMoves += 1;
+        const distance = Math.hypot(event.clientX - downX, event.clientY - downY);
+        if (distance > (options.scrollDistance ?? SCROLL_DISTANCE)) {
+            clearIntent();
+            stopRepeating();
+        }
+    };
+    // Mouse and pen only: a touch has no hover, its pointer leaves when it lifts.
+    const pause = (event) => {
+        if (pressed && !isTouch(event.pointerType))
+            stopRepeating();
+    };
+    const resume = (event) => {
+        if (!pressed || isTouch(event.pointerType) || isTouch(pointerType))
+            return;
+        // The button came up where no pointerup reached us (outside the window, over an iframe):
+        // coming back onto the button without it held ends the press instead of repeating it.
+        if ((event.buttons & 1) === 0) {
+            release();
+            return;
+        }
+        start(event);
+    };
+    $effect(() => {
+        if (isDisabled())
+            untrack(stopRepeating);
+    });
+    onDestroy(() => {
+        clearIntent();
+        stopRepeating();
+        offRelease?.();
+        offRelease = null;
+        pressed = false;
+    });
+    const attachment = (node) => untrack(() => {
+        const offs = [
+            on(node, 'pointerdown', down),
+            on(node, 'pointermove', move),
+            on(node, 'pointerup', release),
+            on(node, 'pointerleave', pause),
+            on(node, 'pointerenter', resume)
+        ];
+        return () => {
+            offs.forEach((off) => off());
+            clearIntent();
+            stopRepeating();
+            offRelease?.();
+            offRelease = null;
+            pressed = false;
+        };
+    });
+    /**
+     * For the button's click handler: true when the click must not step. A mouse or pen press
+     * already stepped on pointerdown, and a touch hold already repeated; a keyboard activation
+     * (`detail` 0) and a quick touch tap still step through the click.
+     */
+    const shouldSkipClick = (event) => {
+        if (event.defaultPrevented)
+            return true;
+        // Keyboard and assistive-tech activations always step, whatever pointer pressed last.
+        if (event.detail === 0)
+            return false;
+        if (!isTouch(pointerType))
+            return true;
+        // The click a touch hold ends with is skipped once; a later one is a tap of its own.
+        const skip = ignoreClick;
+        ignoreClick = false;
+        return skip;
+    };
+    return { attachment, shouldSkipClick, stop };
+};

package/dist/utils/useScrollLock.svelte.d.ts

@@ -2,7 +2,26 @@ type ScrollLockOptions = {
     isActive: () => boolean;
     scroller?: HTMLElement;
 };
-/** Locks `scroller` (default `document.body`) and returns a release function. */
+/** The attribute a locked scroller carries. */
+export declare const SCROLL_LOCK_ATTRIBUTE = "data-entasis-scroll-lock";
+/**
+ * Value of `data-entasis-scroll-lock` when there is nothing to compensate: the page already
+ * reserves its scrollbar gutter (`scrollbar-gutter: stable`) or shows no classic scrollbar.
+ * Otherwise the value is empty and the plugin rule keeps the scrollbar's room.
+ */
+export declare const SCROLL_LOCK_UNCOMPENSATED = "uncompensated";
+/**
+ * Value of `data-entasis-scroll-lock` when `scrollbar-gutter: stable` did not keep the hidden
+ * scrollbar's room (the property is unsupported, or the scroller has a custom scrollbar): the
+ * plugin rule pads the scroller by the scrollbar's width instead.
+ */
+export declare const SCROLL_LOCK_PADDED = "padding";
+/**
+ * Custom property set on a locked scroller: the width in px of the scrollbar the lock hides,
+ * `0px` with overlay scrollbars. Use it to keep `position: fixed` bars from jumping sideways.
+ */
+export declare const SCROLLBAR_WIDTH_VARIABLE = "--entasis-scrollbar-width";
+/** Locks `scroller` (default the page, `<html>`) and returns a release function. */
 export declare const lockScroll: (scroller?: HTMLElement) => () => void;
 export declare const useScrollLock: (opts: ScrollLockOptions) => void;
 export {};

package/dist/utils/useScrollLock.svelte.js

@@ -1,22 +1,63 @@
+/** The attribute a locked scroller carries. */
+export const SCROLL_LOCK_ATTRIBUTE = 'data-entasis-scroll-lock';
+/**
+ * Value of `data-entasis-scroll-lock` when there is nothing to compensate: the page already
+ * reserves its scrollbar gutter (`scrollbar-gutter: stable`) or shows no classic scrollbar.
+ * Otherwise the value is empty and the plugin rule keeps the scrollbar's room.
+ */
+export const SCROLL_LOCK_UNCOMPENSATED = 'uncompensated';
+/**
+ * Value of `data-entasis-scroll-lock` when `scrollbar-gutter: stable` did not keep the hidden
+ * scrollbar's room (the property is unsupported, or the scroller has a custom scrollbar): the
+ * plugin rule pads the scroller by the scrollbar's width instead.
+ */
+export const SCROLL_LOCK_PADDED = 'padding';
+/**
+ * Custom property set on a locked scroller: the width in px of the scrollbar the lock hides,
+ * `0px` with overlay scrollbars. Use it to keep `position: fixed` bars from jumping sideways.
+ */
+export const SCROLLBAR_WIDTH_VARIABLE = '--entasis-scrollbar-width';
 // WeakMap (not Map): purely imperative refcount bookkeeping keyed by element, read and
 // written from inside effects — a reactive Map here would re-trigger its own effect.
 const locks = new WeakMap();
-/** Locks `scroller` (default `document.body`) and returns a release function. */
-export const lockScroll = (scroller = document.body) => {
+/** Whether `scrollbar-gutter: stable` already keeps room for the scrollbar on `scroller`. */
+const reservesGutter = (scroller) => {
+    const document = scroller.ownerDocument;
+    // The root element's value (or the body's, when its overflow propagates) styles the viewport.
+    const targets = scroller === document.documentElement ? [scroller, document.body] : [scroller];
+    return targets.some((target) => document.defaultView?.getComputedStyle(target).scrollbarGutter?.startsWith('stable'));
+};
+/** The width of the scrollbar `scroller` shows now, `0` when it has none or an overlay one. */
+const measureScrollbarWidth = (scroller) => {
+    const document = scroller.ownerDocument;
+    if (scroller === document.documentElement) {
+        return Math.max(0, (document.defaultView?.innerWidth ?? 0) - scroller.clientWidth);
+    }
+    return Math.max(0, scroller.offsetWidth - scroller.clientWidth);
+};
+/** Locks `scroller` (default the page, `<html>`) and returns a release function. */
+export const lockScroll = (scroller = document.documentElement) => {
     const entry = locks.get(scroller);
     if (entry) {
         entry.count += 1;
     }
     else {
-        const scrollBarWidth = window.innerWidth - document.documentElement.clientWidth;
-        locks.set(scroller, {
-            count: 1,
-            overflow: scroller.style.overflow,
-            paddingRight: scroller.style.paddingRight
-        });
-        if (scrollBarWidth > 0)
-            scroller.style.paddingRight = `${scrollBarWidth}px`;
-        scroller.style.overflow = 'hidden';
+        locks.set(scroller, { count: 1 });
+        // Measured before the attribute hides the scrollbar.
+        const width = measureScrollbarWidth(scroller);
+        const before = scroller.clientWidth;
+        scroller.style.setProperty(SCROLLBAR_WIDTH_VARIABLE, `${width}px`);
+        if (width === 0 || reservesGutter(scroller)) {
+            scroller.setAttribute(SCROLL_LOCK_ATTRIBUTE, SCROLL_LOCK_UNCOMPENSATED);
+        }
+        else {
+            scroller.setAttribute(SCROLL_LOCK_ATTRIBUTE, '');
+            // `scrollbar-gutter` is not honoured everywhere (older engines, custom scrollbars on the
+            // viewport). When the content still widened into the hidden scrollbar's room, pad it back.
+            if (scroller.clientWidth - before >= width / 2) {
+                scroller.setAttribute(SCROLL_LOCK_ATTRIBUTE, SCROLL_LOCK_PADDED);
+            }
+        }
     }
     let released = false;
     return () => {
@@ -29,8 +70,8 @@ export const lockScroll = (scroller = document.body) => {
         current.count -= 1;
         if (current.count > 0)
             return;
-        scroller.style.overflow = current.overflow;
-        scroller.style.paddingRight = current.paddingRight;
+        scroller.removeAttribute(SCROLL_LOCK_ATTRIBUTE);
+        scroller.style.removeProperty(SCROLLBAR_WIDTH_VARIABLE);
         locks.delete(scroller);
     };
 };

package/dist/utils/useSlidingIndicator.svelte.d.ts

@@ -9,5 +9,7 @@ export declare const useSlidingIndicator: (options: SlidingIndicatorOptions) =>
     readonly style: string;
     readonly isHydrated: boolean;
     readonly isReady: boolean;
+    /** True while the indicator sits on an active item; false when no item is active. */
+    readonly isVisible: boolean;
 };
 export {};

package/dist/utils/useSlidingIndicator.svelte.js

@@ -7,8 +7,17 @@ export const useSlidingIndicator = (options) => {
     let style = $state('');
     let isHydrated = $state(false);
     let isReady = $state(false);
+    let isVisible = $state(false);
+    const cancelFrames = () => {
+        if (firstFrame !== undefined)
+            cancelAnimationFrame(firstFrame);
+        if (secondFrame !== undefined)
+            cancelAnimationFrame(secondFrame);
+        firstFrame = undefined;
+        secondFrame = undefined;
+    };
     const enableTransition = () => {
-        if (isReady || firstFrame !== undefined)
+        if (isReady || firstFrame !== undefined || secondFrame !== undefined)
             return;
         firstFrame = requestAnimationFrame(() => {
             firstFrame = undefined;
@@ -18,11 +27,23 @@ export const useSlidingIndicator = (options) => {
             });
         });
     };
+    // No active item: drop the last position instead of leaving the indicator on a tab that is
+    // no longer selected, and let the next placement snap into place before transitions resume.
+    const hideIndicator = () => {
+        style = '';
+        isVisible = false;
+        isReady = false;
+        cancelFrames();
+    };
     const placeIndicator = (index = options.activeIndex()) => {
+        if (index < 0)
+            return hideIndicator();
+        // An item that is not attached yet places the indicator from its own `itemReference`.
         const element = itemElements[index];
         if (!element)
             return;
         style = options.getStyle(element);
+        isVisible = true;
         isHydrated = true;
         enableTransition();
     };
@@ -51,10 +72,7 @@ export const useSlidingIndicator = (options) => {
             return () => {
                 resizeObserver?.disconnect();
                 resizeObserver = undefined;
-                if (firstFrame !== undefined)
-                    cancelAnimationFrame(firstFrame);
-                if (secondFrame !== undefined)
-                    cancelAnimationFrame(secondFrame);
+                cancelFrames();
             };
         });
     };
@@ -69,6 +87,10 @@ export const useSlidingIndicator = (options) => {
         },
         get isReady() {
             return isReady;
+        },
+        /** True while the indicator sits on an active item; false when no item is active. */
+        get isVisible() {
+            return isVisible;
         }
     };
 };

package/dist/utils/useTabBridge.svelte.d.ts

@@ -0,0 +1,20 @@
+export interface TabBridgeOptions {
+    /** The bridge is live: the panel is open, placed and nothing above it owns Tab. */
+    isActive: () => boolean;
+    /** The element that has focus while the panel is open; `null` turns the bridge off. */
+    anchor: () => HTMLElement | null;
+    /** The panel element. */
+    panel: () => HTMLElement | null;
+    /** Limits where "after the trigger" is looked for, for a trigger inside another panel. */
+    boundary?: () => HTMLElement | undefined;
+    /** Tab went past the panel's last control and focus moved on; close the panel. */
+    onLeave: (event: KeyboardEvent) => void;
+}
+/**
+ * Bridges Tab between a trigger and its portaled panel. Call during component initialisation
+ * (it registers an effect). Returns whether a key press was handled, for tests and owners that
+ * want to chain their own handling.
+ */
+export declare function useTabBridge(options: TabBridgeOptions): {
+    handleKey: (event: KeyboardEvent) => void;
+};

package/dist/utils/useTabBridge.svelte.js

@@ -0,0 +1,109 @@
+// Tab order for a panel rendered somewhere else in the document (a popover portaled to the end of
+// <body>). The panel is not next to its trigger in the page, so the engine's own Tab skips it:
+//
+// - Tab on the open trigger enters the panel.
+// - Tab past the panel's last control continues after the trigger and closes the panel.
+// - Shift+Tab on the panel's first control returns to the trigger.
+// - When nothing follows the trigger, the engine's Tab is left alone: sending focus back to the
+//   start of the panel would loop for ever. Inside a modal scope (the trigger is the last control
+//   of a dialog) it wraps to the scope's first control instead, as the scope's own Tab would.
+//
+// The listeners sit on the trigger and on the panel, not on the document, so they run before a
+// surrounding modal scope's document-level Tab handling and after a control's own key handling.
+import { on } from 'svelte/events';
+import { composedContains, getDeepActiveElement, getTabbableAfter, getTabbableElements } from './focus.js';
+import { findTrappingScope } from './useFocusScope.svelte.js';
+const FOCUS_VISIBLE = { preventScroll: true, focusVisible: true };
+/**
+ * Bridges Tab between a trigger and its portaled panel. Call during component initialisation
+ * (it registers an effect). Returns whether a key press was handled, for tests and owners that
+ * want to chain their own handling.
+ */
+export function useTabBridge(options) {
+    const enterPanel = (event, panel) => {
+        const first = getTabbableElements(panel)[0];
+        if (!first)
+            return;
+        event.preventDefault();
+        first.focus(FOCUS_VISIBLE);
+    };
+    const leavePanel = (event, panel, anchor) => {
+        const next = getTabbableAfter(anchor, {
+            exclude: panel,
+            boundary: options.boundary ? options.boundary() : undefined
+        });
+        let target = next;
+        if (!target) {
+            // Nothing follows. In a modal scope the page behind is inert, so the engine would leave
+            // the scope: wrap to its first control. Anywhere else the engine moves on, so Tab cannot
+            // cycle between the trigger and the panel.
+            const scope = findTrappingScope(anchor);
+            if (!scope)
+                return;
+            target =
+                getTabbableElements(scope).find((element) => !composedContains(panel, element)) ?? null;
+            if (!target)
+                return;
+        }
+        event.preventDefault();
+        target.focus(FOCUS_VISIBLE);
+        options.onLeave(event);
+    };
+    const handleKey = (event) => {
+        if (event.key !== 'Tab' || event.defaultPrevented)
+            return;
+        if (event.ctrlKey || event.metaKey)
+            return;
+        if (!options.isActive())
+            return;
+        const anchor = options.anchor();
+        const panel = options.panel();
+        if (!anchor || !panel || !anchor.isConnected)
+            return;
+        const active = getDeepActiveElement(anchor.ownerDocument);
+        if (!active)
+            return;
+        if (active === anchor) {
+            if (!event.shiftKey)
+                enterPanel(event, panel);
+            return;
+        }
+        if (!composedContains(panel, active))
+            return;
+        const tabbable = getTabbableElements(panel);
+        const index = active instanceof HTMLElement ? tabbable.indexOf(active) : -1;
+        if (event.shiftKey) {
+            // Back from the first control, or from the panel itself when it holds focus. Anything
+            // else is the engine's to move: an item the list does not know has a control before it.
+            if (index === 0 || active === panel) {
+                event.preventDefault();
+                anchor.focus(FOCUS_VISIBLE);
+            }
+            return;
+        }
+        if (active === panel) {
+            if (tabbable.length > 0)
+                enterPanel(event, panel);
+            else
+                leavePanel(event, panel, anchor);
+            return;
+        }
+        if (index >= 0 && index === tabbable.length - 1)
+            leavePanel(event, panel, anchor);
+    };
+    $effect(() => {
+        if (!options.isActive())
+            return;
+        const anchor = options.anchor();
+        const panel = options.panel();
+        if (!anchor || !panel)
+            return;
+        const offAnchor = on(anchor, 'keydown', handleKey);
+        const offPanel = on(panel, 'keydown', handleKey);
+        return () => {
+            offAnchor();
+            offPanel();
+        };
+    });
+    return { handleKey };
+}

package/dist/utils/values.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether a value holds nothing a user entered: `null`, `undefined`, `''`, an empty array, or an
+ * array of empty slots (a date range with neither end chosen).
+ */
+export declare const isEmptyValue: (value: unknown) => boolean;
+/**
+ * Structural equality: Dates by time, arrays item by item, plain objects key by key; everything
+ * else (files, blobs, class instances, primitives) by identity, with `NaN` equal to itself.
+ */
+export declare const deepEqual: (left: unknown, right: unknown) => boolean;
+/**
+ * Field value equality: two empty values are equal whatever their shape (`null`, `''`, `[]`), so
+ * clearing a field back to nothing is not a change; otherwise the values must be `deepEqual`.
+ */
+export declare const valuesEqual: (left: unknown, right: unknown) => boolean;

package/dist/utils/values.js

@@ -0,0 +1,49 @@
+// Value equality and emptiness shared by fields, Form and registered input types. A field's
+// "empty" is what a user sees as nothing entered: no text, no selection, no file. Equality
+// compares what a value means rather than its identity, so a Form that writes a value back as a
+// new array, or a parent that resets a date to an equal Date, does not read as an edit.
+const isPlainObject = (value) => {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+/**
+ * Whether a value holds nothing a user entered: `null`, `undefined`, `''`, an empty array, or an
+ * array of empty slots (a date range with neither end chosen).
+ */
+export const isEmptyValue = (value) => {
+    if (value === null || value === undefined || value === '')
+        return true;
+    if (Array.isArray(value))
+        return value.every((item) => item === null || item === undefined);
+    return false;
+};
+/**
+ * Structural equality: Dates by time, arrays item by item, plain objects key by key; everything
+ * else (files, blobs, class instances, primitives) by identity, with `NaN` equal to itself.
+ */
+export const deepEqual = (left, right) => {
+    if (Object.is(left, right))
+        return true;
+    if (left instanceof Date || right instanceof Date) {
+        return (left instanceof Date && right instanceof Date && Object.is(left.getTime(), right.getTime()));
+    }
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length)
+            return false;
+        return left.every((item, index) => deepEqual(item, right[index]));
+    }
+    if (isPlainObject(left) && isPlainObject(right)) {
+        const leftKeys = Object.keys(left);
+        if (leftKeys.length !== Object.keys(right).length)
+            return false;
+        return leftKeys.every((key) => Object.hasOwn(right, key) && deepEqual(left[key], right[key]));
+    }
+    return false;
+};
+/**
+ * Field value equality: two empty values are equal whatever their shape (`null`, `''`, `[]`), so
+ * clearing a field back to nothing is not a change; otherwise the values must be `deepEqual`.
+ */
+export const valuesEqual = (left, right) => (isEmptyValue(left) && isEmptyValue(right)) || deepEqual(left, right);