@printstack/print-studio 0.0.0-stage → 0.1.1

package/components/s-form/types.d.ts

@@ -0,0 +1,550 @@
+import { CheckboxGroupProps, DatePickerProps, DateRangePickerProps, InputNumberProps, InputProps, RadioGroupProps, SelectProps, SwitchProps, TextareaProps, TimePickerProps } from 'tdesign-vue-next';
+import { VNodeChild } from 'vue';
+/**
+ * 表单值对象（字段支持 dot-path 嵌套，如 'a.b'）
+ */
+export type SFormValues = Record<string, unknown>;
+/**
+ * 透传给表单组件 / t-form-item 的插槽配置：字符串 = SForm 上的插槽名；函数 = scoped 渲染函数
+ */
+export type SFormSlotConfig = Record<string, ((params?: any) => VNodeChild) | string>;
+/**
+ * 声明式显隐函数：随表单值变化重新计算
+ */
+export type SFormHiddenResolver = (context: {
+    values: SFormValues;
+}) => boolean;
+/**
+ * 字段校验状态：手动覆盖（schema status）与自动推导共用词表；
+ * validating 为校验异步执行期间的中间态
+ */
+export type SFormValidateStatus = 'error' | 'success' | 'validating' | 'warning';
+/**
+ * 单个字段的响应式校验状态：
+ * - touched：用户是否操作过（仅控件输入路径置位，程序化 setValues 不置）
+ * - validating：该字段的校验是否在异步执行中
+ * - errorMessages：错误消息（阻塞提交）
+ * - warningMessages：警告消息（不阻塞提交，对齐 antd warningOnly 语义）
+ */
+export interface SFormFieldState {
+    errorMessages: string[];
+    touched: boolean;
+    validating: boolean;
+    warningMessages: string[];
+}
+/**
+ * 字段的消息子集（validate 结果与 setFieldState 增量使用）
+ */
+export interface SFormFieldMessages {
+    errorMessages: string[];
+    warningMessages: string[];
+}
+/**
+ * setFieldState 的增量：传空数组即清除对应消息，传 touched 显式置位/复位
+ */
+export type SFormFieldStatePatch = Partial<Pick<SFormFieldState, 'errorMessages' | 'touched' | 'warningMessages'>>;
+/**
+ * validateFields 选项（对齐 antd validateFields config）：
+ * - fields：只校验指定字段
+ * - validateOnly：只算状态不落错误消息（UI 不展示）
+ * - dirty：只校验已 touched 的字段
+ */
+export interface SFormValidateOptions {
+    dirty?: boolean;
+    fields?: string[];
+    validateOnly?: boolean;
+}
+/**
+ * validate / validateFields 的结构化结果；
+ * submit 校验失败时以该结构 reject
+ */
+export interface SFormValidateResult {
+    /**
+     * 有错误消息的字段 → 消息映射（含 validateOnly 场景的临时结果）
+     */
+    fields: Record<string, SFormFieldMessages>;
+    /**
+     * 是否通过（以 errorMessages 判定，warning 不阻塞）
+     */
+    valid: boolean;
+}
+/**
+ * 已注册的表单组件类型 → 透传 props 的类型映射。
+ *
+ * 内置 10 个 TDesign 控件映射；业务扩展方式（与运行时 registerSFormComponent 成对使用）：
+ *
+ * ```ts
+ * import type { DeclareSFormComponent } from '@/components/s-form/types'
+ *
+ * declare module '@/components/s-form/types' {
+ *   interface SFormComponentRegistry extends DeclareSFormComponent<'clickableTag', ClickableTagProps> {}
+ * }
+ * ```
+ *
+ * 注册表值既可以是 props 接口，也可以是组件定义类型（自动提取其 $props）。
+ */
+export interface SFormComponentRegistry {
+    /**
+     * TDesign CheckboxGroup
+     */
+    checkbox: CheckboxGroupProps;
+    /**
+     * TDesign DatePicker
+     */
+    datePicker: DatePickerProps;
+    /**
+     * TDesign DateRangePicker
+     */
+    dateRangePicker: DateRangePickerProps;
+    /**
+     * TDesign Input
+     */
+    input: InputProps;
+    /**
+     * TDesign InputNumber
+     */
+    inputNumber: InputNumberProps;
+    /**
+     * TDesign RadioGroup
+     */
+    radioGroup: RadioGroupProps;
+    /**
+     * TDesign Select
+     */
+    select: SelectProps;
+    /**
+     * TDesign Switch
+     */
+    switch: SwitchProps;
+    /**
+     * TDesign Textarea
+     */
+    textarea: TextareaProps;
+    /**
+     * TDesign TimePicker
+     */
+    timePicker: TimePickerProps;
+}
+export type SFormComponentType = keyof SFormComponentRegistry;
+/**
+ * 声明合并辅助工具：把自定义类型名映射到 props 类型（用于 interface extends）
+ */
+export type SFormControlProps = {
+    modelValue?: unknown;
+    'onUpdate:modelValue'?: (...args: any[]) => void;
+};
+export type DeclareSFormComponent<K extends string, P extends SFormControlProps> = {
+    [Key in K]: P;
+};
+/**
+ * 若注册表登记的是组件定义类型，则自动提取 $props
+ */
+type ResolveProps<T> = T extends new (...args: any[]) => {
+    $props: infer P;
+} ? P : T;
+export type SFormItemProps<K extends SFormComponentType> = ResolveProps<SFormComponentRegistry[K]>;
+/**
+ * 响应式列数：按表单容器宽度断点取值（xs<768、sm≥768、md≥992、lg≥1200、xl≥1400）
+ */
+export interface SFormResponsiveColumns {
+    lg?: number;
+    md?: number;
+    sm?: number;
+    xl?: number;
+    xs?: number;
+}
+/**
+ * 内置 grid 布局的表单级参数（schema 传入时平铺在 layout 配置上）
+ */
+export interface SFormGridLayoutProps {
+    /**
+     * maxRows 生效时是否显示「展开/收起」按钮，默认 true；false 时仅隐藏无按钮
+     */
+    collapsible?: boolean;
+    /**
+     * 列数，固定值或按容器宽度断点响应，默认 1
+     */
+    cols?: number | SFormResponsiveColumns;
+    /**
+     * 展开按钮文案 [展开, 收起]，默认 ['展开更多', '收起']
+     */
+    expandText?: [string, string];
+    /**
+     * 间距：统一值或 [水平间距, 垂直间距]
+     */
+    gap?: [number | string, number | string] | number | string;
+    /**
+     * 最大可见行数，超出的元素折叠隐藏（保持挂载，不退出校验）
+     */
+    maxRows?: number;
+}
+/**
+ * grid 布局下单个元素的 layoutConfig 配置
+ */
+export interface SFormGridItemLayout {
+    /**
+     * 左侧空出的列数，默认 0；空位不被后续元素回填
+     */
+    offset?: number;
+    /**
+     * 占据列数，默认 1，自动收敛到总列数内
+     */
+    span?: number;
+}
+/**
+ * 内置 flex 布局的表单级参数。
+ * 方向固定为行方向、自动换行、整体左对齐、行内顶对齐，不提供配置。
+ */
+export interface SFormFlexLayoutProps {
+    /**
+     * 是否显示「展开/收起」按钮，默认 true
+     */
+    collapsible?: boolean;
+    /**
+     * 逻辑列数（元素级 span / offset 的换算基准），固定值或按容器宽度断点响应，默认 1。
+     * 声明后元素宽度精确对齐列边界（自动扣除列间距）。
+     */
+    cols?: number | SFormResponsiveColumns;
+    /**
+     * 展开按钮文案 [展开, 收起]
+     */
+    expandText?: [string, string];
+    /**
+     * 间距：统一值或 [水平间距, 垂直间距]
+     */
+    gap?: [number | string, number | string] | number | string;
+    /**
+     * 元素默认宽度（元素未声明 width / span 时使用），如 240、'50%'
+     */
+    itemWidth?: number | string;
+    /**
+     * 最大可见行数（按换行模拟精确计算），超出折叠隐藏（保持挂载，不退出校验）
+     */
+    maxRows?: number;
+}
+/**
+ * flex 布局下单个元素的 layoutConfig 配置；宽度解析优先级 width > span > itemWidth > 默认 1 列
+ */
+export interface SFormFlexItemLayout {
+    /**
+     * 最大宽度约束
+     */
+    maxWidth?: number | string;
+    /**
+     * 最小宽度约束
+     */
+    minWidth?: number | string;
+    /**
+     * 左侧空出的列数，默认 0
+     */
+    offset?: number;
+    /**
+     * 占据的列数（相对表单级 cols），默认 1
+     */
+    span?: number;
+    /**
+     * 元素宽度，声明后优先于 span，如 240、'50%'
+     */
+    width?: number | string;
+}
+/**
+ * 已注册的布局类型映射，每个布局登记两层：
+ * - container：表单或分组容器的 layout 配置类型
+ * - item：该布局下 schema 元素级 layoutConfig 配置的类型
+ *
+ * 业务扩展方式（与运行时 registerSFormLayout 成对使用）：
+ *
+ * ```ts
+ * declare module '@/components/s-form/types' {
+ *   interface SFormLayoutRegistry extends DeclareSFormLayout<'tabs', {
+ *     container: { tabs: Array<{ label: string; value: string }>; defaultTab?: string }
+ *     item: { tab: string }
+ *   }> {}
+ * }
+ * ```
+ */
+export interface SFormLayoutRegistry {
+    flex: {
+        container: SFormFlexLayoutProps;
+        item: SFormFlexItemLayout;
+    };
+    grid: {
+        container: SFormGridLayoutProps;
+        item: SFormGridItemLayout;
+    };
+}
+export type SFormLayoutType = keyof SFormLayoutRegistry;
+/**
+ * 声明合并辅助工具：把自定义布局名映射到 { container, item } 两层配置类型（用于 interface extends）
+ */
+export type DeclareSFormLayout<K extends string, P> = {
+    [Key in K]: P;
+};
+/**
+ * schema 元素级 layoutConfig 配置：由父布局解释
+ */
+export type SFormItemLayout = {
+    [K in SFormLayoutType]: SFormLayoutRegistry[K]['item'];
+}[SFormLayoutType];
+/**
+ * 内置布局类型名（配置平铺）；自定义布局一律把参数收拢在 params 键下
+ */
+export type SFormBuiltinLayoutType = 'flex' | 'grid';
+/**
+ * 表单级 layout 配置：
+ * - 内置 grid / flex：参数平铺，如 `{ type: 'grid', cols: 2, maxRows: 4 }`
+ * - 自定义布局：参数收拢在 params 下（结构上与内置明显区分），如 `{ type: 'tabs', params: { tabs: [...] } }`
+ */
+export type SFormLayoutConfig = {
+    [K in Exclude<SFormLayoutType, SFormBuiltinLayoutType>]: {
+        params?: SFormLayoutRegistry[K]['container'];
+        type: K;
+    };
+}[Exclude<SFormLayoutType, SFormBuiltinLayoutType>] | {
+    [K in SFormBuiltinLayoutType]: SFormLayoutRegistry[K]['container'] & {
+        type: K;
+    };
+}[SFormBuiltinLayoutType] | {
+    params?: Record<string, unknown>;
+    type: Exclude<string, SFormBuiltinLayoutType>;
+};
+export interface SFormSchemaItemBase {
+    /**
+     * 初始缺省值（挂载及 reset 时补齐）
+     */
+    defaultValue?: unknown;
+    /**
+     * 上游字段列表（值路径）：任一上游经用户输入变化后，本字段自动重新校验
+     * （对齐 antd Form.Item dependencies；不响应程序化 setValues）
+     */
+    dependencies?: string[];
+    /**
+     * 字段名（值路径），支持 dot-path 访问嵌套值（如 'a.b'）；校验路径始终使用 field，与 id 无关
+     */
+    field: string;
+    /**
+     * 类型判别（普通元素恒为缺省或 false，分组节点为 true，可直接 if (item.group) 判断）
+     */
+    group?: never;
+    /**
+     * 帮助文案：恒展示于字段下方，与校验消息互不替代（完整 TNode 配置走 itemProps.help）
+     */
+    help?: string;
+    /**
+     * 声明式显隐：布尔或函数（随表单值响应重算）。隐藏的元素不渲染、不参与校验，值保留
+     */
+    hidden?: boolean | SFormHiddenResolver;
+    /**
+     * 元素唯一标识（显隐方法 / 定位链使用）；缺省时取 field 值充当
+     */
+    id?: string;
+    /**
+     * 透传至 t-form-item
+     */
+    itemProps?: Record<string, unknown>;
+    /**
+     * 透传至 t-form-item 的插槽
+     */
+    itemSlots?: SFormSlotConfig;
+    /**
+     * t-form-item 的 label 快捷方式（完整配置走 itemProps）
+     */
+    label?: string;
+    /**
+     * 元素级布局配置，由表单所使用的布局解释（grid: span / flex: basis 等；自定义布局自定义）
+     */
+    layoutConfig?: SFormItemLayout;
+    /**
+     * 显示必填星号（对齐 antd Form.Item required）；不设置时由 rules 是否含 required 推导
+     */
+    required?: boolean;
+    /**
+     * TDesign 校验规则：校验调度由 SForm 状态层驱动（change / blur 触发），格式与 TDesign FormRule 一致
+     */
+    rules?: Record<string, unknown>[];
+    /**
+     * 手动校验状态覆盖（对齐 antd validateStatus）；
+     * 不设置时由状态层自动推导：validating → error → warning
+     */
+    status?: SFormValidateStatus;
+}
+/**
+ * schema 条目：type 字面量决定 props / slots 的精确类型提示
+ */
+export type SFormSchemaItem = {
+    [K in SFormComponentType]: {
+        /**
+         * 透传至表单组件的 props（含 onXxx 事件回调）；值绑定由 SForm 接管
+         */
+        props?: SFormItemProps<K>;
+        /**
+         * 透传至表单组件的插槽
+         */
+        slots?: SFormSlotConfig;
+        type: K;
+    } & SFormSchemaItemBase;
+}[SFormComponentType];
+export type SFormSchema = SFormSchemaNode[];
+/**
+ * 分组节点：嵌套布局容器 + 显隐联动单元，以 group 对象判别。
+ *
+ * - 对外使用 layoutConfig 配置自身在父布局中的表现
+ * - 对内使用 group.layout 摆放 group.children
+ * - 纯结构概念，不产生数据层级：子元素 field 仍按全局路径存取 values
+ * - hidden 与普通元素同语义
+ */
+export interface SFormGroupSchema {
+    /**
+     * 分组判别标记
+     */
+    group: {
+        children: SFormSchemaNode[];
+        layout?: SFormLayoutConfig | SFormLayoutType;
+    };
+    /**
+     * 声明式显隐：布尔或函数（随表单值响应重算）。隐藏的组连同子元素不渲染、不参与校验，值保留
+     */
+    hidden?: boolean | SFormHiddenResolver;
+    /**
+     * 组唯一标识（必填，组无 field 可兜底），与所有元素 id 同一命名空间
+     */
+    id: string;
+    /**
+     * 组在父布局中的位置配置，由父布局解释
+     */
+    layoutConfig?: SFormItemLayout;
+}
+export type SFormSchemaNode = SFormGroupSchema | SFormSchemaItem;
+/**
+ * 布局组件收到的单个元素
+ */
+export interface SFormLayoutItem {
+    field: string;
+    /**
+     * 元素级布局配置
+     */
+    layoutConfig?: SFormItemLayout;
+    /**
+     * 渲染该元素（隐藏状态下返回 null）
+     */
+    render: () => VNodeChild;
+    /**
+     * 是否可见（隐藏的元素应跳过或渲染 null）
+     */
+    visible: boolean;
+}
+/**
+ * 布局组件必须/可选暴露的方法
+ */
+export interface SFormLayoutHandle {
+    /**
+     * 校验失败时定位字段（如切换 tab、展开折叠区、滚动到可视区）。
+     * 返回 true 表示已处理；返回 false / 未实现时 SForm 回退为滚动定位。
+     */
+    reveal?: (field: string) => boolean;
+}
+export interface SFormProps {
+    /**
+     * 表单级禁用：级联到全部字段控件（含自定义控件，字段级无法压过表单级）；
+     * 未设置时回落 formProps.disabled；表单未禁用时字段可单独 disabled
+     */
+    disabled?: boolean;
+    /**
+     * 透传至 t-form（labelWidth、labelAlign、showErrorMessage 等）
+     */
+    formProps?: Record<string, unknown>;
+    /**
+     * 表单级布局配置，默认 `{ type: 'grid' }`；也支持简写 `layout="grid"`
+     */
+    layout?: SFormLayoutConfig | SFormLayoutType;
+    /**
+     * 表单值（v-model）。
+     * 受控语义：外部 modelValue 为唯一真值源，其变化会整体对齐进内部
+     * （含删除外部已不存在的顶层 key），支持父组件整体重置 / 回填；
+     * 表单编辑经 update:modelValue 回流
+     */
+    modelValue?: SFormValues;
+    /**
+     * getValues / update:modelValue / submit 输出的快照是否剔除当前隐藏字段的值
+     * （含隐藏分组下的全部子字段，剔除后变空的父级对象级联删除）。
+     * 默认 false：隐藏字段值保留输出（向后兼容）；
+     * 内部状态始终保留隐藏字段的值，字段重新显示时原值不丢失
+     */
+    omitHiddenValues?: boolean;
+    /**
+     * 表单级只读：控件展示值但不可编辑（内置控件经 UI 库级联，自定义控件经上下文下发）；
+     * 未设置时回落 formProps.readonly
+     */
+    readonly?: boolean;
+    schema: SFormSchema;
+}
+/**
+ * SForm 组件实例方法（通过 ref 调用）
+ */
+export interface SFormInstance {
+    clearValidate(fields?: string[]): void;
+    /**
+     * 获取字段的错误消息（阻塞提交的那部分）；无错误返回空数组
+     */
+    getFieldError(field: string): string[];
+    /**
+     * 获取字段对应的表单组件实例
+     */
+    getFieldRef(field: string): unknown;
+    /**
+     * 批量获取字段错误消息映射；缺省收集全部有错误消息的字段
+     */
+    getFieldsError(fields?: string[]): Record<string, string[]>;
+    /**
+     * 获取字段的完整响应式状态（touched / validating / 消息）
+     */
+    getFieldState(field: string): SFormFieldState;
+    /**
+     * 获取字段的警告消息（不阻塞提交）；无警告返回空数组
+     */
+    getFieldWarnings(field: string): string[];
+    /**
+     * 获取当前值快照：与内部状态断开引用的深拷贝；
+     * omitHiddenValues 开启时剔除隐藏字段值
+     */
+    getValues(): SFormValues;
+    /**
+     * 批量 touched 检查：缺省收集全部已 touched 字段；
+     * allTouched 为 true 时要求列表内全部字段都被操作过才返回 true
+     */
+    isFieldsTouched(fields?: string[], allTouched?: boolean): boolean;
+    /**
+     * 字段是否被用户操作过（仅控件输入路径置位）
+     */
+    isFieldTouched(field: string): boolean;
+    /**
+     * 重置：恢复各字段 defaultValue、清空全部字段状态与校验结果
+     */
+    reset(): void;
+    /**
+     * 手动定位到某个字段（委托当前布局 reveal，回退滚动定位）
+     */
+    revealField(field: string): void;
+    /**
+     * 手动设置字段状态增量（对齐 antd setFields）：
+     * 程序化写入错误 / 警告 / touched，传空数组清除对应消息。
+     * 不触发校验
+     */
+    setFieldState(field: string, patch: SFormFieldStatePatch): void;
+    setFieldValue(field: string, value: unknown): void;
+    setValues(partial: SFormValues): void;
+    /**
+     * 校验成功后 resolve 表单值并触发 submit 事件，失败 reject 校验结果
+     */
+    submit(): Promise<SFormValues>;
+    /**
+     * 校验（全部可见字段，change / blur 规则都执行）；失败时自动定位到第一个错误字段。
+     * 表单未挂载时报告错误并跳过校验（返回 valid: true）
+     */
+    validate(options?: SFormValidateOptions): Promise<SFormValidateResult>;
+    /**
+     * validate 的 antd 命名别名，语义完全一致
+     */
+    validateFields(options?: SFormValidateOptions): Promise<SFormValidateResult>;
+}
+export {};

package/components/s-form/use-form-layout.d.ts

@@ -0,0 +1,21 @@
+import { SFormLayoutConfig, SFormLayoutHandle, SFormLayoutItem, SFormLayoutType, SFormSchema, SFormSchemaNode, SFormValidateResult } from './types';
+import { getSFormLayout } from './registry';
+export declare function useFormLayout(config: {
+    getFormElement(): HTMLElement | undefined;
+    getLayout(): SFormLayoutConfig | SFormLayoutType | undefined;
+    getSchema(): SFormSchema;
+    isHidden(node: SFormSchemaNode): boolean;
+}): {
+    layoutItems: import('vue').ComputedRef<SFormLayoutItem[]>;
+    layoutRef: import('vue').Ref<{
+        reveal?: ((field: string) => boolean) | undefined;
+    } | null, SFormLayoutHandle | {
+        reveal?: ((field: string) => boolean) | undefined;
+    } | null>;
+    revealField: (field: string) => void;
+    revealFirstErrorField: (result: SFormValidateResult) => void;
+    rootLayout: import('vue').ComputedRef<{
+        component: ReturnType<typeof getSFormLayout>;
+        params: Record<string, unknown>;
+    }>;
+};

package/components/s-form/use-form-model.d.ts

@@ -0,0 +1,15 @@
+import { SFormSchema, SFormSchemaNode, SFormValues } from './types';
+interface FormModelProps {
+    modelValue: SFormValues;
+    omitHiddenValues: boolean;
+    schema: SFormSchema;
+}
+export declare function useFormModel(props: FormModelProps, emitValue: (value: SFormValues) => void, onFieldChange: (field: string) => void): {
+    isHidden: (node: SFormSchemaNode) => boolean;
+    resetValues: () => void;
+    setFieldValue: (field: string, value: unknown) => void;
+    setValues: (partial: SFormValues) => void;
+    snapshotValues: () => SFormValues;
+    values: SFormValues;
+};
+export {};

package/components/s-form/utils.d.ts

@@ -0,0 +1,76 @@
+import { SFormGroupSchema, SFormLayoutHandle, SFormResponsiveColumns, SFormSchemaNode, SFormValues } from './types';
+/**
+ * 分组节点判别（schema 遍历统一入口）
+ */
+export declare function isGroupSchemaNode(node: SFormSchemaNode): node is SFormGroupSchema;
+/**
+ * 按 dot-path 读取值，与 TDesign FormItem 校验取值（lodash get）语义一致
+ */
+export declare function getByPath(source: SFormValues | undefined, path: string): unknown;
+/**
+ * 按 dot-path 写入值，自动创建中间层容器；
+ * 下一段为数字索引时中间层创建/复用为数组（如 'items.0.qty'）
+ */
+export declare function setByPath(target: SFormValues, path: string, value: unknown): void;
+/**
+ * 表单值深拷贝（支持嵌套对象 / 数组 / Date），
+ * 输出快照与内部 reactive 状态完全断开引用
+ */
+export declare function cloneValue(value: unknown): unknown;
+export declare function cloneValues(values: SFormValues): SFormValues;
+/**
+ * 按 dot-path 集合从快照中剔除字段值（仅删除叶子路径）；
+ * 剔除后变空的普通对象父级级联删除（数组容器保留，避免破坏索引语义）
+ */
+export declare function omitPaths(source: SFormValues, paths: Iterable<string>): SFormValues;
+/**
+ * 收集 schema 中全部字段路径（含分组子字段，深度优先）
+ */
+export declare function collectFieldPaths(nodes: SFormSchemaNode[]): string[];
+/**
+ * 收集当前处于隐藏状态的字段路径（显隐判定通过谓词注入；
+ * 隐藏分组下的全部子字段视为隐藏，无需逐个求值）
+ */
+export declare function collectHiddenFieldPaths(nodes: SFormSchemaNode[], isHidden: (node: SFormSchemaNode) => boolean): string[];
+/**
+ * 构建 字段 → 祖先分组 id 链（外→内）映射，供 reveal 链定位
+ */
+export declare function buildAncestorGroups(nodes: SFormSchemaNode[]): Map<string, string[]>;
+/**
+ * reveal 链执行器：由外向内逐层委托布局 handle 定位
+ * （根布局负责第一层目标，各层分组布局负责下一层目标直至字段），
+ * 任一层未声明处理即返回 false，由调用方回退为滚动定位。
+ * handle 均通过回调注入，便于单测与自定义布局替换。
+ */
+export declare function executeRevealChain(options: {
+    chain: string[];
+    field: string;
+    getGroupHandle: (groupId: string) => SFormLayoutHandle | undefined;
+    getRootHandle: () => null | SFormLayoutHandle | undefined;
+}): boolean;
+/**
+ * 解析当前容器宽度下的列数
+ */
+export declare function resolveColumns(width: number, cols?: number | SFormResponsiveColumns): number;
+export declare function toCssSize(value: number | string): string;
+type GapInput = [number | string, number | string] | number | string | undefined;
+/**
+ * 间距归一化为 [水平间距, 垂直间距] 的 CSS 值
+ */
+export declare function normalizeGap(gap: GapInput): {
+    columnGap?: string;
+    rowGap?: string;
+};
+/**
+ * 取水平间距的像素数值（用于换行模拟估算）
+ */
+export declare function gapToPx(gap: GapInput): number;
+/**
+ * 把 basis（'50%'、'240px'、数字）折算为像素宽
+ */
+export declare function basisToPx(basis: number | string, containerWidth: number): number;
+/**
+ * 在容器内查找字段元素（data-sform-field）并滚动到可视区
+ */
+export declare function scrollFieldIntoView(container: HTMLElement | null | undefined, field: string): boolean;
+export {};

package/composables/use-json-object-input.d.ts

@@ -0,0 +1,10 @@
+export declare function useJsonObjectInput(messages: {
+    objectRequired: string;
+    parseFailed: string;
+}): {
+    errorDetail: import('vue').Ref<string, string>;
+    errorKey: import('vue').Ref<string, string>;
+    parse: () => null | Record<string, unknown>;
+    reset: (value: Record<string, unknown>) => void;
+    text: import('vue').Ref<string, string>;
+};

package/composables/use-keyboard-shortcuts.d.ts

@@ -0,0 +1,16 @@
+import { MaybeRefOrGetter } from 'vue';
+export interface KeyboardShortcut {
+    exact?: boolean;
+    preventDefault?: boolean;
+    run: (event: KeyboardEvent) => void;
+    shortcut: string | string[];
+}
+interface KeyboardShortcutOptions {
+    enabled?: MaybeRefOrGetter<boolean>;
+    filter?: (event: KeyboardEvent) => boolean;
+    isolate?: boolean;
+    onTextInput?: (event: KeyboardEvent) => void;
+    target?: MaybeRefOrGetter<EventTarget | null | undefined>;
+}
+export declare function useKeyboardShortcuts(shortcuts: MaybeRefOrGetter<KeyboardShortcut[]>, options?: KeyboardShortcutOptions): Readonly<Record<string, import('vue').ComputedRef<boolean>> & import('@vueuse/core').MagicKeysInternal>;
+export {};