@aithe/aithe-ui 26.2.2 → 26.3.1

package/dist/utils/events.js

@@ -0,0 +1,32 @@
+import { logger, LogLevel } from '../core/logger';
+/**
+ * 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 function emitAitheEvent(target, type, detail) {
+    if (logger.isEnabled) {
+        // Only log when detail is a plain object with log: true — component-instance-level opt-in.
+        const shouldLog = detail != null
+            && typeof detail === 'object'
+            && detail.log === true;
+        if (shouldLog) {
+            const tagName = target.tagName?.toLowerCase?.() ?? '';
+            logger.addEntry(LogLevel.DEBUG, [
+                `[AitheEvent] ${type} from ${tagName}`,
+                { type, tagName, detail },
+            ], ['aithe']);
+        }
+    }
+    return target.dispatchEvent(new CustomEvent(type, {
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+        detail,
+    }));
+}

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/icon.js

@@ -0,0 +1,176 @@
+import { html, svg } from 'lit';
+const ICON_PATTERN = /^\((\w+)\)(.+)/;
+export const ICON_SIZE_MAP = {
+    xs: '12px', sm: '16px', md: '20px', lg: '24px',
+    xl: '28px', '2xl': '32px', '3xl': '48px',
+    '4xl': '64px', '5xl': '96px', '6xl': '128px',
+};
+export const ICON_GLYPH_MAP = {
+    // ── General / 通用 ──
+    sparkles: svg `<path d="M12 3l1.8 4.2L18 9l-4.2 1.8L12 15l-1.8-4.2L6 9l4.2-1.8L12 3z"></path><path d="M5 14l.9 2.1L8 17l-2.1.9L5 20l-.9-2.1L2 17l2.1-.9L5 14z"></path>`,
+    close: svg `<path d="M6 6l12 12M18 6L6 18"></path>`,
+    check: svg `<path d="M5 13l4 4L19 7"></path>`,
+    info: svg `<circle cx="12" cy="12" r="9"></circle><path d="M12 10v5"></path><path d="M12 7h.01"></path>`,
+    warning: svg `<path d="M12 4l9 16H3L12 4z"></path><path d="M12 10v4"></path><path d="M12 17h.01"></path>`,
+    image: svg `<rect x="4" y="5" width="16" height="14" rx="2"></rect><path d="M8 14l3-3 5 5"></path><path d="M14 12l2-2 4 4"></path><circle cx="9" cy="9" r="1.5"></circle>`,
+    search: svg `<circle cx="11" cy="11" r="7"></circle><path d="M21 21l-4.35-4.35"></path>`,
+    plus: svg `<path d="M12 5v14M5 12h14"></path>`,
+    minus: svg `<path d="M5 12h14"></path>`,
+    menu: svg `<path d="M4 6h16M4 12h16M4 18h16"></path>`,
+    more: svg `<circle cx="12" cy="5" r="1.5"></circle><circle cx="12" cy="12" r="1.5"></circle><circle cx="12" cy="19" r="1.5"></circle>`,
+    settings: svg `<circle cx="12" cy="12" r="3"></circle><path d="M19.4 15a1.65 1.65 0 00.5 1.8l.05.05a2 2 0 010 2.83 2 2 0 01-2.83 0l-.05-.05a1.65 1.65 0 00-1.8-.5 1.65 1.65 0 00-1 1.51V21a2 2 0 01-4 0v-.09a1.65 1.65 0 00-1-1.51 1.65 1.65 0 00-1.8.5l-.05.05a2 2 0 01-2.83 0 2 2 0 010-2.83l.05-.05a1.65 1.65 0 00.5-1.8 1.65 1.65 0 00-1.51-1H3a2 2 0 010-4h.09a1.65 1.65 0 001.51-1 1.65 1.65 0 00-.5-1.8l-.05-.05a2 2 0 010-2.83 2 2 0 012.83 0l.05.05a1.65 1.65 0 001.8.5H9a1.65 1.65 0 001-1.51V3a2 2 0 014 0v.09a1.65 1.65 0 001 1.51 1.65 1.65 0 001.8-.5l.05-.05a2 2 0 012.83 0 2 2 0 010 2.83l-.05.05a1.65 1.65 0 00-.5 1.8 1.65 1.65 0 001.51 1H21a2 2 0 010 4h-.09a1.65 1.65 0 00-1.51 1z"></path>`,
+    home: svg `<path d="M3 12l9-9 9 9"></path><path d="M9 21V12h6v9"></path>`,
+    star: svg `<path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"></path>`,
+    heart: svg `<path d="M20.84 4.61a5.5 5.5 0 00-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 00-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 000-7.78z"></path>`,
+    copy: svg `<rect x="9" y="9" width="13" height="13" rx="2"></rect><path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1"></path>`,
+    download: svg `<path d="M21 15v4a2 2 0 01-2 2H5a2 2 0 01-2-2v-4"></path><path d="M7 10l5 5 5-5"></path><path d="M12 15V3"></path>`,
+    upload: svg `<path d="M21 15v4a2 2 0 01-2 2H5a2 2 0 01-2-2v-4"></path><path d="M17 8l-5-5-5 5"></path><path d="M12 3v12"></path>`,
+    share: svg `<circle cx="18" cy="5" r="3"></circle><circle cx="6" cy="12" r="3"></circle><circle cx="18" cy="19" r="3"></circle><path d="M8.59 13.51l6.83 3.98M15.41 6.51l-6.82 3.98"></path>`,
+    link: svg `<path d="M10 13a5 5 0 007.54.54l3-3a5 5 0 00-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 00-7.54-.54l-3 3a5 5 0 007.07 7.07l1.71-1.71"></path>`,
+    external: svg `<path d="M18 13v6a2 2 0 01-2 2H5a2 2 0 01-2-2V8a2 2 0 012-2h6"></path><path d="M15 3h6v6"></path><path d="M10 14L21 3"></path>`,
+    refresh: svg `<path d="M21.5 2v6h-6"></path><path d="M2.5 22v-6h6"></path><path d="M21.5 8A10 10 0 003.5 8"></path><path d="M2.5 16A10 10 0 0020.5 16"></path>`,
+    edit: svg `<path d="M11 4H4a2 2 0 00-2 2v14a2 2 0 002 2h14a2 2 0 002-2v-7"></path><path d="M18.5 2.5a2.12 2.12 0 013 3L12 15l-4 1 1-4 9.5-9.5z"></path>`,
+    trash: svg `<path d="M3 6h18M8 6V4a2 2 0 012-2h4a2 2 0 012 2v2m3 0v14a2 2 0 01-2 2H7a2 2 0 01-2-2V6h14"></path>`,
+    filter: svg `<path d="M22 3H2l8 9.46V19l4 2v-8.54L22 3z"></path>`,
+    sort: svg `<path d="M7 4l-4 4 4 4"></path><path d="M17 4l4 4-4 4"></path><path d="M3 8h18"></path>`,
+    lock: svg `<rect x="3" y="11" width="18" height="11" rx="2"></rect><path d="M7 11V7a5 5 0 0110 0v4"></path>`,
+    unlock: svg `<rect x="3" y="11" width="18" height="11" rx="2"></rect><path d="M7 11V7a5 5 0 019.9-1"></path>`,
+    eye: svg `<path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"></path><circle cx="12" cy="12" r="3"></circle>`,
+    eyeOff: svg `<path d="M17.94 17.94A10.07 10.07 0 0112 20c-7 0-11-8-11-8a18.45 18.45 0 015.06-5.94"></path><path d="M9.9 4.24A9.12 9.12 0 0112 4c7 0 11 8 11 8a18.5 18.5 0 01-2.16 3.19"></path><path d="M14.12 14.12a3 3 0 11-4.24-4.24"></path><path d="M1 1l22 22"></path>`,
+    clock: svg `<circle cx="12" cy="12" r="10"></circle><path d="M12 6v6l4 2"></path>`,
+    calendar: svg `<rect x="3" y="4" width="18" height="18" rx="2"></rect><path d="M16 2v4M8 2v4M3 10h18"></path>`,
+    pin: svg `<path d="M12 2C8.13 2 5 5.13 5 9c0 5.25 7 13 7 13s7-7.75 7-13c0-3.87-3.13-7-7-7z"></path><circle cx="12" cy="9" r="2.5"></circle>`,
+    flag: svg `<path d="M4 22V4"></path><path d="M4 4l8 4-8 4 8 4-8 4"></path>`,
+    bookmark: svg `<path d="M19 21l-7-5-7 5V5a2 2 0 012-2h10a2 2 0 012 2z"></path>`,
+    paperclip: svg `<path d="M21.44 11.05l-9.19 9.19a6 6 0 01-8.49-8.49l9.19-9.19a4 4 0 015.66 5.66l-9.2 9.19a2 2 0 01-2.83-2.83l8.49-8.48"></path>`,
+    tag: svg `<path d="M20.59 13.41l-7.17 7.17a2 2 0 01-2.83 0L2 12V2h10l8.59 8.59a2 2 0 010 2.82z"></path><path d="M7 7h.01"></path>`,
+    thumbUp: svg `<path d="M14 9V5a3 3 0 00-3-3l-4 9v11h11.56a2 2 0 002-1.72l1.67-8a2 2 0 00-2-2.28H14z"></path><path d="M7 22H4a2 2 0 01-2-2v-7a2 2 0 012-2h3"></path>`,
+    thumbDown: svg `<path d="M10 15v4a3 3 0 003 3l4-9V2H5.44a2 2 0 00-2 1.72l-1.67 8a2 2 0 002 2.28H10z"></path><path d="M17 2h3a2 2 0 012 2v7a2 2 0 01-2 2h-3"></path>`,
+    // ── Arrows / 箭头 ──
+    arrowUp: svg `<path d="M12 19V5M5 12l7-7 7 7"></path>`,
+    arrowDown: svg `<path d="M12 5v14M19 12l-7 7-7-7"></path>`,
+    arrowLeft: svg `<path d="M19 12H5M12 19l-7-7 7-7"></path>`,
+    arrowRight: svg `<path d="M5 12h14M12 5l7 7-7 7"></path>`,
+    chevronUp: svg `<path d="M6 15l6-6 6 6"></path>`,
+    chevronDown: svg `<path d="M6 9l6 6 6-6"></path>`,
+    chevronLeft: svg `<path d="M15 6l-6 6 6 6"></path>`,
+    chevronRight: svg `<path d="M9 6l6 6-6 6"></path>`,
+    expand: svg `<path d="M15 3h6v6M9 21H3v-6M21 3l-7 7M3 21l7-7"></path>`,
+    collapse: svg `<path d="M4 14h6v6M20 10h-6V4M14 10l7-7M3 21l7-7"></path>`,
+    // ── Status / 状态 ──
+    success: svg `<circle cx="12" cy="12" r="10"></circle><path d="M8 12l3 3 5-5"></path>`,
+    error: svg `<circle cx="12" cy="12" r="10"></circle><path d="M15 9l-6 6M9 9l6 6"></path>`,
+    question: svg `<circle cx="12" cy="12" r="10"></circle><path d="M9.09 9a3 3 0 015.83 1c0 2-3 3-3 3"></path><path d="M12 17h.01"></path>`,
+    // ── Media / 媒体 ──
+    play: svg `<circle cx="12" cy="12" r="10"></circle><path d="M10 8l6 4-6 4V8z"></path>`,
+    pause: svg `<circle cx="12" cy="12" r="10"></circle><rect x="9" y="8" width="2" height="8"></rect><rect x="15" y="8" width="2" height="8"></rect>`,
+    volume: svg `<path d="M11 5L6 9H2v6h4l5 4V5z"></path><path d="M19.07 4.93a10 10 0 010 14.14M15.54 8.46a5 5 0 010 7.07"></path>`,
+    mute: svg `<path d="M11 5L6 9H2v6h4l5 4V5z"></path><path d="M23 9l-6 6M17 9l6 6"></path>`,
+    camera: svg `<path d="M23 19a2 2 0 01-2 2H3a2 2 0 01-2-2V8a2 2 0 012-2h4l2-3h6l2 3h4a2 2 0 012 2z"></path><circle cx="12" cy="13" r="4"></circle>`,
+    video: svg `<polygon points="23 7 16 12 23 17 23 7"></polygon><rect x="1" y="5" width="15" height="14" rx="2"></rect>`,
+    music: svg `<path d="M9 18V5l12-2v13"></path><circle cx="6" cy="18" r="3"></circle><circle cx="18" cy="16" r="3"></circle>`,
+    // ── Communication / 交流 ──
+    mail: svg `<path d="M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z"></path><path d="M22 6l-10 7L2 6"></path>`,
+    bell: svg `<path d="M18 8A6 6 0 006 8c0 7-3 9-3 9h18s-3-2-3-9M13.73 21a2 2 0 01-3.46 0"></path>`,
+    chat: svg `<path d="M21 15a2 2 0 01-2 2H7l-4 4V5a2 2 0 012-2h14a2 2 0 012 2z"></path>`,
+    phone: svg `<path d="M22 16.92v3a2 2 0 01-2.18 2 19.79 19.79 0 01-8.63-3.07 19.5 19.5 0 01-6-6 19.79 19.79 0 01-3.07-8.67A2 2 0 014.11 2h3a2 2 0 012 1.72c.127.96.361 1.903.7 2.81a2 2 0 01-.45 2.11L8.09 9.91a16 16 0 006 6l1.27-1.27a2 2 0 012.11-.45c.907.339 1.85.573 2.81.7A2 2 0 0122 16.92z"></path>`,
+    // ── Data / 数据 ──
+    barChart: svg `<path d="M12 20V10M18 20V4M6 20v-4"></path>`,
+    pieChart: svg `<path d="M21.21 15.89A10 10 0 118 2.83"></path><path d="M22 12A10 10 0 0012 2v10z"></path>`,
+    database: svg `<ellipse cx="12" cy="5" rx="9" ry="3"></ellipse><path d="M21 12c0 1.66-4 3-9 3s-9-1.34-9-3"></path><path d="M3 5v14c0 1.66 4 3 9 3s9-1.34 9-3V5"></path>`,
+    code: svg `<path d="M16 18l6-6-6-6M8 6l-6 6 6 6"></path>`,
+    terminal: svg `<polyline points="4 17 10 11 4 5"></polyline><path d="M12 19h8"></path>`,
+    file: svg `<path d="M14 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V8z"></path><path d="M14 2v6h6"></path>`,
+    folder: svg `<path d="M22 19a2 2 0 01-2 2H4a2 2 0 01-2-2V5a2 2 0 012-2h5l2 3h9a2 2 0 012 2z"></path>`,
+    // ── Layout / 布局 ──
+    grid: svg `<rect x="3" y="3" width="7" height="7"></rect><rect x="14" y="3" width="7" height="7"></rect><rect x="3" y="14" width="7" height="7"></rect><rect x="14" y="14" width="7" height="7"></rect>`,
+    list: svg `<path d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01"></path>`,
+    sidebar: svg `<rect x="3" y="3" width="18" height="18" rx="2"></rect><path d="M9 3v18"></path>`,
+    maximize: svg `<path d="M8 3H5a2 2 0 00-2 2v3M21 8V5a2 2 0 00-2-2h-3M3 16v3a2 2 0 002 2h3M16 21h3a2 2 0 002-2v-3"></path>`,
+    minimize: svg `<path d="M8 3v3a2 2 0 01-2 2H3M21 8h-3a2 2 0 01-2-2V3M3 16h3a2 2 0 012 2v3M16 21v-3a2 2 0 012-2h3"></path>`,
+    // ── User / 用户 ──
+    user: svg `<path d="M20 21v-2a4 4 0 00-4-4H8a4 4 0 00-4 4v2"></path><circle cx="12" cy="7" r="4"></circle>`,
+    users: svg `<path d="M17 21v-2a4 4 0 00-4-4H5a4 4 0 00-4 4v2"></path><circle cx="9" cy="7" r="4"></circle><path d="M23 21v-2a4 4 0 00-3-3.87M16 3.13a4 4 0 010 7.75"></path>`,
+    // ── Weather / 天气 ──
+    sun: svg `<circle cx="12" cy="12" r="5"></circle><path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"></path>`,
+    moon: svg `<path d="M21 12.79A9 9 0 1111.21 3 7 7 0 0021 12.79z"></path>`,
+    cloud: svg `<path d="M18 10h-1.26A8 8 0 109 20h9a5 5 0 000-10z"></path>`,
+};
+const SVG_STYLE = 'fill:none;stroke:currentColor;stroke-linecap:round;stroke-linejoin:round;stroke-width:1.8;';
+export class IconUtil {
+    static resolveSize(size, fallback = '20px') {
+        if (!size)
+            return fallback;
+        const mapped = ICON_SIZE_MAP[size];
+        if (mapped)
+            return mapped;
+        return /^\d+$/.test(size) ? `${size}px` : size;
+    }
+    static parse(input) {
+        const match = ICON_PATTERN.exec(input);
+        if (match) {
+            const rawType = match[1].toLowerCase();
+            const value = match[2].trim();
+            if (rawType === 'class' ||
+                rawType === 'auto' ||
+                rawType === 'url' ||
+                rawType === 'share' ||
+                rawType === 'remote') {
+                return { type: rawType, value };
+            }
+        }
+        return { type: 'class', value: input };
+    }
+    static renderAuto(value, cssSize, cls, iconStyle, extraStyle = '') {
+        return html `
+      <span class="${cls}" style="${extraStyle}${iconStyle}display:inline-flex;align-items:center;justify-content:center;width:${cssSize};height:${cssSize};border-radius:50%;background:linear-gradient(135deg, var(--aithe-primary-4), var(--aithe-primary-7));color:var(--aithe-color-text-on-primary, #ffffff);font-size:calc(${cssSize} * 0.85);font-weight:600;">
+        ${value.charAt(0).toUpperCase()}
+      </span>
+    `;
+    }
+    static renderClass(value, cssSize, extraStyle = '') {
+        const glyph = ICON_GLYPH_MAP[value] ?? ICON_GLYPH_MAP['sparkles'];
+        return html `
+      <svg viewBox="0 0 24 24" aria-hidden="true"
+        style="${extraStyle}width:${cssSize};height:${cssSize};${SVG_STYLE}">
+        ${glyph}
+      </svg>
+    `;
+    }
+    static render(input, size = '16', cls = '', iconStyle = '', alt = '') {
+        const { type, value } = IconUtil.parse(input);
+        const cssSize = /^\d+$/.test(size) ? `${size}px` : size;
+        switch (type) {
+            case 'auto':
+                return IconUtil.renderAuto(value, cssSize, cls, iconStyle);
+            case 'url':
+            case 'share':
+            case 'remote': {
+                const altText = alt || (value.includes('|')
+                    ? value.split('|')[1].trim()
+                    : '');
+                const src = value.includes('|') ? value.split('|')[0].trim() : value;
+                return html `
+          <span style="${iconStyle}display:inline-flex;position:relative;width:${cssSize};height:${cssSize};">
+            <img class="${cls}" src="${src}" alt="${altText}"
+              style="${iconStyle}display:inline-flex;width:${cssSize};height:${cssSize};object-fit:contain;"
+              @error=${(e) => {
+                    const el = e.target;
+                    el.style.display = 'none';
+                    const fallback = el.nextElementSibling;
+                    if (fallback)
+                        fallback.style.display = 'inline-flex';
+                }}
+            />
+            ${altText
+                    ? html `<span style="position:absolute;top:0;left:0;line-height:1;width:${cssSize};height:${cssSize};border-radius:50%;background:linear-gradient(135deg, var(--aithe-primary-4), var(--aithe-primary-7));color:var(--aithe-color-text-on-primary, #ffffff);font-size:calc(${cssSize} * 0.85);font-weight:600;display:inline-flex;align-items:center;justify-content:center;display:none;">${altText.charAt(0).toUpperCase()}</span>`
+                    : IconUtil.renderClass('image', cssSize, 'display:none;position:absolute;top:0;left:0;')}
+          </span>
+        `;
+            }
+            case 'class':
+            default:
+                return IconUtil.renderClass(value, cssSize);
+        }
+    }
+}

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/index.js

@@ -0,0 +1,4 @@
+export * from './dom';
+export * from './events';
+export * from './validation';
+export * from './icon';

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 string, preventing "[object Object]" output.
+ * Falls back gracefully through multiple strategies:
+ *   1. Pretty-print JSON.stringify for objects (fails on circular references)
+ *   2. Compact JSON.stringify as second attempt
+ *   3. String() as final fallback
+ *
+ * 安全地将任意值转换为字符串，避免 "[object Object]" 输出。
+ * 对象优先尝试格式化 JSON.stringify，失败后降级为紧凑格式，最后 String() 兜底。
+ */
+export 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/utils.js

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

package/dist/utils/validation.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/dist/utils/validation.js

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

package/docs/api/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>
 ```