entasis 0.11.0 → 0.13.0

package/dist/utils/trigger.js

@@ -0,0 +1,103 @@
+// The shared trigger contract (AGENTS.md proposed law 4): any element can open a disclosure
+// owner's popup. The owner writes `aria-haspopup`, `aria-expanded` and `aria-controls` on it,
+// a non-control element becomes a keyboard-reachable button, and a press on it requests the
+// change with `reason: 'trigger-press'` unless the element's own handler already acted or called
+// `event.preventDefault()`.
+import { focusableSelector } from './focus.js';
+/** Elements that may carry popup ARIA state. */
+export const POPUP_CONTROL = 'button, a[href], input, select, textarea, summary, [role="button"], [role="link"], [role="combobox"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="tab"], [role="option"], [role="treeitem"], [role="gridcell"], [role="switch"], [role="checkbox"]';
+/** Elements the browser already focuses and activates from the keyboard. */
+export const NATIVE_CONTROL = 'button, a[href], input, select, textarea, summary';
+const TRIGGER_ARIA = {
+    haspopup: 'aria-haspopup',
+    expanded: 'aria-expanded',
+    controls: 'aria-controls'
+};
+/**
+ * Writes the popup ARIA attributes on a trigger. Call inside an `$effect` so they follow the
+ * state. Only real controls carry them: a wrapper `div` or a presentational `span` used as an
+ * anchor must not (axe: aria-allowed-attr).
+ */
+export function writePopupAria(node, props) {
+    if (!node.matches(POPUP_CONTROL))
+        return;
+    for (const [prop, value] of Object.entries(props)) {
+        const name = TRIGGER_ARIA[prop];
+        if (value === undefined)
+            node.removeAttribute(name);
+        else
+            node.setAttribute(name, String(value));
+    }
+}
+/**
+ * Makes `node` a trigger that activates on click, and on Enter and Space when it is not a native
+ * control. A non-control element also gets `role="button"` and `tabindex="0"`. Returns cleanup.
+ */
+export function triggerActivation(node, options) {
+    const nativeControl = node.matches(NATIVE_CONTROL);
+    if (!node.matches(POPUP_CONTROL) && !node.hasAttribute('role')) {
+        node.setAttribute('role', 'button');
+    }
+    if (!nativeControl && !node.hasAttribute('tabindex'))
+        node.tabIndex = 0;
+    // The element's own handler wins. Svelte delegates `onclick` to the root, so it runs after
+    // this listener: the default action waits until the event has finished dispatching, then
+    // runs only if nothing cancelled the event or asked for an open state meanwhile.
+    let pending;
+    const press = (event) => {
+        if (options.enabled && !options.enabled())
+            return;
+        const requests = options.requests();
+        clearTimeout(pending);
+        pending = setTimeout(() => {
+            if (event.defaultPrevented || options.requests() !== requests)
+                return;
+            options.activate(event);
+        });
+    };
+    const onKeydown = (event) => {
+        if (nativeControl || event.target !== node)
+            return;
+        if (event.key !== 'Enter' && event.key !== ' ')
+            return;
+        event.preventDefault();
+        const requests = options.requests();
+        clearTimeout(pending);
+        pending = setTimeout(() => {
+            if (options.requests() !== requests || (options.enabled && !options.enabled()))
+                return;
+            options.activate(event);
+        });
+    };
+    node.addEventListener('click', press);
+    node.addEventListener('keydown', onKeydown);
+    return () => {
+        clearTimeout(pending);
+        node.removeEventListener('click', press);
+        node.removeEventListener('keydown', onKeydown);
+    };
+}
+/**
+ * The element focus returns to when a popup opened from `trigger` closes: the trigger when it is
+ * focusable, else the focusable element inside it that was pressed or focused (the country button
+ * inside a phone field's wrapper), else `null` (the focus scope's own default).
+ */
+export function triggerFocusTarget(trigger, event) {
+    if (trigger.matches(focusableSelector) && !trigger.matches(':disabled'))
+        return trigger;
+    const active = trigger.ownerDocument.activeElement;
+    if (active instanceof HTMLElement && active !== trigger && trigger.contains(active))
+        return active;
+    const target = event?.target;
+    if (target instanceof Element) {
+        const focusable = target.closest(focusableSelector);
+        if (focusable && trigger.contains(focusable))
+            return focusable;
+    }
+    return null;
+}
+/** The element that has focus now, or `null` when nothing does (the body). */
+export function focusedElement(document = globalThis.document) {
+    const active = document?.activeElement;
+    return active instanceof HTMLElement && active !== document.body ? active : null;
+}

package/dist/utils/typeahead.d.ts

@@ -3,10 +3,19 @@ export interface TypeaheadOptions<Item> {
     getText: (item: Item) => string;
     getCurrentIndex: () => number;
     onMatch: (index: number, item: Item) => void;
+    /**
+     * Items the search steps over, such as disabled or hidden ones: a match on one of them moves
+     * on to the next match instead of ending the search.
+     */
+    isItemDisabled?: (item: Item) => boolean;
     /** Milliseconds of silence before the buffer resets. */
     timeout?: number;
 }
+/** A field the user types into: text inputs, textareas and contenteditable regions. */
+export declare const isTextEntry: (target: EventTarget | null) => target is HTMLElement;
 export declare function createTypeahead<Item>(options: TypeaheadOptions<Item>): {
     handleKey: (event: KeyboardEvent) => boolean;
     reset: () => void;
+    /** True while the buffer holds typed characters (until the timeout or a `reset`). */
+    readonly isTyping: boolean;
 };

package/dist/utils/typeahead.js

@@ -1,12 +1,14 @@
-const isTextEntry = (target) => typeof HTMLElement !== 'undefined' &&
+const nonTextInputTypes = ['button', 'checkbox', 'radio', 'range', 'submit', 'reset', 'image'];
+/** A field the user types into: text inputs, textareas and contenteditable regions. */
+export const isTextEntry = (target) => typeof HTMLElement !== 'undefined' &&
     target instanceof HTMLElement &&
     (target.isContentEditable ||
         target.tagName === 'TEXTAREA' ||
-        (target.tagName === 'INPUT' &&
-            !['button', 'checkbox', 'radio', 'range', 'submit', 'reset'].includes(target.type)));
+        (target.tagName === 'INPUT' && !nonTextInputTypes.includes(target.type)));
 export function createTypeahead(options) {
     let buffer = '';
     let timer = null;
+    /** Empties the buffer and clears its timer; call it on focus-out and on destroy. */
     const reset = () => {
         buffer = '';
         if (timer)
@@ -21,12 +23,12 @@ export function createTypeahead(options) {
             return false;
         if (event.key === ' ' && buffer === '')
             return false; // Space activates, it does not search
-        if (timer)
-            clearTimeout(timer);
-        timer = setTimeout(reset, options.timeout ?? 1000);
         const items = options.getItems();
         if (items.length === 0)
             return false;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(reset, options.timeout ?? 1000);
         buffer += event.key.toLowerCase();
         const repeated = buffer.length > 1 && [...buffer].every((c) => c === buffer[0]);
         const needle = repeated ? buffer[0] : buffer;
@@ -35,12 +37,22 @@ export function createTypeahead(options) {
         const start = repeated || buffer.length === 1 ? current + 1 : current;
         for (let step = 0; step < items.length; step += 1) {
             const index = (((start + step) % items.length) + items.length) % items.length;
-            if (options.getText(items[index]).trim().toLowerCase().startsWith(needle)) {
-                options.onMatch(index, items[index]);
+            const item = items[index];
+            if (options.isItemDisabled?.(item))
+                continue;
+            if (options.getText(item).trim().toLowerCase().startsWith(needle)) {
+                options.onMatch(index, item);
                 return true;
             }
         }
         return true;
     };
-    return { handleKey, reset };
+    return {
+        handleKey,
+        reset,
+        /** True while the buffer holds typed characters (until the timeout or a `reset`). */
+        get isTyping() {
+            return buffer !== '';
+        }
+    };
 }

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

@@ -144,7 +144,7 @@ export type DndOver = {
  * containers on its own.
  *
  * Styling hooks: `data-dnd-dragging` on the dragged item (default 0.4 opacity
- * via an injected rule), `data-dnd-over` on a hovered container (an EMPTY
+ * via the Tailwind plugin base styles), `data-dnd-over` on a hovered container (an EMPTY
  * hovered list gets a default primary tint instead of an indicator line —
  * there is no index to point at; override via your own `data-dnd-over`
  * styles), `data-dnd-indicator` on the shared indicator line,

package/dist/utils/useDndList.svelte.js

@@ -80,27 +80,12 @@ const toLogicalEdge = (physical, element, axis) => {
     return physical === 'left' ? 'right' : physical === 'right' ? 'left' : physical;
 };
 // ---------------------------------------------------------------------------
-// Drop indicator + default dragging style: one fixed-position line and one
-// tiny stylesheet for the whole app, managed imperatively. Override via the
-// [data-dnd-indicator] / [data-dnd-dragging] selectors.
+// Drop indicator: one fixed-position line for the whole app, managed imperatively. The default
+// dragging style and the empty-list tint are plain rules in the Tailwind plugin CSS
+// (`tailwind/global.ts`), so nothing is injected into the document head and a strict CSP needs
+// no nonce for them. Override via the [data-dnd-indicator] / [data-dnd-dragging] selectors.
 // ---------------------------------------------------------------------------
 let indicatorEl = null;
-// Injected once per document, from the list attachment — indicator-less
-// (preview) lists need the data-dnd-dragging default and the empty-list tint
-// too, not just lists that ever draw the line.
-const ensureBaseStyles = () => {
-    if (document.querySelector('style[data-dnd-styles]'))
-        return;
-    const style = document.createElement('style');
-    style.setAttribute('data-dnd-styles', '');
-    // The empty-list rule is wrapped in :where() (zero specificity) so any
-    // consumer class on the container wins over the default tint.
-    style.textContent =
-        '[data-dnd-dragging]{opacity:.4;}' +
-            ':where([data-dnd-over="true"]:not(:has([data-dnd-item]))){' +
-            'background-color:color-mix(in oklab, var(--color-primary, currentColor) 6%, transparent);}';
-    document.head.appendChild(style);
-};
 const ensureIndicator = () => {
     // Query the DOM (not just the module variable) so HMR re-evaluations reuse
     // the existing node instead of orphaning it.
@@ -118,7 +103,6 @@ const ensureIndicator = () => {
         display: 'none'
     });
     document.body.appendChild(indicatorEl);
-    ensureBaseStyles();
     return indicatorEl;
 };
 const THICKNESS = 2;
@@ -283,7 +267,7 @@ const registerAutoScroll = (listEl) => {
  * containers on its own.
  *
  * Styling hooks: `data-dnd-dragging` on the dragged item (default 0.4 opacity
- * via an injected rule), `data-dnd-over` on a hovered container (an EMPTY
+ * via the Tailwind plugin base styles), `data-dnd-over` on a hovered container (an EMPTY
  * hovered list gets a default primary tint instead of an indicator line —
  * there is no index to point at; override via your own `data-dnd-over`
  * styles), `data-dnd-indicator` on the shared indicator line,
@@ -499,7 +483,6 @@ export const useDndList = (options) => {
     const list = (element) => {
         element.setAttribute('data-dnd-list', listId);
         listElements.add(element);
-        ensureBaseStyles();
         /** Rows belonging to THIS list only — nested lists' rows don't count. */
         const ownRows = () => [...element.querySelectorAll('[data-dnd-item]')].filter((row) => row.closest('[data-dnd-list]') === element);
         const terminalEdge = () => {
@@ -522,7 +505,7 @@ export const useDndList = (options) => {
             else {
                 // Empty list: there is no index to point at, so no line — the
                 // container itself signals via [data-dnd-over] (default tint from
-                // the injected stylesheet, override with your own styles).
+                // the plugin base styles, override with your own styles).
                 hideIndicator();
             }
         };

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

@@ -1,3 +1,11 @@
+import type { OpenChangeDetails } from './openChange.js';
+/**
+ * Where focus goes when an overlay closes. `true` (or nothing) restores it to the opener, else the
+ * most recent element still on the page; `false` leaves focus alone; an element receives it. A
+ * function is called with the details of the change that closed the overlay (`null` when it
+ * closed without one) and returns any of these; returning nothing restores as usual.
+ */
+export type FocusOnClose = boolean | HTMLElement | null | ((details: OpenChangeDetails | null) => HTMLElement | boolean | null | void);
 export interface FocusScopeOptions {
     /** Scope is live (typically: it is the topmost layer of its kind). */
     isActive: () => boolean;
@@ -14,7 +22,28 @@ export interface FocusScopeOptions {
     returnTo?: () => HTMLElement | null;
     /** Mark every sibling subtree up to `<body>` `inert` while active (modal scopes). */
     inertSiblings?: () => boolean;
+    /** The owner's `focusOnClose` choice; see `FocusOnClose`. Wins over `restoreFocus`. */
+    focusOnClose?: () => FocusOnClose | undefined;
+    /**
+     * The change that closed the overlay. A close by Escape or from the keyboard returns focus
+     * with a visible focus ring, and `focusOnClose` functions receive it.
+     */
+    closeDetails?: () => OpenChangeDetails | null;
 }
+/** What `focusOnClose` resolves to for one close: leave focus, restore as usual, or this element. */
+export declare function resolveFocusOnClose(choice: FocusOnClose | undefined, details: OpenChangeDetails | null): false | 'default' | HTMLElement;
+/**
+ * The node of the newest live scope that contains Tab and holds `element` (a modal dialog around a
+ * popover's trigger), or `null`. Lets Tab that has nowhere to go inside a portaled panel wrap
+ * within the modal instead of leaving it.
+ */
+export declare function findTrappingScope(element: Node): HTMLElement | null;
+/**
+ * Whether the focus event being dispatched right now comes from an overlay handing focus back to
+ * its opener. Read it synchronously inside a `focus` or `focusin` listener: a tooltip does not
+ * open for focus the page returned, only for focus the user moved.
+ */
+export declare const isRestoringFocus: () => boolean;
 export declare function useFocusScope(options: FocusScopeOptions): {
     attachment: (target: HTMLElement) => () => void;
     restore: () => void;

package/dist/utils/useFocusScope.svelte.js

@@ -3,7 +3,15 @@
 // to the opener when the scope goes away. Radix calls this FocusScope.
 import { on } from 'svelte/events';
 import { tick, untrack } from 'svelte';
-import { getTabbableElements, resolveInitialFocus } from './focus.js';
+import { composedContains, getDeepActiveElement, getTabbableElements, isFocusable, isTextField, isWebKit, resolveInitialFocus } from './focus.js';
+import { findFocusFallback, installFocusHistory } from './focusHistory.js';
+/** What `focusOnClose` resolves to for one close: leave focus, restore as usual, or this element. */
+export function resolveFocusOnClose(choice, details) {
+    const value = typeof choice === 'function' ? choice(details) : choice;
+    if (value === false)
+        return false;
+    return value instanceof HTMLElement ? value : 'default';
+}
 // `inert` refcount per element so stacked modals release it in any order.
 const inertCounts = new WeakMap();
 const makeInert = (element) => {
@@ -22,26 +30,117 @@ const releaseInert = (element) => {
         inertCounts.set(element, count - 1);
     }
 };
+/** Whether focus is on `<body>`, or inside the node (shadow roots included). */
 const isFocusInside = (node) => {
-    const active = node.ownerDocument.activeElement;
-    return !active || active === node.ownerDocument.body || node.contains(active);
+    const doc = node.ownerDocument;
+    const active = getDeepActiveElement(doc);
+    return !active || active === doc.body || composedContains(node, active);
 };
+/** Mounted scopes, in the order they last became active (the newest is last). */
+const scopes = [];
+/**
+ * The node of the newest live scope that contains Tab and holds `element` (a modal dialog around a
+ * popover's trigger), or `null`. Lets Tab that has nowhere to go inside a portaled panel wrap
+ * within the modal instead of leaving it.
+ */
+export function findTrappingScope(element) {
+    for (let index = scopes.length - 1; index >= 0; index -= 1) {
+        const scope = scopes[index];
+        if (scope.node.isConnected &&
+            scope.isActive() &&
+            scope.traps() &&
+            composedContains(scope.node, element))
+            return scope.node;
+    }
+    return null;
+}
+// Counts the `focus()` calls a closing overlay makes to give focus back. Their `focusin` events
+// are dispatched inside the call, so a listener can tell restored focus from focus the user moved.
+let restoringFocus = 0;
+/**
+ * Whether the focus event being dispatched right now comes from an overlay handing focus back to
+ * its opener. Read it synchronously inside a `focus` or `focusin` listener: a tooltip does not
+ * open for focus the page returned, only for focus the user moved.
+ */
+export const isRestoringFocus = () => restoringFocus > 0;
+const usable = (element) => !!element && element.isConnected && !element.closest('[inert]') && isFocusable(element);
 export function useFocusScope(options) {
     let node = null;
     let returnTarget = null;
     let restored = false;
-    /** Idempotent; only moves focus when it is still on `<body>` or inside the scope. */
+    /** Initial focus is applied once per mount: a later re-activation leaves focus where it is. */
+    let initialFocusDone = false;
+    let lastFocusedInside = null;
+    /** Releases the `inert` this scope set on the page behind it; idempotent. */
+    let releaseSiblings = () => { };
+    /** A close by Escape or from the keyboard shows the focus ring where focus lands. */
+    const focusVisibleOnClose = () => {
+        const details = options.closeDetails?.() ?? null;
+        return details?.reason === 'escape-key' || details?.interaction === 'keyboard';
+    };
+    const focusElement = (element, focusVisible = false) => {
+        // `focusVisible` makes engines that do not infer a focus ring from the last input (Firefox,
+        // Safari after a pointer open) show it; engines that do not know the option ignore it. It is
+        // left out otherwise: `false` would suppress the ring a keyboard user is owed.
+        restoringFocus += 1;
+        try {
+            element.focus({
+                preventScroll: true,
+                ...(focusVisible ? { focusVisible } : {})
+            });
+        }
+        finally {
+            restoringFocus -= 1;
+        }
+    };
+    /**
+     * Where focus goes when the scope's own target is gone: the last element that had focus in the
+     * scope still showing below this one (a Dialog under a closing Confirmation), else the most
+     * recent element in the focus history that is still on the page.
+     */
+    const fallbackTarget = (scope) => {
+        for (let index = scopes.length - 1; index >= 0; index -= 1) {
+            const other = scopes[index];
+            if (other.node === scope || !other.node.isConnected || !other.isActive())
+                continue;
+            const candidate = other.lastFocused();
+            if (usable(candidate) && !composedContains(scope, candidate))
+                return candidate;
+        }
+        return findFocusFallback(scope.ownerDocument, { exclude: scope });
+    };
+    /**
+     * Idempotent; only moves focus when it is still on `<body>` or inside the scope. The page
+     * behind is released first: an `inert` opener cannot take focus, and a close that is
+     * reported once its transition ends runs this before the node is torn down.
+     */
     const restore = () => {
         if (restored)
             return;
         restored = true;
-        if (!(options.restoreFocus?.() ?? true))
+        releaseSiblings();
+        const scope = node;
+        if (!scope)
             return;
-        const target = options.returnTo?.() ?? returnTarget;
-        returnTarget = null;
-        if (!target?.isConnected || !node || !isFocusInside(node))
+        // Safari scrolls the page when a focused text field leaves the document: let go of it
+        // while it is still mounted.
+        const active = getDeepActiveElement(scope.ownerDocument);
+        if (isWebKit() && active && composedContains(scope, active) && isTextField(active)) {
+            active.blur();
+        }
+        const choice = resolveFocusOnClose(options.focusOnClose?.(), options.closeDetails?.() ?? null);
+        if (choice === false)
             return;
-        target.focus({ preventScroll: true });
+        if (choice === 'default' && !(options.restoreFocus?.() ?? true))
+            return;
+        if (!isFocusInside(scope))
+            return;
+        const target = choice !== 'default'
+            ? choice
+            : [options.returnTo?.() ?? null, returnTarget].find(usable) || fallbackTarget(scope);
+        returnTarget = null;
+        if (usable(target))
+            focusElement(target, focusVisibleOnClose());
     };
     const applyInitialFocus = (target) => {
         const mode = options.initialFocus?.() ?? 'first';
@@ -52,50 +151,110 @@ export function useFocusScope(options) {
             target.tabIndex = -1;
         element.focus({ preventScroll: true });
     };
+    const insideOtherScope = (element) => scopes.some((other) => other.node !== node && other.isActive() && composedContains(other.node, element));
     const handleKeyDown = (event) => {
         if (!node || event.key !== 'Tab' || event.defaultPrevented)
             return;
+        if (event.ctrlKey || event.metaKey)
+            return;
         if (!(options.trap?.() ?? options.isActive()))
             return;
+        const doc = node.ownerDocument;
+        const active = getDeepActiveElement(doc);
+        const inside = !!active && composedContains(node, active);
+        // A panel opened from inside the scope (a popover over a dialog) handles its own Tab.
+        if (active && !inside && insideOtherScope(active))
+            return;
         const tabbable = getTabbableElements(node);
         if (tabbable.length === 0) {
             event.preventDefault();
             node.focus();
             return;
         }
-        const active = node.ownerDocument.activeElement;
-        const index = tabbable.indexOf(active);
-        const first = tabbable[0];
-        const last = tabbable[tabbable.length - 1];
-        const wrapBackward = event.shiftKey && index <= 0;
-        const wrapForward = !event.shiftKey && index === tabbable.length - 1;
-        const outside = active ? !node.contains(active) : true;
-        if (!wrapBackward && !wrapForward && !outside)
-            return;
+        const index = active instanceof HTMLElement ? tabbable.indexOf(active) : -1;
+        const edge = event.shiftKey ? tabbable[tabbable.length - 1] : tabbable[0];
+        let next;
+        if (index >= 0) {
+            // Move focus ourselves rather than trusting the engine's Tab order: WebKit without
+            // Full Keyboard Access skips buttons, which would let Tab leave the scope.
+            const step = event.shiftKey ? index - 1 : index + 1;
+            next = tabbable[(step + tabbable.length) % tabbable.length];
+        }
+        else if (!inside || active === node) {
+            next = edge;
+        }
+        else {
+            // Focus is on something the list does not know (a roving item, an element in a shadow
+            // root): the engine moves it, unless nothing tabbable lies ahead, which would leave.
+            const ahead = tabbable.some((element) => {
+                const position = active.compareDocumentPosition(element);
+                return event.shiftKey
+                    ? position & Node.DOCUMENT_POSITION_PRECEDING
+                    : position & Node.DOCUMENT_POSITION_FOLLOWING;
+            });
+            if (ahead)
+                return;
+            next = edge;
+        }
         event.preventDefault();
-        (event.shiftKey ? last : first).focus();
+        next.focus();
     };
     const attachment = (target) => {
         return untrack(() => {
             node = target;
             restored = false;
-            const active = target.ownerDocument.activeElement;
-            returnTarget =
-                active instanceof HTMLElement && active !== target.ownerDocument.body ? active : null;
+            initialFocusDone = false;
+            const doc = target.ownerDocument;
+            const active = getDeepActiveElement(doc);
+            returnTarget = active instanceof HTMLElement && active !== doc.body ? active : null;
+            lastFocusedInside =
+                active instanceof HTMLElement && composedContains(target, active) ? active : null;
             if (target.tabIndex < 0)
                 target.tabIndex = -1;
+            const record = {
+                node: target,
+                isActive: () => options.isActive(),
+                traps: () => options.trap?.() ?? options.isActive(),
+                lastFocused: () => lastFocusedInside
+            };
+            scopes.push(record);
             const inerted = [];
-            const cleanups = [on(target.ownerDocument, 'keydown', handleKeyDown)];
+            releaseSiblings = () => inerted.splice(0).forEach(releaseInert);
+            const cleanups = [
+                installFocusHistory(doc),
+                on(doc, 'keydown', handleKeyDown),
+                // Remember where focus last was inside, for the scope below to hand focus back to.
+                on(target, 'focusin', (event) => {
+                    const origin = event.composedPath()[0] ?? event.target;
+                    if (origin instanceof HTMLElement)
+                        lastFocusedInside = origin;
+                }),
+                // A focused element that is disabled or removed drops focus with no new target; it is
+                // still the best place to return to if it comes back.
+                on(target, 'focusout', (event) => {
+                    const origin = event.composedPath()[0] ?? event.target;
+                    if (!event.relatedTarget && origin instanceof HTMLElement)
+                        lastFocusedInside = origin;
+                })
+            ];
             $effect(() => {
                 const active = options.isActive();
                 if (!active)
                     return;
+                // The newest active scope is the last one: a scope that becomes active again after the
+                // one above it closed is the next to receive focus.
+                const position = scopes.indexOf(record);
+                if (position >= 0)
+                    scopes.push(...scopes.splice(position, 1));
                 // Wait for the intro to mount children before picking the initial target.
                 let cancelled = false;
                 void tick().then(() => {
-                    if (!cancelled && node && !node.contains(node.ownerDocument.activeElement)) {
+                    if (cancelled || !node || initialFocusDone)
+                        return;
+                    initialFocusDone = true;
+                    const current = getDeepActiveElement(node.ownerDocument);
+                    if (!current || !composedContains(node, current))
                         applyInitialFocus(node);
-                    }
                 });
                 if (options.inertSiblings?.()) {
                     let current = target;
@@ -116,13 +275,16 @@ export function useFocusScope(options) {
                 }
                 return () => {
                     cancelled = true;
-                    inerted.splice(0).forEach(releaseInert);
+                    releaseSiblings();
                 };
             });
             return () => {
                 cleanups.forEach((cleanup) => cleanup());
-                inerted.splice(0).forEach(releaseInert);
+                releaseSiblings();
                 restore();
+                const at = scopes.indexOf(record);
+                if (at >= 0)
+                    scopes.splice(at, 1);
                 node = null;
             };
         });

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

@@ -1,12 +1,52 @@
+import type { HoverIntentGroup } from './hoverIntent.js';
 type HoverActionHandlerOptions = {
+    /**
+     * Checked when the pointer enters (no delay starts while inactive), again once the delay
+     * elapses, and when it leaves; never when attaching.
+     */
     isActive: () => boolean;
-    onMouseEnter?: () => void;
-    onMouseLeave?: () => void;
-    delay?: number;
+    /** Receives the `mouseenter` event that began the hover, also once a delay has elapsed. */
+    onMouseEnter?: (event: MouseEvent) => void;
+    /** Receives the `mouseleave` (or the `mouseout` that stood in for it) that ended the hover. */
+    onMouseLeave?: (event: MouseEvent) => void;
+    /**
+     * Milliseconds between the pointer entering and `onMouseEnter`. Read on every enter, so a
+     * getter or a function follows a changing value; a function also lets a class field read
+     * options its constructor has not bound yet.
+     */
+    delay?: number | (() => number | undefined);
+    /**
+     * Pointer types whose hover is ignored. Default `['touch']`: a tap fires compatibility mouse
+     * events, `mouseenter` included, that are not a hover.
+     */
+    ignorePointerTypes?: readonly string[];
+    /**
+     * Whether a disabled trigger (`:disabled`, `aria-disabled="true"`, or a `data-disabled` other
+     * than `"false"`) is skipped, on enter and again when the delay elapses. Default `true`.
+     * Tooltips opt out: they often explain why their trigger is disabled.
+     */
+    skipDisabled?: boolean;
+    /** Warm-up group: while it is warm for the trigger, the delay is skipped. */
+    group?: () => HoverIntentGroup | null | undefined;
+    /** Whether the owner's popup is open. While it is, the owner counts as open in `group`. */
+    isOpen?: () => boolean;
+    /** Whether a node is inside the owner's open popup; see `HoverIntentMember.contains`. */
+    contains?: (node: Node) => boolean;
 };
+/**
+ * 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 declare const useHoverAction: (props: HoverActionHandlerOptions) => {
-    reference: (ref: HTMLElement) => (() => void) | null;
+    reference: (ref: HTMLElement) => () => void;
     destroy: () => void;
+    /**
+     * 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: () => void;
     readonly isHovered: boolean;
 };
 export {};