@aithe/aithe-ui 26.2.2 → 26.3.1

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/desc-item.md

@@ -0,0 +1,57 @@
+# AitheDescItem / AitheDescItem 描述列表项
+
+> A single item in a description list, containing a label and a value. Supports filter expressions for content formatting.
+> 描述列表中的单个条目，包含标签和值。支持过滤器表达式对内容进行格式化。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                              | Description (CN)                 |
+| --------- | --------------------------------------------- | -------------------------------- |
+| label     | Custom label content.                         | 自定义标签内容。                 |
+| (default) | Value content (used when `content` is empty). | 值内容（`content` 为空时使用）。 |
+
+## Properties / 属性
+
+| Name       | Type                            | Default  | Description (EN)                                       | Description (CN)                     |
+| ---------- | ------------------------------- | -------- | ------------------------------------------------------ | ------------------------------------ |
+| label      | `string`                        | `''`     | Label text for the item.                               | 条目标签文本。                       |
+| span       | `number`                        | `1`      | Column span for this item.                             | 该条目占用的列数。                   |
+| rowspan    | `number`                        | `1`      | Row span for this item.                                | 该条目占用的行数。                   |
+| width      | `string`                        | `''`     | Width of the content cell.                             | 内容单元格宽度。                     |
+| labelAlign | `'left' \| 'center' \| 'right'` | `'left'` | Text alignment of the label.                           | 标签文本对齐方式。                   |
+| align      | `'left' \| 'center' \| 'right'` | `'left'` | Text alignment of the content.                         | 内容文本对齐方式。                   |
+| min-width  | `string`                        | `''`     | Minimum width of the content cell.                     | 内容单元格最小宽度。                 |
+| content    | `string`                        | `''`     | Content value. When set, used instead of slot content. | 内容值。设置后优先于 slot 内容使用。 |
+| filter     | `string`                        | `''`     | Filter expression for formatting the content value.    | 内容值的过滤器表达式。               |
+
+## CSS Parts / CSS 部分
+
+| Name    | Description (EN)            | Description (CN) |
+| ------- | --------------------------- | ---------------- |
+| item    | The item container.         | 条目容器。       |
+| label   | The label cell container.   | 标签单元格容器。 |
+| content | The content cell container. | 内容单元格容器。 |
+
+## Examples / 示例
+
+### 基本用法
+
+```html
+<aithe-desc-item label="Name">John Doe</aithe-desc-item>
+```
+
+### 使用 content 属性和过滤器
+
+```html
+<aithe-desc-item label="Amount" content="1234.5" filter="amount"></aithe-desc-item>
+<aithe-desc-item label="Created" content="2024-01-15" filter="date"></aithe-desc-item>
+```
+
+### 自定义标签插槽
+
+```html
+<aithe-desc-item>
+  <span slot="label" style="color: red;">Custom Label</span>
+  Custom value content
+</aithe-desc-item>
+```

package/docs/api/display/desc.md

@@ -0,0 +1,204 @@
+# AitheDesc / AitheDesc 描述列表
+
+> A description list component that displays key-value pairs in a structured table-like layout. Supports border mode, column count, title, extra actions, direction control, colspan, and rowspan.
+> 描述列表组件，以结构化的类表格布局展示键值对。支持边框模式、列数、标题、额外操作、方向控制、列合并和行合并。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/display/desc';
+import '@aithe/aithe-ui/components/display/desc-item';
+```
+
+## Description / 描述
+
+`AitheDesc` renders a structured key-value list using CSS Grid layout. It places `<aithe-desc-item>` children into a grid based on the `column` property and each item's `span` and `rowspan`. Supports border mode, vertical/horizontal direction, title, extra slot, and size variants.
+
+`AitheDesc` 使用 CSS Grid 布局渲染结构化的键值列表。根据 `column` 属性和每个条目的 `span`/`rowspan` 将 `<aithe-desc-item>` 子元素放置到网格中。支持边框模式、垂直/水平方向、标题、额外插槽和尺寸变体。
+
+## AitheDesc Properties / AitheDesc 属性
+
+| Name      | Type                              | Default      | Attribute  | Description (EN)                                                    | Description (CN)                   |
+| --------- | --------------------------------- | ------------ | ---------- | ------------------------------------------------------------------- | ---------------------------------- |
+| title     | `string`                          | `''`         | `title`    | Title text displayed in the header.                                 | 头部标题文本。                     |
+| column    | `number`                          | `1`          | `column`   | Number of columns for the description layout.                       | 描述布局的列数。                   |
+| border    | `boolean`                         | `false`      | `border`   | Whether to show border.                                             | 是否显示边框。                     |
+| direction | `'horizontal' \| 'vertical'`      | `'horizontal'` | `direction` | Layout direction: label left of content or label above content.     | 布局方向：标签在内容左侧或上方。   |
+| size      | `'sm' \| 'md' \| 'lg'`            | `'md'`       | `size`     | Size of the description list.                                       | 描述列表的尺寸。                   |
+| labelWidth | `string`                         | `''`         | `label-width` | Global label width. Falls back to individual item's label-width.  | 全局标签宽度，item 单独设置时优先。 |
+| showTitle | `boolean`                         | `true`       | `show-title` | Whether to show the title header.                                  | 是否显示标题头。                   |
+| maxRows   | `number`                          | `0`          | `max-rows`  | Maximum visible rows. 0 means no limit.                            | 最大可见行数，0 表示不限制。        |
+
+## AitheDescItem Properties / AitheDescItem 属性
+
+| Name       | Type                     | Default | Attribute   | Description (EN)                                    | Description (CN)               |
+| ---------- | ------------------------ | ------- | ----------- | --------------------------------------------------- | ------------------------------ |
+| label      | `string`                 | `''`    | `label`     | Label text for the item.                            | 条目标签文本。                 |
+| span       | `number`                 | `1`     | `span`      | Column span for this item.                          | 该条目占用的列数。             |
+| rowspan    | `number`                 | `1`     | `rowspan`   | Row span for this item.                             | 该条目占用的行数。             |
+| labelWidth | `string`                 | `''`    | `label-width` | Width of the label cell.                          | 标签单元格宽度。               |
+| width      | `string`                 | `''`    | `width`     | Width of the content cell.                          | 内容单元格宽度。               |
+| minWidth   | `string`                 | `''`    | `min-width` | Minimum width of the content cell.                  | 内容单元格最小宽度。           |
+| labelAlign | `'left' \| 'center' \| 'right'` | `'left'` | `label-align` | Text alignment of the label.                    | 标签文本对齐方式。             |
+| align      | `'left' \| 'center' \| 'right'` | `'left'` | `align`     | Text alignment of the content.                      | 内容文本对齐方式。             |
+
+## AitheDesc Slots / AitheDesc 插槽
+
+| Name    | Description (EN)                          | Description (CN)             |
+| ------- | ----------------------------------------- | ---------------------------- |
+| title   | Custom title content in the header.       | 头部自定义标题内容。         |
+| extra   | Extra action content in the header.       | 头部额外操作内容。           |
+| (default) | Description items (`<aithe-desc-item>`). | 描述条目（`<aithe-desc-item>`）。 |
+
+## AitheDescItem Slots / AitheDescItem 插槽
+
+| Name    | Description (EN)                          | Description (CN)             |
+| ------- | ----------------------------------------- | ---------------------------- |
+| label   | Custom label content.                     | 自定义标签内容。             |
+| (default) | Value content.                          | 值内容。                     |
+
+## AitheDesc Events / AitheDesc 事件
+
+| Name              | Detail | Cancelable | Description (EN)                       | Description (CN)            |
+| ----------------- | ------ | ---------- | -------------------------------------- | --------------------------- |
+| `aithe-desc-click` | `{}`   | No         | Fired when the description is clicked. | 点击描述列表时触发。        |
+
+## AitheDesc CSS Parts / AitheDesc CSS 部件
+
+| Name   | Description (EN)                    | Description (CN)     |
+| ------ | ----------------------------------- | -------------------- |
+| header | The header container.               | 头部容器。           |
+| body   | The body container.                 | 主体容器。           |
+| row    | A row container.                    | 行容器。             |
+
+## AitheDescItem CSS Parts / AitheDescItem CSS 部件
+
+| Name    | Description (EN)                    | Description (CN)     |
+| ------- | ----------------------------------- | -------------------- |
+| label   | The label cell container.           | 标签单元格容器。     |
+| content | The content cell container.         | 内容单元格容器。     |
+
+## Examples / 示例
+
+### Basic Usage / 基础用法
+
+```html
+<aithe-desc title="User Info">
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+  <aithe-desc-item label="Phone">+1 234 5678</aithe-desc-item>
+</aithe-desc>
+```
+
+### With Border / 带边框
+
+```html
+<aithe-desc title="User Info" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+  <aithe-desc-item label="Phone">+1 234 5678</aithe-desc-item>
+</aithe-desc>
+```
+
+### Column Span / 列合并
+
+```html
+<aithe-desc title="User Info" :column="2" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Address" :span="2">123 Main Street, New York, NY 10001</aithe-desc-item>
+</aithe-desc>
+```
+
+### Vertical Direction / 垂直方向
+
+```html
+<aithe-desc title="User Info" direction="vertical" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+</aithe-desc>
+```
+
+### With Extra Slot / 带额外操作
+
+```html
+<aithe-desc title="User Info" border>
+  <span slot="extra"><aithe-button size="sm">Edit</aithe-button></span>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+</aithe-desc>
+```
+
+### Size Variants / 尺寸变体
+
+```html
+<aithe-desc title="Small" size="sm" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+</aithe-desc>
+<aithe-desc title="Large" size="lg" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+</aithe-desc>
+```
+
+### Column Config / 列数配置
+
+```html
+<aithe-desc title="2 Columns" :column="2" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+  <aithe-desc-item label="Phone">+1 234 5678</aithe-desc-item>
+</aithe-desc>
+```
+
+### Custom Label Width / 自定义标签宽度
+
+```html
+<aithe-desc title="Server Config" border label-width="120px">
+  <aithe-desc-item label="Server Name">Production-Web-01</aithe-desc-item>
+  <aithe-desc-item label="IP Address">192.168.1.100</aithe-desc-item>
+  <aithe-desc-item label="Memory">64 GB DDR5</aithe-desc-item>
+</aithe-desc>
+```
+
+### Row Span / 行合并
+
+```html
+<aithe-desc title="User Profile" border>
+  <aithe-desc-item label="Name">Zhang Wei</aithe-desc-item>
+  <aithe-desc-item label="Age">28</aithe-desc-item>
+  <aithe-desc-item label="Gender">Male</aithe-desc-item>
+  <aithe-desc-item label="Phone">+86 138 0000 1234</aithe-desc-item>
+  <aithe-desc-item label="Email">zhangwei@example.com</aithe-desc-item>
+  <aithe-desc-item label="Address" :span="2" rowspan="2">No. 123, Chang'an Avenue, Haidian District, Beijing</aithe-desc-item>
+  <aithe-desc-item label="Position">Senior Engineer</aithe-desc-item>
+  <aithe-desc-item label="Department">Frontend Team</aithe-desc-item>
+</aithe-desc>
+```
+
+### Hide Title / 隐藏标题
+
+```html
+<aithe-desc title="Hidden Title" show-title="false" border>
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+</aithe-desc>
+```
+
+### Max Rows / 限制行数
+
+```html
+<aithe-desc title="Limited View" border max-rows="2">
+  <aithe-desc-item label="Name">John Doe</aithe-desc-item>
+  <aithe-desc-item label="Age">30</aithe-desc-item>
+  <aithe-desc-item label="Email">john@example.com</aithe-desc-item>
+  <aithe-desc-item label="Phone">+1 234 5678</aithe-desc-item>
+  <aithe-desc-item label="Address">123 Main Street</aithe-desc-item>
+</aithe-desc>
+```

package/docs/api/display/detail-box.md

@@ -0,0 +1,75 @@
+# AitheDetailBox / AitheDetailBox 详情记录
+
+> Two-column detail record display with left metadata and right actions. Designed for rich detail views. All content is provided via named slots.
+> 双列详情记录展示，左侧元数据、右侧操作。设计用于丰富的详情视图。所有内容通过具名插槽提供。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/data/detail-box';
+```
+
+## Description / 描述
+
+`<aithe-detail-box>` renders a two-column layout: the left column contains select, checkbox, name, tags, status, and expandable content; the right column contains actions. Designed for detailed record views where rich metadata and actions are displayed side by side. All content is provided via named slots.
+
+`<aithe-detail-box>` 渲染双列布局：左列包含 select、checkbox、name、tags、status 和可展开内容；右列包含操作。设计用于详细记录视图，丰富的元数据和操作并排显示。所有内容通过具名插槽提供。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                                                    | Description (CN)               |
+| --------- | ------------------------------------------------------------------- | ------------------------------ |
+| select    | Selection control region (e.g. radio).                              | 选择控件区域（如单选框）。     |
+| checkbox  | Checkbox region.                                                    | 复选框区域。                   |
+| name      | Primary label / title region.                                       | 主标签/标题区域。              |
+| tags      | Tags region.                                                        | 标签区域。                     |
+| status    | Status indicator region.                                            | 状态指示器区域。               |
+| actions   | Action buttons region.                                              | 操作按钮区域。                 |
+| content   | Expandable content region.                                          | 可展开的内容区域。             |
+| (default) | Default slot, rendered inside the content region.                   | 默认插槽，渲染在内容区域内。   |
+
+## CSS Parts / CSS 部件
+
+| Name    | Description (EN)                    | Description (CN)     |
+| ------- | ----------------------------------- | -------------------- |
+| select  | The select region container.        | 选择区域容器。       |
+| checkbox| The checkbox region container.      | 复选框区域容器。     |
+| name    | The name region container.          | 名称区域容器。       |
+| tags    | The tags region container.          | 标签区域容器。       |
+| status  | The status region container.        | 状态区域容器。       |
+| actions | The actions region container.       | 操作区域容器。       |
+| content | The content region container.       | 内容区域容器。       |
+
+## Properties / 属性
+
+Inherits all properties from `AitheMiniBox`. See [AitheMiniBox](mini-box.md) for details.
+
+## Events / 事件
+
+Inherits all events from `AitheMiniBox`. See [AitheMiniBox](mini-box.md) for details.
+
+## Usage / 用法
+
+### Basic / 基础用法
+
+```html
+<aithe-detail-box>
+  <aithe-profile slot="name" title="Project Alpha" desc="Frontend application" icon="app"></aithe-profile>
+  <span slot="tags"><aithe-tag>frontend</aithe-tag> <aithe-tag>design</aithe-tag></span>
+  <span slot="status">Active</span>
+  <span slot="content">A front-end design system built with Lit and TypeScript.</span>
+</aithe-detail-box>
+```
+
+### With Actions / 带操作按钮
+
+```html
+<aithe-detail-box>
+  <aithe-profile slot="name" title="Project Alpha" desc="Frontend application" icon="app"></aithe-profile>
+  <span slot="status">Active</span>
+  <span slot="actions">
+    <aithe-button size="sm">Edit</aithe-button>
+    <aithe-button size="sm" variant="danger">Delete</aithe-button>
+  </span>
+</aithe-detail-box>
+```