@aithe/aithe-ui 26.2.2 → 26.2.3

package/dist/components/container/split-panel.d.ts

@@ -1,20 +1,38 @@
-import { AitheElement } from '../../base/aithe-element';
+import { AitheElement } from '../../core/aithe-element';
 /**
- * Resizable two-panel layout.
+ * Resizable two-panel layout with a draggable divider.
+ * 可调整大小的双面板布局，带可拖动分隔条。
+ *
+ * @slot start - Content for the first (start) pane. 第一个（起始）面板的内容。
+ * @slot end   - Content for the second (end) pane. 第二个（末尾）面板的内容。
+ *
+ * @fires aithe-resize - Emitted when the divider is dragged with `{ value }`. 分隔条被拖动时发出 `{ value }`。
+ *
+ * @example
+ * ```html
+ * <aithe-split-panel direction="horizontal" value="40" min-size="20" max-size="80">
+ *   <div slot="start">Left pane</div>
+ *   <div slot="end">Right pane</div>
+ * </aithe-split-panel>
+ * ```
  */
 export declare class AitheSplitPanel extends AitheElement {
+    /** Layout direction of the split. 分割布局的方向。 */
     direction: 'horizontal' | 'vertical';
+    /** Minimum size of the start pane as a percentage. 起始面板的最小百分比尺寸。 */
     minSize: number;
+    /** Maximum size of the start pane as a percentage. 起始面板的最大百分比尺寸。 */
     maxSize: number;
+    /** Current split position as a percentage (0–100). 当前分割位置百分比（0–100）。 */
     value: number;
     private dragging;
     static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected updated(): void;
-    private handlePointerDown;
-    private handlePointerMove;
-    private handlePointerUp;
+    private readonly handlePointerDown;
+    private readonly handlePointerMove;
+    private readonly handlePointerUp;
     render(): import("lit-html").TemplateResult<1>;
 }
 //# sourceMappingURL=split-panel.d.ts.map

package/dist/components/container/split-panel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"split-panel.d.ts","sourceRoot":"","sources":["../../../src/components/container/split-panel.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD;;GAEG;AACH,qBACa,eAAgB,SAAQ,YAAY;IACnB,SAAS,EAAE,YAAY,GAAG,UAAU,CAAgB;IAC7B,OAAO,SAAM;IACb,OAAO,SAAM;IACpC,KAAK,SAAM;IAE9B,OAAO,CAAC,QAAQ,CAAS;IAElC,MAAM,CAAC,QAAQ,CAAC,MAAM,0DA4CpB;IAEF,iBAAiB,IAAI,IAAI;IAMzB,oBAAoB,IAAI,IAAI;IAM5B,SAAS,CAAC,OAAO,IAAI,IAAI;IAIzB,OAAO,CAAC,iBAAiB,CAEvB;IAEF,OAAO,CAAC,iBAAiB,CAavB;IAEF,OAAO,CAAC,eAAe,CAErB;IAEF,MAAM;CAcP"}
+{"version":3,"file":"split-panel.d.ts","sourceRoot":"","sources":["../../../src/components/container/split-panel.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD;;;;;;;;;;;;;;;;GAgBG;AACH,qBACa,eAAgB,SAAQ,YAAY;IAC/C,8CAA8C;IAClB,SAAS,EAAE,YAAY,GAAG,UAAU,CAAgB;IAChF,oEAAoE;IACjB,OAAO,SAAM;IAChE,oEAAoE;IACjB,OAAO,SAAM;IAChE,wEAAwE;IAC5C,KAAK,SAAM;IAE9B,OAAO,CAAC,QAAQ,CAAS;IAElC,MAAM,CAAC,QAAQ,CAAC,MAAM,0DA4CpB;IAEF,iBAAiB,IAAI,IAAI;IAMzB,oBAAoB,IAAI,IAAI;IAM5B,SAAS,CAAC,OAAO,IAAI,IAAI;IAIzB,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAEhC;IAEF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAahC;IAEF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAE9B;IAEF,MAAM;CAcP"}

package/dist/components/data/AGENTS.md

@@ -0,0 +1,34 @@
+# src/components/data/ — 数据展示组件（12个）
+
+## 组件列表
+
+| 组件               | 标签                    | 说明                     |
+| ------------------ | ----------------------- | ------------------------ |
+| `table.ts`         | `<aithe-table>`         | 数据表格，支持排序和选择 |
+| `table-column.ts`  | `<aithe-table-column>`  | 表格列定义               |
+| `tabs.ts`          | `<aithe-tabs>`          | 标签页导航容器           |
+| `tab-pane.ts`      | `<aithe-tab-pane>`      | 单个标签页内容面板       |
+| `tree.ts`          | `<aithe-tree>`          | 树形控件                 |
+| `tree-menu.ts`     | `<aithe-tree-menu>`     | 树形导航菜单             |
+| `timeline.ts`      | `<aithe-timeline>`      | 时间线容器               |
+| `timeline-item.ts` | `<aithe-timeline-item>` | 单个时间线节点           |
+| `pagination.ts`    | `<aithe-pagination>`    | 分页导航                 |
+| `dropdown.ts`      | `<aithe-dropdown>`      | 下拉菜单浮层             |
+| `metrics.ts`       | `<aithe-metrics>`       | 业务指标展示             |
+| `metrics-group.ts` | `<aithe-metrics-group>` | 业务指标组容器           |
+
+## 编码规范
+
+- 继承 `AitheElement`，使用 `@customElement` 装饰器
+- 数据组件通常通过 `data` 属性接收数据，支持响应式更新
+- 导入使用 `@components/data/xxx` 路径别名
+- 中英文双语 JSDoc 注释
+
+## 关键约定
+
+- `aithe-table` + `aithe-table-column` 配合使用，通过列模板定义渲染
+- `aithe-tabs` + `aithe-tab-pane` 配合使用，通过 `active-key` 控制当前标签
+- `aithe-tree` 通过 `data` 属性传入树形数据结构
+- `aithe-timeline` 支持数据驱动模式（通过 `items` 属性）和插槽模式
+- `aithe-dropdown` 依赖 `anchored-overlay` 实现浮层定位，内部使用 `aithe-tree-menu` 渲染菜单
+- 新增组件需同步更新 `src/index.ts` 和 `docs/api/data/`

package/dist/components/data/dropdown.d.ts

@@ -0,0 +1,56 @@
+import type { PropertyValues } from 'lit';
+import { AitheAnchoredOverlayElement } from '../../core/anchored-overlay';
+import type { AitheTreeNodeMeta } from '../../core/types';
+/**
+ * Dropdown menu with nested submenus, keyboard navigation, and hover/click triggers.
+ * Internally uses `<aithe-tree-menu>` for menu rendering.
+ * 下拉菜单，支持嵌套子菜单、键盘导航和悬停/点击触发。内部使用 `<aithe-tree-menu>` 渲染菜单。
+ *
+ * @slot - Default slot for the trigger element. 触发元素内容。
+ * @fires aithe-select - Emitted when a menu item is selected, with `{ item, path, id }`. 菜单项选中时触发。
+ * @fires aithe-open-change - Emitted when open state changes, with `{ open }`. 开关状态变更时触发。
+ * @example
+ * ```html
+ * <aithe-dropdown trigger="click" items='[{"id":"a","label":"Action"},{"id":"b","label":"Another"}]'>
+ *   <button>Menu</button>
+ * </aithe-dropdown>
+ * ```
+ */
+export declare class AitheDropdown extends AitheAnchoredOverlayElement {
+    /** Trigger mode: click or hover. 触发方式：点击或悬停。 */
+    trigger: 'click' | 'hover';
+    /** Display title for the dropdown trigger (shown as tooltip). 下拉菜单触发器的显示标题（作为工具提示）。 */
+    title: string;
+    /** Icon name to display before the trigger slot content. 在触发器插槽内容前显示的图标名称。 */
+    icon: string;
+    /** JSON string of dropdown menu items. 下拉菜单项的 JSON 字符串。 */
+    itemsJson: string;
+    /** Array of dropdown menu item objects. 下拉菜单项对象数组。 */
+    items: readonly AitheTreeNodeMeta[];
+    /** Dropdown panel placement. 下拉面板位置。 */
+    placement: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+    private readonly panel?;
+    private activeId;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
+    protected get panelElement(): HTMLElement | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues<this>): void;
+    /** Closes dropdown on outside pointer events. 点击外部时关闭下拉菜单。 */
+    private readonly handleOutsidePointer;
+    /** Closes dropdown on Escape key. 按 Escape 键关闭下拉菜单。 */
+    private readonly handleDocumentKeydown;
+    /** Toggles dropdown open state (click trigger only). 切换下拉菜单开关状态（仅点击触发）。 */
+    private readonly toggleOpen;
+    /** Opens dropdown on hover (hover trigger only). 悬停时打开下拉菜单（仅悬停触发）。 */
+    private readonly openOnHover;
+    /** Closes dropdown on hover end (hover trigger only). 悬停结束时关闭下拉菜单（仅悬停触发）。 */
+    private readonly closeOnHoverEnd;
+    /** Handles item selection from the tree-menu and emits aithe-select. 处理 tree-menu 的选中事件并触发 aithe-select。 */
+    private readonly handleTreeSelect;
+    /** Recursively finds an item by id. 递归查找指定 id 的菜单项。 */
+    private findItemById;
+    render(): import("lit-html").TemplateResult<1>;
+}
+//# sourceMappingURL=dropdown.d.ts.map

package/dist/components/data/dropdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dropdown.d.ts","sourceRoot":"","sources":["../../../src/components/data/dropdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AAI1C,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAG1D;;;;;;;;;;;;;;GAcG;AACH,qBACa,aAAc,SAAQ,2BAA2B;IAC5D,gDAAgD;IACpB,OAAO,EAAE,OAAO,GAAG,OAAO,CAAW;IACjE,uFAAuF;IAC3D,KAAK,SAAM;IACvC,8EAA8E;IAClD,IAAI,SAAM;IACtC,2DAA2D;IACX,SAAS,SAAM;IAC/D,sDAAsD;IACtB,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAM;IACzE,wCAAwC;IACZ,SAAS,EAAE,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,CAC7E;IAEA,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAc;IAE7C,OAAO,CAAC,QAAQ,CAAM;IAE/B,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAUzD,MAAM,CAAC,QAAQ,CAAC,MAAM,0DA+BpB;IAEF,SAAS,KAAK,YAAY,IAAI,WAAW,GAAG,IAAI,CAE/C;IAED,iBAAiB,IAAI,IAAI;IAMzB,oBAAoB,IAAI,IAAI;IAM5B,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAYtD,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAYnC;IAEF,uDAAuD;IACvD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAIpC;IAEF,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAIzB;IAEF,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAI1B;IAEF,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAI9B;IAEF,4GAA4G;IAC5G,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAO/B;IAEF,uDAAuD;IACvD,OAAO,CAAC,YAAY;IAcpB,MAAM;CAkCP"}

package/dist/components/data/metrics-group.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @file Metrics group container component / 业务指标组容器组件
+ * @description Container that lays out multiple `<aithe-metrics>` children with configurable
+ *              direction (horizontal/vertical) and gap. Supports data-driven mode via the
+ *              inherited `params` and `data` properties from AitheWidget.
+ *              `params` takes precedence over individual properties for overlapping fields.
+ *              容器组件，以水平或垂直方向排列多个 `<aithe-metrics>` 子元素，支持自定义间距。
+ *              通过 AitheWidget 继承的 `params` 和 `data` 属性支持数据驱动模式，
+ *              `params` 中同名字段优先级高于独立属性。
+ */
+import { type TemplateResult } from 'lit';
+import { AitheWidget } from '../../core/aithe-widget';
+import type { MetricsData } from './metrics';
+export type MetricsGroupDirection = 'horizontal' | 'vertical';
+export type MetricsGroupAlign = 'left' | 'center' | 'right';
+export interface MetricsGroupParams {
+    /** Layout direction of the metrics group. 指标组的排列方向。 */
+    direction?: MetricsGroupDirection;
+    /** Gap between metrics items, in pixels. 指标项之间的间距，单位为像素。 */
+    gap?: number;
+    /** Alignment of metrics items within the group. Only takes effect when direction is vertical. 指标项在组内的对齐方式。仅在垂直布局时生效。 */
+    align?: MetricsGroupAlign;
+}
+/**
+ * A container component that groups multiple `<aithe-metrics>` children with
+ * configurable layout direction and gap. Useful for dashboard panel content areas
+ * where several metrics need to be displayed side by side or stacked.
+ *
+ * Inherits from AitheWidget, using `params` for layout configuration (direction, gap, align)
+ * and `data` for metric items. `params` fields take precedence over individual properties.
+ * `data` accepts both a single MetricsData object and an array; a single object is
+ * automatically wrapped into a one-element array.
+ *
+ * 业务指标组容器组件。以水平或垂直方向排列多个 `<aithe-metrics>` 子元素，支持自定义间距。
+ * 适用于仪表盘面板内容区，需要并排或堆叠展示多个指标的场景。
+ *
+ * 继承自 AitheWidget，`params` 用于布局配置（direction, gap, align），
+ * `data` 用于指标数据。`params` 同名字段优先级高于独立属性。
+ * `data` 支持单个 MetricsData 对象或数组，传入对象时自动转为单元素数组。
+ *
+ * @slot - One or more `<aithe-metrics>` elements. 一个或多个 `<aithe-metrics>` 元素。
+ *
+ * @csspart container - The flex container wrapping the metrics. 包裹指标的 flex 容器。
+ *
+ * @example
+ * ```html
+ * <!-- Slot mode -->
+ * <aithe-metrics-group direction="horizontal" gap="32">
+ *   <aithe-metrics label="Users" value="1,024" variant="primary"></aithe-metrics>
+ *   <aithe-metrics label="Revenue" value="$42.5K" variant="success"></aithe-metrics>
+ * </aithe-metrics-group>
+ * ```
+ *
+ * @example
+ * ```js
+ * // Data-driven mode
+ * const el = document.querySelector('aithe-metrics-group');
+ * el.params = { direction: 'horizontal', gap: 24 };
+ * el.data = [
+ *   { label: 'Users', value: '1,024', variant: 'primary' },
+ *   { label: 'Revenue', value: '$42.5K', variant: 'success' },
+ * ];
+ * ```
+ */
+export declare class AitheMetricsGroup extends AitheWidget {
+    /**
+     * Layout direction of the metrics group.
+     * 指标组的排列方向。
+     *
+     * @default 'horizontal'
+     */
+    direction: MetricsGroupDirection;
+    /**
+     * Gap between metrics items, in pixels.
+     * 指标项之间的间距，单位为像素。
+     *
+     * @default 16
+     */
+    gap: number;
+    /**
+     * Alignment of metrics items within the group. Only takes effect when direction is vertical.
+     * 指标项在组内的对齐方式。仅在垂直布局时生效。
+     *
+     * @default 'left'
+     */
+    align: MetricsGroupAlign;
+    /**
+     * Generic configuration object. Fields with the same name as the component's
+     * individual properties take precedence when both are set.
+     * 通用配置对象。与组件独立属性同名的字段优先级更高。
+     */
+    params: MetricsGroupParams;
+    /**
+     * Generic data object or array. When set to MetricsData or MetricsData[],
+     * the component automatically renders `<aithe-metrics>` children.
+     * A single MetricsData object is wrapped into a one-element array.
+     * 通用数据对象或数组。设置为 MetricsData 或 MetricsData[] 时，
+     * 组件自动渲染 `<aithe-metrics>` 子元素。单个对象自动转为单元素数组。
+     */
+    data: MetricsData | MetricsData[] | null;
+    private readonly _containerRef;
+    static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'aithe-metrics-group': AitheMetricsGroup;
+    }
+}
+//# sourceMappingURL=metrics-group.d.ts.map

package/dist/components/data/metrics-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-group.d.ts","sourceRoot":"","sources":["../../../src/components/data/metrics-group.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAKrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,UAAU,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wHAAwH;IACxH,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBACa,iBAAkB,SAAQ,WAAW;IAChD;;;;;OAKG;IACyB,SAAS,EAAE,qBAAqB,CAAgB;IAE5E;;;;;OAKG;IACyB,GAAG,SAAM;IAErC;;;;;OAKG;IACyB,KAAK,EAAE,iBAAiB,CAAU;IAE9D;;;;OAIG;IACkC,MAAM,EAAE,kBAAkB,CAAM;IAErE;;;;;;OAMG;IACkC,IAAI,EAAE,WAAW,GAAG,WAAW,EAAE,GAAG,IAAI,CAAQ;IAErF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;IAElE,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAkBpB;IAEO,MAAM,IAAI,cAAc;CA6ClC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,qBAAqB,EAAE,iBAAiB,CAAC;KAC1C;CACF"}

package/dist/components/data/metrics.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @file Metrics display component / 业务指标展示组件
+ * @description Displays a business metric with label, value, and an optional slot for custom content.
+ *              Supports variant-based color styling for the value, an optional divider,
+ *              and data-driven mode via the inherited `params` and `data` properties from AitheWidget.
+ *              `params` takes precedence over `data` for overlapping fields.
+ *              展示业务指标，含标签、数值和可选的自定义内容插槽。数值支持基于 variant 的颜色样式，
+ *              支持可选分割线。通过 AitheWidget 继承的 `params` 和 `data` 属性支持数据驱动模式，
+ *              `params` 中同名字段优先级高于 `data`。
+ */
+import { type TemplateResult } from 'lit';
+import { AitheWidget } from '../../core/aithe-widget';
+import type { AitheVariant } from '../../types';
+export type MetricsAlign = 'left' | 'center' | 'right';
+export type MetricsScale = 'small' | 'normal' | 'large';
+export interface MetricsData {
+    /** Metric label text. 指标标签文本。 */
+    label?: string;
+    /** Metric value text. 指标数值文本。 */
+    value?: string;
+    /** Visual variant / semantic color for the value text. 数值文本的视觉变体/语义色。 */
+    variant?: AitheVariant;
+    /** Whether to show a divider. 是否显示分割线。 */
+    showDivider?: boolean;
+    /** Text alignment of the metric content. 指标内容的对齐方式。 */
+    align?: MetricsAlign;
+    /** Size scale of the metric. 指标的尺寸规格。 */
+    scale?: MetricsScale;
+}
+/**
+ * A business metrics display component. Renders a value with optional slot content
+ * on top and a label below, suitable for dashboard panels and statistic cards.
+ *
+ * Inherits from AitheWidget, using `params` for layout configuration (align, scale, showDivider)
+ * and `data` for content (label, value, variant). `params` only overrides layout fields
+ * (align, scale, showDivider); content fields (label, value, variant) are always read from
+ * `data` first, falling back to the component's own properties. `data` accepts both a single
+ * MetricsData object and an array; when an array is provided, only the first item is used.
+ *
+ * 业务指标展示组件。上方渲染数值和可选的插槽内容，下方渲染标签，适用于仪表盘面板和统计卡片。
+ *
+ * 继承自 AitheWidget，`params` 用于布局配置（align, scale, showDivider），
+ * `data` 用于内容数据（label, value, variant）。`params` 仅覆盖布局字段
+ * （align, scale, showDivider）；内容字段（label, value, variant）始终优先从 `data` 读取，
+ * 再回退到组件自身属性。`data` 支持单个 MetricsData 对象或数组，传入数组时仅取第一个元素。
+ *
+ * @slot - Custom content displayed next to the value. 显示在数值旁边的自定义内容。
+ *
+ * @csspart value - The metric value element. 指标数值元素。
+ * @csspart label - The metric label element. 指标标签元素。
+ * @csspart divider - The divider element (shown when showDivider is true). 分割线元素。
+ *
+ * @example
+ * ```html
+ * <!-- Attribute mode -->
+ * <aithe-metrics label="Active Users" value="1,024" variant="primary"></aithe-metrics>
+ * ```
+ *
+ * @example
+ * ```html
+ * <!-- Data-driven mode with slot content -->
+ * <aithe-metrics label="Revenue" value="$42.5K" variant="success">
+ *   <aithe-icon name="arrowUp" size="16"></aithe-icon>
+ * </aithe-metrics>
+ * ```
+ *
+ * @example
+ * ```js
+ * // Programmatic mode with params and data
+ * const el = document.querySelector('aithe-metrics');
+ * el.params = { align: 'center', scale: 'large', showDivider: true };
+ * el.data = { label: 'Users', value: '1,024', variant: 'primary' };
+ * ```
+ */
+export declare class AitheMetrics extends AitheWidget {
+    /** Metric label text displayed below the value. 显示在数值下方的标签文本。 */
+    label: string;
+    /** Metric value text displayed prominently. 突出显示的数值文本。 */
+    value: string;
+    /**
+     * Whether to show a divider on the left side.
+     * 是否在左侧显示分割线。由 params / data 驱动，仅用于 CSS 反射。
+     *
+     * @internal
+     */
+    showDivider: boolean;
+    /**
+     * Text alignment of the metric content. Reflected for CSS selectors.
+     * 指标内容的对齐方式。由 params / data 驱动，仅用于 CSS 反射。
+     *
+     * @internal
+     */
+    align: MetricsAlign;
+    /**
+     * Size scale of the metric. Reflected for CSS selectors.
+     * 指标的尺寸规格。由 params / data 驱动，仅用于 CSS 反射。
+     *
+     * @internal
+     */
+    scale: MetricsScale;
+    /**
+     * Generic configuration object. Fields with the same name as MetricsData
+     * take precedence over `data` when both are set.
+     * 通用配置对象。与 MetricsData 同名的字段优先级高于 `data`。
+     */
+    params: MetricsData;
+    /**
+     * Generic data object. Fields with the same name in `params` take precedence.
+     * 通用数据对象。同名时 `params` 中的值优先。
+     */
+    data: MetricsData | MetricsData[] | null;
+    static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'aithe-metrics': AitheMetrics;
+    }
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/components/data/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/components/data/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAKrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE3C,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AACvD,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExD,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uDAAuD;IACvD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,yCAAyC;IACzC,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBACa,YAAa,SAAQ,WAAW;IAC3C,iEAAiE;IACrC,KAAK,SAAM;IAEvC,0DAA0D;IAC9B,KAAK,SAAM;IAEvC;;;;;OAKG;IACoE,WAAW,UAAS;IAE3F;;;;;OAKG;IACwC,KAAK,EAAE,YAAY,CAAY;IAE1E;;;;;OAKG;IACwC,KAAK,EAAE,YAAY,CAAW;IAEzE;;;;OAIG;IACkC,MAAM,EAAE,WAAW,CAAM;IAE9D;;;OAGG;IACkC,IAAI,EAAE,WAAW,GAAG,WAAW,EAAE,GAAG,IAAI,CAAQ;IAErF,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAwIpB;IAEO,MAAM,IAAI,cAAc;CAwClC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,eAAe,EAAE,YAAY,CAAC;KAC/B;CACF"}

package/dist/components/data/pagination.d.ts

@@ -1,11 +1,23 @@
-import { AitheElement } from '../../base/aithe-element';
+import { AitheElement } from '../../core/aithe-element';
 /**
- * Pagination controller.
+ * Pagination controller for navigating through paged data.
+ * 分页控制器，用于浏览分页数据。
+ *
+ * @fires aithe-page-change - Emitted when the current page changes with `{ currentPage, pageSize }`. 当前页变更时发出 `{ currentPage, pageSize }`。
+ *
+ * @example
+ * ```html
+ * <aithe-pagination total="100" page-size="10" current-page="1"></aithe-pagination>
+ * ```
  */
 export declare class AithePagination extends AitheElement {
+    /** Total number of data items. 数据项总数。 */
     total: number;
+    /** Number of items per page. 每页的数据项数。 */
     pageSize: number;
+    /** Currently active page number. 当前活动页码。 */
     currentPage: number;
+    /** Size scale of the pagination buttons. 分页按钮的尺寸规格。 */
     size: 'sm' | 'md' | 'lg';
     static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
     private get pageCount();

package/dist/components/data/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/components/data/pagination.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD;;GAEG;AACH,qBACa,eAAgB,SAAQ,YAAY;IACnB,KAAK,SAAK;IACc,QAAQ,SAAM;IACX,WAAW,SAAK;IAC3C,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAE5D,MAAM,CAAC,QAAQ,CAAC,MAAM,0DA+BpB;IAEF,OAAO,KAAK,SAAS,GAEpB;IAED,OAAO,CAAC,MAAM;IAKd,MAAM;CA2BP"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/components/data/pagination.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD;;;;;;;;;;GAUG;AACH,qBACa,eAAgB,SAAQ,YAAY;IAC/C,yCAAyC;IACb,KAAK,SAAK;IACtC,yCAAyC;IACW,QAAQ,SAAM;IAClE,4CAA4C;IACW,WAAW,SAAK;IACvE,uDAAuD;IAC3B,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAE5D,MAAM,CAAC,QAAQ,CAAC,MAAM,0DA+BpB;IAEF,OAAO,KAAK,SAAS,GAEpB;IAED,OAAO,CAAC,MAAM;IAKd,MAAM;CA+BP"}

package/dist/components/data/tab-pane.d.ts

@@ -1,9 +1,31 @@
 import { AitheElement } from '../../core/aithe-element';
+/**
+ * Single tab pane used inside `aithe-tabs`.
+ * 单个标签面板，用于 `aithe-tabs` 内部。
+ *
+ * @slot - Default slot for tab pane content. 默认插槽，用于标签面板内容。
+ *
+ * @example
+ * ```html
+ * <aithe-tab-pane tab-id="settings" label="Settings" closable>
+ *   Settings content here
+ * </aithe-tab-pane>
+ * ```
+ */
 export declare class AitheTabPane extends AitheElement {
-    tabKey: string;
+    /** Unique identifier for this pane within the tabs. 标签页内标识此面板的唯一标识。 */
+    tabId: string;
+    /** Display label shown on the tab button. 标签按钮上显示的文本。 */
     label: string;
+    /** Icon name to display before the tab label. 在标签文本前显示的图标名称。 */
+    icon: string;
+    /** Display title for the tab pane (shown as tooltip). 标签面板的显示标题（作为工具提示）。 */
+    title: string;
+    /** Whether this tab pane is disabled (cannot be activated). 此标签面板是否禁用（无法激活）。 */
     disabled: boolean;
+    /** Whether this tab pane shows a close button. 此标签面板是否显示关闭按钮。 */
     closable: boolean;
+    /** Whether this tab pane is currently active (managed by parent `aithe-tabs`). 此标签面板是否当前活动（由父级 `aithe-tabs` 管理）。 */
     active: boolean;
     static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
     render(): import("lit-html").TemplateResult<1>;

package/dist/components/data/tab-pane.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tab-pane.d.ts","sourceRoot":"","sources":["../../../src/components/data/tab-pane.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD,qBACa,YAAa,SAAQ,YAAY;IACM,MAAM,SAAM;IAClC,KAAK,SAAM;IACK,QAAQ,UAAS;IACjB,QAAQ,UAAS;IACjB,MAAM,UAAS;IAE3D,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAWpB;IAEF,MAAM;CAGP"}
+{"version":3,"file":"tab-pane.d.ts","sourceRoot":"","sources":["../../../src/components/data/tab-pane.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD;;;;;;;;;;;;GAYG;AACH,qBACa,YAAa,SAAQ,YAAY;IAC5C,uEAAuE;IACtB,KAAK,SAAM;IAC5D,yDAAyD;IAC7B,KAAK,SAAM;IACvC,gEAAgE;IACpC,IAAI,SAAM;IACtC,4EAA4E;IAChD,KAAK,SAAM;IACvC,gFAAgF;IACpC,QAAQ,UAAS;IAC7D,iEAAiE;IACrB,QAAQ,UAAS;IAC7D,oHAAoH;IACxE,MAAM,UAAS;IAE3D,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAWpB;IAEF,MAAM;CAKP"}

package/dist/components/data/table-column.d.ts

@@ -0,0 +1,46 @@
+import { LitElement } from 'lit';
+import type { AitheVariant } from '../../types';
+type CellRenderer = (value: unknown, record: Record<string, unknown>, rowIndex: number) => unknown;
+/**
+ * Column definition element for `aithe-table` (DOM-defined mode).
+ * `aithe-table` 的列定义元素（DOM 定义模式）。
+ *
+ * Place `<aithe-table-column>` elements as children of `<aithe-table>` to define columns declaratively.
+ * 将 `<aithe-table-column>` 元素作为 `<aithe-table>` 的子元素放置，以声明式定义列。
+ *
+ * @example
+ * ```html
+ * <aithe-table .data=${records}>
+ *   <aithe-table-column id="name" title="Name" sortable></aithe-table-column>
+ *   <aithe-table-column id="action" title="Action" .cellRenderer=${(v, r, i) => html`<button>Edit</button>`}></aithe-table-column>
+ * </aithe-table>
+ * ```
+ */
+export declare class AitheTableColumn extends LitElement {
+    /** Unique column identifier. 唯一列标识。 */
+    id: string;
+    /** Header title. 表头标题。 */
+    title: string;
+    /** Property path on the data record. 数据记录上的属性路径。 */
+    dataIndex: string;
+    /** Fixed column width. 固定列宽。 */
+    width: string;
+    /** Text alignment. 文本对齐方式。 */
+    align: 'left' | 'center' | 'right';
+    /** Enable client-side sorting. 启用客户端排序。 */
+    sortable: boolean;
+    /** Icon name rendered in the header via aithe-icon. 通过 aithe-icon 在表头渲染的图标名称。 */
+    icon: string;
+    /** Visual variant / semantic color for the column. 列的视觉变体/语义色。 */
+    variant: AitheVariant;
+    /** Custom cell renderer (only available in DOM-defined mode). 自定义单元格渲染器（仅在 DOM 定义模式下可用）。 */
+    cellRenderer?: CellRenderer;
+    connectedCallback(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'aithe-table-column': AitheTableColumn;
+    }
+}
+export {};
+//# sourceMappingURL=table-column.d.ts.map

package/dist/components/data/table-column.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-column.d.ts","sourceRoot":"","sources":["../../../src/components/data/table-column.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAGjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE3C,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;AAEnG;;;;;;;;;;;;;;GAcG;AACH,qBACa,gBAAiB,SAAQ,UAAU;IAC9C,uCAAuC;IACX,EAAE,SAAM;IACpC,0BAA0B;IACE,KAAK,SAAM;IACvC,oDAAoD;IACxB,SAAS,SAAM;IAC3C,gCAAgC;IACJ,KAAK,SAAM;IACvC,8BAA8B;IACF,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAU;IACxE,2CAA2C;IACd,QAAQ,UAAS;IAC9C,iFAAiF;IACrD,IAAI,SAAM;IACtC,kEAAkE;IACtC,OAAO,EAAE,YAAY,CAAa;IAC9D,4FAA4F;IAC5D,YAAY,CAAC,EAAE,YAAY,CAAC;IAEnD,iBAAiB,IAAI,IAAI;CAInC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,oBAAoB,EAAE,gBAAgB,CAAC;KACxC;CACF"}

package/dist/components/data/table.d.ts

@@ -1,19 +1,75 @@
 import { AitheElement } from '../../core/aithe-element';
-import type { AitheTableColumn } from '../../core/types';
+import type { AitheTableColumnMeta } from '../../core/types';
+import './table-column';
 type TableRecord = Record<string, unknown>;
+/**
+ * Data table with sorting, row selection, and striped/bordered styling.
+ * 数据表格，支持排序、行选择以及斑马纹/边框样式。
+ *
+ * Supports two column definition modes:
+ * 支持两种列定义模式：
+ * - **Data-driven**: Set `columns` / `columns-json` attribute (no render function).
+ *   **数据驱动**：设置 `columns` / `columns-json` 属性（无渲染函数）。
+ * - **DOM-defined**: Place `<aithe-table-column>` children (supports `cellRenderer` for custom rendering).
+ *   **DOM 定义**：放置 `<aithe-table-column>` 子元素（支持 `cellRenderer` 自定义渲染）。
+ *
+ * @slot empty - Content shown when the table has no data. 无数据时显示的内容。
+ * @slot - Default slot for `<aithe-table-column>` children. 用于 `<aithe-table-column>` 子元素的默认插槽。
+ *
+ * @fires aithe-sort-change    - Emitted when a sortable column header is clicked with `{ sortKey, sortOrder }`. 可排序列头被点击时发出 `{ sortKey, sortOrder }`。
+ * @fires aithe-selection-change - Emitted when row selection changes with `{ selectedKeys }`. 行选择变更时发出 `{ selectedKeys }`。
+ * @fires aithe-row-click      - Emitted when a row is clicked with `{ record, rowIndex }`. 行被点击时发出 `{ record, rowIndex }`。
+ *
+ * @example Data-driven mode / 数据驱动模式
+ * ```html
+ * <aithe-table
+ *   columns-json='[{"id":"name","title":"Name","sortable":true}]'
+ *   data-json='[{"name":"Alice"},{"name":"Bob"}]'
+ *   striped
+ *   selectable
+ * ></aithe-table>
+ * ```
+ *
+ * @example DOM-defined mode / DOM 定义模式
+ * ```html
+ * <aithe-table .data=${records} striped>
+ *   <aithe-table-column id="name" title="Name" sortable></aithe-table-column>
+ *   <aithe-table-column id="action" title="Action"
+ *     .cellRenderer=${(v, r, i) => html`<button @click=${() => edit(i)}>Edit</button>`}
+ *   ></aithe-table-column>
+ * </aithe-table>
+ * ```
+ */
 export declare class AitheTable extends AitheElement {
+    /** JSON string of column definitions (parsed into `columns`). 列定义的 JSON 字符串（解析为 `columns`）。 */
     columnsJson: string;
-    columns: AitheTableColumn<TableRecord>[];
+    /** Array of column definitions (prefer this over `columnsJson` in JS). 列定义数组（在 JS 中优先使用此属性而非 `columnsJson`）。 */
+    columns: AitheTableColumnMeta<TableRecord>[];
+    /** JSON string of row data (parsed into `data`). 行数据的 JSON 字符串（解析为 `data`）。 */
     dataJson: string;
+    /** Array of row data (prefer this over `dataJson` in JS). 行数据数组（在 JS 中优先使用此属性而非 `dataJson`）。 */
     data: TableRecord[];
+    /** Unique key field for each row. 每行的唯一键字段。 */
     rowKey: string;
+    /** Whether rows use alternating background colors. 行是否使用交替背景色。 */
     striped: boolean;
+    /** Whether cells have vertical border lines. 单元格是否有垂直边框线。 */
     bordered: boolean;
+    /** Whether rows highlight on hover. 行是否在悬停时高亮。 */
     hoverable: boolean;
+    /** Whether rows can be selected via checkboxes. 行是否可通过复选框选择。 */
     selectable: boolean;
+    /** Current sort column key. 当前排序的列键。 */
     sortKey: string;
+    /** Current sort direction. 当前排序方向。 */
     sortOrder: 'asc' | 'desc' | '';
     private selectedKeys;
+    private slotColumns;
+    private get resolvedColumns();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private slotObserver?;
+    private syncSlotColumns;
     protected willUpdate(changed: Map<string, unknown>): void;
     static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
     private get rowData();
@@ -24,6 +80,8 @@ export declare class AitheTable extends AitheElement {
     private toggleRowSelection;
     private toggleAllRows;
     private renderCell;
+    private getSortIcon;
+    private renderColumnHeader;
     render(): import("lit-html").TemplateResult<1>;
 }
 export {};

package/dist/components/data/table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/components/data/table.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAIzD,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE3C,qBACa,UAAW,SAAQ,YAAY;IACQ,WAAW,SAAM;IACnC,OAAO,EAAE,gBAAgB,CAAC,WAAW,CAAC,EAAE,CAAM;IAC/B,QAAQ,SAAM;IAC7B,IAAI,EAAE,WAAW,EAAE,CAAM;IACP,MAAM,SAAQ;IACnC,OAAO,UAAS;IAChB,QAAQ,UAAQ;IACQ,SAAS,UAAQ;IACzC,UAAU,UAAS;IACG,OAAO,SAAM;IACX,SAAS,EAAE,KAAK,GAAG,MAAM,GAAG,EAAE,CAAM;IAEhF,OAAO,CAAC,YAAY,CAAgB;IAE7C,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAkBzD,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAkFpB;IAEF,OAAO,KAAK,OAAO,GAsBlB;IAED,OAAO,KAAK,UAAU,GAErB;IAED,OAAO,KAAK,gBAAgB,GAE3B;IAED,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,UAAU;IAuBlB,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,UAAU;IAKlB,MAAM;CAsGP"}
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["../../../src/components/data/table.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAIxD,OAAO,gBAAgB,CAAC;AAExB,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAa3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBACa,UAAW,SAAQ,YAAY;IAC1C,+FAA+F;IAC7C,WAAW,SAAM;IACnE,gHAAgH;IAChF,OAAO,EAAE,oBAAoB,CAAC,WAAW,CAAC,EAAE,CAAM;IAClF,+EAA+E;IAChC,QAAQ,SAAM;IAC7D,gGAAgG;IAChE,IAAI,EAAE,WAAW,EAAE,CAAM;IACzD,+CAA+C;IACG,MAAM,SAAQ;IAChE,kEAAkE;IACrC,OAAO,UAAS;IAC7C,6DAA6D;IAChC,QAAQ,UAAQ;IAC7C,kDAAkD;IACG,SAAS,UAAQ;IACtE,gEAAgE;IACnC,UAAU,UAAS;IAChD,wCAAwC;IACW,OAAO,SAAM;IAChE,sCAAsC;IACe,SAAS,EAAE,KAAK,GAAG,MAAM,GAAG,EAAE,CAAM;IAEhF,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,WAAW,CAA2C;IAEvE,OAAO,KAAK,eAAe,GAK1B;IAEQ,iBAAiB,IAAI,IAAI;IAOzB,oBAAoB,IAAI,IAAI;IAKrC,OAAO,CAAC,YAAY,CAAC,CAAmB;IAExC,OAAO,CAAC,eAAe;IA4CvB,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAkBzD,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAoGpB;IAEF,OAAO,KAAK,OAAO,GAsBlB;IAED,OAAO,KAAK,UAAU,GAErB;IAED,OAAO,KAAK,gBAAgB,GAE3B;IAED,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,UAAU;IAuBlB,OAAO,CAAC,kBAAkB;IAc1B,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,kBAAkB;IAqB1B,MAAM;CAsGP"}