sheer-ui 0.4.2 → 0.5.0

package/dist/internal/focus-scope/types.d.ts

@@ -0,0 +1,39 @@
+import type { Snippet } from 'svelte';
+import type { EventCallback } from '../tools/utils/events.js';
+import type { ReadableBox } from '../tools/index.js';
+export type FocusScopeProps = {
+    /**
+     * Event handler called when auto-focusing on open.
+     * Can be prevented.
+     */
+    onOpenAutoFocus?: EventCallback;
+    /**
+     * Event handler called when auto-focusing on close.
+     * Can be prevented.
+     */
+    onCloseAutoFocus?: EventCallback;
+    /**
+     * Whether focus is trapped within the focus scope.
+     *
+     * @defaultValue false
+     */
+    trapFocus?: boolean;
+};
+export type FocusScopeImplProps = {
+    /**
+     * The snippet to render the focus scope container with its props.
+     */
+    focusScope?: Snippet<[{
+        props: Record<string, unknown>;
+    }]>;
+    /**
+     * When `true` will loop through the tabbable elements in the focus scope.
+     */
+    loop?: boolean;
+    /**
+     * Whether the content within the focus trap is being force mounted or not.
+     */
+    forceMount?: boolean;
+    enabled: boolean;
+    ref: ReadableBox<HTMLElement | null>;
+} & FocusScopeProps;

package/dist/internal/focus-scope/types.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/focus.d.ts

@@ -0,0 +1 @@
+export declare function focusFirst(candidates: HTMLElement[], getActiveElement: () => Element | null): boolean;

package/dist/internal/focus.js

@@ -0,0 +1,12 @@
+export function focusFirst(candidates, getActiveElement) {
+    const previouslyFocusedElement = getActiveElement();
+    for (const candidate of candidates) {
+        // focus already sits where we want it, so don't walk past it into the next candidate
+        if (candidate === previouslyFocusedElement)
+            return true;
+        candidate.focus({ preventScroll: true });
+        if (getActiveElement() !== previouslyFocusedElement)
+            return true;
+    }
+    return false;
+}

package/dist/internal/global-singleton.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Realm-global singleton keyed on `globalThis`, so layer stacks and the id counter
+ * survive multiple module-graph copies of this library in one page (e.g. two bundles).
+ * Replaces the ambient `app.d.ts` globals: ambient declarations don't travel when the
+ * library is consumed as workspace source, a typed accessor does.
+ */
+export declare function globalSingleton<T>(key: string, init: () => T): T;

package/dist/internal/global-singleton.js

@@ -0,0 +1,10 @@
+/**
+ * Realm-global singleton keyed on `globalThis`, so layer stacks and the id counter
+ * survive multiple module-graph copies of this library in one page (e.g. two bundles).
+ * Replaces the ambient `app.d.ts` globals: ambient declarations don't travel when the
+ * library is consumed as workspace source, a typed accessor does.
+ */
+export function globalSingleton(key, init) {
+    const globals = globalThis;
+    return (globals[key] ??= init());
+}

package/dist/internal/group-value.svelte.d.ts

@@ -0,0 +1,17 @@
+/** The group's bindable value, as an accessor on the group's options. */
+interface GroupValue {
+    value: string[];
+}
+/** The item's `value` and `checked` as accessors over its props. */
+interface GroupItem {
+    readonly value: string | undefined;
+    readonly checked: boolean;
+}
+/**
+ * Writes the item's checked state into the group's value array and returns a reader for
+ * the reverse direction: whether the group holds the item's value, or undefined when the
+ * item is outside a group or has no value. The component repairs its own `checked` bindable
+ * from that reader, so a parent-driven change never fires the item's onCheckedChange.
+ */
+export declare function joinGroup(group: GroupValue | null, item: GroupItem): () => boolean | undefined;
+export {};

package/dist/internal/group-value.svelte.js

@@ -0,0 +1,25 @@
+import { untrack } from 'svelte';
+/**
+ * Writes the item's checked state into the group's value array and returns a reader for
+ * the reverse direction: whether the group holds the item's value, or undefined when the
+ * item is outside a group or has no value. The component repairs its own `checked` bindable
+ * from that reader, so a parent-driven change never fires the item's onCheckedChange.
+ */
+export function joinGroup(group, item) {
+    if (!group)
+        return () => undefined;
+    $effect(() => {
+        const checked = item.checked;
+        untrack(() => {
+            const value = item.value;
+            const values = group.value;
+            if (!value || checked === values.includes(value))
+                return;
+            group.value = checked ? [...values, value] : values.filter((v) => v !== value);
+        });
+    });
+    return () => {
+        const value = item.value;
+        return value ? group.value.includes(value) : undefined;
+    };
+}

package/dist/internal/hover-intent-geometry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared pointer-geometry primitives for "don't close while the cursor is moving toward the
+ * content" hover tracking. Both `SafePolygon` (tooltip/popover/link-preview) and `MenuSubmenuIntent`
+ * (nested menu chains, in menu.svelte.ts) need this exact math. It's kept in the bitmask+tuple
+ * representation SafePolygon originated (cheap integer comparisons instead of string comparisons on
+ * every pointermove) rather than a more "readable" string+object form — this runs on pointer-move
+ * frequency, and the bits are the performant version worth converging on.
+ *
+ * Deliberately excludes the "safe zone" shape builders (getSafePolygon / getIntentPolygon): those are
+ * genuinely different algorithms (a forgiving hexagon vs a precise triangle) driven by different
+ * domain requirements — a single floating trigger/content pair vs densely-packed sibling menu items —
+ * not incidental duplication, so each keeps its own.
+ */
+export type Point = [number, number];
+export declare const AXIS_VERTICAL = 2;
+export declare const DIR_POS = 1;
+export declare const LEFT = 0;
+export declare const RIGHT = 1;
+export declare const TOP = 2;
+export declare const BOTTOM = 3;
+export type SideBits = typeof LEFT | typeof RIGHT | typeof TOP | typeof BOTTOM;
+export declare function isPointInPolygon(point: Point, polygon: Point[]): boolean;
+export declare const isInsideRect: (point: Point, rect: DOMRect) => boolean;
+export declare function getSide(triggerRect: DOMRect, contentRect: DOMRect): SideBits;
+export declare const flipSide: (side: SideBits) => SideBits;
+export declare const TARGET_NONE = 0;
+export declare const TARGET_TRIGGER = 1;
+export declare const TARGET_CONTENT = 2;
+export type TargetBits = typeof TARGET_NONE | typeof TARGET_TRIGGER | typeof TARGET_CONTENT;
+/**
+ * A rectangular corridor between trigger and content — this prevents closing when the cursor is in
+ * the gap between them.
+ */
+export declare function getCorridorPolygon(triggerRect: DOMRect, contentRect: DOMRect, side: SideBits, buffer: number): Point[];

package/dist/internal/hover-intent-geometry.js

@@ -0,0 +1,76 @@
+/**
+ * Shared pointer-geometry primitives for "don't close while the cursor is moving toward the
+ * content" hover tracking. Both `SafePolygon` (tooltip/popover/link-preview) and `MenuSubmenuIntent`
+ * (nested menu chains, in menu.svelte.ts) need this exact math. It's kept in the bitmask+tuple
+ * representation SafePolygon originated (cheap integer comparisons instead of string comparisons on
+ * every pointermove) rather than a more "readable" string+object form — this runs on pointer-move
+ * frequency, and the bits are the performant version worth converging on.
+ *
+ * Deliberately excludes the "safe zone" shape builders (getSafePolygon / getIntentPolygon): those are
+ * genuinely different algorithms (a forgiving hexagon vs a precise triangle) driven by different
+ * domain requirements — a single floating trigger/content pair vs densely-packed sibling menu items —
+ * not incidental duplication, so each keeps its own.
+ */
+export const AXIS_VERTICAL = 0b10;
+export const DIR_POS = 0b01;
+export const LEFT = 0b00;
+export const RIGHT = 0b01;
+export const TOP = 0b10;
+export const BOTTOM = 0b11;
+export function isPointInPolygon(point, polygon) {
+    const [x, y] = point;
+    let isInside = false;
+    const length = polygon.length;
+    for (let i = 0, j = length - 1; i < length; j = i++) {
+        const [xi, yi] = polygon[i] ?? [0, 0];
+        const [xj, yj] = polygon[j] ?? [0, 0];
+        const intersect = yi >= y !== yj >= y && x <= ((xj - xi) * (y - yi)) / (yj - yi) + xi;
+        if (intersect) {
+            isInside = !isInside;
+        }
+    }
+    return isInside;
+}
+export const isInsideRect = (point, rect) => point[0] >= rect.left && point[0] <= rect.right && point[1] >= rect.top && point[1] <= rect.bottom;
+export function getSide(triggerRect, contentRect) {
+    // determine which side the content is on relative to trigger
+    const dx = contentRect.left + contentRect.width / 2 - (triggerRect.left + triggerRect.width / 2);
+    const dy = contentRect.top + contentRect.height / 2 - (triggerRect.top + triggerRect.height / 2);
+    return Math.abs(dx) > Math.abs(dy)
+        ? (dx > 0 ? DIR_POS : 0)
+        : (AXIS_VERTICAL | (dy > 0 ? DIR_POS : 0));
+}
+export const flipSide = (side) => (side ^ DIR_POS);
+export const TARGET_NONE = 0;
+export const TARGET_TRIGGER = 0b01;
+export const TARGET_CONTENT = 0b10;
+/**
+ * A rectangular corridor between trigger and content — this prevents closing when the cursor is in
+ * the gap between them.
+ */
+export function getCorridorPolygon(triggerRect, contentRect, side, buffer) {
+    const b = buffer;
+    const minX = Math.min(triggerRect.left, contentRect.left) - b;
+    const maxX = Math.max(triggerRect.right, contentRect.right) + b;
+    const minY = Math.min(triggerRect.top, contentRect.top) - b;
+    const maxY = Math.max(triggerRect.bottom, contentRect.bottom) + b;
+    const dir = side & DIR_POS;
+    if (side & AXIS_VERTICAL) {
+        const triggerY = dir === 0 ? triggerRect.top : triggerRect.bottom;
+        const contentY = dir === 0 ? contentRect.bottom : contentRect.top;
+        return [
+            [minX, triggerY],
+            [minX, contentY],
+            [maxX, contentY],
+            [maxX, triggerY],
+        ];
+    }
+    const triggerX = dir === 0 ? triggerRect.left : triggerRect.right;
+    const contentX = dir === 0 ? contentRect.right : contentRect.left;
+    return [
+        [triggerX, minY],
+        [contentX, minY],
+        [contentX, maxY],
+        [triggerX, maxY],
+    ];
+}

package/dist/internal/index.d.ts

@@ -0,0 +1,21 @@
+export type Selected<Value> = {
+    value: Value;
+    label?: string;
+};
+export type FocusTarget = string | HTMLElement | SVGElement | null;
+export type FocusProp = FocusTarget | ((defaultEl?: HTMLElement | null) => FocusTarget);
+export type Orientation = 'horizontal' | 'vertical';
+export type Direction = 'ltr' | 'rtl';
+/**
+ * Controls positioning of the slider thumb.
+ *
+ * - `exact`: The thumb is centered exactly at the value of the slider.
+ * - `contain`: The thumb is centered exactly at the value of the slider, but will be contained within the slider track at the ends.
+ */
+export type SliderThumbPositioning = 'exact' | 'contain';
+export type { StyleProperties } from './tools/types.js';
+export type { WithoutChild, WithoutChildren, WithoutChildrenOrChild, WithElementRef } from './utils.js';
+export type { WithChild, Without, WithChildren, FloatingContentSnippetProps, StaticContentSnippetProps } from './types.js';
+export type { SegmentPart, EditableSegmentPart, EditableTimeSegmentPart, Month, DateMatcher, DateOnInvalid, DateRangeValidator, DateValidator, DateRange, TimeValue, TimeSegmentPart, TimeEndpoints, TimeValidator, TimeRangeValidator, TimeOnInvalid, } from './date-time/types.js';
+export { mergeProps } from './merge-props.js';
+export * from './attribute-types.js';

package/dist/internal/index.js

@@ -0,0 +1,3 @@
+// oxlint-disable no-explicit-any
+export { mergeProps } from './merge-props.js';
+export * from './attribute-types.js';

package/dist/internal/kbd.d.ts

@@ -0,0 +1,57 @@
+import type { Direction, Orientation } from './index.js';
+export declare const kbd: {
+    readonly ALT: "Alt";
+    readonly ARROW_DOWN: "ArrowDown";
+    readonly ARROW_LEFT: "ArrowLeft";
+    readonly ARROW_RIGHT: "ArrowRight";
+    readonly ARROW_UP: "ArrowUp";
+    readonly BACKSPACE: "Backspace";
+    readonly CAPS_LOCK: "CapsLock";
+    readonly CONTROL: "Control";
+    readonly DELETE: "Delete";
+    readonly END: "End";
+    readonly ENTER: "Enter";
+    readonly ESCAPE: "Escape";
+    readonly F1: "F1";
+    readonly F2: "F2";
+    readonly F3: "F3";
+    readonly F4: "F4";
+    readonly F5: "F5";
+    readonly F6: "F6";
+    readonly F7: "F7";
+    readonly F8: "F8";
+    readonly F9: "F9";
+    readonly F10: "F10";
+    readonly F11: "F11";
+    readonly F12: "F12";
+    readonly HOME: "Home";
+    readonly META: "Meta";
+    readonly PAGE_DOWN: "PageDown";
+    readonly PAGE_UP: "PageUp";
+    readonly SHIFT: "Shift";
+    readonly SPACE: " ";
+    readonly TAB: "Tab";
+    readonly CTRL: "Control";
+    readonly ASTERISK: "*";
+    readonly a: "a";
+    readonly A: "A";
+    readonly p: "p";
+    readonly P: "P";
+    readonly n: "n";
+    readonly j: "j";
+    readonly k: "k";
+    readonly h: "h";
+    readonly l: "l";
+};
+export declare const getDirectionalKeys: (dir?: Direction, orientation?: Orientation) => {
+    nextKey: "ArrowDown" | "ArrowLeft" | "ArrowRight";
+    prevKey: "ArrowLeft" | "ArrowRight" | "ArrowUp";
+};
+/**
+ * Keyboard key-sets shared across menu, select, and roving-focus navigation.
+ * Membership is tested with `.includes()`, so element order is irrelevant.
+ */
+export declare const FIRST_KEYS: string[];
+export declare const LAST_KEYS: string[];
+export declare const FIRST_LAST_KEYS: string[];
+export declare const SELECTION_KEYS: string[];

package/dist/internal/kbd.js

@@ -0,0 +1,56 @@
+export const kbd = {
+    ALT: 'Alt',
+    ARROW_DOWN: 'ArrowDown',
+    ARROW_LEFT: 'ArrowLeft',
+    ARROW_RIGHT: 'ArrowRight',
+    ARROW_UP: 'ArrowUp',
+    BACKSPACE: 'Backspace',
+    CAPS_LOCK: 'CapsLock',
+    CONTROL: 'Control',
+    DELETE: 'Delete',
+    END: 'End',
+    ENTER: 'Enter',
+    ESCAPE: 'Escape',
+    F1: 'F1',
+    F2: 'F2',
+    F3: 'F3',
+    F4: 'F4',
+    F5: 'F5',
+    F6: 'F6',
+    F7: 'F7',
+    F8: 'F8',
+    F9: 'F9',
+    F10: 'F10',
+    F11: 'F11',
+    F12: 'F12',
+    HOME: 'Home',
+    META: 'Meta',
+    PAGE_DOWN: 'PageDown',
+    PAGE_UP: 'PageUp',
+    SHIFT: 'Shift',
+    SPACE: ' ',
+    TAB: 'Tab',
+    CTRL: 'Control',
+    ASTERISK: '*',
+    a: 'a',
+    A: 'A',
+    p: 'p',
+    P: 'P',
+    n: 'n',
+    j: 'j',
+    k: 'k',
+    h: 'h',
+    l: 'l',
+};
+export const getDirectionalKeys = (dir = 'ltr', orientation = 'horizontal') => ({
+    nextKey: orientation === 'vertical' ? kbd.ARROW_DOWN : dir === 'rtl' ? kbd.ARROW_LEFT : kbd.ARROW_RIGHT,
+    prevKey: orientation === 'vertical' ? kbd.ARROW_UP : dir === 'rtl' ? kbd.ARROW_RIGHT : kbd.ARROW_LEFT,
+});
+/**
+ * Keyboard key-sets shared across menu, select, and roving-focus navigation.
+ * Membership is tested with `.includes()`, so element order is irrelevant.
+ */
+export const FIRST_KEYS = [kbd.ARROW_DOWN, kbd.PAGE_UP, kbd.HOME];
+export const LAST_KEYS = [kbd.ARROW_UP, kbd.PAGE_DOWN, kbd.END];
+export const FIRST_LAST_KEYS = [...FIRST_KEYS, ...LAST_KEYS];
+export const SELECTION_KEYS = [kbd.ENTER, kbd.SPACE];

package/dist/internal/layer-stack.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A registry of active "layers" (dismissible overlays, escape-key listeners, text-selection
+ * locks, ...) that answers "am I responsible for handling this event right now" — the topmost
+ * registered layer whose value is in the closing set, falling back to the first-registered layer
+ * if none defer. `isClosingBehavior` defaults to always-true, matching stacks that don't have a
+ * behavior-type distinction at all (just "the most recently registered layer is responsible").
+ *
+ * Each layer type gets its own stack via its own `createLayerStack()` call — they don't compete
+ * with each other for "who's on top".
+ */
+export interface LayerStack<TInstance, TValue> {
+    register(instance: TInstance, value: TValue): void;
+    unregister(instance: TInstance): void;
+    isResponsible(instance: TInstance): boolean;
+}
+export declare function createLayerStack<TInstance, TValue>(isClosingBehavior?: (value: TValue) => boolean): LayerStack<TInstance, TValue>;

package/dist/internal/layer-stack.js

@@ -0,0 +1,19 @@
+export function createLayerStack(isClosingBehavior = () => true) {
+    const layers = new Map();
+    return {
+        register(instance, value) {
+            layers.set(instance, value);
+        },
+        unregister(instance) {
+            layers.delete(instance);
+        },
+        isResponsible(instance) {
+            const entries = [...layers];
+            const topMost = entries.findLast(([, value]) => isClosingBehavior(value));
+            if (topMost)
+                return topMost[0] === instance;
+            const firstEntry = entries[0];
+            return firstEntry !== undefined && firstEntry[0] === instance;
+        },
+    };
+}

package/dist/internal/math.d.ts

@@ -0,0 +1 @@
+export declare const linearScale: ([d0, d1]: [number, number], [r0, r1]: [number, number], clamp?: boolean) => (x: number) => number;

package/dist/internal/math.js

@@ -0,0 +1,9 @@
+export const linearScale = ([d0, d1], [r0, r1], clamp = true) => {
+    const slope = d1 === d0 ? 0 : (r1 - r0) / (d1 - d0);
+    const min = Math.min(r0, r1);
+    const max = Math.max(r0, r1);
+    return (x) => {
+        const value = r0 + slope * (x - d0);
+        return clamp ? Math.min(max, Math.max(min, value)) : value;
+    };
+};

package/dist/internal/merge-props.d.ts

@@ -0,0 +1,5 @@
+export declare const mergeProps: import("overrule/props").MergeProps<{
+    readonly styleAs: "string";
+    readonly dropFalseAttrs: readonly ["hidden", "disabled"];
+    readonly isEventHandler: (key: string) => boolean;
+}>;

package/dist/internal/merge-props.js

@@ -0,0 +1,6 @@
+import { createMergeProps } from 'overrule/props';
+export const mergeProps = createMergeProps({
+    styleAs: 'string',
+    dropFalseAttrs: ['hidden', 'disabled'],
+    isEventHandler: (key) => key.length > 2 && key.startsWith('on') && key === key.toLowerCase(),
+});

package/dist/internal/native-dialog-controller.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { EscapeBehaviorType } from './escape-layer/types.js';
+import type { InteractOutsideBehaviorType } from './dismissible-layer/types.js';
+import type { Getter } from './tools/index.js';
+type NativeDialogControllerOptions = {
+    open: Getter<boolean>;
+    onClose: () => void;
+    outsideEvent?: 'pointerdown' | 'click';
+    onInteractOutside?: Getter<(event: PointerEvent) => void>;
+    interactOutsideBehavior?: Getter<InteractOutsideBehaviorType>;
+    onEscapeKeydown?: Getter<(event: KeyboardEvent) => void>;
+    escapeKeydownBehavior?: Getter<EscapeBehaviorType>;
+    trapFocus?: Getter<boolean>;
+};
+/**
+ * Bridges declarative open state to the native dialog top layer and centralizes native dismissal,
+ * veto, cleanup, and optional sequential-focus wrapping. Visual policy stays with each adapter.
+ */
+export declare function nativeDialogControllerAttachment(options: NativeDialogControllerOptions): {
+    [x: symbol]: (node: HTMLDialogElement) => void;
+};
+export {};

package/dist/internal/native-dialog-controller.svelte.js

@@ -0,0 +1,82 @@
+import { getTabbableCandidates } from './tabbable.js';
+import { createSettleRunner } from './animations-settled.svelte.js';
+import { createAttachmentKey } from 'svelte/attachments';
+import { on } from 'svelte/events';
+import { getAbortSignal } from 'svelte';
+/**
+ * Bridges declarative open state to the native dialog top layer and centralizes native dismissal,
+ * veto, cleanup, and optional sequential-focus wrapping. Visual policy stays with each adapter.
+ */
+export function nativeDialogControllerAttachment(options) {
+    const controller = ((node) => {
+        // Every dismissal routes through options.onClose() → root state → this effect, never
+        // node.close() directly: close() hides the dialog the same frame (`overlay` is
+        // Chromium-only and WebKit doesn't start display/top-layer transitions at all —
+        // bug 275184), so the exit ride is a data-[state=closed] keyframe animation played
+        // while the dialog is still open, and close() fires only once it settles.
+        const closeSettle = createSettleRunner({ subtree: false });
+        $effect(() => {
+            if (options.open()) {
+                closeSettle.cancel();
+                if (!node.open)
+                    node.showModal();
+            }
+            else if (node.open) {
+                // An open flip re-runs this effect and cancels the runner first; node.open covers a
+                // UA-initiated close in the meantime.
+                closeSettle.run(node, () => {
+                    if (node.open)
+                        node.close();
+                });
+            }
+        });
+        const signal = getAbortSignal();
+        on(node, 'close', options.onClose, { signal });
+        const handleInteractOutside = (event) => {
+            if (event.target !== node)
+                return;
+            const shim = new PointerEvent('pointerdown', { cancelable: true });
+            options.onInteractOutside?.()(shim);
+            if (shim.defaultPrevented || options.interactOutsideBehavior?.() === 'ignore')
+                return;
+            options.onClose();
+        };
+        if (options.outsideEvent === 'pointerdown')
+            on(node, 'pointerdown', handleInteractOutside, { signal });
+        else if (options.outsideEvent === 'click')
+            on(node, 'click', handleInteractOutside, { signal });
+        on(node, 'cancel', (event) => {
+            // Always prevent the native instant close; a permitted Escape closes through state
+            // so the exit animation runs first.
+            event.preventDefault();
+            const shim = new KeyboardEvent('keydown', { key: 'Escape', cancelable: true });
+            options.onEscapeKeydown?.()(shim);
+            if (shim.defaultPrevented || options.escapeKeydownBehavior?.() === 'ignore')
+                return;
+            options.onClose();
+        }, { signal });
+        // Load-bearing, not redundant with showModal(): verified in Chromium 2026-07-27 —
+        // without this, Tab past the last tabbable parks focus on <body> for one step.
+        if (options.trapFocus) {
+            on(node, 'keydown', (event) => {
+                if (event.key !== 'Tab' || !options.trapFocus?.())
+                    return;
+                const tabbables = getTabbableCandidates(node);
+                if (tabbables.length === 0)
+                    return;
+                const first = tabbables[0];
+                const last = tabbables[tabbables.length - 1];
+                const active = node.ownerDocument.activeElement;
+                if (!event.shiftKey && active === last) {
+                    event.preventDefault();
+                    first.focus();
+                }
+                else if (event.shiftKey && active === first) {
+                    event.preventDefault();
+                    last.focus();
+                }
+            }, { signal });
+        }
+    });
+    return { [createAttachmentKey()]: controller };
+}

package/dist/internal/native-popover.svelte.d.ts

@@ -0,0 +1,50 @@
+import type { Getter } from './tools/index.js';
+type NativePopoverAnchor = HTMLElement | string | null | undefined | object;
+/**
+ * The slice of a content state the lifecycle drives — popover, tooltip, and
+ * link-preview content states all expose this shape, so the hook takes the
+ * state itself instead of a getter per field.
+ *
+ * `manual` mode requires the two dismissal handlers; `auto` mode requires `dismiss`
+ * (the UA decides *when* to close, the state only has to follow).
+ */
+interface NativePopoverContentState {
+    readonly root: {
+        readonly opts: {
+            readonly open: boolean;
+            readonly onOpenChangeComplete: (open: boolean) => void;
+        };
+        readonly triggerNode: HTMLElement | null;
+    };
+    readonly opts: {
+        readonly ref: HTMLElement | null;
+    };
+    onEscapeKeydown?: (event: KeyboardEvent) => void;
+    onInteractOutside?: (event: PointerEvent) => void;
+    dismiss?: () => void;
+}
+/**
+ * Drives a native popover surface from a content state: open/close via
+ * showPopover()/hidePopover() (anchored to the trigger, or the `anchor` override) and
+ * onOpenChangeComplete once the surface's own animations settle.
+ *
+ * `mode: 'auto'` (Popover) hands dismissal to the UA — light dismiss and Escape run
+ * through the browser's top-layer stack, so stacked surfaces close one per Escape —
+ * and syncs UA-initiated closes back into state via the `toggle` event. `manual`
+ * (Tooltip, LinkPreview — they need `popover="hint"`, which Safari lacks as of
+ * 2026-07) keeps document-level Escape / outside-pointerdown listeners; those bypass
+ * bitsEscapeLayers, so a manual surface over a JS-stack menu still closes both on one
+ * Escape.
+ *
+ * Returns the anchored-surface prop bag (`popover`, `data-anchored`) — the JS half of
+ * the contract whose CSS half lives in ui.css under `[data-anchored]` — so surfaces
+ * merge it instead of restating it.
+ */
+export declare function useNativePopoverLifecycle(state: NativePopoverContentState, options?: {
+    anchor?: Getter<NativePopoverAnchor>;
+    mode?: 'auto' | 'manual';
+}): {
+    readonly popover: "auto" | "manual";
+    readonly 'data-anchored': "";
+};
+export {};