@aithe/aithe-ui 26.2.3 → 26.3.1

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

@@ -0,0 +1,100 @@
+# 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".                                                                                                                          | input 控件的 type 属性。   |
+| 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>
+```

package/docs/api/form/autoform.md

@@ -7,7 +7,7 @@
 
 | 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 / 属性
 
@@ -17,6 +17,8 @@
 | 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 / 事件
 

package/docs/api/form/select.md

@@ -5,43 +5,43 @@
 
 ## 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.     | 选项的视觉变体/语义色。                  |
 
 ## Examples / 示例
 
@@ -53,4 +53,4 @@
   searchable
   clearable
 ></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,13 @@ 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. 描述列表中的单个条目，含标签和值。       |
 
 ---
 
@@ -191,7 +201,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 / 菜单结构
 

package/docs/autoform.md

@@ -150,6 +150,9 @@ const values: Record<string, unknown> = form.getValues();
 // 重置为缺省值
 form.reset();
 
+// 编程触发表单提交（校验通过后触发 aithe-submit 事件）
+form.submit();
+
 // 监听提交事件
 form.addEventListener('aithe-submit', (e: CustomEvent<{ values: Record<string, unknown> }>) => {
   console.log('提交数据：', e.detail.values);
@@ -257,10 +260,16 @@ FormRegistry.register({
 
 ### 自定义提交按钮
 
-通过 slot 替换内置提交按钮：
+通过 slot 和 `show-submit` 属性控制操作区域：
 
 ```html
+<!-- 使用 slot 添加自定义按钮，同时保留内置提交按钮 -->
 <aithe-autoform fields="[...]">
+  <aithe-button>取消</aithe-button>
+</aithe-autoform>
+
+<!-- 关闭内置提交按钮，完全使用 slot 自定义 -->
+<aithe-autoform fields="[...]" show-submit="false">
   <aithe-button type="primary">保存</aithe-button>
   <aithe-button>取消</aithe-button>
 </aithe-autoform>
@@ -278,6 +287,8 @@ FormRegistry.register({
 | `submit-text`        | `String`  | `''`    | 提交按钮文本             |
 | `loading`            | `Boolean` | `false` | 提交中状态               |
 | `validate-on-change` | `Boolean` | `true`  | 是否在每次变更时实时校验 |
+| `initial-values`     | `Object` / `String` | `{}` | 表单字段初始值，支持对象或 JSON 字符串，覆盖对应字段的 `dft` |
+| `show-submit`        | `Boolean` | `true`  | 是否显示内置提交按钮，设为 `false` 时使用自定义 slot |
 
 ### `<aithe-autoform>` 方法
 
@@ -286,6 +297,7 @@ FormRegistry.register({
 | `validate()`  | `boolean`                 | 校验所有可见字段     |
 | `getValues()` | `Record<string, unknown>` | 获取所有可见字段值   |
 | `reset()`     | `void`                    | 重置所有字段为缺省值 |
+| `submit()`    | `void`                    | 编程触发表单校验和提交，通过后触发 `aithe-submit` 事件 |
 
 ### 事件
 

package/docs/changelog/CHANGELOG.md

@@ -4,6 +4,86 @@
 
 ---
 
+## 26.3.1 (2026-08-06)
+
+### 2026年第3季度第1个月版本 - 组件功能增强与质量提升
+
+- **树形菜单伸缩与事件改造**: `<aithe-tree-menu>` 新增 `expand-all`/`collapse-all` 方法与 `aithe-tree-toggle` 事件，事件参数统一为 `{ node, expanded }`
+- **Filter 数据格式化框架**: 新增 `@core/filter` 模块，提供 `registerFilter()`/`getFilter()`/`applyFilter()` API，内置 12 种过滤器（date/number/currency/percent/truncate/upper/lower/capitalize/strip-html/default/yes-no/enum）
+- **Table 六项新功能**: 列固定（sticky）、`max-visible-tabs` 溢出折叠、`has-fixed` 属性、斑马纹行固定列背景修复、`selection-cell` sticky 固定、`min-width: max-content` 控制
+- **Autoform 增强**: 条件渲染、字段联动、自定义控件注册表扩展
+- **Tabs 溢出折叠**: `<aithe-tabs>` 新增 `max-visible-tabs` 属性，溢出 tab 折叠为下拉选择；新增 `extra` 具名插槽
+- **Display 组件系列新增**: 新增 `<aithe-desc>`、`<aithe-desc-item>`、`<aithe-log-panel>`、`<aithe-mini-box>`、`<aithe-detail-box>`、`<aithe-brief-box>`、`<aithe-box-table>` 7 个新组件
+- **主题 CSS 变量统一**: 25 个主题统一新增 8 个 CSS 变量（`--aithe-fill-1`/`--aithe-fill-2`/`--aithe-color-surface-hover` 等），CSS 自定义属性命名规范化
+- **DataHub 错误处理增强**: HTTP 非 2xx 错误响应优先用 APIStyle 解析，`DataHubError` 新增 `data` 字段；K8s APIStyle 支持 `Status` 对象解析
+- **SSR 环境适配**: 4 个组件 `window` 引用改为 `globalThis`，兼容非浏览器环境
+- **测试框架集成**: 集成 vitest 测试框架，Filter 模块测试导入路径规范化
+- **SonarQube 代码质量修复**: 消除 S3358/S3776 等告警，提取公共方法
+- **AitheUI 浏览器环境检测**: 新增 `isMobile`/`isAndroid`/`isIOS`/`isChrome`/`isEdge`/`isWechat` 等 10 个环境检测 getter
+- **`AitheSelectableType` 类型重构**: 从 `boolean | 'single'` 改为 `'none' | 'multi' | 'single'` 纯字符串枚举
+- **组件数量**: 100 个可复用的 UI 组件
+
+### 破坏性变更
+
+- **事件名统一**: `aithe-open-change` → `aithe-dropdown-change`
+- **`cellRenderer` 签名变更**: 渲染函数参数结构调整
+- **`AitheSelectableType` 重构**: `boolean | 'single'` → `'none' | 'multi' | 'single'`，Box 组件族 `selectable` 从 `Boolean` 统一为 `AitheSelectableType`
+- **`danger` 属性废弃**: 相关组件移除 `danger` 属性，改用 `variant="danger"`
+- **CSS 自定义属性重命名**: `--aithe-duration-normal` → `--aithe-duration-base`/`--aithe-duration-slow`，`--aithe-container-radius` → `--aithe-container-radius-md`，`--aithe-border-radius-md` → `--aithe-radius-md`，`--aithe-font-mono` → `--aithe-font-family-mono`
+- **`<aithe-desc>` 布局重构**: label+content 合并单元格改为独立 grid 列，移除 `desc-item` 的 `labelWidth` 属性
+- **`<aithe-box-table>` 重构**: 移除自建卡片 DOM，改用 `<aithe-brief-box>` 组件；移除 `content` 列插槽
+
+### 组件分类
+
+| 分类              | 数量 | 组件                                                                                                                                                            |
+| ----------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 基础 (basic)      | 12   | button, button-group, icon, input, textarea, card, tag, badge, avatar, divider, empty, chip                                                                     |
+| 布局 (layout)     | 8    | container, row, col, flex, space, collapse, collapse-item, affix                                                                                                |
+| 导航 (navigation) | 7    | menu, menu-item, sub-menu, breadcrumb, breadcrumb-item, steps, back-top                                                                                         |
+| 表单 (form)       | 18   | autoform, autoform-item, checkbox, checkbox-group, radio, radio-group, select, switch, color-picker, combobox, date-picker, time-picker, slider, rate, form, form-item, upload, transfer |
+| 反馈 (feedback)   | 9    | dialog, modal, drawer, tooltip, popover, toast, alert, notification, loading                                                                                    |
+| 数据展示 (data)   | 14   | table, table-column, tabs, tab-pane, tab-group, tree, tree-menu, dropdown, metrics, metrics-group, pagination, timeline, timeline-item, box-table                |
+| 展示 (display)    | 13   | carousel, comparison, animated-image, markdown, markdown-editor, code-editor, label, mini-box, brief-box, detail-box, profile, desc, desc-item                   |
+| 进度 (progress)   | 4    | progress-bar, progress-ring, spinner, skeleton                                                                                                                  |
+| 容器 (container)  | 4    | callout, details, scroller, split-panel                                                                                                                         |
+| 主题 (theme)      | 7    | theme-picker, shape-picker, shadow-picker, typo-picker, theme-preview, locale-switch, theme-switch                                                              |
+| 框架 (framework)  | 7    | page, body, header, sidebar, dashboard, dashboard-panel, log-panel                                                                                               |
+
+### 主题列表
+
+**Light 系 (11)**: light, blue, festive, orange, purple, pink, teal, indigo, cyan, amber, gray
+
+**Dark 系 (11)**: dark, slate, charcoal, midnight, obsidian, graphite, ink, onyx, ebony, navy, raisin
+
+**云主题 (3)**: aliyun, huawei, tianyi
+
+### 阴影风格列表
+
+**内置阴影 (9)**: flat, neumorphism, skeuomorphic, glassmorphism, cyber, deep, diffuse, sharp-business, retro
+
+### 形状风格列表
+
+**内置形状 (8)**: sharp, smooth, rounded, rounder, pill, circle, chamfer, organic
+
+### 核心特性摘要
+
+- **Filter 数据格式化框架**: `@core/filter` 模块，12 种内置过滤器，支持自定义注册
+- **Table 列固定**: sticky 定位实现列固定，斑马纹背景修复
+- **Tabs 溢出折叠**: `max-visible-tabs` 属性，溢出 tab 折叠为下拉选择
+- **Display 组件系列**: 7 个新组件覆盖描述列表、日志面板、卡片表格等场景
+- **主题 CSS 变量统一**: 25 个主题统一 8 个 CSS 变量，命名规范化
+- **DataHub 错误处理**: APIStyle 解析错误响应，K8s Status 对象支持
+- **SSR 环境适配**: `globalThis` 替代 `window`，兼容非浏览器环境
+- **测试框架集成**: vitest 测试框架，Filter 模块测试覆盖
+- **浏览器环境检测**: `AitheUI` 类新增 10 个环境检测 getter
+- **跨框架兼容**: Web Components 标准，框架无关
+- **样式隔离**: Shadow DOM 确保组件样式不冲突
+- **多主题系统**: 25 套预设主题，支持全局和局部切换
+- **无障碍访问**: ARIA 语义、键盘导航、焦点管理
+- **自定义事件**: `aithe-*` 前缀的统一事件系统
+
+---
+
 ## 26.2.3 (2026-05-14)
 
 ### 2026年第2季度第3个月版本 - 代码规范与架构质量提升