@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/api/data/metrics.md

@@ -0,0 +1,155 @@
+# AitheMetrics / AitheMetrics 业务指标
+
+> Displays a business metric with label, value, and an optional slot for custom content. Supports variant-based color styling for the value, configurable alignment, and size scale.
+> 展示业务指标，含标签、数值和可选的自定义内容插槽。数值支持基于 variant 的颜色样式，支持配置对齐方式和尺寸规格。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/data/metrics';
+```
+
+## Description / 描述
+
+`<aithe-metrics>` renders a metric value prominently on top with an optional slot for inline custom content (such as an icon or badge), and a label below. It is designed for use inside `<aithe-metrics-group>`, `<aithe-dashboard-panel>`, or any statistic card context. The `variant` property controls the color of the value text, the `align` property controls text alignment, and the `scale` property controls the size of the value and label.
+
+`<aithe-metrics>` 上方突出显示指标数值，带可选的自定义内容插槽（如图标或徽章），下方显示标签。设计用于 `<aithe-metrics-group>`、`<aithe-dashboard-panel>` 内部或任何统计卡片场景。`variant` 属性控制数值文本的颜色，`align` 属性控制对齐方式，`scale` 属性控制数值和标签的尺寸。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                          | Description (CN)           |
+| --------- | ----------------------------------------- | -------------------------- |
+| (default) | Custom content displayed next to the value. | 显示在数值旁边的自定义内容。 |
+
+## CSS Parts / CSS 部件
+
+| Name  | Description (EN)          | Description (CN) |
+| ----- | ------------------------- | ---------------- |
+| value | The metric value element. | 指标数值元素。   |
+| label | The metric label element. | 指标标签元素。   |
+
+## Properties / 属性
+
+| Name        | Type                                                                  | Default     | Attribute      | Description (EN)                                                    | Description (CN)                         |
+| ----------- | --------------------------------------------------------------------- | ----------- | -------------- | ------------------------------------------------------------------- | ---------------------------------------- |
+| label       | `string`                                                              | `''`        | `label`        | Metric label text displayed below the value.                        | 显示在数值下方的标签文本。               |
+| value       | `string`                                                              | `''`        | `value`        | Metric value text displayed prominently.                            | 突出显示的数值文本。                     |
+| showDivider | `boolean`                                                             | `false`      | `show-divider` | Whether to show a primary-colored divider on the left side.         | 是否在左侧显示 primary 颜色的分割线。    |
+| align       | `'left' \| 'center' \| 'right'`                                       | `'center'`    | `align`        | Text alignment of the metric content.                                | 指标内容的对齐方式。                     |
+| scale       | `'small' \| 'normal' \| 'large'`                                      | `'small'`  | `scale`        | Size scale of the metric.                                            | 指标的尺寸规格。                         |
+| filter      | `string`                                                              | —            | —              | Filter expression to format the value. See [Filter](/docs/filter.md). | 用于格式化数值的过滤器表达式。参见 [Filter](/docs/filter.md)。 |
+| data        | `MetricsData \| MetricsData[] \| null`                                | `null`       | —              | Data-driven mode: set all properties from one object. Array uses first item. | 数据驱动模式：通过单个对象设置所有属性。数组仅取首项。 |
+| params      | `MetricsData`                                                         | `{}`         | —              | Generic config object. Overrides `data` for overlapping keys.        | 通用配置对象。同名键优先级高于 `data`。 |
+
+### MetricsData
+
+| Field       | Type                                                                  | Default     | Description (EN)                    | Description (CN)         |
+| ----------- | --------------------------------------------------------------------- | ----------- | ----------------------------------- | ------------------------ |
+| label       | `string`                                                              | `''`        | Metric label text.                  | 指标标签文本。           |
+| value       | `string`                                                              | `''`        | Metric value text.                  | 指标数值文本。           |
+| variant      | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'default'` | Color variant for the value text.    | 数值文本的颜色变体。     |
+| filter      | `string`                                                              | —            | Filter expression to format the value. See [Filter](/docs/filter.md). | 用于格式化数值的过滤器表达式。参见 [Filter](/docs/filter.md)。 |
+| showDivider | `boolean`                                                             | `false`     | Whether to show a divider.          | 是否显示分割线。         |
+| align       | `'left' \| 'center' \| 'right'`                                       | `'center'`    | Text alignment of the metric content.| 指标内容的对齐方式。     |
+| scale       | `'small' \| 'normal' \| 'large'`                                      | `'small'`  | Size scale of the metric.            | 指标的尺寸规格。         |
+
+## Usage / 用法
+
+### Basic / 基础用法
+
+```html
+<aithe-metrics label="Active Users" value="1,024" variant="primary"></aithe-metrics>
+```
+
+### With Custom Slot / 自定义插槽
+
+```html
+<aithe-metrics label="Revenue" value="$42.5K" variant="success">
+  <aithe-icon name="arrowUp" size="16"></aithe-icon>
+</aithe-metrics>
+```
+
+### With Divider / 带分割线
+
+```html
+<aithe-metrics label="Users" value="1,024" variant="primary" show-divider></aithe-metrics>
+```
+
+### Alignment / 对齐方式
+
+```html
+<aithe-metrics label="Left" value="100" variant="primary" align="left"></aithe-metrics>
+<aithe-metrics label="Center" value="200" variant="success" align="center"></aithe-metrics>
+<aithe-metrics label="Right" value="300" variant="danger" align="right"></aithe-metrics>
+```
+
+### Scale / 尺寸规格
+
+```html
+<aithe-metrics label="Small" value="1K" variant="primary" scale="small"></aithe-metrics>
+<aithe-metrics label="Normal" value="1K" variant="success" scale="normal"></aithe-metrics>
+<aithe-metrics label="Large" value="1K" variant="danger" scale="large"></aithe-metrics>
+```
+
+### In a Group / 在组中使用
+
+```html
+<aithe-metrics-group direction="horizontal" gap="24">
+  <aithe-metrics label="Users" value="1,024" variant="primary"></aithe-metrics>
+  <aithe-metrics label="Revenue" value="$42.5K" variant="success"></aithe-metrics>
+  <aithe-metrics label="Errors" value="3" variant="danger"></aithe-metrics>
+</aithe-metrics-group>
+```
+
+### With Intent / 带颜色意图
+
+```html
+<aithe-metrics label="Revenue" value="$42.5K" variant="success"></aithe-metrics>
+<aithe-metrics label="Errors" value="3" variant="danger"></aithe-metrics>
+<aithe-metrics label="Pending" value="12" variant="warning"></aithe-metrics>
+```
+
+### With Slot Content / 带插槽内容
+
+```html
+<aithe-metrics-group direction="horizontal" gap="32">
+  <aithe-metrics label="Conversion Rate" value="68.5%" variant="primary">
+    <aithe-icon name="arrowUp" size="16"></aithe-icon>
+  </aithe-metrics>
+  <aithe-metrics label="Bounce Rate" value="12.3%" variant="warning">
+    <aithe-icon name="arrowDown" size="16"></aithe-icon>
+  </aithe-metrics>
+</aithe-metrics-group>
+```
+
+### Inside Dashboard Panel / 在仪表盘面板中使用
+
+```html
+<aithe-dashboard-panel panel-id="stats" x="0" y="0" w="4" h="2" label="Statistics">
+  <aithe-metrics-group direction="horizontal" gap="24">
+    <aithe-metrics label="Users" value="1,024" variant="primary"></aithe-metrics>
+    <aithe-metrics label="Revenue" value="$42.5K" variant="success"></aithe-metrics>
+    <aithe-metrics label="Errors" value="3" variant="danger"></aithe-metrics>
+  </aithe-metrics-group>
+</aithe-dashboard-panel>
+```
+
+### Data-driven / 数据驱动
+
+```html
+<aithe-metrics data='{"label":"Users","value":"1,024","variant":"primary","showDivider":true}'></aithe-metrics>
+```
+
+### Data-driven with params override / params 覆盖
+
+```html
+<aithe-metrics id="my-metrics"></aithe-metrics>
+<script>
+  const el = document.getElementById('my-metrics');
+  el.params = { align: 'center', scale: 'large', showDivider: true };
+  el.data = { label: 'Users', value: '1,024', variant: 'primary' };
+</script>
+```
+
+> `data` also accepts an array; when an array is provided, only the first item is used.
+> `data` 也接受数组，传入数组时仅取第一个元素。

package/docs/api/data/table-column.md

@@ -9,37 +9,42 @@ Place `<aithe-table-column>` elements as children of `<aithe-table>` to define c
 
 ## Properties / 属性
 
-| Name | Type | Default | Attribute | Description (EN) | Description (CN) |
-|------|------|---------|-----------|-------------------|-------------------|
-| id | `string` | '' | `id` | Unique column key. | 唯一列键。 |
-| title | `string` | '' | `title` | Header title. | 表头标题。 |
-| dataIndex | `string` | '' | `data-index` | Property path on the data record. Defaults to `id` if empty. | 数据记录上的属性路径。为空时默认使用 `id`。 |
-| width | `string` | '' | `width` | Fixed column width. | 固定列宽。 |
-| align | 'left' \| 'center' \| 'right' | 'left' | `align` | Text alignment. | 文本对齐方式。 |
-| sortable | `boolean` | false | `sortable` | Enable client-side sorting. | 启用客户端排序。 |
-| icon | `string` | '' | `icon` | Icon name rendered in the header via aithe-icon. | 通过 aithe-icon 在表头渲染的图标名称。 |
-| intent | AitheIntent | 'default' | `intent` | Visual intent / semantic color for the column cells. | 列单元格的视觉意图/语义色。 |
-| cellRenderer | Function | undefined | — | Custom cell renderer: `(value, record, rowIndex) => unknown`. Only settable via JS property (not an HTML attribute). | 自定义单元格渲染器：`(value, record, rowIndex) => unknown`。仅可通过 JS 属性设置（非 HTML 属性）。 |
+| Name         | Type                          | Default   | Attribute    | Description (EN)                                                                                                | Description (CN)                                                                              |
+| ------------ | ----------------------------- | --------- | ------------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| id           | `string`                      | ''        | `id`         | Unique column key.                                                                                              | 唯一列键。                                                                                    |
+| title        | `string`                      | ''        | `title`      | Header title.                                                                                                   | 表头标题。                                                                                    |
+| dataIndex    | `string`                      | ''        | `data-index` | Property path on the data record. Defaults to `id` if empty.                                                    | 数据记录上的属性路径。为空时默认使用 `id`。                                                   |
+| width        | `string`                      | ''        | `width`      | Fixed column width.                                                                                             | 固定列宽。                                                                                    |
+| minWidth     | `string`                      | ''        | `min-width`  | Minimum column width (for resizable columns).                                                                   | 最小列宽（用于可调整宽度的列）。                                                              |
+| align        | 'left' \| 'center' \| 'right' | 'left'    | `align`      | Text alignment.                                                                                                 | 文本对齐方式。                                                                                |
+| sortable     | `boolean`                     | false     | `sortable`   | Enable client-side sorting.                                                                                     | 启用客户端排序。                                                                              |
+| fixed        | AitheColumnFixed \| ''        | ''        | `fixed`      | Fixed column position (`'left'` / `'right'`). The column sticks to the side with shadow indicators.             | 固定列位置（`'left'` / `'right'`）。列固定在侧边并显示阴影指示器。                            |
+| resizable    | `boolean`                     | false     | `resizable`  | Enable column width resizing via drag handle on the right edge of the header.                                   | 启用通过表头右侧边缘拖拽手柄调整列宽。                                                        |
+| draggable    | `boolean`                     | false     | `draggable`  | Enable column drag-to-reorder via drag handle icon in the header.                                               | 启用通过表头拖拽手柄图标拖拽排序列。                                                          |
+| icon         | `string`                      | ''        | `icon`       | Icon name rendered in the header via aithe-icon.                                                                | 通过 aithe-icon 在表头渲染的图标名称。                                                        |
+| variant      | AitheVariant                  | 'default' | `variant`    | Visual variant / semantic color for the column cells.                                                           | 列单元格的视觉变体/语义色。                                                                   |
+| filter       | `string`                      | ''        | `filter`     | Filter expression to format cell value. See [Filter](/docs/filter.md).                                          | 用于格式化单元格值的过滤器表达式。参见 [Filter](/docs/filter.md)。                            |
+| cellRenderer | AitheDataRenderer             | undefined | —            | Custom cell renderer: `(key, value, record) => unknown`. Only settable via JS property (not an HTML attribute). | 自定义单元格渲染器：`(key, value, record) => unknown`。仅可通过 JS 属性设置（非 HTML 属性）。 |
 
 ## cellRenderer Signature / cellRenderer 签名
 
 ```typescript
-(value: unknown, record: Record<string, unknown>, rowIndex: number) => unknown
+(key: string, value: unknown, record: Record<string, unknown>) => unknown;
 ```
 
-| Parameter | Type | Description (EN) | Description (CN) |
-|-----------|------|-------------------|-------------------|
-| value | `unknown` | Cell value resolved from `dataIndex` or `id`. | 从 `dataIndex` 或 `id` 解析的单元格值。 |
-| record | `Record<string, unknown>` | The full data record for the current row. | 当前行完整的数据记录。 |
-| rowIndex | `number` | Zero-based row index. | 从零开始的行索引。 |
-| (return) | `unknown` | Rendered content (string, number, HTMLElement, TemplateResult, etc.). | 渲染内容（字符串、数字、HTMLElement、TemplateResult 等）。 |
+| Parameter | Type                      | Description (EN)                                                      | Description (CN)                                           |
+| --------- | ------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------- |
+| key       | `string`                  | Column id / dataIndex.                                                | 列 id / dataIndex。                                        |
+| value     | `unknown`                 | Cell value resolved from `dataIndex` or `id`.                         | 从 `dataIndex` 或 `id` 解析的单元格值。                    |
+| record    | `Record<string, unknown>` | The full data record for the current row.                             | 当前行完整的数据记录。                                     |
+| (return)  | `unknown`                 | Rendered content (string, number, HTMLElement, TemplateResult, etc.). | 渲染内容（字符串、数字、HTMLElement、TemplateResult 等）。 |
 
 ## Examples / 示例
 
 ### Basic columns / 基础列
 
 ```html
-<aithe-table .data=${records} striped>
+<aithe-table .data="${records}" striped>
   <aithe-table-column id="name" title="Name" sortable></aithe-table-column>
   <aithe-table-column id="owner" title="Owner"></aithe-table-column>
 </aithe-table>
@@ -48,11 +53,20 @@ Place `<aithe-table-column>` elements as children of `<aithe-table>` to define c
 ### Custom cell renderer / 自定义单元格渲染
 
 ```html
-<aithe-table .data=${records} striped>
+<aithe-table .data="${records}" striped>
   <aithe-table-column id="name" title="Name" sortable></aithe-table-column>
-  <aithe-table-column id="status" title="Status" intent="success"></aithe-table-column>
-  <aithe-table-column id="action" title="Action" align="center"
-    .cellRenderer=${(value, record, rowIndex) => html`<aithe-button type="primary" size="sm">Edit</aithe-button>`}
-  ></aithe-table-column>
+  <aithe-table-column id="status" title="Status" variant="success"></aithe-table-column>
+  <aithe-table-column
+    id="action"
+    title="Action"
+    align="center"
+    .cellRenderer="${(key,"
+    value,
+    record)=""
+  >
+    html`
+    <aithe-button type="primary" size="sm">Edit</aithe-button>
+    `} >
+  </aithe-table-column>
 </aithe-table>
 ```

package/docs/api/data/table.md

@@ -8,59 +8,70 @@
 AitheTable supports two column definition modes:
 AitheTable 支持两种列定义模式：
 
-| Mode | How to define | Custom rendering | Description |
-|------|---------------|------------------|-------------|
-| Data-driven | `columns` / `columns-json` attribute | Not supported | Columns defined as JSON data. Suitable for simple display. |
-| DOM-defined | `<aithe-table-column>` children | Supported via `.cellRenderer` | Columns defined as child elements. Supports custom cell rendering. |
+| Mode        | How to define                        | Custom rendering              | Description                                                        |
+| ----------- | ------------------------------------ | ----------------------------- | ------------------------------------------------------------------ |
+| Data-driven | `columns` / `columns-json` attribute | Not supported                 | Columns defined as JSON data. Suitable for simple display.         |
+| DOM-defined | `<aithe-table-column>` children      | Supported via `.cellRenderer` | Columns defined as child elements. Supports custom cell rendering. |
 
-| 模式 | 定义方式 | 自定义渲染 | 说明 |
-|------|----------|-----------|------|
-| 数据驱动 | `columns` / `columns-json` 属性 | 不支持 | 列以 JSON 数据定义，适用于简单展示。 |
-| DOM 定义 | `<aithe-table-column>` 子元素 | 支持，通过 `.cellRenderer` | 列以子元素定义，支持自定义单元格渲染。 |
+| 模式     | 定义方式                        | 自定义渲染                 | 说明                                   |
+| -------- | ------------------------------- | -------------------------- | -------------------------------------- |
+| 数据驱动 | `columns` / `columns-json` 属性 | 不支持                     | 列以 JSON 数据定义，适用于简单展示。   |
+| DOM 定义 | `<aithe-table-column>` 子元素   | 支持，通过 `.cellRenderer` | 列以子元素定义，支持自定义单元格渲染。 |
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
+| Name      | Description (EN)                                                     | Description (CN)                                               |
+| --------- | -------------------------------------------------------------------- | -------------------------------------------------------------- |
 | (default) | Default slot for `<aithe-table-column>` children (DOM-defined mode). | 用于 `<aithe-table-column>` 子元素的默认插槽（DOM 定义模式）。 |
-| empty | Content shown when the table has no data. | 无数据时显示的内容。 |
+| empty     | Content shown when the table has no data.                            | 无数据时显示的内容。                                           |
+| loading   | Custom loading indicator content.                                    | 自定义加载指示器内容。                                         |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| columnsJson | String | '' | JSON string of column definitions (parsed into `columns`). Data-driven mode only. | 列定义的 JSON 字符串（解析为 `columns`）。仅数据驱动模式。 |
-| columns | AitheTableColumnMeta[] | [] | Array of column definitions (prefer this over `columnsJson` in JS). Data-driven mode only. | 列定义数组（在 JS 中优先使用此属性而非 `columnsJson`）。仅数据驱动模式。 |
-| dataJson | String | '' | JSON string of row data (parsed into `data`). | 行数据的 JSON 字符串（解析为 `data`）。 |
-| data | TableRecord[] | [] | Array of row data (prefer this over `dataJson` in JS). | 行数据数组（在 JS 中优先使用此属性而非 `dataJson`）。 |
-| rowKey | String | 'id' | Unique key field for each row. | 每行的唯一键字段。 |
-| striped | Boolean | false | Whether rows use alternating background colors. | 行是否使用交替背景色。 |
-| bordered | Boolean | true | Whether cells have vertical border lines. | 单元格是否有垂直边框线。 |
-| hoverable | Boolean | true | Whether rows highlight on hover. | 行是否在悬停时高亮。 |
-| selectable | Boolean | false | Whether rows can be selected via checkboxes. | 行是否可通过复选框选择。 |
-| sortKey | String | '' | Current sort column key. | 当前排序的列键。 |
-| sortOrder | 'asc' \| 'desc' \| '' | '' | Current sort direction. | 当前排序方向。 |
+| Name         | Type                          | Default   | Description (EN)                                                                                                                  | Description (CN)                                                                   |
+| ------------ | ----------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| columnsJson  | String                        | ''        | JSON string of column definitions (parsed into `columns`). Data-driven mode only.                                                 | 列定义的 JSON 字符串（解析为 `columns`）。仅数据驱动模式。                         |
+| columns      | AitheTableColumnMeta[]        | []        | Array of column definitions (prefer this over `columnsJson` in JS). Data-driven mode only.                                        | 列定义数组（在 JS 中优先使用此属性而非 `columnsJson`）。仅数据驱动模式。           |
+| dataJson     | String                        | ''        | JSON string of row data (parsed into `data`).                                                                                     | 行数据的 JSON 字符串（解析为 `data`）。                                            |
+| data         | TableRecord[]                 | []        | Array of row data (prefer this over `dataJson` in JS).                                                                            | 行数据数组（在 JS 中优先使用此属性而非 `dataJson`）。                              |
+| rowKey       | String                        | 'id'      | Unique key field for each row.                                                                                                    | 每行的唯一键字段。                                                                 |
+| striped      | Boolean                       | false     | Whether rows use alternating background colors.                                                                                   | 行是否使用交替背景色。                                                             |
+| bordered     | Boolean                       | true      | Whether cells have vertical border lines.                                                                                         | 单元格是否有垂直边框线。                                                           |
+| hoverable    | Boolean                       | true      | Whether rows highlight on hover.                                                                                                  | 行是否在悬停时高亮。                                                               |
+| selectable   | 'none' \| 'multi' \| 'single' | 'none'    | Row selection mode. `'none'` disables selection, `'multi'` enables checkbox multi-select, `'single'` enables radio single-select. | 行选择模式。`'none'` 不选择，`'multi'` 启用复选框多选，`'single'` 启用单选框单选。 |
+| selectionSet | Set\<string\>                 | new Set() | Shared Set instance for tracking selected row keys. Pass the same Set to multiple views to share selection state.                 | 共享的 Set 实例，用于跟踪选中的行键。将同一个 Set 传递给多个视图以共享选中状态。   |
+| sortKey      | String                        | ''        | Current sort column key.                                                                                                          | 当前排序的列键。                                                                   |
+| sortOrder    | 'asc' \| 'desc' \| ''         | ''        | Current sort direction.                                                                                                           | 当前排序方向。                                                                     |
+| loading      | Boolean                       | false     | Whether the table is in loading state. Shows a loading overlay with spinner and shimmer placeholder rows.                         | 表格是否处于加载状态。显示加载遮罩层、旋转器和 shimmer 占位行。                    |
+| loadingText  | String                        | ''        | Custom loading text displayed below the spinner.                                                                                  | 在旋转器下方显示的自定义加载文本。                                                 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-sort-change | { sortKey, sortOrder } | Emitted when a sortable column header is clicked. | 可排序列头被点击时触发。 |
-| aithe-selection-change | { selectedKeys } | Emitted when row selection changes. | 行选择变更时触发。 |
-| aithe-row-click | { record, rowIndex } | Emitted when a row is clicked. | 行被点击时触发。 |
+| Name                   | Detail                 | Description (EN)                                                            | Description (CN)                           |
+| ---------------------- | ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------ |
+| aithe-sort-change      | { sortKey, sortOrder } | Emitted when a sortable column header is clicked.                           | 可排序列头被点击时触发。                   |
+| aithe-selection-change | { selectionSet }       | Emitted when row selection changes.                                         | 行选择变更时触发。                         |
+| aithe-row-click        | { record, rowIndex }   | Emitted when a row is clicked.                                              | 行被点击时触发。                           |
+| aithe-column-resize    | { columnId, width }    | Emitted when a resizable column width is changed.                           | 可调整宽度的列宽变更时触发。               |
+| aithe-column-reorder   | { columns }            | Emitted when columns are reordered. Contains the new column id order array. | 列重新排序时触发。包含新的列 ID 顺序数组。 |
 
 ## Column Fields (Data-driven) / 列字段（数据驱动模式）
 
-| Field | Type | Description (EN) | Description (CN) |
-|-------|------|-------------------|-------------------|
-| id | `string` | Unique column key. | 唯一列键。 |
-| title | `string` | Header title. | 表头标题。 |
-| dataIndex | keyof T \| string | Property path on the data record. | 数据记录上的属性路径。 |
-| width | `string` | Fixed column width. | 固定列宽。 |
-| align | 'left' \| 'center' \| 'right' | Text alignment. | 文本对齐方式。 |
-| sortable | `boolean` | Enable client-side sorting. | 启用客户端排序。 |
-| icon | `string` | Icon name rendered in the header via aithe-icon. | 通过 aithe-icon 在表头渲染的图标名称。 |
-| intent | AitheIntent | Visual intent / semantic color for the column cells. | 列单元格的视觉意图/语义色。 |
+| Field     | Type                          | Description (EN)                                                                               | Description (CN)                                                   |
+| --------- | ----------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| id        | `string`                      | Unique column key.                                                                             | 唯一列键。                                                         |
+| title     | `string`                      | Header title.                                                                                  | 表头标题。                                                         |
+| dataIndex | keyof T \| string             | Property path on the data record.                                                              | 数据记录上的属性路径。                                             |
+| width     | `string`                      | Fixed column width.                                                                            | 固定列宽。                                                         |
+| minWidth  | `string`                      | Minimum column width (for resizable columns).                                                  | 最小列宽（用于可调整宽度的列）。                                   |
+| align     | 'left' \| 'center' \| 'right' | Text alignment.                                                                                | 文本对齐方式。                                                     |
+| sortable  | `boolean`                     | Enable client-side sorting.                                                                    | 启用客户端排序。                                                   |
+| fixed     | 'left' \| 'right'             | Fixed column position. The column will stick to the left or right side with shadow indicators. | 固定列位置。列将固定在左侧或右侧，并显示阴影指示器。               |
+| resizable | `boolean`                     | Enable column width resizing via drag handle on the right edge of the header.                  | 启用通过表头右侧边缘拖拽手柄调整列宽。                             |
+| draggable | `boolean`                     | Enable column drag-to-reorder via drag handle icon in the header.                              | 启用通过表头拖拽手柄图标拖拽排序列。                               |
+| icon      | `string`                      | Icon name rendered in the header via aithe-icon.                                               | 通过 aithe-icon 在表头渲染的图标名称。                             |
+| variant   | AitheVariant                  | Visual variant / semantic color for the column cells.                                          | 列单元格的视觉变体/语义色。                                        |
+| filter    | `string`                      | Filter expression to format cell value. See [Filter](/docs/filter.md).                         | 用于格式化单元格值的过滤器表达式。参见 [Filter](/docs/filter.md)。 |
 
 ## Examples / 示例
 
@@ -71,19 +82,122 @@ AitheTable 支持两种列定义模式：
   columns-json='[{"id":"name","title":"Name","sortable":true}]'
   data-json='[{"name":"Alice"},{"name":"Bob"}]'
   striped
-  selectable
+  selectable="multi"
+></aithe-table>
+```
+
+### Data-driven mode with shared selection / 数据驱动模式 + 共享选中状态
+
+```html
+<aithe-table
+  columns-json='[{"id":"name","title":"Name","sortable":true}]'
+  data-json='[{"name":"Alice"},{"name":"Bob"}]'
+  striped
+  selectable="multi"
+  .selectionSet="${mySet}"
 ></aithe-table>
 ```
 
 ### DOM-defined mode / DOM 定义模式
 
 ```html
-<aithe-table .data=${records} striped selectable>
+<aithe-table .data="${records}" striped selectable>
   <aithe-table-column id="name" title="Name" sortable></aithe-table-column>
   <aithe-table-column id="owner" title="Owner"></aithe-table-column>
-  <aithe-table-column id="status" title="Status" intent="success" sortable></aithe-table-column>
-  <aithe-table-column id="action" title="Action" align="center"
-    .cellRenderer=${(value, record, rowIndex) => html`<aithe-button type="primary" size="sm">Edit</aithe-button>`}
+  <aithe-table-column id="status" title="Status" variant="success" sortable></aithe-table-column>
+  <aithe-table-column
+    id="action"
+    title="Action"
+    align="center"
+    .cellRenderer="${(key,"
+    value,
+    record)=""
+  >
+    html`
+    <aithe-button type="primary" size="sm">Edit</aithe-button>
+    `} >
+  </aithe-table-column>
+</aithe-table>
+```
+
+### Column fixed / 列固定
+
+```html
+<aithe-table .data="${records}" striped bordered selectable>
+  <aithe-table-column id="name" title="Name" fixed="left" width="160" sortable></aithe-table-column>
+  <aithe-table-column id="owner" title="Owner" width="200"></aithe-table-column>
+  <aithe-table-column id="status" title="Status" width="200" variant="success"></aithe-table-column>
+  <aithe-table-column
+    id="action"
+    title="Action"
+    fixed="right"
+    width="120"
+    align="center"
+  ></aithe-table-column>
+</aithe-table>
+```
+
+### Column resize / 列宽调整
+
+```html
+<aithe-table .data="${records}" striped bordered>
+  <aithe-table-column
+    id="name"
+    title="Name"
+    resizable
+    min-width="120"
+    width="200"
+    sortable
+  ></aithe-table-column>
+  <aithe-table-column
+    id="owner"
+    title="Owner"
+    resizable
+    min-width="100"
+    width="200"
+  ></aithe-table-column>
+  <aithe-table-column
+    id="status"
+    title="Status"
+    resizable
+    min-width="100"
+    width="200"
   ></aithe-table-column>
 </aithe-table>
-```
+```
+
+### Column reorder / 列排序
+
+```html
+<aithe-table .data="${records}" striped bordered>
+  <aithe-table-column id="name" title="Name" draggable sortable></aithe-table-column>
+  <aithe-table-column id="owner" title="Owner" draggable></aithe-table-column>
+  <aithe-table-column id="status" title="Status" draggable variant="success"></aithe-table-column>
+</aithe-table>
+```
+
+### Loading state / 加载状态
+
+```html
+<aithe-table
+  loading
+  loading-text="Loading..."
+  .data="${records}"
+  columns-json='[{"id":"name","title":"Name","sortable":true}]'
+  striped
+  selectable="multi"
+></aithe-table>
+```
+
+### Single row selection / 行单选
+
+```html
+<aithe-table
+  selectable="multi"
+  ="single"
+  .selectionSet="${mySet}"
+  .data="${records}"
+  columns-json='[{"id":"name","title":"Name","sortable":true}]'
+  striped
+></aithe-table>
+```

package/docs/api/data/tabs.md

@@ -8,6 +8,7 @@
 | Name | Description (EN) | Description (CN) |
 |------|-------------------|-------------------|
 | (default) | Default slot for `aithe-tab-pane` children. | 默认插槽，用于 `aithe-tab-pane` 子组件。 |
+| extra | Slot for extra content rendered at the end of the tab bar (e.g. action buttons). | 额外内容插槽，渲染在标签栏末尾（如操作按钮）。 |
 
 ## Properties / 属性
 
@@ -16,6 +17,7 @@
 | type | 'line' \| 'card' \| 'button' | 'line' | Visual style of the tab navigation. | 标签页导航的视觉样式。 |
 | activeKey | String | '' | Key of the currently active tab pane. | 当前活动标签页的键。 |
 | addable | Boolean | false | Whether to show an add button in the tab bar. | 是否在标签栏中显示添加按钮。 |
+| maxVisibleTabs | Number | 0 | Maximum visible tabs before overflow dropdown. `0` = no limit. | 最大可见标签页数量，超出部分折叠到下拉菜单。`0` 表示不限制。 |
 
 ## Events / 事件
 
@@ -25,11 +27,54 @@
 | aithe-tab-remove | { key } | Emitted when a closable tab is removed. | 可关闭标签页被移除时触发。 |
 | aithe-tab-add | — | Emitted when the add button is clicked. | 添加按钮被点击时触发。 |
 
+## CSS Custom Properties / CSS 自定义属性
+
+| Property | Default | Description (EN) | Description (CN) |
+|----------|---------|-------------------|-------------------|
+| --aithe-tabs-nav-gap | var(--aithe-space-2) | Gap between tab items in the nav bar. | 标签栏中标签项之间的间距。 |
+| --aithe-tabs-nav-border-color | var(--aithe-color-border) | Bottom border color of the nav bar. | 标签栏底部边框颜色。 |
+| --aithe-tabs-tab-padding | 0 var(--aithe-space-4) | Padding inside each tab button. | 标签按钮内边距。 |
+| --aithe-tabs-tab-min-height | 38px | Minimum height of each tab button. | 标签按钮最小高度。 |
+| --aithe-tabs-tab-radius | var(--aithe-radius-md) | Border radius of tab buttons. | 标签按钮圆角。 |
+| --aithe-tabs-tab-color | var(--aithe-color-text-muted) | Text color of inactive tabs. | 非活动标签文字颜色。 |
+| --aithe-tabs-tab-active-color | var(--aithe-primary-7) | Text color of active tabs (line type). | 活动标签文字颜色（line 类型）。 |
+| --aithe-tabs-tab-active-border-color | var(--aithe-primary-6) | Active indicator border color (line type). | 活动标签指示器边框颜色（line 类型）。 |
+| --aithe-tabs-tab-active-bg | var(--aithe-color-surface-elevated) | Background of active tabs (card/button type). | 活动标签背景色（card/button 类型）。 |
+| --aithe-tabs-tab-disabled-opacity | 0.48 | Opacity of disabled tabs. | 禁用标签的不透明度。 |
+
+## CSS Parts / CSS 部件
+
+| Part | Description (EN) | Description (CN) |
+|------|-------------------|-------------------|
+| nav | The tab navigation bar container. | 标签导航栏容器。 |
+| panel | The tab content panel area. | 标签内容面板区域。 |
+| tab | Individual tab button. | 单个标签按钮。 |
+| tab-active | Active tab button. | 活动标签按钮。 |
+| tab-disabled | Disabled tab button. | 禁用标签按钮。 |
+| remove-btn | Close button on closable tabs. | 可关闭标签上的关闭按钮。 |
+| add-btn | Add tab button. | 添加标签按钮。 |
+| overflow-select | Overflow dropdown select. | 溢出下拉选择器。 |
+| nav-extra | Extra content slot container. | 额外内容插槽容器。 |
+
 ## Examples / 示例
 
+### Basic usage / 基础用法
+
 ```html
 <aithe-tabs type="card" active-key="a">
   <aithe-tab-pane tab-id="a" label="Tab A">Content A</aithe-tab-pane>
   <aithe-tab-pane tab-id="b" label="Tab B">Content B</aithe-tab-pane>
 </aithe-tabs>
-```
+```
+
+### With overflow dropdown / 带溢出下拉
+
+```html
+<aithe-tabs max-visible-tabs="3" type="card" active-key="tab1">
+  <aithe-tab-pane tab-id="tab1" label="Tab 1">Content 1</aithe-tab-pane>
+  <aithe-tab-pane tab-id="tab2" label="Tab 2">Content 2</aithe-tab-pane>
+  <aithe-tab-pane tab-id="tab3" label="Tab 3">Content 3</aithe-tab-pane>
+  <aithe-tab-pane tab-id="tab4" label="Tab 4">Content 4</aithe-tab-pane>
+  <aithe-tab-pane tab-id="tab5" label="Tab 5">Content 5</aithe-tab-pane>
+</aithe-tabs>
+```

package/docs/api/data/timeline.md

@@ -38,7 +38,7 @@ AitheTimeline 支持两种节点定义模式：
 |-------|------|-------------------|-------------------|
 | content | `string` | Item content text. | 节点内容文本。 |
 | timestamp | `string` | Timestamp label text. | 时间戳标签文本。 |
-| type | 'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' | Color variant for the dot indicator. | 圆点指示器的颜色类型。 |
+| variant | 'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' | Color variant for the dot indicator. | 圆点指示器的颜色变体。 |
 | dot | `string` | Custom dot content (overrides default circle). | 自定义圆点内容（覆盖默认圆圈）。 |
 
 ## Events / 事件
@@ -53,7 +53,7 @@ AitheTimeline 支持两种节点定义模式：
 
 ```html
 <aithe-timeline
-  items='[{"content":"Design tokens published","timestamp":"09:00","type":"primary"},{"content":"Demo routing completed","timestamp":"11:30","type":"success"},{"content":"Accessibility audit pending","timestamp":"15:20","type":"warning"}]'
+  items='[{"content":"Design tokens published","timestamp":"09:00","variant":"primary"},{"content":"Demo routing completed","timestamp":"11:30","variant":"success"},{"content":"Accessibility audit pending","timestamp":"15:20","variant":"warning"}]'
 ></aithe-timeline>
 ```
 
@@ -61,7 +61,7 @@ AitheTimeline 支持两种节点定义模式：
 
 ```html
 <aithe-timeline reverse>
-  <aithe-timeline-item timestamp="2024-01-01" type="primary">Step 1</aithe-timeline-item>
-  <aithe-timeline-item timestamp="2024-01-02" type="success">Step 2</aithe-timeline-item>
+  <aithe-timeline-item timestamp="2024-01-01" variant="primary">Step 1</aithe-timeline-item>
+  <aithe-timeline-item timestamp="2024-01-02" variant="success">Step 2</aithe-timeline-item>
 </aithe-timeline>
 ```