@h-ai/ui 0.1.0-alpha.67 → 0.1.0-alpha.68

package/dist/internal/form-context.d.ts

@@ -1,18 +1,91 @@
 /** 表单布局和字段提示的内部上下文，不要求应用转发控件属性。 */
 import type { FormLayoutOptions } from '../types.js';
+/**
+ * 表单布局的私有 Svelte Context 键；应用通过 FormLayout 使用。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const context = getContext<FormLayoutOptions | undefined>(FORM_LAYOUT_CONTEXT)
+ * const columns = context?.columns
+ * ```
+ */
 export declare const FORM_LAYOUT_CONTEXT: unique symbol;
+/**
+ * 字段标签、错误与主控件关联的私有 Context 键。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const field = getContext<FormFieldContext | undefined>(FORM_FIELD_CONTEXT)
+ * const controlId = field?.controlId
+ * ```
+ */
 export declare const FORM_FIELD_CONTEXT: unique symbol;
+/**
+ * Modal/Drawer 向内部表单同步可见性的私有 Context 键。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const visibility = getContext<FormVisibilityContext | undefined>(FORM_VISIBILITY_CONTEXT)
+ * const open = visibility?.open
+ * ```
+ */
 export declare const FORM_VISIBILITY_CONTEXT: unique symbol;
+/**
+ * 表单宿主的响应式可见状态，用于关闭时重置触碰校验。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: FormVisibilityContext = { open: true }
+ * ```
+ */
 interface FormVisibilityContext {
     readonly open: boolean;
 }
+/**
+ * 组件初始化阶段读取可见性；没有宿主时返回 undefined。
+ * @returns 最近宿主的可见状态；无宿主时为 undefined。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const visibility = getFormVisibilityContext()
+ * const open = visibility?.open ?? true
+ * ```
+ */
 export declare function getFormVisibilityContext(): FormVisibilityContext | undefined;
+/**
+ * 标签、消息和主控件的关联状态，只在当前组件树中使用。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: FormFieldContext = { controlId: 'email', labelId: 'email-label', messageId: 'email-error', error: '邮箱不能为空' }
+ * ```
+ */
 export interface FormFieldContext {
     readonly controlId: string;
     readonly labelId: string;
     readonly messageId: string | undefined;
     readonly error: string;
 }
+/**
+ * 组件初始化阶段读取祖先布局；没有祖先时使用控件默认布局。
+ * @returns 最近表单布局；无祖先时为 undefined。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const layout = getFormLayoutContext()
+ * const columns = layout?.columns ?? 1
+ * ```
+ */
 export declare function getFormLayoutContext(): FormLayoutOptions | undefined;
+/**
+ * 组件初始化阶段读取最近字段的无障碍关联和校验消息。
+ * @returns 最近字段的标签、控件和校验消息关联；无字段时为 undefined。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const field = getFormFieldContext()
+ * const descriptionId = field?.messageId
+ * ```
+ */
 export declare function getFormFieldContext(): FormFieldContext | undefined;
 export {};

package/dist/internal/form-context.js

@@ -1,13 +1,70 @@
 import { getContext } from 'svelte';
+/**
+ * 表单布局的私有 Svelte Context 键；应用通过 FormLayout 使用。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const context = getContext<FormLayoutOptions | undefined>(FORM_LAYOUT_CONTEXT)
+ * const columns = context?.columns
+ * ```
+ */
 export const FORM_LAYOUT_CONTEXT = Symbol('hai-form-layout');
+/**
+ * 字段标签、错误与主控件关联的私有 Context 键。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const field = getContext<FormFieldContext | undefined>(FORM_FIELD_CONTEXT)
+ * const controlId = field?.controlId
+ * ```
+ */
 export const FORM_FIELD_CONTEXT = Symbol('hai-form-field');
+/**
+ * Modal/Drawer 向内部表单同步可见性的私有 Context 键。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const visibility = getContext<FormVisibilityContext | undefined>(FORM_VISIBILITY_CONTEXT)
+ * const open = visibility?.open
+ * ```
+ */
 export const FORM_VISIBILITY_CONTEXT = Symbol('hai-form-visibility');
+/**
+ * 组件初始化阶段读取可见性；没有宿主时返回 undefined。
+ * @returns 最近宿主的可见状态；无宿主时为 undefined。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const visibility = getFormVisibilityContext()
+ * const open = visibility?.open ?? true
+ * ```
+ */
 export function getFormVisibilityContext() {
     return getContext(FORM_VISIBILITY_CONTEXT);
 }
+/**
+ * 组件初始化阶段读取祖先布局；没有祖先时使用控件默认布局。
+ * @returns 最近表单布局；无祖先时为 undefined。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const layout = getFormLayoutContext()
+ * const columns = layout?.columns ?? 1
+ * ```
+ */
 export function getFormLayoutContext() {
     return getContext(FORM_LAYOUT_CONTEXT);
 }
+/**
+ * 组件初始化阶段读取最近字段的无障碍关联和校验消息。
+ * @returns 最近字段的标签、控件和校验消息关联；无字段时为 undefined。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const field = getFormFieldContext()
+ * const descriptionId = field?.messageId
+ * ```
+ */
 export function getFormFieldContext() {
     return getContext(FORM_FIELD_CONTEXT);
 }

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

@@ -1,12 +1,54 @@
 /** 将原生校验状态保留为消息键，显示时按当前 UI 语言解析。 */
 import type { UIMessageKey } from '../messages.js';
 import type { FormText } from '../types.js';
+/**
+ * 可重新翻译的原生约束错误，不缓存某个语言的最终文案。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: FormValidationIssue = { key: 'form_min_length', params: { min: 12 } }
+ * ```
+ */
 export interface FormValidationIssue {
     key: UIMessageKey;
     params?: Record<string, string | number>;
 }
+/**
+ * 参与原生约束校验的表单控件集合。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: FormControl = document.createElement('input')
+ * ```
+ */
 type FormControl = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+/**
+ * 在显示时求值表单提示，语言切换后读取最新业务翻译。
+ * @param text - 待处理文本。
+ * @returns 当前语言的表单提示，空输入为空字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const message = resolveFormText(() => '邮箱不能为空')
+ * ```
+ */
 export declare function resolveFormText(text?: FormText): string;
+/**
+ * 在组件初始化阶段创建原生约束校验状态；宿主关闭或表单 reset 时清除过期错误。
+ * @param getOverride - 读取自定义校验提示的函数。
+ * @param getValue - 读取当前控件值以跟踪程序回填的函数。
+ * @returns 带响应式 message 和 validate/input/reset 方法的校验状态。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const validation = createControlValidation(() => '邮箱不能为空')
+ * const input = document.createElement('input')
+ * input.required = true
+ * validation.validate(input)
+ * const message = validation.message
+ * validation.reset()
+ * ```
+ */
 export declare function createControlValidation(getOverride?: () => FormText | undefined, getValue?: () => unknown): {
     readonly message: string;
     validate(control: FormControl): void;

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

@@ -1,6 +1,16 @@
 import { untrack } from 'svelte';
 import { getUILocale, uiM } from '../messages.js';
 import { getFormVisibilityContext } from './form-context.js';
+/**
+ * 在显示时求值表单提示，语言切换后读取最新业务翻译。
+ * @param text - 待处理文本。
+ * @returns 当前语言的表单提示，空输入为空字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const message = resolveFormText(() => '邮箱不能为空')
+ * ```
+ */
 export function resolveFormText(text) {
     if (typeof text !== 'function')
         return text ?? '';
@@ -35,6 +45,22 @@ function readIssue(control) {
         return { key: 'form_pattern' };
     return undefined;
 }
+/**
+ * 在组件初始化阶段创建原生约束校验状态；宿主关闭或表单 reset 时清除过期错误。
+ * @param getOverride - 读取自定义校验提示的函数。
+ * @param getValue - 读取当前控件值以跟踪程序回填的函数。
+ * @returns 带响应式 message 和 validate/input/reset 方法的校验状态。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const validation = createControlValidation(() => '邮箱不能为空')
+ * const input = document.createElement('input')
+ * input.required = true
+ * validation.validate(input)
+ * const message = validation.message
+ * validation.reset()
+ * ```
+ */
 export function createControlValidation(getOverride = () => undefined, getValue) {
     const visibility = getFormVisibilityContext();
     let issue = $state();

package/dist/internal/icon-safety.d.ts

@@ -3,5 +3,12 @@
  *
  * 字符串入口只服务由应用代码内置的简单 path/circle 等图标。涉及链接、外部资源、
  * CSS、动画或可执行事件的 SVG 一律拒绝；复杂图标应使用 Svelte Snippet。
+ * @param markup - 候选内联 SVG 文本。
+ * @returns 允许标签及属性的 SVG；无效或不安全内容被移除。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const safe = sanitizeInlineSvg('<svg viewBox="0 0 24 24"><path d="M0 0h24v24"/></svg>')
+ * ```
  */
 export declare function sanitizeInlineSvg(markup: string): string;

package/dist/internal/icon-safety.js

@@ -20,6 +20,13 @@ const unsafeSvgElements = new Set([
  *
  * 字符串入口只服务由应用代码内置的简单 path/circle 等图标。涉及链接、外部资源、
  * CSS、动画或可执行事件的 SVG 一律拒绝；复杂图标应使用 Svelte Snippet。
+ * @param markup - 候选内联 SVG 文本。
+ * @returns 允许标签及属性的 SVG；无效或不安全内容被移除。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const safe = sanitizeInlineSvg('<svg viewBox="0 0 24 24"><path d="M0 0h24v24"/></svg>')
+ * ```
  */
 export function sanitizeInlineSvg(markup) {
     const trimmed = markup.trim();

package/dist/internal/locale.d.ts

@@ -1,2 +1,21 @@
+/**
+ * 读取请求/浏览器当前 UI 语言，服务端不跨请求修改全局默认值。
+ * @returns 当前请求或浏览器的 UI 语言。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const locale = readUILocale()
+ * ```
+ */
 export declare function readUILocale(): string;
+/**
+ * 同步当前浏览器的 UI 语言；SSR 保持请求级隔离。
+ * @param locale - 显式语言代码；省略时使用当前上下文。
+ * @returns {void} 无返回值；同步浏览器语言，服务端保持请求隔离。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * changeUILocale('en-US')
+ * ```
+ */
 export declare function changeUILocale(locale: string): void;

package/dist/internal/locale.js

@@ -9,11 +9,32 @@ const subscribe = createSubscriber((update) => {
         notifyLocaleChange = undefined;
     };
 });
+/**
+ * 读取请求/浏览器当前 UI 语言，服务端不跨请求修改全局默认值。
+ * @returns 当前请求或浏览器的 UI 语言。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const locale = readUILocale()
+ * ```
+ */
 export function readUILocale() {
     subscribe();
     return core.i18n.getGlobalLocale();
 }
+/**
+ * 同步当前浏览器的 UI 语言；SSR 保持请求级隔离。
+ * @param locale - 显式语言代码；省略时使用当前上下文。
+ * @returns {void} 无返回值；同步浏览器语言，服务端保持请求隔离。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * changeUILocale('en-US')
+ * ```
+ */
 export function changeUILocale(locale) {
+    if (typeof window === 'undefined')
+        return;
     core.i18n.setGlobalLocale(locale);
     // 宿主可能在 $effect 中同步语言，setter 不能反向订阅自身状态。
     untrack(() => {

package/dist/message.svelte.d.ts

@@ -8,6 +8,12 @@
 import type { MessageOptions } from './types.js';
 /**
  * 内部消息条目
+ *
+ * @example
+ * ```ts
+ * import type { MessageItem } from '@h-ai/ui'
+ * const example: MessageItem = { id: 'message-1', message: '保存完成', type: 'success', duration: 3000, closable: true }
+ * ```
  */
 export interface MessageItem {
     id: string;
@@ -24,26 +30,110 @@ declare class MessageState {
     private timers;
     /**
      * 添加消息
+     * @param options - 本次操作的行为与显示选项。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.add({ message: '保存完成', type: 'success', duration: 3000 })
+     * message.remove(id)
+     * ```
      */
     add(options: MessageOptions | string): string;
     /**
      * 移除消息
+     * @param id - 待移除的条目 ID。
+     * @returns {void} 无返回值；同时清理对应的自动关闭定时器。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.info('同步中', 0)
+     * message.remove(id)
+     * ```
      */
     remove(id: string): void;
     /**
      * 清空所有消息
+     * @returns {void} 无返回值；同时清理对应的自动关闭定时器。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * message.info('同步中', 0)
+     * message.clear()
+     * ```
      */
     clear(): void;
     /**
      * 快捷方法
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.info('操作结果', 3000)
+     * message.remove(id)
+     * ```
      */
     info(message: string, duration?: number): string;
+    /**
+     * 处理 success 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.success('操作结果', 3000)
+     * message.remove(id)
+     * ```
+     */
     success(message: string, duration?: number): string;
+    /**
+     * 处理 warning 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.warning('操作结果', 3000)
+     * message.remove(id)
+     * ```
+     */
     warning(message: string, duration?: number): string;
+    /**
+     * 处理 error 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.error('操作结果', 3000)
+     * message.remove(id)
+     * ```
+     */
     error(message: string, duration?: number): string;
 }
 /**
  * Message 单例
+ *
+ * @example
+ * ```ts
+ * import { message } from '@h-ai/ui'
+ * // 页面布局需挂载 MessageContainer。
+ * const id = message.success('保存完成', 3000)
+ * message.remove(id)
+ * message.clear()
+ * ```
  */
 export declare const message: MessageState;
 export {};

package/dist/message.svelte.js

@@ -13,6 +13,15 @@ class MessageState {
     timers = new Map();
     /**
      * 添加消息
+     * @param options - 本次操作的行为与显示选项。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.add({ message: '保存完成', type: 'success', duration: 3000 })
+     * message.remove(id)
+     * ```
      */
     add(options) {
         const opts = typeof options === 'string' ? { message: options } : options;
@@ -36,6 +45,15 @@ class MessageState {
     }
     /**
      * 移除消息
+     * @param id - 待移除的条目 ID。
+     * @returns {void} 无返回值；同时清理对应的自动关闭定时器。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.info('同步中', 0)
+     * message.remove(id)
+     * ```
      */
     remove(id) {
         const timer = this.timers.get(id);
@@ -47,6 +65,14 @@ class MessageState {
     }
     /**
      * 清空所有消息
+     * @returns {void} 无返回值；同时清理对应的自动关闭定时器。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * message.info('同步中', 0)
+     * message.clear()
+     * ```
      */
     clear() {
         for (const timer of this.timers.values()) {
@@ -57,21 +83,79 @@ class MessageState {
     }
     /**
      * 快捷方法
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.info('操作结果', 3000)
+     * message.remove(id)
+     * ```
      */
     info(message, duration) {
         return this.add({ message, type: 'info', duration });
     }
+    /**
+     * 处理 success 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.success('操作结果', 3000)
+     * message.remove(id)
+     * ```
+     */
     success(message, duration) {
         return this.add({ message, type: 'success', duration });
     }
+    /**
+     * 处理 warning 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.warning('操作结果', 3000)
+     * message.remove(id)
+     * ```
+     */
     warning(message, duration) {
         return this.add({ message, type: 'warning', duration });
     }
+    /**
+     * 处理 error 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { message } from '@h-ai/ui'
+     * // 布局中需挂载 MessageContainer。
+     * const id = message.error('操作结果', 3000)
+     * message.remove(id)
+     * ```
+     */
     error(message, duration) {
         return this.add({ message, type: 'error', duration });
     }
 }
 /**
  * Message 单例
+ *
+ * @example
+ * ```ts
+ * import { message } from '@h-ai/ui'
+ * // 页面布局需挂载 MessageContainer。
+ * const id = message.success('保存完成', 3000)
+ * message.remove(id)
+ * message.clear()
+ * ```
  */
 export const message = new MessageState();