haze-ui 1.26.0 → 1.28.0

package/dist/types/headless/index.d.ts

@@ -0,0 +1,399 @@
+/**
+ * `haze-ui/headless` — the behavior layer the haze-ui components are built
+ * on, curated for authors assembling their own components: floating-panel
+ * positioning (native popover + anchor positioning with graceful fallback
+ * tiers), exit-animation presence, focus trapping, tab-order queries,
+ * pure collision geometry, menu/submenu keyboard machinery, RTL direction
+ * resolution, ref composition, View-Transition-wrapped state flips, and
+ * the document-level interaction hooks (click-outside, hotkeys, in-view,
+ * media queries) plus the storage-persisted state hooks. Same source,
+ * same version, same design tokens as the `haze-ui` component library —
+ * the general-purpose hooks and direction helpers are also exported from
+ * the main entry; this module gathers the whole behavior layer under one
+ * import.
+ *
+ * Stable public API: this module carries the same semver commitment as
+ * the `haze-ui` component library — breaking changes land only on a
+ * major version. The primitives still evolve alongside the library's
+ * own components, within that contract.
+ */
+import { useClickOutside } from '../hooks/useClickOutside';
+import { hotkey, useHotkeys } from '../hooks/useHotkeys';
+import { useInView } from '../hooks/useInView';
+import { useLocalStorage } from '../hooks/useLocalStorage';
+import { useMediaQuery } from '../hooks/useMediaQuery';
+import { usePrevious } from '../hooks/usePrevious';
+import { useSessionStorage } from '../hooks/useSessionStorage';
+import { computeFloatingPosition, resolvePadding } from '../utils/collision';
+import { getDirection, localeDirection, useDirection } from '../utils/direction';
+import { FloatingPanel, floatingPlacementClasses, placeFloatingPanel, supportsAnchorPositioning, supportsNativePopover, useFloating, useFloatingPosition } from '../utils/floating';
+import { focusFirst, getTabbables, isTabbable, TABBABLE_SELECTOR } from '../utils/focus';
+import { useFocusScope } from '../utils/focus-scope';
+import { getEnabledMenuItems, useMenuKeyboard, useRovingTabindex } from '../utils/menuKeyboard';
+import { Presence, whenExitSettles } from '../utils/presence';
+import { mergeRefs } from '../utils/refs';
+import { SUBMENU_CLOSE_GRACE_MS, SUBMENU_OPEN_DELAY_MS, SubmenuProvider, useSubmenu, useSubmenuContext } from '../utils/submenu';
+import { useViewTransitionFlip } from '../utils/view-transition';
+/**
+ * Detects the native Popover API (`popover` attribute, top layer,
+ * light-dismiss). The floating primitives use this to choose their
+ * rendering tier.
+ */
+export { supportsNativePopover };
+/**
+ * Detects CSS anchor positioning on top of the native Popover API. The
+ * floating primitives use this to choose between the declarative anchored
+ * tier and JS-assisted positioning.
+ */
+export { supportsAnchorPositioning };
+/**
+ * The floating-pair behavior hook: pass the open state pair plus trigger
+ * and panel refs, receive a `FloatingBehavior` record describing the
+ * engine tier and everything to spread on the trigger and panel. This is
+ * the same engine Popover, DropdownMenu, Combobox, Datepicker and Tooltip
+ * run on.
+ */
+export { useFloating };
+/**
+ * Options accepted by {@link useFloating}: the open state pair, trigger
+ * and panel refs, plus optional animation and collision knobs.
+ */
+export type UseFloatingOptions = Parameters<typeof useFloating>[0];
+/**
+ * Behavior record returned by {@link useFloating}: tier flags, lifecycle
+ * phases (`shown`/`dataState`/`exited`), and the props/class entries to
+ * spread on the trigger and panel elements.
+ */
+export type { FloatingBehavior } from '../utils/floating';
+/**
+ * Panel placement relative to the trigger (`'bottom' | 'bottom-span' |
+ * 'bottom-center' | 'bottom-end' | 'top' | 'left' | 'right'`, or
+ * `'point'` to position the panel yourself, e.g. at pointer coordinates).
+ * Logical, not physical: under `dir="rtl"` the horizontal placements and
+ * the start/end alignments mirror automatically.
+ */
+export type { FloatingPlacement } from '../utils/floating';
+/**
+ * x-class entries placing a panel element relative to its trigger, per
+ * engine tier — for consumers composing their own panel instead of using
+ * {@link FloatingPanel}.
+ */
+export { floatingPlacementClasses };
+/**
+ * Imperatively place a fixed panel from the trigger's rect (the
+ * JS-positioned tier). Re-run on scroll/resize — or use
+ * {@link useFloatingPosition}, which wires that up.
+ */
+export { placeFloatingPanel };
+/**
+ * Hook that keeps a floating panel positioned on the JS-assisted tiers:
+ * tier-2 fixed placement and the tier-1 cross-axis nudge, re-run on
+ * scroll and resize.
+ */
+export { useFloatingPosition };
+/**
+ * The panel half of a floating pair: applies the popover attribute, the
+ * anchor custom property and the tier/placement classes, mirrors the
+ * animated lifecycle as `data-state`, and runs the JS-assisted position
+ * effect. Your visual skin goes in `visualClass`; everything else passes
+ * through to the underlying div.
+ */
+export { FloatingPanel };
+/**
+ * Props accepted by {@link FloatingPanel} — behavior record, optional
+ * placement/collision overrides, `visualClass` skin, plus native div
+ * attributes.
+ */
+export type FloatingPanelProps = Parameters<typeof FloatingPanel>[0];
+/**
+ * Keeps a single child mounted while its exit animation runs: the child
+ * receives `data-state="open" | "closed"` (render your enter/exit
+ * transitions on it) and unmounts only after the exit settles. This is
+ * the engine behind haze-ui's animated panels, modals and collapsibles.
+ */
+export { Presence };
+/**
+ * Props accepted by {@link Presence}: `present`, a single-element
+ * `children`, and an optional `onExited` callback.
+ */
+export type { PresenceProps } from '../utils/presence';
+/**
+ * Wait for an element's exit animation/transition to finish. Resolves
+ * immediately when no positive duration is declared, `null` for an
+ * element outside the document; repeated calls share the in-flight
+ * settle. The imperative companion to {@link Presence}.
+ */
+export { whenExitSettles };
+/**
+ * Focus-domain hook for overlays: attach the returned ref callback to a
+ * container and flip `enabled` to get initial focus, focus restoration
+ * and optional Tab trapping — a simplified Radix-style FocusScope with
+ * no CSS dependency.
+ */
+export { useFocusScope };
+/**
+ * Options accepted by {@link useFocusScope}: `enabled`, `trapped`,
+ * `autoFocus`, `returnFocus`, and the mount/unmount auto-focus event
+ * callbacks (preventable via `event.preventDefault()`).
+ */
+export type { FocusScopeOptions } from '../utils/focus-scope';
+/**
+ * Tab-order candidate selector (structural filter only; runtime state —
+ * disabled, hidden, visibility — is filtered by {@link isTabbable}).
+ */
+export { TABBABLE_SELECTOR };
+/**
+ * Whether an element is in the Tab order: matches
+ * {@link TABBABLE_SELECTOR} and is not disabled, hidden or invisible.
+ */
+export { isTabbable };
+/**
+ * All tabbable elements inside a container, in DOM order (the container
+ * itself excluded).
+ */
+export { getTabbables };
+/**
+ * Focus the first tabbable element in a container, or the container
+ * itself when none exists. Returns whether focus actually transferred —
+ * guarding against `focus()` silently no-op-ing on disabled or detached
+ * elements.
+ */
+export { focusFirst };
+/**
+ * Pure floating-panel collision math over literal rects — no DOM, no
+ * React: baseline coordinates, then flip on the primary axis, shift on
+ * the cross axis, primary-axis clamp. The deterministic core of the
+ * JS-positioned tiers.
+ */
+export { computeFloatingPosition };
+/**
+ * Arguments accepted by {@link computeFloatingPosition}: trigger rect,
+ * panel and viewport sizes, placement, per-direction gap, and the
+ * resolved strategy record.
+ */
+export type ComputeFloatingPositionOptions = Parameters<typeof computeFloatingPosition>[0];
+/**
+ * Position resolved by {@link computeFloatingPosition}: panel `top`/
+ * `left` and the (possibly flipped) placement side.
+ */
+export type FloatingPosition = ReturnType<typeof computeFloatingPosition>;
+/**
+ * Normalize a {@link CollisionPadding} into a full per-side record — the
+ * padding shape {@link computeFloatingPosition}'s strategy expects.
+ */
+export { resolvePadding };
+/**
+ * Viewport edge a collision measurement applies to.
+ */
+export type { CollisionSide } from '../utils/collision';
+/**
+ * Viewport inset for collision checks: a number applies to all four
+ * sides, an object per side.
+ */
+export type { CollisionPadding } from '../utils/collision';
+/**
+ * Collision knobs: `flip` to the opposite side and `shift` along the
+ * cross axis when the panel overflows the padded viewport (both default
+ * on), plus `collisionPadding`. Consumers may pass any subset.
+ */
+export type { CollisionStrategy } from '../utils/collision';
+/**
+ * Enabled menu items inside a container, in DOM order. `role="menu"`
+ * containers scope each item to its nearest menu ancestor, so a nested
+ * submenu's items belong to their own level — the same query the
+ * haze-ui menu families' traversal, typeahead and roving tabindex run
+ * on. The item selector is customizable for non-menu containers
+ * (listboxes, command palettes).
+ */
+export { getEnabledMenuItems };
+/**
+ * Keyboard behavior for a roving-tabindex item container (WAI-ARIA menu
+ * button pattern): the orientation's main-axis arrows move focus
+ * wrapping and skipping disabled items (mirrored under `dir="rtl"` for
+ * horizontal layouts), Home/End jump to the ends, Escape and Tab close,
+ * printable characters run typeahead. Returns the `onKeyDown` handler
+ * to spread on the container — the engine DropdownMenu, ContextMenu and
+ * Command run on.
+ */
+export { useMenuKeyboard };
+/**
+ * Options accepted by {@link useMenuKeyboard}: the container ref, the
+ * close callback, an optional custom item selector, the submenu-level
+ * `onCloseToStart` callback and the layout `orientation`.
+ */
+export type UseMenuKeyboardOptions = Parameters<typeof useMenuKeyboard>[0];
+/**
+ * Roving tabindex for a menu/listbox container: exactly one item is a
+ * tab stop at any time — kept on activation, moved with focus, and
+ * re-synced by a MutationObserver when the item set changes (e.g. a
+ * filtered list). While `active` is false the effect is inert.
+ */
+export { useRovingTabindex };
+/**
+ * Options accepted by {@link useRovingTabindex}: the container ref, the
+ * `active` flag and an optional custom item selector.
+ */
+export type UseRovingTabindexOptions = Parameters<typeof useRovingTabindex>[0];
+/**
+ * The nested-submenu mechanism behind `MenuSub*` / `DropdownMenuSub*`:
+ * owns the open state (controllable through the `open` option), drives
+ * the floating pair, wires hover intent (rest-delayed open, graceful
+ * close) and the level-scoped keyboard contract — the inline-end arrow
+ * opens focusing the first item, Escape and the inline-start arrow
+ * close only this level, Tab closes the whole stack. Returns the
+ * behavior record the family components skin.
+ */
+export { useSubmenu };
+/**
+ * Options accepted by {@link useSubmenu}: the `open` state (controlled
+ * control or uncontrolled initial value) and `onOpenChange`, fired on
+ * every open transition whatever drove it.
+ */
+export type UseSubmenuOptions = Parameters<typeof useSubmenu>[0];
+/**
+ * Behavior record returned by {@link useSubmenu}: the open state, the
+ * trigger/content refs, the panel id, the floating behavior, and the
+ * handlers to spread on the trigger (`onPointerEnter`, `onKeyDown`)
+ * and the panel (`onKeyDown`).
+ */
+export type { SubmenuBehavior } from '../utils/submenu';
+/**
+ * Context provider carrying a {@link SubmenuBehavior} from a Sub
+ * container to its trigger/content parts — for authors composing their
+ * own submenu skins. Nesting works naturally: each Sub re-provides for
+ * its own parts.
+ */
+export { SubmenuProvider };
+/**
+ * Read the nearest {@link SubmenuBehavior} provided by an enclosing
+ * {@link SubmenuProvider}. Throws outside one.
+ */
+export { useSubmenuContext };
+/**
+ * Pointer rest time before a submenu opens on hover (intent, not
+ * rest), in milliseconds.
+ */
+export { SUBMENU_OPEN_DELAY_MS };
+/**
+ * Grace before a hover-opened submenu closes after the pointer settled
+ * outside it, in milliseconds.
+ */
+export { SUBMENU_CLOSE_GRACE_MS };
+/**
+ * Writing direction of a subtree: `'ltr'` or `'rtl'`.
+ */
+export type { Direction } from '../utils/direction';
+/**
+ * Direction implied by a BCP 47 tag — RTL primary language subtags
+ * (`ar`, `fa`, `he`, `ur`, …) resolve to `'rtl'`, everything else to
+ * `'ltr'`; `undefined` when no tag is given.
+ */
+export { localeDirection };
+/**
+ * Rendered direction of an element: the nearest ancestor carrying a
+ * `dir` attribute, `'ltr'` when none does. The layout truth that
+ * arrow-key mirroring and JS placement math must follow — read it at
+ * event/measure time, never from React state.
+ */
+export { getDirection };
+/**
+ * Declared direction for the current tree: the LocaleProvider chain's
+ * explicit `direction` prop or locale-derived direction, falling back
+ * to the document's rendered direction when no provider is mounted.
+ * Prefer {@link getDirection} on the concrete element whenever the
+ * value must match the painted layout.
+ */
+export { useDirection };
+/**
+ * Compose several refs (object and/or callback) into one callback ref —
+ * the pattern for merging a behavior record's `triggerRef`/`panelRef`
+ * with your own element handle on the same node.
+ */
+export { mergeRefs };
+/**
+ * Wrap a boolean open-state flip in a View Transition — the same outlet
+ * the Dialog/Drawer/BottomSheet `viewTransition` prop runs on. Every
+ * write executes inside `document.startViewTransition(() =>
+ * flushSync(...))`; the full guard chain (disabled,
+ * `prefers-reduced-motion: reduce`, unsupported engine) degrades to a
+ * direct write. Pass the flag and the `useControl` setter, and use the
+ * returned writer wherever the state flips.
+ */
+export { useViewTransitionFlip };
+/**
+ * Call back on `pointerdown` outside an element: attach the returned
+ * stable callback ref to the target, optionally ignore refs (e.g. the
+ * trigger), and toggle `enabled` with the panel's open state so a
+ * closed overlay costs no listener. Shadow-DOM retargeted clicks are
+ * attributed correctly via `event.composedPath()`.
+ */
+export { useClickOutside };
+/**
+ * Options accepted by {@link useClickOutside}: `enabled` (default
+ * `true`) and the `ignore` ref list — elements whose hits do not count
+ * as outside.
+ */
+export type { UseClickOutsideOptions } from '../hooks/useClickOutside';
+/**
+ * Declarative keyboard shortcuts: a map of spec strings (`'mod+k'`,
+ * `'ctrl+shift+p'`, `'?'`, named keys) to handlers, listened on the
+ * window (or a ref target). `mod` normalizes per platform (⌘ on macOS,
+ * Ctrl elsewhere), editable focus suppresses fires unless
+ * `allowInInput`, and the map may be an inline literal — a latest-ref
+ * keeps the listener mounted once.
+ */
+export { useHotkeys };
+/**
+ * Combine several hotkey specs into one comma-joined alias binding so
+ * a single handler catches any of them:
+ * `useHotkeys({ [hotkey('mod+k', 'mod+j')]: cycle })`.
+ */
+export { hotkey };
+/**
+ * Handler signature {@link useHotkeys} calls with the raw KeyboardEvent
+ * (already `preventDefault`-ed and stopped when it fires).
+ */
+export type { HotkeyHandler } from '../hooks/useHotkeys';
+/**
+ * Options accepted by {@link useHotkeys}: `enabled`, `target` (element
+ * ref or `window`), `eventName` and `allowInInput`.
+ */
+export type { UseHotkeysOptions } from '../hooks/useHotkeys';
+/**
+ * Observe whether an element is in the viewport: attach the returned
+ * callback ref and read the `inView` flag. `once: true` freezes after
+ * the first intersection (lazy-load style); engines without
+ * IntersectionObserver (SSR, jsdom) stay `false` without throwing.
+ */
+export { useInView };
+/**
+ * Options accepted by {@link useInView}: the IntersectionObserver init
+ * members plus the `once` freeze flag.
+ */
+export type { UseInViewOptions } from '../hooks/useInView';
+/**
+ * Subscribe to a CSS media query and return whether it currently
+ * matches; the query can change per render. SSR and hydration snapshots
+ * are `false` (no `window` access), and engines without `matchMedia`
+ * get a stable `false` instead of a throw.
+ */
+export { useMediaQuery };
+/**
+ * The value from the previous render; `undefined` on the first.
+ * Compared by identity per render — no deep equality.
+ */
+export { usePrevious };
+/**
+ * localStorage-persisted controllable state: initial-value resolution
+ * is persisted value > uncontrolled prop > `initial`, uncontrolled
+ * writes persist as JSON, cross-tab updates arrive via `storage`
+ * events, and a controlled `control` stays the single source of truth
+ * (no write-back). Unavailable storage (private mode) degrades
+ * silently to in-memory state.
+ */
+export { useLocalStorage };
+/**
+ * sessionStorage-persisted controllable state — exactly the semantics
+ * of {@link useLocalStorage}, scoped to the tab session.
+ */
+export { useSessionStorage };

package/dist/types/hooks/index.d.ts

@@ -1,7 +1,20 @@
 export { useClipboard } from './useClipboard';
 export type { UseClipboardResult } from './useClipboard';
+export { useClickOutside } from './useClickOutside';
+export type { UseClickOutsideOptions } from './useClickOutside';
+export { useDarkMode } from './useDarkMode';
+export type { ColorMode, UseDarkModeOptions, UseDarkModeResult } from './useDarkMode';
 export { useDebouncedCallback } from './useDebouncedCallback';
 export { useDebouncedValue } from './useDebouncedValue';
+export { useFullscreen } from './useFullscreen';
+export type { FullscreenTarget, UseFullscreenHandle } from './useFullscreen';
+export { useHotkeys, hotkey } from './useHotkeys';
+export type { HotkeyHandler, UseHotkeysOptions } from './useHotkeys';
+export { useInView } from './useInView';
+export type { UseInViewOptions } from './useInView';
+export { useLocalStorage } from './useLocalStorage';
 export { useMediaQuery } from './useMediaQuery';
 export { usePrefersReducedMotion } from './usePrefersReducedMotion';
+export { usePrevious } from './usePrevious';
+export { useSessionStorage } from './useSessionStorage';
 export { useTitle } from './useTitle';

package/dist/types/hooks/useClickOutside.d.ts

@@ -0,0 +1,46 @@
+import type { RefCallback, RefObject } from 'react';
+type UseClickOutsideOptions = {
+    /**
+     * 是否启用监听。默认 `true`；`false` 时不绑定任何事件（浮层关闭态
+     * 常用，省一次全局监听）。
+     */
+    enabled?: boolean;
+    /**
+     * 命中「外部」也要忽略的元素列表（如浮层的 trigger——点 trigger 走
+     * 它自己的开合逻辑，不应同时触发 onOutside）。传 RefObject，元素
+     * 可晚于监听建立。
+     */
+    ignore?: (RefObject<Element | null>)[];
+};
+/**
+ * 元素外部指针按下回调（document 级 `pointerdown` 监听封装）。
+ *
+ * ```tsx
+ * function Panel() {
+ *   const [open, setOpen] = useState(false);
+ *   const triggerRef = useRef<HTMLButtonElement>(null);
+ *   const panelRef = useClickOutside<HTMLDivElement>(
+ *     () => setOpen(false),
+ *     {enabled: open, ignore: [triggerRef]}
+ *   );
+ *   return <>
+ *     <button ref={triggerRef} onClick={() => setOpen(!open)}>…</button>
+ *     {open && <div ref={panelRef}>…</div>}
+ *   </>;
+ * }
+ * ```
+ *
+ * - 返回稳定回调 ref：挂到目标元素上即可，挂载/卸载自动建立/断开监听。
+ * - 用 `event.composedPath()` 判定内外：shadow DOM 的 retarget 点击能
+ *   正确归属到宿主元素。
+ * - 注意 React portal 不是 shadow DOM：portal 到别处的 DOM 点击按
+ *   真实 DOM 树判定为「外部」。portal 面板场景请把返回的 ref 挂到
+ *   portal 容器上，或把 portal 根加进 `ignore`。
+ * - `enabled: false` 时不监听（关闭中的浮层零开销）。
+ *
+ * @param onOutside 目标元素与 ignore 元素之外发生 pointerdown 时调用。
+ * @param options 见 {@link UseClickOutsideOptions}。
+ * @returns 挂到目标元素上的回调 ref。
+ */
+export declare function useClickOutside<T extends Element>(onOutside: (event: PointerEvent) => void, options?: UseClickOutsideOptions): RefCallback<T>;
+export type { UseClickOutsideOptions };

package/dist/types/hooks/useDarkMode.d.ts

@@ -0,0 +1,40 @@
+import type { Dispatch, RefObject, SetStateAction } from 'react';
+/**
+ * useDarkMode：零成本暗色切换。
+ *
+ * - 状态源是 `useLocalStorage`（`useControl` 内核）：`mode` 持久化到
+ *   localStorage（默认 key `haze-ui-color-mode`），跨标签页经 storage
+ *   事件同步；`isDark` 由 `mode` 派生——`'system'` 时跟随
+ *   `prefers-color-scheme`（复用 useMediaQuery 的无 matchMedia 守卫）。
+ * - 副作用是在目标元素（默认 `document.documentElement`）上切换
+ *   `lightTheme` / `darkTheme` 两个 token 类——始终恰好挂其一，其余
+ *   className 不受影响。卸载不摘类：主题是页面级事实，摘类只会闪白。
+ * - SSR：渲染期不碰 `document`；effect 不执行，无 DOM 也可安全渲染。
+ *   storage / matchMedia 缺失时静默降级为纯内存状态（内核既有行为）。
+ *
+ * ```tsx
+ * const [isDark, setIsDark, mode, setMode] = useDarkMode();
+ * setIsDark(true);   // 等价 setMode('dark')，写入 localStorage
+ * setMode('system'); // 重新跟随系统偏好
+ * ```
+ */
+type ColorMode = 'light' | 'dark' | 'system';
+type UseDarkModeOptions = {
+    /** localStorage 持久化键，默认 `'haze-ui-color-mode'`。 */
+    storageKey?: string;
+    /**
+     * 挂主题类的目标元素，接受元素本身或 ref（ref 在 effect 期读取，
+     * 同组件渲染的元素此时已挂载）。默认 `document.documentElement`。
+     */
+    target?: RefObject<HTMLElement | null> | HTMLElement;
+    /** 无持久化值时的兜底模式，默认 `'system'`。 */
+    defaultMode?: ColorMode;
+};
+type UseDarkModeResult = [
+    isDark: boolean,
+    setIsDark: Dispatch<SetStateAction<boolean>>,
+    mode: ColorMode,
+    setMode: Dispatch<SetStateAction<ColorMode>>
+];
+export declare function useDarkMode(options?: UseDarkModeOptions): UseDarkModeResult;
+export type { ColorMode, UseDarkModeOptions, UseDarkModeResult };

package/dist/types/hooks/useFullscreen.d.ts

@@ -0,0 +1,33 @@
+import type { RefObject } from 'react';
+/** A fullscreen target: the element itself or a ref holding it. */
+export type FullscreenTarget = HTMLElement | RefObject<HTMLElement | null>;
+export type UseFullscreenHandle = {
+    /** Whether the target element is currently fullscreen. */
+    readonly isFullscreen: boolean;
+    /** Request fullscreen for the target; a no-op when the API is missing. */
+    enter: () => void;
+    /** Exit fullscreen when the target is the fullscreen element. */
+    exit: () => void;
+    /** Enter or exit based on what the document currently shows. */
+    toggle: () => void;
+};
+/**
+ * Track and drive the Fullscreen API for `target` (an element or a ref;
+ * defaults to `document.documentElement`).
+ *
+ * ```tsx
+ * const boxRef = useRef<HTMLDivElement>(null);
+ * const [isFullscreen, toggle] = useFullscreen(boxRef);
+ * <button onClick={toggle}>{isFullscreen ? 'Exit' : 'Enter'} fullscreen</button>
+ * ```
+ *
+ * State mirrors `fullscreenchange`: entering/exiting through any path
+ * (toggle, another component, the browser's Esc) updates `isFullscreen` —
+ * only when the fullscreen element is *this* target. Engines without the
+ * Fullscreen API (jsdom, iOS Safari) degrade to a permanent `false` and
+ * no-op commands instead of throwing.
+ *
+ * @returns `[isFullscreen, toggle, handle]` — the third element bundles the
+ * same commands with `isFullscreen` for stable-effect consumers.
+ */
+export declare function useFullscreen(target?: FullscreenTarget): [boolean, () => void, UseFullscreenHandle];

package/dist/types/hooks/useHotkeys.d.ts

@@ -0,0 +1,53 @@
+import type { RefObject } from 'react';
+/** 快捷键命中时收到原始 KeyboardEvent。 */
+export type HotkeyHandler = (event: KeyboardEvent) => void;
+type UseHotkeysOptions = {
+    /** `false` 时不挂载任何监听（默认 `true`）。 */
+    enabled?: boolean;
+    /** 监听目标：元素 ref 或 `window`（默认 `window`，随冒泡捕获全局按键）。 */
+    target?: RefObject<HTMLElement | null> | Window;
+    /** 监听的键盘事件类型（默认 `'keydown'`）。 */
+    eventName?: 'keydown' | 'keyup';
+    /** 焦点在 input/textarea/select/contenteditable 内时是否仍触发（默认 `false`）。 */
+    allowInInput?: boolean;
+};
+/**
+ * 组合多个快捷键规格为一条别名绑定（逗号连接），任一命中即触发同一
+ * handler——对象字面量的键只能是字符串，数组规格经由本函数进入。
+ *
+ * ```tsx
+ * useHotkeys({ [hotkey('mod+k', 'mod+j')]: cyclePalette });
+ * ```
+ *
+ * @param specs 至少一个规格，如 `'mod+k'`、`'ctrl+shift+p'`。
+ */
+export declare function hotkey(...specs: [string, ...string[]]): string;
+/**
+ * 声明式键盘快捷键。映射的键为规格字符串，值为处理器；命中时默认
+ * `preventDefault + stopPropagation`，处理器收到原始事件可追加处理。
+ *
+ * ```tsx
+ * useHotkeys({
+ *   'mod+k': openCommandPalette,          // macOS ⌘K / 其它 Ctrl+K
+ *   'ctrl+shift+p': openCommandPalette,
+ *   '?': showHelp,                        // 符号键天然携带 shift，无需声明
+ *   ArrowUp: selectPrev,                  // 命名键精确匹配
+ *   [hotkey('mod+k', 'mod+j')]: cycle,     // 多规格别名：任一命中
+ * }, { allowInInput: false });
+ * ```
+ *
+ * - 规格语法：`[修饰键+]*键`；修饰键别名 mod/ctrl/control/meta/cmd/⌘/
+ *   shift/alt/option/⌥；`mod` 按平台归一（macOS ⌘，否则 ctrl，
+ *   `navigator.platform` 判定，SSR 安全）。
+ * - 默认焦点在 input/textarea/select/contenteditable 时忽略全部快捷键，
+ *   `allowInInput: true` 打开。
+ * - 一个事件只触发第一个命中的绑定；`hotkeys` 映射每次渲染变化不重挂
+ *   监听（latest-ref），`enabled/target/eventName/allowInInput` 变化才
+ *   重新绑定。
+ * - `enabled: false` 等价于不挂载监听。
+ *
+ * @param hotkeys 规格（或逗号连接的规格列表）到处理器的映射。
+ * @param options 监听行为配置。
+ */
+export declare function useHotkeys(hotkeys: Record<string, HotkeyHandler>, options?: UseHotkeysOptions): void;
+export type { UseHotkeysOptions };

package/dist/types/hooks/useInView.d.ts

@@ -0,0 +1,32 @@
+import type { RefCallback } from 'react';
+type UseInViewOptions = IntersectionObserverInit & {
+    /**
+     * 命中一次后冻结为 `true` 并断开观察——适用于「进入视口才加载/上报」
+     * 这类一次性场景。默认 `false`（持续跟随进出视口切换）。
+     */
+    once?: boolean;
+};
+/**
+ * 观察元素是否进入视口（IntersectionObserver 的 ref 回调封装）。
+ *
+ * ```tsx
+ * function LazyImage() {
+ *   const [ref, inView] = useInView<HTMLImageElement>({ once: true });
+ *   // 进入视口前不发起请求；once 命中后冻结，不再重复观察
+ *   return <img ref={ref} src={inView ? '/real.png' : undefined} alt='' />;
+ * }
+ * ```
+ *
+ * - 返回 `[refCallback, inView]`：把回调 ref 挂到目标元素上即可，元素
+ *   挂载/卸载自动建立/断开观察；`options` 变化（root/rootMargin/threshold）
+ *   会重建 observer。
+ * - `once: true`：首次 `isIntersecting` 置 `true` 后 disconnect 并冻结，
+ *   后续进出视口不再翻转。
+ * - 引擎无 IntersectionObserver（SSR、jsdom）：恒返回 `false`、不抛错、
+ *   不建立观察。
+ *
+ * @param options IntersectionObserver 初始化项 + `once`。
+ * @returns `[refCallback, inView]`。
+ */
+export declare function useInView<T extends Element>(options?: UseInViewOptions): [RefCallback<T>, boolean];
+export type { UseInViewOptions };

package/dist/types/hooks/useLocalStorage.d.ts

@@ -0,0 +1,33 @@
+import type { Dispatch, SetStateAction } from 'react';
+import type { ControlOrValue } from 'react-use-control';
+/**
+ * localStorage 持久化的可控状态（`useControl` 作内核，storage 是持久化
+ * 副作用而非替代状态源）。
+ *
+ * ```tsx
+ * // 非受控：初值 'light'，已持久化值优先；setValue 即写回 localStorage
+ * const [theme, setTheme] = useLocalStorage<string>('theme', undefined, 'light');
+ * setTheme('dark'); // localStorage.theme === '"dark"'
+ *
+ * // 受控：control 所有者持有状态，storage 只作初值来源、不回写
+ * const [theme, setTheme, themeControl] = useControl(undefined, 'light');
+ * <ThemeSwitcher theme={themeControl} onThemeChange={setTheme} />
+ * ```
+ *
+ * - 初值解析顺序（惰性，仅首次挂载求值）：已持久化值 > 非受控裸值 >
+ *   `initial`。损坏的 JSON 回落初始值，并在下一次变更时自愈回合法 JSON。
+ * - 非受控：任何变更（含首挂载）即 `JSON.stringify` 写入；跨标签页通过
+ *   `storage` 事件同步（同 key 多实例同标签页不要求同步——storage 事件
+ *   不触发同页文档）。
+ * - 受控：不持久化、不订阅 storage 事件——`control` 的所有者是真值来源，
+ *   避免双写冲突。
+ * - SSR：服务端渲染不访问 `window`，恒返回 `initial`；客户端水合后如与
+ *   本地持久化值不同，会以一次重渲收敛（storage 类状态的固有特性）。
+ * - 隐私模式 / storage 不可用：读写静默降级为纯内存状态。
+ *
+ * @param key storage 键。
+ * @param control `Control<T>` 受控，或裸 `T` 作非受控初值。
+ * @param initial 兜底初始值（支持惰性函数形式）。
+ * @returns `[value, setValue]`，语义与 `useState` 一致。
+ */
+export declare function useLocalStorage<T>(key: string, control?: ControlOrValue<T>, initial?: T | (() => T)): [T, Dispatch<SetStateAction<T>>];

package/dist/types/hooks/useMediaQuery.d.ts

@@ -10,6 +10,9 @@
  * - SSR：服务端渲染与 hydration 首帧恒返回 `false`（不访问
  *   `window`、不建立订阅）；水合后与真实结果不一致时以一次额外
  *   渲染收敛，无 hydration mismatch。
+ * - 引擎无 `matchMedia`（jsdom 等测试环境）：快照恒 `false`、不建立
+ *   订阅——消费方（如 usePrefersReducedMotion → View Transitions）
+ *   在这类环境下拿到「未匹配」的稳定值而不是 throw。
  *
  * @param query CSS 媒体查询字符串，如 `'(min-width: 768px)'`。
  * @returns 当前是否匹配（SSR 阶段恒为 `false`）。