@aithe/aithe-ui 26.2.2 → 26.3.1

package/dist/styles/AGENTS.md

@@ -0,0 +1,36 @@
+# src/styles/ — 样式体系
+
+## 概述
+
+Aithe UI 的正交定制样式系统：Theme × Shape × Shadow × Typo + 国际化 + 布局密度。
+
+## 目录结构
+
+| 模块     | 文件            | 说明                                                                            |
+| -------- | --------------- | ------------------------------------------------------------------------------- |
+| 全局单例 | `aithe-ui.ts`   | `AitheUI` 全局对象，提供 `setTheme/setShape/setShadow/setTypo/setLocale` 等 API |
+| 全局样式 | `global.css.ts` | 全局 CSS 变量和重置样式                                                         |
+| Mixins   | `mixins.ts`     | CSS mixin 工具函数                                                              |
+| 类型     | `types.ts`      | 样式相关类型定义                                                                |
+| 主题     | `theme/`        | 22 套主题（11 Light + 11 Dark），每套含完整设计令牌                             |
+| 形状     | `shape/`        | 8 种形状风格（rounded/pill/circle/organic 等）                                  |
+| 阴影     | `shadow/`       | 9 种阴影风格（flat/neumorphism/glassmorphism 等）                               |
+| 排版     | `typo/`         | 4 种排版风格（minimal/business/luxury/compact）                                 |
+| 布局     | `layout/`       | 布局密度控制                                                                    |
+| 国际化   | `i18n/`         | 10 种语言 locale，翻译函数 `t()`，locale 变更订阅                               |
+
+## 编码规范
+
+- 主题文件导出 `THEME_XXX` 常量，含完整的 CSS 变量映射
+- 形状/阴影/排版文件导出对应的 token 映射
+- 所有样式使用 Lit `css` 模板字面量
+- 导入使用 `@styles/*` 路径别名
+- 中英文双语 JSDoc 注释
+
+## 关键约定
+
+- 新增主题：在 `theme/` 下创建文件，在 `theme/index.ts` 中注册，在 `aithe-ui.ts` 中集成
+- 新增语言：在 `i18n/locales/` 下创建文件，在 `i18n/index.ts` 中注册
+- 主题名使用 kebab-case（如 `zh-CN`、`en-US`）
+- CSS 变量命名遵循 `--aithe-{category}-{token}` 模式
+- `aithe-ui.ts` 是全局单例入口，不要直接修改内部模块的默认值

package/dist/styles/aithe-ui.d.ts

@@ -0,0 +1,113 @@
+import type { AitheLayoutName, AitheShadowName, AitheShapeName, AitheThemeName, AitheTypoName } from './types';
+import { type AitheLocale } from './i18n';
+/**
+ * Unified API class for managing Aithe UI global state: theme, shape, shadow, layout, and i18n.
+ * Aithe UI 全局状态统一管理类：主题、形状、阴影、布局和国际化。
+ *
+ * Provides a single entry point for all runtime configuration and persistence.
+ * 提供所有运行时配置和持久化的单一入口。
+ *
+ * @example
+ * ```ts
+ * import { aitheUI } from '@aithe/aithe-ui';
+ * aitheUI.setTheme('dark');
+ * aitheUI.setShape('pill');
+ * aitheUI.setShadow('neumorphism');
+ * ```
+ */
+export declare class AitheUI {
+    private readonly _ua;
+    /**
+     * Create an AitheUI instance and initialize all subsystems with optional defaults.
+     * 创建 AitheUI 实例，并使用可选默认值初始化所有子系统。
+     *
+     * @param options - Default values for each subsystem. 各子系统的默认值。
+     */
+    constructor(options?: {
+        defaultTheme?: AitheThemeName;
+        defaultLayout?: AitheLayoutName;
+        defaultShape?: AitheShapeName;
+        defaultShadow?: AitheShadowName;
+        defaultTypo?: AitheTypoName;
+        defaultLocale?: AitheLocale;
+    });
+    /** Set the global color theme and optionally persist to localStorage. 设置全局颜色主题，可选持久化到 localStorage。 */
+    setTheme(theme: AitheThemeName, persist?: boolean): void;
+    /** Get the current global color theme. 获取当前全局颜色主题。 */
+    getTheme(): AitheThemeName;
+    /** Subscribe to theme changes. Returns an unsubscribe function. 订阅主题变更，返回取消订阅函数。 */
+    onThemeChange(fn: () => void): () => void;
+    /** Set the global layout density and optionally persist to localStorage. 设置全局布局密度，可选持久化到 localStorage。 */
+    setLayout(layout: AitheLayoutName, persist?: boolean): void;
+    /** Get the current global layout density. 获取当前全局布局密度。 */
+    getLayout(): AitheLayoutName;
+    /** Subscribe to layout density changes. Returns an unsubscribe function. 订阅布局密度变更，返回取消订阅函数。 */
+    onLayoutChange(fn: () => void): () => void;
+    /** Set the global shape style and optionally persist to localStorage. 设置全局形状风格，可选持久化到 localStorage。 */
+    setShape(shape: AitheShapeName, persist?: boolean): void;
+    /** Get the current global shape style. 获取当前全局形状风格。 */
+    getShape(): AitheShapeName;
+    /** Get the list of all built-in shape style names. 获取所有内置形状风格名称列表。 */
+    getShapes(): import("./types").AitheBuiltinShape[];
+    /** Get the CSS variable token map for a given shape style. 获取指定形状风格的 CSS 变量 token 映射。 */
+    getShapeTokens(shape: AitheShapeName): Record<string, string> | undefined;
+    /** Subscribe to shape style changes. Returns an unsubscribe function. 订阅形状风格变更，返回取消订阅函数。 */
+    onShapeChange(fn: () => void): () => void;
+    /** Set the global shadow style and optionally persist to localStorage. 设置全局阴影风格，可选持久化到 localStorage。 */
+    setShadow(shadow: AitheShadowName, persist?: boolean): void;
+    /** Get the current global shadow style. 获取当前全局阴影风格。 */
+    getShadow(): AitheShadowName;
+    /** Get the list of all built-in shadow style names. 获取所有内置阴影风格名称列表。 */
+    getShadows(): import("./types").AitheBuiltinShadow[];
+    /** Get the CSS variable token map for a given shadow style. 获取指定阴影风格的 CSS 变量 token 映射。 */
+    getShadowTokens(shadow: AitheShadowName): Record<string, string> | undefined;
+    /** Subscribe to shadow style changes. Returns an unsubscribe function. 订阅阴影风格变更，返回取消订阅函数。 */
+    onShadowChange(fn: () => void): () => void;
+    /** Set the global typo style and optionally persist to localStorage. 设置全局排版风格，可选持久化到 localStorage。 */
+    setTypo(typo: AitheTypoName, persist?: boolean): void;
+    /** Get the current global typo style. 获取当前全局排版风格。 */
+    getTypo(): AitheTypoName;
+    /** Get the list of all built-in typo style names. 获取所有内置排版风格名称列表。 */
+    getTypos(): import("./types").AitheBuiltinTypo[];
+    /** Get the CSS variable token map for a given typo style. 获取指定排版风格的 CSS 变量 token 映射。 */
+    getTypoTokens(typo: AitheTypoName): Record<string, string> | undefined;
+    /** Subscribe to typo style changes. Returns an unsubscribe function. 订阅排版风格变更，返回取消订阅函数。 */
+    onTypoChange(fn: () => void): () => void;
+    /** Set the global locale and optionally persist to localStorage. 设置全局语言，可选持久化到 localStorage。 */
+    setLocale(locale: AitheLocale, persist?: boolean): void;
+    /** Get the current global locale. 获取当前全局语言。 */
+    getLocale(): AitheLocale;
+    /** Get the list of all registered locale identifiers. 获取所有已注册的语言标识列表。 */
+    getLocales(): AitheLocale[];
+    /** Subscribe to locale changes. Returns an unsubscribe function. 订阅语言变更，返回取消订阅函数。 */
+    onLocaleChange(fn: () => void): () => void;
+    /** Merge additional translations into an existing locale. 合并追加翻译条目到已有语言。 */
+    registerLocale(locale: AitheLocale, translations: Record<string, string>): void;
+    /** Translate a key using the current locale. 使用当前语言翻译指定键。 */
+    t(key: string, dft?: string, params?: Record<string, string | number>): string;
+    /** Whether the UA indicates a mobile device (Android/iOS/WebOS/Blackberry). UA 是否指示移动设备。 */
+    get isMobile(): boolean;
+    /** Whether the UA indicates Android. UA 是否指示 Android。 */
+    get isAndroid(): boolean;
+    /** Whether the UA indicates iOS. UA 是否指示 iOS。 */
+    get isIOS(): boolean;
+    /** Whether the UA indicates Chrome (not Edge). UA 是否指示 Chrome（非 Edge）。 */
+    get isChrome(): boolean;
+    /** Whether the UA indicates Edge. UA 是否指示 Edge。 */
+    get isEdge(): boolean;
+    /** Whether the UA indicates WeChat built-in browser. UA 是否指示微信内置浏览器。 */
+    get isWechat(): boolean;
+    /** Whether the UA indicates Windows. UA 是否指示 Windows。 */
+    get isWindows(): boolean;
+    /** Whether the UA indicates macOS. UA 是否指示 macOS。 */
+    get isMacOS(): boolean;
+    /** Whether the device is truly mobile (UA + touch + small screen + not desktop OS). 是否为真实移动设备。 */
+    get isRealMobile(): boolean;
+    /** Whether Chrome DevTools device emulation is active. Chrome 开发者工具设备模拟是否激活。 */
+    get isChromeEmulator(): boolean;
+    /** Whether the device supports touch events. 设备是否支持触摸事件。 */
+    get supportsTouch(): boolean;
+}
+/** Default singleton instance of AitheUI. AitheUI 的默认单例实例。 */
+export declare const aitheUI: AitheUI;
+//# sourceMappingURL=aithe-ui.d.ts.map

package/dist/styles/aithe-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aithe-ui.d.ts","sourceRoot":"","sources":["../../src/styles/aithe-ui.ts"],"names":[],"mappings":"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"}

package/dist/styles/aithe-ui.js

@@ -0,0 +1,185 @@
+import { AITHE_DEFAULT_THEME, initAitheTheme, onAitheThemeChange, registerAitheTheme, setGlobalTheme, } from './theme';
+import { AITHE_DEFAULT_LAYOUT, initAitheLayout, setAitheLayout, getAitheLayout, onAitheLayoutChange, } from './layout';
+import { AITHE_DEFAULT_SHAPE, initAitheShape, setAitheShape, getAitheShape, getAitheShapes, getShapeTokens, onAitheShapeChange, } from './shape';
+import { AITHE_DEFAULT_SHADOW, initAitheShadow, setAitheShadow, getAitheShadow, getAitheShadows, getShadowTokens, onAitheShadowChange, } from './shadow';
+import { AITHE_DEFAULT_TYPO, initAitheTypo, setAitheTypo, getAitheTypo, getAitheTypos, getTypoTokens, onAitheTypoChange, } from './typo';
+import { AITHE_DEFAULT_LOCALE, initAitheLocale, setAitheLocale, getAitheLocale, getAitheLocales, onAitheLocaleChange, registerAitheTranslations, t as translate, } from './i18n';
+/**
+ * Unified API class for managing Aithe UI global state: theme, shape, shadow, layout, and i18n.
+ * Aithe UI 全局状态统一管理类：主题、形状、阴影、布局和国际化。
+ *
+ * Provides a single entry point for all runtime configuration and persistence.
+ * 提供所有运行时配置和持久化的单一入口。
+ *
+ * @example
+ * ```ts
+ * import { aitheUI } from '@aithe/aithe-ui';
+ * aitheUI.setTheme('dark');
+ * aitheUI.setShape('pill');
+ * aitheUI.setShadow('neumorphism');
+ * ```
+ */
+export class AitheUI {
+    /**
+     * Create an AitheUI instance and initialize all subsystems with optional defaults.
+     * 创建 AitheUI 实例，并使用可选默认值初始化所有子系统。
+     *
+     * @param options - Default values for each subsystem. 各子系统的默认值。
+     */
+    constructor(options) {
+        initAitheTheme(options?.defaultTheme ?? AITHE_DEFAULT_THEME);
+        initAitheLayout(options?.defaultLayout ?? AITHE_DEFAULT_LAYOUT);
+        initAitheShape(options?.defaultShape ?? AITHE_DEFAULT_SHAPE);
+        initAitheShadow(options?.defaultShadow ?? AITHE_DEFAULT_SHADOW);
+        initAitheTypo(options?.defaultTypo ?? AITHE_DEFAULT_TYPO);
+        initAitheLocale(options?.defaultLocale ?? AITHE_DEFAULT_LOCALE);
+        this._ua = navigator.userAgent.toLowerCase();
+    }
+    /** Set the global color theme and optionally persist to localStorage. 设置全局颜色主题，可选持久化到 localStorage。 */
+    setTheme(theme, persist = true) {
+        registerAitheTheme();
+        setGlobalTheme(theme, persist);
+    }
+    /** Get the current global color theme. 获取当前全局颜色主题。 */
+    getTheme() {
+        registerAitheTheme();
+        return document.documentElement.dataset.aitheTheme || AITHE_DEFAULT_THEME;
+    }
+    /** Subscribe to theme changes. Returns an unsubscribe function. 订阅主题变更，返回取消订阅函数。 */
+    onThemeChange(fn) {
+        return onAitheThemeChange(fn);
+    }
+    /** Set the global layout density and optionally persist to localStorage. 设置全局布局密度，可选持久化到 localStorage。 */
+    setLayout(layout, persist = true) {
+        setAitheLayout(layout, persist);
+    }
+    /** Get the current global layout density. 获取当前全局布局密度。 */
+    getLayout() {
+        return getAitheLayout();
+    }
+    /** Subscribe to layout density changes. Returns an unsubscribe function. 订阅布局密度变更，返回取消订阅函数。 */
+    onLayoutChange(fn) {
+        return onAitheLayoutChange(fn);
+    }
+    /** Set the global shape style and optionally persist to localStorage. 设置全局形状风格，可选持久化到 localStorage。 */
+    setShape(shape, persist = true) {
+        setAitheShape(shape, persist);
+    }
+    /** Get the current global shape style. 获取当前全局形状风格。 */
+    getShape() {
+        return getAitheShape();
+    }
+    /** Get the list of all built-in shape style names. 获取所有内置形状风格名称列表。 */
+    getShapes() {
+        return getAitheShapes();
+    }
+    /** Get the CSS variable token map for a given shape style. 获取指定形状风格的 CSS 变量 token 映射。 */
+    getShapeTokens(shape) {
+        return getShapeTokens(shape);
+    }
+    /** Subscribe to shape style changes. Returns an unsubscribe function. 订阅形状风格变更，返回取消订阅函数。 */
+    onShapeChange(fn) {
+        return onAitheShapeChange(fn);
+    }
+    /** Set the global shadow style and optionally persist to localStorage. 设置全局阴影风格，可选持久化到 localStorage。 */
+    setShadow(shadow, persist = true) {
+        setAitheShadow(shadow, persist);
+    }
+    /** Get the current global shadow style. 获取当前全局阴影风格。 */
+    getShadow() {
+        return getAitheShadow();
+    }
+    /** Get the list of all built-in shadow style names. 获取所有内置阴影风格名称列表。 */
+    getShadows() {
+        return getAitheShadows();
+    }
+    /** Get the CSS variable token map for a given shadow style. 获取指定阴影风格的 CSS 变量 token 映射。 */
+    getShadowTokens(shadow) {
+        return getShadowTokens(shadow);
+    }
+    /** Subscribe to shadow style changes. Returns an unsubscribe function. 订阅阴影风格变更，返回取消订阅函数。 */
+    onShadowChange(fn) {
+        return onAitheShadowChange(fn);
+    }
+    /** Set the global typo style and optionally persist to localStorage. 设置全局排版风格，可选持久化到 localStorage。 */
+    setTypo(typo, persist = true) {
+        setAitheTypo(typo, persist);
+    }
+    /** Get the current global typo style. 获取当前全局排版风格。 */
+    getTypo() {
+        return getAitheTypo();
+    }
+    /** Get the list of all built-in typo style names. 获取所有内置排版风格名称列表。 */
+    getTypos() {
+        return getAitheTypos();
+    }
+    /** Get the CSS variable token map for a given typo style. 获取指定排版风格的 CSS 变量 token 映射。 */
+    getTypoTokens(typo) {
+        return getTypoTokens(typo);
+    }
+    /** Subscribe to typo style changes. Returns an unsubscribe function. 订阅排版风格变更，返回取消订阅函数。 */
+    onTypoChange(fn) {
+        return onAitheTypoChange(fn);
+    }
+    /** Set the global locale and optionally persist to localStorage. 设置全局语言，可选持久化到 localStorage。 */
+    setLocale(locale, persist = true) {
+        setAitheLocale(locale, persist);
+    }
+    /** Get the current global locale. 获取当前全局语言。 */
+    getLocale() {
+        return getAitheLocale();
+    }
+    /** Get the list of all registered locale identifiers. 获取所有已注册的语言标识列表。 */
+    getLocales() {
+        return getAitheLocales();
+    }
+    /** Subscribe to locale changes. Returns an unsubscribe function. 订阅语言变更，返回取消订阅函数。 */
+    onLocaleChange(fn) {
+        return onAitheLocaleChange(fn);
+    }
+    /** Merge additional translations into an existing locale. 合并追加翻译条目到已有语言。 */
+    registerLocale(locale, translations) {
+        registerAitheTranslations(locale, translations);
+    }
+    /** Translate a key using the current locale. 使用当前语言翻译指定键。 */
+    t(key, dft, params) {
+        return translate(key, dft, params);
+    }
+    /** Whether the UA indicates a mobile device (Android/iOS/WebOS/Blackberry). UA 是否指示移动设备。 */
+    get isMobile() {
+        return /android|iphone|ipod|ipad|webos|blackberry/i.test(this._ua);
+    }
+    /** Whether the UA indicates Android. UA 是否指示 Android。 */
+    get isAndroid() { return /android/i.test(this._ua); }
+    /** Whether the UA indicates iOS. UA 是否指示 iOS。 */
+    get isIOS() { return /iphone|ipad|ipod/i.test(this._ua); }
+    /** Whether the UA indicates Chrome (not Edge). UA 是否指示 Chrome（非 Edge）。 */
+    get isChrome() { return /chrome/i.test(this._ua) && !this.isEdge; }
+    /** Whether the UA indicates Edge. UA 是否指示 Edge。 */
+    get isEdge() { return /edg|edge/i.test(this._ua); }
+    /** Whether the UA indicates WeChat built-in browser. UA 是否指示微信内置浏览器。 */
+    get isWechat() { return /micromessenger/i.test(this._ua); }
+    /** Whether the UA indicates Windows. UA 是否指示 Windows。 */
+    get isWindows() { return /windows/i.test(this._ua); }
+    /** Whether the UA indicates macOS. UA 是否指示 macOS。 */
+    get isMacOS() { return /mac os x/i.test(this._ua); }
+    /** Whether the device is truly mobile (UA + touch + small screen + not desktop OS). 是否为真实移动设备。 */
+    get isRealMobile() {
+        const isUAMobile = this.isMobile;
+        const hasTouch = 'ontouchstart' in globalThis.window || navigator.maxTouchPoints > 0;
+        const isSmallScreen = window.innerWidth < 768;
+        const isNotDesktop = !this.isWindows && !this.isMacOS;
+        return isUAMobile && hasTouch && isSmallScreen && isNotDesktop;
+    }
+    /** Whether Chrome DevTools device emulation is active. Chrome 开发者工具设备模拟是否激活。 */
+    get isChromeEmulator() {
+        return ((this.isChrome && this.isMobile && globalThis.window.__CHROME_DEVICE_EMULATION__) ||
+            (globalThis.navigator.maxTouchPoints === 1 && globalThis.window.innerWidth > 500));
+    }
+    /** Whether the device supports touch events. 设备是否支持触摸事件。 */
+    get supportsTouch() {
+        return 'ontouchstart' in globalThis.window || navigator.maxTouchPoints > 0;
+    }
+}
+/** Default singleton instance of AitheUI. AitheUI 的默认单例实例。 */
+export const aitheUI = new AitheUI();

package/dist/styles/global.css.d.ts

@@ -1,3 +1,5 @@
-export declare const aitheGlobalCssText = "\n:root {\n  --aithe-space-0: 0;\n  --aithe-space-1: 4px;\n  --aithe-space-2: 8px;\n  --aithe-space-3: 12px;\n  --aithe-space-4: 16px;\n  --aithe-space-5: 20px;\n  --aithe-space-6: 24px;\n  --aithe-space-7: 32px;\n  --aithe-space-8: 40px;\n  --aithe-space-9: 48px;\n  --aithe-space-10: 64px;\n  --aithe-space-xs: var(--aithe-space-2);\n  --aithe-space-sm: var(--aithe-space-3);\n  --aithe-space-md: var(--aithe-space-4);\n  --aithe-space-lg: var(--aithe-space-6);\n  --aithe-space-xl: var(--aithe-space-8);\n  --aithe-radius-sm: 6px;\n  --aithe-radius-md: 10px;\n  --aithe-radius-lg: 14px;\n  --aithe-radius-xl: 20px;\n  --aithe-radius-full: 999px;\n  --aithe-shadow-1: 0 6px 18px rgba(18, 24, 38, 0.06);\n  --aithe-shadow-2: 0 12px 28px rgba(18, 24, 38, 0.08);\n  --aithe-shadow-3: 0 18px 40px rgba(18, 24, 38, 0.1);\n  --aithe-shadow-4: 0 22px 56px rgba(18, 24, 38, 0.14);\n  --aithe-shadow-5: 0 28px 72px rgba(18, 24, 38, 0.18);\n  --aithe-font-family: 'Sora', 'IBM Plex Sans', 'PingFang SC', 'Microsoft YaHei', sans-serif;\n  --aithe-font-family-mono: 'JetBrains Mono', 'SFMono-Regular', 'Consolas', monospace;\n  --aithe-font-size-xs: 12px;\n  --aithe-font-size-sm: 13px;\n  --aithe-font-size-md: 14px;\n  --aithe-font-size-lg: 16px;\n  --aithe-font-size-xl: 20px;\n  --aithe-font-size-2xl: 28px;\n  --aithe-font-weight-regular: 400;\n  --aithe-font-weight-medium: 500;\n  --aithe-font-weight-semibold: 600;\n  --aithe-font-weight-bold: 700;\n  --aithe-line-height-tight: 1.2;\n  --aithe-line-height-base: 1.5;\n  --aithe-line-height-loose: 1.7;\n  --aithe-z-base: 1;\n  --aithe-z-dropdown: 1000;\n  --aithe-z-popover: 1010;\n  --aithe-z-modal: 1080;\n  --aithe-z-drawer: 1090;\n  --aithe-z-tooltip: 1120;\n  --aithe-duration-fast: 140ms;\n  --aithe-duration-base: 220ms;\n  --aithe-duration-slow: 320ms;\n  --aithe-ease-standard: cubic-bezier(0.2, 0.8, 0.2, 1);\n  --aithe-control-height-sm: 32px;\n  --aithe-control-height-md: 40px;\n  --aithe-control-height-lg: 48px;\n}\n\nhtml,\nbody {\n  margin: 0;\n  width: 100%;\n  min-height: 100%;\n  background: var(--aithe-color-bg-subtle);\n  color: var(--aithe-color-text);\n  font-family: var(--aithe-font-family);\n}\n\n*,\n*::before,\n*::after {\n  box-sizing: border-box;\n}\n\n::selection {\n  background: var(--aithe-color-selection);\n}\n";
+/** Global CSS text for `:root` primitive tokens plus base html/body/selection resets. 用于 `:root` 基础令牌及 html/body/选区重置的全局 CSS 文本。 */
+export declare const aitheGlobalCssText = "\n:root {\n  --aithe-space-0: 0;\n  --aithe-space-1: 4px;\n  --aithe-space-2: 8px;\n  --aithe-space-3: 12px;\n  --aithe-space-4: 16px;\n  --aithe-space-5: 20px;\n  --aithe-space-6: 24px;\n  --aithe-space-7: 32px;\n  --aithe-space-8: 40px;\n  --aithe-space-9: 48px;\n  --aithe-space-10: 64px;\n  --aithe-space-xs: var(--aithe-space-2);\n  --aithe-space-sm: var(--aithe-space-3);\n  --aithe-space-md: var(--aithe-space-4);\n  --aithe-space-lg: var(--aithe-space-6);\n  --aithe-space-xl: var(--aithe-space-8);\n  --aithe-radius-sm: 6px;\n  --aithe-radius-md: 10px;\n  --aithe-radius-lg: 14px;\n  --aithe-radius-xl: 20px;\n  --aithe-radius-full: 999px;\n  --aithe-container-radius-sm: 6px;\n  --aithe-container-radius-md: 10px;\n  --aithe-container-radius-lg: 14px;\n  --aithe-container-radius-xl: 20px;\n  --aithe-container-radius-full: 999px;\n  --aithe-shadow-1: 0 2px 4px rgba(18, 24, 38, 0.1), 0 4px 8px rgba(18, 24, 38, 0.06);\n  --aithe-shadow-2: 0 4px 8px rgba(18, 24, 38, 0.12), 0 8px 16px rgba(18, 24, 38, 0.08);\n  --aithe-shadow-3: 0 6px 12px rgba(18, 24, 38, 0.14), 0 12px 24px rgba(18, 24, 38, 0.1);\n  --aithe-shadow-4: 0 8px 16px rgba(18, 24, 38, 0.16), 0 16px 32px rgba(18, 24, 38, 0.12);\n  --aithe-shadow-5: 0 12px 20px rgba(18, 24, 38, 0.18), 0 20px 40px rgba(18, 24, 38, 0.14);\n  --aithe-shadow-glow: none;\n  --aithe-shadow-inner: inset 0 1px 0 rgba(255, 255, 255, 0.15);\n  --aithe-shadow-blur: 0px;\n  --aithe-shadow-opacity: 1;\n  --aithe-shadow-border-glow: 0px;\n  --aithe-font-family: 'Sora', 'IBM Plex Sans', 'PingFang SC', 'Microsoft YaHei', sans-serif;\n  --aithe-font-family-mono: 'JetBrains Mono', 'SFMono-Regular', 'Consolas', monospace;\n  --aithe-font-size-xs: 12px;\n  --aithe-font-size-sm: 13px;\n  --aithe-font-size-md: 14px;\n  --aithe-font-size-lg: 16px;\n  --aithe-font-size-xl: 20px;\n  --aithe-font-size-2xl: 28px;\n  --aithe-font-size-base: 14px;\n  --aithe-font-size-3xl: 32px;\n  --aithe-font-size-4xl: 48px;\n  --aithe-font-size-5xl: 64px;\n  --aithe-font-weight-regular: 400;\n  --aithe-font-weight-medium: 500;\n  --aithe-font-weight-semibold: 600;\n  --aithe-font-weight-bold: 700;\n  --aithe-line-height-tight: 1.2;\n  --aithe-line-height-base: 1.5;\n  --aithe-line-height-loose: 1.7;\n  --aithe-z-base: 1;\n  --aithe-z-dropdown: 1000;\n  --aithe-z-popover: 1010;\n  --aithe-z-modal: 1080;\n  --aithe-z-drawer: 1090;\n  --aithe-z-tooltip: 1120;\n  --aithe-duration-fast: 140ms;\n  --aithe-duration-base: 220ms;\n  --aithe-duration-slow: 320ms;\n  --aithe-ease-standard: cubic-bezier(0.2, 0.8, 0.2, 1);\n  --aithe-control-height-sm: 32px;\n  --aithe-control-height-md: 40px;\n  --aithe-control-height-lg: 48px;\n}\n\nhtml,\nbody {\n  margin: 0;\n  width: 100%;\n  min-height: 100%;\n  background: var(--aithe-color-bg-subtle);\n  color: var(--aithe-color-text);\n  font-family: var(--aithe-font-family);\n}\n\n*,\n*::before,\n*::after {\n  box-sizing: border-box;\n}\n\n::selection {\n  background: var(--aithe-color-selection);\n}\n";
+/** Shadow-DOM reset styles applied to every Aithe component host. 应用到每个 Aithe 组件宿主的 Shadow-DOM 重置样式。 */
 export declare const aitheGlobalResetStyles: import("lit").CSSResult;
 //# sourceMappingURL=global.css.d.ts.map

package/dist/styles/global.css.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"global.css.d.ts","sourceRoot":"","sources":["../../src/styles/global.css.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,kBAAkB,+vEA6E9B,CAAC;AAEF,eAAO,MAAM,sBAAsB,yBAuBlC,CAAC"}
+{"version":3,"file":"global.css.d.ts","sourceRoot":"","sources":["../../src/styles/global.css.ts"],"names":[],"mappings":"AAEA,oIAAoI;AACpI,eAAO,MAAM,kBAAkB,06FA2F9B,CAAC;AAEF,wGAAwG;AACxG,eAAO,MAAM,sBAAsB,yBAuBlC,CAAC"}

package/dist/styles/global.css.js

@@ -0,0 +1,119 @@
+import { css } from 'lit';
+/** Global CSS text for `:root` primitive tokens plus base html/body/selection resets. 用于 `:root` 基础令牌及 html/body/选区重置的全局 CSS 文本。 */
+export const aitheGlobalCssText = `
+:root {
+  --aithe-space-0: 0;
+  --aithe-space-1: 4px;
+  --aithe-space-2: 8px;
+  --aithe-space-3: 12px;
+  --aithe-space-4: 16px;
+  --aithe-space-5: 20px;
+  --aithe-space-6: 24px;
+  --aithe-space-7: 32px;
+  --aithe-space-8: 40px;
+  --aithe-space-9: 48px;
+  --aithe-space-10: 64px;
+  --aithe-space-xs: var(--aithe-space-2);
+  --aithe-space-sm: var(--aithe-space-3);
+  --aithe-space-md: var(--aithe-space-4);
+  --aithe-space-lg: var(--aithe-space-6);
+  --aithe-space-xl: var(--aithe-space-8);
+  --aithe-radius-sm: 6px;
+  --aithe-radius-md: 10px;
+  --aithe-radius-lg: 14px;
+  --aithe-radius-xl: 20px;
+  --aithe-radius-full: 999px;
+  --aithe-container-radius-sm: 6px;
+  --aithe-container-radius-md: 10px;
+  --aithe-container-radius-lg: 14px;
+  --aithe-container-radius-xl: 20px;
+  --aithe-container-radius-full: 999px;
+  --aithe-shadow-1: 0 2px 4px rgba(18, 24, 38, 0.1), 0 4px 8px rgba(18, 24, 38, 0.06);
+  --aithe-shadow-2: 0 4px 8px rgba(18, 24, 38, 0.12), 0 8px 16px rgba(18, 24, 38, 0.08);
+  --aithe-shadow-3: 0 6px 12px rgba(18, 24, 38, 0.14), 0 12px 24px rgba(18, 24, 38, 0.1);
+  --aithe-shadow-4: 0 8px 16px rgba(18, 24, 38, 0.16), 0 16px 32px rgba(18, 24, 38, 0.12);
+  --aithe-shadow-5: 0 12px 20px rgba(18, 24, 38, 0.18), 0 20px 40px rgba(18, 24, 38, 0.14);
+  --aithe-shadow-glow: none;
+  --aithe-shadow-inner: inset 0 1px 0 rgba(255, 255, 255, 0.15);
+  --aithe-shadow-blur: 0px;
+  --aithe-shadow-opacity: 1;
+  --aithe-shadow-border-glow: 0px;
+  --aithe-font-family: 'Sora', 'IBM Plex Sans', 'PingFang SC', 'Microsoft YaHei', sans-serif;
+  --aithe-font-family-mono: 'JetBrains Mono', 'SFMono-Regular', 'Consolas', monospace;
+  --aithe-font-size-xs: 12px;
+  --aithe-font-size-sm: 13px;
+  --aithe-font-size-md: 14px;
+  --aithe-font-size-lg: 16px;
+  --aithe-font-size-xl: 20px;
+  --aithe-font-size-2xl: 28px;
+  --aithe-font-size-base: 14px;
+  --aithe-font-size-3xl: 32px;
+  --aithe-font-size-4xl: 48px;
+  --aithe-font-size-5xl: 64px;
+  --aithe-font-weight-regular: 400;
+  --aithe-font-weight-medium: 500;
+  --aithe-font-weight-semibold: 600;
+  --aithe-font-weight-bold: 700;
+  --aithe-line-height-tight: 1.2;
+  --aithe-line-height-base: 1.5;
+  --aithe-line-height-loose: 1.7;
+  --aithe-z-base: 1;
+  --aithe-z-dropdown: 1000;
+  --aithe-z-popover: 1010;
+  --aithe-z-modal: 1080;
+  --aithe-z-drawer: 1090;
+  --aithe-z-tooltip: 1120;
+  --aithe-duration-fast: 140ms;
+  --aithe-duration-base: 220ms;
+  --aithe-duration-slow: 320ms;
+  --aithe-ease-standard: cubic-bezier(0.2, 0.8, 0.2, 1);
+  --aithe-control-height-sm: 32px;
+  --aithe-control-height-md: 40px;
+  --aithe-control-height-lg: 48px;
+}
+
+html,
+body {
+  margin: 0;
+  width: 100%;
+  min-height: 100%;
+  background: var(--aithe-color-bg-subtle);
+  color: var(--aithe-color-text);
+  font-family: var(--aithe-font-family);
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+::selection {
+  background: var(--aithe-color-selection);
+}
+`;
+/** Shadow-DOM reset styles applied to every Aithe component host. 应用到每个 Aithe 组件宿主的 Shadow-DOM 重置样式。 */
+export const aitheGlobalResetStyles = css `
+  :host {
+    box-sizing: border-box;
+    color: var(--aithe-color-text);
+    font-family: var(--aithe-font-family);
+    font-size: var(--aithe-font-size-md);
+    line-height: var(--aithe-line-height-base);
+  }
+
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  [hidden] {
+    display: none !important;
+  }
+
+  :focus-visible {
+    outline: 2px solid var(--aithe-color-focus-ring);
+    outline-offset: 2px;
+  }
+`;

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

@@ -0,0 +1,66 @@
+export { en } from './locales/en-US';
+export { zh } from './locales/zh-CN';
+export { zhTw } from './locales/zh-TW';
+export { zhHk } from './locales/zh-HK';
+export { ja } from './locales/ja-JP';
+export { ko } from './locales/ko-KR';
+export { es } from './locales/es-ES';
+export { ptBr } from './locales/pt-BR';
+export { fr } from './locales/fr-FR';
+export { de } from './locales/de-DE';
+import type { AitheTreeNodeMeta } from '../../core/types';
+/** 内置 BCP 47 locale 标识 / Built-in BCP 47 locale identifiers */
+export type AitheBuiltinLocale = 'en-US' | 'zh-CN' | 'zh-TW' | 'zh-HK' | 'ja-JP' | 'ko-KR' | 'es-ES' | 'pt-BR' | 'fr-FR' | 'de-DE';
+export declare const AITHE_DEFAULT_LOCALE: AitheBuiltinLocale;
+/**
+ * Static tree menu data for locale selection, compatible with `<aithe-tree-menu>`.
+ * 用于语言选择的静态树形菜单数据，兼容 `<aithe-tree-menu>`。
+ * Each item carries a `label` extension field with the i18n key for display name.
+ * 每个项携带 `label` 扩展字段，包含显示名称的 i18n 键。
+ */
+export declare const localeMenu: AitheTreeNodeMeta[];
+/** BCP 47 locale 标识，支持扩展 / BCP 47 locale identifier, extensible */
+declare const AITHE_CUSTOM_LOCALE: unique symbol;
+export type AitheLocale = AitheBuiltinLocale | (string & {
+    readonly [AITHE_CUSTOM_LOCALE]?: never;
+});
+/**
+ * 注册完整 locale 翻译映射（替换已有）/ Register full locale translations (replaces existing).
+ * 适用于核心库初始化 / Used for core library initialization.
+ */
+export declare function registerAitheLocale(locale: AitheLocale, translations: Record<string, string>): void;
+/**
+ * 合并追加翻译条目到已有 locale / Merge additional translations into existing locale.
+ * 适用于应用层注册自定义翻译 / Used by apps to register custom translations.
+ */
+export declare function registerAitheTranslations(locale: AitheLocale, translations: Record<string, string>): void;
+/** 设置当前 locale 并通知监听器 / Set current locale and notify listeners */
+export declare function setAitheLocale(locale: AitheLocale, persist?: boolean): void;
+/** 获取当前 locale / Get current locale */
+export declare function getAitheLocale(): AitheLocale;
+/** 获取所有已注册的 locale 列表 / Get all registered locale identifiers */
+export declare function getAitheLocales(): AitheLocale[];
+/**
+ * 初始化 locale（从 localStorage 恢复或使用默认值）
+ * Initialize locale from localStorage or fall back to defaultLocale.
+ */
+export declare function initAitheLocale(defaultLocale?: AitheLocale): void;
+export declare function t(key: string, dft?: string, params?: Record<string, string | number>): string;
+/**
+ * 翻译 AitheTreeNodeMeta 的 label 字段。
+ * Translate the label of an AitheTreeNodeMeta node.
+ * 如果节点的 i18n 字段有效（非空字符串），则使用 t(i18n, label) 翻译，label 作为缺省值；
+ * 否则 t('', label) 直接返回 label。
+ * If the node's i18n field is valid (non-empty string), translates via t(i18n, label) with label as default;
+ * otherwise t('', label) returns label directly.
+ */
+export declare function translateNodeLabel(node: {
+    label: string;
+    i18n?: unknown;
+}): string;
+/**
+ * 订阅 locale 变更事件 / Subscribe to locale changes.
+ * 返回取消订阅函数 / Returns unsubscribe function.
+ */
+export declare function onAitheLocaleChange(fn: () => void): () => void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/styles/i18n/index.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AACrC,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AACrC,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AACrC,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AACrC,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAC;AAErC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,GACP,OAAO,CAAC;AAEZ,eAAO,MAAM,oBAAoB,EAAE,kBAA4B,CAAC;AAgBhE;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,iBAAiB,EAIvC,CAAC;AAEJ,mEAAmE;AACnE,OAAO,CAAC,MAAM,mBAAmB,EAAE,OAAO,MAAM,CAAC;AACjD,MAAM,MAAM,WAAW,GACnB,kBAAkB,GAClB,CAAC,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,mBAAmB,CAAC,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAsC1D;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,IAAI,CAEN;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,WAAW,EACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,IAAI,CAGN;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,UAAO,GAAG,IAAI,CAQxE;AAED,uCAAuC;AACvC,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED,iEAAiE;AACjE,wBAAgB,eAAe,IAAI,WAAW,EAAE,CAE/C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,aAAa,GAAE,WAAkC,GAAG,IAAI,CAcvF;AAgCD,wBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAO7F;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAGlF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG9D"}