@h-ai/ui 0.1.0-alpha.61 → 0.1.0-alpha.63

package/dist/internal/form-context.js

@@ -0,0 +1,9 @@
+import { getContext } from 'svelte';
+export const FORM_LAYOUT_CONTEXT = Symbol('hai-form-layout');
+export const FORM_FIELD_CONTEXT = Symbol('hai-form-field');
+export function getFormLayoutContext() {
+    return getContext(FORM_LAYOUT_CONTEXT);
+}
+export function getFormFieldContext() {
+    return getContext(FORM_FIELD_CONTEXT);
+}

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;
+    invalid(control: FormControl): void;
+    input(control: FormControl): void;
+    reset: () => void;
+};
+export {};

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

@@ -0,0 +1,76 @@
+import { untrack } from 'svelte';
+import { getUILocale, uiM } from '../messages.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' };
+    if (validity.tooShort)
+        return { key: 'form_min_length', params: { min: control.getAttribute('minlength') ?? '' } };
+    if (validity.tooLong)
+        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) {
+    let issue = $state();
+    let currentControl = $state();
+    function reset() {
+        issue = undefined;
+        currentControl?.setCustomValidity('');
+    }
+    $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) : '';
+        },
+        invalid(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

@@ -351,5 +351,34 @@
   "password_policy_uppercase": "Include uppercase letters",
   "password_policy_lowercase": "Include lowercase letters",
   "password_policy_number": "Include numbers",
-  "password_policy_special": "Include special characters"
+  "password_policy_special": "Include special characters",
+  "guide_welcome": "Welcome",
+  "guide_start": "Start tour",
+  "guide_later": "Remind me later",
+  "guide_dismiss": "Do not remind me",
+  "guide_help": "Help center",
+  "guide_close": "Close",
+  "guide_loading": "Preparing your tour…",
+  "guide_next": "Next",
+  "guide_previous": "Previous",
+  "guide_done": "Done",
+  "guide_progress": "Step {current} of {total}",
+  "guide_search": "Search help",
+  "guide_empty": "No matching help content",
+  "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.",
+  "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

@@ -351,5 +351,34 @@
   "password_policy_uppercase": "包含大写字母",
   "password_policy_lowercase": "包含小写字母",
   "password_policy_number": "包含数字",
-  "password_policy_special": "包含特殊字符"
+  "password_policy_special": "包含特殊字符",
+  "guide_welcome": "欢迎使用",
+  "guide_start": "开始引导",
+  "guide_later": "稍后提醒",
+  "guide_dismiss": "不再提醒",
+  "guide_help": "帮助中心",
+  "guide_close": "关闭",
+  "guide_loading": "正在准备引导…",
+  "guide_next": "下一步",
+  "guide_previous": "上一步",
+  "guide_done": "完成",
+  "guide_progress": "第 {current} / {total} 步",
+  "guide_search": "搜索帮助内容",
+  "guide_empty": "没有找到相关帮助内容",
+  "guide_tours": "操作导览",
+  "guide_unavailable": "此引导暂不可用，请从帮助中心选择其他内容。",
+  "guide_targetMissing": "当前页面暂未提供此操作。请稍后重试或查看帮助内容。",
+  "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.d.ts

@@ -11,6 +11,7 @@ export type UIMessageKey = keyof typeof messagesZhCN;
  *
  * @param key - 消息 key
  * @param params - 可选的插值参数
+ * @param locale - 可选的宿主语言；省略时使用现有全局语言
  * @returns 当前 locale 对应的翻译文本
  *
  * @example
@@ -18,7 +19,7 @@ export type UIMessageKey = keyof typeof messagesZhCN;
  * uiM('password_show') // => '显示密码' (zh-CN) 或 'Show password' (en-US)
  * ```
  */
-export declare function uiM(key: UIMessageKey, params?: Record<string, string | number | boolean>): string;
+export declare function uiM(key: UIMessageKey, params?: Record<string, string | number | boolean>, locale?: string): string;
 /**
  * 获取当前 UI 模块使用的 locale
  */

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';
@@ -18,6 +19,7 @@ const getMessage = core.i18n.createMessageGetter({
  *
  * @param key - 消息 key
  * @param params - 可选的插值参数
+ * @param locale - 可选的宿主语言；省略时使用现有全局语言
  * @returns 当前 locale 对应的翻译文本
  *
  * @example
@@ -25,18 +27,18 @@ const getMessage = core.i18n.createMessageGetter({
  * uiM('password_show') // => '显示密码' (zh-CN) 或 'Show password' (en-US)
  * ```
  */
-export function uiM(key, params) {
-    return getMessage(key, params ? { params } : undefined);
+export function uiM(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/styles/guide.css

@@ -0,0 +1,88 @@
+/* 引导浮层挂到 body，使用全局主题变量，避免 Svelte 局部样式失效。 */
+.driver-popover.hai-guide-popover {
+  background: var(--color-base-100);
+  color: var(--color-base-content);
+  border: 1px solid color-mix(in oklch, var(--color-base-content) 12%, transparent);
+  border-radius: var(--hai-radius-lg, 16px);
+  box-shadow: var(--shadow-overlay, 0 16px 48px -12px #0003);
+  padding: 20px;
+  min-width: 240px;
+  max-width: min(360px, calc(100vw - 24px));
+  --driver-popover-font-family: inherit;
+}
+
+.hai-guide-popover .driver-popover-title {
+  font-size: 16px;
+  font-weight: 600;
+  line-height: 1.5;
+}
+.hai-guide-popover .driver-popover-description {
+  font-size: 14px;
+  line-height: 1.75;
+  overflow-wrap: anywhere;
+}
+.hai-guide-popover .driver-popover-progress-text {
+  color: color-mix(in oklch, var(--color-base-content) 55%, transparent);
+  font-size: 12px;
+}
+.hai-guide-popover .driver-popover-close-btn {
+  color: var(--color-base-content);
+  min-width: 36px;
+  min-height: 36px;
+}
+.hai-guide-popover .driver-popover-footer button {
+  border: 1px solid color-mix(in oklch, var(--color-base-content) 12%, transparent);
+  border-radius: var(--hai-radius-md, 8px);
+  background: var(--color-base-200);
+  color: var(--color-base-content);
+  padding: 8px 12px;
+  font-size: 13px;
+  font-weight: 500;
+  text-shadow: none;
+  min-height: 36px;
+}
+.hai-guide-popover .driver-popover-footer .driver-popover-next-btn {
+  background: var(--color-primary);
+  color: var(--color-primary-content);
+  border-color: var(--color-primary);
+}
+.hai-guide-popover button:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}
+.hai-guide-popover .driver-popover-arrow-side-top {
+  border-top-color: var(--color-base-100);
+}
+.hai-guide-popover .driver-popover-arrow-side-bottom {
+  border-bottom-color: var(--color-base-100);
+}
+.hai-guide-popover .driver-popover-arrow-side-left {
+  border-left-color: var(--color-base-100);
+}
+.hai-guide-popover .driver-popover-arrow-side-right {
+  border-right-color: var(--color-base-100);
+}
+.hai-guide-offer {
+  padding-bottom: max(20px, env(safe-area-inset-bottom));
+}
+
+/* 引擎会禁用高亮区域外的指针事件，等待提示的取消按钮必须保持可操作。 */
+.driver-active .hai-guide-loading,
+.driver-active .hai-guide-loading * {
+  pointer-events: auto;
+}
+
+@media (max-width: 640px) {
+  .hai-guide-popover .driver-popover-footer button,
+  .hai-guide-popover .driver-popover-close-btn {
+    min-height: var(--hai-touch-target-min, 44px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .driver-overlay,
+  .hai-guide-popover {
+    animation: none !important;
+    transition: none !important;
+  }
+}

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.61",
+  "version": "0.1.0-alpha.63",
   "description": "Hai Framework UI component library for Svelte 5 Runes.",
   "license": "Apache-2.0",
   "svelte": "./dist/index.js",
@@ -19,10 +19,20 @@
       "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"
     },
+    "./guide": {
+      "types": "./dist/guide.d.ts",
+      "svelte": "./dist/guide.js",
+      "import": "./dist/guide.js"
+    },
     "./components/*": {
       "types": "./dist/components/*.d.ts",
       "svelte": "./dist/components/*.js",
@@ -49,10 +59,11 @@
     "svelte": "^5.57.2"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.61",
+    "@h-ai/core": "0.1.0-alpha.63",
     "@internationalized/date": "^3.12.4",
     "@shikijs/langs": "^4.5.0",
     "bits-ui": "^2.19.5",
+    "driver.js": "1.9.0",
     "html2canvas": "^1.4.1",
     "jspdf": "^4.2.1",
     "layerchart": "2.6.1",

package/vite.js

@@ -68,6 +68,7 @@ export const haiPrebundledDeps = Object.freeze([
   'html2canvas',
   // ─── 工具 ───
   'tailwind-merge',
+  'driver.js',
   // ─── 框架运行时（@h-ai/core / @h-ai/crypto / @h-ai/kit 在登录等路径引入） ───
   'nanoid',
   'process',