@aithe/aithe-ui 26.2.3 → 26.3.2

package/docs/api/display/desc.md

@@ -0,0 +1,246 @@
+# AitheDesc / AitheDesc 描述列表
+
+> A description list component that displays key-value pairs in a structured table-like layout. Supports border styles, label background, column count, title, extra actions, direction control, colspan, and rowspan.
+> 描述列表组件，以结构化的类表格布局展示键值对。支持边框样式、标签背景、列数、标题、额外操作、方向控制、列合并和行合并。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/display/desc';
+import '@aithe/aithe-ui/components/display/desc-item';
+```
+
+## Description / 描述
+
+`AitheDesc` renders a structured key-value list using CSS Grid layout. It places `<aithe-desc-item>` children into a grid based on the `column` property and each item's `span` and `rowspan`. Supports border styles (`none`/`full`/`row`), label background (`filled`/`none`), vertical/horizontal direction, title, extra slot, and size variants.
+
+`AitheDesc` 使用 CSS Grid 布局渲染结构化的键值列表。根据 `column` 属性和每个条目的 `span`/`rowspan` 将 `<aithe-desc-item>` 子元素放置到网格中。支持边框样式（`none`/`full`/`row`）、标签背景（`filled`/`none`）、垂直/水平方向、标题、额外插槽和尺寸变体。
+
+## AitheDesc Properties / AitheDesc 属性
+
+| Name             | Type                              | Default        | Attribute          | Description (EN)                                                                                                           | Description (CN)                                                                                          |
+| ---------------- | --------------------------------- | -------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| title            | `string`                          | `''`           | `title`            | Title text displayed in the header.                                                                                        | 头部标题文本。                                                                                            |
+| column           | `number`                          | `1`            | `column`           | Number of columns for the description layout.                                                                              | 描述布局的列数。                                                                                          |
+| border           | `boolean`                         | `false`        | `border`           | Whether to show full borders (outer frame + cell separators). Equivalent to `border-style="full"`.                         | 是否显示完整边框（外框+单元格分隔线），等同 `border-style="full"`。                                       |
+| border-style     | `'none' \| 'full' \| 'row'`       | `'none'`       | `border-style`     | Border style: `none` (no borders), `full` (outer + all cell separators), `row` (row separators only, no outer frame or column separators). | 边框样式：`none`（无边框）、`full`（外框+所有单元格分隔线）、`row`（仅行分隔线，无外框和列分隔线）。      |
+| label-background | `'filled' \| 'none'`              | `'filled'`     | `label-background` | Label background style: `filled` (default gray) or `none` (transparent).                                                   | 标签背景样式：`filled`（默认灰底）或 `none`（透明）。                                                      |
+| direction        | `'horizontal' \| 'vertical'`      | `'horizontal'` | `direction`        | Layout direction: label left of content or label above content.                                                            | 布局方向：标签在内容左侧或上方。                                                                          |
+| size             | `'sm' \| 'md' \| 'lg'`            | `'md'`         | `size`             | Size of the description list.                                                                                              | 描述列表的尺寸。                                                                                          |
+| labelWidth       | `string`                          | `'150px'`      | `label-width`      | Global label width. Falls back to individual item's label-width.                                                           | 全局标签宽度，item 单独设置时优先。                                                                       |
+| showTitle        | `boolean`                         | `true`         | `show-title`       | Whether to show the title header.                                                                                          | 是否显示标题头。                                                                                          |
+| maxRows          | `number`                          | `0`            | `max-rows`         | Maximum visible rows. 0 means no limit.                                                                                    | 最大可见行数，0 表示不限制。                                                                              |
+
+## AitheDescItem Properties / AitheDescItem 属性
+
+| Name       | Type                     | Default | Attribute   | Description (EN)                                    | Description (CN)               |
+| ---------- | ------------------------ | ------- | ----------- | --------------------------------------------------- | ------------------------------ |
+| label      | `string`                 | `''`    | `label`     | Label text for the item.                            | 条目标签文本。                 |
+| span       | `number`                 | `1`     | `span`      | Column span for this item.                          | 该条目占用的列数。             |
+| rowspan    | `number`                 | `1`     | `rowspan`   | Row span for this item.                             | 该条目占用的行数。             |
+| labelWidth | `string`                 | `''`    | `label-width` | Width of the label cell.                          | 标签单元格宽度。               |
+| width      | `string`                 | `''`    | `width`     | Width of the content cell.                          | 内容单元格宽度。               |
+| minWidth   | `string`                 | `''`    | `min-width` | Minimum width of the content cell.                  | 内容单元格最小宽度。           |
+| labelAlign | `'left' \| 'center' \| 'right'` | `'left'` | `label-align` | Text alignment of the label.                    | 标签文本对齐方式。             |
+| align      | `'left' \| 'center' \| 'right'` | `'left'` | `align`     | Text alignment of the content.                      | 内容文本对齐方式。             |
+
+## AitheDesc Slots / AitheDesc 插槽
+
+| Name    | Description (EN)                          | Description (CN)             |
+| ------- | ----------------------------------------- | ---------------------------- |
+| title   | Custom title content in the header.       | 头部自定义标题内容。         |
+| extra   | Extra action content in the header.       | 头部额外操作内容。           |
+| (default) | Description items (`<aithe-desc-item>`). | 描述条目（`<aithe-desc-item>`）。 |
+
+## AitheDescItem Slots / AitheDescItem 插槽
+
+| Name    | Description (EN)                          | Description (CN)             |
+| ------- | ----------------------------------------- | ---------------------------- |
+| label   | Custom label content.                     | 自定义标签内容。             |
+| (default) | Value content.                          | 值内容。                     |
+
+## AitheDesc Events / AitheDesc 事件
+
+| Name              | Detail | Cancelable | Description (EN)                       | Description (CN)            |
+| ----------------- | ------ | ---------- | -------------------------------------- | --------------------------- |
+| `aithe-desc-click` | `{}`   | No         | Fired when the description is clicked. | 点击描述列表时触发。        |
+
+## AitheDesc CSS Parts / AitheDesc CSS 部件
+
+| Name   | Description (EN)                    | Description (CN)     |
+| ------ | ----------------------------------- | -------------------- |
+| header | The header container.               | 头部容器。           |
+| body   | The body container.                 | 主体容器。           |
+| row    | A row container.                    | 行容器。             |
+
+## AitheDescItem CSS Parts / AitheDescItem CSS 部件
+
+| Name    | Description (EN)                    | Description (CN)     |
+| ------- | ----------------------------------- | -------------------- |
+| label   | The label cell container.           | 标签单元格容器。     |
+| content | The content cell container.         | 内容单元格容器。     |
+
+## Examples / 示例
+
+### Basic Usage / 基础用法
+
+```html
+<aithe-desc title="User Info">
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+  <aithe-desc-item label="Phone">+1 234 5678</aithe-desc-item>
+</aithe-desc>
+```
+
+### With Border / 带边框
+
+```html
+<aithe-desc title="User Info" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+  <aithe-desc-item label="Phone">+1 234 5678</aithe-desc-item>
+</aithe-desc>
+```
+
+### Border Styles / 边框样式
+
+`border-style` provides three modes: `none` (no borders), `full` (outer frame + all cell separators), `row` (row separators only).
+
+`border-style` 提供三种模式：`none`（无边框）、`full`（外框+所有单元格分隔线）、`row`（仅行分隔线）。
+
+```html
+<!-- Full border (equivalent to `border`) -->
+<aithe-desc title="Full Border" border-style="full" column="2">
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+  <aithe-desc-item label="Phone">+1 234 5678</aithe-desc-item>
+</aithe-desc>
+
+<!-- Row separators only, no outer frame -->
+<aithe-desc title="Row Separators" border-style="row" column="2">
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+  <aithe-desc-item label="Phone">+1 234 5678</aithe-desc-item>
+</aithe-desc>
+```
+
+### Label Background / 标签背景
+
+`label-background` controls whether the label cell has a gray background (`filled`, default) or is transparent (`none`). Combine with `border-style="row"` for a clean, minimal style.
+
+`label-background` 控制标签单元格是否为灰底（`filled`，默认）或透明（`none`）。配合 `border-style="row"` 可实现简洁风格。
+
+```html
+<!-- No label background + row separators: minimal style -->
+<aithe-desc title="Minimal" border-style="row" label-background="none" column="2">
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+  <aithe-desc-item label="Phone">+1 234 5678</aithe-desc-item>
+</aithe-desc>
+```
+
+### Column Span / 列合并
+
+```html
+<aithe-desc title="User Info" :column="2" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Address" :span="2">123 Main Street, New York, NY 10001</aithe-desc-item>
+</aithe-desc>
+```
+
+### Vertical Direction / 垂直方向
+
+```html
+<aithe-desc title="User Info" direction="vertical" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+</aithe-desc>
+```
+
+### With Extra Slot / 带额外操作
+
+```html
+<aithe-desc title="User Info" border>
+  <span slot="extra"><aithe-button size="sm">Edit</aithe-button></span>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+</aithe-desc>
+```
+
+### Size Variants / 尺寸变体
+
+```html
+<aithe-desc title="Small" size="sm" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+</aithe-desc>
+<aithe-desc title="Large" size="lg" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+</aithe-desc>
+```
+
+### Column Config / 列数配置
+
+```html
+<aithe-desc title="2 Columns" :column="2" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+  <aithe-desc-item label="Phone">+1 234 5678</aithe-desc-item>
+</aithe-desc>
+```
+
+### Custom Label Width / 自定义标签宽度
+
+```html
+<aithe-desc title="Server Config" border label-width="120px">
+  <aithe-desc-item label="Server Name">Production-Web-01</aithe-desc-item>
+  <aithe-desc-item label="IP Address">192.168.1.100</aithe-desc-item>
+  <aithe-desc-item label="Memory">64 GB DDR5</aithe-desc-item>
+</aithe-desc>
+```
+
+### Row Span / 行合并
+
+```html
+<aithe-desc title="User Profile" border>
+  <aithe-desc-item label="Name">Zhang Wei</aithe-desc-item>
+  <aithe-desc-item label="Age">28</aithe-desc-item>
+  <aithe-desc-item label="Gender">Male</aithe-desc-item>
+  <aithe-desc-item label="Phone">+86 138 0000 1234</aithe-desc-item>
+  <aithe-desc-item label="Email">zhangwei@example.com</aithe-desc-item>
+  <aithe-desc-item label="Address" :span="2" rowspan="2">No. 123, Chang'an Avenue, Haidian District, Beijing</aithe-desc-item>
+  <aithe-desc-item label="Position">Senior Engineer</aithe-desc-item>
+  <aithe-desc-item label="Department">Frontend Team</aithe-desc-item>
+</aithe-desc>
+```
+
+### Hide Title / 隐藏标题
+
+```html
+<aithe-desc title="Hidden Title" show-title="false" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+</aithe-desc>
+```
+
+### Max Rows / 限制行数
+
+```html
+<aithe-desc title="Limited View" border max-rows="2">
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+  <aithe-desc-item label="Phone">+1 234 5678</aithe-desc-item>
+  <aithe-desc-item label="Address">123 Main Street</aithe-desc-item>
+</aithe-desc>
+```

package/docs/api/display/detail-box.md

@@ -0,0 +1,75 @@
+# AitheDetailBox / AitheDetailBox 详情记录
+
+> Two-column detail record display with left metadata and right actions. Designed for rich detail views. All content is provided via named slots.
+> 双列详情记录展示，左侧元数据、右侧操作。设计用于丰富的详情视图。所有内容通过具名插槽提供。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/data/detail-box';
+```
+
+## Description / 描述
+
+`<aithe-detail-box>` renders a two-column layout: the left column contains select, checkbox, name, tags, status, and expandable content; the right column contains actions. Designed for detailed record views where rich metadata and actions are displayed side by side. All content is provided via named slots.
+
+`<aithe-detail-box>` 渲染双列布局：左列包含 select、checkbox、name、tags、status 和可展开内容；右列包含操作。设计用于详细记录视图，丰富的元数据和操作并排显示。所有内容通过具名插槽提供。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                                                    | Description (CN)               |
+| --------- | ------------------------------------------------------------------- | ------------------------------ |
+| select    | Selection control region (e.g. radio).                              | 选择控件区域（如单选框）。     |
+| checkbox  | Checkbox region.                                                    | 复选框区域。                   |
+| name      | Primary label / title region.                                       | 主标签/标题区域。              |
+| tags      | Tags region.                                                        | 标签区域。                     |
+| status    | Status indicator region.                                            | 状态指示器区域。               |
+| actions   | Action buttons region.                                              | 操作按钮区域。                 |
+| content   | Expandable content region.                                          | 可展开的内容区域。             |
+| (default) | Default slot, rendered inside the content region.                   | 默认插槽，渲染在内容区域内。   |
+
+## CSS Parts / CSS 部件
+
+| Name    | Description (EN)                    | Description (CN)     |
+| ------- | ----------------------------------- | -------------------- |
+| select  | The select region container.        | 选择区域容器。       |
+| checkbox| The checkbox region container.      | 复选框区域容器。     |
+| name    | The name region container.          | 名称区域容器。       |
+| tags    | The tags region container.          | 标签区域容器。       |
+| status  | The status region container.        | 状态区域容器。       |
+| actions | The actions region container.       | 操作区域容器。       |
+| content | The content region container.       | 内容区域容器。       |
+
+## Properties / 属性
+
+Inherits all properties from `AitheMiniBox`. See [AitheMiniBox](mini-box.md) for details.
+
+## Events / 事件
+
+Inherits all events from `AitheMiniBox`. See [AitheMiniBox](mini-box.md) for details.
+
+## Usage / 用法
+
+### Basic / 基础用法
+
+```html
+<aithe-detail-box>
+  <aithe-profile slot="name" title="Project Alpha" desc="Frontend application" icon="app"></aithe-profile>
+  <span slot="tags"><aithe-tag>frontend</aithe-tag> <aithe-tag>design</aithe-tag></span>
+  <span slot="status">Active</span>
+  <span slot="content">A front-end design system built with Lit and TypeScript.</span>
+</aithe-detail-box>
+```
+
+### With Actions / 带操作按钮
+
+```html
+<aithe-detail-box>
+  <aithe-profile slot="name" title="Project Alpha" desc="Frontend application" icon="app"></aithe-profile>
+  <span slot="status">Active</span>
+  <span slot="actions">
+    <aithe-button size="sm">Edit</aithe-button>
+    <aithe-button size="sm" variant="danger">Delete</aithe-button>
+  </span>
+</aithe-detail-box>
+```

package/docs/api/display/mini-box.md

@@ -0,0 +1,100 @@
+# AitheMiniBox / AitheMiniBox 迷你记录（基类）
+
+> Base class for the Box component family. Provides region-based layout with named slots. The box only defines layout structure — all content is provided via named slots, with no data binding. Not intended for direct use as a base class — use `<aithe-mini-box>`, `<aithe-brief-box>`, or `<aithe-detail-box>` instead.
+> Box 组件族的基类。提供基于区域的布局和具名插槽。Box 只定义布局结构——所有内容通过具名插槽提供，无数据绑定。不推荐作为基类直接使用——请使用 `<aithe-mini-box>`、`<aithe-brief-box>` 或 `<aithe-detail-box>`。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/data/mini-box';
+// or
+import '@aithe/aithe-ui/components/data/brief-box';
+// or
+import '@aithe/aithe-ui/components/data/detail-box';
+```
+
+## Description / 描述
+
+`AitheMiniBox` is the base class for the three Box variants. It defines the common property set, styling, and region rendering logic shared by all variants. Each variant implements a distinct layout strategy:
+
+- `<aithe-mini-box>` — single horizontal row (compact list view)
+- `<aithe-brief-box>` — three rows with description and vertically spanning checkbox/actions
+- `<aithe-detail-box>` — two-column split with left metadata and right actions
+
+All content is provided via named slots. The box only defines layout structure — it does not bind data.
+
+`AitheMiniBox` 是三种 Box 变体的基类，定义了所有变体共享的公共属性集、样式和区域渲染逻辑。每种变体实现不同的布局策略：
+
+- `<aithe-mini-box>` — 单行水平布局（紧凑列表视图）
+- `<aithe-brief-box>` — 三行布局，含描述和垂直贯穿的 checkbox/actions
+- `<aithe-detail-box>` — 左右分栏布局，左侧元数据、右侧操作
+
+所有内容通过具名插槽提供。Box 只定义布局结构——不绑定数据。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                                                    | Description (CN)               |
+| --------- | ------------------------------------------------------------------- | ------------------------------ |
+| select    | Selection control region (e.g. radio).                              | 选择控件区域（如单选框）。     |
+| checkbox  | Checkbox region.                                                    | 复选框区域。                   |
+| name      | Primary label / title region.                                       | 主标签/标题区域。              |
+| tags      | Tags region.                                                        | 标签区域。                     |
+| status    | Status indicator region.                                            | 状态指示器区域。               |
+| actions   | Action buttons region.                                              | 操作按钮区域。                 |
+| content   | Expandable content region.                                          | 可展开的内容区域。             |
+| (default) | Default slot, rendered inside the content region.                   | 默认插槽，渲染在内容区域内。   |
+
+## CSS Parts / CSS 部件
+
+| Name    | Description (EN)                    | Description (CN)     |
+| ------- | ----------------------------------- | -------------------- |
+| select  | The select region container.        | 选择区域容器。       |
+| checkbox| The checkbox region container.      | 复选框区域容器。     |
+| name    | The name region container.          | 名称区域容器。       |
+| tags    | The tags region container.          | 标签区域容器。       |
+| status  | The status region container.        | 状态区域容器。       |
+| actions | The actions region container.       | 操作区域容器。       |
+| content | The content region container.       | 内容区域容器。       |
+
+## Properties / 属性
+
+| Name      | Type                           | Default  | Attribute   | Description (EN)                                        | Description (CN)                     |
+| --------- | ------------------------------ | -------- | ----------- | ------------------------------------------------------- | ------------------------------------ |
+| selectable | `'none'` \| `'multi'` \| `'single'` | `'none'` | `selectable` | Selection mode. `'none'` disables selection, `'multi'` enables checkbox multi-select, `'single'` enables radio single-select. | 选择模式。`'none'` 不选择，`'multi'` 启用复选框多选，`'single'` 启用单选框单选。 |
+| selected  | `boolean`                      | `false`  | `selected`  | Whether the box is selected.                            | box 是否被选中。                     |
+| expanded  | `boolean`                      | `false`  | `expanded`  | Whether the content region is expanded.                 | 内容区域是否展开。                   |
+
+## Events / 事件
+
+| Name              | Detail | Cancelable | Description (EN)               | Description (CN)        |
+| ----------------- | ------ | ---------- | ------------------------------ | ----------------------- |
+| `aithe-box-click` | `{}`   | No         | Fired when the box is clicked. | 点击 box 时触发。       |
+
+## Usage / 用法
+
+### Basic / 基础用法
+
+```html
+<aithe-mini-box>
+  <aithe-profile slot="name" title="Project Alpha" desc="Frontend application" icon="app"></aithe-profile>
+  <span slot="status">Active</span>
+</aithe-mini-box>
+```
+
+### With Checkbox / 带复选框
+
+```html
+<aithe-mini-box selectable>
+  <aithe-profile slot="name" title="Project Alpha" desc="Frontend application" icon="app"></aithe-profile>
+  <span slot="status">Active</span>
+</aithe-mini-box>
+```
+
+### Selected State / 选中状态
+
+```html
+<aithe-mini-box selectable selected>
+  <aithe-profile slot="name" title="Project Alpha" desc="Frontend application" icon="app"></aithe-profile>
+  <span slot="status">Active</span>
+</aithe-mini-box>
+```

package/docs/api/display/profile.md

@@ -0,0 +1,92 @@
+# AitheProfile / AitheProfile 档案展示
+
+> Fixed left-right layout: icon/avatar on the left, title and description on the right. Designed as the standard name region component for the Box component family.
+> 固定左右布局：左侧图标/头像，右侧标题和描述。作为 Box 组件族的标准 name 区域组件。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/display/profile';
+```
+
+## Description / 描述
+
+`AitheProfile` renders a fixed left-right layout with icon/avatar on the left and title/description on the right. It can be used independently or embedded into the `name` slot of `aithe-mini-box`, `aithe-brief-box`, or `aithe-detail-box`. Icon supports `(class)xxx` format for class-based icons, or auto-generates from the first character of `title` when `icon` is empty.
+
+`AitheProfile` 渲染固定左右布局：左侧图标/头像，右侧标题和描述。可独立使用，也可嵌入 `aithe-mini-box` / `aithe-brief-box` / `aithe-detail-box` 的 name 插槽。Icon 支持 `(class)xxx` 格式使用 class 图标，icon 为空时自动用 title 首字符生成。
+
+## Properties / 属性
+
+| Name          | Type                  | Default   | Attribute      | Description (EN)                                                       | Description (CN)                     |
+| ------------- | --------------------- | --------- | -------------- | ---------------------------------------------------------------------- | ------------------------------------ |
+| icon          | `string`              | `''`      | `icon`         | Icon content. Supports `(class)xxx` format for class icons. Empty auto-generates from title first char. | 图标内容。支持 `(class)xxx` 格式使用 class 图标，空时自动用 title 首字符生成。 |
+| icon-size     | `string`              | `'lg'`    | `icon-size`    | Icon size, same as `aithe-avatar` size.                                | 图标尺寸，同 `aithe-avatar` 的 size。 |
+| icon-shape    | `'circle' \| 'square' \| 'none'` | `'none'` | `icon-shape`   | Icon shape. `'none'` renders `<aithe-icon>`, others render `<aithe-avatar>`. | 图标形状。`'none'` 渲染 `<aithe-icon>`，其他值渲染 `<aithe-avatar>`。 |
+| title         | `string`              | `''`      | `title`        | Primary name text.                                                     | 主名称。                             |
+| desc          | `string`              | `''`      | `desc`         | Description text.                                                      | 描述文案。                           |
+| title-ellipsis | `boolean`             | `true`    | `title-ellipsis` | Whether to truncate title with ellipsis when overflow.                 | 标题超长时是否省略。                 |
+| desc-ellipsis  | `boolean`             | `true`    | `desc-ellipsis`  | Whether to truncate description with ellipsis when overflow.           | 描述超长时是否省略。                 |
+
+## Slots / 插槽
+
+| Name  | Description (EN)                          | Description (CN)             |
+| ----- | ----------------------------------------- | ---------------------------- |
+| icon  | Custom icon/avatar region, overrides default avatar. | 自定义图标/头像区域，覆盖默认 avatar。 |
+| title | Custom title region, overrides default title text.   | 自定义标题区域，覆盖默认 title 文本。   |
+| desc  | Custom description region, overrides default desc text. | 自定义描述区域，覆盖默认 desc 文本。   |
+
+## CSS Parts / CSS 部件
+
+| Name  | Description (EN)                    | Description (CN)     |
+| ----- | ----------------------------------- | -------------------- |
+| title | The title region container.         | 标题区域容器。       |
+| desc  | The description region container.   | 描述区域容器。       |
+
+## Examples / 示例
+
+### Basic / 基础用法
+
+```html
+<aithe-profile title="Project Alpha" desc="Frontend application" icon="(class)app"></aithe-profile>
+```
+
+### Title Only / 仅标题
+
+```html
+<aithe-profile title="Project Alpha"></aithe-profile>
+```
+
+### Custom Icon Shape / 自定义图标形状
+
+```html
+<aithe-profile title="User" desc="Administrator" icon="(class)user" icon-shape="circle"></aithe-profile>
+<aithe-profile title="Server" desc="Production" icon="(class)server" icon-shape="square"></aithe-profile>
+```
+
+### Default Icon (aithe-icon) / 默认图标（aithe-icon）
+
+```html
+<aithe-profile title="Project" desc="Description" icon="(class)app"></aithe-profile>
+```
+
+### Custom Icon Size / 自定义图标尺寸
+
+```html
+<aithe-profile title="Project" desc="Description" icon="(class)app" icon-size="xl"></aithe-profile>
+```
+
+### Disable Ellipsis / 关闭省略号
+
+```html
+<aithe-profile title="A very long project name that should not be truncated" desc="Description" ?title-ellipsis=${false}></aithe-profile>
+```
+
+### Custom Slots / 使用插槽自定义
+
+```html
+<aithe-profile>
+  <img slot="icon" src="/avatar.png" style="width:40px;height:40px;border-radius:50%;" />
+  <div slot="title"><strong>Custom Title</strong></div>
+  <span slot="desc">Custom description with <aithe-tag>tag</aithe-tag></span>
+</aithe-profile>
+```

package/docs/api/feedback/popover.md

@@ -5,22 +5,22 @@
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
-| (default) | Default slot for the trigger element. | 触发元素内容。 |
-| content | Custom popover content. | 自定义弹出面板内容。 |
+| Name      | Description (EN)                      | Description (CN)     |
+| --------- | ------------------------------------- | -------------------- |
+| (default) | Default slot for the trigger element. | 触发元素内容。       |
+| content   | Custom popover content.               | 自定义弹出面板内容。 |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
+| Name      | Type                                   | Default  | Description (EN)                       | Description (CN)               |
+| --------- | -------------------------------------- | -------- | -------------------------------------- | ------------------------------ |
 | placement | 'top' \| 'right' \| 'bottom' \| 'left' | 'bottom' | Popover placement relative to trigger. | 弹出面板相对于触发元素的位置。 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-open-change | { open } | Emitted when open state changes. | 开关状态变更时触发。 |
+| Name                  | Detail   | Description (EN)                 | Description (CN)     |
+| --------------------- | -------- | -------------------------------- | -------------------- |
+| aithe-dropdown-change | { open } | Emitted when open state changes. | 开关状态变更时触发。 |
 
 ## Examples / 示例
 
@@ -29,4 +29,4 @@
   <button>Click me</button>
   <slot name="content"><p>Popover content here.</p></slot>
 </aithe-popover>
-```
+```

package/docs/api/feedback/tooltip.md

@@ -5,25 +5,25 @@
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
-| (default) | Default slot for the anchor element. | 锚点元素内容。 |
-| content | Custom tooltip content (overrides `content` property). | 自定义工具提示内容。 |
+| Name      | Description (EN)                                       | Description (CN)     |
+| --------- | ------------------------------------------------------ | -------------------- |
+| (default) | Default slot for the anchor element.                   | 锚点元素内容。       |
+| content   | Custom tooltip content (overrides `content` property). | 自定义工具提示内容。 |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| content | String | '' | Tooltip text content. | 工具提示文本内容。 |
-| title | `string` | `''` | Display title (shown as tooltip). | 显示标题（作为工具提示）。 |
-| icon | `string` | `''` | Icon name to display before the tooltip content. | 在工具提示内容前显示的图标名称。 |
-| placement | 'top' \| 'right' \| 'bottom' \| 'left' | 'top' | Tooltip placement relative to anchor. | 工具提示相对于锚点的位置。 |
+| Name      | Type                                   | Default | Description (EN)                                 | Description (CN)                 |
+| --------- | -------------------------------------- | ------- | ------------------------------------------------ | -------------------------------- |
+| content   | String                                 | ''      | Tooltip text content.                            | 工具提示文本内容。               |
+| title     | `string`                               | `''`    | Display title (shown as tooltip).                | 显示标题（作为工具提示）。       |
+| icon      | `string`                               | `''`    | Icon name to display before the tooltip content. | 在工具提示内容前显示的图标名称。 |
+| placement | 'top' \| 'right' \| 'bottom' \| 'left' | 'top'   | Tooltip placement relative to anchor.            | 工具提示相对于锚点的位置。       |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-open-change | { open } | Inherited from AnchoredOverlay; emitted on open state change. | 开关状态变更时触发。 |
+| Name                  | Detail   | Description (EN)                                              | Description (CN)                             |
+| --------------------- | -------- | ------------------------------------------------------------- | -------------------------------------------- |
+| aithe-dropdown-change | { open } | Inherited from AnchoredOverlay; emitted on open state change. | 继承自 AnchoredOverlay，开关状态变更时触发。 |
 
 ## Examples / 示例
 
@@ -31,4 +31,4 @@
 <aithe-tooltip content="Help text here" title="Help" icon="info" placement="top">
   <button>Hover me</button>
 </aithe-tooltip>
-```
+```