@aithe/aithe-ui 26.2.2 → 26.3.1

package/dist/apps/demo/pages/progress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../../apps/demo/pages/progress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG1C,eAAO,MAAM,YAAY,EAAE,QAwC1B,CAAC"}
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../../src/apps/demo/pages/progress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG1C,eAAO,MAAM,YAAY,EAAE,QAwC1B,CAAC"}

package/dist/apps/demo/pages/progress.js

@@ -0,0 +1,42 @@
+import { t } from '../../../styles/i18n';
+export const progressPage = {
+    key: 'progress',
+    title: () => t('demo.progress.title'),
+    description: () => t('demo.progress.description'),
+    examples: [
+        {
+            title: () => t('demo.progress.bar.title'),
+            description: () => t('demo.progress.bar.description'),
+            code: `<div style="display:grid;gap:16px;max-width:420px;">
+  <aithe-progress-bar percent="42"></aithe-progress-bar>
+  <aithe-progress-bar percent="76" status="success"></aithe-progress-bar>
+  <aithe-progress-bar percent="91" status="danger"></aithe-progress-bar>
+</div>`,
+        },
+        {
+            title: () => t('demo.progress.ring.title'),
+            description: () => t('demo.progress.ring.description'),
+            code: `<aithe-progress-ring percent="68" size="132" status="warning"></aithe-progress-ring>`,
+            previewHeight: '180px',
+        },
+        {
+            title: () => t('demo.progress.spinner.title'),
+            description: () => t('demo.progress.spinner.description'),
+            code: `<div style="display:flex;gap:16px;align-items:center;">
+  <aithe-spinner size="sm"></aithe-spinner>
+  <aithe-spinner size="md"></aithe-spinner>
+  <aithe-spinner variant="dots" color="var(--aithe-success-6)"></aithe-spinner>
+</div>`,
+        },
+        {
+            title: () => t('demo.progress.skeleton.title'),
+            description: () => t('demo.progress.skeleton.description'),
+            code: `<div style="display:grid;gap:16px;">
+  <aithe-skeleton rows="3"></aithe-skeleton>
+  <aithe-skeleton rows="1" shape="circle"></aithe-skeleton>
+  <aithe-skeleton rows="1" shape="rect"></aithe-skeleton>
+</div>`,
+            previewHeight: '320px',
+        },
+    ],
+};

package/dist/apps/demo/pages/theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../../../apps/demo/pages/theme.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG1C,eAAO,MAAM,SAAS,EAAE,QAmDvB,CAAC"}
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../../../src/apps/demo/pages/theme.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAG1C,eAAO,MAAM,SAAS,EAAE,QAoIvB,CAAC"}

package/dist/apps/demo/pages/theme.js

@@ -0,0 +1,126 @@
+import { t } from '../../../styles/i18n';
+export const themePage = {
+    key: 'theme',
+    title: () => t('demo.theme.title'),
+    description: () => t('demo.theme.description'),
+    examples: [
+        {
+            title: () => t('demo.theme.picker.title'),
+            description: () => t('demo.theme.picker.description'),
+            code: `<aithe-theme-picker value="light"></aithe-theme-picker>`,
+        },
+        {
+            title: () => t('demo.theme.pickerHandler.title'),
+            description: () => t('demo.theme.pickerHandler.description'),
+            code: `<div style="display:flex;gap:16px;align-items:center;flex-wrap:wrap;">
+  <aithe-theme-picker id="demo-picker" value="light"></aithe-theme-picker>
+  <span id="demo-label" style="font-size:14px;color:var(--aithe-color-text-muted);">Current: light</span>
+</div>`,
+            setup: (root) => {
+                const picker = root.querySelector('#demo-picker');
+                const label = root.querySelector('#demo-label');
+                picker?.addEventListener('aithe-theme-change', (event) => {
+                    const { theme } = event.detail;
+                    if (label)
+                        label.textContent = `Current: ${theme}`;
+                });
+            },
+        },
+        {
+            title: () => t('demo.theme.pickerPlacement.title'),
+            description: () => t('demo.theme.pickerPlacement.description'),
+            code: `<div style="display:flex;gap:16px;align-items:center;flex-wrap:wrap;">
+  <span style="font-size:13px;color:var(--aithe-color-text-muted);">bottom-end (default)</span>
+  <aithe-theme-picker value="light"></aithe-theme-picker>
+  <span style="font-size:13px;color:var(--aithe-color-text-muted);">bottom-start</span>
+  <aithe-theme-picker value="dark" placement="bottom-start"></aithe-theme-picker>
+</div>`,
+        },
+        {
+            title: () => t('demo.theme.preview.title'),
+            description: () => t('demo.theme.preview.description'),
+            code: `<aithe-theme-preview id="demo-preview" value="light"></aithe-theme-preview>`,
+            setup: (root) => {
+                const preview = root.querySelector('#demo-preview');
+                preview?.addEventListener('aithe-theme-apply', (event) => {
+                    const { theme } = event.detail;
+                    document.documentElement.dataset.aitheTheme = theme;
+                });
+            },
+        },
+        {
+            title: () => t('demo.theme.shapePicker.title', 'Shape Picker'),
+            description: () => t('demo.theme.shapePicker.description', 'Switch between 8 built-in shape styles (Theme × Shape).'),
+            code: `<div style="display:flex;gap:16px;align-items:center;flex-wrap:wrap;">
+  <aithe-shape-picker id="demo-shape"></aithe-shape-picker>
+  <span id="demo-shape-label" style="font-size:14px;color:var(--aithe-color-text-muted);">Current: rounded</span>
+</div>`,
+            setup: (root) => {
+                const picker = root.querySelector('#demo-shape');
+                const label = root.querySelector('#demo-shape-label');
+                picker?.addEventListener('aithe-shape-change', (event) => {
+                    const { shape } = event.detail;
+                    if (label)
+                        label.textContent = `Current: ${shape}`;
+                });
+            },
+        },
+        {
+            title: () => 'Shadow Picker (Standalone)',
+            description: () => 'Switch between 9 built-in shadow styles. Test with native HTML elements.',
+            code: `<div style="display:flex;gap:16px;align-items:center;flex-wrap:wrap; margin-bottom: 24px;">
+  <aithe-shadow-picker id="demo-shadow"></aithe-shadow-picker>
+  <span id="demo-shadow-label" style="font-size:14px;color:var(--aithe-color-text-muted);">Current: skeuomorphic</span>
+</div>
+<h4>Native HTML Elements (should inherit CSS variables):</h4>
+<div style="display:flex;gap:16px;align-items:center;flex-wrap:wrap; margin-bottom: 16px;">
+  <button class="test-btn" style="padding: 12px 20px; cursor: pointer;">Native Button</button>
+  <button class="test-btn" style="padding: 12px 20px; background: #4d8bff; color: white; border: none; cursor: pointer;">Primary</button>
+</div>
+<div class="test-panel" style="margin-top: 16px; padding: 24px; background: var(--aithe-color-surface-elevated); border-radius: 8px; box-shadow: var(--aithe-shadow-3);">
+  Panel with box-shadow: var(--aithe-shadow-3)
+</div>`,
+            setup: (root) => {
+                const picker = root.querySelector('#demo-shadow');
+                const label = root.querySelector('#demo-shadow-label');
+                if (picker && label) {
+                    picker.addEventListener('aithe-shadow-change', (event) => {
+                        const { shadow } = event.detail;
+                        label.textContent = `Current: ${shadow}`;
+                    });
+                }
+            },
+        },
+        {
+            title: () => t('demo.theme.typoPicker.title', 'Typo Picker (Standalone)'),
+            description: () => t('demo.theme.typoPicker.description', 'Switch between 4 built-in typography styles (minimal, business, luxury, compact). Observe font-size, spacing and control-height changes.'),
+            code: `<div style="display:flex;gap:16px;align-items:center;flex-wrap:wrap; margin-bottom: 24px;">
+  <aithe-typo-picker id="demo-typo"></aithe-typo-picker>
+  <span id="demo-typo-label" style="font-size:14px;color:var(--aithe-color-text-muted);">Current: business</span>
+</div>
+<h4>Typography Preview:</h4>
+<div style="margin-bottom: 12px;">
+  <p style="font-size:var(--aithe-font-size-2xl);font-weight:var(--aithe-font-weight-bold);line-height:var(--aithe-line-height-tight);margin:0 0 var(--aithe-space-3) 0;">Heading XL</p>
+  <p style="font-size:var(--aithe-font-size-lg);font-weight:var(--aithe-font-weight-semibold);line-height:var(--aithe-line-height-base);margin:0 0 var(--aithe-space-2) 0;">Section Title</p>
+  <p style="font-size:var(--aithe-font-size-md);line-height:var(--aithe-line-height-base);margin:0 0 var(--aithe-space-2) 0;">Body text at medium size with base line-height. Spacing and sizing adjust per typo style.</p>
+  <p style="font-size:var(--aithe-font-size-sm);line-height:var(--aithe-line-height-base);color:var(--aithe-color-text-muted);margin:0;">Small caption text for secondary info.</p>
+</div>
+<div style="display:flex;gap:var(--aithe-space-3);align-items:center;flex-wrap:wrap;">
+  <aithe-button type="primary" size="sm">Small</aithe-button>
+  <aithe-button type="primary">Medium</aithe-button>
+  <aithe-button type="primary" size="lg">Large</aithe-button>
+</div>`,
+            previewHeight: '320px',
+            setup: (root) => {
+                const picker = root.querySelector('#demo-typo');
+                const label = root.querySelector('#demo-typo-label');
+                if (picker && label) {
+                    picker.addEventListener('aithe-typo-change', (event) => {
+                        const { typo } = event.detail;
+                        label.textContent = `Current: ${typo}`;
+                    });
+                }
+            },
+        },
+    ],
+};

package/dist/apps/demo/standalone.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"standalone.d.ts","sourceRoot":"","sources":["../../../apps/demo/standalone.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,CAAC"}
+{"version":3,"file":"standalone.d.ts","sourceRoot":"","sources":["../../../src/apps/demo/standalone.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,CAAC"}

package/dist/apps/demo/standalone.js

@@ -0,0 +1 @@
+import './app';

package/dist/components/basic/AGENTS.md

@@ -0,0 +1,35 @@
+# src/components/basic/ — 基础组件（12个）
+
+## 组件列表
+
+| 组件              | 标签                   | 说明                                           |
+| ----------------- | ---------------------- | ---------------------------------------------- |
+| `button.ts`       | `<aithe-button>`       | 按钮，支持 type/size/loading/danger/block/href |
+| `button-group.ts` | `<aithe-button-group>` | 按钮组，统一间距布局                           |
+| `icon.ts`         | `<aithe-icon>`         | 矢量图标，内置 glyph 映射                      |
+| `input.ts`        | `<aithe-input>`        | 单行文本输入框，支持验证                       |
+| `textarea.ts`     | `<aithe-textarea>`     | 多行文本域，自动增高                           |
+| `card.ts`         | `<aithe-card>`         | 卡片容器，含 header/body/footer                |
+| `tag.ts`          | `<aithe-tag>`          | 标签，可关闭、可选择                           |
+| `badge.ts`        | `<aithe-badge>`        | 徽章，数字/圆点角标                            |
+| `avatar.ts`       | `<aithe-avatar>`       | 头像，图片/文字/自定义                         |
+| `divider.ts`      | `<aithe-divider>`      | 分割线，水平/垂直                              |
+| `empty.ts`        | `<aithe-empty>`        | 空状态占位                                     |
+| `chip.ts`         | `<aithe-chip>`         | 芯片标签，紧凑可关闭                           |
+
+## 编码规范
+
+- 所有组件继承 `AitheElement`，不直接继承 `LitElement`
+- 使用 `@customElement('aithe-xxx')` 装饰器注册
+- 样式使用 `static styles = [aitheBaseStyles, css`...`]`
+- 事件使用 `this.emit('aithe-xxx', detail)` 发射
+- 导入使用 `@components/basic/xxx` 路径别名
+- 中英文双语 JSDoc，含 `@slot`、`@fires`、`@example`
+
+## 关键约定
+
+- 组件标签统一使用 `aithe-` 前缀
+- 事件名统一使用 `aithe-` 前缀
+- 公共属性：variant/size/theme/disabled/log（继承自基类）
+- 输入类组件（input/textarea）在原生事件处理器中调用 `event.stopPropagation()`，防止原生事件逃逸到组件外部
+- 新增组件需在 `src/index.ts` 添加导出，在 `docs/api/basic/` 添加 API 文档

package/dist/components/basic/avatar.d.ts

@@ -1,13 +1,50 @@
+import { type TemplateResult } from 'lit';
 import { AitheElement } from '../../core/aithe-element';
+/**
+ * Avatar displaying an image, initials, or custom content.
+ * 头像组件，显示图片、首字母或自定义内容。
+ *
+ * The `text` property supports the extended icon format `(type)value`:
+ * - `(auto)Text` — auto-generate from first character (default for bare text)
+ * - `(url)URL|AltText` — load from URL with alt fallback
+ * - `(class)iconName` — render a built-in icon
+ * `text` 属性支持扩展图标格式 `(type)value`。
+ *
+ * For icon-format text, rendering is delegated to {@link IconUtil.render}.
+ * Size presets are resolved via {@link IconUtil.resolveSize} against {@link ICON_SIZE_MAP}.
+ * 图标格式文本委托给 {@link IconUtil.render} 渲染，尺寸预设通过 {@link IconUtil.resolveSize} 解析。
+ *
+ * @slot - Default slot for fallback content when image fails. 图片加载失败时的后备内容。
+ * @example
+ * ```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="(url)https://example.com/avatar.svg|User" shape="circle" size="lg"></aithe-avatar>
+ * <aithe-avatar text="(class)user" shape="circle" size="lg"></aithe-avatar>
+ * ```
+ */
 export declare class AitheAvatar extends AitheElement {
+    /** Image source URL. 图片源地址。 */
     src: string;
+    /** Alt text for the image. 图片替代文本。 */
     alt: string;
+    /** Text or icon descriptor used to generate fallback content. 用于生成后备内容的文本或图标描述符。 */
     text: string;
+    /** Avatar shape variant. 头像形状。 */
     shape: 'circle' | 'square';
-    size: 'sm' | 'md' | 'lg';
+    /** Avatar size preset or explicit CSS value. The inner icon is resolved via {@link IconUtil.resolveSize} against {@link ICON_SIZE_MAP}. 头像尺寸预设或显式 CSS 值，内部图标通过 {@link IconUtil.resolveSize} 结合 {@link ICON_SIZE_MAP} 解析。 */
+    size: string;
+    /** Whether the image failed to load. 图片是否加载失败。 */
     private imageBroken;
     static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
+    /** Extracts up to two initials from the text property. 从 text 属性提取最多两个首字母。 */
     private get fallbackText();
-    render(): import("lit-html").TemplateResult<1>;
+    /** Whether text uses the extended icon format `(type)value`. 文本是否使用扩展图标格式。 */
+    private get isIconFormat();
+    /** Resolve avatar size to a CSS pixel value for IconUtil. 将头像尺寸解析为 CSS 像素值供 IconUtil 使用。 */
+    private get iconSize();
+    /** Compute the container size from icon size (icon + padding). 根据图标尺寸计算容器大小。 */
+    private get containerSize();
+    render(): TemplateResult<1>;
 }
 //# sourceMappingURL=avatar.d.ts.map

package/dist/components/basic/avatar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"avatar.d.ts","sourceRoot":"","sources":["../../../src/components/basic/avatar.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD,qBACa,WAAY,SAAQ,YAAY;IACf,GAAG,SAAM;IACT,GAAG,SAAM;IACT,IAAI,SAAM;IACV,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAY;IACtC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAQ;IAEnD,OAAO,CAAC,WAAW,CAAS;IAErC,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAmDpB;IAEF,OAAO,KAAK,YAAY,GAQvB;IAED,MAAM;CAmBP"}
+{"version":3,"file":"avatar.d.ts","sourceRoot":"","sources":["../../../src/components/basic/avatar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAI9D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBACa,WAAY,SAAQ,YAAY;IAC3C,+BAA+B;IACH,GAAG,SAAM;IACrC,sCAAsC;IACV,GAAG,SAAM;IACrC,oFAAoF;IACxD,IAAI,SAAM;IACtC,kCAAkC;IACN,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAY;IAClE,4NAA4N;IAChM,IAAI,EAAE,MAAM,CAAQ;IAEhD,kDAAkD;IACzC,OAAO,CAAC,WAAW,CAAS;IAErC,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAyCpB;IAEF,8EAA8E;IAC9E,OAAO,KAAK,YAAY,GAQvB;IAED,8EAA8E;IAC9E,OAAO,KAAK,YAAY,GAEvB;IAED,4FAA4F;IAC5F,OAAO,KAAK,QAAQ,GAEnB;IAED,gFAAgF;IAChF,OAAO,KAAK,aAAa,GAKxB;IAED,MAAM;CA0BP"}

package/dist/components/basic/avatar.js

@@ -0,0 +1,168 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { css, html } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
+import { AitheElement } from '../../core/aithe-element';
+import { aitheBaseStyles } from '../../core/styles';
+import { t } from '../../styles/i18n';
+import { IconUtil } from '../../utils';
+/**
+ * Avatar displaying an image, initials, or custom content.
+ * 头像组件，显示图片、首字母或自定义内容。
+ *
+ * The `text` property supports the extended icon format `(type)value`:
+ * - `(auto)Text` — auto-generate from first character (default for bare text)
+ * - `(url)URL|AltText` — load from URL with alt fallback
+ * - `(class)iconName` — render a built-in icon
+ * `text` 属性支持扩展图标格式 `(type)value`。
+ *
+ * For icon-format text, rendering is delegated to {@link IconUtil.render}.
+ * Size presets are resolved via {@link IconUtil.resolveSize} against {@link ICON_SIZE_MAP}.
+ * 图标格式文本委托给 {@link IconUtil.render} 渲染，尺寸预设通过 {@link IconUtil.resolveSize} 解析。
+ *
+ * @slot - Default slot for fallback content when image fails. 图片加载失败时的后备内容。
+ * @example
+ * ```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="(url)https://example.com/avatar.svg|User" shape="circle" size="lg"></aithe-avatar>
+ * <aithe-avatar text="(class)user" shape="circle" size="lg"></aithe-avatar>
+ * ```
+ */
+let AitheAvatar = class AitheAvatar extends AitheElement {
+    constructor() {
+        super(...arguments);
+        /** Image source URL. 图片源地址。 */
+        this.src = '';
+        /** Alt text for the image. 图片替代文本。 */
+        this.alt = '';
+        /** Text or icon descriptor used to generate fallback content. 用于生成后备内容的文本或图标描述符。 */
+        this.text = '';
+        /** Avatar shape variant. 头像形状。 */
+        this.shape = 'circle';
+        /** Avatar size preset or explicit CSS value. The inner icon is resolved via {@link IconUtil.resolveSize} against {@link ICON_SIZE_MAP}. 头像尺寸预设或显式 CSS 值，内部图标通过 {@link IconUtil.resolveSize} 结合 {@link ICON_SIZE_MAP} 解析。 */
+        this.size = 'md';
+        /** Whether the image failed to load. 图片是否加载失败。 */
+        this.imageBroken = false;
+    }
+    static { this.styles = [
+        aitheBaseStyles,
+        css `
+      :host {
+        display: inline-flex;
+      }
+
+      .avatar {
+        position: relative;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        overflow: hidden;
+        width: var(--aithe-avatar-size, 32px);
+        height: var(--aithe-avatar-size, 32px);
+        background: linear-gradient(135deg, var(--aithe-primary-4), var(--aithe-primary-7));
+        color: var(--aithe-color-text-on-primary, #ffffff);
+        font-weight: var(--aithe-font-weight-semibold);
+        box-shadow: var(--aithe-shadow-1);
+      }
+
+      .circle {
+        border-radius: 50%;
+      }
+
+      .square {
+        border-radius: var(--aithe-container-radius-lg);
+      }
+
+      img {
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+      }
+
+      .avatar-text {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+      }
+    `,
+    ]; }
+    /** Extracts up to two initials from the text property. 从 text 属性提取最多两个首字母。 */
+    get fallbackText() {
+        const source = this.text.trim();
+        if (!source) {
+            return '';
+        }
+        const chunks = source.split(/\s+/).slice(0, 2);
+        return chunks.map((chunk) => chunk[0]?.toUpperCase() ?? '').join('');
+    }
+    /** Whether text uses the extended icon format `(type)value`. 文本是否使用扩展图标格式。 */
+    get isIconFormat() {
+        return /^\(\w+\)/.test(this.text.trim());
+    }
+    /** Resolve avatar size to a CSS pixel value for IconUtil. 将头像尺寸解析为 CSS 像素值供 IconUtil 使用。 */
+    get iconSize() {
+        return IconUtil.resolveSize(this.size, '16px');
+    }
+    /** Compute the container size from icon size (icon + padding). 根据图标尺寸计算容器大小。 */
+    get containerSize() {
+        const raw = this.iconSize;
+        const num = Number.parseInt(raw, 10);
+        if (Number.isNaN(num))
+            return '32px';
+        return `${Math.round(num * 1.6)}px`;
+    }
+    render() {
+        const showImage = Boolean(this.src) && !this.imageBroken;
+        let content;
+        if (showImage) {
+            content = html `<img alt=${this.alt} src=${this.src} @error=${() => (this.imageBroken = true)} />`;
+        }
+        else if (this.isIconFormat) {
+            content = IconUtil.render(this.text, this.iconSize);
+        }
+        else {
+            content = html `<span class="avatar-text" style="font-size:calc(${this.iconSize} * 0.75);line-height:1;">${this.fallbackText}</span>`;
+        }
+        return html `
+      <span
+        class=${classMap({
+            avatar: true,
+            [this.shape]: true,
+        })}
+        style="--aithe-avatar-size: ${this.containerSize};"
+        aria-label=${this.alt || this.text || t('basic.avatar.ariaLabel')}
+        role="img"
+      >
+        ${content}
+      </span>
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], AitheAvatar.prototype, "src", void 0);
+__decorate([
+    property({ type: String })
+], AitheAvatar.prototype, "alt", void 0);
+__decorate([
+    property({ type: String })
+], AitheAvatar.prototype, "text", void 0);
+__decorate([
+    property({ type: String })
+], AitheAvatar.prototype, "shape", void 0);
+__decorate([
+    property({ type: String })
+], AitheAvatar.prototype, "size", void 0);
+__decorate([
+    state()
+], AitheAvatar.prototype, "imageBroken", void 0);
+AitheAvatar = __decorate([
+    customElement('aithe-avatar')
+], AitheAvatar);
+export { AitheAvatar };

package/dist/components/basic/badge.d.ts

@@ -1,13 +1,32 @@
 import { AitheElement } from '../../core/aithe-element';
+/**
+ * Badge / count indicator overlaid on an anchor element.
+ * 徽标/计数指示器，覆盖在锚点元素上。
+ *
+ * @slot - Default slot for the anchor element. 锚点元素内容。
+ * @slot badge - Custom badge content (overrides `value` display). 自定义徽标内容。
+ * @example
+ * ```html
+ * <aithe-badge value="5">
+ *   <aithe-button type="default">Messages</aithe-button>
+ * </aithe-badge>
+ * ```
+ */
 export declare class AitheBadge extends AitheElement {
+    /** Badge display value (number or string). 徽标显示值（数字或字符串）。 */
     value: string;
+    /** Maximum count before showing "N+" format. 超过此数值显示"N+"格式。 */
     maxCount: number;
+    /** Whether to show a small dot instead of a count. 是否显示小圆点而非数字。 */
     dot: boolean;
+    /** Badge position relative to the anchor. 徽标相对于锚点的位置。 */
     position: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
-    private badgeSlotNodes;
+    private readonly badgeSlotNodes;
     private hasBadgeSlot;
     static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
-    private syncSlot;
+    /** Syncs badge slot presence state. 同步徽标插槽状态。 */
+    private readonly syncSlot;
+    /** Computes the formatted badge display value. 计算格式化后的徽标显示值。 */
     private get displayValue();
     render(): import("lit-html").TemplateResult<1>;
 }

package/dist/components/basic/badge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../../src/components/basic/badge.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD,qBACa,UAAW,SAAQ,YAAY;IACd,KAAK,SAAM;IACa,QAAQ,SAAM;IACrC,GAAG,UAAS;IACb,QAAQ,EAChC,WAAW,GACX,UAAU,GACV,cAAc,GACd,aAAa,CAAe;IAEU,OAAO,CAAC,cAAc,CAAiB;IACxE,OAAO,CAAC,YAAY,CAAS;IAEtC,MAAM,CAAC,QAAQ,CAAC,MAAM,0DA4DpB;IAEF,OAAO,CAAC,QAAQ,CAEd;IAEF,OAAO,KAAK,YAAY,GAWvB;IAED,MAAM;CAmBP"}
+{"version":3,"file":"badge.d.ts","sourceRoot":"","sources":["../../../src/components/basic/badge.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD;;;;;;;;;;;;GAYG;AACH,qBACa,UAAW,SAAQ,YAAY;IAC1C,6DAA6D;IACjC,KAAK,SAAM;IACvC,+DAA+D;IACX,QAAQ,SAAM;IAClE,mEAAmE;IACtC,GAAG,UAAS;IACzC,yDAAyD;IAC7B,QAAQ,EAAE,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,aAAa,CACjF;IAE4B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IACjF,OAAO,CAAC,YAAY,CAAS;IAEtC,MAAM,CAAC,QAAQ,CAAC,MAAM,0DA6DpB;IAEF,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAEvB;IAEF,gEAAgE;IAChE,OAAO,KAAK,YAAY,GAYvB;IAED,MAAM;CAmBP"}

package/dist/components/basic/badge.js

@@ -0,0 +1,157 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { css, html } from 'lit';
+import { customElement, property, queryAssignedElements, state } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
+import { AitheElement } from '../../core/aithe-element';
+import { aitheBaseStyles } from '../../core/styles';
+/**
+ * Badge / count indicator overlaid on an anchor element.
+ * 徽标/计数指示器，覆盖在锚点元素上。
+ *
+ * @slot - Default slot for the anchor element. 锚点元素内容。
+ * @slot badge - Custom badge content (overrides `value` display). 自定义徽标内容。
+ * @example
+ * ```html
+ * <aithe-badge value="5">
+ *   <aithe-button type="default">Messages</aithe-button>
+ * </aithe-badge>
+ * ```
+ */
+let AitheBadge = class AitheBadge extends AitheElement {
+    constructor() {
+        super(...arguments);
+        /** Badge display value (number or string). 徽标显示值（数字或字符串）。 */
+        this.value = '';
+        /** Maximum count before showing "N+" format. 超过此数值显示"N+"格式。 */
+        this.maxCount = 99;
+        /** Whether to show a small dot instead of a count. 是否显示小圆点而非数字。 */
+        this.dot = false;
+        /** Badge position relative to the anchor. 徽标相对于锚点的位置。 */
+        this.position = 'top-right';
+        this.hasBadgeSlot = false;
+        /** Syncs badge slot presence state. 同步徽标插槽状态。 */
+        this.syncSlot = () => {
+            this.hasBadgeSlot = this.badgeSlotNodes.length > 0;
+        };
+    }
+    static { this.styles = [
+        aitheBaseStyles,
+        css `
+      :host {
+        position: relative;
+        display: inline-flex;
+      }
+
+      .anchor {
+        position: relative;
+        display: inline-flex;
+      }
+
+      .badge {
+        position: absolute;
+        z-index: 2;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-width: 22px;
+        min-height: 22px;
+        padding: 0 var(--aithe-space-2);
+        border: 2px solid var(--aithe-color-surface-elevated);
+        border-radius: var(--aithe-radius-full);
+        background: linear-gradient(180deg, var(--aithe-danger-5), var(--aithe-danger-7));
+        color: var(--aithe-color-text-on-primary, #ffffff);
+        font-size: var(--aithe-font-size-xs);
+        font-weight: var(--aithe-font-weight-semibold);
+        box-shadow: var(--aithe-shadow-1);
+      }
+
+      .badge.dot {
+        min-width: 12px;
+        min-height: 12px;
+        padding: 0;
+      }
+
+      .top-right {
+        top: 0;
+        right: 0;
+        transform: translate(50%, -50%);
+      }
+
+      .top-left {
+        top: 0;
+        left: 0;
+        transform: translate(-50%, -50%);
+      }
+
+      .bottom-right {
+        right: 0;
+        bottom: 0;
+        transform: translate(50%, 50%);
+      }
+
+      .bottom-left {
+        bottom: 0;
+        left: 0;
+        transform: translate(-50%, 50%);
+      }
+    `,
+    ]; }
+    /** Computes the formatted badge display value. 计算格式化后的徽标显示值。 */
+    get displayValue() {
+        if (this.dot) {
+            return '';
+        }
+        const parsed = Number(this.value);
+        if (Number.isFinite(parsed) && this.value !== '') {
+            if (parsed === 0)
+                return '';
+            return parsed > this.maxCount ? `${this.maxCount}+` : String(parsed);
+        }
+        return this.value;
+    }
+    render() {
+        const showBadge = this.dot || this.hasBadgeSlot || Boolean(this.displayValue);
+        return html `
+      <span class="anchor">
+        <slot></slot>
+        <span
+          ?hidden=${!showBadge}
+          class=${classMap({
+            badge: true,
+            dot: this.dot,
+            [this.position]: true,
+        })}
+        >
+          <slot name="badge" @slotchange=${this.syncSlot}>${this.displayValue}</slot>
+        </span>
+      </span>
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], AitheBadge.prototype, "value", void 0);
+__decorate([
+    property({ type: Number, attribute: 'max-count' })
+], AitheBadge.prototype, "maxCount", void 0);
+__decorate([
+    property({ type: Boolean })
+], AitheBadge.prototype, "dot", void 0);
+__decorate([
+    property({ type: String })
+], AitheBadge.prototype, "position", void 0);
+__decorate([
+    queryAssignedElements({ slot: 'badge' })
+], AitheBadge.prototype, "badgeSlotNodes", void 0);
+__decorate([
+    state()
+], AitheBadge.prototype, "hasBadgeSlot", void 0);
+AitheBadge = __decorate([
+    customElement('aithe-badge')
+], AitheBadge);
+export { AitheBadge };