@chenzy-design/svelte 0.3.0 → 0.4.1

package/dist/form/input-group-context.js

@@ -0,0 +1,17 @@
+/**
+ * FormInputGroup 内部 context —— 让组内 <Form.Field> 自动进入 group 模式
+ * （对齐 Semi group.tsx 的 React.cloneElement(child, { isInInputGroup: true })）。
+ *
+ * Semi 在 React 里靠 cloneElement 给每个子 Field 注入 isInInputGroup；Svelte 无法克隆
+ * snippet 子节点注入 prop，改用 context：FormInputGroup setContext，Field 读到即：
+ *   1) 走 isInInputGroup 模式（不在 Field 内插 Label/ErrorMessage）；
+ *   2) 把自己的 field 名注册进来，供 GroupError 聚合组内所有字段错误。
+ */
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol('cd-form-input-group');
+export function setFormInputGroupContext(ctx) {
+    setContext(KEY, ctx);
+}
+export function getFormInputGroupContext() {
+    return getContext(KEY);
+}

package/dist/form/meta.d.ts

@@ -6,7 +6,85 @@ export declare const meta: {
     readonly name: "Form";
     readonly category: "input";
     readonly description: "表单容器，桥接 headless createForm，提供字段注册、校验、布局与 a11y。";
-    readonly subComponents: readonly ["Form.Field", "Form.Input"];
+    readonly subComponents: readonly [{
+        readonly name: "Form.Field";
+        readonly desc: "通用字段包裹器：注册字段、渲染 Label / 必填星标 / 错误提示，snippet 暴露 value/onChange/status/id 等，用于包装任意控件。";
+    }, {
+        readonly name: "Form.List";
+        readonly desc: "动态字段数组：children snippet 暴露 items / add / remove / move / name(item, sub)，用于可增删的重复字段组。";
+    }, {
+        readonly name: "Form.Input";
+        readonly desc: "绑定字段的单行输入框（Field + Input）。";
+    }, {
+        readonly name: "Form.Select";
+        readonly desc: "绑定字段的下拉选择（Field + Select）。";
+    }, {
+        readonly name: "Form.Checkbox";
+        readonly desc: "绑定字段的复选框（Field + Checkbox，valuePropName=checked）。";
+    }, {
+        readonly name: "Form.CheckboxGroup";
+        readonly desc: "绑定字段的复选框组（Field + CheckboxGroup），值为选中项数组。";
+    }, {
+        readonly name: "Form.Radio";
+        readonly desc: "绑定字段的单选框（Field + Radio）。";
+    }, {
+        readonly name: "Form.RadioGroup";
+        readonly desc: "绑定字段的单选框组（Field + RadioGroup），onChange 取 e.target.value。";
+    }, {
+        readonly name: "Form.TextArea";
+        readonly desc: "绑定字段的多行文本框（Field + TextArea）。";
+    }, {
+        readonly name: "Form.InputNumber";
+        readonly desc: "绑定字段的数字输入框（Field + InputNumber）。";
+    }, {
+        readonly name: "Form.TimePicker";
+        readonly desc: "绑定字段的时间选择（Field + TimePicker）。";
+    }, {
+        readonly name: "Form.AutoComplete";
+        readonly desc: "绑定字段的自动补全输入（Field + AutoComplete）。";
+    }, {
+        readonly name: "Form.PinCode";
+        readonly desc: "绑定字段的验证码输入（Field + PinCode），值为整串字符串。";
+    }, {
+        readonly name: "Form.Switch";
+        readonly desc: "绑定字段的开关（Field + Switch，valuePropName=checked）。";
+    }, {
+        readonly name: "Form.Slider";
+        readonly desc: "绑定字段的滑块（Field + Slider）。";
+    }, {
+        readonly name: "Form.Rating";
+        readonly desc: "绑定字段的评分（Field + Rating）。";
+    }, {
+        readonly name: "Form.DatePicker";
+        readonly desc: "绑定字段的日期选择（Field + DatePicker）。";
+    }, {
+        readonly name: "Form.TagInput";
+        readonly desc: "绑定字段的标签输入（Field + TagInput）。";
+    }, {
+        readonly name: "Form.TreeSelect";
+        readonly desc: "绑定字段的树选择（Field + TreeSelect）。";
+    }, {
+        readonly name: "Form.Cascader";
+        readonly desc: "绑定字段的级联选择（Field + Cascader）。";
+    }, {
+        readonly name: "Form.Upload";
+        readonly desc: "绑定字段的上传（Field + Upload）。";
+    }, {
+        readonly name: "Form.Section";
+        readonly desc: "字段分组容器，带分区标题（text）。";
+    }, {
+        readonly name: "Form.Slot";
+        readonly desc: "在表单布局内自由插入非字段内容（保持栅格/间距一致）。";
+    }, {
+        readonly name: "Form.Label";
+        readonly desc: "可独立组合的字段标签原子。";
+    }, {
+        readonly name: "Form.ErrorMessage";
+        readonly desc: "可独立组合的字段错误信息原子。";
+    }, {
+        readonly name: "Form.InputGroup";
+        readonly desc: "字段组容器：把内部多字段的 Label/ErrorMessage 上提到 group 级统一渲染，控件无缝拼接，GroupError 聚合组内错误（对齐 Semi Form.InputGroup）。";
+    }];
     readonly props: readonly [{
         readonly name: "value";
         readonly type: "Record<string, unknown>";
@@ -17,6 +95,11 @@ export declare const meta: {
         readonly type: "Record<string, unknown>";
         readonly default: "{}";
         readonly desc: "非受控初始值";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "form 元素 id（同时写 x-form-id 供外部 DOM 定位）（Semi id）";
     }, {
         readonly name: "layout";
         readonly type: "'vertical'|'horizontal'";
@@ -34,10 +117,6 @@ export declare const meta: {
         readonly type: "'left'|'right'";
         readonly default: "left";
         readonly desc: "Label 文本对齐（spec §4）";
-    }, {
-        readonly name: "size";
-        readonly type: "'small'|'default'|'large'";
-        readonly default: "default";
     }, {
         readonly name: "disabled";
         readonly type: "boolean";
@@ -46,10 +125,6 @@ export declare const meta: {
         readonly name: "requiredMark";
         readonly type: "boolean";
         readonly default: "true";
-    }, {
-        readonly name: "colon";
-        readonly type: "boolean";
-        readonly default: "false";
     }, {
         readonly name: "scrollToError";
         readonly type: "boolean";
@@ -71,27 +146,53 @@ export declare const meta: {
         readonly default: "false";
         readonly desc: "字段命中首条错误即停止该字段后续 rule（spec §4）";
     }, {
-        readonly name: "preventDefault";
-        readonly type: "boolean";
-        readonly default: "true";
-        readonly desc: "是否拦截原生 submit 默认行为（spec §4）";
+        readonly name: "stopPropagation";
+        readonly type: "{ submit?: boolean; reset?: boolean }";
+        readonly default: "undefined";
+        readonly desc: "提交/重置时是否阻止事件冒泡（对齐 Semi 对象形态）";
     }, {
         readonly name: "allowEmpty";
         readonly type: "boolean";
         readonly default: "false";
         readonly desc: "收集值时是否保留空值字段键（spec §4）";
+    }, {
+        readonly name: "autoScrollToError";
+        readonly type: "boolean | ScrollIntoViewOptions";
+        readonly default: "false";
+        readonly desc: "scrollToError 别名，可传 ScrollIntoViewOptions（Semi autoScrollToError）";
+    }, {
+        readonly name: "getFormApi";
+        readonly type: "(formApi: FormApi & { scrollToField; scrollToError }) => void";
+        readonly default: "undefined";
+        readonly desc: "Form 挂载后一次性回传内部 FormApi 句柄（含 scrollToField/scrollToError），供父级外部命令式 setValues/validate/reset（Semi getFormApi）";
     }, {
         readonly name: "onSubmit";
         readonly type: "(r: { valid; values; errors }) => void";
         readonly default: "undefined";
+    }, {
+        readonly name: "onSubmitFail";
+        readonly type: "(errors, values, e: SubmitEvent) => void";
+        readonly default: "undefined";
+        readonly desc: "校验失败回调（带原生 submit 事件）（Semi onSubmitFail）";
     }, {
         readonly name: "onChange";
         readonly type: "(values: Record<string, unknown>) => void";
         readonly default: "undefined";
+    }, {
+        readonly name: "onReset";
+        readonly type: "() => void";
+        readonly default: "undefined";
+        readonly desc: "表单重置时回调（原生 reset 或 formApi.reset()）（Semi onReset）";
+    }, {
+        readonly name: "onErrorChange";
+        readonly type: "(errors, changedError) => void";
+        readonly default: "undefined";
+        readonly desc: "任意字段错误集合变化时回调，入参为最新 errors + 变更子集（Semi onErrorChange）";
     }, {
         readonly name: "children";
-        readonly type: "Snippet";
+        readonly type: "Snippet<[{ formState; formApi }]> | Snippet";
         readonly default: "undefined";
+        readonly desc: "表单内容；带参 snippet 可拿 formState/formApi（Semi children-as-function）";
     }, {
         readonly name: "footer";
         readonly type: "Snippet<[{ submitting: boolean }]>";
@@ -103,8 +204,69 @@ export declare const meta: {
         readonly desc: "字段名（必填）";
     }, {
         readonly name: "Field.label";
+        readonly type: "string | { text; align; width; required; extra; optional }";
+        readonly default: "undefined";
+        readonly desc: "标签：字符串或对象形态（对齐 Semi LabelProps）";
+    }, {
+        readonly name: "Field.labelPosition";
+        readonly type: "'top'|'left'|'inset'";
+        readonly default: "继承容器";
+        readonly desc: "field 级 label 位置覆盖";
+    }, {
+        readonly name: "Field.labelAlign";
+        readonly type: "'left'|'right'";
+        readonly default: "继承容器";
+        readonly desc: "field 级 label 对齐覆盖";
+    }, {
+        readonly name: "Field.labelWidth";
+        readonly type: "number | string";
+        readonly default: "继承容器";
+        readonly desc: "field 级 label 宽度覆盖（left 模式）";
+    }, {
+        readonly name: "Field.noLabel";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "只去 Label 保留 error/wrapper（Semi noLabel）";
+    }, {
+        readonly name: "Field.noErrorMessage";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "只去错误/提示信息块（Semi noErrorMessage）";
+    }, {
+        readonly name: "Field.name";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "label 的 htmlFor 目标（默认用自动 id）（Semi name）";
+    }, {
+        readonly name: "Field.fieldClassName";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "field wrapper 的 class 透传（Semi fieldClassName）";
+    }, {
+        readonly name: "Field.fieldStyle";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "field wrapper 的内联样式透传（Semi fieldStyle）";
+    }, {
+        readonly name: "Field.helpText";
         readonly type: "string";
         readonly default: "undefined";
+        readonly desc: "提示文案，与 error 同块（error 优先）（Semi helpText）";
+    }, {
+        readonly name: "Field.extraTextPosition";
+        readonly type: "'middle'|'bottom'";
+        readonly default: "继承容器";
+        readonly desc: "field 级 extraText 位置覆盖";
+    }, {
+        readonly name: "Field.pure";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "只接管数据流，不插 Label/ErrorMessage/extra（Semi pure）";
+    }, {
+        readonly name: "Field.isInInputGroup";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "group 内字段模式，Label/ErrorMessage 交由 Group 渲染（Semi isInInputGroup）";
     }, {
         readonly name: "Field.rules";
         readonly type: "Rule[]";
@@ -212,7 +374,7 @@ export declare const meta: {
         readonly type: "'text'|'password'";
         readonly default: "text";
     }, {
-        readonly name: "Input.clearable";
+        readonly name: "Input.showClear";
         readonly type: "boolean";
         readonly default: "false";
     }, {
@@ -229,11 +391,46 @@ export declare const meta: {
         readonly type: "'change'|'blur'|'submit'|'mount'|string[]";
         readonly default: "继承容器";
         readonly desc: "字段级校验时机覆盖（spec §4）";
+    }, {
+        readonly name: "form";
+        readonly type: "FormApi";
+        readonly default: "undefined";
+        readonly desc: "外部预建 FormApi（createForm()），传入则用它，父层可立即操作（对齐 Semi Form.useForm()+form=）；不传则内部创建";
+    }, {
+        readonly name: "InputGroup.label";
+        readonly type: "string | { text; align; width; required; extra; optional }";
+        readonly default: "undefined";
+        readonly desc: "组级标签（Label 上提到 group 级）";
+    }, {
+        readonly name: "InputGroup.labelPosition";
+        readonly type: "'top'|'left'";
+        readonly default: "继承容器";
+        readonly desc: "组标签位置";
+    }, {
+        readonly name: "InputGroup.extraText";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "额外说明文本";
+    }, {
+        readonly name: "InputGroup.extraTextPosition";
+        readonly type: "'bottom'|'middle'";
+        readonly default: "bottom";
+        readonly desc: "额外说明位置";
+    }, {
+        readonly name: "InputGroup.size";
+        readonly type: "'small'|'default'|'large'";
+        readonly default: "undefined";
+        readonly desc: "整组尺寸，透传给内部控件";
+    }, {
+        readonly name: "InputGroup.children";
+        readonly type: "Snippet";
+        readonly default: "undefined";
+        readonly desc: "组内多个 <Form.Field>；自动进入 isInInputGroup 模式，Label/Error 上提 group 级";
     }];
     readonly a11y: {
         readonly role: "form";
         readonly notes: readonly ["原生 <form>，submit 经 preventDefault 接管", "字段错误用 role=alert，经 aria-describedby 关联控件", "extraText 无错误时经 aria-describedby 关联", "必填星标 aria-hidden，必填语义由校验承载", "Form.Input 经 Field 自动生成的 id 用 label for/id 精确关联控件（点击 label 聚焦 input）；id 也可由 Input 外部传入"];
     };
-    readonly tokens: readonly ["--cd-form-item-gap", "--cd-form-label-color", "--cd-form-label-gap", "--cd-form-required-color", "--cd-form-optional-color", "--cd-form-extra-color", "--cd-form-error-color", "--cd-form-error-font-size", "--cd-spacing-*", "--cd-color-*"];
+    readonly tokens: readonly ["--cd-form-spinner-track-color", "--cd-form-spinner-active-color", "--cd-spacing-form-field-horizontal-paddingright", "--cd-spacing-form-field-group-horizontal-paddingright", "--cd-spacing-form-field-vertical-paddingtop", "--cd-spacing-form-field-vertical-paddingbottom", "--cd-spacing-form-field-group-vertical-paddingtop", "--cd-spacing-form-field-group-vertical-paddingbottom", "--cd-spacing-form-label-paddingright", "--cd-spacing-form-label-paddingtop", "--cd-spacing-form-label-marginbottom", "--cd-spacing-form-label-margintop", "--cd-spacing-form-label-extra-marginleft", "--cd-spacing-form-label-required-marginleft", "--cd-spacing-form-label-posleft-marginright", "--cd-spacing-form-label-posleft-marginbottom", "--cd-spacing-form-label-postop-paddingtop", "--cd-spacing-form-label-postop-paddingbottom", "--cd-spacing-form-extra-posmid-margintop", "--cd-spacing-form-extra-posmid-marginbottom", "--cd-spacing-form-extra-posbottom-margintop", "--cd-spacing-form-switch-rating-marginy", "--cd-color-form-requiredmark-disabled-text-default", "--cd-color-form-label-disabled-text-default", "--cd-font-form-label-fontweight", "--cd-color-form-label-text-default", "--cd-color-form-label-optional-text-default", "--cd-color-form-label-extra-text-default", "--cd-color-form-requiredmark-text-default", "--cd-font-form-requiredmark-fontweight", "--cd-color-form-message-error-text-default", "--cd-color-form-alerticon-icon-default", "--cd-spacing-form-statusicon-marginright", "--cd-spacing-form-message-margintop", "--cd-color-form-section-text-default", "--cd-color-form-section-border-default", "--cd-width-form-section-border", "--cd-spacing-form-section-margintop", "--cd-spacing-form-section-text-paddingbottom", "--cd-spacing-form-section-text-marginbottom", "--cd-spacing-form-section-text-paddingtop", "--cd-spacing-form-section-text-margintop", "--cd-spacing-*", "--cd-color-*"];
 };
 //# sourceMappingURL=meta.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/form/meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgFP,CAAC"}
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/form/meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwKP,CAAC"}

package/dist/form/meta.js

@@ -6,31 +6,74 @@ export const meta = {
     name: 'Form',
     category: 'input',
     description: '表单容器，桥接 headless createForm，提供字段注册、校验、布局与 a11y。',
-    subComponents: ['Form.Field', 'Form.Input'],
+    subComponents: [
+        { name: 'Form.Field', desc: '通用字段包裹器：注册字段、渲染 Label / 必填星标 / 错误提示，snippet 暴露 value/onChange/status/id 等，用于包装任意控件。' },
+        { name: 'Form.List', desc: '动态字段数组：children snippet 暴露 items / add / remove / move / name(item, sub)，用于可增删的重复字段组。' },
+        { name: 'Form.Input', desc: '绑定字段的单行输入框（Field + Input）。' },
+        { name: 'Form.Select', desc: '绑定字段的下拉选择（Field + Select）。' },
+        { name: 'Form.Checkbox', desc: '绑定字段的复选框（Field + Checkbox，valuePropName=checked）。' },
+        { name: 'Form.CheckboxGroup', desc: '绑定字段的复选框组（Field + CheckboxGroup），值为选中项数组。' },
+        { name: 'Form.Radio', desc: '绑定字段的单选框（Field + Radio）。' },
+        { name: 'Form.RadioGroup', desc: '绑定字段的单选框组（Field + RadioGroup），onChange 取 e.target.value。' },
+        { name: 'Form.TextArea', desc: '绑定字段的多行文本框（Field + TextArea）。' },
+        { name: 'Form.InputNumber', desc: '绑定字段的数字输入框（Field + InputNumber）。' },
+        { name: 'Form.TimePicker', desc: '绑定字段的时间选择（Field + TimePicker）。' },
+        { name: 'Form.AutoComplete', desc: '绑定字段的自动补全输入（Field + AutoComplete）。' },
+        { name: 'Form.PinCode', desc: '绑定字段的验证码输入（Field + PinCode），值为整串字符串。' },
+        { name: 'Form.Switch', desc: '绑定字段的开关（Field + Switch，valuePropName=checked）。' },
+        { name: 'Form.Slider', desc: '绑定字段的滑块（Field + Slider）。' },
+        { name: 'Form.Rating', desc: '绑定字段的评分（Field + Rating）。' },
+        { name: 'Form.DatePicker', desc: '绑定字段的日期选择（Field + DatePicker）。' },
+        { name: 'Form.TagInput', desc: '绑定字段的标签输入（Field + TagInput）。' },
+        { name: 'Form.TreeSelect', desc: '绑定字段的树选择（Field + TreeSelect）。' },
+        { name: 'Form.Cascader', desc: '绑定字段的级联选择（Field + Cascader）。' },
+        { name: 'Form.Upload', desc: '绑定字段的上传（Field + Upload）。' },
+        { name: 'Form.Section', desc: '字段分组容器，带分区标题（text）。' },
+        { name: 'Form.Slot', desc: '在表单布局内自由插入非字段内容（保持栅格/间距一致）。' },
+        { name: 'Form.Label', desc: '可独立组合的字段标签原子。' },
+        { name: 'Form.ErrorMessage', desc: '可独立组合的字段错误信息原子。' },
+        { name: 'Form.InputGroup', desc: '字段组容器：把内部多字段的 Label/ErrorMessage 上提到 group 级统一渲染，控件无缝拼接，GroupError 聚合组内错误（对齐 Semi Form.InputGroup）。' },
+    ],
     props: [
         { name: 'value', type: 'Record<string, unknown>', default: 'undefined', desc: '受控整表单值；变更经 onChange 上报' },
         { name: 'initValues', type: 'Record<string, unknown>', default: '{}', desc: '非受控初始值' },
+        { name: 'id', type: 'string', default: 'undefined', desc: 'form 元素 id（同时写 x-form-id 供外部 DOM 定位）（Semi id）' },
         { name: 'layout', type: "'vertical'|'horizontal'", default: 'vertical' },
         { name: 'labelPosition', type: "'top'|'left'|'inset'", default: 'top' },
         { name: 'labelWidth', type: 'number | string', default: 'undefined' },
         { name: 'labelAlign', type: "'left'|'right'", default: 'left', desc: 'Label 文本对齐（spec §4）' },
-        { name: 'size', type: "'small'|'default'|'large'", default: 'default' },
         { name: 'disabled', type: 'boolean', default: 'false' },
         { name: 'requiredMark', type: 'boolean', default: 'true' },
-        { name: 'colon', type: 'boolean', default: 'false' },
         { name: 'scrollToError', type: 'boolean', default: 'false', desc: '提交校验失败时滚动并聚焦首个错误字段' },
         { name: 'validateTrigger', type: "'change'|'blur'|'submit'|'mount'|string[]", default: "['blur','change']", desc: '全局默认校验时机，字段可经 trigger 覆盖（spec §4）' },
         { name: 'showValidateIcon', type: 'boolean', default: 'true', desc: '错误/警告文案是否带状态图标（spec §4）' },
         { name: 'stopValidateWithError', type: 'boolean', default: 'false', desc: '字段命中首条错误即停止该字段后续 rule（spec §4）' },
-        { name: 'preventDefault', type: 'boolean', default: 'true', desc: '是否拦截原生 submit 默认行为（spec §4）' },
+        { name: 'stopPropagation', type: '{ submit?: boolean; reset?: boolean }', default: 'undefined', desc: '提交/重置时是否阻止事件冒泡（对齐 Semi 对象形态）' },
         { name: 'allowEmpty', type: 'boolean', default: 'false', desc: '收集值时是否保留空值字段键（spec §4）' },
+        { name: 'autoScrollToError', type: 'boolean | ScrollIntoViewOptions', default: 'false', desc: 'scrollToError 别名，可传 ScrollIntoViewOptions（Semi autoScrollToError）' },
+        { name: 'getFormApi', type: '(formApi: FormApi & { scrollToField; scrollToError }) => void', default: 'undefined', desc: 'Form 挂载后一次性回传内部 FormApi 句柄（含 scrollToField/scrollToError），供父级外部命令式 setValues/validate/reset（Semi getFormApi）' },
         { name: 'onSubmit', type: '(r: { valid; values; errors }) => void', default: 'undefined' },
+        { name: 'onSubmitFail', type: '(errors, values, e: SubmitEvent) => void', default: 'undefined', desc: '校验失败回调（带原生 submit 事件）（Semi onSubmitFail）' },
         { name: 'onChange', type: '(values: Record<string, unknown>) => void', default: 'undefined' },
-        { name: 'children', type: 'Snippet', default: 'undefined' },
+        { name: 'onReset', type: '() => void', default: 'undefined', desc: '表单重置时回调（原生 reset 或 formApi.reset()）（Semi onReset）' },
+        { name: 'onErrorChange', type: '(errors, changedError) => void', default: 'undefined', desc: '任意字段错误集合变化时回调，入参为最新 errors + 变更子集（Semi onErrorChange）' },
+        { name: 'children', type: 'Snippet<[{ formState; formApi }]> | Snippet', default: 'undefined', desc: '表单内容；带参 snippet 可拿 formState/formApi（Semi children-as-function）' },
         { name: 'footer', type: 'Snippet<[{ submitting: boolean }]>', default: 'undefined' },
         // Form.Field
         { name: 'Field.field', type: 'string', default: '—', desc: '字段名（必填）' },
-        { name: 'Field.label', type: 'string', default: 'undefined' },
+        { name: 'Field.label', type: 'string | { text; align; width; required; extra; optional }', default: 'undefined', desc: '标签：字符串或对象形态（对齐 Semi LabelProps）' },
+        { name: 'Field.labelPosition', type: "'top'|'left'|'inset'", default: '继承容器', desc: 'field 级 label 位置覆盖' },
+        { name: 'Field.labelAlign', type: "'left'|'right'", default: '继承容器', desc: 'field 级 label 对齐覆盖' },
+        { name: 'Field.labelWidth', type: 'number | string', default: '继承容器', desc: 'field 级 label 宽度覆盖（left 模式）' },
+        { name: 'Field.noLabel', type: 'boolean', default: 'false', desc: '只去 Label 保留 error/wrapper（Semi noLabel）' },
+        { name: 'Field.noErrorMessage', type: 'boolean', default: 'false', desc: '只去错误/提示信息块（Semi noErrorMessage）' },
+        { name: 'Field.name', type: 'string', default: 'undefined', desc: 'label 的 htmlFor 目标（默认用自动 id）（Semi name）' },
+        { name: 'Field.fieldClassName', type: 'string', default: 'undefined', desc: 'field wrapper 的 class 透传（Semi fieldClassName）' },
+        { name: 'Field.fieldStyle', type: 'string', default: 'undefined', desc: 'field wrapper 的内联样式透传（Semi fieldStyle）' },
+        { name: 'Field.helpText', type: 'string', default: 'undefined', desc: '提示文案，与 error 同块（error 优先）（Semi helpText）' },
+        { name: 'Field.extraTextPosition', type: "'middle'|'bottom'", default: '继承容器', desc: 'field 级 extraText 位置覆盖' },
+        { name: 'Field.pure', type: 'boolean', default: 'false', desc: '只接管数据流，不插 Label/ErrorMessage/extra（Semi pure）' },
+        { name: 'Field.isInInputGroup', type: 'boolean', default: 'false', desc: 'group 内字段模式，Label/ErrorMessage 交由 Group 渲染（Semi isInInputGroup）' },
         { name: 'Field.rules', type: 'Rule[]', default: '[]' },
         { name: 'Field.initValue', type: 'unknown', default: 'undefined', desc: '字段级初始值，覆盖容器 initValues（spec §4.2）' },
         { name: 'Field.required', type: 'boolean', default: 'false' },
@@ -55,10 +98,19 @@ export const meta = {
         { name: 'Input.transform', type: '(v, values) => unknown', default: 'undefined', desc: '提交前值转换（纯函数）（spec §4.2）' },
         { name: 'Input.placeholder', type: 'string', default: 'undefined' },
         { name: 'Input.type', type: "'text'|'password'", default: 'text' },
-        { name: 'Input.clearable', type: 'boolean', default: 'false' },
+        { name: 'Input.showClear', type: 'boolean', default: 'false' },
         { name: 'Input.maxLength', type: 'number', default: 'undefined' },
         { name: 'Input.dependencies', type: 'string[]', default: 'undefined', desc: '依赖字段名；其值变化时本字段自动重校验' },
         { name: 'Input.trigger', type: "'change'|'blur'|'submit'|'mount'|string[]", default: '继承容器', desc: '字段级校验时机覆盖（spec §4）' },
+        // Form 顶层：外部预建 form
+        { name: 'form', type: 'FormApi', default: 'undefined', desc: '外部预建 FormApi（createForm()），传入则用它，父层可立即操作（对齐 Semi Form.useForm()+form=）；不传则内部创建' },
+        // Form.InputGroup
+        { name: 'InputGroup.label', type: 'string | { text; align; width; required; extra; optional }', default: 'undefined', desc: '组级标签（Label 上提到 group 级）' },
+        { name: 'InputGroup.labelPosition', type: "'top'|'left'", default: '继承容器', desc: '组标签位置' },
+        { name: 'InputGroup.extraText', type: 'string', default: 'undefined', desc: '额外说明文本' },
+        { name: 'InputGroup.extraTextPosition', type: "'bottom'|'middle'", default: 'bottom', desc: '额外说明位置' },
+        { name: 'InputGroup.size', type: "'small'|'default'|'large'", default: 'undefined', desc: '整组尺寸，透传给内部控件' },
+        { name: 'InputGroup.children', type: 'Snippet', default: 'undefined', desc: '组内多个 <Form.Field>；自动进入 isInInputGroup 模式，Label/Error 上提 group 级' },
     ],
     a11y: {
         role: 'form',
@@ -71,14 +123,50 @@ export const meta = {
         ],
     },
     tokens: [
-        '--cd-form-item-gap',
-        '--cd-form-label-color',
-        '--cd-form-label-gap',
-        '--cd-form-required-color',
-        '--cd-form-optional-color',
-        '--cd-form-extra-color',
-        '--cd-form-error-color',
-        '--cd-form-error-font-size',
+        // —— 本库超集：异步校验 spinner（Semi 无，组件直接消费） ——
+        '--cd-form-spinner-track-color',
+        '--cd-form-spinner-active-color',
+        // —— 全量对齐 Semi form/variables.scss（field / label / extra / errormessage / section）；组件直接消费，无中间层 ——
+        '--cd-spacing-form-field-horizontal-paddingright',
+        '--cd-spacing-form-field-group-horizontal-paddingright',
+        '--cd-spacing-form-field-vertical-paddingtop',
+        '--cd-spacing-form-field-vertical-paddingbottom',
+        '--cd-spacing-form-field-group-vertical-paddingtop',
+        '--cd-spacing-form-field-group-vertical-paddingbottom',
+        '--cd-spacing-form-label-paddingright',
+        '--cd-spacing-form-label-paddingtop',
+        '--cd-spacing-form-label-marginbottom',
+        '--cd-spacing-form-label-margintop',
+        '--cd-spacing-form-label-extra-marginleft',
+        '--cd-spacing-form-label-required-marginleft',
+        '--cd-spacing-form-label-posleft-marginright',
+        '--cd-spacing-form-label-posleft-marginbottom',
+        '--cd-spacing-form-label-postop-paddingtop',
+        '--cd-spacing-form-label-postop-paddingbottom',
+        '--cd-spacing-form-extra-posmid-margintop',
+        '--cd-spacing-form-extra-posmid-marginbottom',
+        '--cd-spacing-form-extra-posbottom-margintop',
+        '--cd-spacing-form-switch-rating-marginy',
+        '--cd-color-form-requiredmark-disabled-text-default',
+        '--cd-color-form-label-disabled-text-default',
+        '--cd-font-form-label-fontweight',
+        '--cd-color-form-label-text-default',
+        '--cd-color-form-label-optional-text-default',
+        '--cd-color-form-label-extra-text-default',
+        '--cd-color-form-requiredmark-text-default',
+        '--cd-font-form-requiredmark-fontweight',
+        '--cd-color-form-message-error-text-default',
+        '--cd-color-form-alerticon-icon-default',
+        '--cd-spacing-form-statusicon-marginright',
+        '--cd-spacing-form-message-margintop',
+        '--cd-color-form-section-text-default',
+        '--cd-color-form-section-border-default',
+        '--cd-width-form-section-border',
+        '--cd-spacing-form-section-margintop',
+        '--cd-spacing-form-section-text-paddingbottom',
+        '--cd-spacing-form-section-text-marginbottom',
+        '--cd-spacing-form-section-text-paddingtop',
+        '--cd-spacing-form-section-text-margintop',
         '--cd-spacing-*',
         '--cd-color-*',
     ],