haze-ui 1.26.0 → 1.28.0

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

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react';
+import type { ToastClassNames } from './Toast';
 type ToastPlacement = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 type ToastContainerProps = {
     children: ReactNode;
@@ -6,6 +7,15 @@ type ToastContainerProps = {
     maxCount?: number;
     /** Viewport edge the stack is pinned to. */
     placement?: ToastPlacement;
+    /**
+     * Semantic slot classes (AntD v6 `classNames` shape) for the whole
+     * toast family — `viewport` lands on the fixed stack this container
+     * renders, `item`/`content`/`close` flow to every toast (see
+     * {@link ToastClassNames}). Toasts are fired imperatively through
+     * `useToast()`/`toast()`, so this prop is the one place to theme
+     * them. Omitting it changes nothing.
+     */
+    classNames?: ToastClassNames;
 };
 export declare const toastPlacements: {
     readonly 'top-left': import("@linaria/core").LinariaClassName;
@@ -13,5 +23,5 @@ export declare const toastPlacements: {
     readonly 'bottom-left': import("@linaria/core").LinariaClassName;
     readonly 'bottom-right': import("@linaria/core").LinariaClassName;
 };
-export default function ToastContainer({ children, maxCount, placement, }: ToastContainerProps): import("react").JSX.Element;
+export default function ToastContainer({ children, maxCount, placement, classNames, }: ToastContainerProps): import("react").JSX.Element;
 export type { ToastContainerProps, ToastPlacement };

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

@@ -1,15 +1,56 @@
 import type { ReactNode } from 'react';
+type ToastVariant = 'info' | 'success' | 'warning' | 'danger';
 type ToastItem = {
     id: number;
-    variant: 'info' | 'success' | 'warning' | 'danger';
+    variant: ToastVariant;
     content: ReactNode;
     duration: number;
 };
+/**
+ * Patch accepted by `toast.update(id, patch)` and `useToast().update(id,
+ * patch)`. Only fields present in the patch change; an omitted (or
+ * undefined) field keeps the toast's current value.
+ */
+type ToastUpdateOptions = {
+    /** Replacement message content. */
+    content?: ReactNode;
+    /** Replacement color variant. */
+    variant?: ToastVariant;
+    /** New auto-dismiss budget in ms. Changing it re-arms the countdown
+     * from the full value; leaving it out keeps the running countdown. */
+    duration?: number;
+};
+/** The `toast.promise` phases whose default copy lives in the locale pack. */
+type ToastDeferredCopyKey = 'loading' | 'success' | 'error';
+/**
+ * Sentinel ReactNode standing in for promise-phase copy that resolves
+ * against the locale pack at render time: `toast.promise` may fire from
+ * outside any React tree, so it cannot read `useStrings` itself — the
+ * container resolves the marker when it renders the toast. The sentinel
+ * rides the `content` channel as an opaque marker (cast once at the
+ * factory below); only the container ever interprets it.
+ */
+type ToastDeferredCopy = {
+    readonly deferredCopy: ToastDeferredCopyKey;
+};
+/** Creates the locale-deferred sentinel for one promise phase. */
+declare function deferredToastCopy(key: ToastDeferredCopyKey): ReactNode;
+declare function deferredCopyKey(node: ReactNode): ToastDeferredCopyKey | null;
+/**
+ * Pure merge of an update patch onto a toast item: keys absent (or
+ * undefined) in the patch keep the item's current value, so an update
+ * never clobbers fields it did not name.
+ */
+declare function applyToastPatch(item: ToastItem, patch: ToastUpdateOptions): ToastItem;
 type ToastContextValue = {
     toasts: ToastItem[];
-    addToast: (toast: Omit<ToastItem, 'id'>) => void;
+    addToast: (toast: Omit<ToastItem, 'id'>) => number;
     removeToast: (id: number) => void;
+    /** Patches a live toast in place — the same id and React key, so the
+     * enter/exit animations never replay (see `toast.update`). */
+    updateToast: (id: number, patch: ToastUpdateOptions) => void;
 };
 export declare const ToastProvider: import("react").Provider<ToastContextValue | undefined>;
 export declare function useToastContext(): ToastContextValue;
-export type { ToastItem, ToastContextValue };
+export { applyToastPatch, deferredCopyKey, deferredToastCopy, };
+export type { ToastDeferredCopy, ToastDeferredCopyKey, ToastItem, ToastContextValue, ToastUpdateOptions, ToastVariant, };

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

@@ -1,5 +1,5 @@
 export { default as Toast } from './Toast';
-export type { ToastProps } from './Toast';
+export type { ToastProps, ToastClassNames } from './Toast';
 export { default as ToastContainer } from './ToastContainer';
 export type { ToastContainerProps } from './ToastContainer';
 export { default as useToast } from './useToast';

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

@@ -1,6 +1,5 @@
 import type { ReactNode } from 'react';
-import type { ToastItem } from './ToastContext';
-type ToastVariant = ToastItem['variant'];
+import type { ToastDeferredCopyKey, ToastItem, ToastUpdateOptions, ToastVariant } from './ToastContext';
 /** Options accepted by `toast()` — the same call shape `useToast()` takes. */
 type ToastOptions = {
     variant?: ToastVariant;
@@ -8,10 +7,29 @@ type ToastOptions = {
 };
 /** Options accepted by the variant sugar methods (`toast.success()` …). */
 type ToastVariantOptions = Omit<ToastOptions, 'variant'>;
+/** Copy for one `toast.promise` phase: a literal, or derived from the
+ * settled value / rejection when the promise settles. */
+type ToastPhaseContent<T> = ReactNode | ((data: T) => ReactNode);
+/** Options accepted by `toast.promise(promise, options)`. */
+type ToastPromiseOptions<T> = {
+    /** Copy shown while the promise is pending. Defaults to the locale
+     * pack's `toast.loading`. The loading toast never auto-dismisses. */
+    loading?: ReactNode;
+    /** Copy shown once the promise resolves; a function receives the
+     * resolved value. Defaults to the locale pack's `toast.success`. */
+    success?: ToastPhaseContent<T>;
+    /** Copy shown once the promise rejects; a function receives the
+     * rejection value. Defaults to the locale pack's `toast.error`. */
+    error?: ToastPhaseContent<unknown>;
+    /** Auto-dismiss delay in ms applied once the promise settles — the
+     * loading toast stays until then. Defaults to 3000. */
+    duration?: number;
+};
 /** Sink a mounted `ToastContainer` registers to receive imperative calls. */
 type ToastChannel = {
     onToast: (item: ToastItem) => void;
     onDismiss: (id?: number) => void;
+    onUpdate: (id: number, patch: ToastUpdateOptions) => void;
 };
 /**
  * The single id sequence, shared by this module and the container's
@@ -21,7 +39,8 @@ export declare function nextToastId(): number;
 /**
  * Fires a toast without `useToast` — module-level, callable from anywhere
  * (outside React, in event callbacks, before a container has mounted).
- * Returns the toast id, usable with `toast.dismiss(id)`.
+ * Returns the toast id, usable with `toast.dismiss(id)` and
+ * `toast.update(id, patch)`.
  *
  * Mirrors the `useToast()` call shape (content + `{variant, duration}`,
  * defaulting to `info` / 3000ms). With no container mounted the toast is
@@ -35,7 +54,19 @@ declare namespace toast {
     var warning: (content: ReactNode, options?: ToastVariantOptions) => number;
     var danger: (content: ReactNode, options?: ToastVariantOptions) => number;
     var dismiss: (id?: number) => void;
+    var update: (id: number, patch: ToastUpdateOptions) => void;
+    var promise: <T>(p: Promise<T>, options?: ToastPromiseOptions<T>) => Promise<T>;
 }
+/**
+ * Shared engine behind `toast.promise` and `useToast().promise`: fires the
+ * loading toast through `show` (persistent — duration 0), then patches it
+ * in place when the promise settles, so the toast never remounts and its
+ * animations never replay. Returns the original promise untouched:
+ * rejections keep propagating to the caller's `await`/`catch`, and a
+ * loading toast dismissed before settling is simply not found by the
+ * update — it never resurrects.
+ */
+export declare function driveToastPromise<T>(show: (content: ReactNode, options?: ToastOptions) => number, updateById: (id: number, patch: ToastUpdateOptions) => void, promise: Promise<T>, options?: ToastPromiseOptions<T>): Promise<T>;
 /**
  * Called from `ToastContainer`'s mount effect. The first subscriber also
  * replays everything queued before any container existed, in call order;
@@ -43,4 +74,4 @@ declare namespace toast {
  */
 export declare function subscribeToastChannel(channel: ToastChannel): () => void;
 export { toast };
-export type { ToastOptions, ToastVariant, ToastVariantOptions };
+export type { ToastDeferredCopyKey, ToastOptions, ToastPhaseContent, ToastPromiseOptions, ToastUpdateOptions, ToastVariant, ToastVariantOptions, };

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

@@ -1,5 +1,17 @@
 import type { ReactNode } from 'react';
-export default function useToast(): (content: ReactNode, options?: {
-    variant?: "info" | "success" | "warning" | "danger";
-    duration?: number;
-}) => void;
+import type { ToastOptions, ToastPromiseOptions, ToastUpdateOptions } from './toast';
+/**
+ * The `useToast()` return value: the toast trigger itself (returns the id,
+ * usable with `update`) plus `update` and `promise` — one-to-one with the
+ * module-level `toast` API, but routed through the enclosing container's
+ * context instead of the first-mounted channel subscriber.
+ */
+type ShowToast = {
+    (content: ReactNode, options?: ToastOptions): number;
+    /** Patches a toast in place — see `toast.update`. */
+    update: (id: number, patch: ToastUpdateOptions) => void;
+    /** Loading → success/danger lifecycle — see `toast.promise`. */
+    promise: <T>(promise: Promise<T>, options?: ToastPromiseOptions<T>) => Promise<T>;
+};
+export default function useToast(): ShowToast;
+export type { ShowToast };

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

@@ -0,0 +1,19 @@
+import type { ComponentPropsWithoutRef, Ref } from 'react';
+import type { ControlOrValue } from 'react-use-control';
+type ToggleProps = {
+    /** Whether the toggle is pressed; a control for full external ownership. */
+    pressed?: ControlOrValue<boolean>;
+    size?: 'sm' | 'md' | 'lg';
+    /** Equal padding on all sides — for icon-only square toggles. */
+    square?: boolean;
+    /** Forwarded to the underlying `<button>` — form bridges and
+     * `ref.current.focus()` reach. */
+    ref?: Ref<HTMLButtonElement>;
+} & Omit<ComponentPropsWithoutRef<'button'>, 'type' | 'aria-pressed'>;
+/**
+ * A momentary pressed-state button (aria-pressed) for one-shot modes —
+ * bold, mute, grid/list view. `pressed` is one prop, two modes: a plain
+ * boolean leaves state internal, a control hands ownership to the caller.
+ */
+export default function Toggle({ pressed: pressedControl, size, square, className, onClick, ref, ...rest }: ToggleProps): import("react").JSX.Element;
+export type { ToggleProps };

package/dist/types/components/Toggle/ToggleCore.d.ts

@@ -0,0 +1,23 @@
+import type { ComponentPropsWithoutRef, Ref } from 'react';
+type ToggleCoreProps = {
+    pressed: boolean;
+    onPressedChange: (pressed: boolean) => void;
+    /** Native click event passthrough — invoked with the DOM event after
+     * `onPressedChange`, so a spread can never override the controlled callback. */
+    onNativeClick?: ComponentPropsWithoutRef<'button'>['onClick'];
+    size?: 'sm' | 'md' | 'lg';
+    /** Equal padding on all sides — for icon-only square toggles. */
+    square?: boolean;
+    className?: string;
+    /** Forwarded to the `<button>` element. */
+    ref?: Ref<HTMLButtonElement>;
+} & Omit<ComponentPropsWithoutRef<'button'>, 'type' | 'aria-pressed'>;
+/**
+ * The controlled half of Toggle: a momentary pressed-state button
+ * (`<button aria-pressed>`) — one-shot commands like bold/mute, not the
+ * on/off *setting* that Switch's `role="switch"` carries. State never
+ * lives here: it renders `pressed` and reports clicks through
+ * `onPressedChange`, so the sugar (or any owner) owns the truth.
+ */
+export default function ToggleCore({ pressed, onPressedChange, onNativeClick, size, square, className, ref, ...rest }: ToggleCoreProps): import("react").JSX.Element;
+export type { ToggleCoreProps };

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

@@ -0,0 +1,4 @@
+export { default as Toggle } from './Toggle';
+export type { ToggleProps } from './Toggle';
+export { default as ToggleCore } from './ToggleCore';
+export type { ToggleCoreProps } from './ToggleCore';

package/dist/types/components/Toolbar/ToolbarToggle.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentPropsWithoutRef } from 'react';
+import type { ControlOrValue } from 'react-use-control';
+/**
+ * A toolbar item that toggles: ToolbarButton's skin and roving behavior
+ * with a pressed state of its own. `pressed` is self-contained by
+ * default (no external wiring needed) and switches to external ownership
+ * when passed a control. The pressed look is keyed off `aria-pressed`,
+ * so the visual state can never drift from what assistive tech announces.
+ */
+type ToolbarToggleProps = {
+    /** Whether the item is pressed; a control for full external ownership. */
+    pressed?: ControlOrValue<boolean>;
+    variant?: 'solid' | 'outline' | 'ghost';
+    size?: 'sm' | 'md' | 'lg';
+    /** Equal padding on all sides — for icon-only square items. */
+    square?: boolean;
+} & Omit<ComponentPropsWithoutRef<'button'>, 'type' | 'aria-pressed'>;
+export default function ToolbarToggle({ pressed: pressedControl, variant, size, square, className, onClick, ...rest }: ToolbarToggleProps): import("react").JSX.Element;
+export type { ToolbarToggleProps };

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

@@ -4,3 +4,5 @@ export { default as ToolbarButton } from './ToolbarButton';
 export type { ToolbarButtonProps } from './ToolbarButton';
 export { default as ToolbarSeparator } from './ToolbarSeparator';
 export type { ToolbarSeparatorProps } from './ToolbarSeparator';
+export { default as ToolbarToggle } from './ToolbarToggle';
+export type { ToolbarToggleProps } from './ToolbarToggle';

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

@@ -4,9 +4,9 @@ import type { FloatingPlacement } from '../../utils/floating';
 /** Why the tour closed: the last step's Done button vs. an early exit. */
 type TourCloseReason = 'done' | 'skip';
 /**
- * Step-card placement relative to the spotlighted target — physical
- * semantics, the anchorable subset of FloatingPlacement ('point' has no
- * meaning without a floating trigger pair).
+ * Step-card placement relative to the spotlighted target — logical
+ * semantics (mirrors under RTL, like FloatingPlacement), the anchorable
+ * subset ('point' has no meaning without a floating trigger pair).
  */
 type TourPlacement = Exclude<FloatingPlacement, 'point'>;
 type TourStep = {

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

@@ -1,3 +1,3 @@
-import type { TreeProps } from './types';
-export default function Tree({ treeData, multiple, checkable, checkStrictly, selectable, disabled, blockNode, showLine, showIcon, switcherIcon, loadingIcon, titleRender, iconRender, expandedKeys: expandedKeysControl, selectedKeys: selectedKeysControl, checkedKeys: checkedKeysControl, className, onExpand, onSelect, onCheck, }: TreeProps): import("react").JSX.Element;
-export type { TreeProps };
+import type { TreeProps, TreeVirtualizedConfig } from './types';
+export default function Tree({ treeData, multiple, checkable, checkStrictly, selectable, disabled, blockNode, showLine, showIcon, switcherIcon, loadingIcon, titleRender, iconRender, virtualized, loadData, searchValue, expandedKeys: expandedKeysControl, selectedKeys: selectedKeysControl, checkedKeys: checkedKeysControl, className, onExpand, onSelect, onCheck, }: TreeProps): import("react").JSX.Element;
+export type { TreeProps, TreeVirtualizedConfig };

package/dist/types/components/Tree/TreeItem.d.ts

@@ -15,12 +15,27 @@ type TreeItemProps = {
     switcherIcon?: ReactNode;
     loadingIcon?: ReactNode;
     loading: boolean;
+    /**
+     * Lazy loading is armed (`loadData` provided): a childless node
+     * without `isLeaf: true` renders as expandable instead of a leaf.
+     */
+    loadable?: boolean;
+    /** The last lazy load of this node rejected — show the retry note. */
+    loadFailed?: boolean;
+    /** Active search query — string titles highlight their matches. */
+    searchValue?: string;
     titleRender?: (node: TreeNodeData) => ReactNode;
     iconRender?: (node: TreeNodeData) => ReactNode;
     isLast: boolean[];
+    /**
+     * Roving-tabindex stop (WAI-ARIA tree pattern): `0` on the row that
+     * owns the tree's single tab stop, `-1` on every other row.
+     */
+    tabIndex: 0 | -1;
     onToggle: () => void;
     onSelect: () => void;
     onCheck: () => void;
+    onRetry?: () => void;
 };
-export default function TreeItem({ node, level, expanded, selected, checked, disabled, checkable, selectable, blockNode, showLine, showIcon, switcherIcon, loadingIcon: loadingIconProp, loading, titleRender, iconRender, isLast, onToggle, onSelect, onCheck, }: TreeItemProps): import("react").JSX.Element;
+export default function TreeItem({ node, level, expanded, selected, checked, disabled, checkable, selectable, blockNode, showLine, showIcon, switcherIcon, loadingIcon: loadingIconProp, loading, loadable, loadFailed, searchValue, titleRender, iconRender, isLast, tabIndex, onToggle, onSelect, onCheck, onRetry, }: TreeItemProps): import("react").JSX.Element;
 export {};

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

@@ -32,6 +32,20 @@ export type TreeState = {
     checkedKeys: string[];
     halfCheckedKeys: string[];
 };
+/**
+ * Virtualized windowing metrics for `Tree.virtualized`.
+ */
+export type TreeVirtualizedConfig = {
+    /** Scrollport height in px. Default `320`. */
+    height?: number;
+    /** Row height in px. Default `32` — the treeitem min-height (2rem). */
+    itemHeight?: number;
+    /**
+     * Extra rows kept mounted above/below the visible window. Defaults to
+     * `VirtualList`'s `5`.
+     */
+    overscan?: number;
+};
 /**
  * Tree 组件 Props
  */
@@ -62,6 +76,43 @@ export type TreeProps = {
     titleRender?: (node: TreeNodeData) => ReactNode;
     /** 自定义节点图标渲染 */
     iconRender?: (node: TreeNodeData) => ReactNode;
+    /**
+     * Render the tree through `VirtualList` so large trees mount only the
+     * visible window (plus overscan) instead of the full DOM list: the
+     * visible rows are flattened depth-first (depth indent preserved) and
+     * windowed. `false`/omitted (default) keeps the plain nested DOM
+     * path; an object additionally customizes row metrics.
+     * `expandedKeys`/`selectedKeys`/`checkedKeys` semantics are identical
+     * in both paths, and roving-tabindex keyboard navigation works the
+     * same way — focus moves `scrollToIndex` the target row into the
+     * window before focusing it.
+     */
+    virtualized?: boolean | TreeVirtualizedConfig;
+    /**
+     * Async child loading: called when a node **without** `children` and
+     * without `isLeaf: true` is expanded (by click, keyboard, controlled
+     * `expandedKeys`, or the auto-expanded ancestor path of a search hit).
+     *
+     * While the promise is pending the node's switcher shows the loading
+     * spinner; resolved children are merged into an internal cache, so
+     * collapsing and re-expanding does **not** request again. Cache entries
+     * are dropped when the controlled `treeData` no longer maps onto them
+     * (the key disappeared, or the node now ships children of its own —
+     * controlled data always wins). An empty array marks the node as a
+     * leaf. A rejected promise renders an inline "Load failed · Retry"
+     * affordance on the node row; expanding a failed node again also
+     * retries.
+     */
+    loadData?: (node: TreeNodeData) => Promise<TreeNodeData[]>;
+    /**
+     * Search filter: when non-empty, only nodes whose (string) title
+     * matches case-insensitively — plus the ancestor path leading to
+     * them — are rendered, ancestors auto-expanded so hits stay visible,
+     * and every match is wrapped in a token-styled `<mark>`. `titleRender`
+     * output is passed through untouched. When nothing matches, the
+     * localized empty state is shown.
+     */
+    searchValue?: string;
     /** （受控）展开的节点 */
     expandedKeys?: ControlOrValue<string[]>;
     /** （受控）选中的节点 */

package/dist/types/components/Tree/utils.d.ts

@@ -1,6 +1,79 @@
 import type { TreeNodeData } from './types';
+/**
+ * A visible tree row: one treeitem in the depth-first order the tree
+ * renders (parents before children, expanded subtrees only). Backs both
+ * the roving-tabindex keyboard navigation and the virtualized windowing,
+ * which need the flat "visible rows" list rather than the recursive
+ * structure.
+ */
+export type VisibleTreeRow = {
+    key: string;
+    node: TreeNodeData;
+    /** Nesting depth; 0 for roots — matches TreeItem's `level` prop. */
+    level: number;
+    /** Parent row's key; null for roots. */
+    parentKey: string | null;
+    /**
+     * showLine guide chain: one "is a last child" flag per ancestor level
+     * (length === level), the same chain the recursive render builds.
+     */
+    isLast: boolean[];
+    /**
+     * Tree-level or per-node disabled flag. Disabled rows render (and can
+     * be expanded through controlled `expandedKeys`) but are skipped as
+     * keyboard focus stops.
+     */
+    disabled: boolean;
+};
+/**
+ * Flatten the tree to its currently visible rows: children of a node are
+ * included only while that node is expanded — the exact visibility rule
+ * of the recursive render (`children?.length && expandedKeys.has(key)`).
+ */
+export declare function flattenVisibleTree(data: TreeNodeData[], expandedKeys: string[], treeDisabled: boolean): VisibleTreeRow[];
 export declare function flattenTreeData(data: TreeNodeData[]): TreeNodeData[];
 export declare function findNodeByKey(data: TreeNodeData[], key: string): TreeNodeData | null;
 export declare function getChildKeys(data: TreeNodeData[], parentKey: string): string[];
 export declare function getParentKey(data: TreeNodeData[], targetKey: string, parentKey?: string): string | null;
 export declare function getAllLeafKeys(data: TreeNodeData[]): string[];
+/**
+ * Case-insensitive `[start, end)` ranges of every non-overlapping
+ * occurrence of `query` inside `text`, left to right. Empty when the
+ * query is empty or absent.
+ */
+export declare function matchRanges(text: string, query: string): [number, number][];
+/** Does the node's own title match? Only string titles can match —
+ *  ReactNode titles stay searchable through their descendants. */
+export declare function nodeTitleMatches(node: TreeNodeData, query: string): boolean;
+/** Result of `filterTreeByQuery`. */
+export type FilteredTree = {
+    /** The pruned tree: matched nodes plus the ancestors leading to them. */
+    tree: TreeNodeData[];
+    /** Keys whose own title matched the query. */
+    matchedKeys: string[];
+    /** Keys of the strict ancestors of matches — auto-expanded while the
+     *  search is active so every hit stays visible. */
+    ancestorKeys: string[];
+};
+/**
+ * Filters the tree to the nodes whose own title matches `query`
+ * (case-insensitive) plus every ancestor on the path to them. Returns
+ * `null` when the query is empty (search inactive) so callers can keep
+ * the unfiltered data by reference.
+ */
+export declare function filterTreeByQuery(data: TreeNodeData[], query: string | undefined): FilteredTree | null;
+/**
+ * Overlays lazy-loaded children onto the controlled data: a childless
+ * node with a cache entry adopts the loaded array; an empty load marks
+ * the node as a leaf (the server said "no children"). Returns `data`
+ * untouched (same reference) when nothing is cached, so memoized
+ * downstream work stays stable.
+ */
+export declare function mergeLoadedChildren(data: TreeNodeData[], loaded: Record<string, TreeNodeData[]>): TreeNodeData[];
+/**
+ * Drops cache entries that no longer map onto the controlled data: keys
+ * that vanished, or nodes that now ship children of their own
+ * (controlled data wins over a stale load). Keeps the same reference
+ * when nothing is pruned.
+ */
+export declare function pruneLoadedChildren(loaded: Record<string, TreeNodeData[]>, data: TreeNodeData[]): Record<string, TreeNodeData[]>;

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

@@ -1,15 +1,59 @@
-import type { ReactNode } from 'react';
+import type { ReactNode, Ref } from 'react';
 import type { ControlOrValue } from 'react-use-control';
+import type { UploadFileStatus, UploadHandle, UploadListItemRender, UploadRequest } from './types';
 type UploadProps = {
     /** Selected files; uncontrolled (accumulating internally) when omitted. */
     value?: ControlOrValue<File[]>;
     accept?: string;
+    /** Renders the drag-and-drop drop area (default) or a plain
+     * click-only picker area — see `UploadCoreProps.droppable`. */
+    droppable?: boolean;
+    /** Gatekeeper for every picked or dropped file — see
+     * `UploadCoreProps.beforeUpload`. */
+    beforeUpload?: (file: File) => boolean | Promise<boolean>;
+    /** Cap for the committed list — see `UploadCoreProps.maxCount`. */
+    maxCount?: number;
     multiple?: boolean;
+    /** Custom upload executor — see `UploadCoreProps.request`. */
+    request?: UploadRequest;
+    /** Upload endpoint for the built-in XHR executor — see
+     * `UploadCoreProps.action`. */
+    action?: string;
+    /** HTTP method for `action` uploads (default `POST`). */
+    method?: string;
+    /** Extra request headers for `action` uploads. */
+    headers?: Record<string, string>;
+    /** Form field name carrying the file in `action` mode (default `file`). */
+    name?: string;
+    /** Extra form fields appended alongside the file in `action` mode. */
+    data?: Record<string, string | Blob>;
+    /** Picks only enter the list; uploads start via the `UploadHandle`
+     * ref — see `UploadCoreProps.manual`. */
+    manual?: boolean;
+    /** Built-in file list with progress and per-state actions — see
+     * `UploadCoreProps.showUploadList`. */
+    showUploadList?: boolean | {
+        itemRender?: UploadListItemRender;
+    };
+    /** Rendering style of the built-in list (`text` rows or a
+     * `picture-card` thumbnail grid) — see `UploadCoreProps.listType`. */
+    listType?: 'text' | 'picture-card';
+    /** Overrides the built-in remove-button label — see
+     * `UploadCoreProps.removeLabel`. */
+    removeLabel?: string;
+    /** Picks directories instead of files — see
+     * `UploadCoreProps.directory`. */
+    directory?: boolean;
+    /** Status-machine snapshot callback — see
+     * `UploadCoreProps.onStatusChange`. */
+    onStatusChange?: (files: UploadFileStatus[]) => void;
     /** Fires with the freshly picked files only — the accumulated list is
-     * the `value` channel (or internal state when uncontrolled). */
+     * the `value` channel (or internal state when uncontrolled).
+     * Removals and `clear()` do not fire this (they are not picks). */
     onChange?: (files: File[]) => void;
     className?: string;
     children?: ReactNode;
+    ref?: Ref<UploadHandle>;
 };
-export default function Upload({ value: valueControl, accept, multiple, onChange, className, children, }: UploadProps): import("react").JSX.Element;
+export default function Upload({ value: valueControl, accept, droppable, beforeUpload, maxCount, multiple, request, action, method, headers, name, data, manual, showUploadList, listType, removeLabel, directory, onStatusChange, onChange, className, children, ref, }: UploadProps): import("react").JSX.Element;
 export type { UploadProps };

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

@@ -1,15 +1,106 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
+import type { UploadFileStatus, UploadHandle, UploadListItemRender, UploadRequest } from './types';
 type UploadCoreProps = {
     /** The selected files — the field value, emitted verbatim (as the
      * complete next list) by `onChange`. */
     value: File[];
     /** Emits the next file list: a single pick replaces `value`, a
-     * `multiple` pick appends to it. */
+     * `multiple` pick appends to it. Removals from the built-in list
+     * (and `clear()`) also flow through here. */
     onChange: (files: File[]) => void;
+    /** Comma-separated accept tokens (`.txt`, `image/*`, `text/plain`) —
+     * the same grammar the native picker uses. Dropped files that do not
+     * match are discarded silently (the native dialog already enforces
+     * this for click picks). */
     accept?: string;
+    /** Gate for the drag-and-drop affordance. `true` (default) renders
+     * the dashed drop area with a drag-over highlight and accepts dropped
+     * files; `false` renders a plain click-only picker area. */
+    droppable?: boolean;
+    /** Gatekeeper applied to every file — click picks and drops alike —
+     * before it enters the value: return `false` (or a promise resolving
+     * to `false`) to drop the file. Verdicts for one pick are awaited
+     * together (`Promise.all`) and committed as a single `onChange` once
+     * every verdict resolved; the UI is not blocked while waiting.
+     * A refused file never enters the list, so it never uploads. */
+    beforeUpload?: (file: File) => boolean | Promise<boolean>;
+    /** Cap for the committed list. Applied last: existing entries win,
+     * then the freshly picked survivors; anything beyond the first
+     * `maxCount` entries is discarded silently. */
+    maxCount?: number;
+    /** A `multiple` pick appends to `value`, a single pick replaces it. */
     multiple?: boolean;
+    /**
+     * Custom upload executor. When given, every file entering the list
+     * (see `manual`) runs through it: call `options.onProgress` with a
+     * 0–100 percent, honor `options.signal` for cancellation, resolve on
+     * success and reject on failure. Takes precedence over `action`.
+     * Neither `request` nor `action` → pure collection mode, exactly the
+     * pre-executor behavior.
+     */
+    request?: UploadRequest;
+    /**
+     * Upload endpoint for the built-in XHR executor: the file is sent as
+     * multipart FormData (field `name`, extra fields `data`) with `method`
+     * and `headers`; progress is wired to `xhr.upload.onprogress` and
+     * cancellation to `xhr.abort()`. Ignored when `request` is given.
+     */
+    action?: string;
+    /** HTTP method for `action` uploads — defaults to `POST`. */
+    method?: string;
+    /** Extra request headers for `action` uploads. */
+    headers?: Record<string, string>;
+    /** Form field name carrying the file in `action` mode — defaults
+     * to `file`. */
+    name?: string;
+    /** Extra form fields appended alongside the file in `action` mode. */
+    data?: Record<string, string | Blob>;
+    /**
+     * `true` keeps picked files at `idle` — the upload only starts via
+     * the `UploadHandle` ref (`upload()`/`uploadAll()`). Only meaningful
+     * with `request` or `action`.
+     */
+    manual?: boolean;
+    /**
+     * Renders the built-in file list below the zone (default `false`):
+     * file name, live progress (reusing `Progress`), status icon and
+     * per-state actions — cancel while uploading, retry + remove on
+     * error, remove otherwise. Pass an `itemRender` to replace whole
+     * rows. Without `request`/`action` the list still tracks picks as
+     * `idle` rows with remove actions.
+     */
+    showUploadList?: boolean | {
+        itemRender?: UploadListItemRender;
+    };
+    /**
+     * Rendering style of the built-in list (default `text`): `text`
+     * rows, or a `picture-card` grid of square thumbnail cards —
+     * object-URL previews for image files (revoked once the card leaves),
+     * a type-icon fallback for the rest, an upload mask with the live
+     * percent, and a danger border + retry on error.
+     */
+    listType?: 'text' | 'picture-card';
+    /**
+     * Overrides the built-in remove-button label (list rows and
+     * picture-card corners); defaults to the locale string.
+     */
+    removeLabel?: string;
+    /**
+     * Picks directories instead of files: forwards the non-standard
+     * `webkitdirectory`/`directory` attributes to the hidden input, so
+     * the native dialog enumerates every file inside the chosen folder
+     * (combine with `multiple` so the whole tree stays in the list).
+     */
+    directory?: boolean;
+    /**
+     * Fires whenever the tracked entries change (added, removed, status
+     * or percent) with the complete snapshot in value order. Only tracks
+     * while `request`/`action` or `showUploadList` is in play.
+     */
+    onStatusChange?: (files: UploadFileStatus[]) => void;
     className?: string;
     children?: ReactNode;
-} & Omit<ComponentPropsWithoutRef<'div'>, 'value' | 'onChange' | 'children' | 'onClick' | 'onDrop' | 'onDragOver' | 'role' | 'tabIndex'>;
-export default function UploadCore({ value, onChange, accept, multiple, className, children, ...rest }: UploadCoreProps): import("react").JSX.Element;
+    ref?: Ref<UploadHandle>;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'value' | 'onChange' | 'children' | 'onClick' | 'onDrop' | 'onDragOver' | 'onDragEnter' | 'onDragLeave' | 'onKeyDown' | 'role' | 'tabIndex'>;
+export default function UploadCore({ value, onChange, accept, droppable, beforeUpload, maxCount, multiple, request, action, method, headers, name, data, manual, showUploadList, listType, removeLabel, directory, onStatusChange, className, children, ref, ...rest }: UploadCoreProps): import("react").JSX.Element;
 export type { UploadCoreProps };