haze-ui 1.32.0 → 1.33.0

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

@@ -0,0 +1,30 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+/** Decomposed remaining time handed to `format`/`render`. */
+type CountdownParts = {
+    /** Whole seconds left — `ceil` of the exact milliseconds so every
+     * displayed second is a full second and the display lands on 0 exactly
+     * at the deadline. */
+    totalSeconds: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    /** Deadline reached — parts are all zero and the clock has stopped. */
+    finished: boolean;
+};
+type CountdownProps = {
+    /** Deadline: epoch milliseconds or a `Date`. Changing it re-aims the
+     * clock (and re-arms a spent `onFinish`). */
+    value: number | Date;
+    /** Fires exactly once when the deadline is reached. */
+    onFinish?: () => void;
+    /** Parts → display string. Default: adaptive — `1d 02:03:04` past a
+     * day, `02:03:04` under it. */
+    format?: (parts: CountdownParts) => string;
+    /** Parts → arbitrary node — the render escape hatch next to `format`
+     * for non-string output. */
+    render?: (parts: CountdownParts) => ReactNode;
+    className?: string;
+} & Omit<ComponentPropsWithoutRef<'span'>, 'children'>;
+export default function Countdown({ value, onFinish, format, render, className, ...rest }: CountdownProps): import("react").JSX.Element;
+export type { CountdownProps, CountdownParts };

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

@@ -0,0 +1,2 @@
+export { default as Countdown } from './Countdown';
+export type { CountdownProps, CountdownParts } from './Countdown';

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

@@ -20,6 +20,10 @@ import type { FloatingPlacement } from '../../utils/floating';
  * the panel cancels the pending close (the "resting zone"). Escape
  * closes at once (native popover light dismiss / the fallback path's
  * document keydown, both owned by useFloating).
+ *
+ * `interactive` upgrades the card to React Aria's PreviewTrigger
+ * semantics: focusable content, focus handoff trigger ↔ card, Escape
+ * returning focus to the trigger — see the prop for the contract.
  */
 type HoverCardProps = {
     /** Card content, rendered inside the floating panel. */
@@ -31,6 +35,19 @@ type HoverCardProps = {
      * before the card closes — long enough to travel into the panel.
      */
     closeDelay?: number;
+    /**
+     * Interactive card contents (React Aria PreviewTrigger semantics):
+     * focusable elements inside `content` join the Tab order and focus
+     * may travel between the trigger and the card without closing it.
+     * The pointer grace after leaving the trigger/panel defaults to
+     * 300 ms in this mode (vs 120 ms otherwise; an explicit `closeDelay`
+     * or a ConfigProvider default still overrides). While focus rests
+     * inside the card, pointer leaves alone no longer close it — Escape
+     * or tabbing out does, and Escape hands focus back to the trigger.
+     * Focus is deliberately NOT trapped: a hover card is a preview, not
+     * a modal, so Tab must keep reaching the rest of the page.
+     */
+    interactive?: boolean;
     /**
      * Panel placement relative to the trigger, in the floating utils'
      * physical convention ('bottom-span' aligns the panel's inline-start
@@ -45,5 +62,5 @@ type HoverCardProps = {
     /** The trigger — render a focusable element for keyboard access. */
     children: ReactNode;
 };
-export default function HoverCard({ content, openDelay: openDelayProp, closeDelay: closeDelayProp, placement, open: openControl, collisionPadding, className, children, }: HoverCardProps): import("react").JSX.Element;
+export default function HoverCard({ content, openDelay: openDelayProp, closeDelay: closeDelayProp, interactive, placement, open: openControl, collisionPadding, className, children, }: HoverCardProps): import("react").JSX.Element;
 export type { HoverCardProps };

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

@@ -0,0 +1,67 @@
+import type { ComponentPropsWithoutRef, Ref } from 'react';
+import type { ControlOrValue } from 'react-use-control';
+import type { CropRect } from './image-crop-geometry';
+/**
+ * Interactive image cropper — the avatar/photo companion to Upload.
+ *
+ * The source image is painted onto a `<canvas>` sized to its natural
+ * pixels (max detail; CSS scales it down), and the crop box is a DOM
+ * overlay positioned in percentages of the same box, so `value` needs no
+ * pixel measurement to render. `value` is the crop rectangle normalized
+ * to the image (every field 0..1) and fully controllable; every commit
+ * path (drag, handle resize, keyboard) runs through the same clamp
+ * pipeline, so an illegal rect can never display.
+ *
+ * Keyboard (the part competitors skip): the crop box is focusable and
+ * labeled. Arrow keys move it (1% of the image per press), Shift + arrow
+ * keys resize it — the Resizable handle's pointer-free contract in
+ * normalized space. A `visually-hidden` description announces the live
+ * geometry so screen readers track drags too.
+ *
+ * `ref.getCroppedCanvas()` rasterizes the current crop into a fresh
+ * `HTMLCanvasElement` (`null` when the image has not loaded or the 2d
+ * context is unavailable — jsdom without a mock). When the 2d context is
+ * unavailable the whole cropper degrades to a notice (Signature
+ * precedent): without paint there is no image to crop.
+ */
+type ImageCropProps = {
+    /** Image source URL. */
+    src: string;
+    /** Accessible name of the rendered image (carried by the canvas). */
+    alt: string;
+    /** Crop rectangle normalized to the image (every field 0..1); a
+     * Control receives every commit live, a plain object seeds it. */
+    value?: ControlOrValue<CropRect>;
+    /** Fires with the new normalized rect on every pointer frame and
+     * keyboard step. */
+    onChange?: (rect: CropRect) => void;
+    /** Locks the crop's pixel-space aspect ratio (width / height, e.g. `1`
+     * for avatars). Height derives from width; a rect that cannot fit
+     * refits from its height budget. */
+    aspect?: number;
+    /** Overlay mask of the crop box: rectangular frame or a full-radius
+     * circle for avatars (pair with `aspect={1}` for a true circle). */
+    shape?: 'rect' | 'circle';
+    /** Accessible label of the focusable crop region. */
+    cropLabel?: string;
+    /** Notice rendered when the canvas 2d context is unavailable. */
+    unsupportedLabel?: string;
+    /** Notice rendered when `src` fails to load. */
+    errorLabel?: string;
+    /** Locks dragging, handle resizing and keyboard operation. */
+    disabled?: boolean;
+    /** Passed to the loader `<img>`; `anonymous` is required for
+     * CORS-clean hosts or `getCroppedCanvas` output stays tainted. */
+    crossOrigin?: 'anonymous' | 'use-credentials';
+    className?: string;
+    ref?: Ref<ImageCropHandle>;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'onChange'>;
+/** Imperative surface exposed through the component `ref`. */
+type ImageCropHandle = {
+    /** Fresh canvas holding the current crop at native pixel resolution,
+     * or `null` when the image has not loaded / 2d context is missing. */
+    getCroppedCanvas: () => HTMLCanvasElement | null;
+};
+export default function ImageCrop({ src, alt, value: valueControl, onChange, aspect, shape, cropLabel, unsupportedLabel, errorLabel, disabled, crossOrigin, className, ref, ...rest }: ImageCropProps): import("react").JSX.Element;
+export type { ImageCropProps, ImageCropHandle };
+export type { CropRect } from './image-crop-geometry';

package/dist/types/components/ImageCrop/image-crop-geometry.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure geometry for ImageCrop — every exported helper works in normalized
+ * space (0..1 relative to the image's own pixel box) so pointer, keyboard
+ * and aspect math share one clamp story. Unit tests exercise these
+ * directly (the signature-points precedent).
+ */
+/** Normalized crop rectangle: top-left corner (x, y) and size, every
+ * field 0..1 relative to the image's own pixel box. */
+export type CropRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Natural pixel size of the loaded source image. */
+export type NaturalSize = {
+    width: number;
+    height: number;
+};
+/** Corner handles of the crop box. */
+export type CropCorner = 'nw' | 'ne' | 'sw' | 'se';
+/** Size floor for the crop box on both axes — a box smaller than this is
+ * no longer grabbable and crops to a degenerate image. */
+export declare const MIN_CROP = 0.05;
+/** Keyboard step for arrow keys: 1% of the image per press (the Resizable
+ * handle's fully-pointer-free contract, scaled to normalized space). */
+export declare const KEYBOARD_STEP = 0.01;
+/** Fit a rect to a locked pixel-space aspect ratio. Width drives; when
+ * the derived height overflows the unit square the height clamps to 1
+ * and the width re-derives from it. Position keeps x/y, clamped so the
+ * box stays inside the image. */
+export declare function fitAspect(rect: CropRect, aspect: number, natural: NaturalSize): CropRect;
+/** Clamp any rect into a legal crop: sizes into [MIN_CROP, 1] — with an
+ * aspect refit when the ratio is locked — and the position so the box
+ * stays inside the unit square. Display and every commit path run
+ * through this, so a stale or consumer-supplied value can never paint an
+ * illegal box. */
+export declare function normalizeRect(rect: CropRect, aspect: number | undefined, natural: NaturalSize): CropRect;
+/** Centered default crop covering 80% of the image (aspect-refit first —
+ * a square crop of a wide image saturates height before width, then the
+ * smaller box recenters). */
+export declare function defaultRect(aspect: number | undefined, natural: NaturalSize): CropRect;
+/** Translate by (dx, dy) — position clamps inside the image, size is
+ * frozen (the keyboard move contract). */
+export declare function moveRect(rect: CropRect, dx: number, dy: number): CropRect;
+/** Keyboard resize anchored at the top-left corner: dw/dh grow the box
+ * towards the right/bottom. With a locked aspect both axes drive the
+ * shared width (dh is translated through the aspect factor), so all four
+ * Shift+arrow keys stay functional. */
+export declare function resizeRect(rect: CropRect, dw: number, dh: number, aspect: number | undefined, natural: NaturalSize): CropRect;
+/** Corner-handle resize: the opposite corner stays anchored and the
+ * dragged corner follows the normalized pointer. Dragging across the
+ * anchor floors at MIN_CROP instead of inverting; a locked aspect fits
+ * width-first, clamped to the space the anchor leaves. */
+export declare function resizeFromAnchor(start: CropRect, corner: CropCorner, pointer: {
+    x: number;
+    y: number;
+}, aspect: number | undefined, natural: NaturalSize): CropRect;
+/** Frame-relative normalized pointer position from client coordinates.
+ * The width/height guards keep a zero-sized rect (jsdom, not-yet-laid-out
+ * frames) from producing NaN instead of merely useless numbers. */
+export declare function pointerToNormalized(clientX: number, clientY: number, frame: DOMRect): {
+    x: number;
+    y: number;
+};

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

@@ -0,0 +1,3 @@
+export { default as ImageCrop } from './ImageCrop';
+export type { ImageCropHandle, ImageCropProps } from './ImageCrop';
+export type { CropRect } from './image-crop-geometry';

package/dist/types/components/LocaleProvider/locale.d.ts

@@ -228,6 +228,12 @@ declare const defaultStrings: {
     spinner: {
         loading: string;
     };
+    splitter: {
+        collapseLead: string;
+        expandLead: string;
+        collapseTrail: string;
+        expandTrail: string;
+    };
     sources: {
         label: string;
         expand: string;

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

@@ -1,4 +1,2 @@
 export { ResizableGroup, ResizablePanel, ResizableHandle } from './Resizable';
 export type { ResizableGroupProps, ResizablePanelProps, ResizableHandleProps, } from './Resizable';
-export { ResizableGroup as SplitterGroup, ResizablePanel as SplitterPanel, ResizableHandle as SplitterHandle, } from './Resizable';
-export type { ResizableGroupProps as SplitterGroupProps, ResizablePanelProps as SplitterPanelProps, ResizableHandleProps as SplitterHandleProps, } from './Resizable';

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

@@ -0,0 +1,33 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ControlOrValue } from 'react-use-control';
+type SplitterProps = {
+    /** Layout axis: horizontal stacks panes left-to-right, vertical
+     * top-to-bottom. */
+    orientation?: 'horizontal' | 'vertical';
+    /** Pane sizes in percent of the pane area (the container minus the
+     * dividers), one entry per pane, summing to 100. Accepts a Control for
+     * controlled usage or a plain array as the uncontrolled initial
+     * value (equal split when omitted). */
+    sizes?: ControlOrValue<number[]>;
+    /** Fired on every applied change — pointer moves and keyboard steps
+     * alike — with the full next sizes array. */
+    onSizesChange?: (sizes: number[]) => void;
+    children?: ReactNode;
+    className?: string;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
+export declare function Splitter({ orientation, sizes: sizesControl, onSizesChange, children, className, ...rest }: SplitterProps): import("react").JSX.Element;
+type SplitterPaneProps = {
+    /** Minimum size in percent of the pane area. */
+    min?: number;
+    /** Maximum size in percent of the pane area. */
+    max?: number;
+    /** Opt the pane into divider collapse triggers: every divider
+     * touching it grows a button that zeroes the pane (the partner
+     * absorbs its share) and, once collapsed, expands it back to its
+     * pre-collapse size. */
+    collapsible?: boolean;
+    children?: ReactNode;
+    className?: string;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'min' | 'max'>;
+export declare function SplitterPane({ min, max, collapsible, children, className, ...rest }: SplitterPaneProps): import("react").JSX.Element;
+export type { SplitterProps, SplitterPaneProps };

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

@@ -0,0 +1,2 @@
+export { Splitter, SplitterPane } from './Splitter';
+export type { SplitterProps, SplitterPaneProps } from './Splitter';

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

@@ -337,11 +337,12 @@ export { useClickOutside };
 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.
+ * `'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 };
 /**
@@ -357,7 +358,7 @@ export { hotkey };
 export type { HotkeyHandler } from '../hooks/useHotkeys';
 /**
  * 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';
 /**

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 规格（或逗号连接的规格列表）到处理器的映射。

package/dist/types/index.d.ts

@@ -106,8 +106,8 @@ export { Command, CommandInput, CommandList, CommandItem, CommandGroup, CommandD
 export type { CommandProps, CommandInputProps, CommandListProps, CommandItemProps, CommandGroupProps, CommandDialogProps } from './components/Command';
 export { ResizableGroup, ResizablePanel, ResizableHandle } from './components/Resizable';
 export type { ResizableGroupProps, ResizablePanelProps, ResizableHandleProps } from './components/Resizable';
-export { SplitterGroup, SplitterPanel, SplitterHandle, } from './components/Resizable';
-export type { ResizableGroupProps as SplitterGroupProps, ResizablePanelProps as SplitterPanelProps, ResizableHandleProps as SplitterHandleProps, } from './components/Resizable';
+export { Splitter, SplitterPane } from './components/Splitter';
+export type { SplitterProps, SplitterPaneProps } from './components/Splitter';
 export { Collapsible, CollapsibleTrigger, CollapsibleContent } from './components/Collapsible';
 export type { CollapsibleProps, CollapsibleTriggerProps, CollapsibleContentProps, CollapsibleClassNames } from './components/Collapsible';
 export { Transfer, TransferCore } from './components/Transfer';
@@ -127,6 +127,8 @@ export { Ellipsis } from './components/Ellipsis';
 export type { EllipsisProps } from './components/Ellipsis';
 export { CountUp } from './components/CountUp';
 export type { CountUpProps } from './components/CountUp';
+export { Countdown } from './components/Countdown';
+export type { CountdownProps, CountdownParts } from './components/Countdown';
 export { Sparkline, sparklineToneStrokes, sparklineToneFills } from './components/Sparkline';
 export type { SparklineProps } from './components/Sparkline';
 export type { StatProps, StatGroupProps } from './components/Stat';
@@ -290,6 +292,9 @@ export { Masonry } from './components/Masonry';
 export type { MasonryProps } from './components/Masonry';
 export { Signature } from './components/Signature';
 export type { SignatureProps } from './components/Signature';
+export { ImageCrop } from './components/ImageCrop';
+export type { ImageCropHandle, ImageCropProps } from './components/ImageCrop';
+export type { CropRect } from './components/ImageCrop';
 export { useTitle, useMediaQuery, usePrefersReducedMotion, useDebouncedValue, useDebouncedCallback, useDarkMode, useClipboard, useFullscreen, } from './hooks';
 export type { UseClipboardResult } from './hooks';
 export type { FullscreenTarget, UseFullscreenHandle } from './hooks';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haze-ui",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "type": "module",
   "description": "A React UI component library powered by react-use-control and Linaria",
   "main": "./dist/index.js",
@@ -101,6 +101,7 @@
   ],
   "author": "wmzy",
   "license": "MIT",
+  "homepage": "https://wmzy.github.io/haze-ui/",
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
@@ -175,7 +176,7 @@
       "name": "Button only (bundled from barrel)",
       "path": "dist/index.js",
       "import": "{Button}",
-      "limit": "5.75 KB"
+      "limit": "5.85 KB"
     },
     {
       "name": "TagGroup+TagGroupItem only — dnd-free (bundled from barrel)",
@@ -204,11 +205,11 @@
     {
       "name": "CSS aggregate (dist/haze-ui.css, brotli)",
       "path": "dist/haze-ui.css",
-      "limit": "26.25 KB"
+      "limit": "27 KB"
     },
     {
       "path": "dist/haze-ui.css",
-      "limit": "35 KB",
+      "limit": "36 KB",
       "gzip": true
     },
     {
@@ -229,6 +230,24 @@
       "limit": "0.3 KB",
       "gzip": true
     },
+    {
+      "name": "CSS family ratchet: countdown",
+      "path": "dist/css/countdown.css",
+      "limit": "0.2 KB",
+      "gzip": true
+    },
+    {
+      "name": "CSS family ratchet: splitter",
+      "path": "dist/css/splitter.css",
+      "limit": "1 KB",
+      "gzip": true
+    },
+    {
+      "name": "CSS family ratchet: image-crop",
+      "path": "dist/css/image-crop.css",
+      "limit": "0.85 KB",
+      "gzip": true
+    },
     {
       "name": "CSS family ratchet: sparkline",
       "path": "dist/css/sparkline.css",