@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/filter.md

@@ -0,0 +1,332 @@
+# Filter 数据格式化 / Data Formatting with Filters
+
+> Aithe UI 内置轻量 Filter 数据格式化框架，支持声明式过滤器表达式，零第三方依赖。
+> Aithe UI provides a lightweight filter-based data formatting framework with declarative filter expressions and zero third-party dependencies.
+
+---
+
+## 概述 / Overview
+
+Filter 模块提供了一套统一的**数据格式化方案**，通过声明式的过滤器表达式对数据进行格式化处理。核心特性：
+
+- **声明式表达式**：如 `"amount"`、`"date yyyy/MM/dd"`、`"date yyyy/MM/dd | empty"`
+- **链式处理**：多个过滤器通过 `|` 串联，前一个输出作为后一个输入
+- **内置过滤器**：金额、日期、空值替换、字节数、时间友好显示
+- **可扩展**：通过 `FilterFactory.register()` 注册自定义过滤器
+- **组件集成**：`<aithe-metrics>` 和 `<aithe-table-column>` 原生支持 `filter` 属性
+
+---
+
+## 快速开始 / Quick Start
+
+```ts
+import { filterFactory } from '@aithe/aithe-ui';
+
+// 单个过滤器
+filterFactory.format(123.456, 'amount');        // "123.46"
+
+// 带参数的过滤器
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd');  // "2024/01/15"
+
+// 链式过滤
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd | empty');  // "2024/01/15"
+filterFactory.format(null, 'date yyyy/MM/dd | empty');          // "--"
+```
+
+---
+
+## 内置过滤器 / Built-in Filters
+
+### amount — 金额格式化
+
+保留两位小数，非数字返回 `--`。
+
+| 输入 | 输出 |
+|------|------|
+| `123.4` | `123.40` |
+| `"100"` | `100.00` |
+| `null` | `--` |
+| `"abc"` | `--` |
+
+```ts
+filterFactory.format(123.4, 'amount');  // "123.40"
+```
+
+### date — 日期格式化
+
+支持 `Date` 对象、时间戳（毫秒）、日期字符串。默认格式 `yyyy-MM-dd HH:mm:ss`，支持自定义格式。
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `format` | 日期格式字符串 | `yyyy-MM-dd HH:mm:ss` |
+
+**格式占位符**：
+
+| 占位符 | 含义 | 示例 |
+|--------|------|------|
+| `yyyy` | 四位年份 | 2024 |
+| `MM` | 两位月份 | 01 |
+| `dd` | 两位日期 | 15 |
+| `HH` | 两位小时 | 09 |
+| `mm` | 两位分钟 | 05 |
+| `ss` | 两位秒数 | 30 |
+
+```ts
+filterFactory.format(new Date('2024-01-15'), 'date');               // "2024-01-15 08:00:00"
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd');              // "2024/01/15"
+filterFactory.format(1705305600000, 'date yyyy-MM-dd');             // "2024-01-15"
+filterFactory.format(null, 'date yyyy/MM/dd');                      // "--"
+```
+
+### empty — 空值替换
+
+将 `null`、`undefined`、空字符串、`NaN` 替换为指定文本。
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `placeholder` | 替换文本 | `--` |
+
+```ts
+filterFactory.format(null, 'empty');          // "--"
+filterFactory.format(undefined, 'empty');      // "--"
+filterFactory.format('', 'empty');             // "--"
+filterFactory.format('hello', 'empty');        // "hello"
+filterFactory.format(null, 'empty N/A');       // "N/A"
+```
+
+### bytes — 字节数格式化
+
+将字节数转换为可读的大小字符串，支持 IEC（1024 进制）和 SI（1000 进制）两种标准。
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `base` | 进制标准：`1024`（IEC）或 `1000`（SI） | `1024` |
+
+**IEC 标准（默认）**：
+
+| 输入 | 输出 |
+|------|------|
+| `500` | `500 B` |
+| `1024` | `1.00 KiB` |
+| `1536` | `1.50 KiB` |
+| `1048576` | `1.00 MiB` |
+| `1073741824` | `1.00 GiB` |
+
+**SI 标准**：
+
+| 输入 | 输出 |
+|------|------|
+| `1000` | `1.00 KB` |
+| `1000000` | `1.00 MB` |
+
+```ts
+filterFactory.format(1024, 'bytes');              // "1.00 KiB"
+filterFactory.format(1000, 'bytes 1000');          // "1.00 KB"
+filterFactory.format(1536, 'bytes');               // "1.50 KiB"
+filterFactory.format(1048576, 'bytes 1024');       // "1.00 MiB"
+```
+
+### timeAgo — 时间友好显示
+
+根据输入时间与当前时间的差值，按规则输出友好文案。超过 1 年显示 `yyyy-MM-dd` 格式日期。
+
+| 时间差 | 输出示例 |
+|--------|----------|
+| < 1 分钟 | `just now` |
+| < 1 小时 | `5 minutes ago` / `in 5 minutes` |
+| < 1 天 | `3 hours ago` / `in 3 hours` |
+| < 1 月 | `2 days ago` / `in 2 days` |
+| < 1 年 | `1 month ago` / `in 1 month` |
+| >= 1 年 | `2025-03-15` |
+
+> 文案通过国际化系统 `t()` 实现，支持 `zh-CN` / `en-US` 切换。
+
+```ts
+filterFactory.format(Date.now() - 300000, 'timeAgo');   // "5 minutes ago"
+filterFactory.format(Date.now() + 600000, 'timeAgo');   // "in 10 minutes"
+filterFactory.format('2025-03-15', 'timeAgo');           // "2025-03-15"
+```
+
+---
+
+## 过滤器表达式语法 / Filter Expression Syntax
+
+过滤器表达式支持以下格式：
+
+| 格式 | 说明 | 示例 |
+|------|------|------|
+| `name` | 仅过滤器名 | `"amount"` |
+| `name arg1 arg2` | 过滤器名 + 参数 | `"date yyyy/MM/dd"` |
+| `name1 \| name2` | 链式过滤 | `"date yyyy/MM/dd \| empty"` |
+
+### 链式过滤规则
+
+多个过滤器通过 `|` 分隔，从左到右依次执行，前一个过滤器的输出作为后一个过滤器的输入。
+
+```ts
+// 先格式化日期，再对空值做兜底
+filterFactory.format(null, 'date yyyy/MM/dd | empty');  // "--"
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd | empty');  // "2024/01/15"
+```
+
+---
+
+## 在组件中使用 / Usage in Components
+
+### `<aithe-metrics>`
+
+通过 `filter` 属性或 `data.filter` / `params.filter` 设置过滤器表达式：
+
+```html
+<!-- 属性模式 -->
+<aithe-metrics label="Revenue" value="1234.5" filter="amount"></aithe-metrics>
+
+<!-- 数据驱动模式 -->
+<aithe-metrics data='{"label":"Revenue","value":"1234.5","filter":"amount"}'></aithe-metrics>
+```
+
+优先级：`data.filter` > `params.filter` > 无过滤。
+
+### `<aithe-table-column>`
+
+通过 `filter` 属性设置过滤器表达式，对列单元格值进行格式化：
+
+```html
+<aithe-table .data=${records}>
+  <aithe-table-column id="price" title="Price" filter="amount"></aithe-table-column>
+  <aithe-table-column id="createdAt" title="Created" filter="date yyyy/MM/dd"></aithe-table-column>
+  <aithe-table-column id="size" title="Size" filter="bytes"></aithe-table-column>
+</aithe-table>
+```
+
+优先级：`cellRenderer` > `filter` > 原始值。
+
+### 数据驱动模式（`AitheTableColumnMeta`）
+
+```ts
+const columns = [
+  { id: 'price', title: 'Price', filter: 'amount' },
+  { id: 'createdAt', title: 'Created', filter: 'date yyyy/MM/dd' },
+  { id: 'size', title: 'Size', filter: 'bytes' },
+];
+```
+
+---
+
+## 编程式使用 / Programmatic Usage
+
+### 直接格式化
+
+```ts
+import { filterFactory } from '@aithe/aithe-ui';
+
+filterFactory.format(123.456, 'amount');               // "123.46"
+filterFactory.format('2024-01-15', 'date yyyy/MM/dd'); // "2024/01/15"
+filterFactory.format(1024, 'bytes');                   // "1.00 KiB"
+```
+
+### 获取过滤器实例
+
+```ts
+const amountFilter = filterFactory.get('amount');
+amountFilter?.apply(123.456);  // "123.46"
+```
+
+### 解析表达式
+
+```ts
+filterFactory.parse('date yyyy/MM/dd | empty');
+// [
+//   { name: 'date', args: ['yyyy/MM/dd'] },
+//   { name: 'empty', args: [] },
+// ]
+```
+
+### 序列化表达式
+
+```ts
+filterFactory.stringify([
+  { name: 'date', args: ['yyyy/MM/dd'] },
+  { name: 'empty', args: [] },
+]);
+// "date yyyy/MM/dd | empty"
+```
+
+---
+
+## 自定义过滤器 / Custom Filters
+
+### 实现 Filter 接口
+
+所有过滤器需实现 `Filter<T, R>` 接口：
+
+```ts
+import type { Filter } from '@aithe/aithe-ui';
+import { filterFactory } from '@aithe/aithe-ui';
+
+// 实现接口（无状态，参数通过 apply 变参传入）
+class PhoneFilter implements Filter<string, string> {
+  apply(value: string): string {
+    if (value == null || value.length !== 11) return value;
+    return `${value.slice(0, 3)}****${value.slice(7)}`;
+  }
+}
+
+// 注册
+filterFactory.register('phone', PhoneFilter);
+
+// 使用
+filterFactory.format('13812345678', 'phone');  // "138****5678"
+```
+
+### 设计约束
+
+- **无状态**：过滤器实例不持有状态，所有参数通过 `apply(value, ...args)` 传入
+- **单例复用**：注册时实例化一次并缓存，后续复用同一实例
+- **参数传递**：表达式中的参数通过 `apply` 的变参传入
+
+---
+
+## 类型定义 / Type Definitions
+
+```ts
+/** 过滤器接口 */
+interface Filter<T = unknown, R = unknown> {
+  apply(value: T, ...args: string[]): R;
+}
+
+/** 过滤器表达式解析结果 */
+interface FilterExpression {
+  name: string;
+  args: string[];
+}
+
+/** 过滤器链配置 */
+type FilterConfig = string | FilterExpression;
+```
+
+---
+
+## API 参考 / API Reference
+
+### FilterFactory
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `register` | `(name: string, ctor: new () => Filter): void` | 注册过滤器 |
+| `get` | `(name: string): Filter \| null` | 获取过滤器实例 |
+| `has` | `(name: string): boolean` | 检查过滤器是否已注册 |
+| `names` | `(): string[]` | 获取所有已注册的过滤器名称 |
+| `format` | `(value: T, config: FilterConfig): unknown` | 使用表达式直接格式化值 |
+| `parse` | `(config: FilterConfig): FilterExpression[]` | 解析过滤器表达式 |
+| `stringify` | `(expressions: FilterExpression[]): string` | 序列化表达式列表 |
+
+### 内置过滤器
+
+| 注册名 | 类 | 说明 |
+|--------|-----|------|
+| `amount` | `AmountFilter` | 金额保留两位小数 |
+| `date` | `DateFilter` | 日期格式化 |
+| `empty` | `EmptyFilter` | 空值替换 |
+| `bytes` | `BytesFilter` | 字节数格式化 |
+| `timeAgo` | `TimeAgoFilter` | 时间友好显示 |

package/docs/framework-integration.md

@@ -30,8 +30,8 @@ Web Components 是浏览器原生标准，不依赖任何框架。Aithe UI 组
 ### 基本使用
 
 ```tsx
-import 'aithe-ui';
-import { setAitheTheme } from 'aithe-ui';
+import '@aithe/aithe-ui';
+import { aitheUI } from '@aithe/aithe-ui';
 
 function App() {
   return (
@@ -84,7 +84,24 @@ function ThemeExample() {
     return () => el.removeEventListener('aithe-theme-change', handler);
   }, []);
 
-  return <aithe-theme-picker ref={pickerRef}></aithe-theme-picker>;
+  return <aithe-theme-switch></aithe-theme-switch>;
+}
+
+// Or use the individual theme picker / 或使用独立的主题选择器
+function ThemePickerReact() {
+  const pickerRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    const el = pickerRef.current;
+    if (!el) return;
+    const handler = (e: Event) => {
+      console.log('Theme changed:', (e as CustomEvent).detail.theme);
+    };
+    el.addEventListener('aithe-theme-change', handler);
+    return () => el.removeEventListener('aithe-theme-change', handler);
+  }, []);
+
+  return <aithe-theme-switch ref={pickerRef}></aithe-theme-switch>;
 }
 ```
 
@@ -94,7 +111,7 @@ function ThemeExample() {
 
 ```tsx
 // AitheButtonReact.tsx
-import 'aithe-ui';
+import '@aithe/aithe-ui';
 
 interface AitheButtonProps {
   type?: 'primary' | 'default' | 'dashed' | 'text' | 'link';
@@ -157,7 +174,7 @@ Vue 3 对 Web Components 有良好的原生支持：
 </template>
 
 <script setup>
-import 'aithe-ui';
+import '@aithe/aithe-ui';
 
 function handleClick() {
   console.log('clicked');
@@ -199,7 +216,7 @@ Vue 3 使用 `v-bind` 的 `.prop` 修饰符或 `:` 前缀传递 DOM 属性：
 
 <script setup>
 import { ref } from 'vue';
-import 'aithe-ui';
+import '@aithe/aithe-ui';
 
 const options = ref([
   { label: 'Option A', id: 'a' },
@@ -223,7 +240,7 @@ function handleChange(e) {
 
 <script setup>
 import { ref } from 'vue';
-import 'aithe-ui';
+import '@aithe/aithe-ui';
 
 const inputValue = ref('');
 
@@ -243,7 +260,7 @@ function handleInput(e) {
 
 ```ts
 // 在 main.ts 或组件中
-import 'aithe-ui';
+import '@aithe/aithe-ui';
 ```
 
 ### 配置自定义元素
@@ -288,12 +305,16 @@ export class ExampleComponent {
 使用 `@HostListener` 或 `(event)` 绑定：
 
 ```html
+<!-- Using unified theme switch / 使用统一外观切换器 -->
+<aithe-theme-switch (aithe-theme-change)="onThemeChange($event)"></aithe-theme-switch>
+
+<!-- Using individual theme picker / 使用独立主题选择器（已废弃，推荐 theme-switch） -->
 <aithe-theme-picker (aithe-theme-change)="onThemeChange($event)"></aithe-theme-picker>
 ```
 
 ```ts
 onThemeChange(event: CustomEvent) {
-  console.log('Theme:', event.detail.theme);
+  console.log('Category:', event.detail.category, 'Value:', event.detail.value);
 }
 ```
 
@@ -307,7 +328,7 @@ Svelte 对 Web Components 支持良好：
 
 ```svelte
 <script>
-import 'aithe-ui';
+import '@aithe/aithe-ui';
 </script>
 
 <aithe-button type="primary" on:aithe-click={handleClick}>
@@ -321,7 +342,7 @@ Svelte 使用 `propname={value}` 语法传递属性：
 
 ```svelte
 <script>
-import 'aithe-ui';
+import '@aithe/aithe-ui';
 
 const options = [
   { label: 'Option A', id: 'a' },
@@ -336,7 +357,7 @@ const options = [
 
 ```svelte
 <script>
-import 'aithe-ui';
+import '@aithe/aithe-ui';
 
 function handleChange(e) {
   console.log('Selected:', e.detail);
@@ -360,10 +381,10 @@ function handleChange(e) {
 <html>
   <head>
     <script type="module">
-      import 'aithe-ui';
-      import { setAitheTheme, setAitheLocale } from 'aithe-ui';
+      import '@aithe/aithe-ui';
+      import { aitheUI, setAitheLocale } from '@aithe/aithe-ui';
 
-      setAitheTheme('light');
+      aitheUI.setTheme('light');
       setAitheLocale('en-US');
     </script>
   </head>
@@ -396,18 +417,145 @@ select.addEventListener('aithe-change', (e) => {
 
 ---
 
+## 路由集成
+
+Aithe UI 提供轻量路由模块 `Router` 和路由容器 `<aithe-page>`，可在各框架中使用。
+
+### React
+
+```tsx
+import { Router } from '@aithe/aithe-ui';
+
+const router = new Router({
+  mode: 'history',
+  routes: [
+    { path: '/', component: 'home-page' },
+    { path: '/user/:id', component: 'user-page' },
+  ],
+});
+
+function App() {
+  const pageRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    router.start();
+    if (pageRef.current) {
+      pageRef.current.router = router;
+    }
+    return () => router.stop();
+  }, []);
+
+  return <aithe-page ref={pageRef}></aithe-page>;
+}
+```
+
+### Vue
+
+```vue
+<template>
+  <aithe-page ref="pageRef"></aithe-page>
+</template>
+
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue';
+import { Router } from '@aithe/aithe-ui';
+
+const pageRef = ref(null);
+
+const router = new Router({
+  mode: 'history',
+  routes: [
+    { path: '/', component: 'home-page' },
+    { path: '/user/:id', component: 'user-page' },
+  ],
+});
+
+onMounted(() => {
+  router.start();
+  if (pageRef.value) pageRef.value.router = router;
+});
+
+onUnmounted(() => router.stop());
+</script>
+```
+
+### Angular
+
+```ts
+// app.component.ts
+import { Router } from '@aithe/aithe-ui';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <aithe-page></aithe-page>
+  `,
+})
+export class AppComponent implements OnInit, OnDestroy {
+  @ViewChild('page') page: ElementRef;
+
+  private router = new Router({
+    mode: 'history',
+    routes: [
+      { path: '/', component: 'home-page' },
+      { path: '/user/:id', component: 'user-page' },
+    ],
+  });
+
+  ngOnInit() {
+    this.router.start();
+  }
+
+  ngAfterViewInit() {
+    this.page.nativeElement.router = this.router;
+  }
+
+  ngOnDestroy() {
+    this.router.stop();
+  }
+}
+```
+
+### Svelte
+
+```svelte
+<script>
+import { onMount, onDestroy } from 'svelte';
+import { Router } from '@aithe/aithe-ui';
+
+const router = new Router({
+  mode: 'history',
+  routes: [
+    { path: '/', component: 'home-page' },
+    { path: '/user/:id', component: 'user-page' },
+  ],
+});
+
+onMount(() => {
+  router.start();
+});
+
+onDestroy(() => {
+  router.stop();
+});
+</script>
+
+<aithe-page router={router}></aithe-page>
+```
+
+---
+
 ## SSR 注意事项
 
 Aithe UI 组件依赖 DOM API（`document`、`window`），在 SSR 环境中需注意：
 
 1. **条件导入**：仅在客户端导入 Aithe UI
-2. **延迟初始化**：在 `onMounted` / `useEffect` / `afterViewInit` 中调用 `initializeAitheUI()`
-3. **主题注入**：`registerAitheTheme()` 内部检查 `typeof document`，SSR 时自动跳过
+2. **主题注入**：`registerAitheTheme()` 内部检查 `typeof document`，SSR 时自动跳过
 
 ```ts
 // Next.js / Nuxt 等框架中
-if (typeof window !== 'undefined') {
-  import('aithe-ui');
+if (typeof globalThis !== 'undefined') {
+  import('@aithe/aithe-ui');
 }
 ```
 
@@ -417,6 +565,6 @@ if (typeof window !== 'undefined') {
 
 - [快速上手](quickstart.md) — 安装和基本使用
 - [使用指南](guide.md) — 组件通用 API
-- [主题系统](theming.md) — 22 种内置主题
+- [主题系统](theming.md) — 25 种内置主题
 - [国际化](i18n.md) — 多语言支持
-- [API 参考](api/summary.md) — 全部组件详细 API
+- [API 参考](api/summary.md) — 全部 100 个组件详细 API