haze-ui 1.30.0 → 1.32.0

package/dist/types/components/TagGroup/TagGroup.d.ts

@@ -1,10 +1,32 @@
 import type { ReactNode } from 'react';
+/** Item-level slot classes flow group → item without prop drilling.
+ * Default `undefined` — the same as no slot classes set anywhere. */
+declare const TagGroupItemClassNamesContext: import("react").Context<TagGroupClassNames | undefined>;
+/**
+ * Semantic slot classes for TagGroup (AntD v6 `classNames` shape; keys
+ * follow the data-slot names). `item`/`removeButton` forward onto every
+ * TagGroupItem child through context, so row-level skins are set once
+ * on the group. A ConfigProvider `TagGroup.classNames` section merges
+ * under the prop, per key.
+ */
+type TagGroupClassNames = {
+    /** The group wrapper (data-slot='tag-group'). */
+    root?: string;
+    /** Every item's chip span (data-slot='tag-group-item'). */
+    item?: string;
+    /** Every item's remove button (data-slot='remove-button'). */
+    removeButton?: string;
+};
 type TagGroupProps = {
     children: ReactNode;
     className?: string;
+    /** Slot classes (see {@link TagGroupClassNames}); item-level keys are
+     * inherited by the TagGroupItem children. */
+    classNames?: TagGroupClassNames;
 };
 /** Plain non-draggable tag row. For drag-and-drop reordering use
  * SortableTagGroup (which statically imports the @dnd-kit runtime);
  * this base component stays free of the dnd runtime. */
-export default function TagGroup({ children, className }: TagGroupProps): import("react").JSX.Element;
-export type { TagGroupProps };
+export default function TagGroup({ children, className, classNames }: TagGroupProps): import("react").JSX.Element;
+export { TagGroupItemClassNamesContext };
+export type { TagGroupClassNames, TagGroupProps };

package/dist/types/components/TagGroup/index.d.ts

@@ -1,6 +1,6 @@
 export { default as TagGroup } from './TagGroup';
 export { default as TagGroupItem } from './TagGroupItem';
 export { default as SortableTagGroup } from './SortableTagGroup';
-export type { TagGroupProps } from './TagGroup';
+export type { TagGroupClassNames, TagGroupProps } from './TagGroup';
 export type { TagGroupItemProps } from './TagGroupItem';
 export type { SortableTagGroupProps } from './SortableTagGroup';

package/dist/types/components/Toast/index.d.ts

@@ -3,5 +3,5 @@ export type { ToastProps, ToastClassNames } from './Toast';
 export { default as ToastContainer } from './ToastContainer';
 export type { ToastContainerProps } from './ToastContainer';
 export { default as useToast } from './useToast';
-export { toast } from './toast';
-export type { ToastAction, ToastOptions, ToastVariant } from './toast';
+export { toast } from './toast-channel';
+export type { ToastAction, ToastOptions, ToastVariant } from './toast-channel';

package/dist/types/components/Toast/useToast.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { ToastOptions, ToastPromiseOptions, ToastUpdateOptions, ToastVariantOptions } from './toast';
+import type { ToastOptions, ToastPromiseOptions, ToastUpdateOptions, ToastVariantOptions } from './toast-channel';
 /**
  * The `useToast()` return value: the toast trigger itself (returns the id,
  * usable with `update`) plus `loading`/`update`/`promise` — one-to-one

package/dist/types/components/VirtualList/VirtualList.d.ts

@@ -109,6 +109,25 @@ type VirtualListProps<T> = {
      * rows along the scroll axis, and columns in grid mode.
      */
     overscan?: number;
+    /**
+     * Fired when the scroll offset comes within `endReachedThreshold` px of
+     * the content's end along the scroll axis — the infinite-scroll "load
+     * the next page" trigger. Entering the zone fires once; staying inside
+     * it does not re-fire; scrolling back out re-arms, and content growth
+     * (a longer `items` array) re-arms too, so a list that is still short
+     * after a page load chains straight into the next one. Content shorter
+     * than the scrollport on mount fires immediately. In `reverse` mode the
+     * end edge mirrors to the scroll start (index 0 anchors to the end
+     * edge): the trigger fires as the *oldest* edge approaches. When the
+     * prop is omitted the check costs nothing.
+     */
+    onEndReached?: () => void;
+    /**
+     * Distance in px from the content end that arms `onEndReached`.
+     * Defaults to `200`. Measured along the scroll axis from the far edge
+     * of the scroll range (in `reverse` mode, from the scroll start).
+     */
+    endReachedThreshold?: number;
     /**
      * Chat orientation (opt-in): units anchor to the scrollport's end edge
      * (vertical: bottom; horizontal: inline-end) with index 0 at that edge
@@ -128,5 +147,5 @@ type VirtualListProps<T> = {
     className?: string;
     ref?: Ref<VirtualListHandle>;
 } & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
-export default function VirtualList<T>({ items, height, width, itemHeight, estimatedItemHeight, columns, columnWidth, orientation, groups, renderItem, overscan, reverse, className, style, ref, ...rest }: VirtualListProps<T>): import("react").JSX.Element;
+export default function VirtualList<T>({ items, height, width, itemHeight, estimatedItemHeight, columns, columnWidth, orientation, groups, renderItem, overscan, onEndReached, endReachedThreshold, reverse, className, style, ref, ...rest }: VirtualListProps<T>): import("react").JSX.Element;
 export type { VirtualListProps, VirtualListHandle, VirtualListGroup, VirtualListAlign, VirtualListOrientation, };

package/dist/types/components/VisuallyHidden/VisuallyHidden.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentPropsWithoutRef } from 'react';
+type VisuallyHiddenProps = ComponentPropsWithoutRef<'span'>;
+export default function VisuallyHidden({ className, ...rest }: VisuallyHiddenProps): import("react").JSX.Element;
+export type { VisuallyHiddenProps };

package/dist/types/components/VisuallyHidden/index.d.ts

@@ -0,0 +1,2 @@
+export { default as VisuallyHidden } from './VisuallyHidden';
+export type { VisuallyHiddenProps } from './VisuallyHidden';

package/dist/types/components/Workbench/Workbench.d.ts

@@ -0,0 +1,50 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ControlOrValue } from 'react-use-control';
+type WorkbenchProps = {
+    /** Narrow icon rail column on the leading edge (ActivityRail is the intended content). */
+    activityBar?: ReactNode;
+    /** Where the activity rail docks: its own column (`'side'`, the
+     *  default) or inside the sidebar column at its top (`'top'`)
+     *  or bottom (`'bottom'`) — the Cursor-style layout, where the
+     *  rail rides the sidebar as one unit. */
+    activityBarPosition?: ControlOrValue<'side' | 'top' | 'bottom'>;
+    /** Docked explorer column beside the editor; under the mobile breakpoint
+     *  it becomes a full-screen slide-out overlay dismissed via Escape, with
+     *  focus moved in on open and returned to the opener on close. */
+    sidebar?: ReactNode;
+    /** Docked secondary column on the trailing edge; overlays like the sidebar on mobile. */
+    auxiliaryBar?: ReactNode;
+    /** Bottom tool region inside the main column (terminal/output); hidden on mobile. */
+    panel?: ReactNode;
+    /** Full-width strip under the middle row (StatusBar is the intended content). */
+    statusBar?: ReactNode;
+    /** Bottom navigation slot, rendered only under the mobile breakpoint where the activity bar is hidden. */
+    tabBar?: ReactNode;
+    /** Expanded sidebar width in px; a Control tracks handle drags live. */
+    sidebarWidth?: ControlOrValue<number>;
+    /** Sidebar collapsed state — desktop hides the column, mobile closes the overlay. */
+    sidebarCollapsed?: ControlOrValue<boolean>;
+    /**
+     * Mobile sidebar overlay, in full-viewport form. Under the
+     * mobile breakpoint this control owns the slide-out (the
+     * docked `sidebarCollapsed` semantics are desktop-only
+     * there); above the breakpoint it is inert. Defaults to
+     * false — the mobile sidebar starts hidden and a consumer's
+     * button (typically in `tabBar`, which only exists on
+     * mobile) opens it.
+     */
+    mobileSidebarOpen?: ControlOrValue<boolean>;
+    /** Expanded auxiliary bar width in px; a Control tracks handle drags live. */
+    auxiliaryBarWidth?: ControlOrValue<number>;
+    /** Auxiliary bar collapsed state — desktop hides the column, mobile closes the overlay. */
+    auxiliaryBarCollapsed?: ControlOrValue<boolean>;
+    /** Expanded bottom panel height in px; a Control tracks handle drags live. */
+    panelHeight?: ControlOrValue<number>;
+    /** Bottom panel collapsed state. */
+    panelCollapsed?: ControlOrValue<boolean>;
+    /** Maximized panel covers the whole main column; reversible through the same Control. */
+    panelMaximized?: ControlOrValue<boolean>;
+    children: ReactNode;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
+export default function Workbench({ activityBar: activityBarSlot, activityBarPosition: activityBarPositionControl, sidebar: sidebarSlot, auxiliaryBar: auxiliaryBarSlot, panel: panelSlot, statusBar: statusBarSlot, tabBar: tabBarSlot, sidebarWidth: sidebarWidthControl, sidebarCollapsed: sidebarCollapsedProp, mobileSidebarOpen: mobileSidebarOpenControl, auxiliaryBarWidth: auxiliaryBarWidthControl, auxiliaryBarCollapsed: auxiliaryBarCollapsedProp, panelHeight: panelHeightControl, panelCollapsed: panelCollapsedProp, panelMaximized: panelMaximizedProp, className, style, children, ...rest }: WorkbenchProps): import("react").JSX.Element;
+export type { WorkbenchProps };

package/dist/types/components/Workbench/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Workbench } from './Workbench';
+export type { WorkbenchProps } from './Workbench';

package/dist/types/dates/adapter.d.ts

@@ -18,7 +18,8 @@
  */
 /** Civil date parts in a specific calendar. `month` is 0-based — the
  * same `Date#getMonth` convention every date.ts function uses (0 = the
- * calendar's first month, 11 = its last) — while `day` is 1-based. */
+ * calendar's first month; 11 in 12-month calendars, 12 in hebrew leap
+ * years and ethiopic's Pagume-ending years) — while `day` is 1-based. */
 export type CivilDateParts = {
     year: number;
     month: number;
@@ -28,8 +29,12 @@ export type CivilDateParts = {
  * Umm al-Qura tabulation Node and browsers ship in full ICU; valid there
  * roughly 1300–1600 AH (Gregorian ~1882–2174), beyond which ICU falls
  * back to computed approximations (still self-consistent through this
- * adapter, which routes every conversion through Intl). */
-export type HazeCalendarIdentifier = 'gregory' | 'islamic-umalqura';
+ * adapter, which routes every conversion through Intl). The five
+ * algorithmic calendars (`persian`, `hebrew`, `japanese`, `buddhist`,
+ * `ethiopic`) are integer-arithmetic implementations whose outputs are
+ * cross-verified against Intl in their tests — see each adapter module
+ * for its supported range. */
+export type HazeCalendarIdentifier = 'gregory' | 'islamic-umalqura' | 'persian' | 'hebrew' | 'japanese' | 'buddhist' | 'ethiopic';
 /** Month-name width, mirroring Intl's `month` option values. */
 export type MonthNameStyle = 'long' | 'short' | 'narrow';
 /**
@@ -57,9 +62,12 @@ export type HazeDateAdapter = {
      * day 29 when that month has 29 days). Pure integer arithmetic on the
      * month index — no Date rollover hazards. */
     addMonths(parts: CivilDateParts, delta: number): CivilDateParts;
-    /** Twelve month names, index 0 = first month of the calendar year.
-     * `locale` defaults to the adapter's base presentation locale ('en'
-     * for the built-ins, matching Intl's calendar-extended locales). */
+    /** Month names for one full cycle of the calendar year, index 0 =
+     * first month of the calendar year. Twelve entries for 12-month
+     * calendars; thirteen where the calendar always has a thirteenth
+     * month (ethiopic's Pagume). `locale` defaults to the adapter's base
+     * presentation locale ('en' for the built-ins, matching Intl's
+     * calendar-extended locales). */
     monthNames(locale?: string, style?: MonthNameStyle): string[];
     /** Era abbreviation for a year ("AH" for Hijri, "AD"/"BC" for
      * Gregorian), via Intl. Optional: consumers that render no era skip
@@ -72,3 +80,22 @@ export type HazeDateAdapter = {
  * (internal helper; not part of the public dates surface).
  */
 export declare function eraOfDate(date: Date, calendar: HazeCalendarIdentifier, locale: string): string;
+/**
+ * UTC-civil milliseconds of a proleptic (year, month, day) triple. The
+ * `setUTCFullYear` route sidesteps the constructor's two-digit-year →
+ * 19xx remap, which the algorithmic adapters need for far-past eras
+ * (ethiopic year 1 maps to 8 CE; buddhist year 608 to 65 CE). Shared
+ * implementation behind the algorithmic adapters' conversions (internal
+ * helper; not part of the public dates surface).
+ */
+export declare function utcCivilMs(year: number, month: number, day: number): number;
+/**
+ * Local-midnight Date materializing a UTC civil instant — the date.ts
+ * civil semantics every adapter's `toGregorian` must produce. The
+ * constructor already builds exact local midnights; only its
+ * two-digit-year → 19xx remap needs dodging (ethiopic year 1 maps to
+ * 8 CE), which `setFullYear` — unlike the constructor — does while
+ * preserving the midnight time-of-day. Internal helper; not part of
+ * the public dates surface.
+ */
+export declare function localMidnightOf(ms: number): Date;

package/dist/types/dates/buddhist.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Buddhist-calendar adapter (Theravāda calendar as used in Thailand
+ * etc.). Structurally identical to the Gregorian calendar — same month
+ * lengths, same leap years — with the year counted in the Buddhist Era
+ * (BE), a constant +543 offset from the Gregorian year (2569 BE =
+ * 2026 CE). Month names come from Intl with the calendar pinned to
+ * `buddhist`, which renders the locale's ordinary month names; the era
+ * piece reports "BE". Because the offset is constant, every operation
+ * delegates to the shared Gregorian math in
+ * `src/lib/components/Calendar/date.ts` after translating the year,
+ * exactly like gregory.ts's shim.
+ */
+import type { HazeDateAdapter } from './adapter';
+export declare const buddhistAdapter: HazeDateAdapter;

package/dist/types/dates/ethiopic.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Ethiopic calendar adapter (Amete Mihret era, as used in Ethiopia and
+ * Eritrea): twelve 30-day months plus the 13th short month Pagume (5
+ * days, 6 in leap years — year ≡ 3 mod 4), the extra day keeping New
+ * Year (1 Maskaram) on September 11, drifting to September 12 after a
+ * leap year. Structurally the Ge'ez calendar with the Incarnation
+ * epoch: 1 Maskaram 1 AME = 8 CE August 29 (Julian), JDN 1724221. All
+ * math is integer day-number arithmetic against that epoch (whole
+ * days, no DST drift); results materialize as local-midnight Dates per
+ * the date.ts civil semantics. ICU's `ethiopic` calendar agrees with
+ * this arithmetic — ethiopic.test.ts's Intl oracle grid is the standing
+ * proof.
+ */
+import type { HazeDateAdapter } from './adapter';
+export declare const ethiopicAdapter: HazeDateAdapter;

package/dist/types/dates/hebrew.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hebrew (Jewish) civil calendar adapter — the fixed arithmetic
+ * rabbinical calendar (Hillel II): 19-year Metonic cycle with leap
+ * years 3/6/8/11/14/17/19 inserting Adar I/II, lunar months of 29/30
+ * days anchored by the molad (mean lunation of 29d 12h 793 parts) plus
+ * the four postponement rules that place Rosh Hashanah, and
+ * defective/regular/complete year types that vary only Heshvan and
+ * Kislev. Month indices are positional within the civil year (Tishri =
+ * 0): common years run 0–11 with Adar at 5; leap years run 0–12 with
+ * Adar I at 5 and Adar II at 6. ICU's `hebrew` calendar agrees with
+ * this arithmetic — hebrew.test.ts's Intl oracle grid (month names
+ * cross-walked to positional indices) is the standing proof.
+ *
+ * All math runs on integer day numbers (whole days, no DST drift) and
+ * results materialize as local-midnight Dates per the date.ts civil
+ * semantics.
+ */
+import type { HazeDateAdapter } from './adapter';
+export declare const hebrewAdapter: HazeDateAdapter;

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

@@ -1,5 +1,10 @@
 export { gregoryAdapter } from './gregory';
 export { islamicUmalquraAdapter } from './islamic';
+export { persianAdapter } from './persian';
+export { hebrewAdapter } from './hebrew';
+export { japaneseAdapter } from './japanese';
+export { buddhistAdapter } from './buddhist';
+export { ethiopicAdapter } from './ethiopic';
 export { getAdapter } from './registry';
 export type { CivilDateParts, HazeDateAdapter, HazeCalendarIdentifier, MonthNameStyle, } from './adapter';
 export { formatInTimeZone, getZonedParts } from './timezone';

package/dist/types/dates/japanese.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Japanese imperial-calendar adapter. ICU's `japanese` calendar is the
+ * Gregorian calendar with era-relative year display: month lengths,
+ * leap years, and weekday math are structurally identical to gregory,
+ * and only the year's *label* segments at imperial accessions (Reiwa 8
+ * = 2026 CE). The adapter therefore keeps the year field at its plain
+ * Gregorian numeric value — era segmentation is a formatting concern
+ * delegated to Intl's era piece (see `era`, which reports the era in
+ * force on June 1 of the year, i.e. after the May 1/January 8
+ * accessions of the modern eras) — so month arithmetic, grid math, and
+ * Date round-trips stay monotonic and hazard-free. Month names come
+ * from Intl with the calendar pinned to `japanese`, which renders
+ * plain month names in the requested locale.
+ */
+import type { HazeDateAdapter } from './adapter';
+export declare const japaneseAdapter: HazeDateAdapter;

package/dist/types/dates/persian.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Persian (Solar Hijri / Jalaali) adapter — the arithmetic calendar in
+ * official use in Iran and Afghanistan. Twelve solar months (six 31-day,
+ * five 30-day, Esfand 29 or 30) kept equinox-locked by the public-domain
+ * Borkowski algorithm that jalaali-js / moment-jalaali popularized: a
+ * breaks table that restarts the 33-year leap pattern at observed
+ * corrections, tracking the astronomical calendar across 1178–1633 AP
+ * (Gregorian 1799–2255). Node and browsers compute `persian` in full ICU
+ * with the same arithmetic, so this implementation and Intl agree over
+ * the whole supported range — persian.test.ts's Intl oracle grid is the
+ * standing proof.
+ *
+ * Like the other algorithmic adapters (hebrew, ethiopic), all math runs
+ * on integer Julian Day Numbers (whole days, no DST drift) and results
+ * materialize as local-midnight Dates per the date.ts civil semantics.
+ */
+import type { HazeDateAdapter } from './adapter';
+export declare const persianAdapter: HazeDateAdapter;

package/dist/types/dates/registry.d.ts

@@ -7,7 +7,7 @@
 import type { HazeCalendarIdentifier, HazeDateAdapter } from './adapter';
 /**
  * Adapter lookup by calendar identifier. Returns the shared singleton
- * adapters (`gregoryAdapter`, `islamicUmalquraAdapter`); throws
+ * adapters (`gregoryAdapter`, `islamicUmalquraAdapter`, …); throws
  * `RangeError` for identifiers with no built-in adapter.
  */
 export declare function getAdapter(identifier: HazeCalendarIdentifier): HazeDateAdapter;

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

@@ -17,6 +17,7 @@
  * major version. The primitives still evolve alongside the library's
  * own components, within that contract.
  */
+import { useBusyPressable } from '../hooks/useBusyPressable';
 import { useClickOutside } from '../hooks/useClickOutside';
 import { hotkey, useHotkeys } from '../hooks/useHotkeys';
 import { useInView } from '../hooks/useInView';
@@ -378,6 +379,14 @@ export type { UseInViewOptions } from '../hooks/useInView';
  * get a stable `false` instead of a throw.
  */
 export { useMediaQuery };
+/**
+ * Props bag for a pressable that can enter a busy/loading state —
+ * `disabled` forced while busy, `aria-busy` mirrored. The behavior
+ * half of `Button`'s/`ButtonLink`'s `loading` prop, for consumers
+ * composing their own trigger. Anchors translate `disabled` to
+ * `aria-disabled` (see ButtonLink).
+ */
+export { useBusyPressable };
 /**
  * The value from the previous render; `undefined` on the first.
  * Compared by identity per render — no deep equality.

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

@@ -1,3 +1,4 @@
+export { useBusyPressable } from './useBusyPressable';
 export { useClipboard } from './useClipboard';
 export type { UseClipboardResult } from './useClipboard';
 export { useClickOutside } from './useClickOutside';
@@ -14,6 +15,18 @@ export { useInView } from './useInView';
 export type { UseInViewOptions } from './useInView';
 export { useLocalStorage } from './useLocalStorage';
 export { useMediaQuery } from './useMediaQuery';
+export { useElementSize } from './useElementSize';
+export type { ElementSize, UseElementSizeOptions, UseElementSizeResult, } from './useElementSize';
+export { useIdle } from './useIdle';
+export type { UseIdleOptions, UseIdleResult } from './useIdle';
+export { useMutationObserver } from './useMutationObserver';
+export type { UseMutationObserverOptions, UseMutationObserverResult, } from './useMutationObserver';
+export { useNetwork } from './useNetwork';
+export type { NetworkSnapshot } from './useNetwork';
+export { useOrientation } from './useOrientation';
+export type { OrientationSnapshot } from './useOrientation';
+export { useResizeObserver } from './useResizeObserver';
+export type { UseResizeObserverOptions, UseResizeObserverResult, } from './useResizeObserver';
 export { usePrefersReducedMotion } from './usePrefersReducedMotion';
 export { usePrevious } from './usePrevious';
 export { useSessionStorage } from './useSessionStorage';

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

@@ -0,0 +1,33 @@
+/**
+ * Props bag for a pressable that can enter a busy/loading state — the
+ * behavior half of `Button`'s `loading` prop, for consumers composing
+ * their own trigger (list rows, table actions, custom submit
+ * controls):
+ *
+ * ```tsx
+ * const busyProps = useBusyPressable(submitting, disabledProp);
+ * <button {...busyProps} onClick={submit}>
+ *   {submitting ? <Spinner size="sm" /> : null}
+ *   Save
+ * </button>
+ * ```
+ *
+ * The bag carries exactly two things:
+ *
+ * - `disabled` — forced `true` while busy, so activation (click, Enter,
+ *   form submission via `type="submit"`) is blocked at the platform
+ *   level, not by convention. When a caller's own `disabled` is
+ *   supplied, busy ORs into it — busy never *re-enables* a disabled
+ *   control.
+ * - `aria-busy` — mirrors the busy phase to assistive technology; pair
+ *   the swapped-in indicator with `aria-hidden` (or a labeled status
+ *   spinner) so it is not double-announced.
+ *
+ * Anchors have no `disabled` attribute: when the pressable is an
+ * `<a>`, translate to `aria-disabled` + `tabIndex={-1}` the way
+ * `ButtonLink` does.
+ */
+export declare function useBusyPressable(busy?: boolean, disabled?: boolean): {
+    disabled: boolean;
+    'aria-busy': true | undefined;
+};

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

@@ -0,0 +1,38 @@
+import type { RefCallback } from 'react';
+type ElementSize = {
+    width: number;
+    height: number;
+};
+type UseElementSizeOptions = {
+    /** 观测盒，同 ResizeObserver（默认 'content-box'）。 */
+    box?: ResizeObserverBoxOptions;
+    /** 是否启用，默认 `true`。 */
+    enabled?: boolean;
+};
+type UseElementSizeResult<T extends Element = Element> = [
+    ref: RefCallback<T>,
+    size: ElementSize
+];
+/**
+ * 元素 size 追踪（useResizeObserver 的简化形态——只吐 width/height）。
+ *
+ * ```tsx
+ * const [ref, size] = useElementSize<HTMLDivElement>();
+ * return <div ref={ref}>{size.width}×{size.height}</div>;
+ * ```
+ *
+ * - 底层 ResizeObserver；仅在 size 实际变化时 setState，避免子像素
+ *   抖动引发反复重渲。
+ * - `enabled=false` / 卸载时 size 清零（与 useResizeObserver 的冻结
+ *   语义相反：size 是原始数据，禁用后无订阅的冻结值是陈旧数据；
+ *   entry 是结构化快照，那边反而选择冻结——详见其文档）。
+ * - ref 回调身份稳定（useCallback）：React 19 对每个新 ref 函数会
+ *   null-detach + re-attach，这里的 ref 只在 box/enabled 变化时才新建。
+ * - SSR：size 恒 `{0,0}`，无 hydration mismatch；无 ResizeObserver
+ *   环境（jsdom ≤23 / 老引擎）静默降级。
+ *
+ * @param options 见 {@link UseElementSizeOptions}。
+ * @returns `[ref, size]`。
+ */
+export declare function useElementSize<T extends Element = Element>(options?: UseElementSizeOptions): UseElementSizeResult<T>;
+export type { ElementSize, UseElementSizeOptions, UseElementSizeResult };

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

@@ -0,0 +1,45 @@
+type UseIdleOptions = {
+    /**
+     * 判定 idle 的时间窗口（毫秒），默认 `60_000`（1 分钟）。
+     */
+    timeout?: number;
+    /**
+     * 哪些 DOM 事件「重置」idle（默认覆盖鼠标/键盘/触摸/滚动/visibilitychange）。
+     * 传空数组应当视为「只按 visibility 判定」，改用 `useNetwork` / 手动控制。
+     */
+    events?: (keyof WindowEventMap)[];
+    /**
+     * 首个事件目标：默认 `document`；显式传 window 时会同时监听
+     * document visibilitychange（不可绕过）。
+     */
+    element?: HTMLElement | Window | null | undefined;
+    /**
+     * 初始 idle 状态，默认 `false`（没收到任何事件前不认为空闲）。
+     * SSR 默认同此。
+     */
+    initialState?: boolean;
+};
+type UseIdleResult = {
+    /** 当前是否 idle（距最后一个事件超过 timeout）。 */
+    idle: boolean;
+    /** 最近一次活动的时间戳（epoch ms）；无活动时为挂载时间。 */
+    lastActive: number;
+};
+/**
+ * 检测用户是否「空闲」（无鼠标/键盘/触摸/滚动活动超过 `timeout` 毫秒）。
+ *
+ * ```tsx
+ * const { idle, lastActive } = useIdle({ timeout: 5_000 });
+ * if (idle) return <AwayBadge />;
+ * ```
+ *
+ * - 触发源走「document 捕获」：子应用嵌套（dialog 内部点击）也算活动。
+ * - `visibilitychange` 强制同步：切走 tab 不重置计时；切回来先更新状态再算 idle。
+ * - SSR：isServer → idle=initialState，不挂监听。
+ * - 引擎无 timer（纯 SSR/单测起点）：state 以 initialState 兜底、不调度。
+ *
+ * @param options 见 {@link UseIdleOptions}。
+ * @returns `{idle, lastActive}`。
+ */
+export declare function useIdle(options?: UseIdleOptions): UseIdleResult;
+export type { UseIdleOptions, UseIdleResult };

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

@@ -0,0 +1,35 @@
+import type { RefCallback } from 'react';
+type UseMutationObserverOptions = MutationObserverInit & {
+    /**
+     * 是否启用。默认 `true`；`false` 时快照冻结为最后一次观测值，
+     * 不建立观察器。
+     */
+    enabled?: boolean;
+};
+type UseMutationObserverResult = [
+    ref: RefCallback<Element>,
+    records: MutationRecord[]
+];
+/**
+ * 通用 MutationObserver 订阅：观察元素的 attributes/childList/
+ * characterData 变化（由 options 决定）。
+ *
+ * ```tsx
+ * const [ref, mutations] = useMutationObserver(
+ *   (records) => { console.log(records); },
+ *   { attributes: true, attributeFilter: ['data-state'], subtree: false }
+ * );
+ * ```
+ *
+ * - 必须显式传 options（MutationObserverInit）——没有监听类型的
+ *   MutationObserver 是非法用法。
+ * - ref 重挂时自动切换观察目标；history 不保留。
+ * - SSR：不观察，records 恒 `[]`。
+ *
+ * @param callback 收到记录时调用（可为 null / 省略，表示只更新 state）。
+ * @param options MutationObserver init 选项 + enabled。
+ * @returns `[ref, records]`：records 是最新一批 MutationRecord 列表
+ *  （每次回调都新建数组——适合直接 `.map`）。
+ */
+export declare function useMutationObserver(callback: MutationCallback | null | undefined, options: UseMutationObserverOptions): UseMutationObserverResult;
+export type { UseMutationObserverOptions, UseMutationObserverResult };

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

@@ -0,0 +1,31 @@
+type NetworkSnapshot = {
+    /** 当前在线状态；SSR/无 navigator 环境恒 `true`（假设在线）。 */
+    online: boolean;
+    /**
+     * 连接元信息（effectiveType/downlink/rtt/saveData）。仅部分浏览器
+     * 暴露 `navigator.connection`；单测/SSR/未支持浏览器全部为 undefined。
+     */
+    effectiveType?: string;
+    downlink?: number;
+    rtt?: number;
+    saveData?: boolean;
+};
+/**
+ * 网络在线状态 + 可选 `navigator.connection` 连接元信息。
+ *
+ * ```tsx
+ * const { online, effectiveType, saveData } = useNetwork();
+ * if (!online) return <OfflineBanner />;
+ * ```
+ *
+ * - 底层 `useSyncExternalStore('online/offline/connection.change')`——
+ *   状态切换自动触发 React 重新渲染，撕裂防护由 React 官方语义兜底。
+ * - SSR：恒返回 `{online: true}`，不产生 hydration mismatch（React
+ *   收不到 onChange 时保持首帧快照）。
+ * - 浏览器不支持 `navigator.connection`（FF/Safari ≤15）：connection
+ *   相关字段 undefined、`online` 仍正确。
+ *
+ * @returns 当前网络状态快照。所有字段在事件触发后原子更新（同一 tick）。
+ */
+export declare function useNetwork(): NetworkSnapshot;
+export type { NetworkSnapshot };

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

@@ -0,0 +1,23 @@
+export type OrientationSnapshot = {
+    /** 屏幕朝角：0/90/180/270，纵向起点 0。 */
+    angle: number;
+    /** 屏幕方向分类：landscape-primary/portrait-primary/landscape-secondary/portrait-secondary。 */
+    type: OrientationType;
+};
+/**
+ * 当前屏幕方向（screen.orientation + change 事件订阅）。
+ *
+ * ```tsx
+ * const { angle, type } = useOrientation();
+ * if (type.startsWith('landscape')) return <WideLayout />;
+ * ```
+ *
+ * - 使用 `useSyncExternalStore` 状态源：渲染与事件切换之间的撕裂由
+ *   React 收敛，无需手动维护两套 useState。
+ * - SSR/无 orientation API（老 jsdom）：恒返回 portrait-primary/0°。
+ * - 视觉上「横/竖」的判断可用 `window.screen.orientation.type.startsWith('landscape')`
+ *   或者 angle % 180 !== 0。
+ *
+ * @returns 当前屏幕方向快照。
+ */
+export declare function useOrientation(): OrientationSnapshot;