haze-ui 1.32.0 → 1.34.0

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

@@ -32,6 +32,11 @@ type UploadFileStatus = {
     status: UploadStatus;
     /** 0–100, clamped; forced to 100 when the upload succeeds. */
     percent: number;
+    /** Why an `error` entry never uploaded: set when the file was
+     * refused at intake (over `maxSize`) — the row renders the message
+     * in place of the retry/progress affordances and only remove
+     * applies. Absent for transport failures (retryable) and echoes. */
+    error?: string;
 };
 /** Runtime handed to a custom `request` (and used internally by the
  * XHR wrapper that `action` mode builds). */
@@ -76,6 +81,28 @@ type UploadHandle = {
     abort: () => void;
     clear: () => void;
 };
+/**
+ * Semantic slot classes (AntD v6 `classNames` shape) for the Upload
+ * family: declared once on `<Upload>` (or `<UploadCore>`) and applied
+ * to the drop zone and handed down to the built-in list. Consumer
+ * classes are appended at the end of each part's class list; per-part
+ * `className` props remain for one-off tweaks and still land after the
+ * slot class.
+ */
+type UploadClassNames = {
+    /** The drop zone / click-to-pick area (`data-slot='drop-zone'`) —
+     *  the dashed drop area in droppable mode, the plain picker area
+     *  otherwise. The component renders no single root element: the zone
+     *  and the built-in list are siblings. */
+    trigger?: string;
+    /** The built-in list root `<ul>` (`data-slot='list'`) — only rendered
+     *  while `showUploadList` is on and files exist. */
+    list?: string;
+    /** Every list row / picture-card (`<li>`, `data-slot='item'`). */
+    item?: string;
+    /** Every progress bar in a row / card mask (the `Progress` element). */
+    progress?: string;
+};
 /** Internal tracked row: public status snapshot plus the stable uid the
  * list keys on (value items carry no serializable identity). Echo
  * entries hold their terminal `status`/`percent` from the
@@ -83,4 +110,4 @@ type UploadHandle = {
 type UploadEntry = UploadFileStatus & {
     uid: string;
 };
-export type { UploadStatus, UploadFile, UploadValueItem, UploadFileStatus, UploadRequestOptions, UploadRequest, UploadListItemActions, UploadListItemRender, UploadHandle, UploadEntry, };
+export type { UploadClassNames, UploadStatus, UploadFile, UploadValueItem, UploadFileStatus, UploadRequestOptions, UploadRequest, UploadListItemActions, UploadListItemRender, UploadHandle, UploadEntry, };

package/dist/types/components/Upload/xhr-upload.d.ts

@@ -1,4 +1,4 @@
-import type { UploadRequest } from './types';
+import type { UploadRequest } from './types.js';
 type XhrUploadConfig = {
     /** Upload endpoint URL. */
     action: string;

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

@@ -1,2 +1,2 @@
-export { default as VirtualList } from './VirtualList';
-export type { VirtualListProps, VirtualListHandle, VirtualListGroup, VirtualListAlign, VirtualListOrientation } from './VirtualList';
+export { default as VirtualList } from './VirtualList.js';
+export type { VirtualListProps, VirtualListHandle, VirtualListGroup, VirtualListAlign, VirtualListOrientation } from './VirtualList.js';

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

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

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

@@ -1,2 +1,2 @@
-export { default as Watermark } from './Watermark';
-export type { WatermarkProps, WatermarkFont } from './Watermark';
+export { default as Watermark } from './Watermark.js';
+export type { WatermarkProps, WatermarkFont } from './Watermark.js';

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

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

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

@@ -10,5 +10,5 @@
  * `src/lib/components/Calendar/date.ts` after translating the year,
  * exactly like gregory.ts's shim.
  */
-import type { HazeDateAdapter } from './adapter';
+import type { HazeDateAdapter } from './adapter.js';
 export declare const buddhistAdapter: HazeDateAdapter;

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

@@ -11,5 +11,5 @@
  * this arithmetic — ethiopic.test.ts's Intl oracle grid is the standing
  * proof.
  */
-import type { HazeDateAdapter } from './adapter';
+import type { HazeDateAdapter } from './adapter.js';
 export declare const ethiopicAdapter: HazeDateAdapter;

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

@@ -6,5 +6,5 @@
  * semantics are date.ts's own, so a Calendar wired to this adapter
  * behaves exactly like today's hard-wired Gregorian code paths.
  */
-import type { HazeDateAdapter } from './adapter';
+import type { HazeDateAdapter } from './adapter.js';
 export declare const gregoryAdapter: HazeDateAdapter;

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

@@ -15,5 +15,5 @@
  * results materialize as local-midnight Dates per the date.ts civil
  * semantics.
  */
-import type { HazeDateAdapter } from './adapter';
+import type { HazeDateAdapter } from './adapter.js';
 export declare const hebrewAdapter: HazeDateAdapter;

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

@@ -1,11 +1,11 @@
-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';
-export type { ZonedParts } from './timezone';
+export { gregoryAdapter } from './gregory.js';
+export { islamicUmalquraAdapter } from './islamic.js';
+export { persianAdapter } from './persian.js';
+export { hebrewAdapter } from './hebrew.js';
+export { japaneseAdapter } from './japanese.js';
+export { buddhistAdapter } from './buddhist.js';
+export { ethiopicAdapter } from './ethiopic.js';
+export { getAdapter } from './registry.js';
+export type { CivilDateParts, HazeDateAdapter, HazeCalendarIdentifier, MonthNameStyle, } from './adapter.js';
+export { formatInTimeZone, getZonedParts } from './timezone.js';
+export type { ZonedParts } from './timezone.js';

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

@@ -13,5 +13,5 @@
  * ICU falls back to computed months, which this adapter stays
  * self-consistent with (every conversion still passes through Intl).
  */
-import type { HazeDateAdapter } from './adapter';
+import type { HazeDateAdapter } from './adapter.js';
 export declare const islamicUmalquraAdapter: HazeDateAdapter;

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

@@ -12,5 +12,5 @@
  * from Intl with the calendar pinned to `japanese`, which renders
  * plain month names in the requested locale.
  */
-import type { HazeDateAdapter } from './adapter';
+import type { HazeDateAdapter } from './adapter.js';
 export declare const japaneseAdapter: HazeDateAdapter;

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

@@ -14,5 +14,5 @@
  * 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';
+import type { HazeDateAdapter } from './adapter.js';
 export declare const persianAdapter: HazeDateAdapter;

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

@@ -4,7 +4,7 @@
  * only depend on the contract (`./adapter`), keeping the module graph
  * acyclic.
  */
-import type { HazeCalendarIdentifier, HazeDateAdapter } from './adapter';
+import type { HazeCalendarIdentifier, HazeDateAdapter } from './adapter.js';
 /**
  * Adapter lookup by calendar identifier. Returns the shared singleton
  * adapters (`gregoryAdapter`, `islamicUmalquraAdapter`, …); throws

package/dist/types/form/FormItem.d.ts

@@ -98,6 +98,36 @@ export type FormItemRawElementBinding<TRawElement extends FormItemRawElement = F
     element: TRawElement;
     eventToValue: (e: any) => any;
 };
+/**
+ * Semantic slot classes (AntD v6 `classNames` shape) for FormItem's own
+ * structural nodes: keys mirror the data-slot each node carries. The
+ * `control` slot is the odd one out — it has no FormItem-owned node in
+ * the render-prop channel (the consumer renders the control), so it
+ * only wires in the declarative `input`/`as` channels, landing as the
+ * control element's own `className` (merged with any `asProps.className`).
+ * Consumer classes are appended after the component defaults; `root`
+ * composes with FormItem's own `className`.
+ */
+export type FormItemClassNames = {
+    /** The item's root `<div>` (`data-slot='form-item'`) in every layout. */
+    root?: string;
+    /** The `<label>` element (`data-slot='label'`); omitted when no label. */
+    label?: string;
+    /**
+     * The field control element itself — wired in the `input` and `as`
+     * channels as the control's `className`; in the render-prop channel
+     * the consumer owns the element and applies the class itself.
+     */
+    control?: string;
+    /**
+     * Horizontal layout only: the column `<div>` (`data-slot='control-column'`)
+     * wrapping control + error beside the label rail.
+     */
+    controlColumn?: string;
+    /** The error `<span role='alert'>` (`data-slot='error'`); rendered
+     * only while the field has errors. */
+    error?: string;
+};
 /** FormItem's own, non-polymorphic props — everything the item itself
  * consumes regardless of how the control is bound (render-prop, `as`
  * or `input`). */
@@ -164,6 +194,10 @@ export type FormItemOwnProps<TValues extends Record<string, any> = any, P extend
      * instead of the bare message. The span itself — id, `role='alert'`,
      * styling — stays FormItem's, in every control-binding mode. */
     renderError?: (error: string, id: string) => ReactNode;
+    /** Slot classes (see {@link FormItemClassNames}); each key lands on
+     * the structural node carrying the matching data-slot, after the
+     * component defaults. */
+    classNames?: FormItemClassNames;
     className?: string;
 };
 /**
@@ -177,6 +211,9 @@ type FormItemWiredProps = {
     /** the focus channel: react-f0rm's `focusRef` rides the control's
      * `ref` — `setFocus` and failed-submit auto-focus depend on it */
     ref?: unknown;
+    /** the control slot: `classNames.control` (merged with any
+     * `asProps.className`) lands as the control's own className */
+    className?: unknown;
     onBlur?: unknown;
     onChange?: unknown;
     /** the value channel: `value` directly, or the prop `valueToProps`
@@ -339,5 +376,5 @@ export type FormItemProps<TValues extends Record<string, any> = any, P extends F
  * error on one row with an automatic inter-item `margin-inline-end`.
  * The id/label/aria wiring is identical in all three layouts.
  */
-export default function FormItem<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name, TInputProps extends Record<string, any> = Record<never, never>, TRawElement extends FormItemRawElement = never>({ form, name, label, layout, labelWidth, labelAlign, validate, mode, validateDebounce, delayError, rules, className, renderError, as: As, asProps, input: Input, eventToValue, valueToProps, children, ...inputProps }: FormItemProps<TValues, P, TInputProps, TRawElement>): import("react").JSX.Element;
+export default function FormItem<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name, TInputProps extends Record<string, any> = Record<never, never>, TRawElement extends FormItemRawElement = never>({ form, name, label, layout, labelWidth, labelAlign, validate, mode, validateDebounce, delayError, rules, className, classNames, renderError, as: As, asProps, input: Input, eventToValue, valueToProps, children, ...inputProps }: FormItemProps<TValues, P, TInputProps, TRawElement>): import("react").JSX.Element;
 export {};

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

@@ -1,15 +1,25 @@
-export { default as FormItem } from './FormItem';
-export type { FieldValidator, FormItemAsProps, FormItemBinding, FormItemOwnProps, FormItemProps, FormItemRawElement, FormItemRawElementBinding } from './FormItem';
-export { default as FormList } from './FormList';
-export type { FormListBinding, FormListField, FormListProps } from './FormList';
+export { default as FormItem } from './FormItem.js';
+export type { FieldValidator, FormItemAsProps, FormItemBinding, FormItemClassNames, FormItemOwnProps, FormItemProps, FormItemRawElement, FormItemRawElementBinding } from './FormItem.js';
+export { default as FormList } from './FormList.js';
+export type { FormListBinding, FormListField, FormListProps } from './FormList.js';
 export type { FormInstance, PathValueOf } from 'react-f0rm';
 /**
  * react-f0rm 的上下文与命令式 API —— haze-ui form 层的官方透传出口。
  * react-f0rm 是 haze-ui 的普通依赖，从这里 import 即可，无需再直接
  * 依赖 react-f0rm。`<FormProvider value={form}>` 挂 context 后，子树里的
  * `FormItem`/`FormList` 可以省略 `form` prop。
+ *
+ * - `Form`：react-f0rm 的 `<form>` 组件封装 —— 挂 context、串提交链
+ *   （onSubmit/onValidSubmit/onInvalidSubmit）与 native validation 开关。
+ * - `useForm`：antd 风格命名的表单实例 hook。react-f0rm 自带组件生命周期
+ *   绑定版的 `useForm`，直接透传即可 —— 不做 `useForm = createForm`
+ *   别名，那会用生命周期语义不同的工厂版遮蔽同名 hook。
+ * - `createForm`：手动生命周期的实例工厂（模块级单例、测试、桥接层等
+ *   非 hook 场景）。
+ * - `useValue`/`useValues`：字段级订阅 hook（响应式读取单个/整个表单值）
+ *   ——同样透传，消费者无需直接依赖 react-f0rm。
  */
-export { FormProvider, useFormContext, useFieldArray, useFieldArrayItem, useWatch, trigger, setFocus, setServerErrors, setValue, getValue, getValues, reset } from 'react-f0rm';
+export { Form, useForm, createForm, FormProvider, useFormContext, useFieldArray, useFieldArrayItem, useWatch, useValue, useValues, trigger, setFocus, setServerErrors, setValue, getValue, getValues, reset } from 'react-f0rm';
 /**
  * Standard Schema v1 适配器（react-f0rm/resolvers/standard-schema）：
  * 任何实现 `~standard` 的 schema 库通用 —— zod v3.24+/v4、valibot v1、
@@ -20,8 +30,8 @@ export { FormProvider, useFormContext, useFieldArray, useFieldArrayItem, useWatc
  * 品牌符号打包缺陷）。`hasStandardProps` 运行时探测 schema 是否实现了
  * Standard Schema。
  */
-export { hasStandardProps, standardSchemaFormValidator, standardSchemaResolver } from './standard-schema';
-export type { StandardSchemaV1 } from './standard-schema';
+export { hasStandardProps, standardSchemaFormValidator, standardSchemaResolver } from './standard-schema.js';
+export type { StandardSchemaV1 } from './standard-schema.js';
 /**
  * zod 专用字段级适配器（react-f0rm/resolvers/zod）：schema 实现了
  * Standard Schema 时直接走通用通道，否则走 zod 的 safeParseAsync。

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

@@ -17,24 +17,24 @@
  * 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';
-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';
+import { useBusyPressable } from '../hooks/useBusyPressable.js';
+import { useClickOutside } from '../hooks/useClickOutside.js';
+import { hotkey, useHotkeys } from '../hooks/useHotkeys.js';
+import { useInView } from '../hooks/useInView.js';
+import { useLocalStorage } from '../hooks/useLocalStorage.js';
+import { useMediaQuery } from '../hooks/useMediaQuery.js';
+import { usePrevious } from '../hooks/usePrevious.js';
+import { useSessionStorage } from '../hooks/useSessionStorage.js';
+import { computeFloatingPosition, resolvePadding } from '../utils/collision.js';
+import { getDirection, localeDirection, useDirection } from '../utils/direction.js';
+import { FloatingPanel, floatingPlacementClasses, placeFloatingPanel, supportsAnchorPositioning, supportsNativePopover, useFloating, useFloatingPosition } from '../utils/floating.js';
+import { focusFirst, getTabbables, isTabbable, TABBABLE_SELECTOR } from '../utils/focus.js';
+import { useFocusScope } from '../utils/focus-scope.js';
+import { getEnabledMenuItems, useMenuKeyboard, useRovingTabindex } from '../utils/menuKeyboard.js';
+import { Presence, whenExitSettles } from '../utils/presence.js';
+import { mergeRefs } from '../utils/refs.js';
+import { SUBMENU_CLOSE_GRACE_MS, SUBMENU_OPEN_DELAY_MS, SubmenuProvider, useSubmenu, useSubmenuContext } from '../utils/submenu.js';
+import { useViewTransitionFlip } from '../utils/view-transition.js';
 /**
  * Detects the native Popover API (`popover` attribute, top layer,
  * light-dismiss). The floating primitives use this to choose their
@@ -65,7 +65,7 @@ export type UseFloatingOptions = Parameters<typeof useFloating>[0];
  * phases (`shown`/`dataState`/`exited`), and the props/class entries to
  * spread on the trigger and panel elements.
  */
-export type { FloatingBehavior } from '../utils/floating';
+export type { FloatingBehavior } from '../utils/floating.js';
 /**
  * Panel placement relative to the trigger (`'bottom' | 'bottom-span' |
  * 'bottom-center' | 'bottom-end' | 'top' | 'left' | 'right'`, or
@@ -73,7 +73,7 @@ export type { FloatingBehavior } from '../utils/floating';
  * Logical, not physical: under `dir="rtl"` the horizontal placements and
  * the start/end alignments mirror automatically.
  */
-export type { FloatingPlacement } from '../utils/floating';
+export type { FloatingPlacement } from '../utils/floating.js';
 /**
  * x-class entries placing a panel element relative to its trigger, per
  * engine tier — for consumers composing their own panel instead of using
@@ -109,15 +109,19 @@ 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.
+ * transitions on it) and unmounts only after the exit settles — or,
+ * with `keepMounted`, stays mounted dormant behind `hidden` + `inert`.
+ * 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.
+ * `children`, an optional `onExited` callback, and `keepMounted` to
+ * keep the child mounted (dormant behind `hidden` + `inert`) after the
+ * exit settles.
  */
-export type { PresenceProps } from '../utils/presence';
+export type { PresenceProps } from '../utils/presence.js';
 /**
  * Wait for an element's exit animation/transition to finish. Resolves
  * immediately when no positive duration is declared, `null` for an
@@ -137,7 +141,7 @@ export { useFocusScope };
  * `autoFocus`, `returnFocus`, and the mount/unmount auto-focus event
  * callbacks (preventable via `event.preventDefault()`).
  */
-export type { FocusScopeOptions } from '../utils/focus-scope';
+export type { FocusScopeOptions } from '../utils/focus-scope.js';
 /**
  * Tab-order candidate selector (structural filter only; runtime state —
  * disabled, hidden, visibility — is filtered by {@link isTabbable}).
@@ -186,18 +190,18 @@ export { resolvePadding };
 /**
  * Viewport edge a collision measurement applies to.
  */
-export type { CollisionSide } from '../utils/collision';
+export type { CollisionSide } from '../utils/collision.js';
 /**
  * Viewport inset for collision checks: a number applies to all four
  * sides, an object per side.
  */
-export type { CollisionPadding } from '../utils/collision';
+export type { CollisionPadding } from '../utils/collision.js';
 /**
  * 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';
+export type { CollisionStrategy } from '../utils/collision.js';
 /**
  * Enabled menu items inside a container, in DOM order. `role="menu"`
  * containers scope each item to its nearest menu ancestor, so a nested
@@ -257,7 +261,7 @@ export type UseSubmenuOptions = Parameters<typeof useSubmenu>[0];
  * handlers to spread on the trigger (`onPointerEnter`, `onKeyDown`)
  * and the panel (`onKeyDown`).
  */
-export type { SubmenuBehavior } from '../utils/submenu';
+export type { SubmenuBehavior } from '../utils/submenu.js';
 /**
  * Context provider carrying a {@link SubmenuBehavior} from a Sub
  * container to its trigger/content parts — for authors composing their
@@ -283,7 +287,7 @@ export { SUBMENU_CLOSE_GRACE_MS };
 /**
  * Writing direction of a subtree: `'ltr'` or `'rtl'`.
  */
-export type { Direction } from '../utils/direction';
+export type { Direction } from '../utils/direction.js';
 /**
  * Direction implied by a BCP 47 tag — RTL primary language subtags
  * (`ar`, `fa`, `he`, `ur`, …) resolve to `'rtl'`, everything else to
@@ -334,14 +338,15 @@ export { useClickOutside };
  * `true`) and the `ignore` ref list — elements whose hits do not count
  * as outside.
  */
-export type { UseClickOutsideOptions } from '../hooks/useClickOutside';
+export type { UseClickOutsideOptions } from '../hooks/useClickOutside.js';
 /**
  * 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.
+ * `'ctrl+shift+p'`, `'?'`, named keys, whitespace-joined sequences like
+ * `'g h'`) to handlers, listened on the window (or a ref target). `mod`
+ * normalizes per platform (⌘ on macOS, Ctrl elsewhere), editable focus
+ * suppresses fires unless `allowInInput`, sequences reset on a wrong key
+ * or after `sequenceTimeout` (default 1000ms), and the map may be an
+ * inline literal — a latest-ref keeps the listener mounted once.
  */
 export { useHotkeys };
 /**
@@ -354,12 +359,12 @@ 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';
+export type { HotkeyHandler } from '../hooks/useHotkeys.js';
 /**
  * Options accepted by {@link useHotkeys}: `enabled`, `target` (element
- * ref or `window`), `eventName` and `allowInInput`.
+ * ref or `window`), `eventName`, `allowInInput` and `sequenceTimeout`.
  */
-export type { UseHotkeysOptions } from '../hooks/useHotkeys';
+export type { UseHotkeysOptions } from '../hooks/useHotkeys.js';
 /**
  * Observe whether an element is in the viewport: attach the returned
  * callback ref and read the `inView` flag. `once: true` freezes after
@@ -371,7 +376,7 @@ export { useInView };
  * Options accepted by {@link useInView}: the IntersectionObserver init
  * members plus the `once` freeze flag.
  */
-export type { UseInViewOptions } from '../hooks/useInView';
+export type { UseInViewOptions } from '../hooks/useInView.js';
 /**
  * Subscribe to a CSS media query and return whether it currently
  * matches; the query can change per render. SSR and hydration snapshots

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

@@ -1,33 +1,33 @@
-export { useBusyPressable } from './useBusyPressable';
-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 { 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';
-export { useTitle } from './useTitle';
+export { useBusyPressable } from './useBusyPressable.js';
+export { useClipboard } from './useClipboard.js';
+export type { UseClipboardResult } from './useClipboard.js';
+export { useClickOutside } from './useClickOutside.js';
+export type { UseClickOutsideOptions } from './useClickOutside.js';
+export { useDarkMode } from './useDarkMode.js';
+export type { ColorMode, UseDarkModeOptions, UseDarkModeResult } from './useDarkMode.js';
+export { useDebouncedCallback } from './useDebouncedCallback.js';
+export { useDebouncedValue } from './useDebouncedValue.js';
+export { useFullscreen } from './useFullscreen.js';
+export type { FullscreenTarget, UseFullscreenHandle } from './useFullscreen.js';
+export { useHotkeys, hotkey } from './useHotkeys.js';
+export type { HotkeyHandler, UseHotkeysOptions } from './useHotkeys.js';
+export { useInView } from './useInView.js';
+export type { UseInViewOptions } from './useInView.js';
+export { useLocalStorage } from './useLocalStorage.js';
+export { useMediaQuery } from './useMediaQuery.js';
+export { useElementSize } from './useElementSize.js';
+export type { ElementSize, UseElementSizeOptions, UseElementSizeResult, } from './useElementSize.js';
+export { useIdle } from './useIdle.js';
+export type { UseIdleOptions, UseIdleResult } from './useIdle.js';
+export { useMutationObserver } from './useMutationObserver.js';
+export type { UseMutationObserverOptions, UseMutationObserverResult, } from './useMutationObserver.js';
+export { useNetwork } from './useNetwork.js';
+export type { NetworkSnapshot } from './useNetwork.js';
+export { useOrientation } from './useOrientation.js';
+export type { OrientationSnapshot } from './useOrientation.js';
+export { useResizeObserver } from './useResizeObserver.js';
+export type { UseResizeObserverOptions, UseResizeObserverResult, } from './useResizeObserver.js';
+export { usePrefersReducedMotion } from './usePrefersReducedMotion.js';
+export { usePrevious } from './usePrevious.js';
+export { useSessionStorage } from './useSessionStorage.js';
+export { useTitle } from './useTitle.js';

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

@@ -10,16 +10,19 @@ type UseHotkeysOptions = {
     eventName?: 'keydown' | 'keyup';
     /** 焦点在 input/textarea/select/contenteditable 内时是否仍触发（默认 `false`）。 */
     allowInInput?: boolean;
+    /** 序列快捷键相邻两步的最大间隔毫秒，超时清空进度（默认 `1000`）。 */
+    sequenceTimeout?: number;
 };
 /**
  * 组合多个快捷键规格为一条别名绑定（逗号连接），任一命中即触发同一
  * handler——对象字面量的键只能是字符串，数组规格经由本函数进入。
+ * 规格可以是单键组合或序列（含空白，如 `'g h'`）。
  *
  * ```tsx
  * useHotkeys({ [hotkey('mod+k', 'mod+j')]: cyclePalette });
  * ```
  *
- * @param specs 至少一个规格，如 `'mod+k'`、`'ctrl+shift+p'`。
+ * @param specs 至少一个规格，如 `'mod+k'`、`'ctrl+shift+p'`、`'g h'`。
  */
 export declare function hotkey(...specs: [string, ...string[]]): string;
 /**
@@ -32,6 +35,8 @@ export declare function hotkey(...specs: [string, ...string[]]): string;
  *   'ctrl+shift+p': openCommandPalette,
  *   '?': showHelp,                        // 符号键天然携带 shift，无需声明
  *   ArrowUp: selectPrev,                  // 命名键精确匹配
+ *   'g h': goHome,                        // 序列：先 g 再 h（步间默认 1s）
+ *   'ctrl+k g': goHome,                   // 修饰键组合可作序列元素
  *   [hotkey('mod+k', 'mod+j')]: cycle,     // 多规格别名：任一命中
  * }, { allowInInput: false });
  * ```
@@ -39,11 +44,18 @@ export declare function hotkey(...specs: [string, ...string[]]): string;
  * - 规格语法：`[修饰键+]*键`；修饰键别名 mod/ctrl/control/meta/cmd/⌘/
  *   shift/alt/option/⌥；`mod` 按平台归一（macOS ⌘，否则 ctrl，
  *   `navigator.platform` 判定，SSR 安全）。
+ * - 序列语法：空白分隔多个步骤（`'g h'`、`'ctrl+k g g'`），每步是独立的
+ *   规格并沿用严格修饰键校验（未声明的 ctrl/alt/meta 必须抬起）。相邻
+ *   两步间隔超过 `sequenceTimeout`（默认 1000ms）重置；中途按错键重置
+ *   ——但错键若本身是某序列的首步（如 `g g h` 的第二个 g）则从该键重新
+ *   起步，若命中任何单键绑定则照常触发该绑定并清空进度。推进中的步骤
+ *   不 `preventDefault`，序列完整命中才拦截事件；命中后进度清零，
+ *   同一序列可立即重新输入。
  * - 默认焦点在 input/textarea/select/contenteditable 时忽略全部快捷键，
  *   `allowInInput: true` 打开。
- * - 一个事件只触发第一个命中的绑定；`hotkeys` 映射每次渲染变化不重挂
- *   监听（latest-ref），`enabled/target/eventName/allowInInput` 变化才
- *   重新绑定。
+ * - 一个事件只触发第一个命中的绑定（含序列完成）；`hotkeys` 映射每次
+ *   渲染变化不重挂监听（latest-ref），`enabled/target/eventName/
+ *   allowInInput/sequenceTimeout` 变化才重新绑定（重绑会清空序列进度）。
  * - `enabled: false` 等价于不挂载监听。
  *
  * @param hotkeys 规格（或逗号连接的规格列表）到处理器的映射。