@aithe/aithe-ui 26.2.2 → 26.3.1

package/dist/components/theme/theme-switch.js

@@ -0,0 +1,318 @@
+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;
+};
+/**
+ * aithe-theme-switch 组件
+ * Theme switch dropdown that integrates theme, shadow, and typo selection in a single submenu.
+ *
+ * 基于 floating overlay 模式实现，在单个下拉菜单中整合主题、阴影和排版切换。
+ * Built on the floating overlay pattern, integrates theme, shadow, and typo switching in one dropdown.
+ *
+ * @fires aithe-theme-change - Emitted when any option is selected. 选择选项时发出，detail 包含 `{ category: string, value: string }`。
+ *   Call `event.preventDefault()` to suppress the built-in switch. 调用 `preventDefault()` 可阻止内置切换逻辑。
+ */
+import { css, html, nothing } from 'lit';
+import { customElement, property, query, state } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
+import { AitheElement } from '../../core/aithe-element';
+import { computeFloatingPosition } from '../../core/floating';
+import { aitheBaseStyles } from '../../core/styles';
+import { aitheUI } from '../../styles/aithe-ui';
+import { themeMenu } from '../../styles/theme';
+import { shadowMenu } from '../../styles/shadow';
+import { shapeMenu } from '../../styles/shape';
+import { typoMenu } from '../../styles/typo';
+import { t } from '../../styles/i18n';
+/**
+ * Build a grouped tree menu structure for theme selection.
+ * Groups: Theme → Shadow → Shape → Typo, each with their respective items.
+ */
+function buildThemeMenu() {
+    return [
+        {
+            id: 'theme-group',
+            label: 'Theme',
+            i18n: 'appearance.group.theme',
+            children: themeMenu.map((group) => ({
+                ...group,
+                children: (group.children ?? []).map((c) => ({ ...c, category: 'theme' })),
+            })),
+        },
+        {
+            id: 'shadow-group',
+            label: 'Shadow',
+            i18n: 'appearance.group.shadow',
+            children: shadowMenu.map((s) => ({ ...s, category: 'shadow' })),
+        },
+        {
+            id: 'shape-group',
+            label: 'Shape',
+            i18n: 'appearance.group.shape',
+            children: shapeMenu.map((s) => ({ ...s, category: 'shape' })),
+        },
+        {
+            id: 'typo-group',
+            label: 'Typo',
+            i18n: 'appearance.group.typo',
+            children: typoMenu.map((t) => ({ ...t, category: 'typo' })),
+        },
+    ];
+}
+let AitheThemeSwitch = class AitheThemeSwitch extends AitheElement {
+    constructor() {
+        super(...arguments);
+        this.placement = 'bottom-end';
+        /** Whether to show only the icon and arrow without the label text. 是否仅显示图标和箭头，不显示标签文字。 */
+        this.iconOnly = false;
+        this.open = false;
+        this.currentTheme = aitheUI.getTheme();
+        this.currentShadow = aitheUI.getShadow();
+        this.currentShape = aitheUI.getShape();
+        this.currentTypo = aitheUI.getTypo();
+        this.themeMenu = buildThemeMenu();
+        this.handleViewportChange = () => this.updatePosition();
+        this.handleOutsideClick = (event) => {
+            if (!this.open)
+                return;
+            if (!event.composedPath().includes(this)) {
+                this.open = false;
+            }
+        };
+        this.toggleOpen = () => {
+            this.open = !this.open;
+            if (this.open) {
+                this.bindViewport();
+            }
+            else {
+                this.unbindViewport();
+            }
+        };
+        this.handleTreeSelect = (event) => {
+            const { value, item } = event.detail;
+            if (!value || !item)
+                return;
+            const category = item.category;
+            if (!category)
+                return;
+            this.open = false;
+            this.unbindViewport();
+            const notPrevented = this.emit('aithe-theme-change', { category, value });
+            if (!notPrevented)
+                return;
+            switch (category) {
+                case 'theme':
+                    aitheUI.setTheme(value);
+                    break;
+                case 'shadow':
+                    aitheUI.setShadow(value);
+                    break;
+                case 'shape':
+                    aitheUI.setShape(value);
+                    break;
+                case 'typo':
+                    aitheUI.setTypo(value);
+                    break;
+            }
+        };
+        this.renderThemeItem = (item) => {
+            if (item.color) {
+                return html `<span
+        style="display:inline-block;width:12px;height:12px;border-radius:50%;border:1px solid rgba(0,0,0,0.15);flex-shrink:0;background:${item.color}"
+      ></span>`;
+            }
+            if (item.preview) {
+                return html `<span
+        style="display:inline-block;width:24px;height:24px;border:1px solid var(--aithe-color-border);flex-shrink:0;background:var(--aithe-color-surface-elevated);border-radius:${item.preview}"
+      ></span>`;
+            }
+            if (item.icon) {
+                return html `<span
+        style="display:inline-block;width:24px;height:24px;flex-shrink:0;display:flex;align-items:center;justify-content:center;font-size:16px;color:var(--aithe-color-text-muted)"
+      >${item.icon}</span>`;
+            }
+            return nothing;
+        };
+    }
+    static { this.styles = [
+        aitheBaseStyles,
+        css `
+      :host {
+        display: inline-flex;
+        position: relative;
+      }
+
+      .trigger {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--aithe-space-2);
+        min-height: 34px;
+        padding: 0 var(--aithe-space-3);
+        border: 1px solid var(--aithe-color-border);
+        border-radius: var(--aithe-radius-full);
+        background: var(--aithe-color-surface);
+        color: var(--aithe-color-text);
+        cursor: pointer;
+        font-size: var(--aithe-font-size-sm);
+        font-family: inherit;
+        transition:
+          border-color 0.15s,
+          background 0.15s;
+      }
+
+      .trigger:hover {
+        border-color: var(--aithe-primary-6);
+      }
+
+      :host([icon-only]) .trigger {
+        min-height: 32px;
+        min-width: 32px;
+        padding: 0 var(--aithe-space-1);
+        justify-content: center;
+      }
+
+      :host([icon-only]) .trigger-label {
+        display: none;
+      }
+
+      .icon {
+        font-size: 14px;
+        color: var(--aithe-color-text-muted);
+      }
+
+      .arrow {
+        font-size: 10px;
+        color: var(--aithe-color-text-muted);
+        transition: transform var(--aithe-duration-fast) var(--aithe-ease-standard);
+      }
+
+      .arrow.open {
+        transform: rotate(180deg);
+      }
+
+      .overlay {
+        position: fixed;
+        z-index: var(--aithe-z-dropdown);
+        width: max-content;
+        min-width: 200px;
+        padding: var(--aithe-space-2);
+        border: 1px solid var(--aithe-color-border);
+        border-radius: var(--aithe-container-radius-lg);
+        background: var(--aithe-color-surface-elevated);
+        box-shadow: var(--aithe-shadow-3);
+      }
+
+      aithe-tree-menu {
+        display: block;
+        width: 100%;
+      }
+    `,
+    ]; }
+    getActiveId() {
+        return this.currentTheme;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        document.addEventListener('mousedown', this.handleOutsideClick);
+        this.unsubscribeTheme = aitheUI.onThemeChange(() => {
+            this.currentTheme = aitheUI.getTheme();
+        });
+        this.unsubscribeShadow = aitheUI.onShadowChange(() => {
+            this.currentShadow = aitheUI.getShadow();
+        });
+        this.unsubscribeShape = aitheUI.onShapeChange(() => {
+            this.currentShape = aitheUI.getShape();
+        });
+        this.unsubscribeTypo = aitheUI.onTypoChange(() => {
+            this.currentTypo = aitheUI.getTypo();
+        });
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        document.removeEventListener('mousedown', this.handleOutsideClick);
+        this.unbindViewport();
+        this.unsubscribeTheme?.();
+        this.unsubscribeShadow?.();
+        this.unsubscribeShape?.();
+        this.unsubscribeTypo?.();
+    }
+    updated() {
+        if (this.open) {
+            queueMicrotask(() => this.updatePosition());
+        }
+    }
+    bindViewport() {
+        globalThis.addEventListener('resize', this.handleViewportChange);
+        globalThis.addEventListener('scroll', this.handleViewportChange, true);
+    }
+    unbindViewport() {
+        globalThis.removeEventListener('resize', this.handleViewportChange);
+        globalThis.removeEventListener('scroll', this.handleViewportChange, true);
+    }
+    updatePosition() {
+        const overlay = this.overlayEl;
+        const trigger = this.triggerEl;
+        if (!overlay || !trigger || !this.open)
+            return;
+        const anchorRect = trigger.getBoundingClientRect();
+        const overlayRect = overlay.getBoundingClientRect();
+        const pos = computeFloatingPosition(anchorRect, overlayRect, this.placement, { offset: 8 });
+        overlay.style.left = `${pos.left}px`;
+        overlay.style.top = `${pos.top}px`;
+    }
+    render() {
+        const displayLabel = t('appearance.label', 'Appearance');
+        return html `
+      <button class="trigger" type="button" @click=${this.toggleOpen}>
+        <span class="icon">✦</span>
+        <span class="trigger-label">${displayLabel}</span>
+        <span class=${classMap({ arrow: true, open: this.open })}>▾</span>
+      </button>
+      ${this.open
+            ? html `
+            <div class="overlay" role="menu">
+              <aithe-tree-menu
+                .items=${this.themeMenu}
+                .active=${this.getActiveId()}
+                .itemRenderer=${this.renderThemeItem}
+                @aithe-select=${this.handleTreeSelect}
+              ></aithe-tree-menu>
+            </div>
+          `
+            : nothing}
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], AitheThemeSwitch.prototype, "placement", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'icon-only' })
+], AitheThemeSwitch.prototype, "iconOnly", void 0);
+__decorate([
+    state()
+], AitheThemeSwitch.prototype, "open", void 0);
+__decorate([
+    state()
+], AitheThemeSwitch.prototype, "currentTheme", void 0);
+__decorate([
+    state()
+], AitheThemeSwitch.prototype, "currentShadow", void 0);
+__decorate([
+    state()
+], AitheThemeSwitch.prototype, "currentShape", void 0);
+__decorate([
+    state()
+], AitheThemeSwitch.prototype, "currentTypo", void 0);
+__decorate([
+    query('.trigger')
+], AitheThemeSwitch.prototype, "triggerEl", void 0);
+__decorate([
+    query('.overlay')
+], AitheThemeSwitch.prototype, "overlayEl", void 0);
+AitheThemeSwitch = __decorate([
+    customElement('aithe-theme-switch')
+], AitheThemeSwitch);
+export { AitheThemeSwitch };

package/dist/components/theme/typo-picker.d.ts

@@ -0,0 +1,28 @@
+import { AitheElement } from '../../core/aithe-element';
+import { type AithePlacement } from '../../core/floating';
+import type { AitheTypoName } from '../../types';
+export declare class AitheTypoPicker extends AitheElement {
+    placement: AithePlacement;
+    /** Whether to show only the icon and arrow without the label text. 是否仅显示图标和箭头，不显示标签文字。 */
+    iconOnly: boolean;
+    value?: AitheTypoName;
+    private open;
+    private currentTypo;
+    private readonly triggerEl?;
+    private readonly overlayEl?;
+    static readonly styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
+    private getEffectiveTypo;
+    private readonly handleViewportChange;
+    private unsubscribe?;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(): void;
+    private bindViewport;
+    private unbindViewport;
+    private updatePosition;
+    private readonly handleOutsideClick;
+    private readonly toggleOpen;
+    private readonly handleTreeSelect;
+    render(): import("lit-html").TemplateResult<1>;
+}
+//# sourceMappingURL=typo-picker.d.ts.map

package/dist/components/theme/typo-picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typo-picker.d.ts","sourceRoot":"","sources":["../../../src/components/theme/typo-picker.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,KAAK,cAAc,EAA2B,MAAM,gBAAgB,CAAC;AAI9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAI5C,qBACa,eAAgB,SAAQ,YAAY;IACnB,SAAS,EAAE,cAAc,CAAgB;IAErE,0FAA0F;IACrC,QAAQ,UAAS;IAE1C,KAAK,CAAC,EAAE,aAAa,CAAC;IAEzC,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,WAAW,CAAoC;IAE7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAc;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAc;IAE5D,MAAM,CAAC,QAAQ,CAAC,MAAM,0DAyEpB;IAEF,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA+B;IAEpE,OAAO,CAAC,WAAW,CAAC,CAAa;IAEjC,iBAAiB,IAAI,IAAI;IAQzB,oBAAoB,IAAI,IAAI;IAO5B,SAAS,CAAC,OAAO,IAAI,IAAI;IAMzB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAKjC;IAEF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAOzB;IAEF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAU/B;IAEF,MAAM;CA6BP"}

package/dist/components/theme/typo-picker.js

@@ -0,0 +1,219 @@
+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, nothing } from 'lit';
+import { customElement, property, query, state } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
+import { AitheElement } from '../../core/aithe-element';
+import { computeFloatingPosition } from '../../core/floating';
+import { aitheBaseStyles } from '../../core/styles';
+import { aitheUI } from '../../styles/aithe-ui';
+import { typoMenu } from '../../styles/typo';
+import { t } from '../../styles/i18n';
+let AitheTypoPicker = class AitheTypoPicker extends AitheElement {
+    constructor() {
+        super(...arguments);
+        this.placement = 'bottom-end';
+        /** Whether to show only the icon and arrow without the label text. 是否仅显示图标和箭头，不显示标签文字。 */
+        this.iconOnly = false;
+        this.open = false;
+        this.currentTypo = aitheUI.getTypo();
+        this.handleViewportChange = () => this.updatePosition();
+        this.handleOutsideClick = (event) => {
+            if (!this.open)
+                return;
+            if (!event.composedPath().includes(this)) {
+                this.open = false;
+            }
+        };
+        this.toggleOpen = () => {
+            this.open = !this.open;
+            if (this.open) {
+                this.bindViewport();
+            }
+            else {
+                this.unbindViewport();
+            }
+        };
+        this.handleTreeSelect = (event) => {
+            const typo = event.detail.value;
+            if (!typo)
+                return;
+            this.open = false;
+            this.unbindViewport();
+            const notPrevented = this.emit('aithe-typo-change', { typo });
+            if (notPrevented) {
+                aitheUI.setTypo(typo);
+            }
+        };
+    }
+    static { this.styles = [
+        aitheBaseStyles,
+        css `
+      :host {
+        display: inline-flex;
+        position: relative;
+      }
+
+      .trigger {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--aithe-space-2);
+        min-height: 34px;
+        padding: 0 var(--aithe-space-3);
+        border: 1px solid var(--aithe-color-border);
+        border-radius: var(--aithe-radius-full);
+        background: var(--aithe-color-surface);
+        color: var(--aithe-color-text);
+        cursor: pointer;
+        font-size: var(--aithe-font-size-sm);
+        font-family: inherit;
+        transition:
+          border-color 0.15s,
+          background 0.15s;
+      }
+
+      .trigger:hover {
+        border-color: var(--aithe-primary-6);
+      }
+
+      :host([icon-only]) .trigger {
+        min-height: 32px;
+        min-width: 32px;
+        padding: 0 var(--aithe-space-1);
+        justify-content: center;
+      }
+
+      :host([icon-only]) .trigger-label {
+        display: none;
+      }
+
+      .icon {
+        font-size: 14px;
+        color: var(--aithe-color-text-muted);
+      }
+
+      .arrow {
+        font-size: 10px;
+        color: var(--aithe-color-text-muted);
+        transition: transform var(--aithe-duration-fast) var(--aithe-ease-standard);
+      }
+
+      .arrow.open {
+        transform: rotate(180deg);
+      }
+
+      .overlay {
+        position: fixed;
+        z-index: var(--aithe-z-dropdown);
+        width: max-content;
+        min-width: 200px;
+        padding: var(--aithe-space-2);
+        border: 1px solid var(--aithe-color-border);
+        border-radius: var(--aithe-container-radius-lg);
+        background: var(--aithe-color-surface-elevated);
+        box-shadow: var(--aithe-shadow-3);
+      }
+
+      aithe-tree-menu {
+        display: block;
+        width: 100%;
+      }
+    `,
+    ]; }
+    getEffectiveTypo() {
+        return this.value ?? this.currentTypo;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        document.addEventListener('mousedown', this.handleOutsideClick);
+        this.unsubscribe = aitheUI.onTypoChange(() => {
+            this.currentTypo = aitheUI.getTypo();
+        });
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        document.removeEventListener('mousedown', this.handleOutsideClick);
+        this.unbindViewport();
+        this.unsubscribe?.();
+    }
+    updated() {
+        if (this.open) {
+            queueMicrotask(() => this.updatePosition());
+        }
+    }
+    bindViewport() {
+        window.addEventListener('resize', this.handleViewportChange);
+        window.addEventListener('scroll', this.handleViewportChange, true);
+    }
+    unbindViewport() {
+        window.removeEventListener('resize', this.handleViewportChange);
+        window.removeEventListener('scroll', this.handleViewportChange, true);
+    }
+    updatePosition() {
+        const overlay = this.overlayEl;
+        const trigger = this.triggerEl;
+        if (!overlay || !trigger || !this.open)
+            return;
+        const anchorRect = trigger.getBoundingClientRect();
+        const overlayRect = overlay.getBoundingClientRect();
+        const pos = computeFloatingPosition(anchorRect, overlayRect, this.placement, { offset: 8 });
+        overlay.style.left = `${pos.left}px`;
+        overlay.style.top = `${pos.top}px`;
+    }
+    render() {
+        const effectiveTypo = this.getEffectiveTypo();
+        const displayLabel = t(`typoPicker.${effectiveTypo}`, effectiveTypo.charAt(0).toUpperCase() + effectiveTypo.slice(1));
+        return html `
+      <button class="trigger" type="button" @click=${this.toggleOpen}>
+        <span class="icon">✦</span>
+        <span class="trigger-label">${displayLabel}</span>
+        <span class=${classMap({ arrow: true, open: this.open })}>▾</span>
+      </button>
+      ${this.open
+            ? html `
+            <div class="overlay" role="menu">
+              <aithe-tree-menu
+                .items=${typoMenu}
+                .active=${effectiveTypo}
+                .itemRenderer=${(item) => item.icon
+                ? html `<span
+                        style="display:inline-block;width:24px;height:24px;flex-shrink:0;display:flex;align-items:center;justify-content:center;font-size:16px;color:var(--aithe-color-text-muted)"
+                      >${item.icon}</span>`
+                : nothing}
+                @aithe-select=${this.handleTreeSelect}
+              ></aithe-tree-menu>
+            </div>
+          `
+            : nothing}
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], AitheTypoPicker.prototype, "placement", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'icon-only' })
+], AitheTypoPicker.prototype, "iconOnly", void 0);
+__decorate([
+    property({ type: String })
+], AitheTypoPicker.prototype, "value", void 0);
+__decorate([
+    state()
+], AitheTypoPicker.prototype, "open", void 0);
+__decorate([
+    state()
+], AitheTypoPicker.prototype, "currentTypo", void 0);
+__decorate([
+    query('.trigger')
+], AitheTypoPicker.prototype, "triggerEl", void 0);
+__decorate([
+    query('.overlay')
+], AitheTypoPicker.prototype, "overlayEl", void 0);
+AitheTypoPicker = __decorate([
+    customElement('aithe-typo-picker')
+], AitheTypoPicker);
+export { AitheTypoPicker };

package/dist/core/AGENTS.md

@@ -0,0 +1,43 @@
+# src/core/ — 核心模块
+
+## 概述
+
+包含 Aithe UI 组件库的核心基础设施，所有组件继承自 `AitheElement`。
+
+## 目录结构
+
+| 模块       | 文件                  | 说明                                                                                        |
+| ---------- | --------------------- | ------------------------------------------------------------------------------------------- |
+| 基类       | `aithe-element.ts`    | 所有组件的基类，继承 LitElement，提供 theme/disabled/log 等公共属性和 `emit()` 事件发射方法 |
+| 浮层       | `floating.ts`         | 浮层定位引擎，用于 tooltip/popover/dropdown 等弹出层                                        |
+| 锚定覆盖   | `anchored-overlay.ts` | 锚定覆盖层组件，提供定位（含含入块偏移修正）+ 点击外部关闭 + 焦点管理 |
+| 样式       | `styles.ts`           | 基础样式集合，导出 `aitheBaseStyles` 供所有组件使用                                         |
+| 类型       | `types.ts`            | 核心类型定义                                                                                |
+| 路由       | `router/index.ts`     | 轻量前端路由，支持 hash/history 模式、动态路由、路由守卫                                    |
+| 数据中间层 | `datahub/`            | DataHub：请求调度、缓存、去重、Mock、幂等防护                                               |
+| 代码高亮   | `highlight/`          | 自研语法高亮引擎，支持 38 种语言                                                            |
+| Markdown   | `markdown/`           | Markdown 解析渲染模块，支持插件架构                                                         |
+| 日志       | `logger/`             | 日志系统，支持 console 劫持、级别过滤、远程上报                                             |
+| 自动表单   | `autoform/`           | 表单控件类型注册表和规则引擎                                                                |
+| 过滤器     | `filter/`             | 数据格式化框架，内置 amount/date/empty/bytes/timeAgo 过滤器，支持链式表达式                  |
+
+## 编码规范
+
+- 所有导出必须通过 `src/index.ts` 统一导出
+- 导入必须使用 `@core/*` 路径别名，禁止 `../` 相对路径
+- 基类属性使用 `@property` 装饰器，响应式状态使用 `@state`
+- 事件使用 `this.emit('event-name', detail)` 方式发射
+- 静态常量和固定配置必须加 `readonly`
+- 中英文双语 JSDoc 注释
+
+## 关键约定
+
+- `AitheElement` 是所有组件的唯一基类，不要直接继承 `LitElement`
+- 新增核心模块时需在 `src/index.ts` 添加对应导出
+- DataHub 适配器通过 `registerAdapter` 注册，可扩展
+- 高亮引擎语言通过 `import './lang-xxx'` 副作用导入注册
+- 路由守卫返回 `false` 阻止导航
+- Filter 接口设计为无状态，参数通过 `apply(value, ...args)` 变参传入，工厂注册时 `new ctor()` 一次缓存复用
+- Filter 表达式语法：`"filterName arg1 arg2 | filter2"`，管道符 `|` 分隔多个过滤器，从左到右依次执行
+- MockAdapter 的 `mockData` 支持 `mockDelay` 模拟网络延迟，`mockPath` 加载本地 JSON 文件（无延迟）
+- 测试文件统一放在模块下的 `__tests__/` 目录，利用 `package.json` 的 `files` 字段排除 src 发布

package/dist/core/aithe-element.d.ts

@@ -1,2 +1,63 @@
-export { AitheElement } from '../base/aithe-element';
+import { LitElement } from 'lit';
+import type { AitheVariant } from "../styles/types";
+/**
+ * Base class for all Aithe UI components. Extends LitElement with theme awareness,
+ * accessibility helpers, a unified event emission API, and browser environment detection.
+ * 所有 Aithe UI 组件的基类。继承 LitElement，提供主题感知、无障碍辅助、统一事件发射 API 和浏览器环境检测。
+ *
+ * @example
+ * ```ts
+ * @customElement('aithe-my-comp')
+ * export class AitheMyComp extends AitheElement {}
+ * ```
+ */
+export declare class AitheElement extends LitElement {
+    /** Visual variant of the component. 组件的视觉变体。 */
+    variant: AitheVariant;
+    /** Size preset of the component. 组件的尺寸规格。 */
+    size: string;
+    /** Local theme override; falls back to the closest themed ancestor or global theme when empty. 本地主题覆盖；为空时继承最近带主题祖先或全局主题。 */
+    theme: string;
+    /** Whether the component is disabled. 组件是否禁用。 */
+    disabled: boolean;
+    /** When true, all events emitted by this component will be captured by the logger. 为 true 时，组件的所有事件将被日志器捕获。 */
+    log: boolean;
+    constructor();
+    /**
+     * Emit a custom event with the `aithe-` prefix convention.
+     * 发射遵循 `aithe-` 前缀约定的自定义事件。
+     *
+     * @param type - Event type (without prefix). 事件类型（不含前缀）。
+     * @param detail - Event payload. 事件载荷。
+     * @returns Whether the event was not cancelled. 事件是否未被取消。
+     */
+    emit(type: string, detail?: unknown): boolean;
+    /**
+     * Resolved theme name: local override → closest themed ancestor → global theme.
+     * 计算后的主题名：本地覆盖 → 最近带主题祖先 → 全局主题。
+     */
+    get computedTheme(): string;
+    connectedCallback(): void;
+    /**
+     * Focus the first focusable element within the given root.
+     * 聚焦给定根节点内第一个可聚焦元素。
+     *
+     * @param root - Parent node to search within. 搜索的父节点。
+     */
+    protected focusFirst(root?: ParentNode): void;
+    /**
+     * Trap keyboard focus within the given root (Tab / Shift+Tab cycle).
+     * 在给定根节点内捕获键盘焦点（Tab / Shift+Tab 循环）。
+     *
+     * @param event - Keyboard event to handle. 要处理的键盘事件。
+     * @param root - Parent node to trap focus within. 捕获焦点的父节点。
+     */
+    protected trapFocus(event: KeyboardEvent, root?: ParentNode): void;
+    /**
+     * Synchronize base accessibility attributes (aria-disabled, data-aithe-theme).
+     * 同步基础无障碍属性（aria-disabled、data-aithe-theme）。
+     */
+    private syncBaseA11yState;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+}
 //# sourceMappingURL=aithe-element.d.ts.map

package/dist/core/aithe-element.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aithe-element.d.ts","sourceRoot":"","sources":["../../src/core/aithe-element.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"aithe-element.d.ts","sourceRoot":"","sources":["../../src/core/aithe-element.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAKjC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,qBAAa,YAAa,SAAQ,UAAU;IAC1C,gDAAgD;IACpB,OAAO,EAAG,YAAY,CAAa;IAE/D,6CAA6C;IACjB,IAAI,SAAQ;IAExC,4HAA4H;IAChG,KAAK,SAAM;IAEvC,iDAAiD;IACL,QAAQ,UAAS;IAE7D,+GAA+G;IAClF,GAAG,UAAS;;IAOzC;;;;;;;OAOG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO;IAO7C;;;OAGG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAEQ,iBAAiB,IAAI,IAAI;IAKlC;;;;;OAKG;IACH,SAAS,CAAC,UAAU,CAAC,IAAI,GAAE,UAA4B,GAAG,IAAI;IAI9D;;;;;;OAMG;IACH,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,GAAE,UAA4B,GAAG,IAAI;IA0BnF;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAchB,wBAAwB,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,IAAI;CAIR"}