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

package/dist/theme-config.js

@@ -7,6 +7,12 @@
 import { readStoredValue, writeStoredValue } from './internal/browser-safety.js';
 /**
  * DaisyUI 内置主题配置（精选）
+ *
+ * @example
+ * ```ts
+ * import { THEMES } from '@h-ai/ui'
+ * const choices = THEMES.map(theme => ({ value: theme.id, label: theme.name }))
+ * ```
  */
 export const THEMES = [
     // 亮色主题
@@ -29,6 +35,13 @@ export const THEMES = [
 ];
 /**
  * 主题分组配置
+ *
+ * @example
+ * ```ts
+ * import { THEME_GROUPS } from '@h-ai/ui'
+ * const light = THEME_GROUPS.find(group => group.id === 'light')
+ * const choices = light?.themes
+ * ```
  */
 export const THEME_GROUPS = [
     {
@@ -44,22 +57,52 @@ export const THEME_GROUPS = [
 ];
 /**
  * 暗色主题列表
+ *
+ * @example
+ * ```ts
+ * import { DARK_THEMES } from '@h-ai/ui'
+ * const dark = DARK_THEMES.includes('dark')
+ * ```
  */
 export const DARK_THEMES = THEMES.filter(t => t.dark).map(t => t.id);
 /**
  * 支持的主题 ID 列表
+ *
+ * @example
+ * ```ts
+ * import { SUPPORTED_THEME_IDS } from '@h-ai/ui'
+ * const supported = SUPPORTED_THEME_IDS.includes('light')
+ * ```
  */
 export const SUPPORTED_THEME_IDS = THEMES.map(theme => theme.id);
 /**
  * 默认主题色
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_THEME_COLOR } from '@h-ai/ui'
+ * const style = { '--brand-color': DEFAULT_THEME_COLOR }
+ * ```
  */
 export const DEFAULT_THEME_COLOR = '#5765f0';
 /**
  * 主题色 CSS 变量名
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui'
+ * document.documentElement.style.setProperty(DEFAULT_THEME_COLOR_CSS_VAR, '#2563eb')
+ * ```
  */
 export const DEFAULT_THEME_COLOR_CSS_VAR = '--hai-theme-color-default';
 /**
  * 内置主题色预设
+ *
+ * @example
+ * ```ts
+ * import { THEME_COLOR_PRESETS } from '@h-ai/ui'
+ * const options = THEME_COLOR_PRESETS.map(preset => ({ value: preset.value, labelKey: preset.labelKey }))
+ * ```
  */
 export const THEME_COLOR_PRESETS = [
     { value: DEFAULT_THEME_COLOR, labelKey: 'theme_color_tech_purple' },
@@ -71,26 +114,65 @@ const SHORT_HEX_COLOR_REGEX = /^#[0-9a-f]{3}$/i;
 const SUPPORTED_THEME_ID_SET = new Set(SUPPORTED_THEME_IDS);
 /**
  * 默认主题
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_THEME, applyTheme } from '@h-ai/ui'
+ * applyTheme(DEFAULT_THEME, false)
+ * ```
  */
 export const DEFAULT_THEME = 'light';
 /**
  * 主题存储键名
+ *
+ * @example
+ * ```ts
+ * import { THEME_STORAGE_KEY, getSavedTheme } from '@h-ai/ui'
+ * const preference = { key: THEME_STORAGE_KEY, value: getSavedTheme('light') }
+ * // 通过公开安全读取函数消费偏好，不直接访问受限存储。
+ * ```
  */
 export const THEME_STORAGE_KEY = 'theme';
 /**
  * 获取主题信息
+ * @param themeId - 主题候选 ID。
+ * @returns 匹配的主题元数据，不存在时返回 undefined。
+ *
+ * @example
+ * ```ts
+ * import { getThemeInfo } from '@h-ai/ui'
+ * const theme = getThemeInfo('light')
+ * const background = theme?.bgColor
+ * ```
  */
 export function getThemeInfo(themeId) {
     return THEMES.find(t => t.id === themeId);
 }
 /**
  * 检查是否为暗色主题
+ * @param themeId - 主题候选 ID。
+ * @returns 是否属于内置暗色主题。
+ *
+ * @example
+ * ```ts
+ * import { isDarkTheme } from '@h-ai/ui'
+ * const dark = isDarkTheme('dark')
+ * ```
  */
 export function isDarkTheme(themeId) {
     return DARK_THEMES.includes(themeId);
 }
 /**
  * 归一化主题 ID，不支持的值回退到默认主题。
+ * @param themeId - 主题候选 ID。
+ * @param fallbackThemeId - 候选不支持时尝试的主题。
+ * @returns 支持的主题 ID；无效输入按候选和默认主题回退。
+ *
+ * @example
+ * ```ts
+ * import { normalizeThemeId } from '@h-ai/ui'
+ * const theme = normalizeThemeId('unknown-theme', 'light')
+ * ```
  */
 export function normalizeThemeId(themeId, fallbackThemeId = DEFAULT_THEME) {
     const normalized = `${themeId ?? ''}`;
@@ -101,6 +183,14 @@ export function normalizeThemeId(themeId, fallbackThemeId = DEFAULT_THEME) {
 }
 /**
  * 归一化 Hex 颜色；无效值返回 null。
+ * @param value - 待处理或校验的值。
+ * @returns 小写六位 Hex 颜色；无效输入返回 null。
+ *
+ * @example
+ * ```ts
+ * import { normalizeHexColor } from '@h-ai/ui'
+ * const color = normalizeHexColor('#abc')
+ * ```
  */
 export function normalizeHexColor(value) {
     const normalized = value?.trim().toLowerCase() ?? '';
@@ -114,6 +204,14 @@ export function normalizeHexColor(value) {
 }
 /**
  * 解析主题对应的浏览器色调。
+ * @param themeId - 主题候选 ID。
+ * @returns 供浏览器控件配色使用的 light/dark 值。
+ *
+ * @example
+ * ```ts
+ * import { resolveThemeTone } from '@h-ai/ui'
+ * const tone = resolveThemeTone('dark')
+ * ```
  */
 export function resolveThemeTone(themeId) {
     return isDarkTheme(themeId) ? 'dark' : 'light';
@@ -127,6 +225,15 @@ function escapeJsonForScript(value) {
 }
 /**
  * 生成首屏主题恢复脚本，适合注入到 SvelteKit `app.html` 的 `<script>` 中。
+ * @param options - 本次操作的行为与显示选项。
+ * @returns 可放入受控 HTML shell 的初始化脚本文本。
+ *
+ * @example
+ * ```ts
+ * import { createThemeBootstrapScript } from '@h-ai/ui'
+ * const script = createThemeBootstrapScript({ storageKey: 'demo-theme', defaultThemeId: 'light' })
+ * // 在应用 HTML shell 中作为受控脚本使用，避免首屏主题闪烁。
+ * ```
  */
 export function createThemeBootstrapScript(options) {
     const defaultThemeId = normalizeThemeId(options.defaultThemeId ?? DEFAULT_THEME);
@@ -156,6 +263,13 @@ export function createThemeBootstrapScript(options) {
  *
  * 返回值是“脚本标签内的文本内容”，适合宿主在构建阶段或服务端模板中注入。
  * 对于 SvelteKit `app.html`，请直接粘贴这段脚本字符串的内容，不能写 `{@html getThemeInitScript()}`。
+ * @returns 使用默认存储约定的主题初始化脚本。
+ *
+ * @example
+ * ```ts
+ * import { getThemeInitScript } from '@h-ai/ui'
+ * const script = getThemeInitScript()
+ * ```
  */
 export function getThemeInitScript() {
     return createThemeBootstrapScript({
@@ -167,6 +281,14 @@ export function getThemeInitScript() {
  * 应用主题
  * @param theme - 主题 ID
  * @param persist - 是否持久化到 localStorage
+ * @returns {void} 无返回值；更新当前文档，并按 persist 决定是否保存偏好。
+ *
+ * @example
+ * ```ts
+ * import { applyTheme } from '@h-ai/ui'
+ * applyTheme('dark', false)
+ * // false 仅更新当前 DOM，不写入持久化偏好。
+ * ```
  */
 export function applyTheme(theme, persist = true) {
     if (typeof document === 'undefined')
@@ -178,6 +300,13 @@ export function applyTheme(theme, persist = true) {
 }
 /**
  * 获取当前主题
+ * @returns 当前文档主题；无 DOM 时使用默认值。
+ *
+ * @example
+ * ```ts
+ * import { getCurrentTheme } from '@h-ai/ui'
+ * const theme = getCurrentTheme()
+ * ```
  */
 export function getCurrentTheme() {
     if (typeof document === 'undefined')
@@ -188,6 +317,13 @@ export function getCurrentTheme() {
  * 获取保存的主题；存储为空或不可用时使用宿主默认主题。
  *
  * @param fallbackTheme - 未保存主题时的默认值，默认 light
+ * @returns 安全读取并归一化的主题偏好。
+ *
+ * @example
+ * ```ts
+ * import { getSavedTheme } from '@h-ai/ui'
+ * const theme = getSavedTheme('light')
+ * ```
  */
 export function getSavedTheme(fallbackTheme = DEFAULT_THEME) {
     return readStoredValue(THEME_STORAGE_KEY) ?? fallbackTheme;
@@ -201,6 +337,13 @@ export function getSavedTheme(fallbackTheme = DEFAULT_THEME) {
  * @plugin "daisyui" {
  *   themes: light --default, dark --prefersdark, cupcake, bumblebee, ...
  * }
+ *
+ * @example
+ * ```ts
+ * import { DAISYUI_THEMES_CONFIG } from '@h-ai/ui'
+ * const css = '@plugin "daisyui" { themes: ' + DAISYUI_THEMES_CONFIG + '; }'
+ * // 将生成的配置用于构建时 CSS，不在浏览器动态安装主题。
+ * ```
  */
 export const DAISYUI_THEMES_CONFIG = THEMES.map((t, i) => {
     if (i === 0)

package/dist/toast.svelte.d.ts

@@ -7,6 +7,12 @@
 import type { ToastProps } from './types.js';
 /**
  * Toast 项
+ *
+ * @example
+ * ```ts
+ * import type { ToastItem } from '@h-ai/ui'
+ * const example: ToastItem = { id: 'toast-1', message: '保存完成', variant: 'success', duration: 3000 }
+ * ```
  */
 export interface ToastItem extends ToastProps {
     id: string;
@@ -20,26 +26,110 @@ declare class ToastState {
     private timers;
     /**
      * 添加 Toast
+     * @param props - 组件的属性对象。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.add({ message: '保存完成', variant: 'success', duration: 3000 })
+     * toast.remove(id)
+     * ```
      */
     add(props: Omit<ToastProps, 'onclose'>): string;
     /**
      * 移除 Toast
+     * @param id - 待移除的条目 ID。
+     * @returns {void} 无返回值；同时清理对应的自动关闭定时器。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.info('同步中', 0)
+     * toast.remove(id)
+     * ```
      */
     remove(id: string): void;
     /**
      * 清空所有 Toast
+     * @returns {void} 无返回值；同时清理对应的自动关闭定时器。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * toast.info('同步中', 0)
+     * toast.clear()
+     * ```
      */
     clear(): void;
     /**
      * 快捷方法
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.success('操作结果', 3000)
+     * toast.remove(id)
+     * ```
      */
     success(message: string, duration?: number): string;
+    /**
+     * 处理 error 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.error('操作结果', 3000)
+     * toast.remove(id)
+     * ```
+     */
     error(message: string, duration?: number): string;
+    /**
+     * 处理 warning 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.warning('操作结果', 3000)
+     * toast.remove(id)
+     * ```
+     */
     warning(message: string, duration?: number): string;
+    /**
+     * 处理 info 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.info('操作结果', 3000)
+     * toast.remove(id)
+     * ```
+     */
     info(message: string, duration?: number): string;
 }
 /**
  * Toast 单例
+ *
+ * @example
+ * ```ts
+ * import { toast } from '@h-ai/ui'
+ * // 页面布局需挂载 ToastContainer。
+ * const id = toast.success('保存完成', 3000)
+ * toast.remove(id)
+ * toast.clear()
+ * ```
  */
 export declare const toast: ToastState;
 /**
@@ -49,9 +139,14 @@ export declare const toast: ToastState;
  *
  * @param message - 用户可见的成功文案（已本地化）。
  * @param duration - 可选停留时长（毫秒），默认 3000。
+ * @returns 新通知的 ID，可交给 toast.remove 提前移除。
  *
  * @example
- * notifySuccess(m.submit_submitted())
+ * ```ts
+ * import { notifySuccess, toast } from '@h-ai/ui'
+ * const id = notifySuccess('保存完成', 3000)
+ * toast.remove(id)
+ * ```
  */
 export declare function notifySuccess(message: string, duration?: number): string;
 /**
@@ -63,9 +158,14 @@ export declare function notifySuccess(message: string, duration?: number): strin
  * @param error - 错误对象或已本地化的错误文案。
  * @param fallback - 当 error 非 Error 且为空时使用的兜底文案。
  * @param duration - 可选停留时长（毫秒），默认 5000。
+ * @returns 新错误通知的 ID，可交给 toast.remove 提前移除。
  *
  * @example
- * notifyError(error, m.submit_failed())
+ * ```ts
+ * import { notifyError, toast } from '@h-ai/ui'
+ * const id = notifyError(new Error('提交失败'), '请稍后重试', 5000)
+ * toast.remove(id)
+ * ```
  */
 export declare function notifyError(error: unknown, fallback?: string, duration?: number): string;
 /**
@@ -73,9 +173,14 @@ export declare function notifyError(error: unknown, fallback?: string, duration?
  *
  * @param message - 用户可见文案（已本地化）。
  * @param duration - 可选停留时长（毫秒），默认 3000。
+ * @returns 新提示的 ID。
  *
  * @example
- * notifyInfo(m.common_saved())
+ * ```ts
+ * import { notifyInfo, toast } from '@h-ai/ui'
+ * const id = notifyInfo('正在同步', 3000)
+ * toast.remove(id)
+ * ```
  */
 export declare function notifyInfo(message: string, duration?: number): string;
 /**
@@ -83,9 +188,14 @@ export declare function notifyInfo(message: string, duration?: number): string;
  *
  * @param message - 用户可见文案（已本地化）。
  * @param duration - 可选停留时长（毫秒），默认 5000。
+ * @returns 新警告的 ID。
  *
  * @example
- * notifyWarning(m.quota_almost_reached())
+ * ```ts
+ * import { notifyWarning, toast } from '@h-ai/ui'
+ * const id = notifyWarning('请先保存修改', 5000)
+ * toast.remove(id)
+ * ```
  */
 export declare function notifyWarning(message: string, duration?: number): string;
 export {};

package/dist/toast.svelte.js

@@ -13,6 +13,15 @@ class ToastState {
     timers = new Map();
     /**
      * 添加 Toast
+     * @param props - 组件的属性对象。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.add({ message: '保存完成', variant: 'success', duration: 3000 })
+     * toast.remove(id)
+     * ```
      */
     add(props) {
         const id = Math.random().toString(36).slice(2, 9);
@@ -36,6 +45,15 @@ class ToastState {
     }
     /**
      * 移除 Toast
+     * @param id - 待移除的条目 ID。
+     * @returns {void} 无返回值；同时清理对应的自动关闭定时器。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.info('同步中', 0)
+     * toast.remove(id)
+     * ```
      */
     remove(id) {
         const timer = this.timers.get(id);
@@ -47,6 +65,14 @@ class ToastState {
     }
     /**
      * 清空所有 Toast
+     * @returns {void} 无返回值；同时清理对应的自动关闭定时器。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * toast.info('同步中', 0)
+     * toast.clear()
+     * ```
      */
     clear() {
         for (const timer of this.timers.values()) {
@@ -57,22 +83,80 @@ class ToastState {
     }
     /**
      * 快捷方法
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.success('操作结果', 3000)
+     * toast.remove(id)
+     * ```
      */
     success(message, duration) {
         return this.add({ message, variant: 'success', duration });
     }
+    /**
+     * 处理 error 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.error('操作结果', 3000)
+     * toast.remove(id)
+     * ```
+     */
     error(message, duration) {
         return this.add({ message, variant: 'error', duration });
     }
+    /**
+     * 处理 warning 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.warning('操作结果', 3000)
+     * toast.remove(id)
+     * ```
+     */
     warning(message, duration) {
         return this.add({ message, variant: 'warning', duration });
     }
+    /**
+     * 处理 info 操作。
+     * @param message - 已经本地化的用户提示。
+     * @param duration - 提示持续时间，单位毫秒。
+     * @returns 新条目的 ID，可用于提前移除。
+     * @example
+     * ```ts
+     * import { toast } from '@h-ai/ui'
+     * // 布局中需挂载 ToastContainer。
+     * const id = toast.info('操作结果', 3000)
+     * toast.remove(id)
+     * ```
+     */
     info(message, duration) {
         return this.add({ message, variant: 'info', duration });
     }
 }
 /**
  * Toast 单例
+ *
+ * @example
+ * ```ts
+ * import { toast } from '@h-ai/ui'
+ * // 页面布局需挂载 ToastContainer。
+ * const id = toast.success('保存完成', 3000)
+ * toast.remove(id)
+ * toast.clear()
+ * ```
  */
 export const toast = new ToastState();
 /** 成功提示默认停留时长（毫秒）。 */
@@ -86,9 +170,14 @@ const ERROR_DURATION = 5000;
  *
  * @param message - 用户可见的成功文案（已本地化）。
  * @param duration - 可选停留时长（毫秒），默认 3000。
+ * @returns 新通知的 ID，可交给 toast.remove 提前移除。
  *
  * @example
- * notifySuccess(m.submit_submitted())
+ * ```ts
+ * import { notifySuccess, toast } from '@h-ai/ui'
+ * const id = notifySuccess('保存完成', 3000)
+ * toast.remove(id)
+ * ```
  */
 export function notifySuccess(message, duration = SUCCESS_DURATION) {
     return toast.success(message, duration);
@@ -102,9 +191,14 @@ export function notifySuccess(message, duration = SUCCESS_DURATION) {
  * @param error - 错误对象或已本地化的错误文案。
  * @param fallback - 当 error 非 Error 且为空时使用的兜底文案。
  * @param duration - 可选停留时长（毫秒），默认 5000。
+ * @returns 新错误通知的 ID，可交给 toast.remove 提前移除。
  *
  * @example
- * notifyError(error, m.submit_failed())
+ * ```ts
+ * import { notifyError, toast } from '@h-ai/ui'
+ * const id = notifyError(new Error('提交失败'), '请稍后重试', 5000)
+ * toast.remove(id)
+ * ```
  */
 export function notifyError(error, fallback = '', duration = ERROR_DURATION) {
     const message = error instanceof Error
@@ -117,9 +211,14 @@ export function notifyError(error, fallback = '', duration = ERROR_DURATION) {
  *
  * @param message - 用户可见文案（已本地化）。
  * @param duration - 可选停留时长（毫秒），默认 3000。
+ * @returns 新提示的 ID。
  *
  * @example
- * notifyInfo(m.common_saved())
+ * ```ts
+ * import { notifyInfo, toast } from '@h-ai/ui'
+ * const id = notifyInfo('正在同步', 3000)
+ * toast.remove(id)
+ * ```
  */
 export function notifyInfo(message, duration = SUCCESS_DURATION) {
     return toast.info(message, duration);
@@ -129,9 +228,14 @@ export function notifyInfo(message, duration = SUCCESS_DURATION) {
  *
  * @param message - 用户可见文案（已本地化）。
  * @param duration - 可选停留时长（毫秒），默认 5000。
+ * @returns 新警告的 ID。
  *
  * @example
- * notifyWarning(m.quota_almost_reached())
+ * ```ts
+ * import { notifyWarning, toast } from '@h-ai/ui'
+ * const id = notifyWarning('请先保存修改', 5000)
+ * toast.remove(id)
+ * ```
  */
 export function notifyWarning(message, duration = ERROR_DURATION) {
     return toast.warning(message, duration);