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

package/README.en.md

@@ -6,13 +6,15 @@
 
 ## Introduction
 
+Built-in messages support `zh-CN`, `en-US` and `ja-JP`; the language selector offers all three by default.
+
 A cross-platform Svelte 5 Runes component library with DaisyUI v5 + Tailwind CSS v4 styling and Bits UI v2 headless interactions. Includes built-in i18n (zh-CN / en-US) and 15 curated DaisyUI themes.
 
 ## Core features
 
 - Forms, tables, dialogs, navigation, charts and application components.
 - Authentication, CRUD, AI content, onboarding and a help center.
-- Svelte 5, themes, responsive layouts and Chinese/English component messages.
+- Svelte 5, themes, responsive layouts and Chinese/English/Japanese component messages.
 
 ## Getting started
 
@@ -197,7 +199,7 @@ For `BareInput` with `type="file"`, read `event.currentTarget.files` in `onchang
 
 Labels connect to nested UI controls automatically; use `<FormField for="control-id">` for explicit IDs or native controls. Errors and hints use `aria-describedby`, invalid controls use `aria-invalid`, and field errors appear once. `label` / `error` / `hint` accept strings or deferred translation functions.
 
-`Input`, `Textarea`, `Select` and `PasswordInput` provide Chinese/English native validation messages. `validationMessage` overrides failures without keeping valid input invalid. Sync locale with the UI `setGlobalLocale` / `createLocaleStore` to update visible validation errors immediately. `Textarea` supports `minlength` / `maxlength`; `Select` supports `name`, required validation and FormData serialization.
+`Input`, `Textarea`, `Select` and `PasswordInput` provide Chinese/English/Japanese native validation messages. `validationMessage` overrides failures without keeping valid input invalid. Sync locale with the UI `setGlobalLocale` / `createLocaleStore` to update visible validation errors immediately. `Textarea` supports `minlength` / `maxlength`; `Select` supports `name`, required validation and FormData serialization.
 
 Client validation appears on the first blur and updates as invalid input is corrected. Untouched fields are validated on submit. CRUD create/edit forms share this behavior, honor custom messages and reset validation when reopened. `Select` validates when focus leaves both its trigger and options. `PasswordInput.minLength` enforces length and informs strength; omitting it leaves login password length unrestricted while strength uses an eight-character baseline.
 
@@ -317,7 +319,7 @@ Client validation appears on the first blur and updates as invalid input is corr
 | -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
 | `AuthPanel`          | Configuration driven authentication | `config`, `actions`, `loginHeader/loginFields/loginFooter`, `registerHeader/registerFields/registerFooter` |
 | `AuthShell`          | Auth page layout (centered card / split columns) | `variant`, `title`, `subtitle`, `brandTitle`, `brandText`, `illustration`, `description`, `highlights` |
-| `LoginForm`          | Login form                                       | `loading`, `errors`, `showRememberMe`, `onsubmit`                                                      |
+| `LoginForm`          | Login form                                       | `loading`, `errors`, `showForgotPassword`, `onsubmit`                                                      |
 | `RegisterForm`       | Registration form                                | `loading`, `errors`, `fields`, `onsubmit`                                                              |
 | `ForgotPasswordForm` | Forgot password                                  | `mode`, `loading`, `errors`, `onsubmit`                                                                |
 | `ResetPasswordForm`  | Reset password                                   | `loading`, `errors`, `showCode`, `onsubmit`                                                            |
@@ -414,6 +416,7 @@ Defaults match `@h-ai/crypto`: `SM4` for encrypted inputs, `SM3` for hashes, and
 > `CrudPage` defaults to the `TableToolbar` icon/popover toolbar; use `toolbarStyle='filter-bar'` for a flat filter bar. `detailColumns={['title']}` makes specified columns open details. `toolbarLeading` injects left-side titles/descriptions; `showHeader={false}` avoids duplicate titles. `toolbarActions` adds right-side actions, `card` replaces rows with cards, `tableCell` renders interactive cells by row/column key (such as Tooltip), and `sortableColumns` controls server sorting fields. Filters support `select`, `boolean`, `number`, `date`, `date-range`, and `text`.
 >
 > The page fills available parent height. Tables fill remaining space even without data; only the data area scrolls, with headers fixed at its top and pagination fixed at the list card bottom.
+> Pass remaining height through every host container, for example with `flex flex-1 min-h-0 flex-col`, from the viewport shell to the content area. Intermediate wrappers must not size only to their content. Pagination stays at the bottom for empty, short and scrolling lists.
 >
 > Columns first shrink to 7rem and truncate long text; horizontal scrolling appears only if total width still exceeds the container. The action column stays fixed on the right.
 
@@ -729,7 +732,7 @@ transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstr
 
 @h-ai/ui uses **built-in component translations**:
 
-- Scene components (`scenes/`) include Chinese/English translations (zh-CN / en-US) out of the box.
+- Scene components (`scenes/`) include Chinese/English/Japanese translations (zh-CN / en-US / ja-JP) out of the box.
 - Components respond automatically to global locale changes, synchronized through `@h-ai/core`.
 - Applications handle **page text** only; @h-ai/ui manages internal component text.
 - Override specific text with props such as `submitText` or `labels`.
@@ -758,6 +761,8 @@ Client locale state management, automatically synchronized with the `@h-ai/core`
 </select>
 ```
 
+`createLocaleStore` from `@h-ai/ui/i18n` selects a resolvable saved locale, then the complete navigator.languages list (followed by navigator.language), then defaultLocale and the first supported entry. An unsupported candidate never triggers an early default. Matching handles case, language shorthand and progressively less specific region/script tags, returning the configured code. Same-language variants follow supportedLocales order. detectBrowserLocale returns null without an actual match; an empty supported list ultimately keeps the caller default. SSR neither reads browser candidates nor changes global locale. Paraglide applications must still synchronize their own setLocale; custom store entries do not add built-in UI dictionaries.
+
 #### Exported i18n utilities
 
 ```ts
@@ -776,6 +781,8 @@ import {
 
 ### Configuration driven authentication
 
+Password login submits only `identifier` and `password`; `AuthPanel` maps the `LoginForm` field `username` to `identifier`. Server settings `session.maxAge` / `session.refreshTokenMaxAge` control session lifetimes. The login form has no per-login persistent-session option.
+
 Agreement content can be configured as `agreements.userAgreementMarkdown` and `privacyPolicyMarkdown` using YAML `|`. The modal safely renders configured Markdown and prefers it over the URL of the same agreement. URL-only content stays in a sandboxed iframe.
 
 ```yaml
@@ -809,7 +816,7 @@ When an authentication link points to the current complete URL, AuthPanel switch
 
 ### Onboarding and help center
 
-Import `createGuide`, `GuideHost` and `HelpCenter` from `@h-ai/ui/guide`. No init/close is required. The tour engine loads when a tour starts; controls follow the current theme and include Chinese/English translations. Business text uses application i18n callbacks.
+Import `createGuide`, `GuideHost` and `HelpCenter` from `@h-ai/ui/guide`. No init/close is required. The tour engine loads when a tour starts; controls follow the current theme and include Chinese/English/Japanese translations. Business text uses application i18n callbacks.
 
 The same entry exports `resolveGuideText(text?)` to evaluate strings or i18n callbacks; host components resolve text automatically.
 
@@ -890,6 +897,19 @@ Agreements open in a Modal and preserve form input. Pages must allow iframe embe
 </AuthPanel>
 ```
 
+
+Component subpaths expose only explicit barrels in package.exports, such as `@h-ai/ui/components/primitives/index`. Component internals and storage helpers stay private; host clipboard registration remains public.
+
+### Request locale isolation
+
+Wrap Node requests and SSR in `core.i18n.runWithLocale(locale, () => handleRequest())`. SvelteKit can use `kit.i18n.runWithLocale(locale, () => resolve(event))`; serv creates the scope automatically from request headers. Async descendants inherit it. Explicit `MessageOptions.locale` takes precedence over the request locale and the startup default. Within a scope, `setGlobalLocale` only changes that request; outside a scope it configures the startup default and must not be called by request hooks.
+
+Browsers keep application-level `setGlobalLocale` / `createLocaleStore`. During SSR, UI store initialization and setters only update the store; messages read the request scope. `runWithLocale` requires the Node entry; browser translations use explicit locale options or application state.
+
+## Input limits and HTTP capabilities
+
+Object keys are limited to 1024 UTF-8 bytes and reject absolute paths, backslashes, control characters and dot segments. Each public HTTP batch delete accepts 1–1000 entries. `@h-ai/storage/schemas` exposes the shared browser-safe rules. Presign expiry is an integer from 1 to 604800 seconds (Node default 3600, HTTP default 900). Upload signing accepts only key/contentType/expiresIn; contentLength/maxSize/metadata/checksum are unsupported. Invalid input returns HTTP 400 and the typed client maps it to VALIDATION_FAILED. FileUpload limits guide file selection; applications must validate actual objects on the server. Node streaming/checksum/conditional-write options have no default HTTP endpoints. See the [capability and authorization matrix (Chinese)](../storage/README.md#存储输入约束与跨端能力).
+
 ## Development and testing
 
 ```sh
@@ -899,6 +919,12 @@ pnpm --filter @h-ai/ui build
 pnpm --filter @h-ai/ui test
 ```
 
+## Design and interaction acceptance
+
+Use [hai-ui-design](../cli/templates/skills/hai-ui-design/SKILL.md) for page decisions, [hai-ui](../cli/templates/skills/hai-ui/SKILL.md) for implementation, and [hai-ui-review](../cli/templates/skills/hai-ui-review/SKILL.md) for rendered UI review. See the [shared design guidance](../../.agents/instructions/ui-design.md).
+
+Tabs support arrow/Home/End navigation, disabled items and one Tab stop. Tables expose sort/loading state and keyboard row activation. Pagination labels follow locale and external page changes update the jump input. Toolbar panels manage focus and view buttons expose selection. Empty/Alert wrap long content. theme.css imports shared tokens; focus follows the current theme and global.css respects reduced motion. Applications still implement filtering, sorting, paging and recovery.
+
 ## License
 
 Apache-2.0

package/README.ja.md

@@ -6,13 +6,15 @@
 
 ## 概要
 
+内蔵メッセージは `zh-CN`、`en-US`、`ja-JP` に対応し、言語セレクターは既定で3言語を表示します。
+
 Svelte 5 Runes のクロスプラットフォーム UI ライブラリーです。DaisyUI v5 + Tailwind CSS v4 のスタイル、Bits UI v2 のヘッドレス UI、内蔵 i18n（zh-CN / en-US）、15 種類の厳選テーマを提供します。
 
 ## 主な機能
 
 - フォーム、テーブル、ダイアログ、ナビゲーション、チャートなどの部品。
 - 認証、CRUD、AI コンテンツ、操作ガイド、ヘルプセンター。
-- Svelte 5、テーマ、レスポンシブ表示、中国語・英語のコンポーネント文言。
+- Svelte 5、テーマ、レスポンシブ表示、中国語・英語・日本語のコンポーネント文言。
 
 ## 使い始める
 
@@ -197,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文字を基準にします。
 
@@ -317,7 +319,7 @@ components/
 | -------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------ |
 | `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`                                                            |
@@ -414,6 +416,7 @@ 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 まで縮小し長文を切り詰め、総幅が容器を超える場合のみ横スクロールを出します。操作列は右に固定し、横スクロール中も表示します。
 
@@ -729,7 +732,7 @@ transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstr
 
 @h-ai/ui は**コンポーネント内蔵翻訳**を使います：
 
-- 用途別コンポーネント（`scenes/`）は中国語・英語（zh-CN / en-US）を内蔵し、そのまま使えます。
+- 用途別コンポーネント（`scenes/`）は中国語・英語・日本語（zh-CN / en-US / ja-JP）を内蔵し、そのまま使えます。
 - `@h-ai/core` と同期した全体 locale の変更へ自動応答します。
 - アプリは**ページ単位の文言**のみを扱い、内部テキストは @h-ai/ui が管理します。
 - 個別文言の変更は `submitText`・`labels` などの props で指定。
@@ -758,6 +761,8 @@ transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstr
 </select>
 ```
 
+`@h-ai/ui/i18n` の createLocaleStore は、解決できる保存値、navigator.languages 全体（その後 navigator.language）、defaultLocale、対応一覧の先頭の順で選択します。未対応の最初の候補で既定値に戻しません。大小文字、言語略称、地域・スクリプトの段階的フォールバックを照合し、設定済みのコードを返します。同じ言語の複数候補は supportedLocales 順です。実際の一致がなければ detectBrowserLocale は null、空の対応一覧では最終的に呼出側の既定値を返します。SSR はブラウザー候補を読まず全体の言語を変更しません。Paraglide アプリは独自の setLocale 同期が必要で、対応一覧の追加だけでは UI 内蔵辞書は増えません。
+
 #### エクスポートされる i18n ツール
 
 ```ts
@@ -776,6 +781,8 @@ import {
 
 ### 設定による認証画面
 
+パスワードログインの送信項目は `identifier` と `password` のみです。`AuthPanel` は `LoginForm` の `username` を `identifier` に変換します。有効期間はサーバーの `session.maxAge` / `session.refreshTokenMaxAge` で設定し、フォームにログインごとの永続セッション選択肢はありません。
+
 YAML の `|` で `agreements.userAgreementMarkdown` と `privacyPolicyMarkdown` を設定できます。Modal は本文を安全に描画し、同じ規約の URL より本文を優先します。URL のみの場合は隔離 iframe を使用します。
 
 ```yaml
@@ -809,7 +816,7 @@ AuthPanel は SSR 中のフォーム操作を無効にし、クライアント
 
 ### 初回ガイドとヘルプセンター
 
-`@h-ai/ui/guide` から `createGuide`、`GuideHost`、`HelpCenter` をインポートします。init/close は不要です。ガイド開始時にエンジンを読み込み、既存テーマと中国語・英語の共通文言を使用します。業務内容はアプリの翻訳関数を使います。
+`@h-ai/ui/guide` から `createGuide`、`GuideHost`、`HelpCenter` をインポートします。init/close は不要です。ガイド開始時にエンジンを読み込み、既存テーマと中国語・英語・日本語の共通文言を使用します。業務内容はアプリの翻訳関数を使います。
 
 同じ入口の `resolveGuideText(text?)` は文字列や i18n コールバックを評価します。ホストコンポーネントは文言を自動で解析します。
 
@@ -890,6 +897,19 @@ import { toast } from '@h-ai/ui'
 </AuthPanel>
 ```
 
+
+コンポーネントのサブパスは 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 は自身の状態のみ変更し、メッセージはリクエストコンテキストを参照します。`runWithLocale` は Node 入口専用です。
+
+## 入力制約と HTTP 機能
+
+キーは UTF-8 で最大 1024 バイトで、絶対パス、バックスラッシュ、制御文字、ドットセグメントを拒否します。公開 HTTP 一括削除は一度に 1–1000 件です。共通規則はブラウザー対応の `@h-ai/storage/schemas` から参照できます。署名有効期限は整数 1–604800 秒（Node 既定 3600、HTTP 既定 900）。アップロード署名の入力は key/contentType/expiresIn のみで、contentLength/maxSize/metadata/checksum は未対応です。不正入力は HTTP 400、typed client では VALIDATION_FAILED です。FileUpload の制限は選択時の補助であり、実際のオブジェクトはサーバーで検証してください。Node のストリーム/checksum/条件付き書き込みには既定の HTTP エンドポイントがありません。[機能と認可の対応表（中国語）](../storage/README.md#存储输入约束与跨端能力)を参照してください。
+
 ## 開発とテスト
 
 ```sh
@@ -899,6 +919,12 @@ 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/README.md

@@ -6,13 +6,15 @@
 
 ## 简介
 
+内置中英日文消息（`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、主题切换、响应式布局及中英文组件文案。
+- Svelte 5、主题切换、响应式布局及中英日文组件文案。
 
 ## 使用入门
 
@@ -197,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 位为基准。
 
@@ -317,7 +319,7 @@ components/
 | -------------------- | ---------- | ----------------------------------------------------- |
 | `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`           |
@@ -413,6 +415,7 @@ 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 并截断超长文本；列总宽度仍超过容器时才显示横向滚动条。操作列固定在右侧，横向滚动时保持可见。
 
@@ -728,44 +731,11 @@ transformPageChunk: ({ html }) => html.replace('%theme_bootstrap%', themeBootstr
 
 @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
 
 用于客户端 locale 状态管理，自动同步到 `@h-ai/core` 全局 locale 管理器：
@@ -790,6 +760,8 @@ AuthPanel 在 SSR 阶段禁用原生表单控件，客户端挂载并绑定事
 </select>
 ```
 
+`@h-ai/ui/i18n` 的 `createLocaleStore` 按“可解析的持久化值 → 完整 navigator.languages（再检查 navigator.language）→ defaultLocale → 支持列表首项”选择语言；首个不支持的候选不触发默认回退。匹配大小写、语言简写及逐级区域/脚本回退，返回 supportedLocales 中的配置代码；同语言多个变体按列表顺序选择。detectBrowserLocale 无实际命中返回 null，不插入框架默认值；空支持列表最终保留调用方默认值。SSR 不读取浏览器候选或修改全局语言。应用若使用 Paraglide，仍需用该项目的 setLocale 同步应用翻译；内置 UI 字典的覆盖范围不因自定义 store 列表而自动增加。
+
 #### 导出的 i18n 工具
 
 ```ts
@@ -823,9 +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
+```
+
+
+
+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。
+`@h-ai/ui/guide` 提供 `createGuide`、`GuideHost`、`HelpCenter` 和相关类型。无需 init/close；引擎在开始导览时按需加载，浮层复用当前主题。组件内置中英日文按钮、进度和错误提示，业务内容使用应用 i18n。
 
 同一入口的 `resolveGuideText(text?)` 可解析字符串或 i18n 回调；宿主组件已自动解析文案。
 
@@ -893,6 +900,19 @@ import { cn, generateId, getSizeClass, getVariantClass } from '@h-ai/ui'
 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
@@ -902,6 +922,12 @@ 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

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

@@ -1,5 +1,18 @@
 import type { DataAttributes } from '../../types.js';
 import type { ActionSheetItem } from './action-sheet-types.js';
+/**
+ * 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;
@@ -17,6 +30,31 @@ interface Props {
     class?: string;
 }
 type $$ComponentProps = Props & DataAttributes;
+/**
+ * ActionSheet
+ * @h-ai/ui — ActionSheet（底部操作菜单）
+ *
+ * 用法：
+ * <ActionSheet
+ *   open={showActions}
+ *   items={[
+ *     { id: 'edit', label: '编辑' },
+ *     { id: 'delete', label: '删除', destructive: true },
+ *   ]}
+ *   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)
+ * ```
+ */
 declare const ActionSheet: import("svelte").Component<$$ComponentProps, {
     ActionSheetItem: typeof ActionSheetItem;
 }, "">;

package/dist/components/compounds/Alert.svelte

@@ -1,6 +1,16 @@
 <!--
   @component Alert
   警告框组件，使用 tabler icon 替代 emoji，更精致。
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Alert } from '@h-ai/ui'
+  const props: ComponentProps<typeof Alert> = { title: '保存成功', variant: 'success', children: createRawSnippet(() => ({ render: () => "<span>操作已经完成。</span>" })) }
+  const component = mount(Alert, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { AlertProps, DataAttributes } from '../../types.js'
@@ -24,6 +34,7 @@
   const alertClass = $derived(
     cn(
       'alert',
+      'flex items-start gap-3',
       getAlertVariantClass(variant),
       className,
     ),
@@ -45,21 +56,21 @@
 
 {#if visible}
   <div {...dataAttributes} class={alertClass} role='alert'>
-    <span class='{iconMap[variant] ?? iconMap.info} size-5 shrink-0'></span>
+    <span class='{iconMap[variant] ?? iconMap.info} mt-0.5 size-5 shrink-0' aria-hidden='true'></span>
 
-    <div>
+    <div class='min-w-0 flex-1 [overflow-wrap:anywhere]'>
       {#if title}
         <h3 class='font-semibold text-sm'>{title}</h3>
       {/if}
       {#if children}
-        <div class='text-sm'>
+        <div class='text-sm leading-relaxed'>
           {@render children()}
         </div>
       {/if}
     </div>
 
     {#if dismissible}
-      <IconButton size='sm' variant='ghost' label={uiM('common_close')} onclick={handleClose}>
+      <IconButton size='sm' variant='ghost' class='shrink-0' label={uiM('common_close')} onclick={handleClose}>
         <span class='icon-[tabler--x] size-4'></span>
       </IconButton>
     {/if}