entasis 0.11.0 → 0.12.0

package/dist/utils/useHoverAction.svelte.js

@@ -1,77 +1,187 @@
 import { onDestroy, untrack } from 'svelte';
 import { on } from 'svelte/events';
-import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+const DEFAULT_IGNORED_POINTER_TYPES = ['touch'];
+// Where a pointer last moved, shared by every hover trigger. An element that appears under a
+// resting pointer (a menu reopened from the keyboard, content the wheel scrolled into place)
+// receives `mouseenter` at exactly that point although the pointer never moved onto it. The
+// window listener sees a move before the boundary events it causes, so an enter at the recorded
+// point is one the pointer did not travel to.
+let lastPointer = null;
+let pointerTrackers = 0;
+let offPointerTracking = null;
+const trackPointer = () => {
+    if (pointerTrackers++ === 0) {
+        offPointerTracking = on(window, 'pointermove', (event) => {
+            lastPointer = { x: event.clientX, y: event.clientY };
+        }, { capture: true, passive: true });
+    }
+    let tracking = true;
+    return () => {
+        if (!tracking)
+            return;
+        tracking = false;
+        if (--pointerTrackers > 0)
+            return;
+        offPointerTracking?.();
+        offPointerTracking = null;
+        lastPointer = null;
+    };
+};
+// Mouse events report whole pixels where pointer events can be fractional.
+const isRestingPointer = (event) => lastPointer !== null &&
+    Math.abs(event.clientX - lastPointer.x) < 1 &&
+    Math.abs(event.clientY - lastPointer.y) < 1;
+const isDisabledTrigger = (node) => {
+    if (node.matches(':disabled') || node.getAttribute('aria-disabled') === 'true')
+        return true;
+    const dataDisabled = node.getAttribute('data-disabled');
+    return dataDisabled !== null && dataDisabled !== 'false';
+};
+/**
+ * Delayed hover for a popup trigger. Hover is read from `mouseenter`/`mouseleave`, with the
+ * pointer type recorded from the pointer events before them, so a touch tap's compatibility
+ * events never count. A pending open needs the pointer still on the trigger when its delay ends:
+ * `mouseout` backs up a `mouseleave` that Chrome can drop when the hovered element restyles.
+ */
 export const useHoverAction = (props) => {
-    const timeouts = new SvelteMap();
-    const offs = new SvelteSet();
+    // Plain collections: attachments read and write them untracked, and nothing renders them.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- attached triggers, not state
+    const targets = new Map();
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- teardown callbacks, not state
+    const offs = new Set();
     let isHovered = $state(false);
-    const wait = async (ref) => {
-        return new Promise((resolve) => {
-            const timeout = setTimeout(() => {
-                resolve(true);
-                timeouts.delete(ref);
-            }, props.delay);
-            timeouts.set(ref, timeout);
-        });
+    const readDelay = () => (typeof props.delay === 'function' ? props.delay() : props.delay) ?? 0;
+    const isIgnored = (target) => (props.ignorePointerTypes ?? DEFAULT_IGNORED_POINTER_TYPES).includes(target.pointerType);
+    // An inactive owner (a popover that is already open) starts nothing: a pending open would act
+    // on a later state, such as reopening a popover the user just closed.
+    const isBlocked = (ref) => !props.isActive() || (props.skipDisabled !== false && isDisabledTrigger(ref));
+    const stopAwaitingMove = (target) => {
+        target.offAwaitMove?.();
+        target.offAwaitMove = null;
     };
-    function onMouseEnter() {
-        if (timeouts.get(this)) {
-            clearTimeout(timeouts.get(this));
-            timeouts.delete(this);
-        }
-        if (props.delay) {
-            wait(this).then(() => {
-                if (props.isActive())
-                    props.onMouseEnter?.();
-                isHovered = true;
-            });
-        }
-        else {
-            if (props.isActive())
-                props.onMouseEnter?.();
-            isHovered = true;
+    const clearPending = (target) => {
+        if (target.timeout !== null)
+            clearTimeout(target.timeout);
+        target.timeout = null;
+        stopAwaitingMove(target);
+    };
+    /** Drops every pending delayed enter, so none of them calls `onMouseEnter` any more. */
+    const cancel = () => {
+        targets.forEach(clearPending);
+    };
+    const fire = (ref, target) => {
+        // The pointer left during the delay, even if its `mouseleave` never arrived.
+        if (!target.inside)
+            return;
+        if (!isBlocked(ref) && target.enterEvent)
+            props.onMouseEnter?.(target.enterEvent);
+        isHovered = true;
+    };
+    const arm = (ref, target) => {
+        const delay = props.group?.()?.isWarm(ref) ? 0 : readDelay();
+        if (!delay) {
+            fire(ref, target);
+            return;
         }
-    }
-    function onMouseLeave() {
-        if (timeouts.get(this)) {
-            clearTimeout(timeouts.get(this));
-            timeouts.delete(this);
+        target.timeout = setTimeout(() => {
+            target.timeout = null;
+            fire(ref, target);
+        }, delay);
+    };
+    const enter = (ref, target, event) => {
+        clearPending(target);
+        if (isIgnored(target))
+            return;
+        target.inside = true;
+        target.enterEvent = event;
+        if (isBlocked(ref))
+            return;
+        if (!isRestingPointer(event)) {
+            arm(ref, target);
+            return;
         }
+        // The trigger arrived under a resting pointer: it is hovered once the pointer moves on it.
+        target.offAwaitMove = on(ref, 'mousemove', () => {
+            stopAwaitingMove(target);
+            if (!target.inside || isIgnored(target) || isBlocked(ref))
+                return;
+            arm(ref, target);
+        });
+    };
+    const leave = (target, event) => {
+        clearPending(target);
+        if (!target.inside)
+            return;
+        target.inside = false;
+        target.enterEvent = null;
         if (props.isActive())
-            props.onMouseLeave?.();
+            props.onMouseLeave?.(event);
         isHovered = false;
+    };
+    // While the owner's popup is open it keeps the group warm for the next hover target.
+    if (props.isOpen) {
+        $effect(() => {
+            const group = props.group?.();
+            if (!group || !props.isOpen?.())
+                return;
+            return untrack(() => group.join({ contains: props.contains }));
+        });
     }
     const destroy = () => {
         offs.forEach((off) => off());
         offs.clear();
-        timeouts.forEach((timeout) => clearTimeout(timeout));
-        timeouts.clear();
+        cancel();
         isHovered = false;
     };
     onDestroy(destroy);
     return {
+        // Always listens: `isActive` is checked when the pointer moves, so an element attached
+        // while the owner is inactive (a popover that starts open, a disabled trigger enabled
+        // later) still responds once it is active.
         reference: (ref) => {
-            if (!props.isActive())
-                return null;
             return untrack(() => {
-                const offEnter = on(ref, 'mouseenter', onMouseEnter.bind(ref));
-                const offLeave = on(ref, 'mouseleave', onMouseLeave.bind(ref));
-                offs.add(offEnter);
-                offs.add(offLeave);
-                return () => {
-                    offLeave();
-                    offEnter();
-                    offs.delete(offEnter);
-                    offs.delete(offLeave);
-                    const timeout = timeouts.get(ref);
-                    if (timeout) {
-                        clearTimeout(timeout);
-                        timeouts.delete(ref);
-                    }
+                const target = {
+                    pointerType: '',
+                    inside: false,
+                    enterEvent: null,
+                    timeout: null,
+                    offAwaitMove: null
+                };
+                targets.set(ref, target);
+                const recordPointerType = (event) => {
+                    target.pointerType = event.pointerType;
+                };
+                const listeners = [
+                    trackPointer(),
+                    on(ref, 'pointerenter', recordPointerType),
+                    on(ref, 'pointerdown', recordPointerType),
+                    on(ref, 'mouseenter', (event) => enter(ref, target, event)),
+                    on(ref, 'mouseleave', (event) => leave(target, event)),
+                    // Bubbles from descendants too; only a move to outside the trigger is a leave.
+                    on(ref, 'mouseout', (event) => {
+                        const next = event.relatedTarget;
+                        if (next instanceof Node && ref.contains(next))
+                            return;
+                        leave(target, event);
+                    })
+                ];
+                const off = () => {
+                    listeners.forEach((stop) => stop());
+                    clearPending(target);
+                    if (targets.get(ref) === target)
+                        targets.delete(ref);
+                    offs.delete(off);
                 };
+                offs.add(off);
+                return off;
             });
         },
         destroy,
+        /**
+         * Cancels pending delayed enters. Owners call it when their state changes another way (a
+         * click, Escape), so a hover that began before the change cannot undo it afterwards.
+         */
+        cancel,
         get isHovered() {
             return isHovered;
         }

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

@@ -1,9 +1,26 @@
+/** Where a handled key was heard: on the referenced element, or on `window` (`onWindow`). */
+export type KeyDownSource = 'element' | 'window';
+/**
+ * Alt, Ctrl or Meta turn a key into a browser or OS shortcut (Alt+← is Back, Cmd+→ jumps to the
+ * line end). Shift is not one of them: Shift+Arrow is still the plain key to a widget.
+ */
+export declare const hasShortcutModifier: (event: KeyboardEvent) => boolean;
 export declare const useKeyDown: (opts: {
+    /** Checked on every key, so a gate that opens after mount still lets keys through. */
     isActive: () => boolean;
-    callback: (event: KeyboardEvent) => void;
+    callback: (event: KeyboardEvent, source: KeyDownSource) => void;
     keys: string[];
     onWindow?: () => boolean;
     preventDefault?: boolean;
+    /**
+     * Leave keys pressed with Alt, Ctrl or Meta to the browser: no `preventDefault` and no
+     * callback. Shift still counts as the plain key. Default `false`.
+     */
+    ignoreModifiers?: boolean;
 }) => {
-    reference: (ref: HTMLElement) => (() => void) | undefined;
+    /**
+     * Listens on `ref` for as long as it is attached; keys typed while `isActive()` is false are
+     * ignored. Attach it untracked: it reads no reactive state, so it never needs to re-run.
+     */
+    reference: (ref: HTMLElement) => () => void;
 };

package/dist/utils/useKeyDown.svelte.js

@@ -1,23 +1,30 @@
 import { on } from 'svelte/events';
+/**
+ * Alt, Ctrl or Meta turn a key into a browser or OS shortcut (Alt+← is Back, Cmd+→ jumps to the
+ * line end). Shift is not one of them: Shift+Arrow is still the plain key to a widget.
+ */
+export const hasShortcutModifier = (event) => event.altKey || event.ctrlKey || event.metaKey;
 export const useKeyDown = (opts) => {
-    const eventCallback = (event) => {
-        if (opts.keys.includes(event.key)) {
-            if (opts.preventDefault !== false) {
-                event.preventDefault();
-            }
-            opts.callback(event);
+    const handle = (event, source) => {
+        if (!opts.keys.includes(event.key) || !opts.isActive())
+            return;
+        if (opts.ignoreModifiers && hasShortcutModifier(event))
+            return;
+        if (opts.preventDefault !== false) {
+            event.preventDefault();
         }
+        opts.callback(event, source);
     };
     $effect(() => {
         if (opts.isActive() && opts.onWindow?.()) {
-            return on(window, 'keydown', eventCallback);
+            return on(window, 'keydown', (event) => handle(event, 'window'));
         }
     });
     return {
-        reference: (ref) => {
-            if (opts.isActive() && !opts.onWindow?.()) {
-                return on(ref, 'keydown', eventCallback);
-            }
-        }
+        /**
+         * Listens on `ref` for as long as it is attached; keys typed while `isActive()` is false are
+         * ignored. Attach it untracked: it reads no reactive state, so it never needs to re-run.
+         */
+        reference: (ref) => on(ref, 'keydown', (event) => handle(event, 'element'))
     };
 };

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

@@ -1,3 +1,16 @@
+/** What moved the highlight: keys (and typeahead), the pointer, or the list changing underneath it. */
+export type HighlightReason = 'keyboard' | 'pointer' | 'list';
+/** Second argument of `onHighlightChange`: why the highlight moved and the event behind it. */
+export type HighlightDetails = {
+    reason: HighlightReason;
+    /** The originating KeyboardEvent or pointer event; absent for `'list'` changes. */
+    event?: Event;
+};
+/**
+ * What moving past either end does: `'wrap'` continues at the other end, `'input'` lands on no
+ * highlight first (focus stays in the input) and wraps from there, `false` stops at the end.
+ */
+export type ListLoop = 'wrap' | 'input' | false;
 type ListNavigationOptions<Value extends string = string> = {
     /**
      * Ordered, selectable values (already filtered — exclude disabled items).
@@ -5,11 +18,21 @@ type ListNavigationOptions<Value extends string = string> = {
      */
     values: () => Value[];
     /**
-     * DOM id of a value's option element — drives `aria-activedescendant` and scroll-into-view.
+     * DOM id of a value's option element — drives `aria-activedescendant` and scrolling.
+     * Leave it out and pass `idPrefix` to get collision-free ids from `nav.optionId`.
      */
     optionId?: (value: Value) => string;
-    /** Fires whenever the highlight moves (keyboard, hover, or re-anchoring). */
-    onHighlightChange?: (value: Value | undefined) => void;
+    /**
+     * Prefix for the ids `nav.optionId` hands out when `optionId` is omitted. Each distinct value
+     * gets the next number in sequence (`<prefix>-option-3`), so values such as `a.b` and `a_b`
+     * never collide and lookups stay constant-time however long the list is.
+     */
+    idPrefix?: string;
+    /**
+     * Fires whenever the highlight moves (keyboard, hover, or re-anchoring). The second argument
+     * says why and carries the originating event.
+     */
+    onHighlightChange?: (value: Value | undefined, details: HighlightDetails) => void;
     /**
      * Type-to-highlight: printable keys jump to the next value whose text starts with the
      * typed buffer. Only for lists whose focus is NOT in a text input (Select, not Combobox).
@@ -17,8 +40,46 @@ type ListNavigationOptions<Value extends string = string> = {
     typeahead?: (value: Value) => string;
     /** Fires on Enter with the highlighted value. */
     onSelect?: (value: Value) => void;
-    /** Wrap around both ends when moving past them. Default `true`. */
-    loop?: boolean;
+    /**
+     * Moving past either end: `'wrap'` (default, `true`), `'input'` (the end lands on no highlight,
+     * then wraps) or `false` (stop at the end).
+     */
+    loop?: boolean | ListLoop;
+    /**
+     * Whether the first value is highlighted on its own. `'always'` (default, the long-standing
+     * behaviour) keeps something highlighted whenever the list has values; `true` does it only
+     * while a `query` is typed; `false` never does, so Enter with no highlight is the consumer's.
+     */
+    autoHighlight?: boolean | 'always';
+    /** The typed query. Re-read reactively: changes reset the list scroll and drive `autoHighlight: true`. */
+    query?: () => string;
+    /**
+     * Whether the list is showing. When given, the highlight re-anchors each time it turns true and
+     * is left alone while it is false. Omit it for lists that are always visible.
+     */
+    open?: () => boolean;
+    /**
+     * The value to highlight when the list opens and when the query clears (the selected value).
+     * Read untracked, at those moments only.
+     */
+    anchor?: () => Value | undefined;
+    /**
+     * The element that scrolls the options. Highlighting scrolls only this element (never the
+     * page or other ancestors) and a changed query scrolls it back to the top. Defaults to the
+     * nearest ancestor of the option that scrolls vertically.
+     */
+    scrollContainer?: () => HTMLElement | null | undefined;
+};
+/**
+ * Hands each distinct value its own DOM id, numbered in the order the values are first asked
+ * for. Sanitizing a value into an id collides (`a.b` and `a_b` both become `a_b`) and searching
+ * for its index is quadratic; a map lookup is neither. Ids are stable for the life of the map.
+ */
+export declare const createOptionIds: <Value extends string = string>(prefix: string) => {
+    /** The id of `value`; the first request assigns the next number. */
+    get(value: Value): string;
+    /** Forgets every assignment (numbering carries on, so old ids are never reused). */
+    clear(): void;
 };
 /**
  * Value-driven keyboard navigation for combobox-style widgets (command palettes, dropdowns,
@@ -27,24 +88,44 @@ type ListNavigationOptions<Value extends string = string> = {
  *
  * Unlike `useNavigation` (DOM/index-based roving tabindex — right for menus, tabs, toolbars),
  * the highlight here is a *value*, so it survives the item set changing underneath it: when the
- * highlighted value disappears (typing in a filter), the highlight re-anchors to the first value.
+ * highlighted value disappears (typing in a filter), the highlight re-anchors per
+ * `autoHighlight` — the first value by default. With `open` and `anchor` it also lands on the
+ * selected value each time the list opens and when the query clears.
  *
  * Must be called during component init (it registers an `$effect`).
  *
  * Wire-up: `onkeydown={nav.onKeydown}` on the input, `aria-activedescendant={nav.activeDescendant}`,
- * `onpointermove={() => nav.setHighlighted(value)}` on rows, `aria-selected={nav.highlighted === value}`.
+ * `id={nav.optionId(value)}` and `onpointermove={(event) => nav.pointerHighlight(value, event)}` on
+ * rows, `aria-selected={nav.highlighted === value}`.
  */
 export declare const useListNavigation: <Value extends string = string>(opts: ListNavigationOptions<Value>) => {
     /** The currently highlighted value. */
     readonly highlighted: Value | undefined;
+    /** Why the highlight last moved, and the event behind it. */
+    readonly highlightDetails: HighlightDetails;
     /** DOM id of the highlighted option, for `aria-activedescendant`. */
     readonly activeDescendant: string | undefined;
-    /** Set the highlight without scrolling — for pointermove/hover. */
-    setHighlighted: (value: Value | undefined) => void;
-    highlight: (value: Value | undefined) => void;
-    move: (delta: number) => void;
-    first: () => void;
-    last: () => void;
+    /**
+     * DOM id of a value's option: `optionId` when given, else the next id in sequence for
+     * `idPrefix`. `undefined` when neither was provided.
+     */
+    optionId: (value: Value) => string | undefined;
+    /** Type-to-highlight state; `null` without the `typeahead` option. */
+    typeahead: {
+        /** True while typed characters are buffered (Space belongs to the search, not to selection). */
+        readonly isTyping: boolean;
+        /** Drop the buffered characters, e.g. on blur or close. */
+        reset: () => void;
+    } | null;
+    /** Set the highlight without scrolling — for hover. Prefer `pointerHighlight`. */
+    setHighlighted: (value: Value | undefined, details?: HighlightDetails) => void;
+    pointerHighlight: (value: Value | undefined, event?: MouseEvent | PointerEvent) => boolean;
+    highlight: (value: Value | undefined, details?: HighlightDetails) => void;
+    move: (delta: number, details?: HighlightDetails) => void;
+    first: (details?: HighlightDetails) => void;
+    last: (details?: HighlightDetails) => void;
+    reanchor: () => void;
+    scrollToHighlighted: () => void;
     onKeydown: (event: KeyboardEvent) => void;
 };
 export {};