@actview/floating-ui 0.1.0

package/dist/hooks/useClick.d.ts

@@ -0,0 +1,45 @@
+import type { ElementProps, FloatingRootContext } from '../types';
+export interface UseClickProps {
+    /**
+     * Whether the Hook is enabled, including all internal Effects and event
+     * handlers.
+     * @default true
+     */
+    enabled?: boolean | undefined;
+    /**
+     * The type of event to use to determine a “click” with mouse input.
+     * Keyboard clicks work as normal.
+     * @default 'click'
+     */
+    event?: 'click' | 'mousedown' | undefined;
+    /**
+     * Whether to toggle the open state with repeated clicks.
+     * @default true
+     */
+    toggle?: boolean | undefined;
+    /**
+     * Whether to ignore the logic for mouse input (for example, if `useHover()`
+     * is also being used).
+     * @default false
+     */
+    ignoreMouse?: boolean | undefined;
+    /**
+     * Whether to add keyboard handlers (Enter and Space key functionality) for
+     * non-button elements (to open/close the floating element via keyboard
+     * “click”).
+     * @default true
+     */
+    keyboardHandlers?: boolean | undefined;
+    /**
+     * If already open from another event such as the `useHover()` Hook,
+     * determines whether to keep the floating element open when clicking the
+     * reference element for the first time.
+     * @default true
+     */
+    stickIfOpen?: boolean | undefined;
+}
+/**
+ * Opens or closes the floating element when clicking the reference element.
+ * @see https://floating-ui.com/docs/useClick
+ */
+export declare function useClick(context: FloatingRootContext, props?: UseClickProps): ElementProps;

package/dist/hooks/useClientPoint.d.ts

@@ -0,0 +1,32 @@
+import type { ElementProps, FloatingRootContext } from '../types';
+export interface UseClientPointProps {
+    /**
+     * Whether the Hook is enabled, including all internal Effects and event
+     * handlers.
+     * @default true
+     */
+    enabled?: boolean | undefined;
+    /**
+     * Whether to restrict the client point to an axis and use the reference
+     * element (if it exists) as the other axis. This can be useful if the
+     * floating element is also interactive.
+     * @default 'both'
+     */
+    axis?: 'x' | 'y' | 'both' | undefined;
+    /**
+     * An explicitly defined `x` client coordinate.
+     * @default null
+     */
+    x?: number | null | undefined;
+    /**
+     * An explicitly defined `y` client coordinate.
+     * @default null
+     */
+    y?: number | null | undefined;
+}
+/**
+ * Positions the floating element relative to a client point (in the viewport),
+ * such as the mouse position. By default, it follows the mouse cursor.
+ * @see https://floating-ui.com/docs/useClientPoint
+ */
+export declare function useClientPoint(context: FloatingRootContext, props?: UseClientPointProps): ElementProps;

package/dist/hooks/useDismiss.d.ts

@@ -0,0 +1,80 @@
+import type { ElementProps, FloatingRootContext } from '../types';
+export declare const normalizeProp: (normalizable?: boolean | {
+    escapeKey?: boolean | undefined;
+    outsidePress?: boolean | undefined;
+}) => {
+    escapeKey: boolean;
+    outsidePress: boolean;
+};
+export interface UseDismissProps {
+    /**
+     * Whether the Hook is enabled, including all internal Effects and event
+     * handlers.
+     * @default true
+     */
+    enabled?: boolean | undefined;
+    /**
+     * Whether to dismiss the floating element upon pressing the `esc` key.
+     * @default true
+     */
+    escapeKey?: boolean | undefined;
+    /**
+     * Whether to dismiss the floating element upon pressing the reference
+     * element. You likely want to ensure the `move` option in the `useHover()`
+     * Hook has been disabled when this is in use.
+     * @default false
+     */
+    referencePress?: boolean | undefined;
+    /**
+     * The type of event to use to determine a “press”.
+     * - `pointerdown` is eager on both mouse + touch input.
+     * - `mousedown` is eager on mouse input, but lazy on touch input.
+     * - `click` is lazy on both mouse + touch input.
+     * @default 'pointerdown'
+     */
+    referencePressEvent?: 'pointerdown' | 'mousedown' | 'click' | undefined;
+    /**
+     * Whether to dismiss the floating element upon pressing outside of the
+     * floating element.
+     * If you have another element, like a toast, that is rendered outside the
+     * floating element’s React tree and don’t want the floating element to close
+     * when pressing it, you can guard the check like so:
+     * ```jsx
+     * useDismiss(context, {
+     *   outsidePress: (event) => !event.target.closest('.toast'),
+     * });
+     * ```
+     * @default true
+     */
+    outsidePress?: boolean | ((event: MouseEvent) => boolean) | undefined;
+    /**
+     * The type of event to use to determine an outside “press”.
+     * - `pointerdown` is eager on both mouse + touch input.
+     * - `mousedown` is eager on mouse input, but lazy on touch input.
+     * - `click` is lazy on both mouse + touch input.
+     * @default 'pointerdown'
+     */
+    outsidePressEvent?: 'pointerdown' | 'mousedown' | 'click' | undefined;
+    /**
+     * Whether to dismiss the floating element upon scrolling an overflow
+     * ancestor.
+     * @default false
+     */
+    ancestorScroll?: boolean | undefined;
+    /**
+     * Determines whether event listeners bubble upwards through a tree of
+     * floating elements.
+     */
+    bubbles?: boolean | {
+        escapeKey?: boolean | undefined;
+        outsidePress?: boolean | undefined;
+    } | undefined;
+    /**
+     * Determines whether to use capture phase event listeners.
+     */
+    capture?: boolean | {
+        escapeKey?: boolean | undefined;
+        outsidePress?: boolean | undefined;
+    } | undefined;
+}
+export declare function useDismiss(context: FloatingRootContext, props?: UseDismissProps): ElementProps;

package/dist/hooks/useFloating.d.ts

@@ -0,0 +1,18 @@
+import type { ReferenceType, UseFloatingOptions, UseFloatingReturn } from '../types';
+/**
+ * actview 版（upstream 为 @floating-ui/react 的 useFloating）。
+ *
+ * 与 upstream 的差异：
+ * - 定位核心直接调用 `@floating-ui/dom` 的 computePosition（actview 版
+ *   `src/useFloating.ts`，无 @floating-ui/react-dom 依赖）
+ * - `React.useState` → `ref()`；`useModernLayoutEffect` → `watch`
+ * - `computedElements`（rootContext.elements）字段为 `Ref` → `.value` /
+ *   直接传 Ref 给定位核心（内部 toValue）
+ * - `nodeId` 支持 `string | Ref<string | undefined>`（toValue 读取）
+ * - 无 React 合成事件 / useCallback / useMemo
+ */
+/**
+ * Provides data to position a floating element and context to add interactions.
+ * @see https://floating-ui.com/docs/useFloating
+ */
+export declare function useFloating<RT extends ReferenceType = ReferenceType>({ elements: elementsOption, ...options }?: UseFloatingOptions<RT>): UseFloatingReturn<RT>;

package/dist/hooks/useFloatingRootContext.d.ts

@@ -0,0 +1,22 @@
+import { type Ref } from '@actview/core';
+import type { FloatingRootContext, OpenChangeReason } from '../types';
+/**
+ * actview 版（upstream 为 React hook）。
+ *
+ * 与 upstream 的差异：
+ * - `React.useRef` → `ref()`；`React.useState` → `ref()` / 直接创建
+ * - `open` 为 `computed(() => toValue(options.open) ?? false)`——options.open
+ *   支持 boolean 或 `Ref<boolean>`（useFloating 传 Ref 时响应式追踪）
+ * - `elements` 字段为 `Ref`（reference / domReference 用 computed 派生，
+ *   floating 固定为首次值——elementsProp 在 setup 解构固定）
+ * - `useEffectEvent` 从 `../utils` 导入
+ */
+export interface UseFloatingRootContextOptions {
+    open?: boolean | Ref<boolean> | undefined;
+    onOpenChange?: ((open: boolean, event?: Event, reason?: OpenChangeReason) => void) | undefined;
+    elements: {
+        reference: Element | null;
+        floating: HTMLElement | null;
+    };
+}
+export declare function useFloatingRootContext(options: UseFloatingRootContextOptions): FloatingRootContext;

package/dist/hooks/useFocus.d.ts

@@ -0,0 +1,21 @@
+import type { ElementProps, FloatingRootContext } from '../types';
+export interface UseFocusProps {
+    /**
+     * Whether the Hook is enabled, including all internal Effects and event
+     * handlers.
+     * @default true
+     */
+    enabled?: boolean | undefined;
+    /**
+     * Whether the open state only changes if the focus event is considered
+     * visible (`:focus-visible` CSS selector).
+     * @default true
+     */
+    visibleOnly?: boolean | undefined;
+}
+/**
+ * Opens the floating element while the reference element has focus, like CSS
+ * `:focus`.
+ * @see https://floating-ui.com/docs/useFocus
+ */
+export declare function useFocus(context: FloatingRootContext, props?: UseFocusProps): ElementProps;

package/dist/hooks/useHover.d.ts

@@ -0,0 +1,57 @@
+import type { Delay, ElementProps, FloatingContext, FloatingRootContext, FloatingTreeType, SafePolygonOptions } from '../types';
+export interface HandleCloseContext extends Omit<FloatingContext, 'x' | 'y'> {
+    onClose: () => void;
+    tree?: FloatingTreeType | null | undefined;
+    leave?: boolean | undefined;
+    x: number;
+    y: number;
+}
+export interface HandleClose {
+    (context: HandleCloseContext): (event: MouseEvent) => void;
+    __options?: SafePolygonOptions | undefined;
+}
+export declare function getDelay(value: UseHoverProps['delay'], prop: 'open' | 'close', pointerType?: PointerEvent['pointerType']): number | undefined;
+export interface UseHoverProps {
+    /**
+     * Whether the Hook is enabled, including all internal Effects and event
+     * handlers.
+     * @default true
+     */
+    enabled?: boolean | undefined;
+    /**
+     * Accepts an event handler that runs on `mousemove` to control when the
+     * floating element closes once the cursor leaves the reference element.
+     * @default null
+     */
+    handleClose?: HandleClose | null | undefined;
+    /**
+     * Waits until the user’s cursor is at “rest” over the reference element
+     * before changing the `open` state.
+     * @default 0
+     */
+    restMs?: number | (() => number) | undefined;
+    /**
+     * Waits for the specified time when the event listener runs before changing
+     * the `open` state.
+     * @default 0
+     */
+    delay?: Delay | (() => Delay) | undefined;
+    /**
+     * Whether the logic only runs for mouse input, ignoring touch input.
+     * Note: due to a bug with Linux Chrome, "pen" inputs are considered "mouse".
+     * @default false
+     */
+    mouseOnly?: boolean | undefined;
+    /**
+     * Whether moving the cursor over the floating element will open it, without a
+     * regular hover event required.
+     * @default true
+     */
+    move?: boolean | undefined;
+}
+/**
+ * Opens the floating element while hovering over the reference element, like
+ * CSS `:hover`.
+ * @see https://floating-ui.com/docs/useHover
+ */
+export declare function useHover(context: FloatingRootContext, props?: UseHoverProps): ElementProps;

package/dist/hooks/useId.d.ts

@@ -0,0 +1,11 @@
+import { type Ref } from '@actview/core';
+/**
+ * Returns a stable unique id for the floating element.
+ * @see https://floating-ui.com/docs/react-utils#useid
+ *
+ * actview 为客户端渲染（无 hydration 匹配需求），id 在 setup 同步生成，
+ * 保证父组件的 nodeId 在子组件挂载前就绪（FloatingNode 的 value.id /
+ * useFloatingParentNodeId 依赖它；延迟到 onMounted 会让嵌套 FloatingTree
+ * 判断读到 null，产生双 FloatingTree）。
+ */
+export declare function useId(): Ref<string | undefined>;

package/dist/hooks/useInteractions.d.ts

@@ -0,0 +1,13 @@
+import type { ElementProps, ExtendedUserProps } from '../types';
+export interface UseInteractionsReturn {
+    getReferenceProps: (userProps?: Record<string, unknown>) => Record<string, unknown>;
+    getFloatingProps: (userProps?: Record<string, unknown>) => Record<string, unknown>;
+    getItemProps: (userProps?: Omit<Record<string, unknown>, 'selected' | 'active'> & ExtendedUserProps) => Record<string, unknown>;
+}
+/**
+ * Merges an array of interaction hooks' props into prop getters, allowing
+ * event handler functions to be composed together without overwriting one
+ * another.
+ * @see https://floating-ui.com/docs/useInteractions
+ */
+export declare function useInteractions(propsList?: Array<ElementProps | void>): UseInteractionsReturn;

package/dist/hooks/useListNavigation.d.ts

@@ -0,0 +1,176 @@
+import { type Ref } from '@actview/core';
+import type { Dimensions, ElementProps, FloatingRootContext } from '../types';
+import { gridNavigation } from './gridNavigation';
+/**
+ * actview 版（upstream 为 React hook）。
+ *
+ * 与 upstream 的差异：
+ * - `React.useRef` → `ref()`；`React.useState` → `ref()`（activeId / virtualId）
+ * - `useModernLayoutEffect` → `watch`（依赖追踪；previous* 状态同步放在
+ *   最后注册的 watch，保持"读上次值"语义）
+ * - `activeIndex` / `selectedIndex` 接受 `Ref<number | null> | number | null`，
+ *   内部用 `toValue` 统一读取（传 Ref 时 watch 响应式同步）
+ * - reference / floating 为 `computed`（响应式 aria 派生），mergeProps 用
+ *   `unref` 解包；`floatingFocusElement` / `typeableComboboxReference` 也用
+ *   computed（floating / domReference 挂载后才非空）
+ * - `virtualItemRef` 为 `Ref<HTMLElement | null>`（.value）
+ * - 无 React 合成事件：`event.nativeEvent` → 直接传 `event`；
+ *   `event.currentTarget` 为 `EventTarget | null`（断言为 HTMLElement）
+ * - `tree.nodesRef.current` → `.value`；`deepestNode.context.elements.*` → `.value`
+ * - props 标量在 setup 解构固定
+ */
+export declare const ESCAPE = "Escape";
+export interface UseListNavigationProps {
+    /**
+     * A ref that holds an array of list items.
+     * @default empty list
+     */
+    listRef: Ref<Array<HTMLElement | null>>;
+    /**
+     * The index of the currently active (focused or highlighted) item, which may
+     * or may not be selected.
+     * @default null
+     */
+    activeIndex: Ref<number | null> | number | null;
+    /**
+     * A callback that is called when the user navigates to a new active item,
+     * passed in a new `activeIndex`.
+     */
+    onNavigate?: ((activeIndex: number | null) => void) | undefined;
+    /**
+     * Whether the Hook is enabled, including all internal Effects and event
+     * handlers.
+     * @default true
+     */
+    enabled?: boolean | undefined;
+    /**
+     * The currently selected item index, which may or may not be active.
+     * @default null
+     */
+    selectedIndex?: Ref<number | null> | number | null | undefined;
+    /**
+     * Whether to focus the item upon opening the floating element. 'auto' infers
+     * what to do based on the input type (keyboard vs. pointer), while a boolean
+     * value will force the value.
+     * @default 'auto'
+     */
+    focusItemOnOpen?: boolean | 'auto' | undefined;
+    /**
+     * Whether hovering an item synchronizes the focus.
+     * @default true
+     */
+    focusItemOnHover?: boolean | undefined;
+    /**
+     * Whether pressing an arrow key on the navigation’s main axis opens the
+     * floating element.
+     * @default true
+     */
+    openOnArrowKeyDown?: boolean | undefined;
+    /**
+     * By default elements with either a `disabled` or `aria-disabled` attribute
+     * are skipped in the list navigation — however, this requires the items to
+     * be rendered.
+     * This prop allows you to manually specify indices which should be disabled,
+     * overriding the default logic.
+     * For Windows-style select menus, where the menu does not open when
+     * navigating via arrow keys, specify an empty array.
+     * @default undefined
+     */
+    disabledIndices?: Array<number> | ((index: number) => boolean) | undefined;
+    /**
+     * Determines whether focus can escape the list, such that nothing is selected
+     * after navigating beyond the boundary of the list. In some
+     * autocomplete/combobox components, this may be desired, as screen
+     * readers will return to the input.
+     * `loop` must be `true`.
+     * @default false
+     */
+    allowEscape?: boolean | undefined;
+    /**
+     * Determines whether focus should loop around when navigating past the first
+     * or last item.
+     * @default false
+     */
+    loop?: boolean | undefined;
+    /**
+     * If the list is nested within another one (e.g. a nested submenu), the
+     * navigation semantics change.
+     * @default false
+     */
+    nested?: boolean | undefined;
+    /**
+     * Allows to specify the orientation of the parent list, which is used to
+     * determine the direction of the navigation.
+     * This is useful when list navigation is used within a Composite,
+     * as the hook can't determine the orientation of the parent list automatically.
+     */
+    parentOrientation?: UseListNavigationProps['orientation'] | undefined;
+    /**
+     * Whether the direction of the floating element’s navigation is in RTL
+     * layout.
+     * @default false
+     */
+    rtl?: boolean | undefined;
+    /**
+     * Whether the focus is virtual (using `aria-activedescendant`).
+     * Use this if you need focus to remain on the reference element
+     * (such as an input), but allow arrow keys to navigate list items.
+     * This is common in autocomplete listbox components.
+     * Your virtually-focused list items must have a unique `id` set on them.
+     * If you’re using a component role with the `useRole()` Hook, then an `id` is
+     * generated automatically.
+     * @default false
+     */
+    virtual?: boolean | undefined;
+    /**
+     * The orientation in which navigation occurs.
+     * @default 'vertical'
+     */
+    orientation?: 'vertical' | 'horizontal' | 'both' | undefined;
+    /**
+     * Specifies how many columns the list has (i.e., it’s a grid). Use an
+     * orientation of 'horizontal' (e.g. for an emoji picker/date picker, where
+     * pressing ArrowRight or ArrowLeft can change rows), or 'both' (where the
+     * current row cannot be escaped with ArrowRight or ArrowLeft, only ArrowUp
+     * and ArrowDown).
+     * @default 1
+     */
+    cols?: number | undefined;
+    /**
+     * base-ui 变体：注入式网格导航（grid-capable consumers 传入）。
+     * 替代上游 `cols` 的单元格映射，支持 DOM 行结构检测（`role="row"`）、
+     * 虚拟化间隙与部分行回退。传入后优先于 `cols` 生效。
+     * 位置参数签名与 `gridNavigation` 锁定（经 `typeof`）。
+     */
+    grid?: typeof gridNavigation | null | undefined;
+    /**
+     * Whether to scroll the active item into view when navigating. The default
+     * value uses nearest options.
+     */
+    scrollItemIntoView?: boolean | ScrollIntoViewOptions | undefined;
+    /**
+     * When using virtual focus management, this holds a ref to the
+     * virtually-focused item. This allows nested virtual navigation to be
+     * enabled, and lets you know when a nested element is virtually focused from
+     * the root reference handling the events. Requires `FloatingTree` to be
+     * setup.
+     */
+    virtualItemRef?: Ref<HTMLElement | null> | undefined;
+    /**
+     * Only for `cols > 1`, specify sizes for grid items.
+     * `{ width: 2, height: 2 }` means an item is 2 columns wide and 2 rows tall.
+     */
+    itemSizes?: Dimensions[] | undefined;
+    /**
+     * Only relevant for `cols > 1` and items with different sizes, specify if
+     * the grid is dense (as defined in the CSS spec for `grid-auto-flow`).
+     * @default false
+     */
+    dense?: boolean | undefined;
+}
+/**
+ * Adds arrow key-based navigation of a list of items, either using real DOM
+ * focus or virtual focus.
+ * @see https://floating-ui.com/docs/useListNavigation
+ */
+export declare function useListNavigation(context: FloatingRootContext, props: UseListNavigationProps): ElementProps;

package/dist/hooks/useMergeRefs.d.ts

@@ -0,0 +1,20 @@
+import { type Ref } from '@actview/core';
+/**
+ * actview 版（upstream 为 React hook：useRef/useCallback/useMemo 缓存 + ref cleanup）。
+ *
+ * 与 upstream 的差异：
+ * - 对象 ref 为 actview 框架类型 `Ref<T>`（.value，非 React 的 .current）
+ * - 无 useMemo/useCallback：每次调用返回新闭包，需要稳定引用的调用方自行缓存
+ *   （如在 setup 中调用一次）
+ * - React 18 的 ref cleanup 由合并函数自行管理：函数 ref 的返回值（cleanup）
+ *   在下次调用同位置 ref 前执行（React 语义：先 cleanup 再 ref 新值）；
+ *   卸载（value 为 null）且存在 cleanup 时只调 cleanup、不调 ref(null)
+ *   （对齐 React 的 commitDetachRef：有 cleanup 的 ref 卸载时不再收到 null）
+ */
+type MergeableRef<Instance> = ((instance: Instance | null) => void | (() => void)) | Ref<Instance | null>;
+/**
+ * Merges an array of refs into a single callback ref or `null`.
+ * @see https://floating-ui.com/docs/react-utils#usemergerefs
+ */
+export declare function useMergeRefs<Instance>(refs: Array<MergeableRef<Instance> | undefined>): null | ((instance: Instance | null) => void);
+export {};

package/dist/hooks/useRole.d.ts

@@ -0,0 +1,33 @@
+import type { ElementProps, FloatingRootContext } from '../types';
+/**
+ * actview 版（upstream 为 React hook）。
+ *
+ * 与 upstream 的差异：
+ * - reference / floating 为 `computed`（响应式派生：open / floatingId / referenceId
+ *   变化时重建），mergeProps 用 `unref` 解包
+ * - item 为普通函数（闭包读 `floatingId.value`，每次调用取最新值）
+ * - `useId` 返回 `Ref<string | undefined>`（.value）
+ * - props 标量（enabled / role）在 setup 解构固定
+ */
+type AriaRole = 'tooltip' | 'dialog' | 'alertdialog' | 'menu' | 'listbox' | 'grid' | 'tree';
+type ComponentRole = 'select' | 'label' | 'combobox';
+export interface UseRoleProps {
+    /**
+     * Whether the Hook is enabled, including all internal Effects and event
+     * handlers.
+     * @default true
+     */
+    enabled?: boolean | undefined;
+    /**
+     * The role of the floating element.
+     * @default 'dialog'
+     */
+    role?: AriaRole | ComponentRole | undefined;
+}
+/**
+ * Adds base screen reader props to the reference and floating elements for a
+ * given floating element `role`.
+ * @see https://floating-ui.com/docs/useRole
+ */
+export declare function useRole(context: FloatingRootContext, props?: UseRoleProps): ElementProps;
+export {};

package/dist/hooks/useTransition.d.ts

@@ -0,0 +1,68 @@
+import { type Ref } from '@actview/core';
+import type { FloatingContext, Placement, ReferenceType, Side } from '../types';
+/**
+ * actview 版（upstream 为 React hook）。
+ *
+ * 与 upstream 的差异：
+ * - `React.useState` → `ref()`；状态机（status / isMounted / styles）返回 `Ref<T>`，
+ *   调用方渲染期读 `.value`
+ * - `React.useEffect` / `useModernLayoutEffect` → `watch`（依赖追踪 + immediate）
+ * - 无 ReactDOM.flushSync：rAF 回调里直接赋值，actview 自行调度渲染
+ * - `useLatestRef` 从 `../utils` 导入
+ * - `React.CSSProperties` → `Record<string, string | number>`（actview 样式对象）
+ */
+type Duration = number | {
+    open?: number | undefined;
+    close?: number | undefined;
+};
+export interface UseTransitionStatusProps {
+    /**
+     * The duration of the transition in milliseconds, or an object containing
+     * `open` and `close` keys for different durations.
+     */
+    duration?: Duration | undefined;
+}
+type TransitionStatus = 'unmounted' | 'initial' | 'open' | 'close';
+/**
+ * Provides a status string to apply CSS transitions to a floating element,
+ * correctly handling placement-aware transitions.
+ * @see https://floating-ui.com/docs/useTransition#usetransitionstatus
+ */
+export declare function useTransitionStatus(context: FloatingContext, props?: UseTransitionStatusProps): {
+    isMounted: Ref<boolean>;
+    status: Ref<TransitionStatus>;
+};
+type CSSStylesProperty = Record<string, string | number> | ((params: {
+    side: Side;
+    placement: Placement;
+}) => Record<string, string | number>);
+export interface UseTransitionStylesProps extends UseTransitionStatusProps {
+    /**
+     * The styles to apply when the floating element is initially mounted.
+     */
+    initial?: CSSStylesProperty | undefined;
+    /**
+     * The styles to apply when the floating element is transitioning to the
+     * `open` state.
+     */
+    open?: CSSStylesProperty | undefined;
+    /**
+     * The styles to apply when the floating element is transitioning to the
+     * `close` state.
+     */
+    close?: CSSStylesProperty | undefined;
+    /**
+     * The styles to apply to all states.
+     */
+    common?: CSSStylesProperty | undefined;
+}
+/**
+ * Provides styles to apply CSS transitions to a floating element, correctly
+ * handling placement-aware transitions. Wrapper around `useTransitionStatus`.
+ * @see https://floating-ui.com/docs/useTransition#usetransitionstyles
+ */
+export declare function useTransitionStyles<RT extends ReferenceType = ReferenceType>(context: FloatingContext<RT>, props?: UseTransitionStylesProps): {
+    isMounted: Ref<boolean>;
+    styles: Ref<Record<string, string | number>>;
+};
+export {};

package/dist/hooks/useTypeahead.d.ts

@@ -0,0 +1,66 @@
+import { type Ref } from '@actview/core';
+import type { ElementProps, FloatingRootContext } from '../types';
+/**
+ * actview 版（upstream 为 React hook）。
+ *
+ * 与 upstream 的差异：
+ * - `React.useRef` → `ref()`；`useModernLayoutEffect` → `watch`
+ * - `activeIndex` / `selectedIndex` 接受 `Ref<number | null> | number | null`，
+ *   内部用 `toValue` 统一读取（传入 Ref 时 watch 响应式同步 prevIndexRef）
+ * - `listRef` 为 `Ref<Array<string | null>>`（.value）
+ * - 无 React 合成事件：onKeyDown 参数为原生 KeyboardEvent
+ * - `useEffectEvent` / `useLatestRef` / `stopEvent` 从 `../utils` 导入
+ */
+export interface UseTypeaheadProps {
+    /**
+     * A ref which contains an array of strings whose indices match the HTML
+     * elements of the list.
+     * @default empty list
+     */
+    listRef: Ref<Array<string | null>>;
+    /**
+     * The index of the active (focused or highlighted) item in the list.
+     * @default null
+     */
+    activeIndex: Ref<number | null> | number | null;
+    /**
+     * Callback invoked with the matching index if found as the user types.
+     */
+    onMatch?: ((index: number) => void) | undefined;
+    /**
+     * Callback invoked with the typing state as the user types.
+     */
+    onTypingChange?: ((isTyping: boolean) => void) | undefined;
+    /**
+     * Whether the Hook is enabled, including all internal Effects and event
+     * handlers.
+     * @default true
+     */
+    enabled?: boolean | undefined;
+    /**
+     * A function that returns the matching string from the list.
+     * @default lowercase-finder
+     */
+    findMatch?: null | ((list: Array<string | null>, typedString: string) => string | null | undefined) | undefined;
+    /**
+     * The number of milliseconds to wait before resetting the typed string.
+     * @default 750
+     */
+    resetMs?: number | undefined;
+    /**
+     * An array of keys to ignore when typing.
+     * @default []
+     */
+    ignoreKeys?: Array<string> | undefined;
+    /**
+     * The index of the selected item in the list, if available.
+     * @default null
+     */
+    selectedIndex?: Ref<number | null> | number | null | undefined;
+}
+/**
+ * Provides a matching callback that can be used to focus an item as the user
+ * types, often used in tandem with `useListNavigation()`.
+ * @see https://floating-ui.com/docs/useTypeahead
+ */
+export declare function useTypeahead(context: FloatingRootContext, props: UseTypeaheadProps): ElementProps;