haze-ui 1.26.0 → 1.28.0

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

@@ -0,0 +1,18 @@
+import type { UploadEntry, UploadListItemRender } from './types';
+type UploadListProps = {
+    /** Tracked rows, in value order. */
+    entries: UploadEntry[];
+    /** Rendering style of the built-in list: `text` rows (default) or a
+     * `picture-card` grid of square thumbnail cards. */
+    listType?: 'text' | 'picture-card';
+    /** Overrides the remove-button label (text rows and picture-card
+     * corners alike); defaults to the locale string. */
+    removeLabel?: string;
+    /** Replaces the default row/cell rendering entirely. */
+    itemRender?: UploadListItemRender;
+    onRemove: (file: File) => void;
+    onRetry: (file: File) => void;
+    onCancel: (file: File) => void;
+};
+export default function UploadList({ entries, listType, removeLabel, 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';

package/dist/types/form/standard-schema.d.ts

@@ -0,0 +1,30 @@
+import type { StandardSchemaV1 } from 'react-f0rm/resolvers/standard-schema';
+import type { FormValidateFn } from 'react-f0rm';
+import { hasStandardProps, standardSchemaResolver } from 'react-f0rm/resolvers/standard-schema';
+export { hasStandardProps, standardSchemaResolver };
+export type { StandardSchemaV1 } from 'react-f0rm/resolvers/standard-schema';
+/**
+ * react-f0rm 1.3.0 的表单级 Standard Schema 适配器，附带一个 dist 打包
+ * 缺陷的兜底：共享块被内联进主入口，`Symbol('validation-outcome')` 品牌
+ * 因此存在两份 —— resolvers 子路径用 errors 块的那份给 `ValidationOutcome`
+ * 打品牌，而主入口里内联的核心校验管线检查的是自己那份，品牌对不上时
+ * outcome 被当成普通错误记录处理，`errors`（`FieldError` 对象数组）被
+ * 静默丢弃。这里用主入口导出的 `VALIDATION_OUTCOME`（核心实际检查的
+ * symbol）给结果重新打品牌；品牌一致（上游修复后）时原样透传。
+ *
+ * 其余行为与 `react-f0rm/resolvers/standard-schema` 的同名函数一致：
+ * 任何实现 `~standard` 的 schema（zod v3.24+/v4、valibot v1、arktype…）
+ * 整表校验，失败时每个 issue 映射为对应路径的 `FieldError`，成功时
+ * schema 的解析结果（coerce/transform）成为表单的 parsedValues 基线。
+ *
+ * 注意与 `createForm` 的 `validateDeps` 搭配：表单级校验轮对字段是
+ * 只设不清的，把参与校验的字段列进 `validateDeps`（如
+ * `['title', 'email']`）后，这些字段的用户修改会重跑整表 schema，
+ * 且上一轮的旧错误在下一轮按快照清理——react-f0rm 的跨字段依赖
+ * 机制，也是 schema 校验错误随输入消除的正路。
+ *
+ * 提交时的校验顺序：先跑已注册的字段级 validator（FormItem 的
+ * `validate`/`rules`），有失败即短路，表单级 schema 那一轮不再执行
+ * ——同一字段两种来源混用时以字段级为准，别在同一场表单里重复覆盖。
+ */
+export declare function standardSchemaFormValidator<T extends Record<string, any>>(schema: StandardSchemaV1<T, any>): FormValidateFn<T>;