@aithe/aithe-ui 26.2.3 → 26.3.2

package/docs/api/display/autoview.md

@@ -0,0 +1,277 @@
+# AitheAutoView / AitheAutoView 自动视图
+
+> JSON-driven read-only detail view, the display-only counterpart of `<aithe-autoform>`. Shares the same `FormFieldConfig` model, rendering field values as a structured description list with type-aware read-only renderers.
+> JSON 驱动的只读详情视图，`<aithe-autoform>` 的只读镜像。共用同一份 `FormFieldConfig` 模型，将字段值渲染为结构化描述列表，内置类型感知的只读渲染器。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/display/autoview';
+```
+
+## Description / 描述
+
+`AitheAutoView` is a thin adapter built on top of `<aithe-desc>`. It parses a `fields` JSON array (same model as autoform) and a `data` object, resolves dependency-based show/hide rules, transforms values per control type, and injects type-aware read-only content into `<aithe-desc-item>` slots.
+
+Built-in renderers cover common control types: `input`/`textarea` (plain text), `select`/`radio` (label lookup), `checkbox` (tag list), `switch` (yes/no badge), `date-picker`/`time-picker` (formatted date), `color-picker` (color chip + hex), `rate`/`slider` (plain number). Custom renderers can be registered via `ViewRegistry`.
+
+`AitheAutoView` 是基于 `<aithe-desc>` 的轻量适配器。解析 `fields` JSON 数组（与 autoform 同模型）和 `data` 对象，解析依赖联动显隐规则，按控件类型转换值，将类型感知的只读内容注入 `<aithe-desc-item>` 的 slot。
+
+内置渲染器覆盖常见控件类型：`input`/`textarea`（纯文本）、`select`/`radio`（label 反查）、`checkbox`（标签组）、`switch`（是/否徽章）、`date-picker`/`time-picker`（格式化日期）、`color-picker`（色块+色值）、`rate`/`slider`（纯数值）。可通过 `ViewRegistry` 注册自定义渲染器。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                                              | Description (CN)                          |
+| --------- | ------------------------------------------------------------- | ----------------------------------------- |
+| title     | Custom title content (passed through to desc).                | 自定义标题内容（透传给 desc）。           |
+| extra     | Extra action content in the header (passed through to desc).  | 头部额外操作内容（透传给 desc）。         |
+
+## Properties / 属性
+
+| Name             | Type                              | Default          | Attribute          | Description (EN)                                                                                                           | Description (CN)                                                                                          |
+| ---------------- | --------------------------------- | ---------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| fields           | `string`                          | `'[]'`           | `fields`           | JSON string of field configurations. Same model as autoform's `fields`.                                                   | 字段配置的 JSON 字符串，与 autoform 的 `fields` 模型一致。                                                 |
+| data             | `Object \| string`                | `{}`             | `.data`            | Display data object keyed by field name. Supports object or JSON string.                                                   | 展示数据对象，按字段名取值。支持对象或 JSON 字符串。                                                      |
+| column           | `number`                          | `1`              | `column`           | Number of columns in the grid layout. Passed to desc.                                                                      | 网格列数，透传给 desc。                                                                                    |
+| border           | `boolean`                         | `true`           | `border`           | Whether to show full borders (outer frame + cell separators). Equivalent to `border-style="full"`.                         | 是否显示完整边框（外框+单元格分隔线），等同 `border-style="full"`。                                       |
+| border-style     | `'none' \| 'full' \| 'row'`       | `'none'`         | `border-style`     | Border style: `none` (no borders), `full` (outer + all cell separators), `row` (row separators only). Passed to desc.      | 边框样式：`none`（无边框）、`full`（外框+所有单元格分隔线）、`row`（仅行分隔线），透传给 desc。            |
+| label-background | `'filled' \| 'none'`              | `'filled'`       | `label-background` | Label background style: `filled` (default gray) or `none` (transparent). Passed to desc.                                   | 标签背景样式：`filled`（默认灰底）或 `none`（透明），透传给 desc。                                        |
+| direction        | `'horizontal' \| 'vertical'`      | `'horizontal'`   | `direction`        | Layout direction. Passed to desc.                                                                                          | 布局方向，透传给 desc。                                                                                    |
+| label-width      | `string`                          | `'150px'`        | `label-width`      | Label cell width. Passed to desc.                                                                                          | 标签单元格宽度，透传给 desc。                                                                              |
+| size             | `'sm' \| 'md' \| 'lg'`            | `'md'`           | `size`             | Size preset. Passed to desc.                                                                                               | 尺寸规格，透传给 desc。                                                                                    |
+| title            | `string`                          | `''`             | `title`            | Title text in the header. Passed to desc.                                                                                  | 头部标题文本，透传给 desc。                                                                                |
+| show-title       | `boolean`                         | `true`           | `show-title`       | Whether to show the title header. When false, the header row is hidden even if title or extra slot is set. Passed to desc. | 是否显示标题头。为 false 时隐藏标题行，即使设置了 title 或 extra slot 也不显示，透传给 desc。              |
+| max-rows         | `number`                          | `0`              | `max-rows`         | Max visible rows. 0 means no limit. Passed to desc.                                                                        | 最大可见行数，0 表示不限制，透传给 desc。                                                                  |
+| empty-text       | `string`                          | `''`             | `empty-text`       | Global empty value placeholder. Falls back to i18n key `form.autoView.empty` (default `--`).                               | 全局空值占位文本，回退到 i18n 键 `form.autoView.empty`（默认 `--`）。                                      |
+
+## Methods / 方法
+
+| Name      | Parameters | Return                  | Description (EN)                                          | Description (CN)                          |
+| --------- | ---------- | ----------------------- | --------------------------------------------------------- | ----------------------------------------- |
+| getValues | —          | `Record<string, unknown>` | Returns the values of all visible fields from `data`.   | 返回所有可见字段在 `data` 中的值。        |
+
+## Events / 事件
+
+| Name             | Detail                        | Cancelable | Description (EN)                                                      | Description (CN)                                  |
+| ---------------- | ----------------------------- | ---------- | --------------------------------------------------------------------- | ------------------------------------------------- |
+| `aithe-view-ready` | `{ values }`                | No         | Emitted after initial render with current visible field values.       | 初始渲染完成后触发，携带当前可见字段值。          |
+
+## Supported Field Types / 支持的字段类型
+
+| Type           | Read-only Rendering (EN)                                    | 只读渲染方式 (CN)                |
+| -------------- | ----------------------------------------------------------- | -------------------------------- |
+| input          | Plain text.                                                 | 纯文本。                         |
+| textarea       | Plain text.                                                 | 纯文本。                         |
+| number         | Plain text (supports `filter`).                             | 纯文本（支持 `filter`）。        |
+| select         | Label lookup from `options` by value.                       | 从 `options` 中按值反查 label。  |
+| radio          | Label lookup from `options` by value.                       | 从 `options` 中按值反查 label。  |
+| checkbox       | Tag list (`<aithe-tag>`) from `options` by value array.     | 标签组（`<aithe-tag>`），按值数组反查。 |
+| switch         | Yes/No badge (`<aithe-tag>` with success/default variant).  | 是/否徽章（`<aithe-tag>`，success/default 变体）。 |
+| date-picker    | Formatted date (`date yyyy-MM-dd` filter).                  | 格式化日期（`date yyyy-MM-dd` 过滤器）。 |
+| time-picker    | Formatted date.                                             | 格式化日期。                     |
+| color-picker   | Color chip + hex text.                                      | 色块 + 色值文本。                |
+| rate           | Plain number.                                               | 纯数值。                         |
+| slider         | Plain number.                                               | 纯数值。                         |
+| _(custom)_     | Any type registered via `ViewRegistry`.                     | 通过 `ViewRegistry` 注册的类型。 |
+
+## Field Configuration / 字段配置
+
+Each field in the `fields` JSON array supports the following properties (all extending `FormFieldConfig`):
+
+`fields` JSON 数组中每个字段支持以下属性（均扩展自 `FormFieldConfig`）：
+
+| Property     | Type       | Required | Description (EN)                                                                 | Description (CN)                                              |
+| ------------ | ---------- | -------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| name         | `string`   | yes      | Field name, used to look up value in `data`.                                     | 字段名称，用于在 `data` 中取值。                              |
+| type         | `string`   | yes      | Field control type (see table above).                                            | 字段控件类型（见上表）。                                      |
+| label        | `string`   | no       | Label text displayed in the label cell.                                          | 标签单元格中显示的文本。                                      |
+| options      | `array`    | no       | Options for select/radio/checkbox. Each: `{ label, id }`.                        | 选择类控件选项，每项：`{ label, id }`。                       |
+| dft          | `string`   | no       | Default value when field is absent in `data`.                                    | 字段在 `data` 中缺失时的缺省值。                              |
+| filter       | `string`   | no       | Filter expression for value formatting (e.g. `"date yyyy-MM-dd"`, `"amount"`).   | 值过滤器表达式（如 `"date yyyy-MM-dd"`、`"amount"`）。        |
+| emptyText    | `string`   | no       | Per-field empty placeholder; falls back to component's `empty-text`.             | 单字段空值占位文本，回退到组件的 `empty-text`。               |
+| span         | `number`   | no       | Column span in the grid. Default 1.                                              | 网格中占用的列数，默认 1。                                    |
+| rowspan      | `number`   | no       | Row span in the grid. Default 1.                                                 | 网格中占用的行数，默认 1。                                    |
+| align        | `string`   | no       | Content text alignment: `'left'` / `'center'` / `'right'`.                       | 内容文本对齐方式：`'left'` / `'center'` / `'right'`。         |
+| hideLabel    | `boolean`  | no       | Whether to hide the label cell.                                                  | 是否隐藏标签单元格。                                          |
+| dependencies | `string[]` | no       | Names of fields this field depends on (for show/hide rules).                     | 当前字段依赖的字段名称列表（用于显隐规则）。                  |
+| rules        | `FormRule[]` | no     | Dependency rules. Only `show`/`hide` types are honored in read-only mode.        | 依赖联动规则。只读模式下仅生效 `show`/`hide`。                |
+
+## Custom View Registry / 自定义视图注册表
+
+The autoview supports registering custom read-only renderers via the `ViewRegistry` class, mirroring `FormRegistry`. This allows extending the view with any custom rendering logic without modifying the autoview source.
+
+autoview 支持通过 `ViewRegistry` 类注册自定义只读渲染器，与 `FormRegistry` 对称。无需修改 autoview 源码即可扩展视图。
+
+### ViewRegistry Static Methods / ViewRegistry 静态方法
+
+| Method                        | Description (EN)                       | Description (CN)               |
+| ----------------------------- | -------------------------------------- | ------------------------------ |
+| `ViewRegistry.register(def)`  | Register a custom view renderer.       | 注册自定义只读渲染器。         |
+| `ViewRegistry.unregister(type)` | Unregister a view type.              | 注销视图类型。                 |
+| `ViewRegistry.get(type)`      | Get a registered view definition.      | 获取已注册的视图定义。         |
+| `ViewRegistry.has(type)`      | Check if a view type is registered.    | 检查视图类型是否已注册。       |
+| `ViewRegistry.types()`        | Get all registered view type names.    | 获取所有已注册的视图类型名。   |
+
+### ViewControlDefinition / 视图控件定义
+
+| Property | Type                       | Required | Description (EN)                                     | Description (CN)                        |
+| -------- | -------------------------- | -------- | ---------------------------------------------------- | --------------------------------------- |
+| type     | `string`                   | yes      | Unique type name matching the `type` in field config. | 唯一类型名称，匹配字段配置中的 type。   |
+| render   | `(ctx) => TemplateResult`  | yes      | Renderer function returning the read-only template.  | 返回只读模板的渲染函数。                |
+
+### ViewRenderContext / 渲染上下文
+
+| Property   | Type             | Description (EN)                                                                 | Description (CN)                                              |
+| ---------- | ---------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| value      | `unknown`        | Transformed value (boolean for switch, number for number, string[] for checkbox). | 转换后的值（switch 为布尔、number 为数值、checkbox 为字符串数组）。 |
+| rawValue   | `string`         | Raw string value as stored in `data`.                                            | `data` 中的原始字符串值。                                     |
+| options    | `FormItemOption[]` | Options for select/radio/checkbox controls.                                    | 选择类控件的选项。                                            |
+| field      | `ViewFieldConfig` | Full field configuration.                                                       | 完整字段配置。                                                |
+| emptyText  | `string`         | Resolved empty placeholder text.                                                 | 解析后的空值占位文本。                                        |
+
+### Register Example / 注册示例
+
+```ts
+import { ViewRegistry } from '@aithe/aithe-ui';
+import { html } from 'lit';
+
+ViewRegistry.register({
+  type: 'status-badge',
+  render: (ctx) => html`
+    <aithe-tag variant=${ctx.value === 'active' ? 'success' : 'default'} size="sm">
+      ${ctx.rawValue || ctx.emptyText}
+    </aithe-tag>
+  `,
+});
+```
+
+Then use it in the fields JSON:
+
+```json
+{
+  "name": "status",
+  "type": "status-badge",
+  "label": "Status"
+}
+```
+
+## Dependency & Visibility / 依赖联动与显隐
+
+The autoview supports field dependency linkage through the same JSON configuration as autoform. When a dependency field's value changes, the dependent field re-evaluates its `show`/`hide` rules to determine visibility.
+
+autoview 支持与 autoform 相同的 JSON 配置实现字段依赖联动。当被依赖字段的值变化时，依赖字段重新计算 `show`/`hide` 规则决定可见性。
+
+> **Note / 注意**: In read-only mode, only `show` and `hide` rule types are honored. `disable`/`enable`/`clear`/`update` rules are ignored.
+> 只读模式下仅生效 `show`/`hide` 规则，`disable`/`enable`/`clear`/`update` 规则被忽略。
+
+### Show/Hide Example / 显隐示例
+
+```json
+[
+  {
+    "name": "hasCar",
+    "label": "Has a car?",
+    "type": "switch"
+  },
+  {
+    "name": "carModel",
+    "label": "Car Model",
+    "type": "input",
+    "dependencies": ["hasCar"],
+    "rules": [{ "type": "show", "condition": "hasCar === true" }]
+  }
+]
+```
+
+## Examples / 示例
+
+### Basic Usage / 基础用法
+
+```html
+<aithe-autoview
+  fields='[
+    {"name":"username","type":"input","label":"Username"},
+    {"name":"email","type":"input","label":"Email","inputType":"email"},
+    {"name":"bio","type":"textarea","label":"Bio","span":2}
+  ]'
+  .data=${{username:"John Doe",email:"john@example.com",bio:"Frontend engineer."}}
+  column="2"
+  border
+></aithe-autoview>
+```
+
+### Selection Display / 选择类展示
+
+```html
+<aithe-autoview
+  fields='[
+    {"name":"role","type":"select","label":"Role","options":[{"label":"Admin","id":"admin"},{"label":"Editor","id":"editor"}]},
+    {"name":"skills","type":"checkbox","label":"Skills","options":[{"label":"TypeScript","id":"ts"},{"label":"Go","id":"go"}]},
+    {"name":"notifications","type":"switch","label":"Notifications"}
+  ]'
+  .data=${{role:"editor",skills:["ts","go"],notifications:true}}
+  column="2"
+  border
+></aithe-autoview>
+```
+
+### Border Styles / 边框样式
+
+```html
+<!-- No border, no label background: clean style -->
+<aithe-autoview border-style="none" label-background="none" column="2"></aithe-autoview>
+
+<!-- Full border with filled labels -->
+<aithe-autoview border-style="full" label-background="filled" column="2"></aithe-autoview>
+
+<!-- Row separators only, no outer frame -->
+<aithe-autoview border-style="row" label-background="none" column="2"></aithe-autoview>
+```
+
+### Hidden Title / 隐藏标题头
+
+Set `show-title="false"` to hide the header row entirely, even when `title` or the `extra` slot is provided. Useful for embedding autoview inside another container that already provides a heading.
+
+设置 `show-title="false"` 可彻底隐藏标题行，即使设置了 `title` 或 `extra` slot 也不显示。适用于将 autoview 嵌入已有标题的容器中。
+
+```html
+<!-- Header row is hidden, title and extra slot are ignored -->
+<aithe-autoview
+  title="Employee Profile"
+  show-title="false"
+  column="2"
+  border
+></aithe-autoview>
+```
+
+### Dependency Visibility / 联动显隐
+
+```html
+<aithe-autoview
+  fields='[
+    {"name":"province","type":"select","label":"Province","options":[{"label":"Beijing","id":"BJ"},{"label":"Shanghai","id":"SH"}]},
+    {"name":"city","type":"select","label":"City","dependencies":["province"],"rules":[{"type":"show","condition":"province !== ''"}]},
+    {"name":"hasCar","type":"switch","label":"Has a car?"},
+    {"name":"carModel","type":"input","label":"Car Model","dependencies":["hasCar"],"rules":[{"type":"show","condition":"hasCar === true"}]}
+  ]'
+  .data=${{province:"BJ",city:"Haidian",hasCar:true,carModel:"Tesla Model 3"}}
+  column="2"
+  border
+></aithe-autoview>
+```
+
+### Empty Values / 空值展示
+
+```html
+<aithe-autoview
+  fields='[
+    {"name":"username","type":"input","label":"Username"},
+    {"name":"role","type":"select","label":"Role","options":[{"label":"Admin","id":"admin"}]},
+    {"name":"active","type":"switch","label":"Active"}
+  ]'
+  .data=${{username:"",role:"",active:false}}
+  column="2"
+  border
+  empty-text="—"
+></aithe-autoview>
+```

package/docs/api/display/box.md

@@ -0,0 +1,66 @@
+# AitheBox / AitheBox 记录容器
+
+> The Box component family provides structured record display layouts. `AitheMiniBox` serves as the base class, providing region-based layout with named slots. The box only defines layout structure — all content is provided via named slots, with no data binding.
+> Box 组件族提供结构化记录展示布局。`AitheMiniBox` 作为基类，提供基于区域的布局和具名插槽。Box 只定义布局结构——所有内容通过具名插槽提供，无数据绑定。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/display/mini-box';
+// or
+import '@aithe/aithe-ui/components/display/brief-box';
+// or
+import '@aithe/aithe-ui/components/display/detail-box';
+```
+
+## Description / 描述
+
+The Box component family includes three variants, each implementing a distinct layout strategy:
+
+- `<aithe-mini-box>` — single horizontal row (compact list view)
+- `<aithe-brief-box>` — three rows with description and vertically spanning checkbox/actions
+- `<aithe-detail-box>` — two-column split with left metadata and right actions
+
+All content is provided via named slots. The box only defines layout structure — it does not bind data.
+
+Box 组件族包含三种变体，每种实现不同的布局策略：
+
+- `<aithe-mini-box>` — 单行水平布局（紧凑列表视图）
+- `<aithe-brief-box>` — 三行布局，含描述和垂直贯穿的 checkbox/actions
+- `<aithe-detail-box>` — 左右分栏布局，左侧元数据、右侧操作
+
+所有内容通过具名插槽提供。Box 只定义布局结构——不绑定数据。
+
+## Common 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.                   | 默认插槽，渲染在内容区域内。   |
+
+## Common Properties / 公共属性
+
+| Name     | Type      | Default | Attribute  | Description (EN)                           | Description (CN)          |
+| -------- | --------- | ------- | ---------- | ------------------------------------------ | ------------------------- |
+| selected | `boolean` | `false` | `selected` | Whether the box is selected.               | box 是否被选中。          |
+| expanded | `boolean` | `false` | `expanded` | Whether the content region is expanded.    | 内容区域是否展开。        |
+
+## Common Events / 公共事件
+
+| Name              | Detail | Cancelable | Description (EN)               | Description (CN)        |
+| ----------------- | ------ | ---------- | ------------------------------ | ----------------------- |
+| `aithe-box-click` | `{}`   | No         | Fired when the box is clicked. | 点击 box 时触发。       |
+
+## Variants / 变体
+
+See the individual variant pages for layout details and usage examples:
+
+- [AitheMiniBox](mini-box.md)
+- [AitheBriefBox](brief-box.md)
+- [AitheDetailBox](detail-box.md)

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

@@ -0,0 +1,73 @@
+# AitheBriefBox / AitheBriefBox 简要记录
+
+> Three-row brief record display with description and vertically spanning checkbox/actions regions. All content is provided via named slots.
+> 三行简要记录展示，含描述行和垂直贯穿的 checkbox/actions 区域。所有内容通过具名插槽提供。
+
+## Import / 引入
+
+```ts
+import '@aithe/aithe-ui/components/data/brief-box';
+```
+
+## Description / 描述
+
+`<aithe-brief-box>` renders a three-row layout: the first row contains select, name, tags, and status; the second row shows the content; the third row is the expandable default slot region. The checkbox and actions regions span vertically across all rows. All content is provided via named slots.
+
+`<aithe-brief-box>` 渲染三行布局：第一行包含 select、name、tags 和 status；第二行显示内容；第三行是可展开的默认插槽区域。checkbox 和 actions 区域垂直贯穿所有行。所有内容通过具名插槽提供。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                                                    | Description (CN)               |
+| --------- | ------------------------------------------------------------------- | ------------------------------ |
+| select    | Selection control region (e.g. radio).                              | 选择控件区域（如单选框）。     |
+| checkbox  | Checkbox region (spans vertically).                                 | 复选框区域（垂直贯穿）。       |
+| name      | Primary label / title region.                                       | 主标签/标题区域。              |
+| tags      | Tags region.                                                        | 标签区域。                     |
+| status    | Status indicator region.                                            | 状态指示器区域。               |
+| actions   | Action buttons region (spans vertically).                           | 操作按钮区域（垂直贯穿）。     |
+| 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-brief-box>
+  <aithe-profile slot="name" title="Project Alpha" desc="Frontend application" icon="app"></aithe-profile>
+  <span slot="status">Active</span>
+  <span slot="tags"><aithe-tag>frontend</aithe-tag></span>
+  <span slot="actions"><aithe-button size="sm">Edit</aithe-button></span>
+</aithe-brief-box>
+```
+
+### With Checkbox / 带复选框
+
+```html
+<aithe-brief-box selectable>
+  <aithe-profile slot="name" title="Project Alpha" desc="Frontend application" icon="app"></aithe-profile>
+  <span slot="status">Active</span>
+  <span slot="tags"><aithe-tag>frontend</aithe-tag></span>
+  <span slot="actions"><aithe-button size="sm">Edit</aithe-button></span>
+</aithe-brief-box>
+```

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>
+```