@icen.ai/ui 0.9.0 → 0.10.0

package/dist/behaviors/form-validate.d.mts

@@ -0,0 +1,102 @@
+/** 可校验字段元素。 */
+type FieldElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+/** 一条校验规则（rule 名 = 消息 key）。 */
+interface FieldRule {
+    /** required / email / url / number / minlength / maxlength / pattern / min / max / icen-step / matches / <custom> */
+    rule: string;
+    /** matches 的目标字段名、自定义规则的参数（data-icen-validate="matches:pwd unique:username"） */
+    arg?: string;
+    /** 原生属性原文（min/max/step/minlength/maxlength/pattern），消息占位符用 */
+    attr?: string;
+}
+/** 自定义校验函数：通过返回 true；失败返回错误消息字符串（可异步）。 */
+type CustomValidatorFn = (value: string, field: FieldElement, form: HTMLFormElement | null) => true | string | Promise<true | string>;
+interface FormValidateStrategy {
+    /** 'submit' = 仅提交时校验（默认策略：提交后出错字段 input 复验 + 未触碰字段 blur 补验） */
+    on?: 'submit' | 'blur' | 'input';
+    /** input 复验防抖（默认 160ms） */
+    debounceMs?: number;
+}
+interface FormValidateOptions {
+    strategy?: FormValidateStrategy;
+    /** 提交失败时聚焦第一个错误字段并 scrollIntoView（默认 true） */
+    scrollToError?: boolean;
+}
+interface FormValidator {
+    readonly form: HTMLFormElement;
+    /** 全量校验（提交语义）：更新呈现 + 汇总 + 派 icen:form-valid / icen:form-invalid */
+    validate(): Promise<boolean>;
+    /** 单字段校验：更新呈现并派 icen:form-field-validate */
+    validateField(name: string): Promise<boolean>;
+    /** 复位校验状态与呈现（不动表单值） */
+    reset(): void;
+    /** 当前错误表（字段名 → 消息） */
+    errors(): Record<string, string>;
+    /** 摘除监听与计时器、清呈现（handle 失效） */
+    destroy(): void;
+}
+/** i18n 全局消息表：setValidateMessages({ required: '必填', email: '…' })；传空串删回默认。 */
+declare function setValidateMessages(messages: Record<string, string | undefined>): void;
+/** 注册具名自定义校验（覆盖同名）；fn 可异步返回 true | string 错误消息。 */
+declare function registerValidator(name: string, fn: CustomValidatorFn): void;
+/** 下架具名自定义校验。 */
+declare function unregisterValidator(name: string): void;
+/**
+ * 从字段元素解析规则集（原生约束 → data-icen-validate 额外规则，顺序即优先级）。
+ * HTML5 属性即 schema；未注册语义的 data-icen-validate token 进入规则集但校验时放行。
+ */
+declare function resolveFieldRules(field: FieldElement): FieldRule[];
+/** 字段取值：勾选类取 checked 语义，其余取 value。 */
+declare function fieldValue(field: FieldElement): string;
+/** 字段标签（消息 {label} 占位符 + 错误汇总链接文案）：label 元素 > aria-label > placeholder > name > fallback。 */
+declare function fieldLabel(field: FieldElement | null | undefined, fallback?: string): string;
+/**
+ * 顺序求值规则集，首个失败即返回其消息（原生约束优先于自定义规则）。
+ * 空值语义对齐 HTML5：非 required 规则对空值放行（valueMissing 归 required 管）。
+ */
+declare function evaluateRules(value: string, rules: FieldRule[], ctx?: {
+    field?: FieldElement;
+    form?: HTMLFormElement | null;
+}): Promise<true | string>;
+/** 收集参与校验的字段：有 name、非 disabled、非提交类/文件类的 input/textarea/select。 */
+declare function collectFormFields(form: HTMLFormElement): FieldElement[];
+/**
+ * 为单个表单创建校验 handle（同一 form 单例：重复创建幂等返回既有实例，
+ * strategy 以首次创建为准）。提交事件由校验层接管（preventDefault），
+ * 通过/未过分别派 icen:form-valid / icen:form-invalid，消费方走事件或 await validate()。
+ * SSR 下返回 no-op handle。
+ */
+declare function createFormValidator(form: HTMLFormElement, opts?: FormValidateOptions): FormValidator;
+/**
+ * 接线表单校验（document 级委托，页面级一次即可，重复调用幂等）。
+ * 现有与后续插入的 form[data-icen-validate] 自动补 novalidate 并挂 handle
+ * （submit 捕获阶段 ensure，冒泡阶段 handle 的 submit 监听接管校验）。
+ * 返回销毁函数：摘除委托、销毁 scope 内由委托路径建立的 handle 并复位幂等标记，
+ * 销毁后可重新 initFormValidate。SSR 下返回 no-op。
+ */
+declare function initFormValidate(root?: ParentNode): () => void;
+/** show_form 字段规格（inputSchema 的运行时形态）。 */
+interface ShowFormFieldSpec {
+    name: string;
+    label: string;
+    type?: 'text' | 'email' | 'number' | 'url' | 'textarea' | 'select' | 'date';
+    required?: boolean;
+    pattern?: string;
+    min?: number;
+    max?: number;
+    options?: Array<string | {
+        label: string;
+        value: string;
+    }>;
+    help?: string;
+}
+interface ShowFormSpec {
+    title?: string;
+    fields: ShowFormFieldSpec[];
+    submitLabel?: string;
+}
+type ShowFormResult = Record<string, unknown> | {
+    cancelled: true;
+};
+
+export { type CustomValidatorFn, type FieldElement, type FieldRule, type FormValidateOptions, type FormValidateStrategy, type FormValidator, type ShowFormFieldSpec, type ShowFormResult, type ShowFormSpec, collectFormFields, createFormValidator, evaluateRules, fieldLabel, fieldValue, initFormValidate, registerValidator, resolveFieldRules, setValidateMessages, unregisterValidator };