seam-react 0.12.3 → 0.13.0

package/README.md

@@ -35,13 +35,14 @@ export function Root() {
 }
 ```
 
-组件包含：Button、Input、Switch、Tabs、Dialog、Toast、Tooltip、Sidebar。
+组件包含：Button、Input、Form、Switch、Tabs、Dialog、Toast、Tooltip、Sidebar。
 
 - Tabs 支持方向键切换、ARIA 关联与 fluid 指示器。
 - Switch 支持点击、键盘和拖拽 spring。
 - Dialog 提供 Root / Trigger / Content 与语义化内容层，自带 Motion 进出场、焦点陷阱、Esc 关闭与滚动锁定。
 - Toast 提供 `useToast` 状态队列与 `ToastStack` 呈现层，支持六向定位、自动关闭、状态图标、操作和拖拽关闭。
 - Tooltip 提供延迟显示、键盘与触屏访问、视口翻转/避让，以及可让相邻触发器共享并连续移动表面的 Group / Item 组合。
+- Form 提供组合式字段、同步/异步规则、服务端错误和失败聚焦；安装 `valibot` 后可通过 `seam-react/valibot` 接入 schema 校验。
 - Sidebar 提供可折叠 Group、可配置分组间距，以及互斥的轨道与背景 hover 模式。
 
 完整文档：[chenhaojie9527.github.io/ui-kit](https://chenhaojie9527.github.io/ui-kit/)

package/dist/FormComponent.d.ts

@@ -1,7 +1,8 @@
-import { type FormHTMLAttributes, type HTMLAttributes, type LabelHTMLAttributes, type ReactElement, type ReactNode } from "react";
+import { type FormHTMLAttributes, type HTMLAttributes, type LabelHTMLAttributes, type ReactElement, type ReactNode, type Ref } from "react";
 export type FormErrors<T extends Record<string, unknown> = Record<string, unknown>> = {
     [K in keyof T]?: string;
 } & Record<string, string | undefined>;
+export type FormValidationTrigger = "submit" | "focus" | "change" | "blur" | "pointerleave";
 export type FieldRule<T = unknown> = {
     required: boolean;
     message?: string;
@@ -79,6 +80,7 @@ export interface FormContextValue<T = Record<string, unknown>> {
     }) => void;
     setFieldTouched: (name: string, touched: boolean) => void;
     setFieldFocused: (name: string, focused: boolean) => void;
+    handleFieldInteraction: (name: string, trigger: Exclude<FormValidationTrigger, "submit">) => void;
     registerField: (name: string, config: FieldConfig) => void;
     unregisterField: (name: string) => void;
     validateField: (name: string) => Promise<boolean>;
@@ -90,8 +92,8 @@ export interface FormContextValue<T = Record<string, unknown>> {
     setFormError: (error: string | null) => void;
     clearErrors: (fields?: string[]) => void;
     focusFirstError: () => void;
-    validateOn: "submit" | "blur" | "change";
-    revalidateOn: "change" | "blur";
+    validateOn: FormValidationTrigger;
+    revalidateOn: Exclude<FormValidationTrigger, "submit">;
     validateDebounce: number;
 }
 interface FieldConfig {
@@ -110,11 +112,12 @@ export interface FormRootProps<T extends Record<string, unknown> = Record<string
     onValuesChange?: (values: T, changedField?: keyof T) => void;
     onSubmit?: (values: T) => void | Promise<void>;
     onSubmitFailed?: (errors: FormErrors<T>) => void;
-    validateOn?: "submit" | "blur" | "change";
-    revalidateOn?: "change" | "blur";
+    validateOn?: FormValidationTrigger;
+    revalidateOn?: Exclude<FormValidationTrigger, "submit">;
     validateDebounce?: number;
     noValidate?: boolean;
     validate?: (values: T) => FormErrors<T> | Promise<FormErrors<T>>;
+    layout?: "vertical" | "inline" | "horizontal";
     children: ReactNode;
 }
 export interface FormFieldProps<T = unknown> {
@@ -132,6 +135,7 @@ export interface FormFieldProps<T = unknown> {
 }
 export interface FormLabelProps extends LabelHTMLAttributes<HTMLLabelElement> {
     required?: boolean;
+    labelWrap?: boolean;
     children: ReactNode;
 }
 export interface FormControlProps {
@@ -149,7 +153,9 @@ export interface FormActionsProps extends HTMLAttributes<HTMLDivElement> {
 export declare function useFormContext<T = Record<string, unknown>>(): FormContextValue<T>;
 export declare function useFieldState(name: string): FieldState;
 export declare function useWatch<T = unknown>(name: string | string[]): T;
-declare const FormRoot: import("react").ForwardRefExoticComponent<FormRootProps<Record<string, unknown>> & import("react").RefAttributes<FormRef<Record<string, unknown>>>>;
+declare const FormRoot: <T extends Record<string, unknown> = Record<string, unknown>>(props: FormRootProps<T> & {
+    ref?: Ref<FormRef>;
+}) => ReactElement | null;
 declare function FormField({ name, defaultValue, rules, transform, disabled, readOnly, hidden, preserveOnUnmount, dependencies, children, className, }: FormFieldProps): ReactElement | null;
 declare const FormLabel: import("react").ForwardRefExoticComponent<FormLabelProps & import("react").RefAttributes<HTMLLabelElement>>;
 declare function FormControl({ children }: FormControlProps): ReactElement;