entasis 0.11.0 → 0.12.0

package/dist/utils/stateAttributes.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The shared state attributes every component exposes as styling hooks. They are presence
+ * attributes: `''` while the state holds and omitted otherwise, so `[data-open]` selectors and
+ * Tailwind's `data-open:` variant work without values. `data-side` and `data-align` carry a value.
+ *
+ * Spread the returned objects on rendered elements (`{...openStateAttributes(open)}`); use
+ * `applyStateAttributes` for elements a component manages imperatively. Components keep their
+ * existing `data-state` values alongside these for compatibility.
+ */
+import type { Placement } from '@floating-ui/dom';
+/** A presence attribute value: `''` sets the attribute, `undefined` omits it. */
+export type Presence = '' | undefined;
+/** `''` when `on` is truthy, `undefined` otherwise. */
+export declare const presence: (on: unknown) => Presence;
+/** Lifecycle of anything that opens and closes with a transition. */
+export type OpenTransitionStatus = 'closed' | 'entering' | 'open' | 'exiting';
+export type OpenStateAttributes = {
+    'data-open': Presence;
+    'data-closed': Presence;
+};
+/** `data-open` while open, `data-closed` otherwise (including while the exit transition plays). */
+export declare const openStateAttributes: (open: boolean) => OpenStateAttributes;
+export type TransitionStatusAttributes = {
+    'data-entering': Presence;
+    'data-exiting': Presence;
+};
+/** `data-entering` while the enter transition plays, `data-exiting` while the exit one plays. */
+export declare const transitionStatusAttributes: (status: OpenTransitionStatus | undefined) => TransitionStatusAttributes;
+/**
+ * The side of the anchor a popup sits on. A popup that asked for a logical side reports
+ * `inline-start` or `inline-end` while it stays on the inline axis.
+ */
+export type PopupSide = 'top' | 'right' | 'bottom' | 'left' | 'inline-start' | 'inline-end';
+/** A popup's side, or `none` when it is not placed beside its anchor (Select over its trigger). */
+export type PopupPlacementSide = PopupSide | 'none';
+/** How a popup lines up with its anchor along that side. */
+export type PopupAlign = 'start' | 'center' | 'end';
+/** Splits a floating-ui placement (`bottom-start`) into its side and alignment. */
+export declare const parsePlacement: (placement: Placement) => {
+    side: PopupSide;
+    align: PopupAlign;
+};
+export type PlacementAttributes = {
+    'data-side': PopupPlacementSide | undefined;
+    'data-align': PopupAlign | undefined;
+    'data-anchor-hidden': Presence;
+};
+/**
+ * `data-side` and `data-align` from the resolved placement (not the requested one, which a flip
+ * may have changed), and `data-anchor-hidden` while the anchor is scrolled out of view. A popup
+ * on side `none` has no alignment.
+ */
+export declare const placementAttributes: (placement: Placement | {
+    side: PopupPlacementSide;
+    align?: PopupAlign;
+} | undefined, { anchorHidden }?: {
+    anchorHidden?: boolean;
+}) => PlacementAttributes;
+export type PopupTriggerAttributes = {
+    'data-popup-open': Presence;
+};
+/** `data-popup-open` on a trigger while the popup it controls is open. */
+export declare const popupTriggerAttributes: (open: boolean) => PopupTriggerAttributes;
+export type PopupSideAttributes = {
+    'data-popup-side': PopupPlacementSide | undefined;
+};
+/** `data-popup-side` on a trigger: the side its placed popup sits on, omitted while unplaced. */
+export declare const popupSideAttributes: (side: PopupPlacementSide | null | undefined) => PopupSideAttributes;
+export type ItemState = {
+    /** The keyboard or pointer highlight is on the item. */
+    highlighted?: boolean;
+    /** The item cannot be chosen. */
+    disabled?: boolean;
+    /** The item is chosen (selected, checked or current). */
+    selected?: boolean;
+};
+export type ItemStateAttributes = {
+    'data-highlighted': Presence;
+    'data-disabled': Presence;
+    'data-selected': Presence;
+};
+/** `data-highlighted`, `data-disabled` and `data-selected` for an option, menu item or row. */
+export declare const itemStateAttributes: ({ highlighted, disabled, selected }: ItemState) => ItemStateAttributes;
+/**
+ * Writes attributes onto an element Svelte doesn't render: a string sets the attribute, `undefined`
+ * or `null` removes it.
+ */
+export declare const applyStateAttributes: (element: Element, attributes: Readonly<Record<string, string | null | undefined>>) => void;
+/**
+ * What each shared state attribute means. Components build their documented styling-hook maps
+ * from these entries so the wording stays the same everywhere.
+ */
+export declare const stateDataAttributes: {
+    readonly 'data-open': "Present while open.";
+    readonly 'data-closed': "Present while closed, including during the exit transition.";
+    readonly 'data-entering': "Present while the enter transition plays.";
+    readonly 'data-exiting': "Present while the exit transition plays.";
+    readonly 'data-side': "The side of the anchor the popup sits on: top, right, bottom or left; inline-start or inline-end when a logical side was requested; none when the popup is not placed beside its anchor.";
+    readonly 'data-align': "The alignment with the anchor: start, center or end.";
+    readonly 'data-anchor-hidden': "Present while the anchor is scrolled out of view.";
+    readonly 'data-popup-open': "Present on a trigger while its popup is open.";
+    readonly 'data-popup-side': "On a trigger, the side its placed popup sits on (the values of data-side).";
+    readonly 'data-highlighted': "Present on the item the keyboard or pointer highlights.";
+    readonly 'data-disabled': "Present while disabled.";
+    readonly 'data-selected': "Present while selected or checked.";
+};
+/** The name of a shared state attribute. */
+export type StateDataAttribute = keyof typeof stateDataAttributes;

package/dist/utils/stateAttributes.js

@@ -0,0 +1,78 @@
+/** `''` when `on` is truthy, `undefined` otherwise. */
+export const presence = (on) => (on ? '' : undefined);
+/** `data-open` while open, `data-closed` otherwise (including while the exit transition plays). */
+export const openStateAttributes = (open) => ({
+    'data-open': presence(open),
+    'data-closed': presence(!open)
+});
+/** `data-entering` while the enter transition plays, `data-exiting` while the exit one plays. */
+export const transitionStatusAttributes = (status) => ({
+    'data-entering': presence(status === 'entering'),
+    'data-exiting': presence(status === 'exiting')
+});
+/** Splits a floating-ui placement (`bottom-start`) into its side and alignment. */
+export const parsePlacement = (placement) => {
+    const [side, align] = placement.split('-');
+    return { side, align: align ?? 'center' };
+};
+/**
+ * `data-side` and `data-align` from the resolved placement (not the requested one, which a flip
+ * may have changed), and `data-anchor-hidden` while the anchor is scrolled out of view. A popup
+ * on side `none` has no alignment.
+ */
+export const placementAttributes = (placement, { anchorHidden = false } = {}) => {
+    const resolved = placement === undefined
+        ? undefined
+        : typeof placement === 'string'
+            ? parsePlacement(placement)
+            : { side: placement.side, align: placement.align ?? 'center' };
+    return {
+        'data-side': resolved?.side,
+        'data-align': resolved?.side === 'none' ? undefined : resolved?.align,
+        'data-anchor-hidden': presence(anchorHidden)
+    };
+};
+/** `data-popup-open` on a trigger while the popup it controls is open. */
+export const popupTriggerAttributes = (open) => ({
+    'data-popup-open': presence(open)
+});
+/** `data-popup-side` on a trigger: the side its placed popup sits on, omitted while unplaced. */
+export const popupSideAttributes = (side) => ({
+    'data-popup-side': side ?? undefined
+});
+/** `data-highlighted`, `data-disabled` and `data-selected` for an option, menu item or row. */
+export const itemStateAttributes = ({ highlighted, disabled, selected }) => ({
+    'data-highlighted': presence(highlighted),
+    'data-disabled': presence(disabled),
+    'data-selected': presence(selected)
+});
+/**
+ * Writes attributes onto an element Svelte doesn't render: a string sets the attribute, `undefined`
+ * or `null` removes it.
+ */
+export const applyStateAttributes = (element, attributes) => {
+    for (const [name, value] of Object.entries(attributes)) {
+        if (value == null)
+            element.removeAttribute(name);
+        else if (element.getAttribute(name) !== value)
+            element.setAttribute(name, value);
+    }
+};
+/**
+ * What each shared state attribute means. Components build their documented styling-hook maps
+ * from these entries so the wording stays the same everywhere.
+ */
+export const stateDataAttributes = {
+    'data-open': 'Present while open.',
+    'data-closed': 'Present while closed, including during the exit transition.',
+    'data-entering': 'Present while the enter transition plays.',
+    'data-exiting': 'Present while the exit transition plays.',
+    'data-side': 'The side of the anchor the popup sits on: top, right, bottom or left; inline-start or inline-end when a logical side was requested; none when the popup is not placed beside its anchor.',
+    'data-align': 'The alignment with the anchor: start, center or end.',
+    'data-anchor-hidden': 'Present while the anchor is scrolled out of view.',
+    'data-popup-open': 'Present on a trigger while its popup is open.',
+    'data-popup-side': 'On a trigger, the side its placed popup sits on (the values of data-side).',
+    'data-highlighted': 'Present on the item the keyboard or pointer highlights.',
+    'data-disabled': 'Present while disabled.',
+    'data-selected': 'Present while selected or checked.'
+};

package/dist/utils/swipeVelocity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Release speed for swipe gestures (drawer dismissal, Sidebar view swipes, Toast flicks).
+ *
+ * The speed is measured over a time window that ends at the last sample where the pointer was
+ * still moving, rather than from the last pair of samples. That keeps it stable whatever the
+ * input rate (60 Hz and 120 Hz report the same flick) and survives the effectively stationary
+ * move some Android devices emit right before release, which would otherwise read as a stop.
+ * A pointer that rests longer than the window before release has no speed left.
+ */
+/** Width of the measuring window, in ms. */
+export declare const SWIPE_VELOCITY_WINDOW_MS = 80;
+export type VelocityTrackerOptions = {
+    /** Width of the measuring window, in ms. Default `SWIPE_VELOCITY_WINDOW_MS`. */
+    windowMs?: number;
+    /** Shortest interval a speed is divided by, in ms. Default 4. */
+    minIntervalMs?: number;
+};
+export type VelocityTracker = {
+    /** Forgets every sample: call it when a gesture starts. */
+    reset(): void;
+    /**
+     * Records the pointer's position along the gesture axis at `time` (an event's `timeStamp`).
+     * Record the release event too: a release that moved still counts.
+     */
+    add(position: number, time: number): void;
+    /**
+     * The speed along the axis in px/ms (signed: positive toward increasing positions) at `time`,
+     * usually the release event's `timeStamp`. Defaults to the newest sample's time.
+     */
+    velocity(time?: number): number;
+};
+export declare const createVelocityTracker: ({ windowMs, minIntervalMs }?: VelocityTrackerOptions) => VelocityTracker;

package/dist/utils/swipeVelocity.js

@@ -0,0 +1,59 @@
+/**
+ * Release speed for swipe gestures (drawer dismissal, Sidebar view swipes, Toast flicks).
+ *
+ * The speed is measured over a time window that ends at the last sample where the pointer was
+ * still moving, rather than from the last pair of samples. That keeps it stable whatever the
+ * input rate (60 Hz and 120 Hz report the same flick) and survives the effectively stationary
+ * move some Android devices emit right before release, which would otherwise read as a stop.
+ * A pointer that rests longer than the window before release has no speed left.
+ */
+/** Width of the measuring window, in ms. */
+export const SWIPE_VELOCITY_WINDOW_MS = 80;
+/** Shortest interval a speed is divided by, so near-simultaneous samples cannot spike it. */
+const MIN_INTERVAL_MS = 4;
+/** Samples closer than this to the resting position count as stationary. */
+const STATIONARY_PX = 1;
+/** Samples kept: comfortably more than a window's worth at 240 Hz. */
+const MAX_SAMPLES = 64;
+export const createVelocityTracker = ({ windowMs = SWIPE_VELOCITY_WINDOW_MS, minIntervalMs = MIN_INTERVAL_MS } = {}) => {
+    let samples = [];
+    /** Index of the first sample of the stationary tail: where the pointer came to rest. */
+    const restingIndex = () => {
+        const newest = samples[samples.length - 1];
+        let index = samples.length - 1;
+        while (index > 0 && Math.abs(samples[index - 1].position - newest.position) < STATIONARY_PX) {
+            index -= 1;
+        }
+        return index;
+    };
+    return {
+        reset() {
+            samples = [];
+        },
+        add(position, time) {
+            if (!Number.isFinite(position) || !Number.isFinite(time))
+                return;
+            const newest = samples[samples.length - 1];
+            if (newest && time < newest.time)
+                return;
+            samples.push({ position, time });
+            if (samples.length > MAX_SAMPLES)
+                samples = samples.slice(-MAX_SAMPLES);
+        },
+        velocity(time) {
+            if (samples.length < 2)
+                return 0;
+            const end = restingIndex();
+            const last = samples[end];
+            const now = time ?? samples[samples.length - 1].time;
+            // Resting for longer than the window is a hold, not a flick.
+            if (end === 0 || now - last.time > windowMs)
+                return 0;
+            let start = end - 1;
+            while (start > 0 && last.time - samples[start - 1].time <= windowMs)
+                start -= 1;
+            const first = samples[start];
+            return (last.position - first.position) / Math.max(last.time - first.time, minIntervalMs);
+        }
+    };
+};

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

@@ -1,19 +1,82 @@
+export type TimerOptions = {
+    /** Creates the timer held by `pause()`: it counts nothing until `resume()`. @default false */
+    startPaused?: boolean;
+    /**
+     * Reason, or reasons, that hold the timer from the start, such as `'hover'` or `'window'` when
+     * the pointer or an inactive window already pauses its owner. It counts nothing until each one
+     * is released.
+     */
+    heldBy?: string | Iterable<string>;
+};
+/** The reason `pause()` holds and `resume()` releases. */
+export declare const PAUSE_REASON = "pause";
+/**
+ * A countdown driven by requestAnimationFrame, with reactive `elapsed` and `remaining`.
+ *
+ * Several things can stop it at once (hover, keyboard focus, a swipe, an inactive window): each
+ * one calls `hold(reason)` and later `release(reason)`, and the countdown runs only while no
+ * reason holds it. `pause()` and `resume()` hold and release the `'pause'` reason.
+ *
+ * Frames stop while a tab is hidden but `performance.now()` keeps counting, so the owner has to
+ * hold the timer while its window is inactive (see `watchWindowActivity`); otherwise the first
+ * frame after the user comes back sees the whole hidden interval as elapsed.
+ */
 export declare class Timer {
     private rafId;
     private startTime;
     private pausedTime;
     private callback;
-    private isPaused;
+    private holds;
+    private revision;
+    private touch;
+    private stopped;
+    private held;
     delay: number;
     remaining: number;
     elapsed: number;
     elapsedInSeconds: number;
     elapsedInPercent: number;
-    constructor(callback: () => void, delay: number);
+    constructor(callback: () => void, delay: number, { startPaused, heldBy }?: TimerOptions);
+    /** Whether any reason holds the countdown. Reactive. */
+    get paused(): boolean;
+    /** The reasons currently holding the countdown, in the order they were added. Reactive. */
+    get heldBy(): readonly string[];
+    /** Whether `reason` currently holds the countdown. Reactive. */
+    isHeldBy: (reason: string) => boolean;
     start: () => void;
+    /**
+     * Stops the countdown for `reason`, keeping the time already elapsed. Holding with a reason
+     * that already holds it changes nothing.
+     */
+    hold: (reason: string) => void;
+    /**
+     * Drops `reason`. When no other reason holds the timer, the countdown resumes with the time it
+     * had left. Releasing a reason that doesn't hold it changes nothing.
+     */
+    release: (reason: string) => void;
+    /** Holds the countdown with the `'pause'` reason. */
     pause: () => void;
+    /** Releases the `'pause'` reason; other reasons keep holding the timer. */
     resume: () => void;
     destroy: () => void;
+    /**
+     * Restarts the countdown from the full `delay`. A held timer stays held, so a toast updated
+     * under the pointer or in a background tab does not start counting down.
+     */
     update: (delay: number) => void;
+    private cancelFrame;
     private scheduleFrame;
 }
+/**
+ * Reports when the window becomes inactive (blurred, or its document hidden) and active again:
+ * `onChange(true)` on the way in, `onChange(false)` on the way out. A document that is already
+ * hidden reports `true` at once; focus is assumed at the start. Returns the cleanup.
+ */
+export declare const watchWindowActivity: (onChange: (inactive: boolean) => void, targetWindow?: Window | undefined) => (() => void);
+/** Reason `holdWhileWindowInactive` holds a timer with. */
+export declare const WINDOW_INACTIVE_REASON = "window";
+/**
+ * Holds `timer` with `reason` while the window is blurred or its tab hidden, and releases it when
+ * the window is active again. Returns the cleanup, which also releases the reason.
+ */
+export declare const holdWhileWindowInactive: (timer: Pick<Timer, "hold" | "release">, reason?: string) => (() => void);

package/dist/utils/timer.svelte.js

@@ -1,69 +1,203 @@
+import { untrack } from 'svelte';
+/** The reason `pause()` holds and `resume()` releases. */
+export const PAUSE_REASON = 'pause';
+/**
+ * A countdown driven by requestAnimationFrame, with reactive `elapsed` and `remaining`.
+ *
+ * Several things can stop it at once (hover, keyboard focus, a swipe, an inactive window): each
+ * one calls `hold(reason)` and later `release(reason)`, and the countdown runs only while no
+ * reason holds it. `pause()` and `resume()` hold and release the `'pause'` reason.
+ *
+ * Frames stop while a tab is hidden but `performance.now()` keeps counting, so the owner has to
+ * hold the timer while its window is inactive (see `watchWindowActivity`); otherwise the first
+ * frame after the user comes back sees the whole hidden interval as elapsed.
+ */
 export class Timer {
     rafId = null;
     startTime = 0;
     pausedTime = 0;
     callback;
-    isPaused = false;
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- read imperatively, so `hold()` in an effect doesn't subscribe it; `held` and `revision` are the reactive mirrors
+    holds = new Set();
+    // Bumped on every hold and release, so `heldBy` and `isHeldBy` are reactive.
+    revision = $state(0);
+    // Bumps `revision` without reading it, so a `hold()` inside an effect doesn't subscribe it.
+    touch = () => untrack(() => (this.revision += 1));
+    // Set once the callback ran or the timer was destroyed; only `update()` restarts it.
+    stopped = false;
+    held = $state(false);
     delay = $state(0);
     remaining = $state(0);
     elapsed = $state(0);
     elapsedInSeconds = $derived(Math.round(Math.min(this.elapsed / 1000, this.delay / 1000)));
     elapsedInPercent = $derived(Math.round(Math.min((this.elapsed / this.delay) * 100, 100)));
-    constructor(callback, delay) {
+    constructor(callback, delay, { startPaused = false, heldBy = [] } = {}) {
         this.callback = callback;
         this.delay = delay;
         this.remaining = delay;
-        if (delay > 0) {
+        for (const reason of typeof heldBy === 'string' ? [heldBy] : heldBy)
+            this.holds.add(reason);
+        if (startPaused)
+            this.holds.add(PAUSE_REASON);
+        this.held = this.holds.size > 0;
+        if (delay > 0 && !this.held) {
             this.start();
         }
     }
+    /** Whether any reason holds the countdown. Reactive. */
+    get paused() {
+        return this.held;
+    }
+    /** The reasons currently holding the countdown, in the order they were added. Reactive. */
+    get heldBy() {
+        void this.revision;
+        return [...this.holds];
+    }
+    /** Whether `reason` currently holds the countdown. Reactive. */
+    isHeldBy = (reason) => {
+        void this.revision;
+        return this.holds.has(reason);
+    };
     start = () => {
+        this.cancelFrame();
         this.startTime = performance.now();
         this.rafId = requestAnimationFrame(this.scheduleFrame);
     };
-    pause = () => {
-        if (this.rafId !== null) {
-            cancelAnimationFrame(this.rafId);
-            this.rafId = null;
-        }
-        this.isPaused = true;
+    /**
+     * Stops the countdown for `reason`, keeping the time already elapsed. Holding with a reason
+     * that already holds it changes nothing.
+     */
+    hold = (reason) => {
+        if (this.holds.has(reason))
+            return;
+        this.holds.add(reason);
+        this.touch();
+        if (this.holds.size > 1)
+            return;
+        this.cancelFrame();
         this.pausedTime = this.elapsed;
+        this.held = true;
     };
-    resume = () => {
-        if (this.isPaused) {
-            this.startTime = performance.now() - this.pausedTime;
-            this.isPaused = false;
-            this.rafId = requestAnimationFrame(this.scheduleFrame);
-        }
+    /**
+     * Drops `reason`. When no other reason holds the timer, the countdown resumes with the time it
+     * had left. Releasing a reason that doesn't hold it changes nothing.
+     */
+    release = (reason) => {
+        if (!this.holds.delete(reason))
+            return;
+        this.touch();
+        if (this.holds.size > 0)
+            return;
+        this.held = false;
+        if (this.stopped || this.delay <= 0)
+            return;
+        this.startTime = performance.now() - this.pausedTime;
+        this.cancelFrame();
+        this.rafId = requestAnimationFrame(this.scheduleFrame);
     };
+    /** Holds the countdown with the `'pause'` reason. */
+    pause = () => this.hold(PAUSE_REASON);
+    /** Releases the `'pause'` reason; other reasons keep holding the timer. */
+    resume = () => this.release(PAUSE_REASON);
     destroy = () => {
-        if (this.rafId !== null) {
-            cancelAnimationFrame(this.rafId);
-            this.rafId = null;
-        }
+        this.cancelFrame();
+        this.stopped = true;
     };
+    /**
+     * Restarts the countdown from the full `delay`. A held timer stays held, so a toast updated
+     * under the pointer or in a background tab does not start counting down.
+     */
     update = (delay) => {
-        this.destroy();
+        this.cancelFrame();
+        this.stopped = false;
         this.delay = delay;
         this.remaining = delay;
         this.elapsed = 0;
         this.pausedTime = 0;
-        this.isPaused = false;
-        if (delay > 0) {
+        if (delay > 0 && this.holds.size === 0) {
             this.start();
         }
     };
+    cancelFrame = () => {
+        if (this.rafId === null)
+            return;
+        cancelAnimationFrame(this.rafId);
+        this.rafId = null;
+    };
     scheduleFrame = (timestamp) => {
-        if (this.isPaused)
+        this.rafId = null;
+        if (this.holds.size > 0 || this.stopped)
             return;
-        this.elapsed = timestamp - this.startTime;
+        // A frame's timestamp can precede the `performance.now()` read in `start()`.
+        this.elapsed = Math.max(0, timestamp - this.startTime);
         this.remaining = Math.max(0, this.delay - this.elapsed);
         if (this.elapsed >= this.delay) {
+            this.stopped = true;
             this.callback();
-            this.rafId = null;
         }
         else {
             this.rafId = requestAnimationFrame(this.scheduleFrame);
         }
     };
 }
+/**
+ * Reports when the window becomes inactive (blurred, or its document hidden) and active again:
+ * `onChange(true)` on the way in, `onChange(false)` on the way out. A document that is already
+ * hidden reports `true` at once; focus is assumed at the start. Returns the cleanup.
+ */
+export const watchWindowActivity = (onChange, targetWindow = typeof window === 'undefined' ? undefined : window) => {
+    if (!targetWindow)
+        return () => { };
+    const targetDocument = targetWindow.document;
+    let blurred = false;
+    let hidden = targetDocument.visibilityState === 'hidden';
+    let inactive = hidden;
+    const update = () => {
+        const next = blurred || hidden;
+        if (next === inactive)
+            return;
+        inactive = next;
+        onChange(next);
+    };
+    // Blur and focus don't bubble, so these only see the window's own events; the target check
+    // keeps element focus changes out all the same.
+    const onBlur = (event) => {
+        if (event.target !== event.currentTarget)
+            return;
+        blurred = true;
+        update();
+    };
+    const onFocus = (event) => {
+        if (event.target !== event.currentTarget)
+            return;
+        blurred = false;
+        update();
+    };
+    const onVisibilityChange = () => {
+        hidden = targetDocument.visibilityState === 'hidden';
+        update();
+    };
+    targetWindow.addEventListener('blur', onBlur);
+    targetWindow.addEventListener('focus', onFocus);
+    targetDocument.addEventListener('visibilitychange', onVisibilityChange);
+    if (inactive)
+        onChange(true);
+    return () => {
+        targetWindow.removeEventListener('blur', onBlur);
+        targetWindow.removeEventListener('focus', onFocus);
+        targetDocument.removeEventListener('visibilitychange', onVisibilityChange);
+    };
+};
+/** Reason `holdWhileWindowInactive` holds a timer with. */
+export const WINDOW_INACTIVE_REASON = 'window';
+/**
+ * Holds `timer` with `reason` while the window is blurred or its tab hidden, and releases it when
+ * the window is active again. Returns the cleanup, which also releases the reason.
+ */
+export const holdWhileWindowInactive = (timer, reason = WINDOW_INACTIVE_REASON) => {
+    const stop = watchWindowActivity((inactive) => inactive ? timer.hold(reason) : timer.release(reason));
+    return () => {
+        stop();
+        timer.release(reason);
+    };
+};

package/dist/utils/trigger.d.ts

@@ -0,0 +1,41 @@
+/** Elements that may carry popup ARIA state. */
+export declare 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 declare const NATIVE_CONTROL = "button, a[href], input, select, textarea, summary";
+/** A trigger's popup state, in the library's semantic vocabulary. */
+export type PopupTriggerProps = {
+    haspopup: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | true;
+    expanded: boolean;
+    controls: string | undefined;
+};
+/**
+ * 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 declare function writePopupAria(node: HTMLElement, props: PopupTriggerProps): void;
+export interface TriggerActivationOptions {
+    /** Requests the change; called with the click or key event that pressed the trigger. */
+    activate: (event: MouseEvent | KeyboardEvent) => void;
+    /**
+     * A counter the owner bumps on every open-state request. The press stands down when it moved
+     * while the event was dispatching: the element's own handler (`onclick={popover.toggle}`)
+     * already acted, and acting again would undo it.
+     */
+    requests: () => number;
+    /** Whether presses act at all (`openOnClick`). Default `true`. */
+    enabled?: () => boolean;
+}
+/**
+ * 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 declare function triggerActivation(node: HTMLElement, options: TriggerActivationOptions): () => void;
+/**
+ * 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 declare function triggerFocusTarget(trigger: HTMLElement, event?: Event): HTMLElement | null;
+/** The element that has focus now, or `null` when nothing does (the body). */
+export declare function focusedElement(document?: Document): HTMLElement | null;