haze-ui 1.26.0 → 1.27.0

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

@@ -18,9 +18,14 @@ type TreeItemProps = {
     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;
 };
-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, titleRender, iconRender, isLast, tabIndex, onToggle, onSelect, onCheck, }: 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,18 @@ 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;
     /** （受控）展开的节点 */
     expandedKeys?: ControlOrValue<string[]>;
     /** （受控）选中的节点 */

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

@@ -1,4 +1,36 @@
 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[];

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

@@ -1,15 +1,50 @@
-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;
+    };
+    /** 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, onStatusChange, onChange, className, children, ref, }: UploadProps): import("react").JSX.Element;
 export type { UploadProps };

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

@@ -1,15 +1,86 @@
-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;
+    };
+    /**
+     * 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, onStatusChange, className, children, ref, ...rest }: UploadCoreProps): import("react").JSX.Element;
 export type { UploadCoreProps };

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

@@ -0,0 +1,12 @@
+import type { UploadEntry, UploadListItemRender } from './types';
+type UploadListProps = {
+    /** Tracked rows, in value order. */
+    entries: UploadEntry[];
+    /** Replaces the default row rendering entirely. */
+    itemRender?: UploadListItemRender;
+    onRemove: (file: File) => void;
+    onRetry: (file: File) => void;
+    onCancel: (file: File) => void;
+};
+export default function UploadList({ entries, itemRender, onRemove, onRetry, onCancel, }: UploadListProps): import("react").JSX.Element;
+export type { UploadListProps };

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

@@ -2,3 +2,4 @@ export { default as Upload } from './Upload';
 export type { UploadProps } from './Upload';
 export { default as UploadCore } from './UploadCore';
 export type { UploadCoreProps } from './UploadCore';
+export type { UploadHandle, UploadStatus, UploadFileStatus, UploadRequest, UploadRequestOptions, UploadListItemActions, UploadListItemRender, } from './types';

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

@@ -0,0 +1,60 @@
+import type { ReactNode } from 'react';
+/** Lifecycle of one tracked file while an upload executor (`request`
+ * or `action`) is armed. */
+type UploadStatus = 'idle' | 'uploading' | 'success' | 'error';
+/** Status snapshot for one tracked file — the shape surfaced through
+ * `onStatusChange` and `showUploadList.itemRender`. */
+type UploadFileStatus = {
+    file: File;
+    status: UploadStatus;
+    /** 0–100, clamped; forced to 100 when the upload succeeds. */
+    percent: number;
+};
+/** Runtime handed to a custom `request` (and used internally by the
+ * XHR wrapper that `action` mode builds). */
+type UploadRequestOptions = {
+    /** Report progress; values are clamped to 0–100. */
+    onProgress: (percent: number) => void;
+    /** Aborted when the upload is cancelled, removed or cleared — wire
+     * it to the underlying transport. */
+    signal: AbortSignal;
+};
+/** Custom upload executor: resolve on success, reject on failure.
+ * Rejecting with an `AbortError` `DOMException` (or after `signal`
+ * aborted) maps the file back to `idle` instead of `error`. */
+type UploadRequest = (file: File, options: UploadRequestOptions) => Promise<void>;
+/** Row-level callbacks handed to a custom `itemRender`. */
+type UploadListItemActions = {
+    /** Abort the upload if in flight, then drop the file from the list. */
+    remove: () => void;
+    /** Re-run the upload. No-op unless the file errored. */
+    retry: () => void;
+    /** Abort the in-flight upload and drop the file (uploading state). */
+    cancel: () => void;
+};
+/** Custom renderer replacing a built-in list row. */
+type UploadListItemRender = (file: File, status: UploadStatus, percent: number, actions: UploadListItemActions) => ReactNode;
+/**
+ * Imperative surface (`ref.current?.…`) — the same React 19
+ * ref-as-prop channel `DialogHandle` uses:
+ *
+ * - `upload(file?)` — start every pending file (idle or error); with a
+ *   `file`, (re)start just that one.
+ * - `uploadAll()` — (re)start every file that is not currently
+ *   uploading, successful ones included.
+ * - `abort()` — abort every in-flight upload; aborted files return to
+ *   `idle` and stay in the list.
+ * - `clear()` — abort everything and empty the list (`onChange([])`).
+ */
+type UploadHandle = {
+    upload: (file?: File) => void;
+    uploadAll: () => void;
+    abort: () => void;
+    clear: () => void;
+};
+/** Internal tracked row: public status snapshot plus the stable uid the
+ * list keys on (File objects have no serializable identity). */
+type UploadEntry = UploadFileStatus & {
+    uid: string;
+};
+export type { UploadStatus, UploadFileStatus, UploadRequestOptions, UploadRequest, UploadListItemActions, UploadListItemRender, UploadHandle, UploadEntry, };

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

@@ -0,0 +1,20 @@
+import type { UploadRequest } from './types';
+type XhrUploadConfig = {
+    /** Upload endpoint URL. */
+    action: string;
+    /** HTTP method — defaults to `POST`. */
+    method?: string;
+    /** Extra request headers. */
+    headers?: Record<string, string>;
+    /** Form field name carrying the file — defaults to `file`. */
+    name?: string;
+    /** Extra form fields appended alongside the file. */
+    data?: Record<string, string | Blob>;
+};
+/** Builds the executor used when only `action` (plus optional
+ * `method`/`headers`/`name`/`data`) is given: a multipart FormData
+ * upload via XHR with progress wired to `xhr.upload.onprogress` and
+ * abort wired to `xhr.abort()`. */
+declare function createXhrRequest(config: XhrUploadConfig): UploadRequest;
+export type { XhrUploadConfig };
+export { createXhrRequest };

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

@@ -57,8 +57,23 @@ type VirtualListProps<T> = {
     renderItem: (item: T, index: number) => ReactNode;
     /** Extra rows kept mounted above/below the visible window. */
     overscan?: number;
+    /**
+     * Chat orientation (opt-in): rows anchor to the scrollport bottom with
+     * index 0 at the bottom edge and later indices stacking upward — the
+     * natural geometry for a newest-at-bottom log where new items are
+     * prepended. The viewport parks at the bottom on mount and stays glued
+     * there across appends while the user is parked at the bottom; a
+     * reader who scrolled up keeps their position (rows keep their
+     * top-origin coordinates as content grows upward, so nothing jumps).
+     *
+     * `scrollToIndex` keeps its signature; alignments mirror vertically —
+     * `'start'` pins the row's bottom edge to the viewport bottom,
+     * `'end'` its top edge to the viewport top. The `VirtualListHandle`
+     * API is unchanged.
+     */
+    reverse?: boolean;
     className?: string;
     ref?: Ref<VirtualListHandle>;
 } & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
-export default function VirtualList<T>({ items, height, itemHeight, estimatedItemHeight, groups, renderItem, overscan, className, style, ref, ...rest }: VirtualListProps<T>): import("react").JSX.Element;
+export default function VirtualList<T>({ items, height, itemHeight, estimatedItemHeight, groups, renderItem, overscan, reverse, className, style, ref, ...rest }: VirtualListProps<T>): import("react").JSX.Element;
 export type { VirtualListProps, VirtualListHandle, VirtualListGroup, VirtualListAlign, };

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

@@ -0,0 +1,32 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+export type WatermarkFont = {
+    /** Font size in px (canvas metrics, not CSS). */
+    size?: number;
+    /** Any CSS color; defaults to the theme's `--haze-color-text-muted`. */
+    color?: string;
+    /** Numeric font weight. */
+    weight?: number;
+    /** CSS font-family stack; falls back to the page's sans stack. */
+    family?: string;
+};
+type WatermarkProps = {
+    /** Watermark text; an array renders stacked lines. */
+    content: string | string[];
+    /** Typography of the drawn text. */
+    font?: WatermarkFont;
+    /** Rotation in degrees. */
+    rotate?: number;
+    /** Space between tiles, in px — one number or `[x, y]`. */
+    gap?: number | [number, number];
+    /** `[x, y]` offset of the tile grid origin, in px. */
+    offset?: [number, number];
+    /** Overlay stacking order. */
+    zIndex?: number;
+    /** Span the whole viewport (fixed) instead of the container. */
+    fullscreen?: boolean;
+    /** Content to watermark; with children the component becomes its container. */
+    children?: ReactNode;
+    className?: string;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'className' | 'content'>;
+export default function Watermark({ content, font, rotate, gap, offset, zIndex, fullscreen, children, className, style, ...rest }: WatermarkProps): import("react").JSX.Element;
+export type { WatermarkProps };

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

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

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

@@ -1,5 +1,5 @@
 import type { ComponentPropsWithoutRef, ComponentType, ReactNode } from 'react';
-import type { FieldError, FieldPath, FieldRules, Name, ValidationMode, FormInstance, PathValueOf } from 'react-f0rm';
+import type { FieldError, FieldPath, FieldRules, Name, Path, ValidationMode, FormInstance, PathValueOf } from 'react-f0rm';
 /**
  * Field-level validator, structurally compatible with react-f0rm's
  * `Validator`: return an error (string, FieldError, or an array mixing
@@ -11,9 +11,15 @@ import type { FieldError, FieldPath, FieldRules, Name, ValidationMode, FormInsta
  * the value argument is `PathValueOf<TValues, P>` — the field's actual
  * type — instead of `any`. The bare defaults keep untyped call sites
  * exactly as permissive as before.
+ *
+ * The `meta` shape mirrors react-f0rm's `Validator` (`form`/`path`/
+ * `signal`) on purpose, so its resolver adapters — `zodResolver`,
+ * `standardSchemaResolver` from `react-f0rm/resolvers/*` — slot straight
+ * into `FormItem`'s `validate` prop without a wrapper.
  */
 export type FieldValidator<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name> = (value: PathValueOf<TValues, P>, meta: {
     form: FormInstance;
+    path: Path;
     signal: AbortSignal;
 }) => string | FieldError | (string | FieldError)[] | undefined | Promise<string | FieldError | (string | FieldError)[] | undefined>;
 /** Render binding handed to `FormItem`'s render-prop children. */
@@ -37,6 +43,15 @@ export type FormItemBinding<TValues, P extends FieldPath<TValues> | Name> = {
      * It routes through the same mode-gated, re-validating pipeline as
      * react-f0rm's built-in Field/Checkbox/Select. */
     onChange: (next: PathValueOf<TValues, P>) => void;
+    /**
+     * react-f0rm's focus channel (callback ref): attach it to the
+     * control's `ref` (`<InputCore ref={focusRef} />`) so
+     * `setFocus(form, name)` and a failed submit's first-error
+     * auto-focus can reach this field's element. Without it, focus
+     * requests aimed at this field are silent no-ops (react-f0rm's
+     * `setFocus` contract).
+     */
+    focusRef: (el: any) => void;
 };
 /**
  * Declarative `as` binding for `FormItem` — the same props shape as
@@ -87,7 +102,12 @@ export type FormItemRawElementBinding<TRawElement extends FormItemRawElement = F
  * consumes regardless of how the control is bound (render-prop, `as`
  * or `input`). */
 export type FormItemOwnProps<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name> = {
-    form: FormInstance<TValues>;
+    /**
+     * 表单实例（`useForm()`/`createForm()` 的返回值）。可省略：省略时从
+     * 最近的 `<FormProvider value={form}>` 读取（react-f0rm 的 form
+     * context），显式传入的 `form` 总是优先。两者都没有时 throw。
+     */
+    form?: FormInstance<TValues>;
     name: P;
     label?: ReactNode;
     /** Field-level validator, registered through react-f0rm's own
@@ -131,6 +151,9 @@ export type FormItemOwnProps<TValues extends Record<string, any> = any, P extend
  */
 type FormItemWiredProps = {
     id?: unknown;
+    /** the focus channel: react-f0rm's `focusRef` rides the control's
+     * `ref` — `setFocus` and failed-submit auto-focus depend on it */
+    ref?: unknown;
     onBlur?: unknown;
     onChange?: unknown;
     /** the value channel: `value` directly, or the prop `valueToProps`
@@ -231,11 +254,13 @@ export type FormItemProps<TValues extends Record<string, any> = any, P extends F
  *
  * With `as`, the id/aria/onBlur/onChange wiring happens here: the control
  * gets `id`, `aria-invalid`/`aria-describedby` while the field errors,
- * and `onChange={(v) => onChange(toValue(v))}` where `toValue` defaults
+ * `onChange={(v) => onChange(toValue(v))}` where `toValue` defaults
  * to identity (haze cores emit plain values — pass
  * `eventToValue={(e) => e.target.value}` for a raw DOM element) and the
  * value lands as `{value}` or, with `valueToProps`, whatever props the
- * control wants (e.g. `{checked}` for CheckboxCore).
+ * control wants (e.g. `{checked}` for CheckboxCore). react-f0rm's focus
+ * channel rides the control's `ref`, so `setFocus(form, name)` and a
+ * failed submit's first-error auto-focus reach the field's element.
  *
  * The ergonomic form for haze-ui cores is `input`: the rest of the JSX
  * props — and JSX children, e.g. a `SelectCore`'s `<option>`s — are
@@ -252,10 +277,10 @@ export type FormItemProps<TValues extends Record<string, any> = any, P extends F
  * />
  * ```
  *
- * The same wiring as `as` applies (id, aria, onBlur, onChange, value);
- * wired and FormItem-owned prop names are reserved — a control prop that
- * collides (CheckboxCore's `label`) needs the render-prop or
- * `as`/`asProps` channel.
+ * The same wiring as `as` applies (id, aria, onBlur, onChange, value,
+ * and the `ref`-riding focus channel); wired and FormItem-owned prop
+ * names are reserved — a control prop that collides (CheckboxCore's
+ * `label`) needs the render-prop or `as`/`asProps` channel.
  *
  * `input` also accepts raw DOM bindings — no core required:
  *

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

@@ -0,0 +1,113 @@
+import type { ReactNode } from 'react';
+import type { FieldPath, FieldRules, FormInstance, Name } from 'react-f0rm';
+/**
+ * `fields` 数组的元素 —— react-f0rm `useFieldArray` 的行描述透传：
+ * 稳定行 key、当前索引，以及 `keyName` 指定属性名下的同值别名
+ * （默认 `id`，自定义名如 `'key'` 用于避开行数据自带的同名字段）。
+ */
+export type FormListField<K extends string = 'id'> = {
+    /** 行的稳定 id：跨 append/remove/swap/move 跟随数据行本身，
+     * 渲染列表时直接作 React key（绝不要用 index 当 key）。 */
+    id: string;
+    /** 行的当前位置：remove/move/swap/insert 之后随数据迁移。 */
+    index: number;
+} & Record<K, string>;
+/**
+ * FormList 的 render-prop 入参 —— react-f0rm `useFieldArray` 返回值
+ * （`UseFieldArrayResult`）的结构透传。f0rm 主入口不导出该类型，这里按
+ * 其形状镜像声明；`useFieldArray` 的真实返回值直接满足本类型。
+ */
+export type FormListBinding<K extends string = 'id'> = {
+    /** 行列表：每行带稳定 key（`id` 或 `keyName` 指定的属性）与当前索引。 */
+    fields: FormListField<K>[];
+    /** 在数组末尾追加一行。 */
+    append: (value: any) => void;
+    /** 在数组头部插入一行。 */
+    prepend: (value: any) => void;
+    /** 在 `index` 处插入一行，其后各行顺移。 */
+    insert: (index: number, value: any) => void;
+    /** 删除 `index` 处的行，其后各行前移（行 key 随数据行消失）。 */
+    remove: (index: number) => void;
+    /** 交换两行位置：只动这两行，中间行不动。 */
+    swap: (from: number, to: number) => void;
+    /** 把 `from` 行移动到 `to` 位置，中间行整体顺移。 */
+    move: (from: number, to: number) => void;
+    /** 整表替换：清空后按 `values` 重建全部行。 */
+    replace: (values: any[]) => void;
+    /** 原位覆写 `index` 行的值：行 key 与位置保持不变。 */
+    update: (index: number, value: any) => void;
+};
+/** FormList 自身的 props —— `useFieldArray` 选项的组件化外壳。 */
+export type FormListProps<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name, K extends string = 'id'> = {
+    /**
+     * 表单实例（`useForm()`/`createForm()` 的返回值）。可省略：省略时从
+     * 最近的 `<FormProvider value={form}>` 读取（react-f0rm 的 form
+     * context）；显式传入的 `form` 总是优先。
+     */
+    form?: FormInstance<TValues>;
+    /** 数组字段的路径，如 `'tags'`。 */
+    name: P;
+    /**
+     * 稳定行 key 在每个 `fields` 条目上暴露的属性名（默认 `'id'`）；
+     * 行数据自带同名字段时换一个（如 `'key'`）避免覆盖，底层 id 不变。
+     */
+    keyName?: K;
+    /**
+     * 声明式规则，对整个数组值校验（react-hook-form `useFieldArray` 的
+     * `rules`）：`required` 空数组失败，`minLength`/`maxLength` 读行数。
+     * 与字段级规则一样在 submit 与 `trigger` 时运行。
+     */
+    rules?: FieldRules;
+    /**
+     * 卸载本组件时是否移除整个数组分支（含各行数据）。默认跟随表单级
+     * `shouldUnregister`；传 `false` 保留数据。
+     */
+    shouldUnregister?: boolean;
+    className?: string;
+    /** render-prop：收到数组操作句柄，渲染整张行列表。 */
+    children: (binding: FormListBinding<K>) => ReactNode;
+};
+/**
+ * 数组字段的组件外壳：包住 react-f0rm 1.3 的 `useFieldArray`，把行
+ * 列表与增删换位操作以 render-prop 交给消费者。headless —— 不带任何
+ * 内置布局，只渲染一个可挂 `className` 的壳 `<div>`；行怎么排、按钮
+ * 怎么放完全由 children 决定。
+ *
+ * `form` 可省略：省略时从最近的 `<FormProvider value={form}>` 回退读取；
+ * 两者都没有时 throw。`keyName`/`rules`/`shouldUnregister` 原样透传给
+ * `useFieldArray`。
+ *
+ * **行内编辑的保留（物化时机）**：react-f0rm 的数组操作从「数组层的
+ * 上一次物化」读取整表，行内控件（如 `name={['tags', i, 'label']}` 的
+ * FormItem）的编辑先是挂在更深层的待合并写入——直接 append/remove 会
+ * 让它们被下一代覆盖丢失。FormList 在每个读旧值的操作（append/
+ * prepend/insert/remove/swap/move/update）前，先用 `getValues()` 的
+ * 合并视图把数组分支物化一次，行内编辑因此跨操作保留——与
+ * react-hook-form / TanStack Form 的行为一致。`replace` 不读旧值，
+ * 原样透传；`update`/`replace` 的显式值仍然覆盖对应行的行内编辑。
+ *
+ * ```tsx
+ * <FormList form={form} name='tags'>
+ *   {({fields, append, remove}) => (
+ *     <>
+ *       {fields.map((field) => (
+ *         <div key={field.id}>
+ *           <FormItem
+ *             form={form}
+ *             name={['tags', field.index, 'label']}
+ *             input={InputCore}
+ *           />
+ *           <Button onClick={() => remove(field.index)}>Remove</Button>
+ *         </div>
+ *       ))}
+ *       <Button onClick={() => append({label: ''})}>Add tag</Button>
+ *     </>
+ *   )}
+ * </FormList>
+ * ```
+ *
+ * 行 key 用 `field.id`（或 `keyName` 指定的属性）——不要用 index：
+ * remove/swap/move 之后 index 会迁移，index key 会让 React 把行状态
+ * 错配到别的数据行上。
+ */
+export default function FormList<TValues extends Record<string, any> = any, P extends FieldPath<TValues> | Name = Name, K extends string = 'id'>({ form, name, keyName, rules, shouldUnregister, className, children }: FormListProps<TValues, P, K>): import("react").JSX.Element;

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

@@ -1,3 +1,29 @@
 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 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。
+ */
+export { FormProvider, useFormContext, useFieldArray, useFieldArrayItem, useWatch, 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、
+ * arktype 等。`standardSchemaResolver` 是字段级（FormItem 的
+ * `validate`），`standardSchemaFormValidator` 是表单级
+ * （`createForm({validate})`，成功时把 schema 解析结果存为
+ * parsedValues；经 `./standard-schema` 兜底 react-f0rm 1.3.0 的
+ * 品牌符号打包缺陷）。`hasStandardProps` 运行时探测 schema 是否实现了
+ * Standard Schema。
+ */
+export { hasStandardProps, standardSchemaFormValidator, standardSchemaResolver } from './standard-schema';
+export type { StandardSchemaV1 } from './standard-schema';
+/**
+ * zod 专用字段级适配器（react-f0rm/resolvers/zod）：schema 实现了
+ * Standard Schema 时直接走通用通道，否则走 zod 的 safeParseAsync。
+ */
+export { zodResolver } from 'react-f0rm/resolvers/zod';