entasis 0.11.0 → 0.13.0

package/dist/utils/openLifecycle.svelte.js

@@ -0,0 +1,134 @@
+// The open/close lifecycle every overlay shares: `closed → entering → open → exiting → closed`,
+// with `onAfterOpen` and `onAfterClose` firing exactly once per open and per close.
+//
+// Svelte plays no intro for an element whose `{#if}` block is already true when it is created
+// (`defaultOpen`, hydration, a component mounted open), so `introend` alone would leave such an
+// overlay "entering" forever. The lifecycle notes when the element's transition function is
+// called (Svelte calls it synchronously, in the flush that starts the transition) and completes
+// the phase itself once that flush has settled without one.
+import { tick, untrack } from 'svelte';
+/**
+ * Tracks one surface's lifecycle. Call during component initialisation (it installs effects).
+ * A close during the opening transition cancels the pending `onAfterOpen`, and a reopen during the
+ * closing one cancels the pending `onAfterClose`; each phase that completes reports once.
+ */
+export function useOpenLifecycle(options) {
+    let status = $state('closed');
+    // The direction of the phase in progress: `true` opening or open, `false` closing or closed,
+    // `null` before the first run. Plain fields: read by event handlers, never rendered.
+    let direction = null;
+    let phase = 0;
+    let transitionStarted = false;
+    /**
+     * A transition Svelte started before this flush reached `begin` (effect order is not
+     * guaranteed): the phase it belongs to has not been recorded yet.
+     */
+    let earlyTransition = null;
+    /** Such an early transition that has already ended (a zero duration ends synchronously). */
+    let earlyEnd = null;
+    const early = (kind, playing) => {
+        if (kind === 'transition')
+            earlyTransition = playing;
+        else
+            earlyEnd = playing;
+        queueMicrotask(() => {
+            earlyTransition = earlyEnd = null;
+        });
+    };
+    let completed = true;
+    let disposed = false;
+    const complete = (id) => {
+        if (disposed || id !== phase || completed)
+            return;
+        completed = true;
+        if (direction) {
+            status = 'open';
+            options.onAfterOpen?.();
+        }
+        else {
+            status = 'closed';
+            options.onAfterClose?.();
+        }
+    };
+    // Runs once the flush that changed the state has settled: by then Svelte has called the
+    // transition function of any element that animates this phase.
+    const completeWithoutTransition = async (id) => {
+        await tick();
+        if (id !== phase || transitionStarted || completed || options.external?.())
+            return;
+        const element = options.animated?.();
+        const animations = element?.getAnimations?.({ subtree: true }) ?? [];
+        if (animations.length > 0) {
+            await Promise.allSettled(animations.map((animation) => animation.finished));
+        }
+        complete(id);
+    };
+    const begin = (open) => {
+        if (open === direction)
+            return;
+        const initial = direction === null;
+        direction = open;
+        const id = ++phase;
+        const playing = open ? 'in' : 'out';
+        // A transition that already ended leaves nothing to wait for: the fallback completes.
+        transitionStarted = earlyTransition === playing && earlyEnd !== playing;
+        earlyTransition = earlyEnd = null;
+        completed = false;
+        // Closed at creation: there is no close to report.
+        if (initial && !open) {
+            completed = true;
+            return;
+        }
+        status = open ? 'entering' : 'exiting';
+        void completeWithoutTransition(id);
+    };
+    // `.pre`, so `status` is normally current before the template renders the change. Effect
+    // order is not guaranteed, though: a transition that starts first is caught by `early`.
+    $effect.pre(() => {
+        const open = options.isOpen();
+        untrack(() => begin(open));
+    });
+    $effect(() => () => {
+        disposed = true;
+    });
+    return {
+        get status() {
+            return status;
+        },
+        transition: (fn) => ((...args) => {
+            // Svelte passes `{ direction }` third: 'in' for an intro, 'out' for an outro.
+            const playing = args[2]?.direction;
+            if (playing === 'both' || (playing === 'in') === direction) {
+                transitionStarted = true;
+            }
+            else if (playing === 'in' || playing === 'out') {
+                // The state change that starts this phase has not reached `begin` yet; it does
+                // within the same flush, before any microtask.
+                early('transition', playing);
+            }
+            const config = fn(...args);
+            // Svelte keeps these options for as long as the element lives once an exit has started
+            // (a reopen reverses it) and does not call this function for the next exit. Handed back
+            // as a deferred config, they are asked for on every run instead, in a microtask the
+            // flush that starts it queues: before `completeWithoutTransition` reads
+            // `transitionStarted` after its tick.
+            return (options) => {
+                if (!completed && (options.direction === 'in') === direction)
+                    transitionStarted = true;
+                return typeof config === 'function' ? config(options) : config;
+            };
+        }),
+        introEnd: () => {
+            if (direction)
+                complete(phase);
+            else if (earlyTransition === 'in')
+                early('end', 'in');
+        },
+        outroEnd: () => {
+            if (direction === false)
+                complete(phase);
+            else if (earlyTransition === 'out')
+                early('end', 'out');
+        }
+    };
+}

package/dist/utils/pointerDrag.d.ts

@@ -34,6 +34,16 @@ export type PointerDragOptions<Node extends HTMLElement = HTMLElement> = {
      *  promoted simply ends on pointerup, without `onStart`/`onEnd`. Takes the place of
      *  `activation`, which promotes on distance and a touch hold instead. */
     shouldActivate?: (payload: PointerDragPayload<Node>) => boolean;
+    /** Direction attribution for a gesture along one axis, decided before any activation. Once
+     *  the press has travelled `axisSlopPx` either way, a press that went further across the axis
+     *  than along it is spent: it never activates (neither `shouldActivate` nor `activation` is
+     *  consulted again) and ends on pointerup through `onCancel`, so a mostly sideways drag stays
+     *  with whatever scrolls or swipes across. Until then, movement activates nothing (a touch
+     *  hold under `activation` still can). Return `undefined` to skip attribution. Ignored by
+     *  sessions that activate on press. */
+    axis?: () => 'x' | 'y' | undefined;
+    /** Travel in px after which `axis` attributes the press. Default 6. */
+    axisSlopPx?: number;
     /** While the drag is active, `touchmove` is prevented so the page cannot pan under it.
      *  Default true; set false when the consumer governs touch panning itself (`touch-action`)
      *  and native scrolling around the gesture must keep working. */

package/dist/utils/pointerDrag.js

@@ -1,6 +1,7 @@
 import { on } from 'svelte/events';
 import { untrack } from 'svelte';
 const DEFAULT_MOVE_TOLERANCE = 2;
+const DEFAULT_AXIS_SLOP = 6;
 export const createPointerDrag = (options) => {
     let session = null;
     let moveFrame = null;
@@ -49,7 +50,9 @@ export const createPointerDrag = (options) => {
         };
     };
     const releasePointer = (currentSession) => {
-        if (currentSession.node.hasPointerCapture(currentSession.pointerId)) {
+        // Optional: an `on-activate` session that never activated took no capture, and DOM
+        // implementations without pointer capture (jsdom) must still end the session.
+        if (currentSession.node.hasPointerCapture?.(currentSession.pointerId)) {
             currentSession.node.releasePointerCapture(currentSession.pointerId);
         }
     };
@@ -138,7 +141,8 @@ export const createPointerDrag = (options) => {
                 isActive: false,
                 usesActivation: false,
                 activationTimer: null,
-                detachWindowEnd: null
+                detachWindowEnd: null,
+                attribution: 'pending'
             };
             const deferCapture = options.capture === 'on-activate';
             if (!deferCapture)
@@ -175,11 +179,42 @@ export const createPointerDrag = (options) => {
                 dispatchMove(getPayload(nextSession.lastEvent, nextSession));
             }, activation.touchDelayMs);
         };
+        /** Whether a candidate may be promoted on this move, after `axis` attribution. */
+        const isAttributed = (payload, currentSession) => {
+            if (currentSession.attribution !== 'pending') {
+                return currentSession.attribution === 'attributed';
+            }
+            const axis = options.axis?.();
+            if (!axis)
+                return true;
+            const along = Math.abs(axis === 'x' ? payload.deltaX : payload.deltaY);
+            const across = Math.abs(axis === 'x' ? payload.deltaY : payload.deltaX);
+            if (Math.max(along, across) < (options.axisSlopPx ?? DEFAULT_AXIS_SLOP))
+                return false;
+            if (across > along) {
+                // Spent: the session stays until the pointer lifts, so a second pointer cannot
+                // take over mid-press, but it no longer waits on a touch hold either.
+                currentSession.attribution = 'spent';
+                clearActivationTimer(currentSession);
+                return false;
+            }
+            currentSession.attribution = 'attributed';
+            return true;
+        };
         const move = (event) => {
             if (!session || event.pointerId !== session.pointerId)
                 return;
+            // The primary button came up where no pointerup reached us (outside the window, over
+            // an iframe, under devtools): a mouse moving without it held is no longer dragging.
+            // It ends where the button was last known to be held, not where this move landed.
+            if (event.pointerType === 'mouse' && (event.buttons & 1) === 0) {
+                end(session.lastEvent);
+                return;
+            }
             const currentSession = session;
             const payload = getPayload(event, currentSession);
+            if (!currentSession.isActive && !isAttributed(payload, currentSession))
+                return;
             // A candidate the consumer promotes itself: nothing moves until it says so.
             if (options.shouldActivate && !currentSession.isActive) {
                 if (!options.shouldActivate(payload))

package/dist/utils/pragmaticDragAndDrop.d.ts

@@ -5,7 +5,8 @@ import type * as PointerOutsideOfPreview from '@atlaskit/pragmatic-drag-and-drop
 import type * as SetCustomNativeDragPreview from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
 import type * as Reorder from '@atlaskit/pragmatic-drag-and-drop/reorder';
 declare const elementAdapter: typeof ElementAdapter;
-export declare const autoScrollForElements: (args: import("@atlaskit/pragmatic-drag-and-drop-auto-scroll/dist/types/internal-types.js").ElementAutoScrollArgs<import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").ElementDragType>) => import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").CleanupFn, autoScrollWindowForElements: (args?: import("@atlaskit/pragmatic-drag-and-drop-auto-scroll/dist/types/internal-types.js").WindowAutoScrollArgs<import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").ElementDragType>) => import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").CleanupFn;
+export declare const autoScrollForElements: (args: import("@atlaskit/pragmatic-drag-and-drop-auto-scroll/dist/types/internal-types.js").ElementAutoScrollArgs<import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").ElementDragType>) => import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").CleanupFn;
+export declare const autoScrollWindowForElements: (args?: import("@atlaskit/pragmatic-drag-and-drop-auto-scroll/dist/types/internal-types.js").WindowAutoScrollArgs<import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").ElementDragType>) => import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").CleanupFn;
 export declare const combine: typeof Combine.combine;
 export declare const draggable: typeof elementAdapter.draggable;
 export declare const dropTargetForElements: (args: import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").DropTargetArgs<import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").ElementDragType>) => import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").CleanupFn, monitorForElements: (args: import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").MonitorArgs<import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").ElementDragType>) => import("@atlaskit/pragmatic-drag-and-drop/dist/types/internal-types.js").CleanupFn;

package/dist/utils/pragmaticDragAndDrop.js

@@ -1,8 +1,11 @@
 // The installed Atlaskit packages publish typed directory entry points that Node ESM cannot
 // load after SSR externalization. Their explicit CommonJS files are runtime-safe but omit
 // adjacent declarations, so this boundary reconnects each verified runtime to its public type.
+// The auto-scroll element entry point binds itself to `@atlaskit/pragmatic-drag-and-drop/adapter/element-adapter`,
+// which bundlers resolve to the package's ESM copy while the CommonJS adapter below is a second
+// copy. Its monitor would then never see a drag, so the scroller is built here on our own adapter.
 // @ts-expect-error See compatibility boundary above.
-import * as autoScrollRuntime from '@atlaskit/pragmatic-drag-and-drop-auto-scroll/dist/cjs/entry-point/element.js';
+import * as autoScrollApiRuntime from '@atlaskit/pragmatic-drag-and-drop-auto-scroll/dist/cjs/over-element/make-api.js';
 // @ts-expect-error See compatibility boundary above.
 import * as combineRuntime from '@atlaskit/pragmatic-drag-and-drop/dist/cjs/entry-point/combine.js';
 // @ts-expect-error See compatibility boundary above.
@@ -17,7 +20,6 @@ import * as setCustomNativeDragPreviewRuntime from '@atlaskit/pragmatic-drag-and
 import * as preventUnhandledRuntime from '@atlaskit/pragmatic-drag-and-drop/dist/cjs/entry-point/prevent-unhandled.js';
 // @ts-expect-error See compatibility boundary above.
 import * as reorderRuntime from '@atlaskit/pragmatic-drag-and-drop/dist/cjs/entry-point/reorder.js';
-const autoScroll = autoScrollRuntime;
 const combineEntry = combineRuntime;
 const elementAdapter = elementAdapterRuntime;
 const disableNativeDragPreviewEntry = disableNativeDragPreviewRuntime;
@@ -26,7 +28,10 @@ const setCustomNativeDragPreviewEntry = setCustomNativeDragPreviewRuntime;
 const preventUnhandledEntry = preventUnhandledRuntime;
 const reorderEntry = reorderRuntime;
 const { preventUnhandled } = preventUnhandledEntry;
-export const { autoScrollForElements, autoScrollWindowForElements } = autoScroll;
+const { makeApi } = autoScrollApiRuntime;
+const autoScroll = makeApi({ monitor: elementAdapter.monitorForElements });
+export const autoScrollForElements = autoScroll.autoScroll;
+export const autoScrollWindowForElements = autoScroll.autoScrollWindow;
 export const { combine } = combineEntry;
 export const draggable = (args) => elementAdapter.draggable({
     ...args,

package/dist/utils/range.d.ts

@@ -0,0 +1,62 @@
+/** Clamps `value` into `[min, max]`. `NaN` reads as `min`; a range with `max < min` collapses to `min`. */
+export declare const clampRange: (value: number, min?: number, max?: number) => number;
+/**
+ * Where `value` sits between `min` and `max`, as a percentage clamped to 0–100. An empty range
+ * (`max <= min`) reads 100 at or past `max` and 0 below it; `NaN` reads 0.
+ */
+export declare const toPercent: (value: number, min?: number, max?: number) => number;
+/** `indeterminate` without a finite value, `complete` at `max`, `progressing` otherwise. */
+export type RangeStatus = 'indeterminate' | 'progressing' | 'complete';
+export type RangeValueOptions = {
+    /** The raw value. `null`, `undefined` and non-finite values are indeterminate. */
+    value: number | null | undefined;
+    /** @default 0 */
+    min?: number;
+    /** @default 100 */
+    max?: number;
+    /**
+     * Formats the clamped value itself (`{ style: 'unit', unit: 'megabyte' }`). Without it, the
+     * text is the value's percentage of the range (`45 %` in French).
+     */
+    format?: Intl.NumberFormatOptions;
+    /** Locale of the text; components pass the active I18n locale. */
+    locale?: Intl.LocalesArgument;
+};
+export type ResolvedRangeValue = {
+    /** The value clamped into the range, or `null` when indeterminate. */
+    value: number | null;
+    /** The clamped value as a 0–100 percentage of the range, or `null` when indeterminate. */
+    percent: number | null;
+    /** The display text, or `''` when indeterminate. */
+    formatted: string;
+    status: RangeStatus;
+};
+/** Clamps, measures and formats a range value in one pass. */
+export declare const resolveRangeValue: ({ value, min, max, format, locale }: RangeValueOptions) => ResolvedRangeValue;
+/**
+ * The display text of a range value: `format` applied to the clamped value, or the percentage of
+ * the range in `locale` by default. `''` when indeterminate.
+ */
+export declare const formatRangeValue: (options: RangeValueOptions) => string;
+export type RangeAriaValueTextOptions = RangeValueOptions & {
+    /** Custom text from the formatted value and the raw value; wins over the defaults. */
+    getAriaValueText?: (formattedValue: string, value: number | null) => string;
+    /** Text for an indeterminate value (from the I18n catalog); omitted when not given. */
+    indeterminateText?: string;
+};
+/**
+ * `aria-valuetext` for a range value: `getAriaValueText(formatted, raw)` when given, the formatted
+ * text otherwise, and `indeterminateText` while indeterminate.
+ */
+export declare const rangeAriaValueText: (options: RangeAriaValueTextOptions) => string | undefined;
+export type RangeAriaAttributes = {
+    'aria-valuemin': number;
+    'aria-valuemax': number;
+    'aria-valuenow': number | undefined;
+    'aria-valuetext': string | undefined;
+};
+/**
+ * ARIA value attributes for a `meter`, `progressbar` or `slider`: the bounds, the clamped value
+ * (omitted while indeterminate) and the value text.
+ */
+export declare const rangeAriaAttributes: (options: RangeAriaValueTextOptions) => RangeAriaAttributes;

package/dist/utils/range.js

@@ -0,0 +1,70 @@
+/**
+ * Value helpers for bounded displays (Meter, Progress, ProgressCircle, Slider, the Toast progress
+ * bar): clamping, percentages, locale formatting and the ARIA value text, kept in one place so the
+ * fill, the visible text and `aria-valuenow` always describe the same number.
+ */
+import { formatNumber } from './number.js';
+/** Clamps `value` into `[min, max]`. `NaN` reads as `min`; a range with `max < min` collapses to `min`. */
+export const clampRange = (value, min = 0, max = 100) => {
+    if (Number.isNaN(value))
+        return min;
+    return Math.min(Math.max(value, min), Math.max(min, max));
+};
+/**
+ * Where `value` sits between `min` and `max`, as a percentage clamped to 0–100. An empty range
+ * (`max <= min`) reads 100 at or past `max` and 0 below it; `NaN` reads 0.
+ */
+export const toPercent = (value, min = 0, max = 100) => {
+    if (Number.isNaN(value))
+        return 0;
+    if (max <= min)
+        return value >= max ? 100 : 0;
+    return Math.min(Math.max(((value - min) * 100) / (max - min), 0), 100);
+};
+/** Clamps, measures and formats a range value in one pass. */
+export const resolveRangeValue = ({ value, min = 0, max = 100, format, locale }) => {
+    if (value == null || !Number.isFinite(value)) {
+        return { value: null, percent: null, formatted: '', status: 'indeterminate' };
+    }
+    const clamped = clampRange(value, min, max);
+    const percent = toPercent(clamped, min, max);
+    return {
+        value: clamped,
+        percent,
+        formatted: format
+            ? formatNumber(clamped, locale, format)
+            : formatNumber(percent / 100, locale, { style: 'percent' }),
+        status: clamped >= Math.max(min, max) ? 'complete' : 'progressing'
+    };
+};
+/**
+ * The display text of a range value: `format` applied to the clamped value, or the percentage of
+ * the range in `locale` by default. `''` when indeterminate.
+ */
+export const formatRangeValue = (options) => resolveRangeValue(options).formatted;
+const ariaValueText = (resolved, options) => {
+    if (options.getAriaValueText) {
+        const raw = options.value == null || !Number.isFinite(options.value) ? null : options.value;
+        return options.getAriaValueText(resolved.formatted, raw);
+    }
+    return resolved.status === 'indeterminate' ? options.indeterminateText : resolved.formatted;
+};
+/**
+ * `aria-valuetext` for a range value: `getAriaValueText(formatted, raw)` when given, the formatted
+ * text otherwise, and `indeterminateText` while indeterminate.
+ */
+export const rangeAriaValueText = (options) => ariaValueText(resolveRangeValue(options), options);
+/**
+ * ARIA value attributes for a `meter`, `progressbar` or `slider`: the bounds, the clamped value
+ * (omitted while indeterminate) and the value text.
+ */
+export const rangeAriaAttributes = (options) => {
+    const { min = 0, max = 100 } = options;
+    const resolved = resolveRangeValue(options);
+    return {
+        'aria-valuemin': min,
+        'aria-valuemax': max,
+        'aria-valuenow': resolved.value ?? undefined,
+        'aria-valuetext': ariaValueText(resolved, options)
+    };
+};

package/dist/utils/requestNativeSubmit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The form an element submits with: its form owner when it is a form control (which honours a
+ * `form` attribute, and is null when that attribute names no form), else the closest ancestor form.
+ */
+export declare const getNativeForm: (element: Element | null | undefined) => HTMLFormElement | null;
+/**
+ * The button a browser clicks for implicit submission: the first submit button of the form in tree
+ * order, counting buttons placed outside it with a `form` attribute. It may be disabled.
+ */
+export declare const getDefaultSubmitter: (form: HTMLFormElement | null) => HTMLButtonElement | HTMLInputElement | null;
+/**
+ * Submits the form that owns `element` as Enter does on a native checkbox: by clicking the form's
+ * default button, so its click handlers, `formaction`/`formmethod` and `SubmitEvent.submitter` all
+ * take part and constraint validation runs. Without an enabled default button nothing happens,
+ * like a native checkbox. Returns whether a submission was requested.
+ */
+export declare const requestNativeSubmit: (element: Element | null | undefined) => boolean;

package/dist/utils/requestNativeSubmit.js

@@ -0,0 +1,47 @@
+// Implicit submission for custom controls. A native checkbox or radio submits its form on Enter
+// through the form's default button, the way a text field does, and does nothing when the form has
+// none (or when that button is disabled). Controls built on buttons and divs mirror that here.
+const isFormAssociated = (element) => 'form' in element && element.localName !== 'form';
+/**
+ * The form an element submits with: its form owner when it is a form control (which honours a
+ * `form` attribute, and is null when that attribute names no form), else the closest ancestor form.
+ */
+export const getNativeForm = (element) => {
+    if (!element)
+        return null;
+    if (element.localName === 'form')
+        return element;
+    if (isFormAssociated(element) && (element.form || element.hasAttribute('form'))) {
+        return element.form;
+    }
+    return element.closest('form');
+};
+/**
+ * The button a browser clicks for implicit submission: the first submit button of the form in tree
+ * order, counting buttons placed outside it with a `form` attribute. It may be disabled.
+ */
+export const getDefaultSubmitter = (form) => {
+    if (!form)
+        return null;
+    for (const element of Array.from(form.elements)) {
+        if ((element.localName === 'button' || element.localName === 'input') &&
+            element.type === 'submit') {
+            return element;
+        }
+    }
+    return null;
+};
+/**
+ * Submits the form that owns `element` as Enter does on a native checkbox: by clicking the form's
+ * default button, so its click handlers, `formaction`/`formmethod` and `SubmitEvent.submitter` all
+ * take part and constraint validation runs. Without an enabled default button nothing happens,
+ * like a native checkbox. Returns whether a submission was requested.
+ */
+export const requestNativeSubmit = (element) => {
+    const submitter = getDefaultSubmitter(getNativeForm(element));
+    // `:disabled` also covers a button inside a disabled fieldset, which `.disabled` misses.
+    if (!submitter || submitter.matches(':disabled'))
+        return false;
+    submitter.click();
+    return true;
+};

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

@@ -1,10 +1,19 @@
 type SafeAreaDebugOption = boolean | (() => boolean);
+/** Default grace before a pointer outside the safe area closes it; see `closeDelay`. */
+export declare const SAFE_AREA_CLOSE_DELAY = 120;
 export declare const useSafeArea: (opts: {
     isActive: () => boolean;
-    callback?: () => void;
+    /** Runs when the pointer has left the safe area, with the pointer event that left it. */
+    callback?: (event?: PointerEvent) => void;
     offset?: number;
     debug?: SafeAreaDebugOption;
     trackPosition?: boolean;
+    /**
+     * Milliseconds the pointer may stay outside the safe area before `callback` runs. Read each
+     * time the pointer leaves, so a function follows a changing value. Default
+     * `SAFE_AREA_CLOSE_DELAY`.
+     */
+    closeDelay?: number | (() => number | undefined);
 }) => {
     reference: (ref: HTMLElement) => () => void;
     anchorReference: (ref: HTMLElement) => () => void;

package/dist/utils/safeArea.svelte.js

@@ -100,6 +100,8 @@ function drawAreaInDOM(points, style) {
     document.body.appendChild(svg);
     return svg;
 }
+/** Default grace before a pointer outside the safe area closes it; see `closeDelay`. */
+export const SAFE_AREA_CLOSE_DELAY = 120;
 export const useSafeArea = (opts) => {
     const refs = new SvelteMap();
     const observerOffs = new SvelteMap();
@@ -111,10 +113,11 @@ export const useSafeArea = (opts) => {
     let lastSafeRole = null;
     let isListening = false;
     let closeTimer = null;
-    // ponytail: a short grace delay is a sampling safety net — pointermove fires
-    // on discrete points, so a fast flick can skip past the cone in one event; the
-    // delay lets it re-enter a safe region before the close actually fires.
-    const CLOSE_DELAY = 120;
+    // A short grace delay is also a sampling safety net: pointermove fires on discrete points, so
+    // a fast flick can skip past the cone in one event, and the delay lets it re-enter a safe
+    // region before the close actually fires.
+    const readCloseDelay = () => Math.max(0, (typeof opts.closeDelay === 'function' ? opts.closeDelay() : opts.closeDelay) ??
+        SAFE_AREA_CLOSE_DELAY);
     const { offset = 10 } = opts;
     const getDebug = () => (typeof opts.debug === 'function' ? opts.debug() : !!opts.debug);
     // The anchor (trigger) is measured tight — expanding it would push the cone's
@@ -197,14 +200,14 @@ export const useSafeArea = (opts) => {
         clearTimeout(closeTimer);
         closeTimer = null;
     };
-    const scheduleClose = () => {
+    const scheduleClose = (event) => {
         if (closeTimer !== null)
             return;
         closeTimer = setTimeout(() => {
             closeTimer = null;
-            opts.callback?.();
+            opts.callback?.(event);
             destroy();
-        }, CLOSE_DELAY);
+        }, readCloseDelay());
     };
     const onPointerMove = (e) => {
         if (rects.size === 0)
@@ -228,7 +231,7 @@ export const useSafeArea = (opts) => {
             cancelClose();
             return;
         }
-        scheduleClose();
+        scheduleClose(e);
     };
     const removeDebug = () => {
         rectDebugs.forEach((debug) => debug.remove());
@@ -319,9 +322,14 @@ export const useSafeArea = (opts) => {
         destroy();
     });
     const registerReference = (ref, role) => {
-        refs.set(ref, role);
-        if (isListening)
-            addReference(ref);
+        // Runs inside the caller's attachment effect. While the area is listening,
+        // `addReference` reads and writes `observerOffs`; tracked, that would re-run the
+        // attachment, whose teardown deletes the entry again, without end.
+        untrack(() => {
+            refs.set(ref, role);
+            if (isListening)
+                addReference(ref);
+        });
         return () => {
             refs.delete(ref);
             observerOffs.get(ref)?.();