@mercury-fx/core 2.4.0

package/dist/internal/date-time/formatter.d.ts

@@ -0,0 +1,114 @@
+import { DateValue } from '@internationalized/date';
+import { HourCycle, TimeValue } from '../..shared/date/types.js';
+/**
+ * A read-only, *live* value source — anything that exposes its current value
+ * behind a `current` getter. A Svelte `box`, a signal wrapper, or the Effector
+ * adapter from `@mercury-fx/effector` (`createFormatterModel`) all satisfy it. The
+ * formatter reads `.current` on every call, so changes to the source are picked
+ * up immediately with no rebuild and no framework coupling in this package.
+ */
+export interface Readable<T> {
+    readonly current: T;
+}
+/** A formatter input that may be a plain value or a live {@link Readable}. */
+export type MaybeReadable<T> = T | Readable<T>;
+/**
+ * How the month renders in {@link Formatter.fullMonthAndYear}: an `Intl` month
+ * style (`"long"`, `"short"`, `"narrow"`, `"numeric"`, `"2-digit"`) or a custom
+ * mapper from the 1-based month number to a string.
+ */
+export type MonthFormat = NonNullable<Intl.DateTimeFormatOptions["month"]> | ((month: number) => string);
+/**
+ * How the year renders in {@link Formatter.fullMonthAndYear}: an `Intl` year
+ * style (`"numeric"`, `"2-digit"`) or a custom mapper from the full year.
+ */
+export type YearFormat = NonNullable<Intl.DateTimeFormatOptions["year"]> | ((year: number) => string);
+/** The resolved day period. */
+export type DayPeriodValue = "AM" | "PM";
+/** Options for {@link createFormatter}. Only `locale` is required. */
+export interface FormatterOptions {
+    /** BCP-47 locale tag. Static, or a live source to follow a locale store. */
+    locale: MaybeReadable<string>;
+    /** Month rendering for `fullMonthAndYear`. Defaults to `"long"`. */
+    monthFormat?: MaybeReadable<MonthFormat>;
+    /** Year rendering for `fullMonthAndYear`. Defaults to `"numeric"`. */
+    yearFormat?: MaybeReadable<YearFormat>;
+}
+/**
+ * The locale-aware date-formatting surface used across the date builders. Every
+ * method goes through `Intl`'s {@link DateFormatter} at the *current* locale, so
+ * output stays consistent and updates when a live `locale` source changes.
+ */
+export interface Formatter {
+    /** Imperatively override the active locale (wins over a live `locale` source). */
+    setLocale(newLocale: string): void;
+    /** The active locale — the override if one was set, else the (possibly live) source. */
+    getLocale(): string;
+    /** Format a native `Date` with arbitrary `Intl` options. */
+    custom(date: Date, options: Intl.DateTimeFormatOptions): string;
+    /** A human "selected date" string, with time included when the value carries one. */
+    selectedDate(date: DateValue, includeTime?: boolean): string;
+    /** The full month + year, honoring `monthFormat` / `yearFormat`. */
+    fullMonthAndYear(date: Date): string;
+    /** The full ("long") month name. */
+    fullMonth(date: Date): string;
+    /** The numeric year. */
+    fullYear(date: Date): string;
+    /** The `Intl` parts of a date value, timezone-aware for zoned values. */
+    toParts(date: DateValue, options?: Intl.DateTimeFormatOptions): Intl.DateTimeFormatPart[];
+    /** A single weekday label at the given width (default `"narrow"`). */
+    dayOfWeek(date: Date, length?: Intl.DateTimeFormatOptions["weekday"]): string;
+    /** "AM" / "PM" for the given instant under the (optional) hour cycle. */
+    dayPeriod(date: Date, hourCycle?: HourCycle): DayPeriodValue;
+    /** The string value of one `Intl` part of a date value (`""` if absent). */
+    part(dateObj: DateValue, type: Intl.DateTimeFormatPartTypes, options?: Intl.DateTimeFormatOptions): string;
+}
+/** Options for {@link createTimeFormatter}. */
+export interface TimeFormatterOptions {
+    /** BCP-47 locale tag. Static, or a live source to follow a locale store. */
+    locale: MaybeReadable<string>;
+}
+/** The locale-aware time-formatting surface (the time-only counterpart to {@link Formatter}). */
+export interface TimeFormatter {
+    /** Imperatively override the active locale (wins over a live `locale` source). */
+    setLocale(newLocale: string): void;
+    /** The active locale — the override if one was set, else the (possibly live) source. */
+    getLocale(): string;
+    /** Format a native `Date` with arbitrary `Intl` options. */
+    custom(date: Date, options: Intl.DateTimeFormatOptions): string;
+    /** A human "selected time" string (long time style). */
+    selectedTime(date: TimeValue): string;
+    /** The `Intl` parts of a time value, timezone-aware for zoned values. */
+    toParts(timeValue: TimeValue, options?: Intl.DateTimeFormatOptions): Intl.DateTimeFormatPart[];
+    /** "AM" / "PM" for the given instant under the (optional) hour cycle. */
+    dayPeriod(date: Date, hourCycle?: HourCycle): DayPeriodValue;
+    /** The string value of one `Intl` part of a time value (`""` if absent). */
+    part(dateObj: TimeValue, type: Intl.DateTimeFormatPartTypes, options?: Intl.DateTimeFormatOptions): string;
+}
+/**
+ * Creates a typed wrapper around `@internationalized/date`'s {@link DateFormatter}
+ * — itself an improved {@link Intl.DateTimeFormat} — used by the date builders to
+ * format dates consistently.
+ *
+ * The wrapper is framework-agnostic: pass plain values for a static formatter, or
+ * {@link Readable} sources (Svelte boxes, signals, the `@mercury-fx/effector` store
+ * adapter) for one that tracks live locale / format changes.
+ *
+ * @example Static
+ * ```ts
+ * const fmt = createFormatter({ locale: "en-GB" });
+ * fmt.fullMonthAndYear(new Date()); // "December 2025"
+ * ```
+ * @example Live (Effector — see `@mercury-fx/effector` `createFormatterModel`)
+ * ```ts
+ * const fmt = createFormatter({ locale: { get current() { return $locale.getState(); } } });
+ * ```
+ *
+ * @see [DateFormatter](https://react-spectrum.adobe.com/internationalized/date/DateFormatter.html)
+ */
+export declare function createFormatter(opts: FormatterOptions): Formatter;
+/**
+ * The time-only counterpart to {@link createFormatter}. Accepts a plain locale
+ * string or a live {@link Readable} source, the same way.
+ */
+export declare function createTimeFormatter(locale: MaybeReadable<string>): TimeFormatter;

package/dist/internal/date-time/placeholders.d.ts

@@ -0,0 +1,8 @@
+declare const supportedLocales: readonly ["ach", "af", "am", "an", "ar", "ast", "az", "be", "bg", "bn", "br", "bs", "ca", "cak", "ckb", "cs", "cy", "da", "de", "dsb", "el", "en", "eo", "es", "et", "eu", "fa", "ff", "fi", "fr", "fy", "ga", "gd", "gl", "he", "hr", "hsb", "hu", "ia", "id", "it", "ja", "ka", "kk", "kn", "ko", "lb", "lo", "lt", "lv", "meh", "ml", "ms", "nl", "nn", "no", "oc", "pl", "pt", "rm", "ro", "ru", "sc", "scn", "sk", "sl", "sr", "sv", "szl", "tg", "th", "tr", "uk", "zh-CN", "zh-TW"];
+declare const placeholderFields: readonly ["year", "month", "day"];
+type SupportedLocale = (typeof supportedLocales)[number];
+type PlaceholderField = (typeof placeholderFields)[number];
+export type PlaceholderMap = Record<SupportedLocale, Record<PlaceholderField, string>>;
+type Field = "era" | "year" | "month" | "day" | "hour" | "minute" | "second" | "dayPeriod";
+export declare function getPlaceholder(field: Field, value: string, locale: SupportedLocale | (string & {})): string;
+export {};

package/dist/internal/date-time/time-value.d.ts

@@ -0,0 +1,11 @@
+import { CalendarDateTime, ZonedDateTime } from '@internationalized/date';
+import { TimeValue } from '../..shared/date/types.js';
+/**
+ * Normalize a {@link TimeValue} to a date-bearing value the `Intl` formatters
+ * can consume. A bare `Time` has no date, so it is anchored to a fixed sentinel
+ * day (2020-01-01) — only the time parts are ever read back out.
+ *
+ * This lives as a standalone leaf (rather than in `field/time-helpers`) so the
+ * formatter can depend on it without pulling in the whole date-field surface.
+ */
+export declare function convertTimeValueToDateValue(time: TimeValue): CalendarDateTime | ZonedDateTime;

package/dist/internal/date-time/utils.d.ts

@@ -0,0 +1,76 @@
+import { CalendarDateTime, DateValue, ZonedDateTime } from '@internationalized/date';
+import { DateMatcher, Granularity, TimeGranularity, TimeValue } from '../..shared/date/types.js';
+type GetDefaultDateProps = {
+    defaultValue?: DateValue | DateValue[] | undefined;
+    minValue?: DateValue;
+    maxValue?: DateValue;
+    granularity?: Granularity;
+};
+type GetDefaultTimeProps = {
+    defaultValue?: TimeValue | undefined;
+    granularity?: TimeGranularity;
+};
+/**
+ * A helper function used throughout the various date builders
+ * to generate a default `DateValue` using the `defaultValue`,
+ * `defaultPlaceholder`, `minValue`, `maxValue`, and `granularity` props.
+ *
+ * It's important to match the `DateValue` type being used
+ * elsewhere in the builder, so they behave according to the
+ * behavior the user expects based on the props they've provided.
+ *
+ */
+export declare function getDefaultDate(opts: GetDefaultDateProps): DateValue;
+export declare function getDefaultTime(opts: GetDefaultTimeProps): TimeValue;
+/**
+ * Given a date string and a reference `DateValue` object, parse the
+ * string to the same type as the reference object.
+ *
+ * Useful for parsing strings from data attributes, which are always
+ * strings, to the same type being used by the date component.
+ */
+export declare function parseStringToDateValue(dateStr: string, referenceVal: DateValue): DateValue;
+/**
+ * Given a `DateValue` object, convert it to a native `Date` object.
+ * If a timezone is provided, the date will be converted to that timezone.
+ * If no timezone is provided, the date will be converted to the local timezone.
+ */
+export declare function toDate(dateValue: DateValue, tz?: string): Date;
+export declare function getDateValueType(date: DateValue): string;
+export declare function parseAnyDateValue(value: string, type: string): DateValue;
+export declare function isZonedDateTime(dateValue: DateValue | TimeValue): dateValue is ZonedDateTime;
+export declare function hasTime(dateValue: DateValue): dateValue is CalendarDateTime | ZonedDateTime;
+/**
+ * Given a date, return the number of days in the month.
+ */
+export declare function getDaysInMonth(date: Date | DateValue): number;
+/**
+ * Determine if a date is before the reference date.
+ * @param dateToCompare - is this date before the `referenceDate`
+ * @param referenceDate - is the `dateToCompare` before this date
+ *
+ * @see {@link isBeforeOrSame} for inclusive
+ */
+export declare function isBefore(dateToCompare: DateValue, referenceDate: DateValue): boolean;
+/**
+ * Determine if a date is after the reference date.
+ * @param dateToCompare - is this date after the `referenceDate`
+ * @param referenceDate - is the `dateToCompare` after this date
+ *
+ * @see {@link isAfterOrSame} for inclusive
+ */
+export declare function isAfter(dateToCompare: DateValue, referenceDate: DateValue): boolean;
+/**
+ * Determine if a date is inclusively between a start and end reference date.
+ *
+ * @param date - is this date inclusively between the `start` and `end` dates
+ * @param start - the start reference date to make the comparison against
+ * @param end - the end reference date to make the comparison against
+ *
+ * @see {@link isBetween} for non-inclusive
+ */
+export declare function isBetweenInclusive(date: DateValue, start: DateValue, end: DateValue): boolean;
+export declare function getLastFirstDayOfWeek<T extends DateValue = DateValue>(date: T, firstDayOfWeek: number, locale: string): T;
+export declare function getNextLastDayOfWeek<T extends DateValue = DateValue>(date: T, firstDayOfWeek: number, locale: string): T;
+export declare function areAllDaysBetweenValid(start: DateValue, end: DateValue, isUnavailable: DateMatcher | undefined, isDisabled: DateMatcher | undefined): boolean;
+export {};

package/dist/internal/debounce.d.ts

@@ -0,0 +1,4 @@
+export declare function debounce<T extends (...args: any[]) => any>(fn: T, wait?: number): {
+    (...args: Parameters<T>): void;
+    destroy(): void;
+};

package/dist/internal/dom.d.ts

@@ -0,0 +1,7 @@
+export declare function getFirstNonCommentChild(element: HTMLElement | null): ChildNode | null;
+/**
+ * Determines if the click event truly occurred outside the content node.
+ * This was added to handle password managers and other elements that may be injected
+ * into the DOM but visually appear inside the content.
+ */
+export declare function isClickTrulyOutside(event: PointerEvent, contentNode: HTMLElement): boolean;

package/dist/internal/elements.d.ts

@@ -0,0 +1,2 @@
+export declare function isOrContainsTarget(node: HTMLElement, target: Element): boolean;
+export declare function getOwnerDocument(el: Element | null | undefined): Document;

package/dist/internal/focus.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A target that can receive DOM focus. Mirrors the elements `HTMLElement.focus`
+ * / `SVGElement.focus` accept, used by the focus-management helpers.
+ */
+export type FocusableTarget = HTMLElement | SVGElement;

package/dist/internal/get-directional-keys.d.ts

@@ -0,0 +1,21 @@
+import { Direction, Orientation } from '..shared/index.js';
+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[];
+/**
+ * A utility function that returns the next key based on the direction and orientation.
+ */
+export declare function getNextKey(dir?: Direction, orientation?: Orientation): string;
+/**
+ * A utility function that returns the previous key based on the direction and orientation.
+ */
+export declare function getPrevKey(dir?: Direction, orientation?: Orientation): string;
+/**
+ * A utility function that returns the next and previous keys based on the direction
+ * and orientation.
+ */
+export declare function getDirectionalKeys(dir?: Direction, orientation?: Orientation): {
+    nextKey: string;
+    prevKey: string;
+};

package/dist/internal/is.d.ts

@@ -0,0 +1,25 @@
+import { FocusableTarget } from './focus.js';
+export declare const isBrowser: boolean;
+export declare const isIOS: boolean | "";
+export declare function isFunction(value: unknown): value is (...args: unknown[]) => unknown;
+export declare function isHTMLElement(element: unknown): element is HTMLElement;
+export declare function isElement(element: unknown): element is Element;
+export declare function isElementOrSVGElement(element: unknown): element is Element | SVGElement;
+export declare function isNumberString(value: string): boolean;
+export declare function isNull(value: unknown): value is null;
+export declare function isTouch(e: PointerEvent): boolean;
+export declare function isFocusVisible(element: Element): boolean;
+export declare function isNotNull<T>(value: T | null): value is T;
+/**
+ * Determines if the provided object is a valid `HTMLInputElement` with
+ * a `select` method available.
+ */
+export declare function isSelectableInput(element: unknown): element is FocusableTarget & {
+    select: () => void;
+};
+/**
+ * Given a node, determine if it is hidden by walking up the
+ * DOM tree until we hit the `stopAt` node (exclusive), if provided)
+ * otherwise we stop at the document root.
+ */
+export declare function isElementHidden(node: HTMLElement, stopAt?: HTMLElement): boolean;

package/dist/internal/kbd-constants.d.ts

@@ -0,0 +1,42 @@
+export declare const ALT = "Alt";
+export declare const ARROW_DOWN = "ArrowDown";
+export declare const ARROW_LEFT = "ArrowLeft";
+export declare const ARROW_RIGHT = "ArrowRight";
+export declare const ARROW_UP = "ArrowUp";
+export declare const BACKSPACE = "Backspace";
+export declare const CAPS_LOCK = "CapsLock";
+export declare const CONTROL = "Control";
+export declare const DELETE = "Delete";
+export declare const END = "End";
+export declare const ENTER = "Enter";
+export declare const ESCAPE = "Escape";
+export declare const F1 = "F1";
+export declare const F10 = "F10";
+export declare const F11 = "F11";
+export declare const F12 = "F12";
+export declare const F2 = "F2";
+export declare const F3 = "F3";
+export declare const F4 = "F4";
+export declare const F5 = "F5";
+export declare const F6 = "F6";
+export declare const F7 = "F7";
+export declare const F8 = "F8";
+export declare const F9 = "F9";
+export declare const HOME = "Home";
+export declare const META = "Meta";
+export declare const PAGE_DOWN = "PageDown";
+export declare const PAGE_UP = "PageUp";
+export declare const SHIFT = "Shift";
+export declare const SPACE = " ";
+export declare const TAB = "Tab";
+export declare const CTRL = "Control";
+export declare const ASTERISK = "*";
+export declare const a = "a";
+export declare const P = "P";
+export declare const A = "A";
+export declare const p = "p";
+export declare const n = "n";
+export declare const j = "j";
+export declare const k = "k";
+export declare const h = "h";
+export declare const l = "l";

package/dist/internal/kbd.d.ts

@@ -0,0 +1 @@
+export * as kbd from './kbd-constants.js';

package/dist/internal/locale.d.ts

@@ -0,0 +1,6 @@
+import { Direction } from '..shared/index.js';
+/**
+ * Detects the text direction in the element.
+ * @returns {Direction} The text direction ('ltr' for left-to-right or 'rtl' for right-to-left).
+ */
+export declare function getElemDirection(elem: HTMLElement): Direction;

package/dist/internal/math.d.ts

@@ -0,0 +1 @@
+export declare function linearScale(domain: [number, number], range: [number, number], clamp?: boolean): (x: number) => number;

package/dist/internal/noop.d.ts

@@ -0,0 +1,4 @@
+/**
+ * A no operation function (does nothing)
+ */
+export declare function noop(): void;

package/dist/internal/should-enable-focus-trap.d.ts

@@ -0,0 +1,4 @@
+export declare function shouldEnableFocusTrap({ forceMount, open, }: {
+    forceMount: boolean;
+    open: boolean;
+}): boolean;

package/dist/internal/types.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+/** Any function — used where the signature is irrelevant. */
+export type { AnyFn, Without } from '..types.js';
+/** A component's props plus the standard React `children`. */
+export type WithChildren<T = Record<never, never>> = T & {
+    children?: ReactNode;
+};
+/**
+ * A component's props plus an optional `child` render slot — the React analogue
+ * of the bits-ui `child` snippet, for headless "render your own element" APIs.
+ */
+export type WithChild<T = Record<never, never>> = T & {
+    child?: (props: Record<string, unknown>) => ReactNode;
+};

package/dist/internal/use-anchored-position.d.ts

@@ -0,0 +1,45 @@
+import { CSSProperties, RefObject } from 'react';
+/** A side, optionally refined by a cross-axis alignment (`bottom-start` …). */
+export type AnchoredPlacement = "top" | "bottom" | "left" | "right" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "left-start" | "left-end" | "right-start" | "right-end";
+/** Cross-axis alignment for a bare side (`placement: "bottom"` + `align: "end"`). */
+export type AnchoredAlign = "start" | "center" | "end";
+/** A pointer anchor (e.g. a context menu) — overrides the anchor element's rect. */
+export interface AnchoredPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Options for {@link useAnchoredPosition}.
+ */
+export interface UseAnchoredPositionOptions {
+    /** The placed side (+ optional compound alignment). Default `"bottom-start"`. */
+    placement?: AnchoredPlacement;
+    /** Cross-axis alignment when `placement` is a bare side. Default `"center"`. */
+    align?: AnchoredAlign;
+    /** A fixed float width (px). When set, overrides the measured width. */
+    width?: number;
+    /** Offset between the anchor and the float (px). Default `8`. */
+    gap?: number;
+    /** Viewport-edge clamp padding (px). Default `8`. */
+    padding?: number;
+    /** Recompute while open and track scroll/resize. Default open when omitted. */
+    open?: boolean;
+    /** Pointer anchor — overrides the anchor rect (context-menu case). */
+    point?: AnchoredPoint | null;
+}
+/** The return of {@link useAnchoredPosition}. */
+export interface UseAnchoredPositionReturn {
+    /** A `position: fixed` style to spread onto the float element. */
+    style: CSSProperties;
+    /** Force a recompute (e.g. after the float's content resizes). */
+    update: () => void;
+}
+/**
+ * Hand-rolled anchored positioning (no positioning dependency — §D). Places
+ * `floatRef` relative to `anchorRef` (or a pointer `point`) using `position:
+ * fixed` + `getBoundingClientRect`, so it escapes overflow/stacking contexts and
+ * pairs with the `<Portal>`. Recomputes on scroll/resize while open and clamps to
+ * the viewport. Supports every enum placement + the pointer case the overlay
+ * family needs. Guards the React-19 nullable refs.
+ */
+export declare function useAnchoredPosition(anchorRef: RefObject<HTMLElement | null>, floatRef: RefObject<HTMLElement | null>, options?: UseAnchoredPositionOptions): UseAnchoredPositionReturn;

package/dist/internal/use-arrow-navigation.d.ts

@@ -0,0 +1,62 @@
+import { Direction } from '..shared/index.js';
+type ArrowKeyOptions = "horizontal" | "vertical" | "both";
+interface ArrowNavigationOptions {
+    /**
+     * The arrow key options to allow navigation
+     *
+     * @defaultValue "both"
+     */
+    arrowKeyOptions?: ArrowKeyOptions;
+    /**
+     * The selector to find the collection items in the parent element.
+     */
+    candidateSelector: string;
+    /**
+     * The parent element where contains all the collection items, this will collect every item to be used when nav
+     * It will be ignored if attributeName is provided
+     *
+     * @defaultValue []
+     */
+    itemsArray?: HTMLElement[];
+    /**
+     * Allow loop navigation. If false, it will stop at the first and last element
+     *
+     * @defaultValue true
+     */
+    loop?: boolean;
+    /**
+     * The orientation of the collection
+     *
+     * @defaultValue "ltr"
+     */
+    dir?: Direction;
+    /**
+     * Prevent the scroll when navigating. This happens when the direction of the
+     * key matches the scroll direction of any ancestor scrollable elements.
+     *
+     * @defaultValue true
+     */
+    preventScroll?: boolean;
+    /**
+     * By default all currentElement would trigger navigation. If `true`, currentElement nodeName in the ignore list will return null
+     *
+     * @defaultValue false
+     */
+    enableIgnoredElement?: boolean;
+    /**
+     * Focus the element after navigation
+     *
+     * @defaultValue false
+     */
+    focus?: boolean;
+}
+/**
+ *
+ * @param e               Keyboard event
+ * @param currentElement  Event initiator element or any element that wants to handle the navigation
+ * @param parentElement   Parent element where contains all the collection items, this will collect every item to be used when nav
+ * @param options         further options
+ * @returns               the navigated html element or null if none
+ */
+export declare function useArrowNavigation(e: KeyboardEvent, currentElement: HTMLElement, parentElement: HTMLElement | undefined, options: ArrowNavigationOptions): HTMLElement | null;
+export {};

package/dist/internal/use-dismiss.d.ts

@@ -0,0 +1,31 @@
+import { RefObject } from 'react';
+/**
+ * Options for {@link useDismiss}.
+ */
+export interface UseDismissOptions {
+    /** Called when an outside press or `Escape` requests dismissal. */
+    onDismiss: () => void;
+    /** Dismiss on a press outside `ref`. Default `true`. `AlertDialog` opts out. */
+    outsideClick?: boolean;
+    /** Dismiss on `Escape`. Default `true`. */
+    escapeKey?: boolean;
+    /**
+     * Elements whose presses do NOT count as outside — typically the trigger /
+     * anchor, so re-pressing it toggles rather than double-firing dismiss + open.
+     */
+    ignore?: ReadonlyArray<RefObject<HTMLElement | null> | null>;
+    /** Gate the whole hook — a closed overlay ignores `Escape`/outside. Default `true`. */
+    enabled?: boolean;
+}
+/**
+ * The one true outside-press + `Escape` dismiss effect, replacing the overlays'
+ * inline copies. Subscribes once while `enabled` and reads the latest options at
+ * event time, so `outsideClick`/`escapeKey`/`onDismiss` may change without churn.
+ *
+ * Uses `pointerdown` (mouse + touch + pen, before `click`) and composes
+ * `dom.isClickTrulyOutside`: a press dismisses only when it lands outside the
+ * DOM subtree AND outside the content's box (the latter guards password-manager
+ * overlays injected outside the tree but visually within). Guards the React-19
+ * nullable `ref.current`.
+ */
+export declare function useDismiss(ref: RefObject<HTMLElement | null>, options: UseDismissOptions): void;

package/dist/internal/use-focus-trap.d.ts

@@ -0,0 +1,31 @@
+import { RefObject } from 'react';
+import { FocusableTarget } from './focus.js';
+/**
+ * Options for {@link useFocusTrap}.
+ */
+export interface UseFocusTrapOptions {
+    /** While `true`, `Tab`/`Shift+Tab` cycle within `ref`'s focusable descendants. */
+    active: boolean;
+    /**
+     * Where focus returns on deactivate — the trigger. Accepts a ref or a direct
+     * element. When omitted, focus returns to whatever held it when the trap engaged.
+     */
+    returnFocusTo?: RefObject<FocusableTarget | null> | FocusableTarget | null;
+    /**
+     * The element to focus first on engage (e.g. an alert dialog's confirm action).
+     * When omitted, focus moves to the first focusable descendant, else the container.
+     */
+    initialFocus?: RefObject<FocusableTarget | null> | null;
+    /** Composes `shouldEnableFocusTrap` — a portal that stays mounted while closed. */
+    forceMount?: boolean;
+}
+/**
+ * Headless focus trap + focus return. While `active`, keyboard focus is confined
+ * to `ref`'s focusable descendants (Tab wraps last→first, Shift+Tab first→last,
+ * and focus that escapes is pulled back); on deactivate, focus returns to
+ * `returnFocusTo` (or the element that held focus when the trap engaged).
+ *
+ * JSX/portal-free — the `<Portal>` wrapper lives in `@mercury-fx/ui`. Guards the
+ * React-19 nullable `ref.current`.
+ */
+export declare function useFocusTrap(ref: RefObject<HTMLElement | null>, { active, returnFocusTo, initialFocus, forceMount }: UseFocusTrapOptions): void;

package/dist/internal/use-id.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generates a process-unique id with the given prefix. Despite the name this is
+ * NOT a React hook — it's a plain monotonic counter (base36), safe to call from
+ * anywhere a stable, collision-free id is needed.
+ */
+export declare function useId(prefix?: string): string;

package/dist/internal/warn.d.ts

@@ -0,0 +1 @@
+export declare function warn(...messages: string[]): void;