@aithe/aithe-ui 26.2.2 → 26.2.3

package/docs/api/data/tree-menu.md

@@ -5,36 +5,38 @@
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
-| — | — | No slots (content driven by `items` property). | 无插槽（内容由 items 属性控制）。 |
+| Name | Description (EN) | Description (CN)                               |
+| ---- | ---------------- | ---------------------------------------------- | 
+| —    | No slots (content driven by `items` property). | 无插槽（内容由 items 属性控制）。 |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| items | String (JSON) | `''` | JSON string of tree menu items (maps to `items` HTML attribute). | 树菜单项的 JSON 字符串（映射到 `items` HTML 属性）。 |
-| items | `AitheTreeNodeMeta[]` | `[]` | Array of tree menu items (prefer this in JS). | 树菜单项数组（在 JS 中优先使用）。 |
-| active | `string` | `''` | Active (selected) menu item value. | 当前选中的菜单项值。 |
-| expandAll | Boolean | false | Whether all nodes are expanded by default. | 是否默认展开所有节点。 |
+| Name      | Type                       | Default    | Description (EN)                                                                                               | Description (CN)                                                             |
+| --------- | -------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| items     | String (JSON)              | `''`       | JSON string of tree menu items (maps to `items` HTML attribute).                                               | 树菜单项的 JSON 字符串（映射到 `items` HTML 属性）。                         |
+| items     | `AitheTreeNodeMeta[]`      | `[]`       | Array of tree menu items (prefer this in JS).                                                                  | 树菜单项数组（在 JS 中优先使用）。                                           |
+| active    | `string`                   | `''`       | Active (selected) menu item value.                                                                             | 当前选中的菜单项值。                                                         |
+| expandAll | Boolean                    | false      | Whether all nodes are expanded by default.                                                                     | 是否默认展开所有节点。                                                       |
 | direction | 'vertical' \| 'horizontal' | 'vertical' | Layout direction. Vertical stacks items; horizontal arranges top-level items in a row with dropdown sub-menus. | 布局方向。垂直堆叠菜单项；水平将顶级菜单项排列为一行，子菜单以下拉方式展开。 |
+| item-filter | `AitheSidebarItemFilter \| null` | `null` | Filter callback for menu items. Return `true` to show, `false` to hide. Useful for permission control. | 菜单项过滤回调。返回 `true` 显示，`false` 隐藏。适用于权限控制。 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
+| Name         | Detail      | Description (EN)                      | Description (CN)   |
+| ------------ | ----------- | ------------------------------------- | ------------------ |
 | aithe-select | `{ value }` | Emitted when a menu item is selected. | 菜单项选中时触发。 |
 
 ## Data Item Fields / 数据项字段
 
-| Field | Type | Description (EN) | Description (CN) |
-|-------|------|-------------------|-------------------|
-| label | `string` | Display text of the menu item. | 菜单项的显示文本。 |
-| id | `string` | Unique value identifying this node. | 节点唯一标识值。 |
-| icon | `string` | Icon name rendered before the label via aithe-icon. | 通过 aithe-icon 在标签前渲染的图标名称。 |
-| disabled | `boolean` | Whether the menu item is non-interactive. | 是否禁用菜单项。 |
-| intent | `AitheIntent` | Visual intent / semantic color for the node. | 节点的视觉意图/语义色。 |
-| children | `AitheTreeNodeMeta[]` | Nested sub-menu items. | 嵌套子菜单项。 |
+| Field    | Type                  | Description (EN)                                                                                                      | Description (CN)                                                           |
+| -------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| label    | `string`              | Display text of the menu item. Used as i18n fallback when `i18n` is set.                                              | 菜单项的显示文本。设置 `i18n` 时作为缺省值。                               |
+| id       | `string`              | Unique value identifying this node.                                                                                   | 节点唯一标识值。                                                           |
+| icon     | `string`              | Icon name rendered before the label via aithe-icon.                                                                   | 通过 aithe-icon 在标签前渲染的图标名称。                                   |
+| disabled | `boolean`             | Whether the menu item is non-interactive.                                                                             | 是否禁用菜单项。                                                           |
+| variant   | `AitheVariant`        | Visual variant / semantic color for the node.                                                                         | 节点的视觉变体/语义色。                                                    |
+| children | `AitheTreeNodeMeta[]` | Nested sub-menu items.                                                                                                | 嵌套子菜单项。                                                             |
+| i18n     | `string`              | i18n translation key. When set, `t(i18n, label)` is used to translate the label; `label` serves as the default value. | 国际化翻译键。设置后通过 `t(i18n, label)` 翻译 label，`label` 作为缺省值。 |
 
 ## Examples / 示例
 
@@ -56,3 +58,40 @@
   active="dashboard"
 ></aithe-tree-menu>
 ```
+
+### With i18n / 国际化
+
+```html
+<aithe-tree-menu
+  items='[{"label":"Dashboard","id":"dashboard","icon":"home","i18n":"app.menu.dashboard"},{"label":"Settings","id":"settings","icon":"settings","i18n":"app.menu.settings","children":[{"label":"Profile","id":"profile","i18n":"app.menu.profile"},{"label":"Security","id":"security","i18n":"app.menu.security"}]}]'
+  active="dashboard"
+></aithe-tree-menu>
+```
+
+When `i18n` is set, the component automatically translates the label via `t(i18n, label)`. The `label` field serves as the fallback default value when the translation key is not found.
+
+设置 `i18n` 后，组件自动通过 `t(i18n, label)` 翻译 label。`label` 字段作为翻译键未找到时的缺省值。
+
+### Permission-based filtering / 基于权限的菜单过滤
+
+Use `itemFilter` to control which menu items are visible based on the current user's roles/permissions. The callback receives the item metadata and nesting depth (0 = top-level).
+
+使用 `itemFilter` 根据当前用户角色/权限控制菜单项可见性。回调接收菜单项元数据和嵌套深度（0 = 顶层）。
+
+```js
+const menu = document.querySelector('aithe-tree-menu');
+menu.itemFilter = (item, depth) => {
+  // Hide "Settings" for non-admin users
+  if (item.id === 'settings' && !currentUser.roles.includes('admin')) {
+    return false;
+  }
+  return true;
+};
+```
+
+```html
+<aithe-tree-menu
+  .items="${menuItems}"
+  active="dashboard"
+></aithe-tree-menu>
+```

package/docs/api/data/tree.md

@@ -5,41 +5,44 @@
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
-| — | — | No slots (content driven by `data` property). | 无插槽（内容由 data 属性控制）。 |
+| Name | Description (EN)                              | Description (CN)                              |
+| ---- |-----------------------------------------------| --------------------------------------------- | 
+| —    | No slots (content driven by `data` property). | 无插槽（内容由 data 属性控制）。 |
 
 ## Properties / 属性
 
-| Name | Type | Default | Description (EN) | Description (CN) |
-|------|------|---------|-------------------|-------------------|
-| data | String | '[]' | JSON string of tree node data. Each node supports `icon` and `intent` (AitheIntent) fields. | 树节点数据的 JSON 字符串。每个节点支持 `icon` 和 `intent`（AitheIntent）字段。 |
-| title | `string` | `''` | Display title (shown as tooltip). | 显示标题（作为工具提示）。 |
-| icon | `string` | `''` | Icon name to display before the tree title. | 在树标题前显示的图标名称。 |
-| checkable | Boolean | false | Whether nodes show checkboxes for selection. | 节点是否显示复选框以供选择。 |
-| expandAll | Boolean | false | Whether all nodes are expanded by default. | 是否默认展开所有节点。 |
-| renderer | Function | undefined | Custom renderer function for tree nodes. Receives a TreeNode and returns a TemplateResult. | 树节点的自定义渲染函数。接收 TreeNode 并返回 TemplateResult。 |
+| Name      | Type     | Default   | Description (EN)                                                                             | Description (CN)                                                                |
+| --------- | -------- | --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| data      | String   | '[]'      | JSON string of tree node data. Each node supports `icon` and `variant` (AitheVariant) fields. | 树节点数据的 JSON 字符串。每个节点支持 `icon` 和 `variant`（AitheVariant）字段。 |
+| title     | `string` | `''`      | Display title (shown as tooltip).                                                            | 显示标题（作为工具提示）。                                                      |
+| icon      | `string` | `''`      | Icon name to display before the tree title.                                                  | 在树标题前显示的图标名称。                                                      |
+| checkable | Boolean  | false     | Whether nodes show checkboxes for selection.                                                 | 节点是否显示复选框以供选择。                                                    |
+| expandAll | Boolean  | false     | Whether all nodes are expanded by default.                                                   | 是否默认展开所有节点。                                                          |
+| renderer  | Function | undefined | Custom renderer function for tree nodes. Receives a TreeNode and returns a TemplateResult.   | 树节点的自定义渲染函数。接收 TreeNode 并返回 TemplateResult。                   |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-check | { checked } | Emitted when a checkbox is toggled. | 复选框切换时触发。 |
-| aithe-node-click | { node } | Emitted when a node label is clicked. | 节点标签被点击时触发。 |
+| Name             | Detail      | Description (EN)                      | Description (CN)       |
+| ---------------- | ----------- | ------------------------------------- | ---------------------- |
+| aithe-check      | { checked } | Emitted when a checkbox is toggled.   | 复选框切换时触发。     |
+| aithe-node-click | { node }    | Emitted when a node label is clicked. | 节点标签被点击时触发。 |
 
 ## Data Node Fields / 数据节点字段
 
-| Field | Type | Description (EN) | Description (CN) |
-|-------|------|-------------------|-------------------|
-| label | `string` | Display text of the node. | 节点的显示文本。 |
-| id | `string` | Unique identifier of the node. | 节点的唯一标识。 |
-| children | `AitheTreeNodeMeta[]` | Nested child nodes. | 嵌套子节点。 |
-| disabled | `boolean` | Whether the node is non-interactive. | 是否不可交互。 |
-| icon | `string` | Icon name rendered before the label via aithe-icon. | 通过 aithe-icon 在标签前渲染的图标名称。 |
-| intent | `AitheIntent` | Visual intent / semantic color for the node label. | 节点标签的视觉意图/语义色。 |
+| Field    | Type                  | Description (EN)                                                                                                      | Description (CN)                                                           |
+| -------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| label    | `string`              | Display text of the node. Used as i18n fallback when `i18n` is set.                                                   | 节点的显示文本。设置 `i18n` 时作为缺省值。                                 |
+| id       | `string`              | Unique identifier of the node.                                                                                        | 节点的唯一标识。                                                           |
+| children | `AitheTreeNodeMeta[]` | Nested child nodes.                                                                                                   | 嵌套子节点。                                                               |
+| disabled | `boolean`             | Whether the node is non-interactive.                                                                                  | 是否不可交互。                                                             |
+| icon     | `string`              | Icon name rendered before the label via aithe-icon.                                                                   | 通过 aithe-icon 在标签前渲染的图标名称。                                   |
+| variant   | `AitheVariant`        | Visual variant / semantic color for the node label.                                                                   | 节点标签的视觉变体/语义色。                                                |
+| i18n     | `string`              | i18n translation key. When set, `t(i18n, label)` is used to translate the label; `label` serves as the default value. | 国际化翻译键。设置后通过 `t(i18n, label)` 翻译 label，`label` 作为缺省值。 |
 
 ## Examples / 示例
 
+### Basic usage / 基础用法
+
 ```html
 <aithe-tree
   data='[{"label":"Root","id":"root","children":[{"label":"Child","id":"child"}]}]'
@@ -48,4 +51,18 @@
   checkable
   expand-all
 ></aithe-tree>
-```
+```
+
+### With i18n / 国际化
+
+```html
+<aithe-tree
+  data='[{"label":"Root","id":"root","i18n":"app.tree.root","children":[{"label":"Child","id":"child","i18n":"app.tree.child"}]}]'
+  checkable
+  expand-all
+></aithe-tree>
+```
+
+When `i18n` is set, the component automatically translates the label via `t(i18n, label)`. The `label` field serves as the fallback default value when the translation key is not found.
+
+设置 `i18n` 后，组件自动通过 `t(i18n, label)` 翻译 label。`label` 字段作为翻译键未找到时的缺省值。

package/docs/api/display/code-editor.md

@@ -0,0 +1,275 @@
+# AitheCodeEditor / 代码编辑器
+
+> A code editor Web Component based on Lit + TypeScript with syntax highlighting and no third-party dependencies.
+> 基于 Lit + TypeScript 的代码编辑器 Web Component，具有语法高亮功能，无需第三方依赖。
+
+## Slots / 插槽
+
+| Name          | Description (EN)                             | Description (CN)         |
+| ------------- | -------------------------------------------- | ------------------------ |
+| toolbar-left  | Custom content on the left side of toolbar.  | 工具栏左侧的自定义内容。 |
+| toolbar-right | Custom content on the right side of toolbar. | 工具栏右侧的自定义内容。 |
+| preview       | Custom preview content (when show-preview).  | 自定义预览内容。         |
+
+## Properties / 属性
+
+| Name                  | Type      | Default        | Description (EN)                                                                          | Description (CN)                                       |
+| --------------------- | --------- | -------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| value                 | `string`  | `''`           | Editor content. Code text displayed in the editor.                                        | 编辑器内容。编辑器中显示的代码文本。                   |
+| language              | `string`  | `'javascript'` | Programming language for syntax highlighting. Dynamically resolved from `SyntaxRegistry`. | 用于语法高亮的编程语言。从 `SyntaxRegistry` 动态获取。 |
+| readonly              | `boolean` | `false`        | Whether the editor is readonly. When true, content is not editable.                       | 是否只读。为 true 时，内容不可编辑。                   |
+| lineNumbers           | `boolean` | `true`         | Whether to show line numbers on the left side.                                            | 是否显示左侧行号。                                     |
+| placeholder           | `string`  | `''`           | Placeholder text shown when editor is empty.                                              | 编辑器为空时显示的占位符文本。                         |
+| showToolbar           | `boolean` | `false`        | Whether to show the toolbar with action buttons.                                          | 是否显示包含操作按钮的工具栏。                         |
+| showTheme             | `boolean` | `true`         | Whether to show the theme picker in the toolbar.                                          | 是否在工具栏中显示主题选择器。                         |
+| showPreview           | `boolean` | `false`        | Whether to show the preview pane with a resizable splitter.                               | 是否显示带可调整分割条的预览面板。                     |
+| showLanguage          | `boolean` | `true`         | Whether to show the language selector in the toolbar.                                     | 是否在工具栏中显示语言选择器。                         |
+| showFullscreen        | `boolean` | `true`         | Whether to show the fullscreen button in the toolbar.                                     | 是否在工具栏中显示全屏按钮。                           |
+| showCopy              | `boolean` | `true`         | Whether to show the copy button in the toolbar.                                           | 是否在工具栏中显示复制按钮。                           |
+| showLineNumbersToggle | `boolean` | `true`         | Whether to show the line numbers toggle button in the toolbar.                            | 是否在工具栏中显示行号切换按钮。                       |
+
+> **Note:** The `showTheme` property controls the visibility of the `<aithe-theme-picker>` component in the toolbar. When a theme is selected, the `data-aithe-theme` attribute is set on the editor wrapper, and an `aithe-theme-change` event is emitted.
+> **注意：** `showTheme` 属性控制工具栏中 `<aithe-theme-picker>` 组件的可见性。选择主题时，编辑器外壳上会设置 `data-aithe-theme` 属性，并触发 `aithe-theme-change` 事件。
+
+## Events / 事件
+
+All events are dispatched with the `aithe-` prefix following the Aithe convention.
+所有事件均遵循 Aithe 约定，使用 `aithe-` 前缀。
+
+| Name                      | Detail                                                  | Description (EN)                                   | Description (CN)               |
+| ------------------------- | ------------------------------------------------------- | -------------------------------------------------- | ------------------------------ |
+| aithe-input               | `{ value: string }`                                     | Fired when editor content changes.                 | 当编辑器内容发生变化时触发。   |
+| aithe-focus               | —                                                       | Fired when editor gains focus.                     | 当编辑器获得焦点时触发。       |
+| aithe-blur                | —                                                       | Fired when editor loses focus.                     | 当编辑器失去焦点时触发。       |
+| aithe-language-change     | `{ language: string }`                                  | Fired when language is changed via toolbar select. | 通过工具栏选择更改语言时触发。 |
+| aithe-line-numbers-change | `{ lineNumbers: boolean }`                              | Fired when line numbers visibility is toggled.     | 行号显示切换时触发。           |
+| aithe-fullscreen-change   | `{ isFullscreen: boolean }`                             | Fired when fullscreen mode is toggled.             | 全屏模式切换时触发。           |
+| aithe-copy                | `{ success: boolean; value?: string; error?: unknown }` | Fired after copy button is clicked.                | 点击复制按钮后触发。           |
+| aithe-theme-change        | `{ theme: string }`                                     | Fired when theme is changed via toolbar picker.    | 通过工具栏选择更改主题时触发。 |
+| aithe-preview-toggle      | `{ visible: boolean }`                                  | Fired when preview pane is toggled.                | 预览面板切换时触发。           |
+
+> **Note:** Pressing the `Escape` key exits fullscreen mode. This is handled via a global `keydown` listener added in `connectedCallback` and removed in `disconnectedCallback`.
+> **注意：** 按下 `Escape` 键退出全屏模式。这是通过在 `connectedCallback` 中添加的全局 `keydown` 监听器处理的，在 `disconnectedCallback` 中移除。
+
+## Methods / 方法
+
+| Name                  | Parameters                     | Return                               | Description (EN)                                   | Description (CN)             |
+| --------------------- | ------------------------------ | ------------------------------------ | -------------------------------------------------- | ---------------------------- |
+| focus                 | —                              | `void`                               | Focus the editor textarea.                         | 将焦点设置到编辑器文本区域。 |
+| getSelectionStart     | —                              | `number`                             | Get the start position of text selection.          | 获取选区起始位置。           |
+| getSelectionEnd       | —                              | `number`                             | Get the end position of text selection.            | 获取选区结束位置。           |
+| setSelection          | `(start: number, end: number)` | `void`                               | Set the text selection range.                      | 设置文本选区范围。           |
+| getSupportedLanguages | —                              | `{ langId: string; name: string }[]` | Get the list of supported languages from registry. | 从注册表获取支持的语言列表。 |
+
+> **Note:** The editor intercepts the `Tab` key to insert 2 spaces instead of moving focus out of the textarea.
+> **注意：** 编辑器拦截 `Tab` 键，插入 2 个空格而不是移出焦点。
+
+## CSS Properties / CSS 属性
+
+The editor uses the following `--aithe-code-*` CSS custom properties for syntax highlighting colors. These are automatically set by each Aithe theme.
+编辑器使用以下 `--aithe-code-*` CSS 自定义属性控制语法高亮颜色，每个 Aithe 主题会自动设置这些变量。
+
+| Name                      | Default   | Description (EN)              | Description (CN) |
+| ------------------------- | --------- | ----------------------------- | ---------------- |
+| --aithe-code-keyword      | `#a626a4` | Keyword color.                | 关键字颜色。     |
+| --aithe-code-boolean      | `#986801` | Boolean literal color.        | 布尔值颜色。     |
+| --aithe-code-builtin      | `#4078f2` | Built-in object color.        | 内置对象颜色。   |
+| --aithe-code-number       | `#986801` | Numeric literal color.        | 数值颜色。       |
+| --aithe-code-string       | `#50a14f` | String literal color.         | 字符串颜色。     |
+| --aithe-code-function     | `#4078f2` | Function name color.          | 函数名颜色。     |
+| --aithe-code-type         | `#c18401` | Type name color.              | 类型名颜色。     |
+| --aithe-code-preprocessor | `#a626a4` | Preprocessor directive color. | 预处理指令颜色。 |
+| --aithe-code-tag          | `#e45649` | XML/HTML tag color.           | 标签颜色。       |
+| --aithe-code-attr         | `#986801` | XML/HTML attribute color.     | 属性颜色。       |
+| --aithe-code-key          | `#e45649` | JSON/YAML key color.          | 键名颜色。       |
+| --aithe-code-punctuation  | `#383a42` | Punctuation character color.  | 标点符号颜色。   |
+| --aithe-code-comment      | `#94a3b8` | Comment color.                | 注释颜色。       |
+| --aithe-code-doctype      | `#94a3b8` | DOCTYPE declaration color.    | DOCTYPE 颜色。   |
+| --aithe-code-entity       | `#986801` | HTML entity color.            | HTML 实体颜色。  |
+| --aithe-code-placeholder  | `#94a3b8` | Placeholder text color.       | 占位符颜色。     |
+
+## Syntax Highlighting Classes / 语法高亮样式类
+
+The editor applies the following CSS classes for syntax highlighting:
+编辑器应用以下 CSS 类进行语法高亮：
+
+| Class              | Description (EN)              | Description (CN) |
+| ------------------ | ----------------------------- | ---------------- |
+| `.hl-keyword`      | Programming language keywords | 编程语言关键字   |
+| `.hl-boolean`      | Boolean values (true/false)   | 布尔值           |
+| `.hl-builtin`      | Built-in objects / globals    | 内置对象/全局量  |
+| `.hl-number`       | Numeric values                | 数值             |
+| `.hl-string`       | String literals               | 字符串字面量     |
+| `.hl-function`     | Function names                | 函数名           |
+| `.hl-type`         | Type names                    | 类型名           |
+| `.hl-preprocessor` | Preprocessor directives       | 预处理指令       |
+| `.hl-key`          | JSON/YAML object keys         | JSON/YAML 键     |
+| `.hl-tag`          | XML/HTML tags                 | XML/HTML 标签    |
+| `.hl-attr`         | XML/HTML attributes           | XML/HTML 属性    |
+| `.hl-comment`      | Comments                      | 注释             |
+| `.hl-doctype`      | DOCTYPE declarations          | DOCTYPE 声明     |
+| `.hl-entity`       | HTML entities                 | HTML 实体        |
+| `.hl-punctuation`  | Punctuation characters        | 标点符号         |
+| `.hl-placeholder`  | Placeholder text              | 占位符文本       |
+
+## Supported Languages / 支持的语言
+
+Languages are dynamically registered via `SyntaxRegistry`. The built-in languages are:
+语言通过 `SyntaxRegistry` 动态注册。内置语言包括：
+
+| langId     | Name        |
+| ---------- | ----------- |
+| javascript | JavaScript  |
+| typescript | TypeScript  |
+| c          | C           |
+| cpp        | C++         |
+| java       | Java        |
+| html       | HTML        |
+| xml        | XML         |
+| json       | JSON        |
+| jsonline   | JSON (Line) |
+| yaml       | YAML        |
+| markdown   | Markdown    |
+| python     | Python      |
+| ruby       | Ruby        |
+| bash       | Bash        |
+| css        | CSS         |
+| sql        | SQL         |
+| rust       | Rust        |
+| go         | Go          |
+| kotlin     | Kotlin      |
+| swift      | Swift       |
+| jsx        | JSX         |
+| tsx        | TSX         |
+| vue        | Vue         |
+| svelte     | Svelte      |
+| wasm       | WebAssembly |
+| dockerfile | Dockerfile  |
+| makefile   | Makefile    |
+| cmake      | CMake       |
+| latex      | LaTeX       |
+| fsharp     | F#          |
+| powershell | PowerShell  |
+| perl       | Perl        |
+| lua        | Lua         |
+| scala      | Scala       |
+| dart       | Dart        |
+| r          | R           |
+| objectivec | Objective-C |
+
+To register a custom language, use `SyntaxRegistry.register()`:
+如需注册自定义语言，使用 `SyntaxRegistry.register()`：
+
+```typescript
+import { SyntaxRegistry } from '@aithe/aithe-ui';
+
+SyntaxRegistry.register({
+  langId: 'mylang',
+  name: 'My Language',
+  rules: [
+    { pattern: /\b(keyword1|keyword2)\b/g, className: 'hl-keyword', order: 1 },
+    { pattern: /"(?:[^"\\]|\\.)*"/g, className: 'hl-string', order: 2 },
+  ],
+});
+```
+
+## Examples / 示例
+
+### Basic Usage / 基础用法
+
+```html
+<aithe-code-editor language="javascript"></aithe-code-editor>
+```
+
+### With Toolbar / 带工具栏
+
+```html
+<aithe-code-editor language="typescript" show-toolbar></aithe-code-editor>
+```
+
+### Readonly Mode / 只读模式
+
+```html
+<aithe-code-editor language="json" readonly value='{"key": "value"}'></aithe-code-editor>
+```
+
+### Without Line Numbers / 不显示行号
+
+```html
+<aithe-code-editor language="java" line-numbers="false"></aithe-code-editor>
+```
+
+### Custom Toolbar Buttons / 自定义工具栏按钮
+
+```html
+<aithe-code-editor
+  language="javascript"
+  show-toolbar
+  show-language
+  show-fullscreen="false"
+  show-copy="false"
+  show-line-numbers-toggle
+></aithe-code-editor>
+```
+
+### Custom Toolbar Content via Slots / 通过插槽自定义工具栏内容
+
+```html
+<aithe-code-editor language="javascript" show-toolbar>
+  <button slot="toolbar-left" onclick="runCode()">Run</button>
+  <button slot="toolbar-right" onclick="formatCode()">Format</button>
+</aithe-code-editor>
+```
+
+### With Preview Pane / 带预览面板
+
+```html
+<aithe-code-editor language="markdown" show-toolbar show-preview>
+  <div slot="preview"><!-- rendered preview content --></div>
+</aithe-code-editor>
+```
+
+### Event Handling / 事件处理
+
+```javascript
+const editor = document.querySelector('aithe-code-editor');
+editor.addEventListener('aithe-input', (e) => {
+  console.log('Content:', e.detail.value);
+});
+editor.addEventListener('aithe-language-change', (e) => {
+  console.log('Language changed to:', e.detail.language);
+});
+editor.addEventListener('aithe-line-numbers-change', (e) => {
+  console.log('Line numbers visible:', e.detail.lineNumbers);
+});
+editor.addEventListener('aithe-theme-change', (e) => {
+  console.log('Theme changed to:', e.detail.theme);
+});
+editor.addEventListener('aithe-preview-toggle', (e) => {
+  console.log('Preview visible:', e.detail.visible);
+});
+```
+
+### Using with TypeScript / 在 TypeScript 中使用
+
+```typescript
+import '@aithe/aithe-ui';
+
+const editor = document.querySelector('aithe-code-editor') as HTMLElement & {
+  value: string;
+  language: string;
+  focus: () => void;
+};
+
+// Set content
+editor.value = `function greet(name: string): string {
+  return \`Hello, \${name}!\`;
+}`;
+
+editor.language = 'typescript';
+
+// Listen for changes
+editor.addEventListener('aithe-input', (e: CustomEvent<{ value: string }>) => {
+  console.log('New value:', e.detail.value);
+});
+```

package/docs/api/display/label.md

@@ -0,0 +1,85 @@
+# AitheLabel / AitheLabel标签
+
+> Lightweight label component that renders a Markdown subset for descriptions and labels.
+> 轻量级标签组件，渲染 Markdown 子集用于描述和标签展示。
+
+## Supported Syntax / 支持的语法
+
+| Syntax         | Description (EN)                                               | Description (CN)                     |
+| -------------- | -------------------------------------------------------------- | ------------------------------------ |
+| `**text**`     | Bold                                                           | 加粗                                 |
+| `~~text~~`     | Strikethrough                                                  | 删除线                               |
+| `` `code` ``   | Inline code                                                    | 行内代码                             |
+| `[text](path)` | Internal link (external links blocked by default for security) | 站内链接（外链默认被阻止以确保安全） |
+| `:emoji_name:` | Emoji shortcode (e.g. `:smile:`, `:check:`)                    | 表情简码                             |
+| `:iconName:`   | Built-in icon via `<aithe-icon>`                               | 内置图标                             |
+
+> External URLs (http/https/ftp/absolute paths) are converted to plain text by default. Use `linkHooks` to customize this behavior.
+> 外部 URL（http/https/ftp/绝对路径）默认被转换为纯文本。可通过 `linkHooks` 自定义此行为。
+
+## Slots / 插槽
+
+| Name | Description (EN)                                          | Description (CN)                      |
+| ---- | --------------------------------------------------------- | ------------------------------------- |
+| —    | No slots; content is provided via the `content` property. | 无插槽；内容通过 `content` 属性提供。 |
+
+## Properties / 属性
+
+| Name      | Type                 | Default | Description (EN)                               | Description (CN)                      |
+| --------- | -------------------- | ------- | ---------------------------------------------- | ------------------------------------- |
+| content   | `string`             | `''`    | Markdown source text.                          | Markdown 源文本。                     |
+| linkHooks | `MarkdownLinkHook[]` | —       | Custom link hooks to intercept/transform URLs. | 自定义链接处理 hook，拦截或转换 URL。 |
+
+## Events / 事件
+
+| Name | Detail | Description (EN)  | Description (CN) |
+| ---- | ------ | ----------------- | ---------------- |
+| —    | —      | No custom events. | 无自定义事件。   |
+
+## CSS Custom Properties / CSS 自定义属性
+
+| Name                       | Default | Description (EN)                              | Description (CN)                 |
+| -------------------------- | ------- | --------------------------------------------- | -------------------------------- |
+| `--aithe-color-text`       | —       | Text color.                                   | 文本颜色。                       |
+| `--aithe-color-text-muted` | —       | Muted text color (strikethrough, blockquote). | 弱化文本颜色（删除线、引用块）。 |
+| `--aithe-color-bg-muted`   | —       | Code background color.                        | 代码背景颜色。                   |
+| `--aithe-primary-5`        | —       | Blockquote left border color.                 | 引用块左边框颜色。               |
+| `--aithe-primary-6`        | —       | Link color.                                   | 链接颜色。                       |
+| `--aithe-primary-7`        | —       | Inline code text color.                       | 行内代码文本颜色。               |
+| `--aithe-font-size-sm`     | `12px`  | Font size for `size="sm"`.                    | `size="sm"` 时的字号。           |
+| `--aithe-font-size-md`     | `14px`  | Font size for `size="md"`.                    | `size="md"` 时的字号。           |
+| `--aithe-font-size-lg`     | `16px`  | Font size for `size="lg"`.                    | `size="lg"` 时的字号。           |
+| `--aithe-font-family-mono` | —       | Monospace font for inline code.               | 行内代码的等宽字体。             |
+| `--aithe-space-2`          | —       | Spacing unit (blockquote/list margin).        | 间距单位（引用块/列表外边距）。  |
+| `--aithe-space-3`          | —       | Spacing unit (blockquote padding).            | 间距单位（引用块内边距）。       |
+| `--aithe-space-5`          | —       | Spacing unit (list padding-left).             | 间距单位（列表左内边距）。       |
+
+## Examples / 示例
+
+### Basic Usage / 基础用法
+
+```html
+<aithe-label content="**Bold** and `code`."></aithe-label>
+```
+
+### With Emoji and Icons / 带表情和图标
+
+```html
+<aithe-label content=":check: 已完成"></aithe-label>
+<aithe-label content=":smile: 很高兴见到你"></aithe-label>
+```
+
+### Size Variants / 尺寸变体
+
+```html
+<aithe-label content="Small label" size="sm"></aithe-label>
+<aithe-label content="Medium label" size="md"></aithe-label>
+<aithe-label content="Large label" size="lg"></aithe-label>
+```
+
+### With Custom Link Hooks / 自定义链接处理
+
+```javascript
+const label = document.querySelector('aithe-label');
+label.linkHooks = [(url) => (url.startsWith('/docs/') ? url : '')];
+```