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

package/README.md

@@ -4,19 +4,31 @@
 
 [框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
 
-> 基于 Svelte 5 Runes 的多端 UI 组件库，采用 DaisyUI v5 + Tailwind CSS v4 样式 + Bits UI v2 headless 交互，内置 i18n（zh-CN / en-US），内置 15 个精选 DaisyUI 主题。
+## 简介
 
-## 安装
+内置中英日文消息（`zh-CN` / `en-US` / `ja-JP`），语言选择器默认提供三种语言。
+
+基于 Svelte 5 Runes 的多端 UI 组件库，采用 DaisyUI v5 + Tailwind CSS v4 样式 + Bits UI v2 headless 交互，内置 i18n（zh-CN / en-US），内置 15 个精选 DaisyUI 主题。
+
+## 核心功能清单
+
+- 表单、表格、弹窗、导航、图表与业务场景组件。
+- 认证、CRUD、AI 内容展示、新手引导和帮助中心。
+- Svelte 5、主题切换、响应式布局及中英日文组件文案。
+
+## 使用入门
+
+### 安装
 
 ```bash
-npm install @h-ai/ui
+npm install @h-ai/ui @h-ai/core
 ```
 
-依赖 `@h-ai/core`（会自动安装）。
+Node 服务端工程将 UI 与 core 都列为生产依赖，确保适配器保留 core 的日志和原生依赖加载。
 
-## 快速开始
+### 快速开始
 
-### 1. 配置 svelte.config.js
+#### 1. 配置 svelte.config.js
 
 ```js
 import { autoImportHaiUi } from '@h-ai/ui/auto-import'
@@ -33,7 +45,7 @@ const config = {
 export default config
 ```
 
-### 2. 配置 vite.config.ts
+#### 2. 配置 vite.config.ts
 
 ```ts
 import { haiOptimizeExclude, haiPrebundledDeps } from '@h-ai/ui/vite'
@@ -51,11 +63,13 @@ export default defineConfig({
     // 避免首次进入业务路由时触发依赖再优化与整页刷新
     include: [...haiPrebundledDeps],
   },
-  ssr: { noExternal: [/@h-ai\//] },
+  ssr: { noExternal: ['@h-ai/ui', '@h-ai/kit'], external: ['@h-ai/core', 'sm-crypto'] },
 })
 ```
 
-### 3. 配置 src/app.css
+使用 Crypto 或依赖它的 Kit/IAM 时，应用生产依赖需包含 `sm-crypto@0.5.7`。CLI 已配好这一项；手工接入时运行 `pnpm add sm-crypto@0.5.7`。仅设置 external 不够，adapter-node 还需要这项直接依赖声明才能保留原包加载。
+
+#### 3. 配置 src/app.css
 
 ```css
 @import 'tailwindcss';
@@ -76,7 +90,7 @@ export default defineConfig({
 
 > `@source` 让 TailwindCSS 扫描 `@h-ai/ui` 组件中使用的 class 名，否则组件样式会丢失。嵌套应用位于 monorepo 中时，依赖包可能被提升到工作区根 `node_modules`，所以建议同时保留两条路径。
 
-### 4. 使用组件
+#### 4. 使用组件
 
 ```svelte
 <script>
@@ -108,7 +122,7 @@ import { Button } from '@h-ai/ui/components/primitives/index'
 import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
 ```
 
-### data-* 属性透传
+#### data-* 属性透传
 
 公开 Svelte 组件支持把调用方传入的 `data-*` 属性透传到组件根节点或主交互节点，便于测试选择器、埋点和自动化标记。普通未知属性不会被透传。
 
@@ -120,7 +134,7 @@ import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
 
 无需再为了 `data-testid` 单独封装按钮、输入框或弹层组件。
 
-## 组件架构
+### 组件架构
 
 组件按三层划分（primitives → compounds → scenes）：
 
@@ -137,9 +151,9 @@ components/
     └── crypto/   # 加密展示
 ```
 
-## 组件清单
+### 组件清单
 
-### 原子组件 Primitives（20 个）
+#### 原子组件 Primitives（20 个）
 
 | 组件             | 描述         | 主要属性                                                           |
 | ---------------- | ------------ | ------------------------------------------------------------------ |
@@ -166,9 +180,9 @@ components/
 
 `BareInput` 的 `file` 类型通过 `onchange` 读取 `event.currentTarget.files`，不绑定文件路径 `value`；其他输入类型可使用 `bind:value`。
 
-### 组合组件 Compounds（37 个）
+#### 组合组件 Compounds（37 个）
 
-#### 表单
+##### 表单
 
 | 组件        | 描述     | 主要属性                                     |
 | ----------- | -------- | -------------------------------------------- |
@@ -177,7 +191,7 @@ components/
 | `FormLayout` | 表单布局 | `columns`, `labelPosition`, `labelWidth` |
 | `TagInput`  | 标签输入 | `tags`, `maxTags`, `allowDuplicates`, `size` |
 
-#### 表单布局与校验
+##### 表单布局与校验
 
 `Form` 和可嵌入原生 `<form>` 的 `FormLayout` 共用 `columns={1 | 2}`、`labelPosition="top" | "left"`、`labelWidth`（默认 `8rem`）。默认单列、标签独立成行；双列在容器不足 `36rem` 时收为单列，同行标签在容器不足 `28rem` 时改为上下排列。
 
@@ -185,7 +199,7 @@ components/
 
 标签自动关联内部 UI 控件；已有控件 ID 或原生控件使用 `<FormField for="control-id">`。错误/提示通过 `aria-describedby` 关联，错误控件带 `aria-invalid`，只显示一份字段提示。`label` / `error` / `hint` 支持字符串或延迟翻译函数。
 
-`Input`、`Textarea`、`Select` 和 `PasswordInput` 的原生校验使用内置中英文提示；`validationMessage` 只覆盖失败提示，不让有效输入一直无效。应用通过 UI 的 `setGlobalLocale` / `createLocaleStore` 同步语言，已显示的校验错误即时更新。`Textarea` 支持 `minlength` / `maxlength`，`Select` 支持 `name`、必填校验和 FormData 序列化。
+`Input`、`Textarea`、`Select` 和 `PasswordInput` 的原生校验使用内置中英日文提示；`validationMessage` 只覆盖失败提示，不让有效输入一直无效。应用通过 UI 的 `setGlobalLocale` / `createLocaleStore` 同步语言，已显示的校验错误即时更新。`Textarea` 支持 `minlength` / `maxlength`，`Select` 支持 `name`、必填校验和 FormData 序列化。
 
 字段首次失焦后显示前端校验错误，修正输入时即时更新；未访问的字段在提交时统一校验。CRUD 新增/编辑复用该行为，支持自定义校验文案，关闭重开清空校验状态。`Select` 在焦点离开触发器和选项后校验。`PasswordInput.minLength` 同时约束长度并用于强度计算；省略时不限制登录密码长度，强度计算仍以 8 位为基准。
 
@@ -206,14 +220,14 @@ components/
 </Form>
 ```
 
-#### 反馈
+##### 反馈
 
 | 组件             | 描述     | 主要属性                          |
 | ---------------- | -------- | --------------------------------- |
 | `Alert`          | 警告框   | `variant`, `title`, `dismissible` |
 | `ToastContainer` | 通知容器 | 全局放置，配合 `toast` 单例使用   |
 
-#### 弹层
+##### 弹层
 
 | 组件      | 描述   | 主要属性                                                |
 | --------- | ------ | ------------------------------------------------------- |
@@ -222,7 +236,7 @@ components/
 | `Confirm` | 确认框 | `open`, `title`, `message`, `variant`, `onconfirm`      |
 | `Popover` | 弹出层 | `open`, `position`, `trigger`, `offset`, `portal`       |
 
-#### 数据展示
+##### 数据展示
 
 | 组件        | 描述     | 主要属性                                 |
 | ----------- | -------- | ---------------------------------------- |
@@ -231,7 +245,7 @@ components/
 | `Accordion` | 手风琴   | `items: AccordionItem[]`                 |
 | `Timeline`  | 时间线   | `items: TimelineItem[]`                  |
 
-#### Bits UI headless 交互
+##### Bits UI headless 交互
 
 | 组件         | 描述                        | 主要属性                                                    |
 | ------------ | --------------------------- | ----------------------------------------------------------- |
@@ -241,7 +255,7 @@ components/
 
 > 日期值使用 `@internationalized/date` 的 `DateValue` / `CalendarDate` 类型。
 
-#### 移动端 / 增强交互
+##### 移动端 / 增强交互
 
 | 组件             | 描述         | 主要属性                                            |
 | ---------------- | ------------ | --------------------------------------------------- |
@@ -253,7 +267,7 @@ components/
 | `SafeArea`       | 安全区域容器 | `top`, `bottom`, `left`, `right`                    |
 | `SwipeCell`      | 滑动操作单元 | `leftActions`, `rightActions`, `threshold`, `onaction` |
 
-#### 导航
+##### 导航
 
 | 组件         | 描述     | 主要属性                                     |
 | ------------ | -------- | -------------------------------------------- |
@@ -264,7 +278,7 @@ components/
 | `Dropdown`   | 下拉菜单 | `items`, `trigger`, `triggerClass`, `position` |
 | `Tooltip`    | 提示     | `content`, `position`, `delay`               |
 
-#### 状态占位
+##### 状态占位
 
 | 组件       | 描述   | 主要属性                              |
 | ---------- | ------ | ------------------------------------- |
@@ -272,22 +286,22 @@ components/
 | `Empty`    | 空状态 | `title`, `description`, `icon`        |
 | `Result`   | 结果页 | `status`, `title`, `description`      |
 
-#### 页面级
+##### 页面级
 
 | 组件         | 描述     | 主要属性                                    |
 | ------------ | -------- | ------------------------------------------- |
 | `PageHeader` | 页面头部 | `title`, `description`，支持 `actions` 插槽 |
 
-### 场景组件 Scenes（36 个）
+#### 场景组件 Scenes（36 个）
 
-#### Guide 引导与帮助（2 个）
+##### Guide 引导与帮助（2 个）
 
 | 组件 | 描述 | 主要属性 |
 | --- | --- | --- |
 | `GuideHost` | 首次邀请、页面导览与帮助弹窗宿主 | `guide`, `locale`, `scope`, `autoStart` |
 | `HelpCenter` | 可独立使用的帮助中心 | `articles`, `tours`, `locale`, `selectedId`, `onstart` |
 
-#### App 应用级（7 个）
+##### App 应用级（7 个）
 
 | 组件             | 描述             | 主要属性           |
 | ---------------- | ---------------- | ------------------ |
@@ -299,13 +313,13 @@ components/
 | `ThemeSelector`  | 完整主题选择面板 | 无需 Props         |
 | `ThemeToggle`    | 明/暗主题切换    | 无需 Props         |
 
-#### IAM 身份认证（10 个）
+##### IAM 身份认证（10 个）
 
 | 组件                 | 描述       | 主要属性                                              |
 | -------------------- | ---------- | ----------------------------------------------------- |
 | `AuthPanel`          | 配置驱动认证页 | `config`, `actions`, `loginHeader/loginFields/loginFooter`, `registerHeader/registerFields/registerFooter` |
 | `AuthShell`          | 认证页布局（居中卡片 / 左右分栏） | `variant`, `title`, `subtitle`, `brandTitle`, `brandText`, `illustration`, `description`, `highlights` |
-| `LoginForm`          | 登录表单   | `loading`, `errors`, `showRememberMe`, `onsubmit`     |
+| `LoginForm`          | 登录表单   | `loading`, `errors`, `showForgotPassword`, `onsubmit`     |
 | `RegisterForm`       | 注册表单   | `loading`, `errors`, `fields`, `onsubmit`             |
 | `ForgotPasswordForm` | 忘记密码   | `mode`, `loading`, `errors`, `onsubmit`               |
 | `ResetPasswordForm`  | 重置密码   | `loading`, `errors`, `showCode`, `onsubmit`           |
@@ -314,7 +328,7 @@ components/
 | `PermGuard`          | 权限守卫   | `permissions`, `mode`, `fallback`                     |
 | `UserProfile`        | 用户资料   | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint`, `onsubmit` |
 
-#### Storage 存储（4 个）
+##### Storage 存储（4 个）
 
 | 组件           | 描述     | 主要属性                                                 |
 | -------------- | -------- | -------------------------------------------------------- |
@@ -325,7 +339,7 @@ components/
 
 上传组件不内置 presign、请求头或 PUT/POST 协议。应用层通过 `uploadHandler(file, { signal, onProgress })` 调用自己的 service，并返回 `{ url?, response? }`；图片和头像上传需要返回可展示的 `url`。未提供 handler 时，`FileUpload` 只选择文件，图片/头像组件只生成本地预览。
 
-#### Crypto 加密展示（3 个）
+##### Crypto 加密展示（3 个）
 
 输入变化立即清空 `encryptedValue`，只有当前输入的成功结果会回填；清空、回调替换和卸载均使旧请求失效。失败显示内置错误提示且密文保持为空；表单应仅在当前密文非空时提交需要加密的输入。
 
@@ -339,7 +353,7 @@ components/
 
 默认算法与 `@h-ai/crypto` 对齐：加密输入使用 `SM4`，哈希展示使用 `SM3`，签名展示使用 `SM2`。
 
-#### AI 文档与表格（4 个）
+##### AI 文档与表格（4 个）
 
 | 组件                     | 描述             | 主要属性 / 能力 |
 | ------------------------ | ---------------- | ---------------- |
@@ -369,7 +383,7 @@ components/
 />
 ```
 
-#### Charts 图表
+##### Charts 图表
 
 `Chart type='line'` 默认透传 LayerChart 原生折线图；需要监控看板常见的“分段线 + 圆点 + 最近点 hover + 竖向参考线”时，使用 `lineVariant='segmented-point'`：
 
@@ -388,7 +402,7 @@ components/
 />
 ```
 
-#### CRUD 场景（5 个）
+##### CRUD 场景（5 个）
 
 | 组件                 | 描述         | 主要属性 / 能力 |
 | -------------------- | ------------ | ---------------- |
@@ -401,10 +415,11 @@ components/
 > `CrudPage` 默认使用 `TableToolbar` 图标弹层工具栏，也可通过 `toolbarStyle='filter-bar'` 切回平铺筛选栏；`detailColumns={['title']}` 可把标题等指定列绑定为详情入口；`toolbarLeading` 用于注入左侧标题或说明，配合 `showHeader={false}` 可避免重复标题；`toolbarActions` 注入右侧业务操作，`card` 插槽可将列表项替换为卡片视图，`tableCell` 可按行和列 key 渲染交互式单元格内容（例如 Tooltip），`sortableColumns` 控制服务端排序字段。过滤工具栏支持 `select`、`boolean`、`number`、`date`、`date-range`、`text`。
 >
 > 页面根容器会占满父级可用高度。表格无论是否有数据都会撑满剩余空间，仅数据区域滚动；表头固定在数据区顶部，分页栏固定在列表卡片底部。
+> 宿主从视口外壳到内容区须逐层传递剩余高度（例如 `flex flex-1 min-h-0 flex-col`），中间包装层不能仅按内容自动计算高度。空表、少量数据和长列表均沿用底部分页。
 >
 > 表格列会优先压缩到 7rem 并截断超长文本；列总宽度仍超过容器时才显示横向滚动条。操作列固定在右侧，横向滚动时保持可见。
 
-#### 错误页场景（1 个）
+##### 错误页场景（1 个）
 
 | 组件        | 描述         | 主要属性 / 能力 |
 | ----------- | ------------ | ---------------- |
@@ -435,9 +450,9 @@ components/
 >
 > `Tabs` 支持惰性页签：`lazy` 开启后未激活过的页签内容不渲染（`children` 提供 `isActivated(key)` 判断），`onactivate(key)` 在页签首次激活时触发一次，适合配合 `createCrudController({ autoLoad: false })` 在首次可见时才加载。
 
-## 使用示例
+### 使用示例
 
-### Toast 通知
+#### Toast 通知
 
 ```svelte
 <script>
@@ -457,7 +472,7 @@ components/
 
 > 已内置 `notifySuccess` / `notifyError` / `notifyInfo` / `notifyWarning` 封装，业务应用无需自建 toast 工具文件：`notifyError(err, fallback?)` 接受 `Error` 或字符串并内置兑底文案，默认成功 3s / 失败 5s。
 
-### Message 消息提示
+#### Message 消息提示
 
 ```svelte
 <script>
@@ -475,7 +490,7 @@ components/
 <MessageContainer />
 ```
 
-### 典型 CRUD 页面
+#### 典型 CRUD 页面
 
 ```svelte
 <script>
@@ -545,7 +560,7 @@ components/
 
 `Modal` 不传 `title` / `header` 时会保留右上角关闭按钮，但不额外渲染整条头部。需要调整圆角时可传 `radius="1.4rem"`，内部下拉等浮层需要越界显示时可传 `bodyOverflow="visible"`。
 
-### 声明式 CRUD 页面（CrudPage）
+#### 声明式 CRUD 页面（CrudPage）
 
 ```svelte
 <script lang='ts'>
@@ -571,7 +586,7 @@ components/
 
 > 抽屉形式可改用 `form={{ variant: 'drawer', drawerWidth: '40rem' }}`；用户拖动后的宽度会覆盖初始宽度并按资源记忆。
 
-### 登录页面
+#### 登录页面
 
 ```svelte
 <script>
@@ -597,7 +612,7 @@ components/
 <LoginForm {loading} {errors} onsubmit={handleLogin} showRegisterLink />
 ```
 
-### PasswordInput 受控模式
+#### PasswordInput 受控模式
 
 ```svelte
 <script>
@@ -614,7 +629,7 @@ components/
 />
 ```
 
-## 样式依赖
+### 样式依赖
 
 组件基于 TailwindCSS v4 + DaisyUI。应用层 `app.css` 需要以下配置：
 
@@ -653,7 +668,7 @@ components/
 </div>
 ```
 
-### 图标
+#### 图标
 
 组件使用 Iconify (Tabler Icons)：
 
@@ -668,7 +683,7 @@ npm install -D @iconify/tailwind4 @iconify-json/tabler
 }
 ```
 
-### 主题切换
+#### 主题切换
 
 使用内置的主题工具函数管理 15 个精选 DaisyUI 主题：
 
@@ -712,49 +727,16 @@ const themeBootstrapScript = createThemeBootstrapScript({
 transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstrapScript)
 ```
 
-## 国际化 (i18n)
+### 国际化 (i18n)
 
 @h-ai/ui 采用**组件内置翻译**模式：
 
-- 场景组件（`scenes/`）内置中英文翻译（zh-CN / en-US），开箱即用
+- 场景组件（`scenes/`）内置中英日文翻译（zh-CN / en-US / ja-JP），开箱即用
 - 组件自动响应全局 locale 变化（通过 `@h-ai/core` 同步）
 - 应用层只需处理**页面级文本**，组件内部文本由 @h-ai/ui 统一管理
 - 如需覆盖特定文本，通过 `submitText`、`labels` 等 props 传入
 
-## 配置驱动认证页面
-
-协议支持 `agreements.userAgreementMarkdown` 与 `privacyPolicyMarkdown` 直接从配置加载；YAML 的 `|` 保留 Markdown 段落和换行。弹窗复用安全 MarkdownRenderer，关闭原始 HTML、脚本和代码复制工具。同主题同时提供正文与 URL 时优先正文，URL 可作为额外查看入口；只有 URL 时使用隔离 iframe。
-
-```yaml
-agreements:
-  showOnRegister: true
-  showOnLogin: false
-  userAgreementMarkdown: |
-    # 用户协议
-
-    **账户使用条款**
-
-    - 请妥善保管账户凭据。
-  privacyPolicyMarkdown: |
-    # 隐私政策
-
-    注册资料用于账户管理，会话信息用于身份认证。
-  # 可选 URL；同主题同时配置 Markdown 和 URL 时，弹窗优先显示 Markdown。
-  # userAgreementUrl: https://example.com/terms
-  # privacyPolicyUrl: https://example.com/privacy
-```
-
-
-
-AuthPanel 直接接收 IAM 白名单配置和 actions，内置登录（密码/LDAP/邮件/短信）、注册、找回、重置及协议展示。使用 `config.ui` 配置卡片/分栏、标题、品牌、Logo 和配图。`LoginForm` 提供 methods、onsendotp、otpLength、resendInterval；密码表单接受 passwordPolicy。组件只渲染与交互，网络和 Token 存储通过 actions 注入。认证场景按公开 IAM 错误码显示当前 UI 语言的提示，应用自定义错误保留原文。
-
-AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事件后自动开放输入，避免接管时丢失早到的输入。应用无需额外的就绪适配；E2E 等待控件可编辑，并覆盖客户端脚本延迟加载的场景。
-
-认证链接指向当前完整 URL 时，AuthPanel 只切换场景并阻止重复导航，返回登录后可立即输入。路径、查询串或 hash 不同时交给应用路由处理；Ctrl/Cmd 等修改键点击保留浏览器行为。
-
-[完整 IAM 配置 / IAM configuration](../iam/README.md)
-
-### createLocaleStore
+#### createLocaleStore
 
 用于客户端 locale 状态管理，自动同步到 `@h-ai/core` 全局 locale 管理器：
 
@@ -778,7 +760,9 @@ AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事
 </select>
 ```
 
-### 导出的 i18n 工具
+`@h-ai/ui/i18n` 的 `createLocaleStore` 按“可解析的持久化值 → 完整 navigator.languages（再检查 navigator.language）→ defaultLocale → 支持列表首项”选择语言；首个不支持的候选不触发默认回退。匹配大小写、语言简写及逐级区域/脚本回退，返回 supportedLocales 中的配置代码；同语言多个变体按列表顺序选择。detectBrowserLocale 无实际命中返回 null，不插入框架默认值；空支持列表最终保留调用方默认值。SSR 不读取浏览器候选或修改全局语言。应用若使用 Paraglide，仍需用该项目的 setLocale 同步应用翻译；内置 UI 字典的覆盖范围不因自定义 store 列表而自动增加。
+
+#### 导出的 i18n 工具
 
 ```ts
 import {
@@ -811,10 +795,44 @@ import {
 
 上例的 subscribe 为应用自身的 $state，应用包装 register 动作校验/提交扩展业务数据；如需单独组合表单，使用 `<RegisterForm> {#snippet extraFields()}...{/snippet} </RegisterForm>`。扩展里的按钮须为 `type="button"`，避免误提交。
 
+### 配置驱动认证页面
+
+密码登录只提交 `identifier` 和 `password`；`AuthPanel` 将 `LoginForm` 的 `username` 映射为 `identifier`。会话有效期由服务端 `session.maxAge` / `session.refreshTokenMaxAge` 配置决定，登录表单不提供按次登录的持久会话选项。
+
+协议支持 `agreements.userAgreementMarkdown` 与 `privacyPolicyMarkdown` 直接从配置加载；YAML 的 `|` 保留 Markdown 段落和换行。弹窗复用安全 MarkdownRenderer，关闭原始 HTML、脚本和代码复制工具。同主题同时提供正文与 URL 时优先正文，URL 可作为额外查看入口；只有 URL 时使用隔离 iframe。
+
+```yaml
+agreements:
+  showOnRegister: true
+  showOnLogin: false
+  userAgreementMarkdown: |
+    # 用户协议
+
+    **账户使用条款**
+
+    - 请妥善保管账户凭据。
+  privacyPolicyMarkdown: |
+    # 隐私政策
 
-## 新手引导与帮助中心
+    注册资料用于账户管理，会话信息用于身份认证。
+  # 可选 URL；同主题同时配置 Markdown 和 URL 时，弹窗优先显示 Markdown。
+  # userAgreementUrl: https://example.com/terms
+  # privacyPolicyUrl: https://example.com/privacy
+```
 
-`@h-ai/ui/guide` 提供 `createGuide`、`GuideHost`、`HelpCenter` 和相关类型。无需 init/close；引擎在开始导览时按需加载，浮层复用当前主题。组件内置中英文按钮、进度和错误提示，业务内容使用应用 i18n。
+
+
+AuthPanel 直接接收 IAM 白名单配置和 actions，内置登录（密码/LDAP/邮件/短信）、注册、找回、重置及协议展示。使用 `config.ui` 配置卡片/分栏、标题、品牌、Logo 和配图。`LoginForm` 提供 methods、onsendotp、otpLength、resendInterval；密码表单接受 passwordPolicy。组件只渲染与交互，网络和 Token 存储通过 actions 注入。认证场景按公开 IAM 错误码显示当前 UI 语言的提示，应用自定义错误保留原文。
+
+AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事件后自动开放输入，避免接管时丢失早到的输入。应用无需额外的就绪适配；E2E 等待控件可编辑，并覆盖客户端脚本延迟加载的场景。
+
+认证链接指向当前完整 URL 时，AuthPanel 只切换场景并阻止重复导航，返回登录后可立即输入。路径、查询串或 hash 不同时交给应用路由处理；Ctrl/Cmd 等修改键点击保留浏览器行为。
+
+[完整 IAM 配置 / IAM configuration](../iam/README.md)
+
+### 新手引导与帮助中心
+
+`@h-ai/ui/guide` 提供 `createGuide`、`GuideHost`、`HelpCenter` 和相关类型。无需 init/close；引擎在开始导览时按需加载，浮层复用当前主题。组件内置中英日文按钮、进度和错误提示，业务内容使用应用 i18n。
 
 同一入口的 `resolveGuideText(text?)` 可解析字符串或 i18n 回调；宿主组件已自动解析文案。
 
@@ -865,7 +883,7 @@ import {
 
 admin-console 示例和 CLI fullstack Web/App/Desktop 默认包含帮助入口、首次邀请及个人资料导览。完整配置和验证场景见 [引导指南](../cli/templates/skills/hai-ui/guide.md)。
 
-## 其他导出
+### 其他导出
 
 ```ts
 // 类型
@@ -881,3 +899,35 @@ import { cn, generateId, getSizeClass, getVariantClass } from '@h-ai/ui'
 // Toast 单例
 import { toast } from '@h-ai/ui'
 ```
+
+
+组件子路径只开放 package.exports 明确列出的 barrel，例如 `@h-ai/ui/components/primitives/index`；不开放任意组件实现或内部存储辅助函数。宿主剪贴板注册仍是公开能力。
+
+### 请求语言隔离
+
+Node 请求与 SSR 使用 `core.i18n.runWithLocale(locale, () => handleRequest())`；SvelteKit 可使用 `kit.i18n.runWithLocale(locale, () => resolve(event))`，serv 自动按请求头建立上下文。异步子任务继承请求语言，优先级为显式 `MessageOptions.locale`、请求语言、进程启动默认语言。`setGlobalLocale` 在请求上下文中只更新当前请求；上下文外仅用于启动默认值，不能在请求 hook 中调用它修改默认值。
+
+浏览器继续使用应用级 `setGlobalLocale` / `createLocaleStore`。SSR 的 UI store 初始化和 setter 只修改自身状态，不写全局语言；UI 消息从请求上下文读取。`runWithLocale` 仅支持 Node 入口，浏览器通过显式 locale 或应用状态翻译。
+
+## 输入约束与 HTTP 能力
+
+存储 key 按 UTF-8 最多 1024 字节，并拒绝绝对路径、反斜线、控制字符及点路径段；公开 HTTP 批量删除每次 1–1000 项。`@h-ai/storage/schemas` 提供浏览器安全的共同规则。预签名有效期为整数 1–604800 秒（Node 默认 3600，HTTP 默认 900）；HTTP 上传仅接受 key/contentType/expiresIn，不支持 contentLength/maxSize/metadata/checksum。无效输入返回 HTTP 400，typed client 映射 VALIDATION_FAILED。FileUpload 的大小/类型限制仅为前端体验，实际对象须由应用服务端复核。Node 流式读写/checksum/条件写等没有默认 HTTP 端点。完整映射与授权边界见 [存储 API 能力](../storage/README.md#存储输入约束与跨端能力)。
+
+## 开发测试
+
+```sh
+pnpm --filter @h-ai/ui typecheck
+pnpm --filter @h-ai/ui lint
+pnpm --filter @h-ai/ui build
+pnpm --filter @h-ai/ui test
+```
+
+## 设计与交互验收
+
+页面设计使用 [hai-ui-design](../cli/templates/skills/hai-ui-design/SKILL.md)，组件实现使用 [hai-ui](../cli/templates/skills/hai-ui/SKILL.md)，真实界面走查使用 [hai-ui-review](../cli/templates/skills/hai-ui-review/SKILL.md)。[设计约定](../../.agents/instructions/ui-design.md) 说明布局、状态和示例。
+
+Tabs 支持方向键/Home/End、禁用项跳过和单一 Tab 入口；表格提供排序与加载状态和行键盘操作；分页导航/输入名称跟随语言，外部页码同步跳页输入；工具栏弹层管理焦点，视图按钮提供选中状态。Empty/Alert 支持长内容换行。theme.css 引入共享 tokens，焦点跟随当前主题，global.css 响应减少动态效果。应用仍需接入实际筛选、排序、分页与失败恢复。
+
+## 许可证
+
+Apache-2.0

package/dist/components/compounds/Accordion.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component Accordion
   =============================================================================
   @h-ai/ui - Accordion 组件
   =============================================================================
@@ -7,6 +8,16 @@
   使用 Svelte 5 Runes ($props, $state, $derived)
   使用 DaisyUI collapse 类
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Accordion } from '@h-ai/ui'
+  const props: ComponentProps<typeof Accordion> = { items: [{ id: 'intro', title: '简介', content: '操作说明' }], value: 'intro' }
+  const component = mount(Accordion, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 
 <script lang='ts'>
@@ -17,6 +28,19 @@
   import ToggleCheckbox from '../primitives/ToggleCheckbox.svelte'
   import ToggleRadio from '../primitives/ToggleRadio.svelte'
 
+  /**
+   * Accordion 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { Accordion } from '@h-ai/ui'
+   * const props: ComponentProps<typeof Accordion> = { items: [{ id: 'intro', title: '简介', content: '操作说明' }], value: 'intro' }
+   * const component = mount(Accordion, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 折叠项数据 */
     items: AccordionItem[]

package/dist/components/compounds/Accordion.svelte.d.ts

@@ -1,6 +1,19 @@
 import type { Snippet } from 'svelte';
 import type { DataAttributes } from '../../types.js';
 import type { AccordionItem } from './accordion-types.js';
+/**
+ * Accordion 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Accordion } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Accordion> = { items: [{ id: 'intro', title: '简介', content: '操作说明' }], value: 'intro' }
+ * const component = mount(Accordion, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     /** 折叠项数据 */
     items: AccordionItem[];
@@ -22,6 +35,27 @@ interface Props {
     children?: Snippet<[AccordionItem]>;
 }
 type $$ComponentProps = Props & DataAttributes;
+/**
+ * Accordion
+ * =============================================================================
+ * @h-ai/ui - Accordion 组件
+ * =============================================================================
+ * 手风琴/折叠面板组件，支持单选/多选模式、多种样式变体
+ *
+ * 使用 Svelte 5 Runes ($props, $state, $derived)
+ * 使用 DaisyUI collapse 类
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Accordion } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Accordion> = { items: [{ id: 'intro', title: '简介', content: '操作说明' }], value: 'intro' }
+ * const component = mount(Accordion, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const Accordion: import("svelte").Component<$$ComponentProps, {}, "value">;
 type Accordion = ReturnType<typeof Accordion>;
 export default Accordion;

package/dist/components/compounds/ActionSheet.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component ActionSheet
   @h-ai/ui — ActionSheet（底部操作菜单）
 
   用法：
@@ -11,6 +12,16 @@
     onselect={(id) => handleAction(id)}
     onclose={() => showActions = false}
   />
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { ActionSheet } from '@h-ai/ui'
+  const props: ComponentProps<typeof ActionSheet> = { open: true, items: [{ id: 'remove', label: '删除', destructive: true }] }
+  const component = mount(ActionSheet, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../types.js'
@@ -20,6 +31,19 @@
   // eslint-disable-next-line no-import-assign -- type re-export
   export type { ActionSheetItem }
 
+  /**
+   * ActionSheet 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { ActionSheet } from '@h-ai/ui'
+   * const props: ComponentProps<typeof ActionSheet> = { open: true, items: [{ id: 'remove', label: '删除', destructive: true }] }
+   * const component = mount(ActionSheet, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 是否显示 */
     open?: boolean