@h-ai/ui 0.1.0-alpha.62 → 0.1.0-alpha.64

package/dist/internal/form-validation.svelte.d.ts

@@ -0,0 +1,16 @@
+/** 将原生校验状态保留为消息键，显示时按当前 UI 语言解析。 */
+import type { UIMessageKey } from '../messages.js';
+import type { FormText } from '../types.js';
+export interface FormValidationIssue {
+    key: UIMessageKey;
+    params?: Record<string, string | number>;
+}
+type FormControl = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+export declare function resolveFormText(text?: FormText): string;
+export declare function createControlValidation(getOverride?: () => FormText | undefined, getValue?: () => unknown): {
+    readonly message: string;
+    validate(control: FormControl): void;
+    input(control: FormControl): void;
+    reset: () => void;
+};
+export {};

package/dist/internal/form-validation.svelte.js

@@ -0,0 +1,86 @@
+import { untrack } from 'svelte';
+import { getUILocale, uiM } from '../messages.js';
+import { getFormVisibilityContext } from './form-context.js';
+export function resolveFormText(text) {
+    if (typeof text !== 'function')
+        return text ?? '';
+    // 应用翻译函数也在 UI 语言同步后重新求值。
+    void getUILocale();
+    return text();
+}
+function readIssue(control) {
+    if (!control.willValidate)
+        return undefined;
+    const validity = control.validity;
+    if (validity.valueMissing)
+        return { key: 'form_required' };
+    if (validity.typeMismatch)
+        return { key: control.getAttribute('type') === 'email' ? 'form_email' : 'form_url' };
+    // 程序回填的值也需校验长度，原生 tooShort/tooLong 只覆盖用户输入。
+    const minLength = control.getAttribute('minlength');
+    const maxLength = control.getAttribute('maxlength');
+    if (validity.tooShort || (control.value && minLength !== null && control.value.length < Number(minLength)))
+        return { key: 'form_min_length', params: { min: control.getAttribute('minlength') ?? '' } };
+    if (validity.tooLong || (control.value && maxLength !== null && control.value.length > Number(maxLength)))
+        return { key: 'form_max_length', params: { max: control.getAttribute('maxlength') ?? '' } };
+    if (validity.rangeUnderflow)
+        return { key: 'form_min', params: { min: control.getAttribute('min') ?? '' } };
+    if (validity.rangeOverflow)
+        return { key: 'form_max', params: { max: control.getAttribute('max') ?? '' } };
+    if (validity.stepMismatch)
+        return { key: 'form_step', params: { step: control.getAttribute('step') ?? '1' } };
+    if (validity.badInput)
+        return { key: 'form_number' };
+    if (validity.patternMismatch)
+        return { key: 'form_pattern' };
+    return undefined;
+}
+export function createControlValidation(getOverride = () => undefined, getValue) {
+    const visibility = getFormVisibilityContext();
+    let issue = $state();
+    let currentControl = $state();
+    function reset() {
+        issue = undefined;
+        currentControl?.setCustomValidity('');
+    }
+    $effect(() => {
+        // 弹窗与抽屉保留子树；关闭时清理原生错误，重开不能沿用上次的触碰状态。
+        if (visibility && !visibility.open)
+            reset();
+    });
+    $effect(() => {
+        const form = currentControl?.form;
+        form?.addEventListener('reset', reset);
+        return () => form?.removeEventListener('reset', reset);
+    });
+    $effect(() => {
+        getValue?.();
+        const control = currentControl;
+        if (control) {
+            // 回填、重置及约束变更不一定触发 input；同步清除过期的原生错误。
+            untrack(() => {
+                control.setCustomValidity('');
+                if (issue)
+                    issue = readIssue(control);
+            });
+        }
+    });
+    return {
+        get message() {
+            return issue ? resolveFormText(getOverride()) || uiM(issue.key, issue.params) : '';
+        },
+        validate(control) {
+            currentControl = control;
+            control.setCustomValidity('');
+            issue = readIssue(control);
+            control.setCustomValidity(issue ? resolveFormText(getOverride()) || uiM(issue.key, issue.params) : '');
+        },
+        input(control) {
+            currentControl = control;
+            control.setCustomValidity('');
+            if (issue)
+                issue = readIssue(control);
+        },
+        reset,
+    };
+}

package/dist/internal/locale.d.ts

@@ -0,0 +1,2 @@
+export declare function readUILocale(): string;
+export declare function changeUILocale(locale: string): void;

package/dist/internal/locale.js

@@ -0,0 +1,22 @@
+/** UI 语言变更触发组件重新求值；实际语言仍由 core 统一管理。 */
+import { core } from '@h-ai/core';
+import { untrack } from 'svelte';
+import { createSubscriber } from 'svelte/reactivity';
+let notifyLocaleChange;
+const subscribe = createSubscriber((update) => {
+    notifyLocaleChange = update;
+    return () => {
+        notifyLocaleChange = undefined;
+    };
+});
+export function readUILocale() {
+    subscribe();
+    return core.i18n.getGlobalLocale();
+}
+export function changeUILocale(locale) {
+    core.i18n.setGlobalLocale(locale);
+    // 宿主可能在 $effect 中同步语言，setter 不能反向订阅自身状态。
+    untrack(() => {
+        notifyLocaleChange?.();
+    });
+}

package/dist/messages/en-US.json

@@ -368,5 +368,17 @@
   "guide_tours": "Product tours",
   "guide_unavailable": "This tour is unavailable. Choose another topic in the help center.",
   "guide_targetMissing": "This action is not available on the current page. Try again later or read the help content.",
-  "guide_startFailed": "Unable to start the tour. Please try again later."
+  "guide_startFailed": "Unable to start the tour. Please try again later.",
+  "form_required": "This field is required.",
+  "form_email": "Enter a valid email address.",
+  "form_url": "Enter a valid URL.",
+  "form_number": "Enter a valid number.",
+  "form_min_length": "Enter at least {min} characters.",
+  "form_max_length": "Enter no more than {max} characters.",
+  "form_min": "Enter a value of at least {min}.",
+  "form_max": "Enter a value no greater than {max}.",
+  "form_step": "Enter a value in increments of {step}.",
+  "form_pattern": "Enter a value in the required format.",
+  "select_clear": "Clear selection",
+  "select_no_match": "No matching options"
 }

package/dist/messages/zh-CN.json

@@ -368,5 +368,17 @@
   "guide_tours": "操作导览",
   "guide_unavailable": "此引导暂不可用，请从帮助中心选择其他内容。",
   "guide_targetMissing": "当前页面暂未提供此操作。请稍后重试或查看帮助内容。",
-  "guide_startFailed": "无法开始引导，请稍后重试。"
+  "guide_startFailed": "无法开始引导，请稍后重试。",
+  "form_required": "请填写此项。",
+  "form_email": "请输入有效的邮箱地址。",
+  "form_url": "请输入有效的网址。",
+  "form_number": "请输入有效的数字。",
+  "form_min_length": "请至少输入 {min} 个字符。",
+  "form_max_length": "请最多输入 {max} 个字符。",
+  "form_min": "请输入不小于 {min} 的值。",
+  "form_max": "请输入不大于 {max} 的值。",
+  "form_step": "请按 {step} 的步长输入。",
+  "form_pattern": "请按要求的格式填写。",
+  "select_clear": "清空选择",
+  "select_no_match": "无匹配选项"
 }

package/dist/messages.js

@@ -5,6 +5,7 @@
  * @module messages
  */
 import { core } from '@h-ai/core';
+import { changeUILocale, readUILocale } from './internal/locale.js';
 // 导入消息文件
 import messagesEnUS from './messages/en-US.json';
 import messagesZhCN from './messages/zh-CN.json';
@@ -27,17 +28,17 @@ const getMessage = core.i18n.createMessageGetter({
  * ```
  */
 export function uiM(key, params, locale) {
-    return getMessage(key, { params, locale });
+    return getMessage(key, { params, locale: locale ?? readUILocale() });
 }
 /**
  * 获取当前 UI 模块使用的 locale
  */
 export function getUILocale() {
-    return core.i18n.getGlobalLocale();
+    return readUILocale();
 }
 /**
  * 手动设置 UI 模块的 locale（通常不需要，会自动同步）
  */
 export function setUILocale(locale) {
-    core.i18n.setGlobalLocale(locale);
+    changeUILocale(locale);
 }

package/dist/types.d.ts

@@ -102,9 +102,9 @@ export interface InputProps extends DataAttributes {
     /** 是否必填 */
     required?: boolean;
     /** 错误消息 */
-    error?: string;
+    error?: FormText;
     /** 自定义验证消息（用于覆盖浏览器原生验证提示） */
-    validationMessage?: string;
+    validationMessage?: FormText;
     /** 自定义类名 */
     class?: string;
     /** 元素 ID */
@@ -182,6 +182,10 @@ export interface BareInputProps extends DataAttributes {
     ariaControls?: string;
     /** aria-autocomplete */
     ariaAutocomplete?: 'none' | 'list' | 'inline' | 'both';
+    /** 字段校验状态 */
+    ariaInvalid?: boolean;
+    /** 字段提示/错误元素 ID */
+    ariaDescribedby?: string;
     /** 元素 ID */
     id?: string;
     /** input 引用 */
@@ -255,10 +259,19 @@ export interface TextareaProps extends DataAttributes {
     required?: boolean;
     /** 是否自动调整高度 */
     autoResize?: boolean;
-    inputmode?: HTMLInputElement['inputMode'];
-    error?: string;
+    inputmode?: InputProps['inputmode'];
+    error?: FormText;
     /** 自定义验证消息（用于覆盖浏览器原生验证提示） */
-    validationMessage?: string;
+    validationMessage?: FormText;
+    /** 最小长度 */
+    minlength?: number;
+    /** 最大长度 */
+    maxlength?: number;
+    /** 原生控件引用 */
+    textareaRef?: HTMLTextAreaElement;
+    oninvalid?: (e: Event & {
+        currentTarget: HTMLTextAreaElement;
+    }) => void;
     /** 自定义类名 */
     class?: string;
     /** 元素 ID */
@@ -302,7 +315,11 @@ export interface SelectProps<T = string> extends DataAttributes {
     /** 是否可筛选（启用后可在输入框内输入过滤选项） */
     filterable?: boolean;
     /** 错误消息 */
-    error?: string;
+    error?: FormText;
+    /** 自定义验证提示，仅在校验失败时显示。 */
+    validationMessage?: FormText;
+    /** 表单字段名 */
+    name?: string;
     /** 自定义类名 */
     class?: string;
     /** 元素 ID */
@@ -314,6 +331,8 @@ export interface SelectProps<T = string> extends DataAttributes {
  * 复选框属性
  */
 export interface CheckboxProps extends DataAttributes {
+    /** 元素 ID；用于 FormField 标签关联。 */
+    id?: string;
     /** 是否选中 */
     checked?: boolean;
     /** 标签 */
@@ -766,7 +785,27 @@ export interface DropdownProps extends DataAttributes {
 /**
  * 表单属性
  */
-export interface FormProps extends DataAttributes {
+/** 表单标签位置：独立成行或与控件同行。 */
+export type FormLabelPosition = 'top' | 'left';
+/** 双列表单字段占用列数；auto 根据控件类型判断。 */
+export type FormColSpan = 'auto' | 1 | 2;
+/** 支持延迟求值的表单文案，切换语言时重新解析。 */
+export type FormText = string | (() => string);
+/** 表单布局配置；窄容器自动收为单列。 */
+export interface FormLayoutOptions {
+    /** 字段列数，默认 1。 */
+    columns?: 1 | 2;
+    /** 标签位置，默认 top。 */
+    labelPosition?: FormLabelPosition;
+    /** 同行标签宽度（CSS 值），默认 8rem。 */
+    labelWidth?: string;
+}
+/** 可嵌入原生 form 的布局容器。 */
+export interface FormLayoutProps extends FormLayoutOptions, DataAttributes {
+    class?: string;
+    children?: Snippet;
+}
+export interface FormProps extends FormLayoutOptions, DataAttributes {
     /** 表单 ID */
     id?: string;
     /** 自定义类名 */
@@ -789,13 +828,21 @@ export interface FormProps extends DataAttributes {
  */
 export interface FormFieldProps extends DataAttributes {
     /** 标签 */
-    label?: string;
+    label?: FormText;
+    /** 关联控件 ID；省略时为内部控件自动提供唯一 ID。 */
+    for?: string;
+    /** 覆盖所在表单的标签位置。 */
+    labelPosition?: FormLabelPosition;
+    /** 覆盖所在表单的同行标签宽度。 */
+    labelWidth?: string;
+    /** 双列时的占用列数，默认 auto；多行文本、上传和多选自动占两列。 */
+    colSpan?: FormColSpan;
     /** 字段名 */
     name?: string;
     /** 错误消息 */
-    error?: string;
+    error?: FormText;
     /** 提示信息 */
-    hint?: string;
+    hint?: FormText;
     /** 是否必填 */
     required?: boolean;
     /** 自定义类名 */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/ui",
   "type": "module",
-  "version": "0.1.0-alpha.62",
+  "version": "0.1.0-alpha.64",
   "description": "Hai Framework UI component library for Svelte 5 Runes.",
   "license": "Apache-2.0",
   "svelte": "./dist/index.js",
@@ -19,6 +19,11 @@
       "types": "./vite.d.ts",
       "import": "./vite.js"
     },
+    "./i18n": {
+      "types": "./dist/i18n.svelte.d.ts",
+      "svelte": "./dist/i18n.svelte.js",
+      "import": "./dist/i18n.svelte.js"
+    },
     "./theme": {
       "types": "./dist/theme-config.d.ts",
       "import": "./dist/theme-config.js"
@@ -54,7 +59,7 @@
     "svelte": "^5.57.2"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.62",
+    "@h-ai/core": "0.1.0-alpha.64",
     "@internationalized/date": "^3.12.4",
     "@shikijs/langs": "^4.5.0",
     "bits-ui": "^2.19.5",