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

package/dist/messages/zh-CN.json

@@ -11,7 +11,6 @@
   "login_username_placeholder": "请输入用户名或邮箱",
   "login_password": "密码",
   "login_password_placeholder": "请输入密码",
-  "login_remember_me": "记住我",
   "login_forgot_password": "忘记密码？",
   "login_submit": "登录",
   "login_title": "登录",
@@ -25,6 +24,7 @@
   "combobox_remove": "移除",
   "data_table_actions": "操作",
   "data_table_empty": "暂无数据",
+  "common_loading": "正在加载…",
   "chart_loading": "图表加载中",
   "chart_empty": "暂无数据",
   "confirm_title": "确认",
@@ -166,6 +166,11 @@
   "pagination_page_size": "{size} 条/页",
   "pagination_rows_per_page": "每页",
   "pagination_page_info": "第 {page} / {total} 页",
+  "pagination_first": "首页",
+  "pagination_previous": "上一页",
+  "pagination_next": "下一页",
+  "pagination_last": "末页",
+  "pagination_jump_label": "跳转到页",
   "severity_critical": "严重",
   "severity_high": "高",
   "severity_medium": "中",

package/dist/messages.d.ts

@@ -5,26 +5,47 @@
  * @module messages
  */
 import messagesZhCN from './messages/zh-CN.json';
+/**
+ * 内置翻译键集合；应用业务文案使用应用自己的翻译字典。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: UIMessageKey = 'password_show'
+ * ```
+ */
 export type UIMessageKey = keyof typeof messagesZhCN;
 /**
  * 获取 UI 组件翻译消息
  *
  * @param key - 消息 key
  * @param params - 可选的插值参数
- * @param locale - 可选的宿主语言；省略时使用现有全局语言
+ * @param locale - 可选的宿主语言；省略时使用 Node 请求语言或浏览器应用语言
  * @returns 当前 locale 对应的翻译文本
  *
- * @example
+ * @example 模块内部上下文
  * ```ts
- * uiM('password_show') // => '显示密码' (zh-CN) 或 'Show password' (en-US)
+ * const label = uiM('password_show', undefined, 'zh-CN')
  * ```
  */
 export declare function uiM(key: UIMessageKey, params?: Record<string, string | number | boolean>, locale?: string): string;
 /**
  * 获取当前 UI 模块使用的 locale
+ * @returns 当前 UI 语言。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const locale = getUILocale()
+ * ```
  */
 export declare function getUILocale(): string;
 /**
  * 手动设置 UI 模块的 locale（通常不需要，会自动同步）
+ * @param locale - 显式语言代码；省略时使用当前上下文。
+ * @returns {void} 无返回值；同步浏览器 UI 语言。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * setUILocale('en-US')
+ * ```
  */
 export declare function setUILocale(locale: string): void;

package/dist/messages.js

@@ -8,23 +8,25 @@ import { core } from '@h-ai/core';
 import { changeUILocale, readUILocale } from './internal/locale.js';
 // 导入消息文件
 import messagesEnUS from './messages/en-US.json';
+import messagesJaJP from './messages/ja-JP.json';
 import messagesZhCN from './messages/zh-CN.json';
 // 创建消息获取器
 const getMessage = core.i18n.createMessageGetter({
     'zh-CN': messagesZhCN,
     'en-US': messagesEnUS,
+    'ja-JP': messagesJaJP,
 });
 /**
  * 获取 UI 组件翻译消息
  *
  * @param key - 消息 key
  * @param params - 可选的插值参数
- * @param locale - 可选的宿主语言；省略时使用现有全局语言
+ * @param locale - 可选的宿主语言；省略时使用 Node 请求语言或浏览器应用语言
  * @returns 当前 locale 对应的翻译文本
  *
- * @example
+ * @example 模块内部上下文
  * ```ts
- * uiM('password_show') // => '显示密码' (zh-CN) 或 'Show password' (en-US)
+ * const label = uiM('password_show', undefined, 'zh-CN')
  * ```
  */
 export function uiM(key, params, locale) {
@@ -32,12 +34,25 @@ export function uiM(key, params, locale) {
 }
 /**
  * 获取当前 UI 模块使用的 locale
+ * @returns 当前 UI 语言。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const locale = getUILocale()
+ * ```
  */
 export function getUILocale() {
     return readUILocale();
 }
 /**
  * 手动设置 UI 模块的 locale（通常不需要，会自动同步）
+ * @param locale - 显式语言代码；省略时使用当前上下文。
+ * @returns {void} 无返回值；同步浏览器 UI 语言。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * setUILocale('en-US')
+ * ```
  */
 export function setUILocale(locale) {
     changeUILocale(locale);

package/dist/styles/design-tokens.css

@@ -1,15 +1,17 @@
 /**
  * =============================================================================
- * @hai/ui - Design Token 系统
+ * @h-ai/ui - Design Token 系统
  * =============================================================================
  * 所有视觉变量通过 CSS Variables 定义，多端复用。
  *
  * 在 app.css 中导入：
- * @import '@hai/ui/styles/design-tokens.css';
+ * @import '@h-ai/ui/styles/design-tokens.css';
  * =============================================================================
  */
 
 :root {
+  /* 焦点继承当前 DaisyUI 主题，业务可在主题层覆盖。 */
+  --hai-focus-color: var(--color-primary);
   /* ─── 间距 ─── */
   --hai-spacing-xs: 4px;
   --hai-spacing-sm: 8px;

package/dist/styles/global.css

@@ -1,6 +1,6 @@
 /**
  * =============================================================================
- * @hai/ui - 全局样式
+ * @h-ai/ui - 全局样式
  * =============================================================================
  * 可选的全局样式增强，消费应用可通过以下方式导入：
  *
@@ -45,8 +45,8 @@ body {
 .input:focus,
 .select:focus,
 .textarea:focus {
-  outline: none;
-  box-shadow: 0 0 0 2px oklch(var(--p) / 0.15);
+  outline: 2px solid var(--hai-focus-color, var(--color-primary));
+  outline-offset: 2px;
 }
 
 /* ─── 隐藏浏览器原生密码显示按钮（使用自定义切换） ─── */
@@ -61,7 +61,7 @@ input::-webkit-credentials-auto-fill-button {
    表单组件 (.select, .radio, .checkbox, .toggle, .textarea, input, textarea)
    由 DaisyUI 或组件自身处理焦点样式 */
 :focus-visible:not(input, select, textarea, .select, .radio, .checkbox, .toggle, .textarea) {
-  outline: 2px solid oklch(0.6 0.15 250);
+  outline: 2px solid var(--hai-focus-color, var(--color-primary));
   outline-offset: 2px;
   border-radius: 4px;
 }
@@ -69,12 +69,16 @@ input::-webkit-credentials-auto-fill-button {
 /* ─── DaisyUI 组件微调 ─── */
 .card {
   transition:
-    box-shadow 0.2s cubic-bezier(0.4, 0, 0.2, 1),
-    transform 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+    box-shadow var(--hai-transition-normal, 250ms) cubic-bezier(0.4, 0, 0.2, 1),
+    transform var(--hai-transition-normal, 250ms) cubic-bezier(0.4, 0, 0.2, 1);
 }
 
 .btn {
-  transition: all 0.15s cubic-bezier(0.4, 0, 0.2, 1);
+  transition:
+    color var(--hai-transition-fast, 150ms),
+    background-color var(--hai-transition-fast, 150ms),
+    border-color var(--hai-transition-fast, 150ms),
+    box-shadow var(--hai-transition-fast, 150ms);
 }
 
 .badge {
@@ -86,7 +90,7 @@ input::-webkit-credentials-auto-fill-button {
   font-size: 0.75rem;
   text-transform: uppercase;
   letter-spacing: 0.05em;
-  color: oklch(0.55 0 0);
+  color: color-mix(in oklab, var(--color-base-content) 70%, transparent);
 }
 
 /* ─── DaisyUI 组件微调：fieldset-legend 间距修正 ─── */
@@ -264,3 +268,19 @@ input::-webkit-credentials-auto-fill-button {
 .fade-in {
   animation-name: hai-fade-in;
 }
+
+/* 保留最终状态及动画结束事件，减少动态效果时不再播放装饰运动。 */
+@media (prefers-reduced-motion: reduce) {
+  html {
+    scroll-behavior: auto;
+  }
+
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}

package/dist/styles/theme.css

@@ -11,6 +11,8 @@
  * =============================================================================
  */
 
+@import './design-tokens.css';
+
 :root {
   --hai-theme-color-default: #5765f0;
   --hai-theme-color-tech-purple: #5765f0;

package/dist/theme-config.d.ts

@@ -7,6 +7,12 @@
 import type { UIMessageKey } from './messages.js';
 /**
  * 主题信息
+ *
+ * @example
+ * ```ts
+ * import type { ThemeInfo } from '@h-ai/ui'
+ * const example: ThemeInfo = { id: 'light', name: 'Light', dark: false, primaryColor: '#2563eb', bgColor: '#ffffff' }
+ * ```
  */
 export interface ThemeInfo {
     /** 主题标识符 */
@@ -22,6 +28,12 @@ export interface ThemeInfo {
 }
 /**
  * 主题色预设定义
+ *
+ * @example
+ * ```ts
+ * import type { ThemeColorPreset } from '@h-ai/ui'
+ * const example: ThemeColorPreset = { value: '#2563eb', labelKey: 'theme_color_ocean' }
+ * ```
  */
 export interface ThemeColorPreset {
     /** 颜色值（Hex） */
@@ -31,6 +43,12 @@ export interface ThemeColorPreset {
 }
 /**
  * 主题分组
+ *
+ * @example
+ * ```ts
+ * import type { ThemeGroup } from '@h-ai/ui'
+ * const example: ThemeGroup = { id: 'light', nameKey: 'theme_group_light', themes: [{ id: 'light', name: 'Light', dark: false, primaryColor: '#2563eb', bgColor: '#ffffff' }] }
+ * ```
  */
 export interface ThemeGroup {
     /** 分组标识 */
@@ -42,58 +60,156 @@ export interface ThemeGroup {
 }
 /**
  * DaisyUI 内置主题配置（精选）
+ *
+ * @example
+ * ```ts
+ * import { THEMES } from '@h-ai/ui'
+ * const choices = THEMES.map(theme => ({ value: theme.id, label: theme.name }))
+ * ```
  */
 export declare const THEMES: ThemeInfo[];
 /**
  * 主题分组配置
+ *
+ * @example
+ * ```ts
+ * import { THEME_GROUPS } from '@h-ai/ui'
+ * const light = THEME_GROUPS.find(group => group.id === 'light')
+ * const choices = light?.themes
+ * ```
  */
 export declare const THEME_GROUPS: ThemeGroup[];
 /**
  * 暗色主题列表
+ *
+ * @example
+ * ```ts
+ * import { DARK_THEMES } from '@h-ai/ui'
+ * const dark = DARK_THEMES.includes('dark')
+ * ```
  */
 export declare const DARK_THEMES: string[];
 /**
  * 支持的主题 ID 列表
+ *
+ * @example
+ * ```ts
+ * import { SUPPORTED_THEME_IDS } from '@h-ai/ui'
+ * const supported = SUPPORTED_THEME_IDS.includes('light')
+ * ```
  */
 export declare const SUPPORTED_THEME_IDS: string[];
 /**
  * 默认主题色
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_THEME_COLOR } from '@h-ai/ui'
+ * const style = { '--brand-color': DEFAULT_THEME_COLOR }
+ * ```
  */
 export declare 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 declare 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 declare const THEME_COLOR_PRESETS: ThemeColorPreset[];
 /**
  * 默认主题
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_THEME, applyTheme } from '@h-ai/ui'
+ * applyTheme(DEFAULT_THEME, false)
+ * ```
  */
 export declare 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 declare 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 declare function getThemeInfo(themeId: string): ThemeInfo | undefined;
 /**
  * 检查是否为暗色主题
+ * @param themeId - 主题候选 ID。
+ * @returns 是否属于内置暗色主题。
+ *
+ * @example
+ * ```ts
+ * import { isDarkTheme } from '@h-ai/ui'
+ * const dark = isDarkTheme('dark')
+ * ```
  */
 export declare function isDarkTheme(themeId: string): boolean;
 /**
  * 归一化主题 ID，不支持的值回退到默认主题。
+ * @param themeId - 主题候选 ID。
+ * @param fallbackThemeId - 候选不支持时尝试的主题。
+ * @returns 支持的主题 ID；无效输入按候选和默认主题回退。
+ *
+ * @example
+ * ```ts
+ * import { normalizeThemeId } from '@h-ai/ui'
+ * const theme = normalizeThemeId('unknown-theme', 'light')
+ * ```
  */
 export declare function normalizeThemeId(themeId: string | null | undefined, fallbackThemeId?: string): string;
 /**
  * 归一化 Hex 颜色；无效值返回 null。
+ * @param value - 待处理或校验的值。
+ * @returns 小写六位 Hex 颜色；无效输入返回 null。
+ *
+ * @example
+ * ```ts
+ * import { normalizeHexColor } from '@h-ai/ui'
+ * const color = normalizeHexColor('#abc')
+ * ```
  */
 export declare function normalizeHexColor(value: string | null | undefined): string | null;
 /**
  * 解析主题对应的浏览器色调。
+ * @param themeId - 主题候选 ID。
+ * @returns 供浏览器控件配色使用的 light/dark 值。
+ *
+ * @example
+ * ```ts
+ * import { resolveThemeTone } from '@h-ai/ui'
+ * const tone = resolveThemeTone('dark')
+ * ```
  */
 export declare function resolveThemeTone(themeId: string): 'light' | 'dark';
 /**
@@ -101,6 +217,12 @@ export declare function resolveThemeTone(themeId: string): 'light' | 'dark';
  *
  * 业务侧如果把语言和主题一起落到同一个偏好对象里，可用这组配置在首屏阶段同步恢复语言值，
  * 避免 HTML shell 和 hydrate 后的语言状态短暂不一致。
+ *
+ * @example
+ * ```ts
+ * import type { ThemeBootstrapLocaleConfig } from '@h-ai/ui'
+ * const example: ThemeBootstrapLocaleConfig = { key: 'demo-locale', defaultValue: 'zh-CN', supportedValues: ['zh-CN', 'en-US'] }
+ * ```
  */
 export interface ThemeBootstrapLocaleConfig {
     /** 偏好对象中的语言字段名。 */
@@ -115,6 +237,12 @@ export interface ThemeBootstrapLocaleConfig {
  *
  * 这组配置刻意只保留“HTML shell 首屏恢复”所需的信息，避免把运行时 helper 或 UI 组件状态
  * 泄漏到脚本字符串里，方便不同应用在 `app.html` / 服务端模板中复用同一套恢复逻辑。
+ *
+ * @example
+ * ```ts
+ * import type { ThemeBootstrapScriptOptions } from '@h-ai/ui'
+ * const example: ThemeBootstrapScriptOptions = { storageKey: 'demo-theme', defaultThemeId: 'light', defaultThemeColor: '#2563eb' }
+ * ```
  */
 export interface ThemeBootstrapScriptOptions {
     /** 偏好存储 key。 */
@@ -134,6 +262,15 @@ export interface ThemeBootstrapScriptOptions {
 }
 /**
  * 生成首屏主题恢复脚本，适合注入到 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 declare function createThemeBootstrapScript(options: ThemeBootstrapScriptOptions): string;
 /**
@@ -141,22 +278,51 @@ export declare function createThemeBootstrapScript(options: ThemeBootstrapScript
  *
  * 返回值是“脚本标签内的文本内容”，适合宿主在构建阶段或服务端模板中注入。
  * 对于 SvelteKit `app.html`，请直接粘贴这段脚本字符串的内容，不能写 `{@html getThemeInitScript()}`。
+ * @returns 使用默认存储约定的主题初始化脚本。
+ *
+ * @example
+ * ```ts
+ * import { getThemeInitScript } from '@h-ai/ui'
+ * const script = getThemeInitScript()
+ * ```
  */
 export declare function getThemeInitScript(): string;
 /**
  * 应用主题
  * @param theme - 主题 ID
  * @param persist - 是否持久化到 localStorage
+ * @returns {void} 无返回值；更新当前文档，并按 persist 决定是否保存偏好。
+ *
+ * @example
+ * ```ts
+ * import { applyTheme } from '@h-ai/ui'
+ * applyTheme('dark', false)
+ * // false 仅更新当前 DOM，不写入持久化偏好。
+ * ```
  */
 export declare function applyTheme(theme: string, persist?: boolean): void;
 /**
  * 获取当前主题
+ * @returns 当前文档主题；无 DOM 时使用默认值。
+ *
+ * @example
+ * ```ts
+ * import { getCurrentTheme } from '@h-ai/ui'
+ * const theme = getCurrentTheme()
+ * ```
  */
 export declare function getCurrentTheme(): string;
 /**
  * 获取保存的主题；存储为空或不可用时使用宿主默认主题。
  *
  * @param fallbackTheme - 未保存主题时的默认值，默认 light
+ * @returns 安全读取并归一化的主题偏好。
+ *
+ * @example
+ * ```ts
+ * import { getSavedTheme } from '@h-ai/ui'
+ * const theme = getSavedTheme('light')
+ * ```
  */
 export declare function getSavedTheme(fallbackTheme?: string): string;
 /**
@@ -168,5 +334,12 @@ export declare function getSavedTheme(fallbackTheme?: string): string;
  * @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 declare const DAISYUI_THEMES_CONFIG: string;