entasis 0.11.0 → 0.12.0

package/dist/utils/hoverIntent.d.ts

@@ -0,0 +1,42 @@
+/**
+ * How long after the last hover popup closed the next one still opens without its delay. Matches
+ * the tooltip warm-up that predates the shared group.
+ */
+export declare const HOVER_WARM_WINDOW_MS = 400;
+/** An open hover popup, as the group sees it. */
+export type HoverIntentMember = {
+    /**
+     * Whether `node` is inside this popup. A trigger inside an open popup (a tooltip in a hover
+     * card, a nested card) is not handed the warm-up by that popup: entering it is not a move
+     * from one hover target to the next.
+     */
+    contains?: (node: Node) => boolean;
+};
+/**
+ * Hover warm-up shared by tooltips, hover cards and hover-opened popovers. While one of them is
+ * open, and for `windowMs` after the last one closed, the next one opens without its delay, so
+ * running the pointer along a toolbar or a row of links does not wait at every stop.
+ *
+ * Plain fields: the group is read when a pointer arrives, never rendered.
+ */
+export declare class HoverIntentGroup {
+    #private;
+    readonly windowMs: number;
+    constructor(windowMs?: number);
+    /**
+     * Counts a popup as open until the returned function runs. Each call is its own membership, so
+     * the same member object can join twice without one leave ending both.
+     */
+    join(member?: HoverIntentMember): () => void;
+    /** Records a close at `time` for a surface that does not track membership. */
+    markClosed(time?: number): void;
+    /** When the last open popup closed, or `null` before any did. */
+    get lastClosedAt(): number | null;
+    /**
+     * Whether a hover arriving on `trigger` skips its delay: another popup is open (one that does
+     * not contain the trigger), or the last one closed less than `windowMs` ago.
+     */
+    isWarm(trigger?: Node | null): boolean;
+    /** `delay`, or 0 while the group is warm for `trigger`. */
+    resolveDelay(delay: number, trigger?: Node | null): number;
+}

package/dist/utils/hoverIntent.js

@@ -0,0 +1,57 @@
+/**
+ * How long after the last hover popup closed the next one still opens without its delay. Matches
+ * the tooltip warm-up that predates the shared group.
+ */
+export const HOVER_WARM_WINDOW_MS = 400;
+/**
+ * Hover warm-up shared by tooltips, hover cards and hover-opened popovers. While one of them is
+ * open, and for `windowMs` after the last one closed, the next one opens without its delay, so
+ * running the pointer along a toolbar or a row of links does not wait at every stop.
+ *
+ * Plain fields: the group is read when a pointer arrives, never rendered.
+ */
+export class HoverIntentGroup {
+    windowMs;
+    #open = new Set();
+    #lastClosedAt = null;
+    constructor(windowMs = HOVER_WARM_WINDOW_MS) {
+        this.windowMs = windowMs;
+    }
+    /**
+     * Counts a popup as open until the returned function runs. Each call is its own membership, so
+     * the same member object can join twice without one leave ending both.
+     */
+    join(member = {}) {
+        const entry = { contains: member.contains };
+        this.#open.add(entry);
+        return () => {
+            if (!this.#open.delete(entry))
+                return;
+            if (this.#open.size === 0)
+                this.#lastClosedAt = Date.now();
+        };
+    }
+    /** Records a close at `time` for a surface that does not track membership. */
+    markClosed(time = Date.now()) {
+        this.#lastClosedAt = time;
+    }
+    /** When the last open popup closed, or `null` before any did. */
+    get lastClosedAt() {
+        return this.#lastClosedAt;
+    }
+    /**
+     * Whether a hover arriving on `trigger` skips its delay: another popup is open (one that does
+     * not contain the trigger), or the last one closed less than `windowMs` ago.
+     */
+    isWarm(trigger) {
+        for (const member of this.#open) {
+            if (!trigger || !member.contains?.(trigger))
+                return true;
+        }
+        return this.#lastClosedAt !== null && Date.now() - this.#lastClosedAt < this.windowMs;
+    }
+    /** `delay`, or 0 while the group is warm for `trigger`. */
+    resolveDelay(delay, trigger) {
+        return this.isWarm(trigger) ? 0 : delay;
+    }
+}

package/dist/utils/id.d.ts

@@ -3,3 +3,10 @@
  * Never empty, and never shorter than 8 characters after the prefix.
  */
 export declare const createId: (prefix?: string) => string;
+/**
+ * Finds an element by id in the tree `from` lives in: the document, or the shadow root when it
+ * renders inside one (`document.getElementById` cannot see into a shadow tree). Falls back to the
+ * page's document, where a panel portaled out of a shadow root ends up. `from` is any node of
+ * that tree; without one the page's document is searched.
+ */
+export declare const elementById: (from: Node | null | undefined, id: string) => HTMLElement | null;

package/dist/utils/id.js

@@ -24,3 +24,18 @@ export const createId = (prefix) => {
         : `${Date.now().toString(36)}-${randomSegment()}`;
     return prefix ? `${prefix}-${id}` : id;
 };
+/**
+ * Finds an element by id in the tree `from` lives in: the document, or the shadow root when it
+ * renders inside one (`document.getElementById` cannot see into a shadow tree). Falls back to the
+ * page's document, where a panel portaled out of a shadow root ends up. `from` is any node of
+ * that tree; without one the page's document is searched.
+ */
+export const elementById = (from, id) => {
+    const root = from?.getRootNode?.();
+    if (root && 'getElementById' in root) {
+        const found = root.getElementById(id);
+        if (found)
+            return found;
+    }
+    return typeof document === 'undefined' ? null : document.getElementById(id);
+};

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

@@ -1,7 +1,14 @@
 import { SvelteSet } from 'svelte/reactivity';
+import type { OpenChangeInit, OpenChangeReason } from './openChange.js';
 import { LAYER_Z_BASE } from '../components/Theme/theme.layers.js';
 export type LayerKind = keyof typeof LAYER_Z_BASE;
-export type DismissReason = 'escape' | 'outside';
+/** The open-change reasons the layer stack itself reports. */
+export type DismissReason = Extract<OpenChangeReason, 'escape-key' | 'outside-press' | 'close-watcher'>;
+/** A dismissal the stack asks a layer's owner to apply, in `onOpenChange` details terms. */
+export interface LayerDismissRequest extends OpenChangeInit {
+    reason: DismissReason;
+    event: Event;
+}
 export interface LayerOptions {
     kind: LayerKind;
     isOpen: () => boolean;
@@ -9,7 +16,11 @@ export interface LayerOptions {
     isModal: () => boolean;
     dismissOnEscape?: () => boolean;
     dismissOnOutside?: () => boolean;
-    onDismiss?: (reason: DismissReason) => void;
+    /**
+     * Closes the layer for `request.reason`. Return `false` when the owner's `onOpenChange`
+     * cancelled the change: the stack then leaves the originating event untouched.
+     */
+    onDismiss?: (request: LayerDismissRequest) => boolean | void;
     /** Owner state, exposed to siblings that need more than the handle (e.g. the backdrop). */
     state?: unknown;
     /**
@@ -19,13 +30,28 @@ export interface LayerOptions {
      */
     parent?: LayerHandle | null;
 }
+/**
+ * The layer the calling component renders inside, as a getter read when a layer registers.
+ * Call during component initialisation.
+ */
+export declare function useParentLayer(): () => LayerHandle | null;
+/**
+ * Makes `resolve()` the parent layer of every layer registered below the calling component, for
+ * an owner that registers its own layer later, in a child created on open (a closed Popover
+ * registers none). Call during component initialisation.
+ */
+export declare function provideLayer(resolve: () => LayerHandle | null): void;
 export declare class LayerHandle {
     #private;
     readonly kind: LayerKind;
     readonly options: LayerOptions;
-    readonly parent: LayerHandle | null;
     /** Global sequence assigned on every open; later opens sit above earlier ones. */
     openOrder: number;
+    /**
+     * When the layer last opened, on the `Event.timeStamp` clock. A press that began earlier
+     * belongs to whatever opened it and never dismisses it.
+     */
+    openedAt: number;
     /** DOM nodes that count as "inside" this layer (panel, trigger…). */
     readonly nodes: SvelteSet<Node>;
     /** Index in the open stack (bottom = 0), -1 when closed. */
@@ -38,6 +64,8 @@ export declare class LayerHandle {
     kindDepth: number;
     zIndex: number;
     constructor(stack: LayerStack, options: LayerOptions);
+    /** The layer this one renders inside, or `null`. */
+    get parent(): LayerHandle | null;
     get isOpen(): boolean;
     get isModal(): boolean;
     get state(): unknown;
@@ -54,7 +82,7 @@ export declare class LayerStack {
     constructor();
     /**
      * Registers a layer for the lifetime of the calling component. Call during component
-     * initialisation (it installs an `$effect`).
+     * initialisation (it installs `$effect`s).
      */
     register(options: LayerOptions): LayerHandle;
     remove(handle: LayerHandle): void;

package/dist/utils/layers.svelte.js

@@ -1,6 +1,6 @@
 // One registry for every floating surface (dialogs, popovers, menus, tooltips, windows,
 // lightboxes). It decides which layer is on top, hands out z-indexes in open order, and
-// dispatches Escape / outside-pointer dismissal to the right layer only — the
+// dispatches Escape / outside-pointer / platform close requests to the right layer only — the
 // "dismissable layer" that Radix, Bits and Ark build every overlay on.
 import { on } from 'svelte/events';
 import { getContext, hasContext, setContext, untrack } from 'svelte';
@@ -8,12 +8,59 @@ import { SvelteSet } from 'svelte/reactivity';
 import { Registry } from './registry.svelte.js';
 import { LAYER_Z_BASE, LAYER_Z_STEP } from '../components/Theme/theme.layers.js';
 const LAYER_CONTEXT = Symbol('entasis:layer');
+/**
+ * The layer the calling component renders inside, as a getter read when a layer registers.
+ * Call during component initialisation.
+ */
+export function useParentLayer() {
+    const context = hasContext(LAYER_CONTEXT) ? getContext(LAYER_CONTEXT) : null;
+    return typeof context === 'function' ? context : () => context;
+}
+/**
+ * Makes `resolve()` the parent layer of every layer registered below the calling component, for
+ * an owner that registers its own layer later, in a child created on open (a closed Popover
+ * registers none). Call during component initialisation.
+ */
+export function provideLayer(resolve) {
+    setContext(LAYER_CONTEXT, resolve);
+}
+/** Movement in px after which a touch on the page is a scroll, not a tap. */
+const TAP_SLOP = 10;
+/**
+ * The current time on the clock events are stamped with (`Event.timeStamp`), so it compares with
+ * the time a press began.
+ */
+const eventClockNow = () => new Event('entasis:now').timeStamp;
+/**
+ * The platform close request (`CloseWatcher`) is used on Android only, where it is the Back
+ * gesture. On desktop it would turn an Escape that an inner control stopped (without preventing)
+ * into a second, unwanted close; Escape keeps its own keydown path there.
+ */
+const closeWatcherConstructor = () => {
+    if (typeof window === 'undefined')
+        return null;
+    const constructor = window.CloseWatcher;
+    if (!constructor)
+        return null;
+    const navigatorData = navigator;
+    const android = navigatorData.userAgentData?.platform === 'Android' || /android/i.test(navigator.userAgent);
+    return android ? constructor : null;
+};
 export class LayerHandle {
     kind;
     options;
-    parent;
+    /**
+     * The parent from context, read on each access: a layer built while its owner was closed (a
+     * mobile-sheet Dialog inside a closed Popover) reaches the owner's layer once it opens.
+     */
+    #resolveParent;
     /** Global sequence assigned on every open; later opens sit above earlier ones. */
     openOrder = $state(0);
+    /**
+     * When the layer last opened, on the `Event.timeStamp` clock. A press that began earlier
+     * belongs to whatever opened it and never dismisses it.
+     */
+    openedAt = 0;
     /** DOM nodes that count as "inside" this layer (panel, trigger…). */
     nodes = new SvelteSet();
     #stack;
@@ -30,12 +77,8 @@ export class LayerHandle {
         this.#stack = stack;
         this.kind = options.kind;
         this.options = options;
-        this.parent =
-            options.parent !== undefined
-                ? options.parent
-                : hasContext(LAYER_CONTEXT)
-                    ? getContext(LAYER_CONTEXT)
-                    : null;
+        const explicit = options.parent;
+        this.#resolveParent = explicit !== undefined ? () => explicit : useParentLayer();
         this.stackIndex = $derived(stack.open.indexOf(this));
         this.isTop = $derived(this.stackIndex >= 0 && this.stackIndex === stack.open.length - 1);
         this.isTopOfKind = $derived(this.isOpen && stack.ofKind(this.kind).at(-1) === this);
@@ -46,6 +89,11 @@ export class LayerHandle {
         });
         this.zIndex = $derived(LAYER_Z_BASE[this.kind] + this.openOrder * LAYER_Z_STEP);
     }
+    /** The layer this one renders inside, or `null`. */
+    get parent() {
+        const parent = this.#resolveParent();
+        return parent === this ? null : parent;
+    }
     get isOpen() {
         return this.options.isOpen();
     }
@@ -73,29 +121,68 @@ export class LayerStack {
     // ignored Escape).
     #layers = new Registry();
     #seq = 0;
+    /** A touch press outside non-modal layers, judged when the finger lifts. */
+    #pendingTap = null;
+    /** An Escape keydown whose dismissal was cancelled, until its task ends. */
+    #cancelledEscape = null;
     /** Open layers sorted bottom → top. */
     open = $derived(this.#layers.items.filter((layer) => layer.isOpen).sort((a, b) => a.openOrder - b.openOrder));
     topModal = $derived([...this.open].reverse().find((layer) => layer.isModal));
     ofKind(kind) {
         return this.open.filter((layer) => layer.kind === kind);
     }
+    /** The documents whose listeners are attached now, each with the function that removes them. */
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- imperative listener bookkeeping, written from the effect that syncs it
+    #listening = new Map();
     constructor() {
         // Listeners exist only while something is open. Escape goes to the top layer alone;
-        // a pointer press dismisses every non-hit layer above the first layer it lands in.
+        // a pointer press dismisses every non-hit layer above the first layer it lands in. They
+        // sit on the page's document and on the owner document of every open layer's nodes, so a
+        // popup rendered into an iframe (or a portal container in another document) hears its
+        // own Escape and outside presses. Documents are added and dropped as layers come and go;
+        // a pending touch tap survives that, and only ends when nothing is open.
         $effect(() => {
-            if (this.open.length === 0)
-                return;
-            const offKey = on(window, 'keydown', this.#onKeyDown);
-            const offPointer = on(document, 'pointerdown', this.#onPointerDown, { capture: true });
-            return () => {
+            const documents = [];
+            if (this.open.length > 0) {
+                documents.push(document);
+                for (const layer of this.open) {
+                    for (const node of layer.nodes) {
+                        const owner = node.ownerDocument;
+                        if (owner && !documents.includes(owner))
+                            documents.push(owner);
+                    }
+                }
+            }
+            untrack(() => this.#syncDocuments(documents));
+        });
+        $effect(() => () => untrack(() => this.#syncDocuments([])));
+    }
+    #syncDocuments(documents) {
+        for (const [owner, off] of this.#listening) {
+            if (documents.includes(owner))
+                continue;
+            off();
+            this.#listening.delete(owner);
+        }
+        for (const owner of documents) {
+            if (this.#listening.has(owner))
+                continue;
+            const view = owner.defaultView;
+            if (!view)
+                continue;
+            const offKey = on(view, 'keydown', this.#onKeyDown);
+            const offPointer = on(owner, 'pointerdown', this.#onPointerDown, { capture: true });
+            this.#listening.set(owner, () => {
                 offKey();
                 offPointer();
-            };
-        });
+            });
+        }
+        if (this.#listening.size === 0)
+            this.#pendingTap?.();
     }
     /**
      * Registers a layer for the lifetime of the calling component. Call during component
-     * initialisation (it installs an `$effect`).
+     * initialisation (it installs `$effect`s).
      */
     register(options) {
         const handle = new LayerHandle(this, options);
@@ -105,23 +192,79 @@ export class LayerStack {
             if (options.isOpen()) {
                 untrack(() => {
                     handle.openOrder = ++this.#seq;
+                    handle.openedAt = eventClockNow();
                 });
             }
         });
+        this.#watchCloseRequests(handle);
         $effect(() => () => this.remove(handle));
         return handle;
     }
     remove(handle) {
         this.#layers.delete(handle);
     }
+    /**
+     * One `CloseWatcher` per open modal layer that Escape could dismiss, created in open order, so
+     * the Android Back gesture closes the top layer instead of leaving the page. A watcher the
+     * browser closed while its layer stays open (a refused request it could not keep) is replaced.
+     */
+    #watchCloseRequests(handle) {
+        let generation = $state(0);
+        $effect(() => {
+            void generation;
+            if (!handle.isOpen || !handle.isModal || !handle.options.dismissOnEscape?.())
+                return;
+            const CloseWatcher = untrack(closeWatcherConstructor);
+            if (!CloseWatcher)
+                return;
+            const watcher = new CloseWatcher();
+            const offCancel = on(watcher, 'cancel', this.#onCloseRequest);
+            const offClose = on(watcher, 'close', () => {
+                if (handle.isOpen)
+                    generation += 1;
+            });
+            return () => {
+                offCancel();
+                offClose();
+                watcher.destroy();
+            };
+        });
+    }
+    /** The same rule as Escape: the top layer alone, and only when Escape may dismiss it. */
+    #onCloseRequest = (event) => {
+        // Chromium turns an Escape nobody prevented into a close request after dispatch: that
+        // Escape's dismissal was already refused, so it must not be asked twice.
+        const refused = this.#cancelledEscape !== null;
+        const top = this.open.at(-1);
+        const applied = !refused &&
+            !!top?.options.dismissOnEscape?.() &&
+            top.options.onDismiss?.({
+                reason: 'close-watcher',
+                event,
+                // The Back gesture is user input, though the event it fires carries no modality.
+                interaction: 'touch',
+                cancelable: event.cancelable
+            }) !== false;
+        // Keeps the watcher alive for the next request when nothing closed.
+        if (!applied && event.cancelable)
+            event.preventDefault();
+    };
     #onKeyDown = (event) => {
         if (event.key !== 'Escape' || event.defaultPrevented)
             return;
         const top = this.open.at(-1);
         if (!top?.options.dismissOnEscape?.())
             return;
+        if (top.options.onDismiss?.({ reason: 'escape-key', event }) === false) {
+            // Cancelled: the keydown stays untouched for whatever handles Escape next.
+            this.#cancelledEscape = event;
+            setTimeout(() => {
+                if (this.#cancelledEscape === event)
+                    this.#cancelledEscape = null;
+            });
+            return;
+        }
         event.preventDefault();
-        top.options.onDismiss?.('escape');
     };
     #onPointerDown = (event) => {
         const path = event.composedPath();
@@ -136,13 +279,63 @@ export class LayerStack {
                     protectedLayers.push(current);
             }
         }
+        const now = [];
+        const onTap = [];
         for (let index = open.length - 1; index >= 0; index -= 1) {
             const layer = open[index];
-            if (!protectedLayers.includes(layer) && layer.options.dismissOnOutside?.()) {
-                layer.options.onDismiss?.('outside');
+            // A press that began before the layer opened is the one that opened it.
+            if (!protectedLayers.includes(layer) &&
+                layer.openedAt <= event.timeStamp &&
+                layer.options.dismissOnOutside?.()) {
+                // A finger on the page may be starting a scroll: a non-modal layer (the page still
+                // scrolls under it) waits to see a tap. Nothing scrolls under a modal layer.
+                (event.pointerType === 'touch' && !layer.isModal ? onTap : now).push(layer);
             }
             if (layer.isModal)
-                return; // nothing below a modal is reachable, hit or not
+                break; // nothing below a modal is reachable, hit or not
         }
+        for (const layer of now)
+            layer.options.onDismiss?.({ reason: 'outside-press', event });
+        if (onTap.length > 0)
+            this.#awaitTap(event, onTap);
     };
+    /**
+     * Dismisses `layers` when the touch that began with `down` ends as a tap: it lifts without
+     * moving past the slop and without the browser taking it over for scrolling (`pointercancel`).
+     */
+    #awaitTap(down, layers) {
+        this.#pendingTap?.();
+        // Capture phase, like the press itself: a control that stops propagation cannot hide it.
+        // On the document the press landed in, which is not the page's inside an iframe.
+        const capture = { capture: true };
+        const owner = down.currentTarget ?? document;
+        const offs = [
+            on(owner, 'pointermove', (event) => {
+                if (event.pointerId !== down.pointerId)
+                    return;
+                const distance = Math.hypot(event.clientX - down.clientX, event.clientY - down.clientY);
+                if (distance > TAP_SLOP)
+                    stop();
+            }, capture),
+            on(owner, 'pointercancel', (event) => {
+                if (event.pointerId === down.pointerId)
+                    stop();
+            }, capture),
+            on(owner, 'pointerup', (event) => {
+                if (event.pointerId !== down.pointerId)
+                    return;
+                stop();
+                for (const layer of layers) {
+                    if (layer.isOpen)
+                        layer.options.onDismiss?.({ reason: 'outside-press', event });
+                }
+            }, capture)
+        ];
+        const stop = () => {
+            offs.splice(0).forEach((off) => off());
+            if (this.#pendingTap === stop)
+                this.#pendingTap = null;
+        };
+        this.#pendingTap = stop;
+    }
 }

package/dist/utils/listFilter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Locale-aware text matching for filterable lists (Combobox, TagsInput, Command, PhoneInput,
+ * menus). Comparisons go through `Intl.Collator` with `usage: 'search'` and, by default,
+ * `sensitivity: 'base'`, so `eclair` finds `Éclair` and case never matters, while each language
+ * keeps its own rules (in Turkish, `i` matches `İ` but not `I`).
+ */
+export type ListFilterOptions = Omit<Intl.CollatorOptions, 'usage'> & {
+    /** Locale of the compared text. Components pass the active I18n locale; defaults to the runtime's. */
+    locale?: Intl.LocalesArgument;
+};
+/** How an item's text has to relate to the query. */
+export type ListFilterMatch = 'contains' | 'startsWith';
+export type ListFilterQueryOptions<T> = {
+    /**
+     * The text of an item: one string, or several (label, keywords…) of which any may match.
+     * Defaults to `String(item)`.
+     */
+    text?: (item: T) => string | readonly (string | null | undefined)[];
+    /** `contains` (default), `startsWith`, or a predicate built on this filter. */
+    match?: ListFilterMatch | ((text: string, query: string) => boolean);
+    /**
+     * Stop after this many results. Matching stops as soon as the limit is reached, so the rest
+     * of a long list is never compared. For grouped lists, pass what is left of the limit to each
+     * group.
+     */
+    limit?: number;
+};
+export type ListFilter = {
+    /** The locale the collator resolved to. */
+    readonly locale: string;
+    /** Whether `query` appears anywhere in `text`. An empty query matches everything. */
+    contains: (text: string, query: string) => boolean;
+    /** Whether `text` starts with `query`. An empty query matches everything. */
+    startsWith: (text: string, query: string) => boolean;
+    /** Whether `text` and `query` are the same text under this filter's sensitivity. */
+    equals: (text: string, query: string) => boolean;
+    /** The items whose text matches `query`, in order, up to `limit`. */
+    filter: <T>(items: Iterable<T>, query: string, options?: ListFilterQueryOptions<T>) => T[];
+};
+/**
+ * A cached filter for `options`. Building an `Intl.Collator` is expensive, so filters are shared
+ * per locale and collator options.
+ */
+export declare const createListFilter: (options?: ListFilterOptions) => ListFilter;