@aithe/aithe-ui 26.2.2 → 26.2.3

package/docs/api/framework/dashboard-panel.md

@@ -0,0 +1,127 @@
+# AitheDashboardPanel / AitheDashboardPanel 仪表盘面板
+
+> Dashboard panel child component with drag, resize, close, maximize support and slot-based content distribution.
+> 仪表盘面板子组件，支持拖拽、调整大小、关闭、最大化，通过插槽分发内容。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/framework/dashboard-panel';
+```
+
+## Description / 描述
+
+`<aithe-dashboard-panel>` renders as a card with a header bar (icon + label), close/maximize buttons, and a default slot for arbitrary content. It is designed to be used as a child of `<aithe-dashboard>`, which manages positioning and state. Drag is initiated by pressing the panel header and emits events that the parent dashboard listens to for grid-snap repositioning. Resize is initiated by dragging the edge handles. Action buttons (maximize, close) are shown on hover with a smooth transition.
+
+`<aithe-dashboard-panel>` 渲染为带标题栏（图标 + 标签）、关闭/最大化按钮和默认插槽的卡片。设计为 `<aithe-dashboard>` 的子组件，由父组件管理定位和状态。拖拽通过按下面板头部触发，发出事件供父仪表盘监听以实现格子吸附重定位。调整大小通过拖拽边缘手柄触发。操作按钮（最大化、关闭）在悬停时显示，带平滑过渡动画。
+
+## Slots / 插槽
+
+| Name           | Description (EN)                       | Description (CN)                 |
+| -------------- | -------------------------------------- | -------------------------------- |
+| (default)      | Panel body content.                    | 面板正文内容。                   |
+| header-actions | Slot for custom header action buttons. | 面板头部操作区域自定义按钮插槽。 |
+
+## CSS Parts / CSS 部件
+
+| Name         | Description (EN)      | Description (CN) |
+| ------------ | --------------------- | ---------------- |
+| header       | The panel header bar. | 面板标题栏。     |
+| body         | The panel body area.  | 面板正文区域。   |
+| close-btn    | The close button.     | 关闭按钮。       |
+| maximize-btn | The maximize button.  | 最大化按钮。     |
+
+## Properties / 属性
+
+| Name       | Type      | Default | Attribute     | Description (EN)                                    | Description (CN)             |
+| ---------- | --------- | ------- | ------------- | --------------------------------------------------- | ---------------------------- |
+| panelId    | `string`  | `''`    | `panel-id`    | Panel unique identifier.                            | 面板唯一标识。               |
+| x          | `number`  | `0`     | `x`           | Starting column (0-based).                          | 起始列（从 0 开始）。        |
+| y          | `number`  | `0`     | `y`           | Starting row (0-based).                             | 起始行（从 0 开始）。        |
+| w          | `number`  | `1`     | `w`           | Number of columns spanned.                          | 占列数。                     |
+| h          | `number`  | `1`     | `h`           | Number of rows spanned.                             | 占行数。                     |
+| closable   | `boolean` | `true`  | `closable`    | Whether the panel can be closed.                    | 面板是否可关闭。             |
+| label      | `string`  | `''`    | `label`       | Panel header label text.                            | 面板标题文本。               |
+| icon       | `string`  | `''`    | `icon`        | Panel header icon name (from aithe-icon glyph map). | 面板标题图标名称。           |
+| visible    | `boolean` | `true`  | `visible`     | Whether the panel is currently visible.             | 面板当前是否可见。           |
+| maximized  | `boolean` | `false` | `maximized`   | Whether the panel is currently maximized.           | 面板当前是否最大化。         |
+| locked     | `boolean` | `false` | `locked`      | Whether the dashboard is locked (disables drag).    | 仪表盘是否锁定（禁用拖拽）。 |
+| showHeader | `boolean` | `true`  | `show-header` | Whether to show the panel header bar.               | 是否显示面板标题栏。         |
+
+## Events / 事件
+
+| Name                     | Detail                                                              | Cancelable | Description (EN)                          | Description (CN)       |
+| ------------------------ | ------------------------------------------------------------------- | ---------- | ----------------------------------------- | ---------------------- |
+| aithe-panel-close        | `{ panelId: string }`                                               | No         | Emitted when the close button is clicked. | 关闭按钮点击时发出。   |
+| aithe-panel-drag-start   | `{ panelId: string, startX: number, startY: number }`               | No         | Emitted when drag starts.                 | 拖拽开始时发出。       |
+| aithe-panel-drag         | `{ panelId: string, deltaX: number, deltaY: number }`               | No         | Emitted during drag.                      | 拖拽过程中发出。       |
+| aithe-panel-drag-end     | `{ panelId: string }`                                               | No         | Emitted when drag ends.                   | 拖拽结束时发出。       |
+| aithe-panel-maximize     | `{ panelId: string }`                                               | No         | Emitted when maximize button is clicked.  | 最大化按钮点击时发出。 |
+| aithe-panel-resize-start | `{ panelId: string, edge: string, startX: number, startY: number }` | No         | Emitted when resize starts.               | 调整大小开始时发出。   |
+| aithe-panel-resize       | `{ panelId: string, edge: string, deltaX: number, deltaY: number }` | No         | Emitted during resize.                    | 调整大小过程中发出。   |
+| aithe-panel-resize-end   | `{ panelId: string }`                                               | No         | Emitted when resize ends.                 | 调整大小结束时发出。   |
+
+## Usage / 用法
+
+### Basic / 基本用法
+
+```html
+<aithe-dashboard-panel
+  panel-id="stats"
+  x="0"
+  y="0"
+  w="6"
+  h="4"
+  label="Statistics"
+  icon="barChart"
+  closable
+>
+  <p>Panel content here</p>
+</aithe-dashboard-panel>
+```
+
+### Non-closable Panel / 不可关闭面板
+
+```html
+<aithe-dashboard-panel
+  panel-id="pinned"
+  x="0"
+  y="0"
+  w="12"
+  h="2"
+  label="Pinned Info"
+  closable="false"
+>
+  <p>This panel cannot be closed.</p>
+</aithe-dashboard-panel>
+```
+
+### Hidden Header / 隐藏标题栏
+
+```html
+<aithe-dashboard-panel panel-id="embed" x="0" y="0" w="6" h="4" show-header="false">
+  <p>Panel without header bar</p>
+</aithe-dashboard-panel>
+```
+
+### Custom Header Actions / 自定义头部操作
+
+```html
+<aithe-dashboard-panel panel-id="chart" x="0" y="0" w="6" h="4" label="Chart">
+  <button slot="header-actions" @click="${()" ="">refresh()}>Refresh</button>
+  <p>Chart content</p>
+</aithe-dashboard-panel>
+```
+
+### Inside Dashboard / 在仪表盘中使用
+
+```html
+<aithe-dashboard columns="12" cell-height="60" gap="10">
+  <aithe-dashboard-panel panel-id="users" x="0" y="0" w="4" h="3" label="Users" icon="users">
+    <p>1,024 active users</p>
+  </aithe-dashboard-panel>
+  <aithe-dashboard-panel panel-id="revenue" x="4" y="0" w="8" h="3" label="Revenue" icon="barChart">
+    <p>$42,500 this month</p>
+  </aithe-dashboard-panel>
+</aithe-dashboard>
+```

package/docs/api/framework/dashboard.md

@@ -0,0 +1,140 @@
+# AitheDashboard / AitheDashboard 仪表盘
+
+> Drag-and-drop dashboard parent component using CSS Grid for panel positioning and sizing.
+> 拖拽式仪表盘父组件，基于 CSS Grid 格子布局管理面板定位与尺寸。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/framework/dashboard';
+```
+
+## Description / 描述
+
+`<aithe-dashboard>` is a grid-based dashboard container that manages child `<aithe-dashboard-panel>` elements. It provides a built-in toolbar with lock toggle, visibility dropdown, reset, fullscreen, and theme picker buttons. Panels are positioned using absolute coordinates calculated from grid cell dimensions. Drag-and-drop and resize are supported with grid snapping, boundary detection, overlap detection, and auto-rearrangement. Panel state can be persisted to `localStorage` via the `storage-key` attribute. The grid auto-fills the container width — cellWidth is computed from container width / columns.
+
+`<aithe-dashboard>` 是基于格子的仪表盘容器，管理子组件 `<aithe-dashboard-panel>`。提供内置工具栏，含锁定开关、可见性下拉框、重置、全屏和主题选择按钮。面板通过格子尺寸计算的绝对坐标定位。支持拖拽和调整大小吸附格子、边界检测、重叠检测和自动重排。面板状态可通过 `storage-key` 属性持久化到 `localStorage`。网格自动填充容器宽度——cellWidth 由容器宽度/列数计算。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                                                        | Description (CN)                                   |
+| --------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
+| (default) | Slot for `aithe-dashboard-panel` children.                              | 放置 `aithe-dashboard-panel` 子组件的插槽。        |
+| toolbar   | Slot for custom toolbar buttons (inserted at the left side of toolbar). | 工具栏插槽，用于插入自定义按钮（位于工具栏左侧）。 |
+
+## CSS Parts / CSS 部件
+
+| Name    | Description (EN)             | Description (CN)    |
+| ------- | ---------------------------- | ------------------- |
+| toolbar | The header toolbar bar.      | 头部工具栏。        |
+| grid    | The CSS Grid container area. | CSS Grid 容器区域。 |
+
+## Properties / 属性
+
+| Name           | Type      | Default | Attribute         | Description (EN)                                                    | Description (CN)                           |
+| -------------- | --------- | ------- | ----------------- | ------------------------------------------------------------------- | ------------------------------------------ |
+| columns        | `number`  | `12`    | `columns`         | Total number of grid columns.                                       | 网格总列数。                               |
+| cellHeight     | `number`  | `60`    | `cell-height`     | Base cell height in pixels.                                         | 格子基础高度（像素）。                     |
+| gap            | `number`  | `10`    | `gap`             | Gap between grid cells in pixels.                                   | 格子间距（像素）。                         |
+| locked         | `boolean` | `false` | `locked`          | Whether the dashboard is locked (disables all drag and resize).     | 仪表盘是否锁定（禁用所有拖拽和调整大小）。 |
+| storageKey     | `string`  | `''`    | `storage-key`     | Storage key for persisting panel state. Empty disables persistence. | 状态持久化存储键，为空则禁用持久化。       |
+| showToolbar    | `boolean` | `true`  | `show-toolbar`    | Whether to show the built-in toolbar header.                        | 是否显示内置工具栏头部。                   |
+| showVisibility | `boolean` | `true`  | `show-visibility` | Whether to show the visibility dropdown button.                     | 是否显示可见性下拉按钮。                   |
+| showLock       | `boolean` | `true`  | `show-lock`       | Whether to show the lock toggle button.                             | 是否显示锁定切换按钮。                     |
+| showReset      | `boolean` | `true`  | `show-reset`      | Whether to show the reset button.                                   | 是否显示重置按钮。                         |
+| showFullscreen | `boolean` | `true`  | `show-fullscreen` | Whether to show the fullscreen toggle button.                       | 是否显示全屏切换按钮。                     |
+| showTheme      | `boolean` | `true`  | `show-theme`      | Whether to show the theme picker button.                            | 是否显示主题选择按钮。                     |
+| showAutoArrange | `boolean` | `true`  | `show-auto-arrange` | Whether to show the auto-arrange button.                           | 是否显示自动重排按钮。                     |
+
+## Events / 事件
+
+| Name                       | Detail                              | Cancelable | Description (EN)                      | Description (CN)     |
+| -------------------------- | ----------------------------------- | ---------- | ------------------------------------- | -------------------- |
+| aithe-dashboard-change     | `{ panels: DashboardPanelState[] }` | No         | Emitted when panel layout changes.    | 面板布局变更时发出。 |
+| aithe-dashboard-fullscreen | `{ fullscreen: boolean }`           | No         | Emitted when fullscreen mode toggles. | 全屏模式切换时发出。 |
+
+## DashboardPanelState / 面板状态接口
+
+| Field     | Type      | Description (EN)                | Description (CN)      |
+| --------- | --------- | ------------------------------- | --------------------- |
+| panelId   | `string`  | Panel unique identifier.        | 面板唯一标识。        |
+| label     | `string`  | Panel display label.            | 面板显示标签。        |
+| x         | `number`  | Starting column (0-based).      | 起始列（从 0 开始）。 |
+| y         | `number`  | Starting row (0-based).         | 起始行（从 0 开始）。 |
+| w         | `number`  | Number of columns spanned.      | 占列数。              |
+| h         | `number`  | Number of rows spanned.         | 占行数。              |
+| visible   | `boolean` | Whether the panel is visible.   | 面板是否可见。        |
+| maximized | `boolean` | Whether the panel is maximized. | 面板是否最大化。      |
+
+## Usage / 用法
+
+### Basic / 基本用法
+
+```html
+<aithe-dashboard columns="12" cell-height="60" gap="10">
+  <aithe-dashboard-panel
+    panel-id="stats"
+    x="0"
+    y="0"
+    w="6"
+    h="4"
+    label="Statistics"
+    icon="barChart"
+  >
+    <p>Stats content</p>
+  </aithe-dashboard-panel>
+  <aithe-dashboard-panel panel-id="chart" x="6" y="0" w="6" h="4" label="Chart" icon="pieChart">
+    <p>Chart content</p>
+  </aithe-dashboard-panel>
+</aithe-dashboard>
+```
+
+### With State Persistence / 带状态持久化
+
+```html
+<aithe-dashboard storage-key="my-dashboard" columns="12">
+  <aithe-dashboard-panel panel-id="overview" x="0" y="0" w="12" h="3" label="Overview">
+    <p>Overview content</p>
+  </aithe-dashboard-panel>
+</aithe-dashboard>
+```
+
+### Locked Dashboard / 锁定仪表盘
+
+```html
+<aithe-dashboard locked show-toolbar>
+  <aithe-dashboard-panel panel-id="info" x="0" y="0" w="4" h="3" label="Info">
+    <p>Read-only panel</p>
+  </aithe-dashboard-panel>
+</aithe-dashboard>
+```
+
+### Without Toolbar / 无工具栏
+
+```html
+<aithe-dashboard show-toolbar="false">
+  <aithe-dashboard-panel panel-id="widget" x="0" y="0" w="6" h="4" label="Widget">
+    <p>Widget content</p>
+  </aithe-dashboard-panel>
+</aithe-dashboard>
+```
+
+### Selective Toolbar Buttons / 选择性显示工具栏按钮
+
+```html
+<aithe-dashboard show-visibility show-lock show-reset show-fullscreen="false" show-theme="false">
+  <aithe-dashboard-panel panel-id="data" x="0" y="0" w="6" h="4" label="Data">
+    <p>Data content</p>
+  </aithe-dashboard-panel>
+</aithe-dashboard>
+```
+
+### Fullscreen Mode / 全屏模式
+
+```html
+<aithe-dashboard show-fullscreen>
+  <aithe-dashboard-panel panel-id="big-chart" x="0" y="0" w="12" h="8" label="Big Chart">
+    <p>Fullscreen dashboard for big-screen display</p>
+  </aithe-dashboard-panel>
+</aithe-dashboard>
+```

package/docs/api/framework/header.md

@@ -0,0 +1,112 @@
+# AitheHeader / AitheHeader 页头
+
+> Framework-level page header with brand, navigation, built-in locale/theme toggles and user area.
+> 框架级页头，包含品牌区、导航区、内置国际化/主题切换和用户区。
+>
+> Locale and theme switching are handled internally by embedded `aithe-locale-switch` and `aithe-theme-switch` components — no external event handling required.
+> 国际化和主题切换由内嵌的 `aithe-locale-switch` 和 `aithe-theme-switch` 组件在内部完成，无需外部事件处理。
+
+## Slots / 插槽
+
+| Name   | Description (EN)                                               | Description (CN)                                  |
+| ------ | -------------------------------------------------------------- | ------------------------------------------------- |
+| left   | Custom brand area (overrides `brand` and `slogan` properties). | 自定义品牌区域（覆盖 `brand` 和 `slogan` 属性）。 |
+| center | Navigation / business columns area.                            | 导航/业务栏目区域。                               |
+| right  | User / login info area.                                        | 用户/登录信息区域。                               |
+
+## Properties / 属性
+
+| Name               | Type                            | Default      | Description (EN)                                                  | Description (CN)                   |
+| ------------------ | ------------------------------- | ------------ | ----------------------------------------------------------------- | ---------------------------------- |
+| brand              | `string`                        | `'Aithe UI'` | Brand name displayed in the left area.                            | 左侧品牌名称。                     |
+| slogan             | `string`                        | `''`         | Slogan displayed below the brand name.                            | 品牌名称下方的口号。               |
+| show-locale-switch | `boolean`                       | `false`      | Whether to show the locale switch between center and right areas. | 是否在中右区域之间显示国际化切换。 |
+| show-theme-switch  | `boolean`                       | `false`      | Whether to show the theme switch between center and right areas.  | 是否在中右区域之间显示主题切换。   |
+| center-align       | `'left' \| 'center' \| 'right'` | `'right'`    | Alignment of the center slot content.                             | 中间插槽内容的对齐方式。           |
+
+## CSS Parts / CSS 部件
+
+| Name   | Description (EN)                                               | Description (CN)                                 |
+| ------ | -------------------------------------------------------------- | ------------------------------------------------ |
+| center | The center container. Override alignment via `::part(center)`. | 中间容器。可通过 `::part(center)` 覆盖对齐方式。 |
+
+## Events / 事件
+
+The header itself does not emit custom events. The embedded `aithe-locale-switch` and `aithe-theme-switch` components emit their own events (`aithe-locale-change` / `aithe-theme-change`) which bubble through the header. By default, both components handle switching internally, so no event listener is needed.
+
+Header 本身不发出自定义事件。内嵌的 `aithe-locale-switch` 和 `aithe-theme-switch` 组件会发出各自的事件（`aithe-locale-change` / `aithe-theme-change`），这些事件会冒泡穿过 header。默认情况下，两个组件都在内部处理切换，因此无需监听事件。
+
+| Name | Detail | Description (EN)                                                                    | Description (CN)                                    |
+| ---- | ------ | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
+| —    | —      | No custom events emitted by the header itself. See embedded component events above. | Header 本身不发出自定义事件。参见上方内嵌组件事件。 |
+
+## Examples / 示例
+
+### Basic usage / 基础用法
+
+```html
+<aithe-header
+  brand="Aithe UI"
+  slogan="Enterprise Design System"
+  show-locale-switch
+  show-theme-switch
+>
+  <aithe-menu slot="center" mode="horizontal" active="home">
+    <aithe-menu-item name="home">Home</aithe-menu-item>
+    <aithe-menu-item name="docs">Docs</aithe-menu-item>
+  </aithe-menu>
+  <aithe-avatar slot="right" text="U"></aithe-avatar>
+</aithe-header>
+```
+
+### Center slot alignment / 中间插槽对齐
+
+Use the `center-align` attribute to control how center slot content is positioned:
+
+使用 `center-align` 属性控制中间插槽内容的对齐方式：
+
+```html
+<!-- Left-aligned / 靠左 -->
+<aithe-header center-align="left">
+  <aithe-menu slot="center" mode="horizontal">...</aithe-menu>
+</aithe-header>
+
+<!-- Centered / 居中 -->
+<aithe-header center-align="center">
+  <aithe-menu slot="center" mode="horizontal">...</aithe-menu>
+</aithe-header>
+
+<!-- Right-aligned (default) / 靠右（默认） -->
+<aithe-header center-align="right">
+  <aithe-button slot="center" href="/docs">Docs</aithe-button>
+</aithe-header>
+```
+
+For more granular control, use the `::part(center)` CSS selector:
+
+如需更细粒度的控制，可使用 `::part(center)` CSS 选择器：
+
+```css
+aithe-header::part(center) {
+  justify-content: space-between;
+  gap: 24px;
+}
+```
+
+### Overriding built-in locale/theme behavior / 覆盖内置国际化/主题行为
+
+The embedded `aithe-locale-switch` and `aithe-theme-switch` handle switching by default. To take manual control, listen for their events on the header and call `preventDefault()`:
+
+内嵌的 `aithe-locale-switch` 和 `aithe-theme-switch` 默认处理切换。如需手动控制，可在 header 上监听它们的事件并调用 `preventDefault()`：
+
+```js
+const header = document.querySelector('aithe-header');
+header.addEventListener('aithe-locale-change', (e) => {
+  e.preventDefault();
+  console.log('Custom locale:', e.detail.locale);
+});
+header.addEventListener('aithe-theme-change', (e) => {
+  e.preventDefault();
+  console.log('Custom category:', e.detail.category, 'value:', e.detail.value);
+});
+```

package/docs/api/framework/page.md

@@ -0,0 +1,144 @@
+# AithePage / AithePage 路由容器
+
+> Framework-level route container that renders the matched page component.
+> 框架级路由容器，渲染匹配到的页面组件。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/framework/page';
+```
+
+## Description / 描述
+
+`<aithe-page>` connects to a `Router` instance, listens for route changes, and dynamically renders the component specified by the matched route's `component` field. Route params, query, and location are passed as properties to the rendered component.
+
+`<aithe-page>` 连接到 `Router` 实例，监听路由变更，动态渲染匹配路由的 `component` 字段指定的组件。路由参数、查询参数和位置信息会作为属性传递给渲染的组件。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                                                           | Description (CN)                                      |
+| --------- | -------------------------------------------------------------------------- | ----------------------------------------------------- |
+| (default) | Fallback content when no route matches and `notFoundComponent` is not set. | 无匹配路由且未设置 `notFoundComponent` 时的回退内容。 |
+
+## CSS Parts / CSS 部件
+
+| Name      | Description (EN)                                  | Description (CN)         |
+| --------- | ------------------------------------------------- | ------------------------ |
+| container | The container element wrapping the rendered page. | 包裹渲染页面的容器元素。 |
+
+## Properties / 属性
+
+| Name                | Type             | Default | Description (EN)                                         | Description (CN)               |
+| ------------------- | ---------------- | ------- | -------------------------------------------------------- | ------------------------------ |
+| router              | `Router \| null` | `null`  | Router instance to connect to.                           | 要连接的 Router 实例。         |
+| not-found-component | `string`         | `''`    | Fallback component tag name when no route matches (404). | 无匹配路由时的回退组件标签名。 |
+
+## Events / 事件
+
+| Name               | Detail                        | Cancelable | Description (EN)                | Description (CN) |
+| ------------------ | ----------------------------- | ---------- | ------------------------------- | ---------------- |
+| aithe-route-change | `{ location: RouteLocation }` | No         | Emitted when the route changes. | 路由变更时发出。 |
+
+## Passed Properties / 传递给页面组件的属性
+
+When a route matches, the rendered component receives the following properties:
+
+当路由匹配时，渲染的组件会接收以下属性：
+
+| Property  | Type                     | Description (EN)                                       | Description (CN)     |
+| --------- | ------------------------ | ------------------------------------------------------ | -------------------- |
+| .params   | `Record<string, string>` | Path parameters (e.g. `{ id: '42' }` for `/user/:id`). | 路径参数。           |
+| .query    | `Record<string, string>` | Query parameters (e.g. `{ a: '1' }` for `?a=1`).       | 查询参数。           |
+| .route    | `RouteConfig \| null`    | The matched route config.                              | 匹配的路由配置。     |
+| .location | `RouteLocation`          | The full route location object.                        | 完整的路由位置对象。 |
+
+## Usage / 用法
+
+### Basic / 基本用法
+
+```ts
+import { Router } from '@aithe/aithe-ui';
+
+const router = new Router({
+  mode: 'history',
+  routes: [
+    { path: '/', component: 'home-page' },
+    { path: '/user/:id', component: 'user-page' },
+    { path: '*', component: 'not-found-page' },
+  ],
+});
+router.start();
+```
+
+```html
+<aithe-page .router="${router}"></aithe-page>
+```
+
+### With 404 Component / 带 404 组件
+
+```html
+<aithe-page .router="${router}" not-found-component="not-found-page"></aithe-page>
+```
+
+### Accessing Route Params in Page Component / 在页面组件中访问路由参数
+
+```ts
+@customElement('user-page')
+export class UserPage extends LitElement {
+  @property({ type: Object }) params: Record<string, string> = {};
+  @property({ type: Object }) query: Record<string, string> = {};
+
+  render() {
+    return html`
+      <p>User ID: ${this.params.id}</p>
+    `;
+  }
+}
+```
+
+## Router API / Router API
+
+The `Router` class is the core routing engine. It is exported from `@aithe/aithe-ui` alongside `AithePage`.
+
+`Router` 类是路由核心引擎，与 `AithePage` 一起从 `@aithe/aithe-ui` 导出。
+
+### Constructor / 构造函数
+
+```ts
+new Router({ mode?: 'hash' | 'history', routes: RouteConfig[] })
+```
+
+### Methods / 方法
+
+| Method                   | Description (EN)                                            | Description (CN)                               |
+| ------------------------ | ----------------------------------------------------------- | ---------------------------------------------- |
+| `start()`                | Start listening for route changes.                          | 启动路由监听。                                 |
+| `stop()`                 | Stop listening for route changes.                           | 停止路由监听。                                 |
+| `navigate(path: string)` | Programmatic navigation (pushState).                        | 编程式导航（pushState）。                      |
+| `replace(path: string)`  | Replace current history entry and navigate.                 | 替换当前历史记录并导航。                       |
+| `back()`                 | Go back in history.                                         | 历史记录后退。                                 |
+| `forward()`              | Go forward in history.                                      | 历史记录前进。                                 |
+| `match(path: string)`    | Match a path and return `RouteLocation` without navigation. | 匹配路径并返回 `RouteLocation`（不触发导航）。 |
+| `onChange(listener)`     | Subscribe to route changes; returns unsubscribe function.   | 订阅路由变更；返回取消订阅函数。               |
+| `addGuard(guard)`        | Add a route guard; returns remove function.                 | 添加路由守卫；返回移除函数。                   |
+| `addRoutes(routes)`      | Add route configurations.                                   | 添加路由配置。                                 |
+
+### RouteConfig / 路由配置
+
+| Field     | Type                      | Description (EN)                                                 | Description (CN)               |
+| --------- | ------------------------- | ---------------------------------------------------------------- | ------------------------------ |
+| path      | `string`                  | Path pattern: static `/home`, dynamic `/user/:id`, wildcard `*`. | 路径模式：静态、动态、通配符。 |
+| component | `string`                  | Component tag name to render when matched.                       | 匹配时渲染的组件标签名。       |
+| meta      | `Record<string, unknown>` | Route metadata (e.g. auth, title).                               | 路由元数据。                   |
+| children  | `RouteConfig[]`           | Child routes for nested routing.                                 | 子路由（嵌套路由）。           |
+
+### RouteLocation / 路由位置
+
+| Field    | Type                     | Description (EN)                         | Description (CN)                  |
+| -------- | ------------------------ | ---------------------------------------- | --------------------------------- |
+| path     | `string`                 | Full path without query string and hash. | 完整路径（不含查询参数和 hash）。 |
+| params   | `Record<string, string>` | Path parameters.                         | 路径参数。                        |
+| query    | `Record<string, string>` | Query parameters.                        | 查询参数。                        |
+| route    | `RouteConfig \| null`    | Matched route config.                    | 匹配的路由配置。                  |
+| fullPath | `string`                 | Full URL including query string.         | 完整 URL（含查询参数）。          |