@aithe/aithe-ui 26.2.2 → 26.2.3

package/dist/styles/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Built-in typo (typography) style options.
+ * 内置排版风格选项。
+ */
+export type AitheBuiltinTypo = 'minimal' | 'business' | 'luxury' | 'compact';
+/**
+ * Typo style name — either a built-in value or a custom string.
+ * 排版风格名称 — 内置值或自定义字符串。
+ */
+export type AitheTypoName = AitheBuiltinTypo | string;
+/**
+ * Built-in layout density options.
+ * 内置布局密度选项。
+ */
+export type AitheBuiltinLayout = 'compact' | 'medium' | 'wide';
+/**
+ * Layout density name — either a built-in value or a custom string.
+ * 布局密度名称 — 内置值或自定义字符串。
+ */
+export type AitheLayoutName = AitheBuiltinLayout | string;
+/**
+ * Built-in shadow style options.
+ * 内置阴影风格选项。
+ */
+export type AitheBuiltinShadow = 'flat' | 'neumorphism' | 'skeuomorphic' | 'glassmorphism' | 'cyber' | 'deep' | 'diffuse' | 'sharp-business' | 'retro';
+/**
+ * Shadow style name — either a built-in value or a custom string.
+ * 阴影风格名称 — 内置值或自定义字符串。
+ */
+export type AitheShadowName = AitheBuiltinShadow | string;
+/**
+ * Built-in shape style options.
+ * 内置形状风格选项。
+ */
+export type AitheBuiltinShape = 'sharp' | 'smooth' | 'rounded' | 'rounder' | 'pill' | 'circle' | 'chamfer' | 'organic';
+/**
+ * Shape style name — either a built-in value or a custom string.
+ * 形状风格名称 — 内置值或自定义字符串。
+ */
+export type AitheShapeName = AitheBuiltinShape | string;
+/**
+ * Built-in theme options.
+ * 内置主题选项。
+ */
+export type AitheBuiltinTheme = 'light' | 'dark' | 'gray' | 'blue' | 'festive' | 'orange' | 'purple' | 'pink' | 'teal' | 'indigo' | 'cyan' | 'amber' | 'slate' | 'charcoal' | 'midnight' | 'obsidian' | 'graphite' | 'ink' | 'onyx' | 'ebony' | 'navy' | 'raisin' | 'huawei' | 'tianyi' | 'aliyun';
+/**
+ * Theme name — either a built-in value or a custom string.
+ * 主题名称 — 内置值或自定义字符串。
+ */
+export type AitheThemeName = AitheBuiltinTheme | string;
+/**
+ * Component color variant options.
+ * 组件颜色变体选项。
+ */
+export type AitheVariant = 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'neutral' | string;
+//# sourceMappingURL=types.d.ts.map

package/dist/styles/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/styles/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,UAAU,GACV,QAAQ,GACR,SAAS,CAAC;AAEd;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,MAAM,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAE1D;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,aAAa,GACb,cAAc,GACd,eAAe,GACf,OAAO,GACP,MAAM,GACN,SAAS,GACT,gBAAgB,GAChB,OAAO,CAAC;AAEZ;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAE1D;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,QAAQ,GACR,SAAS,GACT,SAAS,GACT,MAAM,GACN,QAAQ,GACR,SAAS,GACT,SAAS,CAAC;AAEd;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,OAAO,GACP,UAAU,GACV,UAAU,GACV,UAAU,GACV,UAAU,GACV,KAAK,GACL,MAAM,GACN,OAAO,GACP,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,CAAC;AAEb;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG,MAAM,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,QAAQ,GACR,SAAS,GACT,MAAM,CAAC"}

package/dist/styles/typo/business.d.ts

@@ -0,0 +1,2 @@
+export declare const businessTypoTokens: Record<string, string>;
+//# sourceMappingURL=business.d.ts.map

package/dist/styles/typo/business.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"business.d.ts","sourceRoot":"","sources":["../../../src/styles/typo/business.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiCrD,CAAC"}

package/dist/styles/typo/compact.d.ts

@@ -0,0 +1,2 @@
+export declare const compactTypoTokens: Record<string, string>;
+//# sourceMappingURL=compact.d.ts.map

package/dist/styles/typo/compact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../../../src/styles/typo/compact.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiCpD,CAAC"}

package/dist/styles/typo/index.d.ts

@@ -0,0 +1,22 @@
+import type { AitheBuiltinTypo, AitheTypoName } from '../types';
+import type { AitheTreeNodeMeta } from '../../core/types';
+export type { AitheBuiltinTypo, AitheTypoName } from '../types';
+export { minimalTypoTokens } from './minimal';
+export { businessTypoTokens } from './business';
+export { luxuryTypoTokens } from './luxury';
+export { compactTypoTokens } from './compact';
+/**
+ * Static tree menu data for typo selection, compatible with `<aithe-tree-menu>`.
+ * 用于排版选择的静态树形菜单数据，兼容 `<aithe-tree-menu>`。
+ * Each item carries an `icon` extension field with the preview character.
+ * 每个项携带 `icon` 扩展字段，包含预览字符。
+ */
+export declare const typoMenu: AitheTreeNodeMeta[];
+export declare const AITHE_DEFAULT_TYPO: AitheTypoName;
+export declare function getTypoTokens(typo: AitheTypoName): Record<string, string> | undefined;
+export declare function getAitheTypos(): AitheBuiltinTypo[];
+export declare function setAitheTypo(typo: AitheTypoName, persist?: boolean): void;
+export declare function getAitheTypo(): AitheTypoName;
+export declare function initAitheTypo(defaultTypo?: AitheTypoName): void;
+export declare function onAitheTypoChange(fn: () => void): () => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/styles/typo/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/styles/typo/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAuB9C;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,iBAAiB,EAKrC,CAAC;AAGJ,eAAO,MAAM,kBAAkB,EAAE,aAA0B,CAAC;AAI5D,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAErF;AAED,wBAAgB,aAAa,IAAI,gBAAgB,EAAE,CAElD;AAkCD,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,UAAO,GAAG,IAAI,CAStE;AAED,wBAAgB,YAAY,IAAI,aAAa,CAE5C;AAED,wBAAgB,aAAa,CAAC,WAAW,GAAE,aAAkC,GAAG,IAAI,CAKnF;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG5D"}

package/dist/styles/typo/luxury.d.ts

@@ -0,0 +1,2 @@
+export declare const luxuryTypoTokens: Record<string, string>;
+//# sourceMappingURL=luxury.d.ts.map

package/dist/styles/typo/luxury.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"luxury.d.ts","sourceRoot":"","sources":["../../../src/styles/typo/luxury.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiCnD,CAAC"}

package/dist/styles/typo/minimal.d.ts

@@ -0,0 +1,2 @@
+export declare const minimalTypoTokens: Record<string, string>;
+//# sourceMappingURL=minimal.d.ts.map

package/dist/styles/typo/minimal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"minimal.d.ts","sourceRoot":"","sources":["../../../src/styles/typo/minimal.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiCpD,CAAC"}

package/dist/types/AGENTS.md

@@ -0,0 +1,25 @@
+# src/types/ — 类型定义
+
+## 概述
+
+共享 TypeScript 类型定义，作为 `@types` 路径别名的唯一目标。
+
+## 内容
+
+```typescript
+// src/types/index.ts
+export * from '@styles/types'; // 样式相关类型（主题名、形状名等）
+export * from '@core/types'; // 核心类型定义
+```
+
+## 编码规范
+
+- `@types` 是纯 re-export 入口，不在此目录定义新类型
+- 新类型应在所属模块内定义（`src/core/types.ts` 或 `src/styles/types.ts`）
+- 导入时使用 `@types` 路径别名
+- 类型导出使用 `export type` 以利用 isolatedModules
+
+## 关键约定
+
+- 不要在此目录创建新文件，类型定义应放在所属功能模块中
+- 修改类型时需同步更新 `docs/api/` 中相关组件的 API 文档

package/dist/types/index.d.ts

@@ -1,4 +1,3 @@
-export * from './theme';
-export * from './component';
+export * from '../styles/types';
 export * from '../core/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/utils/AGENTS.md

@@ -0,0 +1,28 @@
+# src/utils/ — 工具函数
+
+## 概述
+
+通用工具函数集合，提供 DOM 操作、事件处理和表单验证等辅助能力。
+
+## 目录结构
+
+| 文件            | 导出                                            | 说明         |
+| --------------- | ----------------------------------------------- | ------------ |
+| `dom.ts`        | `findFirstFocusable`, `getFocusableElements` 等 | DOM 操作工具 |
+| `events.ts`     | `emitAitheEvent` 等                             | 事件发射工具 |
+| `validation.ts` | 表单验证相关                                    | 输入验证工具 |
+| `icon.ts`       | `IconUtil` 类（`parse`/`render`）、`ICON_GLYPH_MAP` 常量 | 图标解析与渲染工具 |
+| `index.ts`      | 统一 re-export                                  | 导出入口     |
+
+## 编码规范
+
+- 所有工具函数通过 `src/utils/index.ts` 统一导出
+- 导入使用 `@utils` 路径别名
+- 纯函数风格，无副作用
+- 中英文双语 JSDoc 注释
+
+## 关键约定
+
+- 新增工具函数时，在对应文件中定义并在 `index.ts` 中导出
+- 工具函数应保持通用性，不依赖具体组件逻辑
+- DOM 操作需考虑 Shadow DOM 边界情况

package/dist/utils/dom.d.ts

@@ -1,4 +1,26 @@
+/**
+ * Walk up the DOM tree to find the closest element that carries a theme
+ * (via `data-aithe-theme` attribute or `aithe-theme-*` class).
+ * 向上遍历 DOM 树，查找携带主题的最近元素（通过 `data-aithe-theme` 属性或 `aithe-theme-*` 类）。
+ *
+ * @param element - Starting element. 起始元素。
+ * @returns The themed ancestor, or `null` if none found. 携带主题的祖先元素，或 `null`。
+ */
 export declare function findClosestThemeElement(element: HTMLElement | null): HTMLElement | null;
+/**
+ * Collect all focusable elements inside a root container.
+ * 收集根容器中所有可聚焦元素。
+ *
+ * @param root - Parent node to search within. 要搜索的父节点。
+ * @returns Array of visible, non-disabled focusable elements. 可见、非禁用的可聚焦元素数组。
+ */
 export declare function getFocusableElements(root: ParentNode): HTMLElement[];
+/**
+ * Find the first focusable element inside a root container.
+ * 在根容器中查找第一个可聚焦元素。
+ *
+ * @param root - Parent node to search within. 要搜索的父节点。
+ * @returns The first focusable element, or `null`. 第一个可聚焦元素，或 `null`。
+ */
 export declare function findFirstFocusable(root: ParentNode): HTMLElement | null;
 //# sourceMappingURL=dom.d.ts.map

package/dist/utils/dom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/utils/dom.ts"],"names":[],"mappings":"AAAA,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CAiBvF;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,EAAE,CAcpE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAEvE"}
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/utils/dom.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,WAAW,GAAG,IAAI,CAmBvF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,EAAE,CAcpE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAEvE"}

package/dist/utils/events.d.ts

@@ -1,2 +1,12 @@
-export declare function emitAitheEvent<T>(target: EventTarget, type: string, detail?: T): void;
+/**
+ * Dispatch a composed, bubbling `CustomEvent` with Aithe defaults.
+ * Also records the event in the logger for debugging / telemetry.
+ * 使用 Aithe 默认值分发一个组合、冒泡的 `CustomEvent`，同时记录到日志器。
+ *
+ * @param target - Event target element. 事件目标元素。
+ * @param type   - Event type string. 事件类型字符串。
+ * @param detail - Optional event detail payload. 可选的事件详情载荷。
+ * @typeparam T  - Type of the event detail. 事件详情的类型。
+ */
+export declare function emitAitheEvent<T>(target: EventTarget, type: string, detail?: T): boolean;
 //# sourceMappingURL=events.d.ts.map

package/dist/utils/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,IAAI,CASrF"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/utils/events.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,OAAO,CA4BxF"}

package/dist/utils/icon.d.ts

@@ -0,0 +1,16 @@
+import { nothing, type TemplateResult } from 'lit';
+export type IconType = 'class' | 'auto' | 'url' | 'share' | 'remote';
+export interface IconDescriptor {
+    type: IconType;
+    value: string;
+}
+export declare const ICON_SIZE_MAP: Record<string, string>;
+export declare const ICON_GLYPH_MAP: Record<string, TemplateResult>;
+export declare class IconUtil {
+    static resolveSize(size: string, fallback?: string): string;
+    static parse(input: string): IconDescriptor;
+    private static renderAuto;
+    private static renderClass;
+    static render(input: string, size?: string, cls?: string, iconStyle?: string, alt?: string): TemplateResult | typeof nothing;
+}
+//# sourceMappingURL=icon.d.ts.map

package/dist/utils/icon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon.d.ts","sourceRoot":"","sources":["../../src/utils/icon.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,OAAO,EAAO,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAE9D,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAID,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIhD,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CA0FzD,CAAC;AAIF,qBAAa,QAAQ;IACnB,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAe,GAAG,MAAM;IAOnE,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc;IAkB3C,OAAO,CAAC,MAAM,CAAC,UAAU;IAczB,OAAO,CAAC,MAAM,CAAC,WAAW;IAc1B,MAAM,CAAC,MAAM,CACX,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,MAAa,EACnB,GAAG,GAAE,MAAW,EAChB,SAAS,GAAE,MAAW,EACtB,GAAG,GAAE,MAAW,GACf,cAAc,GAAG,OAAO,OAAO;CAsCnC"}

package/dist/utils/index.d.ts

@@ -1,6 +1,5 @@
 export * from './dom';
 export * from './events';
-export * from './theme';
 export * from './validation';
-export { clamp, getValueByPath, uid } from '../core/utils';
+export * from './icon';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC"}

package/dist/utils/utils.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 declare function clamp(value: number, min: number, max: number): number;
+/**
+ * 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 declare function getValueByPath(record: unknown, dataIndex?: string): unknown;
+/**
+ * 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 declare function uid(prefix?: string): string;
+/**
+ * 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 declare function findFirstFocusable(root: ParentNode): HTMLElement | null;
+/**
+ * Safely converts an unknown value to a JSON string, preventing "[object Object]" output.
+ * Falls back gracefully through multiple strategies:
+ *   1. JSON.stringify with pretty-print (fails on circular references)
+ *   2. JSON.stringify without pretty-print for objects, or String() for primitives
+ *   3. String() as final fallback
+ *
+ * 安全地将任意值转换为 JSON 字符串，避免 "[object Object]" 输出。
+ * 逐级降级：格式化序列化 → 无格式序列化/基本类型转换 → String() 兜底
+ */
+export declare function safeStringify(value: unknown): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils/utils.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAY3E;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,CAAC,MAAM,SAAU,GAAG,MAAM,CAG5C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAYvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAapD"}

package/dist/utils/validation.d.ts

@@ -1,4 +1,30 @@
+/**
+ * Check whether a value is `null` or `undefined`.
+ * 检查值是否为 `null` 或 `undefined`。
+ *
+ * @param value - Value to check. 要检查的值。
+ * @returns `true` when the value is nullish. 当值为空时返回 `true`。
+ */
 export declare function isNil(value: unknown): value is null | 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 declare function toBooleanAttribute(value: unknown): boolean;
+/**
+ * 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 declare function normalizeCssUnit(value: string | number | null | undefined, fallback?: string): string;
 //# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,SAAS,CAE/D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EACzC,QAAQ,SAAK,GACZ,MAAM,CAuBR"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,GAAG,SAAS,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,SAAK,GAAG,MAAM,CAuBjG"}

package/docs/api/AGENTS.md

@@ -0,0 +1,61 @@
+# docs/api/ — 组件 API 文档
+
+## 概述
+
+各组件的详细 API 参考文档，包含属性、事件、插槽和示例。与 `src/components/` 目录结构一一对应。
+
+## 目录结构
+
+| 目录          | 对应组件分类                              | 文档数 |
+| ------------- | ----------------------------------------- | ------ |
+| `basic/`      | 基础组件（button/input/card 等）          | 12     |
+| `layout/`     | 布局组件（container/row/col 等）          | 8      |
+| `framework/`  | 框架组件（header/sidebar/page 等）        | 6      |
+| `navigation/` | 导航组件（menu/breadcrumb/steps 等）      | 7      |
+| `form/`       | 表单组件（select/date-picker/upload 等）  | 17     |
+| `feedback/`   | 反馈组件（dialog/drawer/toast 等）        | 9      |
+| `data/`       | 数据组件（table/tabs/tree/dropdown 等）   | 12     |
+| `display/`    | 展示组件（carousel/markdown 等）          | 7      |
+| `progress/`   | 进度组件（progress-bar/spinner 等）       | 4      |
+| `container/`  | 容器组件（callout/details 等）            | 4      |
+| `theme/`      | 主题组件（theme-switch/theme-picker/locale-switch 等） | 7      |
+| `summary.md`  | API 参考索引                              | —      |
+
+## 文档格式规范
+
+每个组件 API 文档必须包含以下章节：
+
+```markdown
+# AitheXxx / AitheXxx 中文名
+
+> English description.
+> 中文描述。
+
+## Slots / 插槽
+
+| Name | Description (EN) | Description (CN) |
+
+## Properties / 属性
+
+| Name | Type | Default | Description (EN) | Description (CN) |
+
+## Events / 事件
+
+| Name | Detail | Cancelable | Description (EN) | Description (CN) |
+
+## Examples / 示例
+```
+
+## 编码规范
+
+- 中英文双语，英文在前中文在后
+- 属性/事件/插槽信息必须从源码 `@property` / `@fires` / `@slot` 提取
+- 示例代码使用 ` ```html ` 代码块
+- `summary.md` 维护所有组件的索引列表，需与 `src/components/` 实际文件保持一致
+
+## 关键约定
+
+- 修改组件源码时，必须同步更新对应的 API 文档
+- 新增组件时，必须创建对应的 API 文档并在 `summary.md` 中添加条目
+- 删除组件时，必须删除对应的 API 文档并从 `summary.md` 中移除
+- **不要修改 `docs/issue/` 和 `docs/changelog/` 目录**

package/docs/api/basic/avatar.md

@@ -2,6 +2,9 @@
 
 > Avatar displaying an image, initials, or custom content.
 > 头像组件，显示图片、首字母或自定义内容。
+>
+> The `text` property supports the extended icon format `(type)value`. Icon-format text is delegated to `IconUtil.render` for rendering.
+> `text` 属性支持扩展图标格式 `(type)value`。图标格式文本委托给 `IconUtil.render` 渲染。
 
 ## Slots / 插槽
 
@@ -15,9 +18,9 @@
 |------|------|---------|-------------------|-------------------|
 | src | `string` | `''` | Image source URL. | 图片源地址。 |
 | alt | `string` | `''` | Alt text for the image. | 图片替代文本。 |
-| text | `string` | `''` | Text used to generate initials fallback. | 用于生成首字母后备显示的文本。 |
+| text | `string` | `''` | Text or icon descriptor used to generate fallback content. Supports extended icon format `(type)value`. See [Extended Text Format](#extended-text-format--扩展文本格式) below. | 用于生成后备内容的文本或图标描述符。支持扩展图标格式 `(type)value`。详见下方扩展文本格式。 |
 | shape | `'circle' \| 'square'` | `'circle'` | Avatar shape variant. | 头像形状。 |
-| size | `'sm' \| 'md' \| 'lg'` | `'md'` | Avatar size preset. | 头像尺寸预设。 |
+| size | `string` | `'md'` | Avatar size. Accepts preset aliases (`xs`~`6xl`) or any explicit CSS value. Resolved via `IconUtil.resolveSize` against `ICON_SIZE_MAP`. | 头像尺寸。支持预设别名（`xs`~`6xl`）或显式 CSS 值。通过 `IconUtil.resolveSize` 结合 `ICON_SIZE_MAP` 解析。 |
 
 ## Events / 事件
 
@@ -25,9 +28,26 @@
 |------|--------|-------------------|-------------------|
 | — | — | No custom events. | 无自定义事件。 |
 
+## Extended Text Format / 扩展文本格式
+
+The `text` property supports the same extended icon format as `<aithe-icon>`:
+`text` 属性支持与 `<aithe-icon>` 相同的扩展图标格式：
+
+| Format | Type | Description (EN) | Description (CN) |
+|--------|------|-------------------|-------------------|
+| `Jane Smith` | `auto` | Bare text — auto-generates initials from first characters. | 裸文本 — 取首字母自动生成。 |
+| `(auto)Admin` | `auto` | Explicit auto-generated from first character. | 显式指定文本首字母。 |
+| `(class)user` | `class` | Render a built-in icon as avatar content. | 渲染内置图标作为头像内容。 |
+| `(url)https://example.com/icon.svg\|User` | `url` | Load from URL with alt fallback. Shows "U" on load failure. | 从 URL 加载，带 alt 占位，加载失败时显示 "U"。 |
+
 ## Examples / 示例
 
+### Basic usage / 基本用法
+
 ```html
 <aithe-avatar src="/photo.jpg" alt="User" shape="circle" size="md"></aithe-avatar>
 <aithe-avatar text="Jane Smith" shape="square" size="lg"></aithe-avatar>
+<aithe-avatar text="(class)user" shape="circle" size="lg"></aithe-avatar>
+<aithe-avatar text="(auto)Admin" shape="circle" size="lg"></aithe-avatar>
+<aithe-avatar text="(url)https://example.com/avatar.svg|Bot" shape="circle" size="lg"></aithe-avatar>
 ```

package/docs/api/basic/button.md

@@ -1,38 +1,63 @@
 # AitheButton / AitheButton 按钮
 
-> Button component with multiple visual types, sizes, and states.
-> 按钮组件，支持多种视觉类型、尺寸和状态。
+> Button component with multiple visual types, sizes, and states. When `href` is set, renders as an `<a>` element for native link behavior.
+> 按钮组件，支持多种视觉类型、尺寸和状态。设置 `href` 后渲染为 `<a>` 元素以获得原生链接行为。
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
-| (default) | Default slot for button label. | 默认插槽，用于按钮标签。 |
-| prefix | Icon or content before the label. | 标签前的图标或内容。 |
-| suffix | Icon or content after the label. | 标签后的图标或内容。 |
+| Name      | Description (EN)                  | Description (CN)         |
+| --------- | --------------------------------- | ------------------------ |
+| (default) | Default slot for button label.    | 默认插槽，用于按钮标签。 |
+| prefix    | Icon or content before the label. | 标签前的图标或内容。     |
+| suffix    | Icon or content after the label.  | 标签后的图标或内容。     |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| type | `'primary' \| 'default' \| 'dashed' \| 'text' \| 'link'` | `'default'` | Visual type 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. | 按钮是否占满容器宽度。 |
+| Name     | Type                                                     | Default     | Description (EN)                                                                      | Description (CN)                                          |
+| -------- | -------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| type     | `'primary' \| 'default' \| 'dashed' \| 'text' \| 'link'` | `'default'` | Visual type 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` 时生效。 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-click | `{ originalEvent: MouseEvent }` | Emitted when the button is clicked (not when disabled/loading). | 按钮被点击时发出（禁用/加载时不发出）。 |
+| Name        | Detail                          | Cancelable | Description (EN)                                                                                                                                     | Description (CN)                                                                                    |
+| ----------- | ------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| aithe-click | `{ originalEvent: MouseEvent }` | Yes        | Emitted when the button is clicked (not when disabled/loading). When `href` is set, navigation runs by default; call `preventDefault()` to suppress. | 按钮被点击时发出（禁用/加载时不发出）。设置 `href` 后默认执行导航；调用 `preventDefault()` 可阻止。 |
 
 ## Examples / 示例
 
+### 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>
-```
+```
+
+### 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>
+```
+
+No event listener is required — the component navigates to `href` internally by default.
+
+无需监听事件 — 组件默认在内部导航到 `href`。
+
+### Custom click handling (prevent default navigation) / 自定义点击处理（阻止默认导航）
+
+```js
+const button = document.querySelector('aithe-button');
+button.addEventListener('aithe-click', (e) => {
+  e.preventDefault();
+  console.log('Click intercepted, navigation suppressed');
+});
+```