@tianyr/schema-antd 0.0.0-stage → 0.1.0

package/dist/editable-table/types.d.ts

@@ -0,0 +1,109 @@
+import type { Key, ReactElement, ReactNode, Ref } from 'react';
+import type { TableProps } from 'antd';
+import type { TableFooterContext } from '../TableFooter.js';
+import type { EditableColumn, ToolbarPlacement } from '../types.js';
+/** onSave 返回 T 表示“本次确认版本”，返回 void 表示由上层刷新 dataSource */
+export type SaveResult<T> = T | void;
+export type EditingState = {
+    status: 'idle';
+} | {
+    status: 'editing';
+    rowKey: Key;
+} | {
+    status: 'validating';
+    rowKey: Key;
+} | {
+    status: 'saving';
+    rowKey: Key;
+};
+export interface DiscardConfirmContext<T> {
+    /** switch：切换编辑行；cancel：取消/覆盖草稿 */
+    reason: 'switch' | 'cancel';
+    currentRow: T;
+    nextRow: T | null;
+}
+export interface EditableRowActionContext<T> {
+    row: T;
+    /** 该行是否为当前活动行 */
+    active: boolean;
+    /** 校验或保存进行中，冲突操作应禁用 */
+    busy: boolean;
+    edit(): void;
+    save(): void;
+    cancel(): void;
+    remove(): void;
+}
+export interface EditableTableProps<T extends object> extends Omit<TableProps<T>, 'columns' | 'rowKey'> {
+    rowKey: keyof T | ((row: T) => Key);
+    columns: EditableColumn<T>[];
+    /** 仅在活动行校验通过后调用；抛错视为保存失败，草稿保留 */
+    onSave(nextRow: T, originalRow: T): Promise<SaveResult<T>> | SaveResult<T>;
+    onDelete?(row: T): Promise<void> | void;
+    /** 有脏差异需要切换时优先使用它；返回 false 表示不切换 */
+    onBeforeEditSwitch?(currentRow: T, nextRow: T): boolean | Promise<boolean>;
+    /** 覆盖内置“放弃修改”确认框 */
+    confirmDiscard?(ctx: DiscardConfirmContext<T>): boolean | Promise<boolean>;
+    /** 保存抛错时的出口；未提供则内置提示一次 */
+    onSaveError?(error: unknown): void;
+    /** dataSource 受控时，ref.setData() 通过它向上层发出替换请求 */
+    onSetData?(rows: T[]): void | Promise<void>;
+    /** 默认 true：追加行尾操作列 */
+    showActions?: boolean;
+    actionsColumnProps?: Partial<EditableColumn<T>>;
+    renderActions?(ctx: EditableRowActionContext<T>): ReactNode;
+    /** 整表只读：不进入编辑、不渲染操作列 */
+    disabled?: boolean;
+    /** 表体最大高度（scroll.y 的便捷入口）：超过后表体自身滚动；不传则整表撑开 */
+    maxHeight?: number;
+    /**
+     * 新增按钮（追加到末尾），默认开启。
+     * dataSource 受控，组件自己加不了行：只有同时提供 createRow 与 onSetData 时才默认显示，
+     * 显式传值优先（想关掉就传 false）。
+     */
+    showAddButton?: boolean;
+    /** 新增按钮文案，默认「新增」 */
+    addButtonText?: string;
+    /** 新增行默认值；必须能产出唯一 rowKey，否则新增被拒绝 */
+    createRow?: () => Partial<T>;
+    /** 底部新增按钮右侧插槽；不传则只渲染新增按钮 */
+    renderFooterExtra?: (ctx: TableFooterContext<T>) => ReactNode;
+    /** 行多选（勾选框），默认关闭；调用方自己传 rowSelection 时以调用方为准 */
+    showRowSelection?: boolean;
+    /**
+     * 底部批量删除按钮，默认关闭；只删勾选行。
+     * dataSource 受控，删除同样经由 onSetData 落地。
+     */
+    showBatchDelete?: boolean;
+    /** 批量删除文案，默认「批量删除」 */
+    batchDeleteText?: string;
+    /** 内置工具条（新增 / 插槽 / 批量删除）位置，默认顶部（与老家族 BatchEdit 一致） */
+    toolbarPlacement?: ToolbarPlacement;
+    /** 内置按钮是否带图标（新增 / 批量删除），默认不带 */
+    showButtonIcon?: boolean;
+}
+export interface EditableTableRef<T extends object> {
+    /** 仅返回已确认的 dataSource 快照，不含正在编辑的草稿 */
+    getDataSync(): T[];
+    /** 活动行草稿（原始行 + 表单值合并）；无活动行返回 null */
+    getEditingDraftSync(): T | null;
+    getEditingRowKey(): Key | null;
+    isEditing(): boolean;
+    /** 当前活动行是否有未保存差异 */
+    isDirty(): boolean;
+    /** 结束编辑并丢弃草稿；脏数据需确认，返回是否已退出 */
+    cancelEdit(): Promise<boolean>;
+    /**
+     * 请求替换已确认数据，成功后才结束编辑；脏草稿需先确认。
+     *
+     * 返回值回答的是“这次请求是否已生效”，false 不是错误，调用方可以忽略：
+     * - resolve true：onSetData 已成功执行；
+     * - resolve false：未做任何改动——用户放弃覆盖，或被校验/保存占用（稍后重试）；
+     * - reject：只有两种情况——未提供 onSetData（集成错误，须在丢草稿前暴露），
+     *   或 onSetData 自身失败（草稿保留，原样上抛）。
+     */
+    setData(rows: T[]): Promise<boolean>;
+}
+export type EditableTableComponent = <T extends object>(props: EditableTableProps<T> & {
+    ref?: Ref<EditableTableRef<T>>;
+}) => ReactElement;
+//# sourceMappingURL=types.d.ts.map

package/dist/editable-table/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/editable-table/types.ts"],"names":[],"mappings":"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"}

package/dist/editable-table/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/editable-table/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/editable-table/types.ts"],"names":[],"mappings":""}

package/dist/env.d.ts

@@ -0,0 +1,3 @@
+/** 开发态标记：只在 Vite 注入的 DEV 环境下为 true */
+export declare const IS_DEV: boolean;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,eAAO,MAAM,MAAM,SAOf,CAAC"}

package/dist/env.js

@@ -0,0 +1,11 @@
+/** 开发态标记：只在 Vite 注入的 DEV 环境下为 true */
+export const IS_DEV = (() => {
+    try {
+        const meta = import.meta;
+        return Boolean(meta.env?.DEV);
+    }
+    catch {
+        return false;
+    }
+})();
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE;IAC1B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,CAAC,IAAgD,CAAC;QACrE,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC,EAAE,CAAC"}

package/dist/form/FormRuntimeHost.d.ts

@@ -0,0 +1,39 @@
+import type { ReactNode } from 'react';
+import type { FormInstance } from 'antd';
+import type { FormFieldSchema } from '../types.js';
+export declare class FormRuntimeHost {
+    private readonly form;
+    private readonly fields;
+    /** 防止同一轮派发内被重入 */
+    private dispatching;
+    /** immediate 规则上次执行时的依赖值签名，键为 `${字段}#${规则序号}` */
+    private readonly immediateSignatures;
+    /** 依赖值未变却重复执行的次数，用于发现跨字段成环 */
+    private readonly immediateRepeats;
+    constructor(form: FormInstance);
+    /** 返回注销函数；同名字段以最后一次登记为准 */
+    registerField(schema: FormFieldSchema): () => void;
+    private createWriteContext;
+    private runRule;
+    /** 依赖值签名：两次执行签名相同说明这次不是被依赖变化驱动的 */
+    private dependencySignature;
+    /**
+     * 用户交互后的派发入口。
+     * 调用前必须保证新值已经写入 Form Store，否则 ctx.get() 会读到旧值。
+     * immediate 规则不在这里执行：它们由依赖值订阅统一驱动，避免同一变更跑两遍。
+     */
+    dispatchUserChange(changed: FormFieldSchema, value: unknown, meta: unknown[]): void;
+    /**
+     * 执行某个字段声明的 immediate 规则。
+     * 由 SchemaFormField 在依赖值变化时调用（含初始值、回填、setData），
+     * 不区分变更来源。
+     */
+    runImmediateRulesOf(schema: FormFieldSchema): void;
+}
+export declare function FormRuntimeHostProvider({ form, children, }: {
+    form: FormInstance;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** 不在 Host 内时返回 null：字段照常渲染，只是没有联动派发 */
+export declare function useFormRuntimeHost(): FormRuntimeHost | null;
+//# sourceMappingURL=FormRuntimeHost.d.ts.map

package/dist/form/FormRuntimeHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormRuntimeHost.d.ts","sourceRoot":"","sources":["../../src/form/FormRuntimeHost.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAGzC,OAAO,KAAK,EAAqB,eAAe,EAAuC,MAAM,UAAU,CAAC;AAMxG,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IAEpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAE7D,kBAAkB;IAClB,OAAO,CAAC,WAAW,CAAS;IAE5B,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAA6B;IAEjE,8BAA8B;IAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6B;gBAElD,IAAI,EAAE,YAAY;IAI9B,2BAA2B;IAC3B,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,IAAI;IAUlD,OAAO,CAAC,kBAAkB;IAyC1B,OAAO,CAAC,OAAO;IAIf,mCAAmC;IACnC,OAAO,CAAC,mBAAmB;IAS3B;;;;OAIG;IACH,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IA4BnF;;;;OAIG;IACH,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;CA4CnD;AAID,wBAAgB,uBAAuB,CAAC,EACtC,IAAI,EACJ,QAAQ,GACT,EAAE;IACD,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;CACrB,+BAGA;AAED,wCAAwC;AACxC,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,IAAI,CAE3D"}

package/dist/form/FormRuntimeHost.js

@@ -0,0 +1,184 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * FormRuntimeHost：一个 FormInstance 一份的联动运行作用域。
+ *
+ * 职责边界（见统一运行契约 §2/§4）：
+ * - 登记字段级 linkage / events 配置；
+ * - 用户交互后派发 events 与**非 immediate** 的 linkage；
+ * - 派发顺序固定：Form Store 写入 → events → linkage；
+ * - 写入不再隐式触发下一轮联动，避免循环。
+ *
+ * 变更来源：antd 的 `setFieldsValue` / `setFields` 走 `source: 'external'`，
+ * 不会触发 `onValuesChange`，因此**不能**靠它识别程序赋值（契约明确要求
+ * 用显式标记，不依赖该偶然行为）。这里的来源划分是：
+ * - 用户交互：SchemaField 的 onChange → dispatchUserChange，显式调用；
+ * - 任意变更（含初始化、回填、setData）：immediate 规则由 SchemaFormField
+ *   订阅自身依赖值变化后调用 runImmediateRulesOf，与来源无关。
+ */
+import { createContext, useContext, useMemo } from 'react';
+import { IS_DEV } from '../env.js';
+import { namePathKey } from './namePath.js';
+/** 依赖值没变却重复执行的容忍次数，超出视为规则成环 */
+const MAX_IMMEDIATE_REPEATS = 3;
+export class FormRuntimeHost {
+    constructor(form) {
+        this.fields = new Map();
+        /** 防止同一轮派发内被重入 */
+        this.dispatching = false;
+        /** immediate 规则上次执行时的依赖值签名，键为 `${字段}#${规则序号}` */
+        this.immediateSignatures = new Map();
+        /** 依赖值未变却重复执行的次数，用于发现跨字段成环 */
+        this.immediateRepeats = new Map();
+        this.form = form;
+    }
+    /** 返回注销函数；同名字段以最后一次登记为准 */
+    registerField(schema) {
+        const key = namePathKey(schema.name);
+        this.fields.set(key, schema);
+        return () => {
+            if (this.fields.get(key) === schema) {
+                this.fields.delete(key);
+            }
+        };
+    }
+    createWriteContext(written, touched, skipUnchanged = false) {
+        const form = this.form;
+        const track = (name, value) => {
+            const key = namePathKey(name);
+            if (written.has(key) && written.get(key) !== value && IS_DEV) {
+                console.warn(`[schema] 同一轮联动重复写入 "${key}"，结果依赖规则执行顺序，请合并规则`);
+            }
+            written.set(key, value);
+            touched.add(key);
+        };
+        const set = (name, value) => {
+            track(name, value);
+            // 仅优化 immediate 的纯标量赋值；对象、显式清空和错误清理保持原行为。
+            if (skipUnchanged && value != null && typeof value !== 'object'
+                && typeof value !== 'function' && Object.is(form.getFieldValue(name), value)
+                && !form.isFieldValidating(name) && !form.getFieldError(name).length
+                && !form.getFieldWarning(name).length)
+                return;
+            form.setFieldValue(name, value);
+        };
+        return {
+            form,
+            get: (name) => form.getFieldValue(name),
+            getValues: () => form.getFieldsValue(true),
+            set,
+            // 批量写入：记账口径与 set 一致（按顶层键），写入合并成一次 Store 更新
+            setValues: (values) => {
+                const entries = Object.entries(values);
+                for (const [key, value] of entries)
+                    track(key, value);
+                if (!entries.length)
+                    return;
+                form.setFieldsValue(values);
+            },
+            clear: (name) => set(name, undefined),
+            clearValues: (names) => names.forEach((name) => set(name, undefined)),
+        };
+    }
+    runRule(ctx, rule) {
+        rule.handler(ctx);
+    }
+    /** 依赖值签名：两次执行签名相同说明这次不是被依赖变化驱动的 */
+    dependencySignature(rule) {
+        try {
+            return JSON.stringify(rule.dependencies.map((dep) => this.form.getFieldValue(dep)));
+        }
+        catch {
+            // 存在循环引用时放弃判定，宁可不拦也不误伤
+            return undefined;
+        }
+    }
+    /**
+     * 用户交互后的派发入口。
+     * 调用前必须保证新值已经写入 Form Store，否则 ctx.get() 会读到旧值。
+     * immediate 规则不在这里执行：它们由依赖值订阅统一驱动，避免同一变更跑两遍。
+     */
+    dispatchUserChange(changed, value, meta) {
+        if (this.dispatching)
+            return;
+        this.dispatching = true;
+        try {
+            const written = new Map();
+            const ctx = this.createWriteContext(written, new Set());
+            // 1. 当前字段的交互副作用
+            if (changed.events?.onChange) {
+                const eventCtx = { ...ctx, option: meta[0], meta };
+                changed.events.onChange(value, eventCtx);
+            }
+            // 2. 依赖该字段的非 immediate linkage 规则
+            const changedKey = namePathKey(changed.name);
+            for (const field of this.fields.values()) {
+                for (const rule of field.linkage ?? []) {
+                    if (rule.immediate)
+                        continue;
+                    if (rule.dependencies.some((dep) => namePathKey(dep) === changedKey)) {
+                        this.runRule(ctx, rule);
+                    }
+                }
+            }
+        }
+        finally {
+            this.dispatching = false;
+        }
+    }
+    /**
+     * 执行某个字段声明的 immediate 规则。
+     * 由 SchemaFormField 在依赖值变化时调用（含初始值、回填、setData），
+     * 不区分变更来源。
+     */
+    runImmediateRulesOf(schema) {
+        if (this.dispatching)
+            return;
+        const rules = (schema.linkage ?? []).filter((rule) => rule.immediate);
+        if (!rules.length)
+            return;
+        this.dispatching = true;
+        try {
+            for (const rule of rules) {
+                const ruleKey = `${namePathKey(schema.name)}#${schema.linkage?.indexOf(rule)}`;
+                // 依赖值没变还在跑，说明是别的规则写回了依赖，继续跑下去就是成环
+                const signature = this.dependencySignature(rule);
+                const repeated = signature !== undefined && signature === this.immediateSignatures.get(ruleKey);
+                const repeats = repeated ? (this.immediateRepeats.get(ruleKey) ?? 0) + 1 : 0;
+                if (signature !== undefined)
+                    this.immediateSignatures.set(ruleKey, signature);
+                this.immediateRepeats.set(ruleKey, repeats);
+                if (repeats > MAX_IMMEDIATE_REPEATS) {
+                    if (IS_DEV) {
+                        console.error(`[schema] "${ruleKey}" 依赖值未变却重复执行 ${repeats} 次，判定为成环，已跳过`);
+                    }
+                    continue;
+                }
+                const written = new Map();
+                const touched = new Set();
+                this.runRule(this.createWriteContext(written, touched, true), rule);
+                // immediate 写回自己的依赖会形成渲染死循环，开发态直接指出来
+                if (IS_DEV) {
+                    const depKeys = new Set(rule.dependencies.map((dep) => namePathKey(dep)));
+                    for (const key of touched) {
+                        if (depKeys.has(key)) {
+                            console.warn(`[schema] immediate 规则 "${ruleKey}" 写回了自己的依赖 "${key}"`);
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            this.dispatching = false;
+        }
+    }
+}
+const FormRuntimeHostContext = createContext(null);
+export function FormRuntimeHostProvider({ form, children, }) {
+    const host = useMemo(() => new FormRuntimeHost(form), [form]);
+    return _jsx(FormRuntimeHostContext.Provider, { value: host, children: children });
+}
+/** 不在 Host 内时返回 null：字段照常渲染，只是没有联动派发 */
+export function useFormRuntimeHost() {
+    return useContext(FormRuntimeHostContext);
+}
+//# sourceMappingURL=FormRuntimeHost.js.map

package/dist/form/FormRuntimeHost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FormRuntimeHost.js","sourceRoot":"","sources":["../../src/form/FormRuntimeHost.tsx"],"names":[],"mappings":"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"}

package/dist/form/SchemaFormField.d.ts

@@ -0,0 +1,15 @@
+import type { AnyFormFieldSchema, FieldMode } from '../types.js';
+export interface SchemaFormFieldProps {
+    /** 普通字段或 type: 'Custom' 的局部自定义字段 */
+    schema: AnyFormFieldSchema;
+    /** 只调整布局与错误展示，不改变绑定/校验/联动语义 */
+    compact?: boolean;
+    /** 表单级只读，优先于字段自身 mode */
+    mode?: FieldMode;
+    /** 表单级禁用，永远优先于字段配置 */
+    disabled?: boolean;
+}
+declare function SchemaFormFieldInner(props: SchemaFormFieldProps): import("react").JSX.Element;
+export declare const SchemaFormField: import("react").MemoExoticComponent<typeof SchemaFormFieldInner>;
+export {};
+//# sourceMappingURL=SchemaFormField.d.ts.map

package/dist/form/SchemaFormField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaFormField.d.ts","sourceRoot":"","sources":["../../src/form/SchemaFormField.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAgC,MAAM,UAAU,CAAC;AAO5F,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,+BAA+B;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yBAAyB;IACzB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,sBAAsB;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAkBD,iBAAS,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,+BAQxD;AAED,eAAO,MAAM,eAAe,kEAA6B,CAAC"}

package/dist/form/SchemaFormField.js

@@ -0,0 +1,142 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * SchemaFormField：唯一可复用的字段绑定层。
+ *
+ * 普通 SchemaForm、EditableTable 活动行、FullEditableTable 每一行都复用它，
+ * 不另建第二套 Form.Item 绑定。它负责：具名 Form.Item、dynamic 派生、
+ * 隐藏时跳过校验、以及把用户交互交给 FormRuntimeHost 派发。
+ */
+import { memo, useEffect, useMemo, useRef } from 'react';
+import { Form } from 'antd';
+import { IS_DEV } from '../env.js';
+import { SchemaField } from '../SchemaField.js';
+import { useFormRuntimeHost } from './FormRuntimeHost.js';
+import { deriveFieldState, withDerivedProps } from './derive.js';
+import { dedupeNamePaths, getNestedValue, namePathKey } from './namePath.js';
+const EMPTY_DEPS = [];
+/** 漏写 dependencies 的字段已提醒过，按字段名去重，避免千格表格刷屏 */
+const warnedMissingDeps = new Set();
+/**
+ * `dynamic.dependencies` 在契约里是必填，但配置可能来自 JS 或后端下发。
+ * 缺了只会退化成静态字段（联动不生效），所以只在开发态提示一次，不抛错。
+ */
+function warnMissingDependencies(schema) {
+    const key = namePathKey(schema.name);
+    if (warnedMissingDeps.has(key))
+        return;
+    warnedMissingDeps.add(key);
+    console.warn(`[schema] 字段 "${key}" 配了 dynamic 却没有 dependencies，将按静态字段渲染`);
+}
+function SchemaFormFieldInner(props) {
+    const { schema } = props;
+    const dependencies = schema.dynamic?.dependencies;
+    if (IS_DEV && schema.dynamic && !dependencies)
+        warnMissingDependencies(schema);
+    const reactive = Boolean(dependencies?.length || schema.linkage?.some((rule) => rule.immediate));
+    return reactive ? _jsx(ReactiveField, { ...props }) : _jsx(FieldBody, { ...props });
+}
+export const SchemaFormField = memo(SchemaFormFieldInner);
+function FieldBody({ schema, compact, mode, disabled }) {
+    const form = Form.useFormInstance();
+    const host = useFormRuntimeHost();
+    useEffect(() => host?.registerField(schema), [host, schema]);
+    const readCtx = useMemo(() => ({
+        get: (name) => form.getFieldValue(name),
+        getValues: () => form.getFieldsValue(true),
+    }), [form]);
+    const derived = deriveFieldState(schema, readCtx);
+    return _jsx(FieldContent, { schema: schema, compact: compact, mode: mode, disabled: disabled, derived: derived });
+}
+/** 静态字段不订阅；动态字段变化后仍复用相同的绑定与校验。 */
+function ReactiveField(props) {
+    const { schema } = props;
+    const form = Form.useFormInstance();
+    const host = useFormRuntimeHost();
+    // immediate 规则的依赖：变更来源无关（初始化、回填、setData 都重算），
+    // 与非 immediate 的“只响应用户交互”区分开。
+    const immediateDeps = useMemo(() => (schema.linkage ?? [])
+        .filter((rule) => rule.immediate)
+        .flatMap((rule) => rule.dependencies), [schema]);
+    // 依赖订阅：用稳定 selector + ref 取最新依赖，
+    // 避免把一个 NamePath 数组误当成单条嵌套路径传给 useWatch。
+    const dependencies = schema.dynamic?.dependencies ?? EMPTY_DEPS;
+    const watchDependencies = useMemo(() => immediateDeps.length
+        ? dedupeNamePaths([...dependencies, ...immediateDeps])
+        : dependencies, [dependencies, immediateDeps]);
+    const depsRef = useRef(watchDependencies);
+    depsRef.current = watchDependencies;
+    const selector = useMemo(() => (values) => depsRef.current.map((dep) => getNestedValue(values, dep)), []);
+    // useWatch 内部按 JSON 比较，值没变就返回同一个引用，可直接做 effect 依赖
+    const watchedDeps = Form.useWatch(selector, { form, preserve: true });
+    // schema 多为模块级常量，用 ref 兜住内联定义，避免每次渲染都重跑 immediate 规则
+    const schemaRef = useRef(schema);
+    schemaRef.current = schema;
+    useEffect(() => {
+        // undefined 是 useWatch 首帧占位，等它读到真实依赖值再跑，避免初始化跑两遍
+        if (!immediateDeps.length || watchedDeps === undefined)
+            return;
+        host?.runImmediateRulesOf(schemaRef.current);
+    }, [host, watchedDeps, immediateDeps.length]);
+    return _jsx(FieldBody, { ...props });
+}
+function FieldContent({ schema, compact, mode, disabled, derived }) {
+    const form = Form.useFormInstance();
+    const host = useFormRuntimeHost();
+    const visible = derived.visible;
+    // 隐藏期间跳过校验：清掉历史错误，重新显示后按当时的规则恢复
+    const nameKey = namePathKey(schema.name);
+    useEffect(() => {
+        if (!visible) {
+            form.setFields([{ name: schema.name, errors: [] }]);
+        }
+        // name 用 nameKey 表达，避免数组字面量每次渲染都触发
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [visible, form, nameKey]);
+    const finalMode = mode ?? schema.mode ?? 'edit';
+    if (finalMode === 'read') {
+        // 只读态同样消费派生结果：props 里的 queryParams / options / format 必须透传
+        return _jsx(ReadableSchemaFormField, { schema: schema, state: derived, compact: compact });
+    }
+    // dynamic.disabled 覆盖字段级 props.disabled；表单级 disabled 永远优先
+    const finalDisabled = disabled ? true : derived.disabled;
+    const rules = derived.rules;
+    const field = withDerivedProps(schema, derived.props);
+    const itemProps = {
+        name: schema.name,
+        // 表格单元格由列头承担标题，compact 不重复渲染 label
+        label: compact ? undefined : schema.label,
+        rules,
+        dependencies: schema.dependencies,
+        hidden: !visible,
+        ...(compact ? { style: { marginBottom: 0 } } : null),
+        ...schema.formItemProps,
+    };
+    return (_jsx(Form.Item, { ...itemProps, children: _jsx(BoundField, { fieldSchema: schema, field: field, host: host, disabled: finalDisabled }) }));
+}
+/**
+ * Form.Item 固定以 value/onChange 注入，控件各自的受控属性名由 SchemaField 的注册表处理。
+ * 事件顺序：先写 Form Store，再派发 events/linkage，保证 ctx.get() 读到新值。
+ */
+function BoundField({ value, onChange, id, fieldSchema, field, host, disabled }) {
+    const handleChange = (next, ...meta) => {
+        // Form.Item 的受控写入是同步的，先落 Store 再派发，保证 ctx.get() 读到新值
+        onChange?.(next);
+        host?.dispatchUserChange(fieldSchema, next, meta);
+    };
+    return (_jsx(SchemaField, { schema: field, value: value, onChange: handleChange, disabled: disabled, id: id }));
+}
+/**
+ * 只读字段：轻量展示，订阅 Store 但不注册具名 Form.Item、不参与校验。
+ *
+ * 不注册指的是不传 name；label 与外层布局仍要走 Form.Item，
+ * 否则整表只读后会只剩一列值、字段名全丢，和编辑态对不上。
+ */
+function ReadableSchemaFormField({ schema, state, compact, }) {
+    const form = Form.useFormInstance();
+    const value = Form.useWatch(schema.name, { form, preserve: true });
+    // dynamic.visible 同样作用于只读态；普通表单隐藏即不渲染（表格由列自己保留 <td>）
+    if (!state.visible)
+        return null;
+    return (_jsx(Form.Item, { label: compact ? undefined : schema.label, ...(compact ? { style: { marginBottom: 0 } } : null), ...schema.formItemProps, children: _jsx(SchemaField, { schema: withDerivedProps(schema, state.props), value: value, mode: "read" }) }));
+}
+//# sourceMappingURL=SchemaFormField.js.map

package/dist/form/SchemaFormField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaFormField.js","sourceRoot":"","sources":["../../src/form/SchemaFormField.tsx"],"names":[],"mappings":"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"}

package/dist/form/derive.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 字段状态的统一派生（统一运行契约 §3）。
+ *
+ * `dynamic` 是字段的运行时派生配置，不是编辑态专属配置：
+ * 编辑态与只读态必须共用这一份求值逻辑，两种模式只在
+ * 属性下发、校验、事件与写入行为上不同，派生结果本身一致。
+ */
+import type { FieldSchema, FormFieldSchema, ReadContext, Rule } from '../types.js';
+export interface DerivedFieldState {
+    /** 显示优先级：dynamic.visible > visible > !hidden > true */
+    visible: boolean;
+    /** 仅 dynamic.disabled 的结果；表单级 disabled 由调用方优先合并 */
+    disabled?: boolean;
+    /** 仅 dynamic.props 的覆盖项；静态 props 由调用方浅合并 */
+    props?: Record<string, unknown>;
+    /** 隐藏时规则为空：隐藏期间跳过校验 */
+    rules: Rule[];
+}
+/**
+ * 计算字段当前的有效状态。派生函数必须是纯函数，只依赖 dynamic.dependencies 声明的字段。
+ */
+export declare function deriveFieldState(schema: FormFieldSchema, ctx: ReadContext): DerivedFieldState;
+/** 把 dynamic.props 浅合并到静态 props 上，用于编辑态与只读态共用同一份有效属性 */
+export declare function withDerivedProps<T extends FieldSchema>(schema: T, props?: Record<string, unknown>): T;
+/**
+ * 用行记录构造只读上下文。
+ *
+ * 单活动行表格的 Form Store 里只有活动行的草稿，普通行没有自己的 Form，
+ * 必须从 record 取数；用 Form 会读到活动行的值（错行）。
+ * `getValues()` 因此返回整条行记录，而不是整表值。
+ */
+export declare function createRecordReadContext(record: unknown): ReadContext;
+//# sourceMappingURL=derive.d.ts.map

package/dist/form/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/form/derive.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAW,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAGzF,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,uBAAuB;IACvB,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAqBD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,EAAE,WAAW,GAAG,iBAAiB,CAsB7F;AAED,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EACpD,MAAM,EAAE,CAAC,EACT,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,CAAC,CAGH;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,CAMpE"}