seam-react 0.12.2 → 0.12.4

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/CheckBox.d.ts

@@ -9,10 +9,4 @@ export interface CheckBoxProps extends Omit<InputHTMLAttributes<HTMLInputElement
     /** 显示在复选框右侧的标签文本。 */
     children?: ReactNode;
 }
-/**
- * 复选框。
- *
- * 保留原生 checkbox 的表单、键盘和读屏语义；方框内的对勾用 SVG 描边
- * 展示状态转换，按压时的轻微缩放提供即时的触觉反馈。
- */
 export declare const CheckBox: ForwardRefExoticComponent<CheckBoxProps & RefAttributes<HTMLInputElement>>;

package/dist/FormComponent.d.ts

@@ -0,0 +1,171 @@
+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 FieldRule<T = unknown> = {
+    required: boolean;
+    message?: string;
+} | {
+    minLength: number;
+    message?: string;
+} | {
+    maxLength: number;
+    message?: string;
+} | {
+    pattern: RegExp;
+    message?: string;
+} | {
+    min: number;
+    message?: string;
+} | {
+    max: number;
+    message?: string;
+} | {
+    enum: T[];
+    message?: string;
+} | {
+    validator: (value: T, values: Record<string, unknown>) => string | null | Promise<string | null>;
+};
+export interface FieldState {
+    value: unknown;
+    initialValue: unknown;
+    dirty: boolean;
+    touched: boolean;
+    focused: boolean;
+    validating: boolean;
+    invalid: boolean;
+    valid: boolean;
+    required: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    hidden: boolean;
+    error?: string;
+}
+export interface FormState {
+    submitting: boolean;
+    submitted: boolean;
+    submitSucceeded: boolean;
+    submitFailed: boolean;
+    dirty: boolean;
+    validating: boolean;
+    errors: Record<string, string>;
+    formError: string | null;
+}
+export interface FormRef<T = Record<string, unknown>> {
+    getValues: () => T;
+    getValue: (name: string) => unknown;
+    setValue: (name: string, value: unknown, options?: {
+        validate?: boolean;
+        touch?: boolean;
+    }) => void;
+    setValues: (values: Partial<T>, options?: {
+        validate?: boolean;
+    }) => void;
+    reset: (values?: Partial<T>) => void;
+    clear: () => void;
+    validate: (fields?: string[]) => Promise<boolean>;
+    setError: (name: string, error: string) => void;
+    setFormError: (error: string | null) => void;
+    clearErrors: (fields?: string[]) => void;
+    focusFirstError: () => void;
+}
+export interface FormContextValue<T = Record<string, unknown>> {
+    values: T;
+    state: FormState;
+    getFieldState: (name: string) => FieldState;
+    setValue: (name: string, value: unknown, options?: {
+        validate?: boolean;
+        touch?: boolean;
+    }) => void;
+    setFieldTouched: (name: string, touched: boolean) => void;
+    setFieldFocused: (name: string, focused: boolean) => void;
+    registerField: (name: string, config: FieldConfig) => void;
+    unregisterField: (name: string) => void;
+    validateField: (name: string) => Promise<boolean>;
+    validateForm: () => Promise<boolean>;
+    submit: () => Promise<void>;
+    reset: (values?: Partial<T>) => void;
+    clear: () => void;
+    setError: (name: string, error: string) => void;
+    setFormError: (error: string | null) => void;
+    clearErrors: (fields?: string[]) => void;
+    focusFirstError: () => void;
+    validateOn: "submit" | "blur" | "change";
+    revalidateOn: "change" | "blur";
+    validateDebounce: number;
+}
+interface FieldConfig {
+    rules?: FieldRule[];
+    transform?: (value: unknown) => unknown;
+    dependencies?: string[];
+    preserveOnUnmount?: boolean;
+    defaultValue?: unknown;
+    disabled?: boolean;
+    readOnly?: boolean;
+    hidden?: boolean;
+}
+export interface FormRootProps<T extends Record<string, unknown> = Record<string, unknown>> extends Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "onChange"> {
+    values?: T;
+    defaultValues?: Partial<T>;
+    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";
+    validateDebounce?: number;
+    noValidate?: boolean;
+    validate?: (values: T) => FormErrors<T> | Promise<FormErrors<T>>;
+    children: ReactNode;
+}
+export interface FormFieldProps<T = unknown> {
+    name: string;
+    defaultValue?: T;
+    rules?: FieldRule<T>[];
+    transform?: (value: T) => T;
+    disabled?: boolean;
+    readOnly?: boolean;
+    hidden?: boolean;
+    preserveOnUnmount?: boolean;
+    dependencies?: string[];
+    children: ReactNode;
+    className?: string;
+}
+export interface FormLabelProps extends LabelHTMLAttributes<HTMLLabelElement> {
+    required?: boolean;
+    children: ReactNode;
+}
+export interface FormControlProps {
+    children: ReactElement;
+}
+export interface FormDescriptionProps extends HTMLAttributes<HTMLParagraphElement> {
+    children: ReactNode;
+}
+export interface FormErrorMessageProps extends Omit<HTMLAttributes<HTMLParagraphElement>, "children"> {
+    children?: (error: string) => ReactNode;
+}
+export interface FormActionsProps extends HTMLAttributes<HTMLDivElement> {
+    children: ReactNode;
+}
+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: <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;
+declare const FormDescription: import("react").ForwardRefExoticComponent<FormDescriptionProps & import("react").RefAttributes<HTMLParagraphElement>>;
+declare const FormErrorMessage: import("react").ForwardRefExoticComponent<FormErrorMessageProps & import("react").RefAttributes<HTMLParagraphElement>>;
+declare const FormActions: import("react").ForwardRefExoticComponent<FormActionsProps & import("react").RefAttributes<HTMLDivElement>>;
+export interface FormComponent {
+    Root: typeof FormRoot;
+    Field: typeof FormField;
+    Label: typeof FormLabel;
+    Control: typeof FormControl;
+    Description: typeof FormDescription;
+    ErrorMessage: typeof FormErrorMessage;
+    Actions: typeof FormActions;
+}
+export declare const Form: FormComponent;
+export {};

package/dist/Select.d.ts

@@ -53,8 +53,8 @@ export type SelectProps<Multiple extends boolean = false> = SelectBaseProps & (M
     defaultValue?: string | null;
     onValueChange?: (value: string) => void;
 });
-declare const Select: {
+export declare const Select: {
     (props: SelectSingleProps & RefAttributes<HTMLDivElement>): ReactElement | null;
     (props: SelectMultipleProps & RefAttributes<HTMLDivElement>): ReactElement | null;
 };
-export { Select };
+export {};

package/dist/Switch.d.ts

@@ -9,10 +9,4 @@ export interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
     /** 显示在开关右侧的标签文本。 */
     children?: ReactNode;
 }
-/**
- * 开关。
- *
- * 底层是原生 checkbox（role="switch"），所以表单提交、键盘操作和
- * 屏幕阅读器语义都是免费的；视觉部分由 track / thumb 两个 span 承担。
- */
 export declare const Switch: ForwardRefExoticComponent<SwitchProps & RefAttributes<HTMLInputElement>>;

package/dist/control-contract.d.ts

@@ -0,0 +1,4 @@
+export declare const CONTROL_KIND: "__seamControlKind";
+export type ControlKind = "boolean" | "value";
+export declare function markControl<T extends object>(component: T, kind: ControlKind): T;
+export declare function getControlKind(component: unknown): ControlKind | undefined;