@aithe/aithe-ui 26.2.3 → 26.3.2

package/docs/api/form/autoform-item.md

@@ -0,0 +1,115 @@
+# AitheAutoformItem / AitheAutoformItem 自动表单项
+
+> JSON-driven auto form item with three-section layout (header / control / footer) and built-in validation. Supports dependency rules for dynamic visibility, disabled state, and options.
+> JSON 驱动的自动表单项，三段式布局（头部 / 控件 / 底部），内置校验。支持依赖联动规则动态控制可见性、禁用状态和选项。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                           | Description (CN)   |
+| --------- | ------------------------------------------ | ------------------ |
+| (default) | Default slot for the form control element. | 表单控件元素内容。 |
+
+## Properties / 属性
+
+| Name               | Type                      | Default   | Description (EN)                                                                                                                                                | Description (CN)           |
+| ------------------ | ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| name               | `string`                  | `''`      | Field unique identifier.                                                                                                                                        | 字段唯一标识。             |
+| type               | `AutoformItemType`        | `'input'` | Control type: input \| textarea \| select \| radio \| checkbox \| switch \| number \| slider \| rate \| color-picker \| date-picker \| time-picker \| combobox. | 控件类型。                 |
+| label              | `string`                  | `''`      | Label text.                                                                                                                                                     | 标签文本。                 |
+| icon               | `string`                  | `''`      | Icon name displayed before the label.                                                                                                                           | 标签前显示的图标名称。     |
+| tooltip            | `string`                  | `''`      | Tooltip text shown on hover.                                                                                                                                    | 悬停提示文本。             |
+| description        | `string`                  | `''`      | Description text below the control.                                                                                                                             | 控件下方的说明文字。       |
+| dft                | `string`                  | `''`      | Default value.                                                                                                                                                  | 缺省值。                   |
+| placeholder        | `string`                  | `''`      | Placeholder text.                                                                                                                                               | 占位提示文本。             |
+| disabled           | `boolean`                 | `false`   | Whether the field is disabled.                                                                                                                                  | 是否禁用。                 |
+| required           | `boolean`                 | `false`   | Whether the field is required.                                                                                                                                  | 是否必填。                 |
+| pattern            | `string`                  | `''`      | Validation regex pattern string.                                                                                                                                | 校验正则表达式字符串。     |
+| message            | `string`                  | `''`      | Validation failure message.                                                                                                                                     | 校验失败提示语。           |
+| options            | `FormItemOption[]`        | `[]`      | Options for select/radio/checkbox.                                                                                                                              | 选择类控件的选项。         |
+| value              | `string`                  | `''`      | Current field value.                                                                                                                                            | 当前字段值。               |
+| inputType          | `string`                  | `'text'`  | Input type attribute for type="input". When set to `password`, a suffix icon button (`eye`/`eyeOff`) is rendered to toggle between masked and plaintext display. | input 控件的 type 属性。设为 `password` 时，后缀渲染图标按钮（`eye`/`eyeOff`）用于在密文与明文之间切换。 |
+| min                | `string`                  | `''`      | Minimum value for number/slider.                                                                                                                                | 数字/滑块最小值。          |
+| max                | `string`                  | `''`      | Maximum value for number/slider.                                                                                                                                | 数字/滑块最大值。          |
+| step               | `string`                  | `''`      | Step value for number/slider/rate.                                                                                                                              | 数字/滑块/评分步长。       |
+| rows               | `string`                  | `'3'`     | Number of rows for textarea.                                                                                                                                    | 文本域行数。               |
+| validate-on-change | `boolean`                 | `true`    | Whether to validate on every change.                                                                                                                            | 是否在每次变更时实时校验。 |
+| dependencies       | `string[]`                | `[]`      | Dependency field names.                                                                                                                                         | 依赖字段名称列表。         |
+| rules              | `FormRule[]`              | `[]`      | Dependency rules.                                                                                                                                               | 依赖联动规则。             |
+| dependencyValues   | `Record<string, unknown>` | `{}`      | Current values of dependency fields.                                                                                                                            | 依赖字段的当前值。         |
+
+## Events / 事件
+
+| Name         | Detail                             | Cancelable | Description (EN)                      | Description (CN)   |
+| ------------ | ---------------------------------- | ---------- | ------------------------------------- | ------------------ |
+| aithe-change | `{ name: string, value: unknown }` | No         | Emitted when the field value changes. | 字段值变更时触发。 |
+
+## Methods / 方法
+
+| Name            | Return Type | Description (EN)                                                   | Description (CN)                          |
+| --------------- | ----------- | ------------------------------------------------------------------ | ----------------------------------------- |
+| validate()      | `boolean`   | Validates the field and sets error state. Returns `true` if valid. | 校验字段并设置错误状态，有效返回 `true`。 |
+| clearError()    | `void`      | Clears the validation error.                                       | 清除校验错误。                            |
+| getError()      | `string`    | Returns the current validation error message.                      | 返回当前校验错误消息。                    |
+| getFieldValue() | `unknown`   | Returns the current field value (type-aware).                      | 返回当前字段值（类型感知）。              |
+
+## Properties (Getters) / 只读属性
+
+| Name    | Type      | Description (EN)                                               | Description (CN)                 |
+| ------- | --------- | -------------------------------------------------------------- | -------------------------------- |
+| visible | `boolean` | Whether the field is visible (controlled by dependency rules). | 字段是否可见（由依赖规则控制）。 |
+
+## Examples / 示例
+
+### 基本用法
+
+```html
+<aithe-autoform-item
+  name="email"
+  type="input"
+  label="Email"
+  icon="mail"
+  tooltip="Your work email"
+  description="We will never share your email."
+  required
+></aithe-autoform-item>
+```
+
+### 选择类控件
+
+```html
+<aithe-autoform-item
+  name="country"
+  type="select"
+  label="Country"
+  .options='[{ "id": "cn", "label": "China" }, { "id": "us", "label": "USA" }]'
+></aithe-autoform-item>
+```
+
+### 带校验规则
+
+```html
+<aithe-autoform-item
+  name="phone"
+  type="input"
+  inputType="tel"
+  label="Phone"
+  required
+  pattern="^1[3-9]\d{9}$"
+  message="Please enter a valid phone number"
+></aithe-autoform-item>
+```
+
+### 密码输入（带明文切换）
+
+```html
+<aithe-autoform-item
+  name="password"
+  type="input"
+  inputType="password"
+  label="Password"
+  icon="lock"
+  required
+  placeholder="Enter your password"
+  message="Password is required"
+></aithe-autoform-item>
+```

package/docs/api/form/autoform.md

@@ -7,16 +7,18 @@
 
 | Name      | Description (EN)                                                                                         | Description (CN)                                           |
 | --------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| (default) | Default slot for custom actions below the form items. Replaces the built-in submit button when provided. | 表单项下方的自定义操作区域，传入内容后将替换内置提交按钮。 |
+| (default) | Default slot for custom actions (buttons) below the form items. Use together with `show-submit` to control the built-in submit button. | 表单项下方的自定义操作区域（按钮），配合 `show-submit` 属性控制内置提交按钮的显隐。 |
 
 ## Properties / 属性
 
 | Name               | Type    | Default | Description (EN)                                                                                                                                                                                                  | Description (CN)                                                                                                                                                                               |
 | ------------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| fields             | String  | '[]'    | JSON string of field configurations. Each field supports: name, type, label, icon, tooltip, description, dft, rules (required/pattern/message), placeholder, disabled, options, dependencies, rules (dependency). | 字段配置的 JSON 字符串。每个字段支持：name、type、label、icon、tooltip、description、dft、rules（required/pattern/message）、placeholder、disabled、options、dependencies、rules（依赖联动）。 |
+| fields             | String  | '[]'    | JSON string of field configurations. Each field supports: name, type, label, icon, tooltip, description, dft, rules (required/pattern/message), placeholder, disabled, options, dependencies, rules (dependency), inputType (for type="input", e.g. `password`/`email`/`tel`; `password` renders a visibility toggle). | 字段配置的 JSON 字符串。每个字段支持：name、type、label、icon、tooltip、description、dft、rules（required/pattern/message）、placeholder、disabled、options、dependencies、rules（依赖联动）、inputType（用于 type="input"，如 `password`/`email`/`tel`；`password` 渲染明文切换按钮）。 |
 | submitText         | String  | ''      | Custom submit button label. Falls back to i18n key `form.autoform.submit`.                                                                                                                                        | 自定义提交按钮文本。缺省使用 i18n 键 `form.autoform.submit`。                                                                                                                                  |
 | loading            | Boolean | false   | Whether the form is in a submitting state.                                                                                                                                                                        | 表单是否处于提交中状态。                                                                                                                                                                       |
 | validate-on-change | Boolean | true    | Whether to validate on every field change.                                                                                                                                                                        | 是否在每次字段变更时实时校验。                                                                                                                                                                 |
+| initial-values     | Object / String | {}     | Initial values for form fields, as an object or JSON string. Overrides `dft` for each matching field.                                                                                                             | 表单字段初始值，支持对象或 JSON 字符串，覆盖对应字段的 `dft`。                                                                                                                                |
+| show-submit        | Boolean | true    | Whether to show the built-in submit button. Set to `false` when using custom action slot.                                                                                                                         | 是否显示内置提交按钮，设为 `false` 时使用自定义 slot。                                                                                                                                         |
 
 ## Methods / 方法
 
@@ -25,6 +27,7 @@
 | validate  | —          | boolean                 | Validate all fields and return whether the form is valid.  | 校验所有字段并返回表单是否有效。 |
 | getValues | —          | Record<string, unknown> | Return current values of all fields.                       | 返回所有字段的当前值。           |
 | reset     | —          | void                    | Reset all fields to their default values and clear errors. | 重置所有字段为缺省值并清除错误。 |
+| submit    | —          | void                    | Trigger form validation and submission programmatically. Emits aithe-submit if valid. | 编程触发表单校验和提交，通过后触发 aithe-submit 事件。 |
 
 ## Events / 事件
 
@@ -41,7 +44,7 @@
 | input      | Single-line text input.               | 单行文本输入。         |
 | textarea   | Multi-line text input.                | 多行文本输入。         |
 | number     | Numeric input.                        | 数值输入。             |
-| password   | Password input.                       | 密码输入。             |
+| password   | Password input with a visibility toggle suffix icon.  | 密码输入，后缀图标切换明文显示。 |
 | email      | Email input.                          | 邮箱输入。             |
 | select     | Dropdown selector.                    | 下拉选择器。           |
 | radio      | Radio button group.                   | 单选按钮组。           |
@@ -261,6 +264,7 @@ String values use single or double quotes. Boolean values use `true`/`false`. Nu
   fields='[
     {"name":"username","type":"input","label":"Username","icon":"user","required":true,"message":"Username is required","placeholder":"Enter username"},
     {"name":"email","type":"input","label":"Email","tooltip":"Your work email","required":true,"inputType":"email","pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$","message":"Invalid email","placeholder":"you@company.com"},
+    {"name":"password","type":"input","label":"Password","icon":"lock","required":true,"inputType":"password","placeholder":"Enter your password","message":"Password is required"},
     {"name":"role","type":"select","label":"Role","options":"[{\\"label\\":\\"Admin\\",\\"id\\":\\"admin\\"},{\\"label\\":\\"Editor\\",\\"id\\":\\"editor\\"},{\\"label\\":\\"Viewer\\",\\"id\\":\\"viewer\\"}]","dft":"viewer"},
     {"name":"notifications","type":"switch","label":"Notifications","dft":"true"}
   ]'

package/docs/api/form/combobox.md

@@ -30,15 +30,24 @@
 
 ## Option Fields / 选项字段
 
-| Field | Type | Description (EN) | Description (CN) |
-|-------|------|-------------------|-------------------|
-| label | `string` | Display text. | 显示文本。 |
-| id | `string` | Unique value emitted on select. | 选择时发出的唯一值。 |
-| icon | `string` | Icon name rendered before the label via aithe-icon. | 通过 aithe-icon 在标签前渲染的图标名称。 |
-| variant | AitheVariant | Visual variant / semantic color for the option. | 选项的视觉变体/语义色。 |
+| Field   | Type         | Description (EN)                                                                                                                                       | Description (CN)                                            |
+| ------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| label   | `string`     | Display text.                                                                                                                                         | 显示文本。                                                  |
+| id      | `string`     | Unique value emitted on select.                                                                                                                       | 选择时发出的唯一值。                                        |
+| icon    | `string`     | Icon name rendered before the label via aithe-icon.                                                                                                   | 通过 aithe-icon 在标签前渲染的图标名称。                    |
+| variant | AitheVariant | Visual variant / semantic color for the option.                                                                                                       | 选项的视觉变体/语义色。                                     |
+| group   | `string`     | Group name for grouped rendering. When any option carries a `group` field, all options are aggregated by `group` and rendered under a group header. | 分组名称，用于分组显示。任一选项携带 `group` 字段时，所有选项按 `group` 聚合，每组前置分组标题渲染。 |
+
+## Grouped Rendering / 分组渲染
+
+When any option in `options` carries a `group` field, the combobox automatically switches to grouped rendering mode: options are aggregated by `group` (preserving insertion order), each group is preceded by a `.group-header` title, and options within a group are indented. Options without a `group` field are collected under an untitled section. When no option carries `group`, rendering falls back to the flat list.
+
+当 `options` 中任一选项携带 `group` 字段时，combobox 自动切换到分组渲染模式：选项按 `group` 聚合（保留插入顺序），每组前置 `.group-header` 标题，组内选项缩进显示。未携带 `group` 字段的选项归入无标题分组。无任何 `group` 字段时回退为扁平列表渲染。
 
 ## Examples / 示例
 
+### 基本用法
+
 ```html
 <aithe-combobox
   options='[{"label":"Apple","id":"apple"},{"label":"Banana","id":"banana"}]'
@@ -46,4 +55,15 @@
   icon="search"
   filterable
 ></aithe-combobox>
-```
+```
+
+### 分组选项
+
+```html
+<aithe-combobox
+  title="Preset search"
+  icon="search"
+  placeholder="Search presets"
+  options='[{"label":"A/B Test","id":"ab-test","group":"Analytics","icon":"barChart"},{"label":"Funnel","id":"funnel","group":"Analytics","icon":"filter"},{"label":"Assistant Shell","id":"assistant-shell","group":"Automation","icon":"terminal"},{"label":"Workflow Editor","id":"workflow-editor","group":"Automation","icon":"edit"}]'
+></aithe-combobox>
+```

package/docs/api/form/select.md

@@ -5,46 +5,55 @@
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
+| Name      | Description (EN)                                  | Description (CN)                          |
+| --------- | ------------------------------------------------- | ----------------------------------------- |
 | (default) | Default slot (unused; content driven by options). | 默认插槽（未使用，内容由 options 控制）。 |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| optionsJson | String | '' | JSON string of select options. | 选项的 JSON 字符串。 |
-| options | AitheSelectOption[] | [] | Array of select option objects. Each option supports `icon` and `variant` (AitheVariant) fields. | 选项对象数组。每个选项支持 `icon` 和 `variant`（AitheVariant）字段。 |
-| value | String | '' | Currently selected value. | 当前选中的值。 |
-| title | `string` | `''` | Display title (shown as tooltip). | 显示标题（作为工具提示）。 |
-| icon | `string` | `''` | Icon name to display before the selected value. | 在选中值前显示的图标名称。 |
-| placeholder | String | '请选择' | Placeholder text shown when no value is selected. | 无选中值时的占位文本。 |
-| searchable | Boolean | false | Whether the select supports search/filter. | 是否支持搜索过滤。 |
-| clearable | Boolean | false | Whether the selected value can be cleared. | 是否允许清除选中值。 |
-| disabled | Boolean | false | Whether the select is disabled. | 是否禁用。 |
-| placement | 'bottom-start' \| 'top-start' | 'bottom-start' | Dropdown panel placement. | 下拉面板位置。 |
+| Name        | Type                          | Default        | Description (EN)                                                                                 | Description (CN)                                                     |
+| ----------- | ----------------------------- | -------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| optionsJson | String                        | ''             | JSON string of select options.                                                                   | 选项的 JSON 字符串。                                                 |
+| options     | AitheSelectOption[]           | []             | Array of select option objects. Each option supports `icon` and `variant` (AitheVariant) fields. | 选项对象数组。每个选项支持 `icon` 和 `variant`（AitheVariant）字段。 |
+| value       | String                        | ''             | Currently selected value.                                                                        | 当前选中的值。                                                       |
+| title       | `string`                      | `''`           | Display title (shown as tooltip).                                                                | 显示标题（作为工具提示）。                                           |
+| icon        | `string`                      | `''`           | Icon name to display before the selected value.                                                  | 在选中值前显示的图标名称。                                           |
+| placeholder | String                        | '请选择'       | Placeholder text shown when no value is selected.                                                | 无选中值时的占位文本。                                               |
+| searchable  | Boolean                       | false          | Whether the select supports search/filter.                                                       | 是否支持搜索过滤。                                                   |
+| clearable   | Boolean                       | false          | Whether the selected value can be cleared.                                                       | 是否允许清除选中值。                                                 |
+| disabled    | Boolean                       | false          | Whether the select is disabled.                                                                  | 是否禁用。                                                           |
+| placement   | 'bottom-start' \| 'top-start' | 'bottom-start' | Dropdown panel placement.                                                                        | 下拉面板位置。                                                       |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-change | { option, value } | Emitted when a value is selected. | 选中值变更时触发。 |
-| aithe-clear | — | Emitted when the value is cleared. | 值被清除时触发。 |
-| aithe-open-change | { open } | Emitted when the dropdown opens or closes. | 下拉框开关状态变更时触发。 |
+| Name                  | Detail            | Description (EN)                           | Description (CN)           |
+| --------------------- | ----------------- | ------------------------------------------ | -------------------------- |
+| aithe-change          | { option, value } | Emitted when a value is selected.          | 选中值变更时触发。         |
+| aithe-clear           | —                 | Emitted when the value is cleared.         | 值被清除时触发。           |
+| aithe-dropdown-change | { open }          | Emitted when the dropdown opens or closes. | 下拉框开关状态变更时触发。 |
 
 ## Option Fields / 选项字段
 
-| Field | Type | Description (EN) | Description (CN) |
-|-------|------|-------------------|-------------------|
-| label | `string` | Display text. | 显示文本。 |
-| id | `string` | Unique value emitted on select. | 选择时发出的唯一值。 |
-| disabled | `boolean` | Whether the option is non-interactive. | 是否不可交互。 |
-| description | `string` | Secondary description line. | 二级描述行。 |
-| icon | `string` | Icon name rendered before the label via aithe-icon. | 通过 aithe-icon 在标签前渲染的图标名称。 |
-| variant | AitheVariant | Visual variant / semantic color for the option. | 选项的视觉变体/语义色。 |
+| Field       | Type         | Description (EN)                                                                                                                                       | Description (CN)                                            |
+| ----------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| label       | `string`     | Display text.                                                                                                                                         | 显示文本。                                                  |
+| id          | `string`     | Unique value emitted on select.                                                                                                                       | 选择时发出的唯一值。                                        |
+| disabled    | `boolean`    | Whether the option is non-interactive.                                                                                                                | 是否不可交互。                                              |
+| description | `string`     | Secondary description line.                                                                                                                           | 二级描述行。                                                |
+| icon        | `string`     | Icon name rendered before the label via aithe-icon.                                                                                                   | 通过 aithe-icon 在标签前渲染的图标名称。                    |
+| variant     | AitheVariant | Visual variant / semantic color for the option.                                                                                                       | 选项的视觉变体/语义色。                                     |
+| group       | `string`     | Group name for grouped rendering. When any option carries a `group` field, all options are aggregated by `group` and rendered under a group header. | 分组名称，用于分组显示。任一选项携带 `group` 字段时，所有选项按 `group` 聚合，每组前置分组标题渲染。 |
+
+## Grouped Rendering / 分组渲染
+
+When any option in `options` carries a `group` field, the select automatically switches to grouped rendering mode: options are aggregated by `group` (preserving insertion order), each group is preceded by a `.group-header` title, and options within a group are indented. Options without a `group` field are collected under an untitled section. When no option carries `group`, rendering falls back to the flat list. Keyboard navigation (`activeIndex`) is maintained via a flattened index across groups.
+
+当 `options` 中任一选项携带 `group` 字段时，select 自动切换到分组渲染模式：选项按 `group` 聚合（保留插入顺序），每组前置 `.group-header` 标题，组内选项缩进显示。未携带 `group` 字段的选项归入无标题分组。无任何 `group` 字段时回退为扁平列表渲染。键盘导航（`activeIndex`）通过跨分组的扁平索引维护。
 
 ## Examples / 示例
 
+### 基本用法
+
 ```html
 <aithe-select
   options='[{"id":"a","label":"Option A"},{"id":"b","label":"Option B"}]'
@@ -53,4 +62,17 @@
   searchable
   clearable
 ></aithe-select>
-```
+```
+
+### 分组选项
+
+```html
+<aithe-select
+  title="Region selector"
+  icon="globe"
+  placeholder="Choose a city"
+  clearable
+  searchable
+  options='[{"label":"上海","id":"sh","group":"华东"},{"label":"杭州","id":"hz","group":"华东"},{"label":"北京","id":"bj","group":"华北"},{"label":"天津","id":"tj","group":"华北"},{"label":"广州","id":"gz","group":"华南"},{"label":"深圳","id":"sz","group":"华南"}]'
+></aithe-select>
+```

package/docs/api/framework/log-panel.md

@@ -0,0 +1,46 @@
+# AitheLogPanel / AitheLogPanel 日志面板
+
+> Floating or inline log panel that subscribes to the global `logger` and displays log entries with level filtering, search, copy, and resize support.
+> 浮动或内联日志面板，订阅全局 `logger` 并展示日志条目，支持级别过滤、搜索、复制和拖拽调整高度。
+
+## Properties / 属性
+
+| Name            | Type                    | Default     | Description (EN)                                                                | Description (CN)                                  |
+| --------------- | ----------------------- | ----------- | ------------------------------------------------------------------------------- | ------------------------------------------------- |
+| open            | `boolean`               | `false`     | Whether the panel is expanded.                                                  | 面板是否展开。                                    |
+| panel-placement | `'overlay' \| 'inline'` | `'overlay'` | Placement mode: `overlay` floats at bottom-right; `inline` fills the container. | 放置模式：`overlay` 右下浮动；`inline` 填充容器。 |
+
+## Events / 事件
+
+| Name             | Detail              | Cancelable | Description (EN)                   | Description (CN)      |
+| ---------------- | ------------------- | ---------- | ---------------------------------- | --------------------- |
+| log-panel-toggle | `{ open: boolean }` | No         | Emitted when the panel is toggled. | 面板展开/收起时触发。 |
+
+## CSS Custom Properties / CSS 自定义属性
+
+| Name                       | Default | Description (EN)                    | Description (CN)     |
+| -------------------------- | ------- | ----------------------------------- | -------------------- |
+| `--aithe-log-panel-height` | `200px` | Height of the panel in inline mode. | 内联模式下面板高度。 |
+
+## Examples / 示例
+
+### 浮动模式（默认）
+
+```html
+<aithe-log-panel open></aithe-log-panel>
+```
+
+### 内联模式
+
+```html
+<aithe-log-panel open panel-placement="inline"></aithe-log-panel>
+```
+
+### 监听切换事件
+
+```js
+const panel = document.querySelector('aithe-log-panel');
+panel.addEventListener('log-panel-toggle', (e) => {
+  console.log('Panel open:', e.detail.open);
+});
+```

package/docs/api/framework/sidebar.md

@@ -36,13 +36,13 @@
 | mobile-breakpoint | `number`              | `768`     | Viewport width threshold (px); when ≤ this value, overlay mode is auto-enabled and sidebar collapses. | 移动端断点（像素）；视口宽度 ≤ 此值时自动启用 overlay 并收起。 |
 | expanded-width    | `string`              | `'260px'` | Sidebar width when expanded (CSS value).                                                              | 展开时的侧边栏宽度。                                           |
 | collapsed-width   | `string`              | `'64px'`  | Sidebar width when collapsed (CSS value).                                                             | 收起时的侧边栏宽度。                                           |
-| item-filter       | `AitheSidebarItemFilter \| null` | `null`    | Filter callback for menu items. Return `true` to show, `false` to hide. Useful for permission control. | 菜单项过滤回调。返回 `true` 显示，`false` 隐藏。适用于权限控制。 |
+| item-filter       | `AitheTreeNodeFilter \| null` | 内置默认值    | Filter callback for menu items. Return `true` to show, `false` to hide. Defaults to `(item) => item.hasPermission !== false` — items with `hasPermission: false` are hidden. Useful for permission control. | 菜单项过滤回调。返回 `true` 显示，`false` 隐藏。默认值为 `(item) => item.hasPermission !== false` — 设置 `hasPermission: false` 的项会被隐藏。适用于权限控制。 |
 
 ## Events / 事件
 
 | Name                  | Detail                   | Cancelable | Description (EN)                                                                                        | Description (CN)                                                   |
 | --------------------- | ------------------------ | ---------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| aithe-select          | `{ value: string }`      | No         | Emitted when a menu item is selected.                                                                   | 菜单项选中时发出。                                                 |
+| aithe-select          | `{ value: string, item: AitheTreeNodeMeta }` | No         | Propagated from the inner `<aithe-tree-menu>` (composed event). Sidebar does not re-emit — listen on the sidebar element directly. `value` is the item's `id`, `item` is the full node metadata. | 由内部 `<aithe-tree-menu>` 透传（composed 事件）。sidebar 不重新发射 — 直接监听 sidebar 元素即可。`value` 为项的 `id`，`item` 为完整节点元数据。 |
 | aithe-collapse-change | `{ collapsed: boolean }` | Yes        | Emitted when sidebar collapse state is about to change. Call `preventDefault()` to suppress the toggle. | 侧边栏伸缩状态即将变更时发出。调用 `preventDefault()` 可阻止切换。 |
 
 ## AitheTreeNodeMeta / 树节点元数据
@@ -53,6 +53,7 @@
 | id       | `string`              | Unique identifier.                                                                                                    | 节点唯一标识。                                                             |
 | icon     | `string`              | Icon name (via `aithe-icon`).                                                                                         | 图标名称。                                                                 |
 | disabled | `boolean`             | Whether the node is disabled.                                                                                         | 是否禁用节点。                                                             |
+| hasPermission | `boolean`         | Permission flag. When set to `false`, the item is hidden by the default `itemFilter`.                                 | 权限标记。设为 `false` 时，默认 `itemFilter` 会隐藏该项。                  |
 | intent   | `AitheVariant`        | Visual variant / semantic color.                                                                                      | 视觉变体/语义色。                                                          |
 | children | `AitheTreeNodeMeta[]` | Nested child nodes.                                                                                                   | 嵌套子节点。                                                               |
 | i18n     | `string`              | i18n translation key. When set, `t(i18n, label)` is used to translate the label; `label` serves as the default value. | 国际化翻译键。设置后通过 `t(i18n, label)` 翻译 label，`label` 作为缺省值。 |

package/docs/api/summary.md

@@ -40,8 +40,6 @@ Structural layout primitives for page composition. 页面结构布局基础组
 | [Space](layout/space.md)                 | `<aithe-space>`         | Equal spacing helper for child elements. 等间距辅助组件。            |
 | [Collapse](layout/collapse.md)           | `<aithe-collapse>`      | Accordion / multi-expand collapse container. 手风琴/多展开折叠容器。 |
 | [Collapse Item](layout/collapse-item.md) | `<aithe-collapse-item>` | Single collapsible panel. 单个可折叠面板。                           |
-| [Timeline](data/timeline.md)             | `<aithe-timeline>`      | Timeline container for process records. 时间线容器。                 |
-| [Timeline Item](data/timeline-item.md)   | `<aithe-timeline-item>` | Single timeline node. 时间线节点。                                   |
 | [Affix](layout/affix.md)                 | `<aithe-affix>`         | Sticky wrapper that pins content on scroll. 固定/吸顶包装器。        |
 
 ---
@@ -58,7 +56,7 @@ Application-level layout and routing components for admin-style applications.
 | [Page](framework/page.md)                       | `<aithe-page>`            | Route container that renders the matched page component. 路由容器，渲染匹配到的页面组件。                                  |
 | [Dashboard](framework/dashboard.md)             | `<aithe-dashboard>`       | Drag-and-drop dashboard with grid layout, toolbar, and state persistence. 拖拽式仪表盘，支持格子布局、工具栏和状态持久化。 |
 | [Dashboard Panel](framework/dashboard-panel.md) | `<aithe-dashboard-panel>` | Dashboard panel card with drag, close, maximize and slot content. 仪表盘面板卡片，支持拖拽、关闭、最大化和插槽内容。       |
-
+| [Log Panel](framework/log-panel.md)             | `<aithe-log-panel>`       | Floating/inline log panel with level filtering and search. 浮动/内联日志面板，支持级别过滤和搜索。                         |
 
 ---
 
@@ -82,25 +80,26 @@ Components for site navigation and wayfinding. 站点导航和路径指引组件
 
 Interactive form controls for data entry and selection. 交互式表单控件，用于数据输入和选择。
 
-| Component                                | Tag                      | Description                                                                              |
-| ---------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------- |
-| [Checkbox](form/checkbox.md)             | `<aithe-checkbox>`       | Binary selection control. 二选控件。                                                     |
-| [Checkbox Group](form/checkbox-group.md) | `<aithe-checkbox-group>` | Multi-select group of checkboxes. 多选复选框组。                                         |
-| [Radio](form/radio.md)                   | `<aithe-radio>`          | Single selection control. 单选控件。                                                     |
-| [Radio Group](form/radio-group.md)       | `<aithe-radio-group>`    | Group of mutually exclusive radios. 单选按钮组。                                         |
-| [Select](form/select.md)                 | `<aithe-select>`         | Dropdown single/multi selector. 下拉单选/多选器。                                        |
-| [Switch](form/switch.md)                 | `<aithe-switch>`         | Toggle switch for on/off state. 开关切换控件。                                           |
-| [Color Picker](form/color-picker.md)     | `<aithe-color-picker>`   | Color selection input. 颜色选择器。                                                      |
-| [Combobox](form/combobox.md)             | `<aithe-combobox>`       | Searchable dropdown with free input. 可搜索下拉输入框。                                  |
-| [Date Picker](form/date-picker.md)       | `<aithe-date-picker>`    | Date selection input. 日期选择器。                                                       |
-| [Time Picker](form/time-picker.md)       | `<aithe-time-picker>`    | Time selection input. 时间选择器。                                                       |
-| [Slider](form/slider.md)                 | `<aithe-slider>`         | Range slider for numeric input. 滑块数值输入。                                           |
-| [Rate](form/rate.md)                     | `<aithe-rate>`           | Star rating input. 星级评分输入。                                                        |
-| [Form](form/form.md)                     | `<aithe-form>`           | Form container with validation. 表单容器，支持校验。                                     |
-| [Form Item](form/form-item.md)           | `<aithe-form-item>`      | Form field wrapper with label and validation. 表单字段包装器。                           |
-| [Upload](form/upload.md)                 | `<aithe-upload>`         | File upload control. 文件上传控件。                                                      |
-| [Transfer](form/transfer.md)             | `<aithe-transfer>`       | Dual-list transfer selector. 双栏穿梭选择器。                                            |
-| [Autoform](form/autoform.md)             | `<aithe-autoform>`       | JSON-driven auto-rendering form with validation. JSON 配置驱动的自动渲染表单，支持校验。 |
+| Component                                | Tag                      | Description                                                                                                           |
+| ---------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| [Checkbox](form/checkbox.md)             | `<aithe-checkbox>`       | Binary selection control. 二选控件。                                                                                  |
+| [Checkbox Group](form/checkbox-group.md) | `<aithe-checkbox-group>` | Multi-select group of checkboxes. 多选复选框组。                                                                      |
+| [Radio](form/radio.md)                   | `<aithe-radio>`          | Single selection control. 单选控件。                                                                                  |
+| [Radio Group](form/radio-group.md)       | `<aithe-radio-group>`    | Group of mutually exclusive radios. 单选按钮组。                                                                      |
+| [Select](form/select.md)                 | `<aithe-select>`         | Dropdown single/multi selector. 下拉单选/多选器。                                                                     |
+| [Switch](form/switch.md)                 | `<aithe-switch>`         | Toggle switch for on/off state. 开关切换控件。                                                                        |
+| [Color Picker](form/color-picker.md)     | `<aithe-color-picker>`   | Color selection input. 颜色选择器。                                                                                   |
+| [Combobox](form/combobox.md)             | `<aithe-combobox>`       | Searchable dropdown with free input. 可搜索下拉输入框。                                                               |
+| [Date Picker](form/date-picker.md)       | `<aithe-date-picker>`    | Date selection input. 日期选择器。                                                                                    |
+| [Time Picker](form/time-picker.md)       | `<aithe-time-picker>`    | Time selection input. 时间选择器。                                                                                    |
+| [Slider](form/slider.md)                 | `<aithe-slider>`         | Range slider for numeric input. 滑块数值输入。                                                                        |
+| [Rate](form/rate.md)                     | `<aithe-rate>`           | Star rating input. 星级评分输入。                                                                                     |
+| [Form](form/form.md)                     | `<aithe-form>`           | Form container with validation. 表单容器，支持校验。                                                                  |
+| [Form Item](form/form-item.md)           | `<aithe-form-item>`      | Form field wrapper with label and validation. 表单字段包装器。                                                        |
+| [Upload](form/upload.md)                 | `<aithe-upload>`         | File upload control. 文件上传控件。                                                                                   |
+| [Transfer](form/transfer.md)             | `<aithe-transfer>`       | Dual-list transfer selector. 双栏穿梭选择器。                                                                         |
+| [Autoform](form/autoform.md)             | `<aithe-autoform>`       | JSON-driven auto-rendering form with validation. JSON 配置驱动的自动渲染表单，支持校验。                              |
+| [Autoform Item](form/autoform-item.md)   | `<aithe-autoform-item>`  | JSON-driven form item with three-section layout and dependency rules. JSON 驱动表单项，三段式布局，支持依赖联动规则。 |
 
 ---
 
@@ -126,18 +125,22 @@ Components for user feedback, overlays, and notifications. 用户反馈、浮层
 
 Components for displaying and interacting with structured data. 结构化数据展示和交互组件。
 
-| Component                            | Tag                    | Description                                                                      |
-| ------------------------------------ | ---------------------- | -------------------------------------------------------------------------------- |
-| [Table](data/table.md)               | `<aithe-table>`        | Data table with sorting and selection. 数据表格，支持排序和选择。                |
-| [Table Column](data/table-column.md) | `<aithe-table-column>` | Column definition for DOM-defined mode. DOM 定义模式的列定义。                   |
-| [Tabs](data/tabs.md)                 | `<aithe-tabs>`         | Tab navigation container. 标签页导航容器。                                       |
-| [Tab Pane](data/tab-pane.md)         | `<aithe-tab-pane>`     | Single tab content panel. 单个标签页内容面板。                                   |
-| [Tree](data/tree.md)                 | `<aithe-tree>`         | Hierarchical tree view. 层级树视图。                                             |
-| [Tree Menu](data/tree-menu.md)       | `<aithe-tree-menu>`    | Data-driven tree menu with active highlighting. 数据驱动树形菜单，支持高亮选中。 |
-| [Dropdown](data/dropdown.md)         | `<aithe-dropdown>`     | Dropdown menu overlay. 下拉菜单浮层。                                           |
-| [Metrics](data/metrics.md)                 | `<aithe-metrics>`         | Business metric display with label, value and variant colors. 业务指标展示，含标签、数值和 variant 颜色样式。                 |
-| [Metrics Group](data/metrics-group.md)     | `<aithe-metrics-group>`   | Container that groups multiple metrics with direction and gap. 业务指标组容器，支持方向和间距配置。                         |
-| [Pagination](data/pagination.md)     | `<aithe-pagination>`   | Page navigation for large datasets. 大数据集分页导航。                           |
+| Component                              | Tag                     | Description                                                                                                   |
+| -------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
+| [Table](data/table.md)                 | `<aithe-table>`         | Data table with sorting and selection. 数据表格，支持排序和选择。                                             |
+| [Table Column](data/table-column.md)   | `<aithe-table-column>`  | Column definition for DOM-defined mode. DOM 定义模式的列定义。                                                |
+| [Tabs](data/tabs.md)                   | `<aithe-tabs>`          | Tab navigation container. 标签页导航容器。                                                                    |
+| [Tab Pane](data/tab-pane.md)           | `<aithe-tab-pane>`      | Single tab content panel. 单个标签页内容面板。                                                                |
+| [Tab Group](data/tabs.md)              | `<aithe-tab-group>`     | Alias of `<aithe-tabs>`. `<aithe-tabs>` 的别名组件。                                                          |
+| [Tree](data/tree.md)                   | `<aithe-tree>`          | Hierarchical tree view. 层级树视图。                                                                          |
+| [Tree Menu](data/tree-menu.md)         | `<aithe-tree-menu>`     | Data-driven tree menu with active highlighting. 数据驱动树形菜单，支持高亮选中。                              |
+| [Dropdown](data/dropdown.md)           | `<aithe-dropdown>`      | Dropdown menu overlay. 下拉菜单浮层。                                                                         |
+| [Metrics](data/metrics.md)             | `<aithe-metrics>`       | Business metric display with label, value and variant colors. 业务指标展示，含标签、数值和 variant 颜色样式。 |
+| [Metrics Group](data/metrics-group.md) | `<aithe-metrics-group>` | Container that groups multiple metrics with direction and gap. 业务指标组容器，支持方向和间距配置。           |
+| [Pagination](data/pagination.md)       | `<aithe-pagination>`    | Page navigation for large datasets. 大数据集分页导航。                                                        |
+| [Timeline](data/timeline.md)           | `<aithe-timeline>`      | Timeline container for process records. 时间线容器。                                                          |
+| [Timeline Item](data/timeline-item.md) | `<aithe-timeline-item>` | Single timeline node. 时间线节点。                                                                            |
+| [Box Table](data/box-table.md)         | `<aithe-box-table>`     | Dual-mode table/box view with sortable columns and selection. 双模式表格/盒子视图，支持排序和选择。           |
 
 ---
 
@@ -154,6 +157,14 @@ Rich content display and media components. 富内容展示和媒体组件。
 | [Markdown Editor](display/markdown-editor.md) | `<aithe-markdown-editor>` | Markdown editor with live preview. Markdown 编辑器，带实时预览。                                 |
 | [Code Editor](display/code-editor.md)         | `<aithe-code-editor>`     | Syntax-highlighted code editor with toolbar. 语法高亮代码编辑器，带工具栏。                      |
 | [Label](display/label.md)                     | `<aithe-label>`           | Lightweight label component that renders a Markdown subset. 轻量级标签组件，渲染 Markdown 子集。 |
+| [Box Overview](display/box.md)                | —                         | Box component family overview (Mini Box / Brief Box / Detail Box). Box 组件族概览。              |
+| [Mini Box](display/mini-box.md)               | `<aithe-mini-box>`        | Single-row compact record display (base class). 单行紧凑记录展示（基类）。                       |
+| [Brief Box](display/brief-box.md)             | `<aithe-brief-box>`       | Three-row brief record display with description. 三行简要记录展示，含描述行。                    |
+| [Detail Box](display/detail-box.md)           | `<aithe-detail-box>`      | Two-column detail record display. 双列详情记录展示。                                             |
+| [Profile](display/profile.md)                 | `<aithe-profile>`         | Profile display with icon/avatar, title and description. 档案展示，含图标/头像、标题和描述。     |
+| [Description List](display/desc.md)           | `<aithe-desc>`            | Structured key-value description list. 结构化键值描述列表。                                      |
+| [Description Item](display/desc-item.md)      | `<aithe-desc-item>`       | Single item in a description list with label and value. 描述列表中的单个条目，含标签和值。       |
+| [Auto View](display/autoview.md)              | `<aithe-autoview>`        | JSON-driven read-only detail view, the display-only counterpart of autoform. JSON 驱动的只读详情视图，autoform 的只读镜像。 |
 
 ---
 
@@ -191,7 +202,7 @@ Theme, shape, shadow, typo, and locale management components. The **Theme × Sha
 
 | Component                               | Tag                     | Description                                                                                                                |
 | --------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| [Theme Switch](theme/theme-switch.md)   | `<aithe-theme-switch>`  | Unified appearance switch — theme, shadow, shape & typo in one dropdown. 统一外观切换器，整合主题、阴影、形状和排版。     |
+| [Theme Switch](theme/theme-switch.md)   | `<aithe-theme-switch>`  | Unified appearance switch — theme, shadow, shape & typo in one dropdown. 统一外观切换器，整合主题、阴影、形状和排版。      |
 | [Theme Picker](theme/theme-picker.md)   | `<aithe-theme-picker>`  | Grouped theme selector with color dot previews. 分组主题选择器，带色点预览。                                               |
 | [Shape Picker](theme/shape-picker.md)   | `<aithe-shape-picker>`  | Shape style selector with preview thumbnails. 形状风格选择器，带预览缩略图。                                               |
 | [Shadow Picker](theme/shadow-picker.md) | `<aithe-shadow-picker>` | Shadow style selector with preview thumbnails. 阴影风格选择器，带预览缩略图。                                              |

package/docs/api/theme/theme-switch.md

@@ -20,7 +20,7 @@
 
 | Name               | Detail                                       | Cancelable | Description (EN)                                                                                                                                                                                                                                                              | Description (CN)                                                                                                                                                          |
 | ------------------ | -------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| aithe-theme-change | `{ category: string, value: string }`        | Yes        | Emitted when any option (theme/shadow/shape/typo) is selected. `category` is one of `'theme'`, `'shadow'`, `'shape'`, `'typo'`. Built-in switch (`aitheUI.setTheme()` / `aitheUI.setShadow()` / `aitheUI.setShape()` / `aitheUI.setTypo()`) runs by default. Call `preventDefault()` to suppress the built-in behavior and handle switching manually. | 选择任意选项（主题/阴影/形状/排版）时发出。`category` 为 `'theme'`、`'shadow'`、`'shape'` 或 `'typo'`。默认执行内置切换逻辑。调用 `preventDefault()` 可阻止内置切换，由外部自行处理。 |
+| aithe-theme-change | `{ category: string, value: string }`        | Yes        | Emitted when any option (theme/shadow/shape/typo) is selected. `category` is read from `item.category` on the selected tree-menu item (one of `'theme'`, `'shadow'`, `'shape'`, `'typo'`). Built-in switch (`aitheUI.setTheme()` / `aitheUI.setShadow()` / `aitheUI.setShape()` / `aitheUI.setTypo()`) runs by default. Call `preventDefault()` to suppress the built-in behavior and handle switching manually. | 选择任意选项（主题/阴影/形状/排版）时发出。`category` 从选中项的 `item.category` 读取（`'theme'`、`'shadow'`、`'shape'` 或 `'typo'`）。默认执行内置切换逻辑。调用 `preventDefault()` 可阻止内置切换，由外部自行处理。 |
 
 ## Menu Structure / 菜单结构