@aithe/aithe-ui 26.2.3 → 26.3.2

package/dist/utils/utils.js

@@ -0,0 +1,89 @@
+/** Auto-incrementing ID counter for unique element identifiers. 自增ID计数器，用于生成唯一元素标识符。 */
+let aitheId = 0;
+/**
+ * Clamp a numeric value between a minimum and maximum bound.
+ * 将数值限制在最小值和最大值之间。
+ *
+ * @param value - The number to clamp. 要限制的数值。
+ * @param min   - Lower bound. 下界。
+ * @param max   - Upper bound. 上界。
+ * @returns The clamped value. 限制后的值。
+ */
+export function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * Resolve a nested property from an object using a dot-separated path.
+ * 使用点分隔路径从对象中解析嵌套属性。
+ *
+ * @param record    - Source object. 源对象。
+ * @param dataIndex - Dot-separated key path, e.g. `"user.name"`. 点分隔的键路径，如 `"user.name"`。
+ * @returns The resolved value, or `undefined` if the path cannot be traversed. 解析后的值，若路径无法遍历则返回 `undefined`。
+ */
+export function getValueByPath(record, dataIndex) {
+    if (!dataIndex || typeof record !== 'object' || record === null) {
+        return dataIndex ? undefined : record;
+    }
+    return dataIndex.split('.').reduce((current, key) => {
+        if (typeof current === 'object' && current !== null && key in current) {
+            return current[key];
+        }
+        return undefined;
+    }, record);
+}
+/**
+ * Generate a unique ID string with the given prefix.
+ * 使用给定前缀生成唯一ID字符串。
+ *
+ * @param prefix - Prefix for the ID. Defaults to `"aithe"`. ID前缀，默认为 `"aithe"`。
+ * @returns A unique string like `"aithe-1"`. 类似 `"aithe-1"` 的唯一字符串。
+ */
+export function uid(prefix = 'aithe') {
+    aitheId += 1;
+    return `${prefix}-${aitheId}`;
+}
+/**
+ * Find the first focusable element inside a root container.
+ * 在根容器中查找第一个可聚焦元素。
+ *
+ * @param root - Parent node to search within. 要搜索的父节点。
+ * @returns The first visible, non-disabled focusable element, or `null`. 第一个可见、非禁用的可聚焦元素，或 `null`。
+ */
+export function findFirstFocusable(root) {
+    const selectors = [
+        'button:not([disabled])',
+        '[href]',
+        'input:not([disabled])',
+        'select:not([disabled])',
+        'textarea:not([disabled])',
+        '[tabindex]:not([tabindex="-1"])',
+    ];
+    const items = Array.from(root.querySelectorAll(selectors.join(',')));
+    return items.find((item) => !item.hasAttribute('hidden') && item.offsetParent !== null) ?? null;
+}
+/**
+ * Safely converts an unknown value to a string, preventing "[object Object]" output.
+ * Falls back gracefully through multiple strategies:
+ *   1. Pretty-print JSON.stringify for objects (fails on circular references)
+ *   2. Compact JSON.stringify as second attempt
+ *   3. String() as final fallback
+ *
+ * 安全地将任意值转换为字符串，避免 "[object Object]" 输出。
+ * 对象优先尝试格式化 JSON.stringify，失败后降级为紧凑格式，最后 String() 兜底。
+ */
+export function safeStringify(value) {
+    if (typeof value !== 'object' || value === null) {
+        return String(value);
+    }
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+}

package/dist/utils/validation.js

@@ -0,0 +1,52 @@
+/**
+ * Check whether a value is `null` or `undefined`.
+ * 检查值是否为 `null` 或 `undefined`。
+ *
+ * @param value - Value to check. 要检查的值。
+ * @returns `true` when the value is nullish. 当值为空时返回 `true`。
+ */
+export function isNil(value) {
+    return value === null || value === undefined;
+}
+/**
+ * Convert an HTML attribute value to a boolean, treating empty string and
+ * `"true"` as truthy (matches HTML boolean attribute semantics).
+ * 将 HTML 属性值转换为布尔值，将空字符串和 `"true"` 视为真值（符合 HTML 布尔属性语义）。
+ *
+ * @param value - Attribute value to convert. 要转换的属性值。
+ * @returns Boolean interpretation. 布尔解释。
+ */
+export function toBooleanAttribute(value) {
+    return value === '' || value === true || value === 'true';
+}
+/**
+ * Normalize a CSS dimension value: bare numbers get `px` appended,
+ * size aliases (`xs`/`sm`/`md`/`lg`/`xl`) resolve to design tokens,
+ * and already-valid CSS values pass through unchanged.
+ * 规范化 CSS 尺寸值：纯数字追加 `px`，尺寸别名（`xs`/`sm`/`md`/`lg`/`xl`）解析为设计令牌，
+ * 已有效的 CSS 值直接通过。
+ *
+ * @param value    - Raw value to normalize. 要规范化的原始值。
+ * @param fallback - Default value when input is empty. Defaults to `""`. 输入为空时的默认值，默认为 `""`。
+ * @returns A valid CSS dimension string. 有效的 CSS 尺寸字符串。
+ */
+export function normalizeCssUnit(value, fallback = '') {
+    if (typeof value === 'number') {
+        return `${value}px`;
+    }
+    const normalized = (value ?? '').trim();
+    if (!normalized) {
+        return fallback;
+    }
+    if (/^-?\d+(\.\d+)?$/.test(normalized)) {
+        return `${normalized}px`;
+    }
+    const sizeAliasMap = {
+        xs: 'var(--aithe-space-xs)',
+        sm: 'var(--aithe-space-sm)',
+        md: 'var(--aithe-space-md)',
+        lg: 'var(--aithe-space-lg)',
+        xl: 'var(--aithe-space-xl)',
+    };
+    return sizeAliasMap[normalized] ?? normalized;
+}

package/docs/api/basic/button.md

@@ -15,13 +15,13 @@
 
 | Name     | Type                                                     | Default     | Description (EN)                                                                      | Description (CN)                                          |
 | -------- | -------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| type     | `'primary' \| 'default' \| 'dashed' \| 'text' \| 'link'` | `'default'` | Visual type of the button.                                                            | 按钮的视觉类型。                                          |
+| variant  | `'default' \| 'primary' \| 'danger' \| 'success' \| 'warning' \| 'neutral'` | `'default'` | Color intent of the button. Controls emphasis and semantic color.                     | 按钮的颜色意图。控制强调程度和语义色。                    |
+| type     | `'default' \| 'dashed' \| 'text' \| 'link'`              | `'default'` | Appearance style of the button.                                                       | 按钮的外观风格。                                          |
 | size     | `'small' \| 'medium' \| 'large'`                         | `'medium'`  | Size scale of the button.                                                             | 按钮的尺寸规格。                                          |
 | title    | `string`                                                 | `''`        | Display title (shown as tooltip).                                                     | 显示标题（作为工具提示）。                                |
 | icon     | `string`                                                 | `''`        | Icon name to display before the label.                                                | 在标签前显示的图标名称。                                  |
 | disabled | `boolean`                                                | `false`     | Whether the button is disabled.                                                       | 按钮是否禁用。                                            |
 | loading  | `boolean`                                                | `false`     | Whether the button shows a loading spinner.                                           | 按钮是否显示加载旋转器。                                  |
-| danger   | `boolean`                                                | `false`     | Whether the button uses danger styling.                                               | 按钮是否使用危险样式。                                    |
 | block    | `boolean`                                                | `false`     | Whether the button spans the full width of its container.                             | 按钮是否占满容器宽度。                                    |
 | href     | `string`                                                 | `''`        | Link URL. When set, the button renders as an `<a>` element with native link behavior. | 链接地址。设置后按钮渲染为 `<a>` 元素，具有原生链接行为。 |
 | target   | `string`                                                 | `''`        | Link target attribute (e.g. `_blank`). Only applies when `href` is set.               | 链接 target 属性（如 `_blank`）。仅在设置 `href` 时生效。 |
@@ -37,15 +37,18 @@
 ### Basic buttons / 基础按钮
 
 ```html
-<aithe-button type="primary" size="medium" title="Submit form" icon="check">Submit</aithe-button>
-<aithe-button type="danger" loading>Deleting...</aithe-button>
+<aithe-button variant="primary" size="medium" title="Submit form" icon="check">Submit</aithe-button>
+<aithe-button variant="danger" loading>Deleting...</aithe-button>
+<aithe-button type="dashed">Dashed</aithe-button>
+<aithe-button type="text">Text</aithe-button>
+<aithe-button type="link">Link</aithe-button>
 ```
 
 ### Link button / 链接按钮
 
 ```html
-<aithe-button type="primary" href="/dashboard">Go to Dashboard</aithe-button>
-<aithe-button type="default" href="https://example.com" target="_blank">External Link</aithe-button>
+<aithe-button variant="primary" href="/dashboard">Go to Dashboard</aithe-button>
+<aithe-button href="https://example.com" target="_blank">External Link</aithe-button>
 ```
 
 No event listener is required — the component navigates to `href` internally by default.

package/docs/api/basic/tag.md

@@ -5,30 +5,37 @@
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
-| (default) | Default slot for tag label text. | 标签文本内容。 |
+| Name      | Description (EN)                 | Description (CN) |
+| --------- | -------------------------------- | ---------------- |
+| (default) | Default slot for tag label text. | 标签文本内容。   |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| type | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'default'` | `'default'` | Tag color variant. | 标签颜色类型。 |
-| closable | `boolean` | `false` | Whether the tag shows a close button. Clicking it animates and removes the tag from DOM. | 是否显示关闭按钮。点击后动画移除标签。 |
-| selectable | `boolean` | `false` | Whether the tag can be toggled (selected/unselected). | 是否可选中切换。 |
-| selected | `boolean` | `false` | Whether the tag is currently selected. | 当前是否选中。 |
-| rounded | `'sm' \| 'md' \| 'lg' \| 'full'` | `'full'` | Border-radius preset. | 圆角预设。 |
-| disabled | `boolean` | `false` | Whether the tag is disabled. | 是否禁用。 |
+| Name       | Type                                                                        | Default     | Description (EN)                                                                         | Description (CN)                                    |
+| ---------- | --------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| variant    | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'default'` | Color intent of the tag. Inherited from `AitheElement`. Controls semantic color.         | 标签的颜色意图。继承自 `AitheElement`。控制语义色。 |
+| type       | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'default'`              | `'success'` | _(Deprecated)_ Tag color variant. Use `variant` instead.                                 | _(已废弃)_ 标签颜色类型。请使用 `variant` 代替。    |
+| size       | `'sm' \| 'md' \| 'lg'`                                                      | `'sm'`      | Size preset of the tag.                                                                  | 标签的尺寸预设。                                    |
+| closable   | `boolean`                                                                   | `false`     | Whether the tag shows a close button. Clicking it animates and removes the tag from DOM. | 是否显示关闭按钮。点击后动画移除标签。              |
+| selectable | `boolean`                                                                   | `false`     | Whether the tag can be toggled (selected/unselected).                                    | 是否可选中切换。                                    |
+| selected   | `boolean`                                                                   | `false`     | Whether the tag is currently selected.                                                   | 当前是否选中。                                      |
+| rounded    | `'sm' \| 'md' \| 'lg' \| 'full'`                                            | `'full'`    | Border-radius preset.                                                                    | 圆角预设。                                          |
+| disabled   | `boolean`                                                                   | `false`     | Whether the tag is disabled.                                                             | 是否禁用。                                          |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-change | `{ selected }` | Emitted when selectable tag is toggled. | 选中状态变更时触发。 |
-| aithe-close | — | Emitted when the close button is clicked, before the tag is removed from DOM. | 关闭按钮点击时触发，在标签从 DOM 移除之前。 |
+| Name         | Detail         | Description (EN)                                                              | Description (CN)                            |
+| ------------ | -------------- | ----------------------------------------------------------------------------- | ------------------------------------------- |
+| aithe-change | `{ selected }` | Emitted when selectable tag is toggled.                                       | 选中状态变更时触发。                        |
+| aithe-close  | —              | Emitted when the close button is clicked, before the tag is removed from DOM. | 关闭按钮点击时触发，在标签从 DOM 移除之前。 |
 
 ## Examples / 示例
 
 ```html
-<aithe-tag type="primary" closable>Selectable Tag</aithe-tag>
-```
+<aithe-tag variant="primary" closable>Selectable Tag</aithe-tag>
+<aithe-tag variant="success">Success</aithe-tag>
+<aithe-tag variant="warning">Warning</aithe-tag>
+<aithe-tag variant="danger">Danger</aithe-tag>
+<aithe-tag size="sm">Small</aithe-tag>
+<aithe-tag size="lg">Large</aithe-tag>
+```

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

@@ -0,0 +1,73 @@
+# AitheBoxTable / AitheBoxTable 盒子表格
+
+> Dual-mode table/box data display with sorting, selection, and box grid view.
+> 双模式表格/盒子数据展示，支持排序、选择和盒子网格视图。
+
+AitheBoxTable extends AitheTable with a `mode` property. When `mode="table"`, it behaves like a standard table. When `mode="box"`, it renders records as a grid of cards using box layout.
+AitheBoxTable 扩展 AitheTable，增加 `mode` 属性。当 `mode="table"` 时，行为与标准表格一致。当 `mode="box"` 时，使用盒子布局将记录渲染为卡片网格。
+
+## Column Box Mapping / 列 Box 映射
+
+In box mode, columns with a `box` property map their data to the corresponding box slot:
+
+| box value | Box slot | Description |
+|-----------|----------|-------------|
+| `"name"` | Name/title region | 主标签/标题区域 |
+| `"status"` | Status indicator | 状态指示器区域 |
+| `"tags"` | Tags region | 标签区域 |
+| `"content"` | Content region | 内容区域 |
+| `"actions"` | Actions region | 操作按钮区域 |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+|------|------|---------|-------------------|-------------------|
+| mode | 'table' \| 'box' | 'table' | Display mode: "table" for standard table view, "box" for box grid view. | 显示模式："table" 为标准表格视图，"box" 为盒子网格视图。 |
+| boxCols | Number | 3 | Number of box columns in box mode (1–12). | 盒子模式下每行显示的盒子数（1–12）。 |
+
+All properties from `aithe-table` are also inherited (see [Table API](table.md)).
+所有 `aithe-table` 的属性也继承自（参见 [Table API](table.md)）。
+
+## Events / 事件
+
+| 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 box is clicked. | 点击 box 时触发。 |
+
+## Examples / 示例
+
+### Basic box mode / 基本盒子模式
+
+```html
+<aithe-box-table
+  mode="box"
+  box-cols="3"
+  columns='[{"id":"name","title":"Module","box":"name"},{"id":"owner","title":"Owner","box":"tags"},{"id":"status","title":"Status","box":"status"}]'
+  data='[{"id":1,"name":"Theme Engine","owner":"Design Systems","status":"Ready"},{"id":2,"name":"Component API","owner":"Frontend Platform","status":"Review"}]'
+></aithe-box-table>
+```
+
+### Box mode with selection / 盒子模式 + 选择
+
+```html
+<aithe-box-table
+  mode="box"
+  box-cols="3"
+  selectable="multi"
+  .selectionSet=${mySet}
+  columns='[{"id":"name","title":"Module","box":"name"},{"id":"status","title":"Status","box":"status"}]'
+  data='[{"id":1,"name":"Theme Engine","status":"Ready"},{"id":2,"name":"Component API","status":"Review"}]'
+></aithe-box-table>
+```
+
+### Table mode (standard) / 表格模式（标准）
+
+```html
+<aithe-box-table
+  mode="table"
+  columns='[{"id":"name","title":"Name","sortable":true},{"id":"owner","title":"Owner"}]'
+  data='[{"name":"Alice","owner":"Team A"},{"name":"Bob","owner":"Team B"}]'
+></aithe-box-table>
+```

package/docs/api/data/dropdown.md

@@ -20,14 +20,15 @@
 | itemsJson | String                                                     | ''             | JSON string of dropdown menu items.                                                                | 下拉菜单项的 JSON 字符串。                                            |
 | items     | AitheTreeNodeMeta[]                                        | []             | Array of dropdown menu item objects. Each item supports `icon` and `variant` (AitheVariant) fields. | 下拉菜单项对象数组。每项支持 `icon` 和 `variant`（AitheVariant）字段。 |
 | placement | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' | 'bottom-start' | Dropdown panel placement. Auto-adapts to viewport.                                                 | 下拉面板位置。自动适应视口。                                          |
+| 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` 的项会被隐藏。适用于权限控制。 |
 | offset    | `number`                                                   | 8              | Pixel gap between anchor and dropdown panel.                                                       | 锚点与下拉面板之间的像素间距。                                        |
 
 ## Events / 事件
 
 | Name              | Detail             | Description (EN)                      | Description (CN)     |
 | ----------------- | ------------------ | ------------------------------------- | -------------------- |
-| aithe-select      | { item, path, id } | Emitted when a menu item is selected. | 菜单项选中时触发。   |
-| aithe-open-change | { open }           | Emitted when open state changes.      | 开关状态变更时触发。 |
+| aithe-select      | `{ value, item }` | Emitted when a menu item is selected. Propagated from the inner `<aithe-tree-menu>` (composed event). `value` is the item's `id`, `item` is the full `AitheTreeNodeMeta` object. | 菜单项选中时触发。由内部 `<aithe-tree-menu>` 透传（composed 事件）。`value` 为项的 `id`，`item` 为完整的 `AitheTreeNodeMeta` 对象。 |
+| aithe-dropdown-change | { open }           | Emitted when open state changes.      | 开关状态变更时触发。 |
 
 ## Item Fields / 菜单项字段
 

package/docs/api/data/metrics.md

@@ -37,6 +37,7 @@ import '@aithe/aithe-ui/components/data/metrics';
 | 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`。 |
 
@@ -47,6 +48,7 @@ import '@aithe/aithe-ui/components/data/metrics';
 | 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.            | 指标的尺寸规格。         |

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 在表头渲染的图标名称。 |
-| variant | AitheVariant | 'default' | `variant` | Visual variant / 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" variant="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="action"
+    title="Action"
+    align="center"
+    .cellRenderer="${(key,"
+    value,
+    record)=""
+  >
+    html`
+    <aithe-button type="primary" size="sm">Edit</aithe-button>
+    `} >
+  </aithe-table-column>
 </aithe-table>
 ```