@rxdrag/form 0.1.0

package/dist/AppForm.d.ts

@@ -0,0 +1,44 @@
+import { CSSProperties, ReactNode } from 'react';
+import { ButtonProps } from '@rxdrag/shadcn';
+import { AnyAppForm } from './context';
+
+/**
+ * TanStack Form 表单层（替代 fieldy 的 VirtualForm/EntityForm 内核）。
+ *
+ * - useAppForm：包 TanStack useForm——defaultValues 即初始值（编辑=实体对象,新建=空对象/预填）；
+ *   onSubmit 在校验全部通过后拿到整表单值。
+ * - AppForm：渲染 <form> + 提供上下文；**脏判定用 `!form.state.isDefaultValue`**（TanStack 内置
+ *   逐字段深比较 defaultValue，改回去即不脏——语义正确，无 fieldy modified 黑盒/整对象结构噪音）。
+ * - SubmitButton：type=submit + 提交中 loading。
+ */
+export interface UseAppFormOptions<T> {
+    defaultValues: T;
+    onSubmit?: (value: T) => void | Promise<void>;
+}
+export declare function useAppForm<T extends object>(opts: UseAppFormOptions<T>): AnyAppForm;
+/**
+ * refillForm —— 表单重灌的唯一入口：值 + 脏基线(defaultValues) 一起换新。
+ * 语义（form-core 源码确认）：reset(next) = options.defaultValues←next + 全字段 meta 清空
+ * （isTouched=false、isDefaultValue=true）。配合 useAppForm 已关闭 options 同步，重灌后
+ * 任何渲染都不会把值拉回旧默认值。用于「编辑态数据到达/重新加载整表/手动重置到基线」。
+ */
+export declare function refillForm<T extends object>(form: AnyAppForm, next: T): void;
+/**
+ * commitForm —— 保存成功后的基线提交：把「当前表单值 +（可选）服务端补丁」设为新值与新脏基线。
+ * 替代业务手拼 form.reset({...values,...serverPatch,id}) 的易错写法；patch 只应含服务端
+ * 生成字段（id/code/createdAt/updatedAt 等白名单），用户填的值一律以表单现值为准。
+ */
+export declare function commitForm<T extends object>(form: AnyAppForm, patch?: Partial<T>): void;
+export interface AppFormProps {
+    form: AnyAppForm;
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** 表单名（= 实体名，调试标识）。 */
+    name?: string;
+    /** 未保存脏态上报（= !isDefaultValue，供 useUnsavedGuard）。 */
+    onDirtyChange?: (dirty: boolean) => void;
+}
+export declare function AppForm(props: AppFormProps): import("react").JSX.Element;
+/** 提交按钮：submit 类型 + 提交中 loading/禁用。放在 AppForm 内使用。 */
+export declare function SubmitButton(props: ButtonProps): import("react").JSX.Element;

package/dist/ObjectField.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+
+/**
+ * 嵌套对象字段：把 name 作为前缀下发给子字段（TanStack Form 用点号路径表达嵌套）。
+ * 例如 <ObjectField name="meta"><InputField name="title" /></ObjectField>
+ * 内部字段实际绑定到 "meta.title"。可多层嵌套。
+ */
+export declare function ObjectField(props: {
+    name: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;

package/dist/bindField.d.ts

@@ -0,0 +1,38 @@
+import { default as React } from 'react';
+import { FieldValidateProps } from './validators';
+
+/**
+ * bindField —— fieldy 的 toField 的 TanStack 等价 HOC：
+ * 把「受控展示组件（value/onValueChange/isInvalid/errorMessage）」绑定到 TanStack Field。
+ *
+ * 关键约定：**显示层转换不污染 store**——组件渲染用 value ?? displayDefault（如 ''），
+ * 但 store 里保持原始值（DB 的 null 不会被规范化写值弄脏，脏判定 isDefaultValue 因此可靠）。
+ */
+export type ControlProps = {
+    id?: string;
+    name?: string;
+    label?: React.ReactNode;
+    placeholder?: string;
+    value?: any;
+    isInvalid?: boolean;
+    errorMessage?: React.ReactNode;
+    onValueChange?: (value: any) => void;
+};
+export type BoundFieldProps = FieldValidateProps & {
+    /** 字段路径（XxxFields.* 常量）。可选：无 name 时不绑定，直接渲染展示组件（对齐 fieldy）。 */
+    name?: string;
+    /** 值写回前的转换（如 number 字段把输入串转数字）。 */
+    coerce?: (raw: any) => any;
+    /** 以下为 fieldy 遗留 props：类型上接受、运行时忽略（不写回 store、不透传 DOM）。 */
+    initialValue?: unknown;
+    defaultValue?: unknown;
+    value?: unknown;
+    valueComputer?: unknown;
+};
+export type BindFieldOptions = {
+    /** 渲染层空值兜底（不写回 store）。 */
+    displayDefault?: unknown;
+    /** 登记到字段元数据表的控件类型。 */
+    controlType?: string;
+};
+export declare function bindField<P extends ControlProps = ControlProps>(Component: React.ComponentType<P>, options?: BindFieldOptions): (props: BoundFieldProps & Omit<P, "value" | "onValueChange" | "isInvalid" | "errorMessage">) => React.JSX.Element;

package/dist/components/Checkbox.d.ts

@@ -0,0 +1,10 @@
+import * as React from "react";
+export type CheckboxProps = {
+    id?: string;
+    children?: React.ReactNode;
+    value?: boolean;
+    onValueChange?: (value: boolean) => void;
+    isInvalid?: boolean;
+    errorMessage?: React.ReactNode;
+};
+export declare function Checkbox(props: CheckboxProps): React.JSX.Element;

package/dist/components/ColorInput.d.ts

@@ -0,0 +1,5 @@
+export type ColorInputProps = {
+    value?: string;
+    onValueChange?: (value?: string) => void;
+};
+export declare function ColorInput(props: ColorInputProps): import("react").JSX.Element;

package/dist/components/Input.d.ts

@@ -0,0 +1,29 @@
+import * as React from "react";
+type ShadcnInputSize = "sm" | "md" | "lg";
+type ShadcnInputVariant = "default" | "filled" | "flat";
+type BaseInputProps = Omit<React.ComponentProps<"input">, "size"> & {
+    size?: ShadcnInputSize;
+    variant?: ShadcnInputVariant;
+};
+export type InputProps = BaseInputProps & {
+    label?: React.ReactNode;
+    labelPlacement?: "outside" | "inside" | "outside-left";
+    description?: React.ReactNode;
+    isInvalid?: boolean;
+    errorMessage?: React.ReactNode;
+    onValueChange?: (value: string) => void;
+    startContent?: React.ReactNode;
+    endContent?: React.ReactNode;
+    required?: boolean;
+    requried?: boolean;
+    classNames?: Partial<{
+        base: string;
+        label: string;
+        inputWrapper: string;
+        input: string;
+        description: string;
+        errorMessage: string;
+    }>;
+};
+export declare function Input(props: InputProps): React.JSX.Element;
+export {};

package/dist/components/Password.d.ts

@@ -0,0 +1,6 @@
+import { InputProps } from './Input';
+import * as React from "react";
+export type PasswordProps = Omit<InputProps, "type" | "endContent"> & {
+    endContent?: React.ReactNode;
+};
+export declare function Password(props: PasswordProps): React.JSX.Element;

package/dist/components/Select.d.ts

@@ -0,0 +1,24 @@
+import * as React from "react";
+export type SelectProps = {
+    id?: string;
+    label?: React.ReactNode;
+    labelPlacement?: "outside" | "inside" | "outside-left";
+    placeholder?: string;
+    description?: React.ReactNode;
+    isInvalid?: boolean;
+    errorMessage?: React.ReactNode;
+    value?: string | number;
+    onValueChange?: (value?: string | number) => void;
+    disabled?: boolean;
+    className?: string;
+    classNames?: Partial<{
+        base: string;
+        label: string;
+        trigger: string;
+        content: string;
+        description: string;
+        errorMessage: string;
+    }>;
+    children?: React.ReactNode;
+};
+export declare function Select(props: SelectProps): React.JSX.Element;

package/dist/components/SingleSelect.d.ts

@@ -0,0 +1,7 @@
+import { SelectProps } from './Select';
+
+export type SingleSelectProps = Omit<SelectProps, "value" | "onValueChange"> & {
+    value?: string;
+    onValueChange?: (value?: string) => void;
+};
+export declare function SingleSelect(props: SingleSelectProps): import("react").JSX.Element;

package/dist/components/Switch.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+export type SwitchProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "value"> & {
+    value?: boolean;
+    onValueChange?: (value: boolean) => void;
+    size?: "sm" | "md" | "lg";
+    children?: React.ReactNode;
+    disabled?: boolean;
+};
+export declare function Switch(props: SwitchProps): React.JSX.Element;

package/dist/components/Textarea.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+export type TextareaProps = React.ComponentProps<"textarea"> & {
+    id?: string;
+    label?: React.ReactNode;
+    labelPlacement?: "outside" | "inside" | "outside-left";
+    description?: React.ReactNode;
+    isInvalid?: boolean;
+    errorMessage?: React.ReactNode;
+    onValueChange?: (value: string) => void;
+    required?: boolean;
+    requried?: boolean;
+    minRows?: number;
+    classNames?: Partial<{
+        base: string;
+        label: string;
+        textarea: string;
+        description: string;
+        errorMessage: string;
+    }>;
+};
+export declare function Textarea(props: TextareaProps): React.JSX.Element;

package/dist/components/index.d.ts

@@ -0,0 +1,8 @@
+export * from './Input';
+export * from './Textarea';
+export * from './Select';
+export * from './SingleSelect';
+export * from './Switch';
+export * from './Checkbox';
+export * from './ColorInput';
+export * from './Password';

package/dist/context.d.ts

@@ -0,0 +1,35 @@
+/**
+ * AppForm 上下文：向字段组件提供 TanStack form 实例 + 字段元数据登记表。
+ *
+ * form 类型收敛为 any：TanStack Form 的泛型链按字面 name 做类型级校验，而本项目字段组件
+ * 以动态字符串 name（XxxFields.name 常量）工作——功能兼容优先，类型宽松收敛在包内部，
+ * 业务层拿到的字段组件 props 仍是强类型。
+ */
+export type AnyAppForm = any;
+/** 已挂载字段的元数据（供枚举/调试/未来 agent 工作台）。 */
+export interface RegisteredFieldMeta {
+    name: string;
+    label?: string;
+    type?: string;
+}
+export interface AppFormContextValue {
+    /** 表单名（= 实体名）。 */
+    name?: string;
+    form: AnyAppForm;
+    /** 字段挂载时登记元数据，返回注销函数。 */
+    registerFieldMeta: (meta: RegisteredFieldMeta) => () => void;
+    /** 枚举当前挂载字段（按登记序）。 */
+    getFieldMetas: () => RegisteredFieldMeta[];
+}
+export declare const AppFormContext: import('react').Context<AppFormContextValue | undefined>;
+export declare function useAppFormContext(): AppFormContextValue;
+/** 宽松版：不在 AppForm 内返回 undefined（供可选场景探测）。 */
+export declare function useMaybeAppFormContext(): AppFormContextValue | undefined;
+/**
+ * 字段名前缀上下文（ObjectField 用）。TanStack Form 用点号路径（如 "meta.title"）表达嵌套，
+ * ObjectField 把自己的 name 作为前缀下发，内部字段 name="title" 解析成 "meta.title"。
+ */
+export declare const FieldNamePrefixContext: import('react').Context<string>;
+export declare function useFieldNamePrefix(): string;
+/** 拼接前缀与字段名（空前缀直接返回 name）。 */
+export declare function joinFieldName(prefix: string, name: string): string;

package/dist/fields.d.ts

@@ -0,0 +1,112 @@
+import { default as React } from 'react';
+import { BindFieldOptions, ControlProps } from './bindField';
+import { InputProps } from './components/Input';
+import { TextareaProps } from './components/Textarea';
+import { SelectProps } from './components/Select';
+import { SingleSelectProps } from './components/SingleSelect';
+import { SwitchProps } from './components/Switch';
+import { CheckboxProps } from './components/Checkbox';
+import { ColorInputProps } from './components/ColorInput';
+import { PasswordProps } from './components/Password';
+
+/**
+ * 业务字段组件（TanStack 版）——沿用 fieldy-ui 的同名 props 心智，功能对齐。
+ * name 用 codegen 出的 XxxFields.* 常量；校验支持 required / zodSchema / 旧版 validateSchema。
+ */
+declare const BaseInputField: (props: import('./validators').FieldValidateProps & {
+    name?: string;
+    coerce?: (raw: any) => any;
+    initialValue?: unknown;
+    defaultValue?: unknown;
+    value?: unknown;
+    valueComputer?: unknown;
+} & Omit<InputProps, "value" | "onValueChange" | "isInvalid" | "errorMessage">) => React.JSX.Element;
+/** 文本/数字输入。type="number" 时写回 store 的是 number（空串→undefined）。 */
+export declare function InputField(props: Parameters<typeof BaseInputField>[0] & {
+    type?: string;
+}): React.JSX.Element;
+export declare const TextareaField: (props: import('./validators').FieldValidateProps & {
+    name?: string;
+    coerce?: (raw: any) => any;
+    initialValue?: unknown;
+    defaultValue?: unknown;
+    value?: unknown;
+    valueComputer?: unknown;
+} & Omit<TextareaProps, "value" | "onValueChange" | "isInvalid" | "errorMessage">) => React.JSX.Element;
+export declare const SelectField: (props: import('./validators').FieldValidateProps & {
+    name?: string;
+    coerce?: (raw: any) => any;
+    initialValue?: unknown;
+    defaultValue?: unknown;
+    value?: unknown;
+    valueComputer?: unknown;
+} & Omit<SelectProps, "value" | "onValueChange" | "isInvalid" | "errorMessage">) => React.JSX.Element;
+export declare const SingleSelectField: (props: import('./validators').FieldValidateProps & {
+    name?: string;
+    coerce?: (raw: any) => any;
+    initialValue?: unknown;
+    defaultValue?: unknown;
+    value?: unknown;
+    valueComputer?: unknown;
+} & Omit<SingleSelectProps, "value" | "onValueChange" | "isInvalid" | "errorMessage">) => React.JSX.Element;
+export declare const SwitchField: (props: import('./validators').FieldValidateProps & {
+    name?: string;
+    coerce?: (raw: any) => any;
+    initialValue?: unknown;
+    defaultValue?: unknown;
+    value?: unknown;
+    valueComputer?: unknown;
+} & Omit<SwitchProps, "value" | "onValueChange" | "isInvalid" | "errorMessage">) => React.JSX.Element;
+export declare const CheckboxField: (props: import('./validators').FieldValidateProps & {
+    name?: string;
+    coerce?: (raw: any) => any;
+    initialValue?: unknown;
+    defaultValue?: unknown;
+    value?: unknown;
+    valueComputer?: unknown;
+} & Omit<CheckboxProps, "value" | "onValueChange" | "isInvalid" | "errorMessage">) => React.JSX.Element;
+export declare const PasswordField: (props: import('./validators').FieldValidateProps & {
+    name?: string;
+    coerce?: (raw: any) => any;
+    initialValue?: unknown;
+    defaultValue?: unknown;
+    value?: unknown;
+    valueComputer?: unknown;
+} & Omit<PasswordProps, "value" | "onValueChange" | "isInvalid" | "errorMessage">) => React.JSX.Element;
+export declare const ColorField: (props: import('./validators').FieldValidateProps & {
+    name?: string;
+    coerce?: (raw: any) => any;
+    initialValue?: unknown;
+    defaultValue?: unknown;
+    value?: unknown;
+    valueComputer?: unknown;
+} & Omit<ColorInputProps, "value" | "onValueChange" | "isInvalid" | "errorMessage">) => React.JSX.Element;
+/**
+ * toField —— fieldy-ui 同名 API 的兼容别名（供 glue 字段沿用）。
+ * 旧签名是 toField(Component, { defaultValue })，这里把 defaultValue 映射为 displayDefault。
+ * 保留「显式传 undefined」语义（如 select 存对象/undefined 而非 ""）。
+ */
+export declare function toField<P extends ControlProps = ControlProps>(Component: React.ComponentType<P>, options?: {
+    defaultValue?: unknown;
+} & BindFieldOptions): (props: import('./validators').FieldValidateProps & {
+    name?: string;
+    coerce?: (raw: any) => any;
+    initialValue?: unknown;
+    defaultValue?: unknown;
+    value?: unknown;
+    valueComputer?: unknown;
+} & Omit<P, "value" | "onValueChange" | "isInvalid" | "errorMessage">) => React.JSX.Element;
+/**
+ * fieldy-ui 的 FieldProps 兼容类型：字段包装组件的公共 props（供 glue 字段手写签名沿用）。
+ */
+export type FieldProps = {
+    name?: string;
+    label?: React.ReactNode;
+    defaultValue?: unknown;
+    initialValue?: unknown;
+    value?: unknown;
+    required?: boolean | string;
+    validateSchema?: import('./validators').LegacyValidateSchema;
+    valueComputer?: any;
+};
+export {};

package/dist/hooks.d.ts

@@ -0,0 +1,30 @@
+import { AnyAppForm } from './context';
+
+/** 订阅整表单当前值（TanStack store 切片）。 */
+export declare function useFormValues<T = any>(): T;
+/** fieldy useFormValue 兼容别名（无参，返回整表单值）。 */
+export declare const useFormValue: typeof useFormValues;
+/** 订阅某字段当前值（尊重 ObjectField 前缀）。 */
+export declare function useFieldValue<T = any>(name: string): T;
+/**
+ * fieldy useFormModified 兼容：脏 = !isDefaultValue。
+ * setModified(false)：以当前值为新基线（保存成功后调用 → 变“未修改”，禁用保存按钮）。
+ * setModified(true)：无需处理（TanStack 由值变化自动置脏）。
+ */
+export declare function useFormModified(): {
+    modified: boolean;
+    setModified: (v: boolean) => void;
+};
+/**
+ * 命令式校验整表单并取值（替代 fieldy 的 form.validate()）。
+ * 返回 { ok, value }：ok=全字段校验通过；value=当前表单值（重组出的 entity 形状）。
+ */
+export declare function validateForm<T = any>(form: AnyAppForm): Promise<{
+    ok: boolean;
+    value: T;
+}>;
+/**
+ * 命令式设置某字段值（供加载后回填等场景，尊重 ObjectField 前缀）。
+ * 用法：const setField = useSetFieldValue(); setField("schemaJson", text)
+ */
+export declare function useSetFieldValue(): (name: string, value: unknown) => any;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './context';
+export * from './AppForm';
+export * from './bindField';
+export * from './validators';
+export * from './fields';
+export * from './ObjectField';
+export * from './hooks';
+export * from './components';
+export { useStore } from '@tanstack/react-form';