@aithe/aithe-ui 26.2.2 → 26.2.3

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

@@ -0,0 +1,110 @@
+# AitheMarkdownEditor / AitheMarkdownEditor编辑器
+
+> Markdown editor component built on top of `aithe-code-editor`, with a live preview pane.
+> 基于 `aithe-code-editor` 定制的 Markdown 编辑器，集成实时预览面板。
+
+## Overview / 概述
+
+`aithe-markdown-editor` wraps `aithe-code-editor` with language fixed to `"markdown"`. It provides:
+
+- A code editor pane for writing Markdown
+- A live preview pane that renders Markdown as styled HTML
+- Configurable preview update strategy (auto or throttled)
+- Toolbar with toggle for code-only / code+preview modes
+
+`aithe-markdown-editor` 封装了 `aithe-code-editor`，语言固定为 `"markdown"`。提供：
+
+- 用于编写 Markdown 的代码编辑面板
+- 实时预览面板，将 Markdown 渲染为带样式的 HTML
+- 可配置的预览刷新策略（自动或节流）
+- 工具栏，支持纯代码 / 代码+预览模式切换
+
+## Slots / 插槽
+
+| Name | Description (EN)                                        | Description (CN)                    |
+| ---- | ------------------------------------------------------- | ----------------------------------- |
+| —    | No slots; content is provided via the `value` property. | 无插槽；内容通过 `value` 属性提供。 |
+
+## Properties / 属性
+
+| Name                  | Type              | Default  | Description (EN)                                                       | Description (CN)                            |
+| --------------------- | ----------------- | -------- | ---------------------------------------------------------------------- | ------------------------------------------- |
+| value                 | `string`          | `''`     | Markdown source text.                                                  | Markdown 源文本。                           |
+| showToolbar           | `boolean`         | `false`  | Whether the toolbar is visible.                                        | 是否显示工具栏。                            |
+| showTheme             | `boolean`         | `true`   | Whether to show the theme picker in toolbar.                           | 是否在工具栏中显示主题选择器。              |
+| lineNumbers           | `boolean`         | `true`   | Whether to show line numbers.                                          | 是否显示行号。                              |
+| readonly              | `boolean`         | `false`  | Whether the editor is read-only.                                       | 是否只读。                                  |
+| placeholder           | `string`          | `''`     | Placeholder text when the editor is empty.                             | 编辑器为空时的占位文本。                    |
+| showLanguage          | `boolean`         | `false`  | Whether to show the language selector (typically hidden for markdown). | 是否显示语言选择器（Markdown 时通常隐藏）。 |
+| showFullscreen        | `boolean`         | `true`   | Whether to show the fullscreen button.                                 | 是否显示全屏按钮。                          |
+| showCopy              | `boolean`         | `true`   | Whether to show the copy button.                                       | 是否显示复制按钮。                          |
+| showLineNumbersToggle | `boolean`         | `true`   | Whether to show the line numbers toggle button.                        | 是否显示行号切换按钮。                      |
+| previewStrategy       | `PreviewStrategy` | `'auto'` | Preview update strategy. See below.                                    | 预览刷新策略。详见下方。                    |
+
+### Preview Strategy / 预览刷新策略
+
+The `previewStrategy` property controls how often the preview pane re-renders:
+
+| Value                                  | Behavior                                                                          |
+| -------------------------------------- | --------------------------------------------------------------------------------- |
+| `'auto'`                               | Re-render preview on every value change (default). 每次值变更都重新渲染（默认）。 |
+| `{ changeCount: 5 }`                   | Re-render only after every 5 value changes. 每 5 次变更后刷新。                   |
+| `{ updateSeconds: 2 }`                 | Re-render at most once every 2 seconds. 每 2 秒最多刷新一次。                     |
+| `{ changeCount: 5, updateSeconds: 2 }` | Both conditions must be met. 两个条件同时满足时才刷新。                           |
+
+## Events / 事件
+
+| Name        | Detail              | Description (EN)                         | Description (CN)           |
+| ----------- | ------------------- | ---------------------------------------- | -------------------------- |
+| aithe-input | `{ value: string }` | Emitted when the markdown value changes. | 当 Markdown 值变化时触发。 |
+
+## Examples / 示例
+
+### Basic Usage / 基础用法
+
+```html
+<aithe-markdown-editor value="# Hello" show-toolbar></aithe-markdown-editor>
+```
+
+### Readonly Mode / 只读模式
+
+```html
+<aithe-markdown-editor value="**Bold** text" readonly></aithe-markdown-editor>
+```
+
+### Without Line Numbers / 不显示行号
+
+```html
+<aithe-markdown-editor value="- item 1\n- item 2" line-numbers="false"></aithe-markdown-editor>
+```
+
+### With Throttled Preview / 带节流预览
+
+```html
+<aithe-markdown-editor
+  value="# Hello"
+  show-toolbar
+  preview-strategy='{"updateSeconds":1}'
+></aithe-markdown-editor>
+```
+
+### Custom Toolbar / 自定义工具栏
+
+```html
+<aithe-markdown-editor
+  value="# Hello"
+  show-toolbar
+  show-theme="false"
+  show-copy="false"
+  show-fullscreen="false"
+></aithe-markdown-editor>
+```
+
+### Event Handling / 事件处理
+
+```javascript
+const editor = document.querySelector('aithe-markdown-editor');
+editor.addEventListener('aithe-input', (e) => {
+  console.log('Markdown content:', e.detail.value);
+});
+```

package/docs/api/display/markdown.md

@@ -1,29 +1,87 @@
 # AitheMarkdown / AitheMarkdown渲染器
 
-> Lightweight inline markdown renderer that converts markdown text to styled HTML.
-> 轻量级内联 Markdown 渲染器，将 Markdown 文本转换为带样式的 HTML。
+> Full-featured markdown renderer that converts GFM (GitHub Flavored Markdown) text to styled HTML.
+> 全功能 Markdown 渲染器，将 GFM Markdown 文本转换为带样式的 HTML。
+
+## Supported Syntax / 支持的语法
+
+| Syntax                        | Description (EN)                         | Description (CN)       |
+| ----------------------------- | ---------------------------------------- | ---------------------- |
+| `# ` `## ` `### ` … `###### ` | ATX headings                             | ATX 标题               |
+| `===` / `---` underline       | Setext headings                          | 下划线标题             |
+| `---` `***` `___`             | Thematic break / horizontal rule         | 分隔线                 |
+| `` ``` ```` / `~~~`           | Fenced code blocks                       | 围栏代码块             |
+| `\| col1 \| col2 \|`          | Tables                                   | 表格                   |
+| `> text`                      | Blockquote                               | 引用块                 |
+| `- item` / `* item`           | Unordered list                           | 无序列表               |
+| `1. item`                     | Ordered list                             | 有序列表               |
+| `- [ ] task` / `- [x] done`   | Task list                                | 任务列表               |
+| `**bold**`                    | Bold                                     | 加粗                   |
+| `*italic*`                    | Italic                                   | 斜体                   |
+| `` `code` ``                  | Inline code                              | 行内代码               |
+| `~~text~~`                    | Strikethrough                            | 删除线                 |
+| `[text](url)`                 | Link (external links blocked by default) | 链接（外链默认被阻止） |
+| `![alt](url)`                 | Image                                    | 图片                   |
+| `<url>`                       | Autolink                                 | 自动链接               |
+
+> 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` 属性提供。 |
+| 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` | `''` | Raw markdown source string. | Markdown 源文本字符串。 |
-| theme | `'default' | 'article'` | `'default'` | Visual theme preset. | 视觉主题预设。 |
+| Name      | Type                 | Default | Description (EN)                               | Description (CN)                      |
+| --------- | -------------------- | ------- | ---------------------------------------------- | ------------------------------------- |
+| content   | `string`             | `''`    | Raw markdown source string.                    | Markdown 源文本字符串。               |
+| linkHooks | `MarkdownLinkHook[]` | —       | Custom link hooks to intercept/transform URLs. | 自定义链接处理 hook，拦截或转换 URL。 |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| — | — | No custom 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 (blockquote).  | 弱化文本颜色（引用块）。 |
+| `--aithe-color-bg-muted`   | —       | Code / table header background. | 代码/表头背景颜色。      |
+| `--aithe-color-border`     | —       | Table border color.             | 表格边框颜色。           |
+| `--aithe-primary-5`        | —       | Blockquote left border color.   | 引用块左边框颜色。       |
+| `--aithe-primary-6`        | —       | Link color.                     | 链接颜色。               |
+| `--aithe-primary-7`        | —       | Inline code text color.         | 行内代码文本颜色。       |
+| `--aithe-font-family-mono` | —       | Monospace font for inline code. | 行内代码的等宽字体。     |
+| `--aithe-container-radius` | `6px`   | Image border radius.            | 图片圆角。               |
+| `--aithe-space-2`          | —       | Table cell padding.             | 表格单元格内边距。       |
+| `--aithe-space-3`          | —       | Heading / blockquote margin.    | 标题/引用块外边距。      |
+| `--aithe-space-4`          | —       | Block-level element spacing.    | 块级元素间距。           |
 
 ## Examples / 示例
 
+### Basic Usage / 基础用法
+
+### With Tables / 带表格
+
+```html
+<aithe-markdown content="| Name | Age |\n|------|-----|\n| Alice | 25 |"></aithe-markdown>
+```
+
+### With Task Lists / 带任务列表
+
 ```html
-<aithe-markdown content="# Hello\n**Bold** text and `code`." theme="article"></aithe-markdown>
-```
+<aithe-markdown content="- [x] Done\n- [ ] Pending"></aithe-markdown>
+```
+
+### With Custom Link Hooks / 自定义链接处理
+
+```javascript
+const md = document.querySelector('aithe-markdown');
+md.linkHooks = [(url) => (url.startsWith('https://internal.example.com') ? url : '')];
+```

package/docs/api/form/autoform.md

@@ -0,0 +1,268 @@
+# AitheAutoform / AitheAutoform 自动表单
+
+> JSON-driven auto-rendering form with built-in validation and a default submit button. Use the default slot to replace the built-in submit button with custom actions.
+> JSON 配置驱动的自动渲染表单，内置校验和默认提交按钮。通过默认插槽可替换内置提交按钮为自定义操作。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                                                                                         | Description (CN)                                           |
+| --------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| (default) | Default slot for custom actions below the form items. Replaces the built-in submit button when provided. | 表单项下方的自定义操作区域，传入内容后将替换内置提交按钮。 |
+
+## Properties / 属性
+
+| Name               | Type    | Default | Description (EN)                                                                                                                                                                                                  | Description (CN)                                                                                                                                                                               |
+| ------------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| fields             | String  | '[]'    | JSON string of field configurations. Each field supports: name, type, label, icon, tooltip, description, dft, rules (required/pattern/message), placeholder, disabled, options, dependencies, rules (dependency). | 字段配置的 JSON 字符串。每个字段支持：name、type、label、icon、tooltip、description、dft、rules（required/pattern/message）、placeholder、disabled、options、dependencies、rules（依赖联动）。 |
+| submitText         | String  | ''      | Custom submit button label. Falls back to i18n key `form.autoform.submit`.                                                                                                                                        | 自定义提交按钮文本。缺省使用 i18n 键 `form.autoform.submit`。                                                                                                                                  |
+| loading            | Boolean | false   | Whether the form is in a submitting state.                                                                                                                                                                        | 表单是否处于提交中状态。                                                                                                                                                                       |
+| validate-on-change | Boolean | true    | Whether to validate on every field change.                                                                                                                                                                        | 是否在每次字段变更时实时校验。                                                                                                                                                                 |
+
+## Methods / 方法
+
+| Name      | Parameters | Return                  | Description (EN)                                           | Description (CN)                 |
+| --------- | ---------- | ----------------------- | ---------------------------------------------------------- | -------------------------------- |
+| validate  | —          | boolean                 | Validate all fields and return whether the form is valid.  | 校验所有字段并返回表单是否有效。 |
+| getValues | —          | Record<string, unknown> | Return current values of all fields.                       | 返回所有字段的当前值。           |
+| reset     | —          | void                    | Reset all fields to their default values and clear errors. | 重置所有字段为缺省值并清除错误。 |
+
+## Events / 事件
+
+| Name           | Detail            | Description (EN)                      | Description (CN)       |
+| -------------- | ----------------- | ------------------------------------- | ---------------------- |
+| aithe-submit   | { values }        | Emitted on valid form submission.     | 有效表单提交时触发。   |
+| aithe-validate | { valid, errors } | Emitted after validation.             | 校验完成后触发。       |
+| aithe-change   | { name, value }   | Emitted when any field value changes. | 任意字段值变更时触发。 |
+
+## Supported Field Types / 支持的字段类型
+
+| Type       | Description (EN)                      | Description (CN)       |
+| ---------- | ------------------------------------- | ---------------------- |
+| input      | Single-line text input.               | 单行文本输入。         |
+| textarea   | Multi-line text input.                | 多行文本输入。         |
+| number     | Numeric input.                        | 数值输入。             |
+| password   | Password input.                       | 密码输入。             |
+| email      | Email input.                          | 邮箱输入。             |
+| select     | Dropdown selector.                    | 下拉选择器。           |
+| radio      | Radio button group.                   | 单选按钮组。           |
+| checkbox   | Checkbox group.                       | 复选框组。             |
+| switch     | Toggle switch.                        | 开关切换。             |
+| slider     | Range slider.                         | 滑块。                 |
+| rate       | Star rating.                          | 星级评分。             |
+| date       | Date picker.                          | 日期选择器。           |
+| time       | Time picker.                          | 时间选择器。           |
+| _(custom)_ | Any type registered via the registry. | 通过注册表注册的类型。 |
+
+## Custom Control Registry / 自定义控件注册表
+
+The autoform supports registering custom control types via the `FormRegistry` class. This allows extending the form with any custom Web Component or rendering logic without modifying the autoform source.
+
+自动表单支持通过 `FormRegistry` 类注册自定义控件类型，无需修改 autoform 源码即可扩展表单。
+
+### FormRegistry Static Methods / FormRegistry 静态方法
+
+| Method                        | Description (EN)                       | Description (CN)               |
+| ----------------------------- | -------------------------------------- | ------------------------------ |
+| FormRegistry.register(def)    | Register a custom control type.        | 注册自定义控件类型。           |
+| FormRegistry.unregister(type) | Unregister a custom control type.      | 注销自定义控件类型。           |
+| FormRegistry.get(type)        | Get a registered control definition.   | 获取已注册的控件定义。         |
+| FormRegistry.has(type)        | Check if a control type is registered. | 检查控件类型是否已注册。       |
+| FormRegistry.types()          | Get all registered custom type names.  | 获取所有已注册的自定义类型名。 |
+
+### FormControlDefinition / 控件定义
+
+| Property         | Type                       | Required | Description (EN)                                     | Description (CN)                        |
+| ---------------- | -------------------------- | -------- | ---------------------------------------------------- | --------------------------------------- |
+| type             | string                     | yes      | Unique type name matching the `type` in JSON config. | 唯一类型名称，匹配 JSON 配置中的 type。 |
+| render           | (ctx) => TemplateResult    | yes      | Renderer function returning the control template.    | 返回控件模板的渲染函数。                |
+| valueTransformer | (value: string) => unknown | no       | Optional transformer for `getFieldValue()`.          | 可选的 getFieldValue() 值转换器。       |
+| styles           | string                     | no       | Optional CSS styles for the custom control.          | 可选的自定义控件 CSS 样式。             |
+
+### FormControlContext / 渲染上下文
+
+| Property    | Type                     | Description (EN)                | Description (CN)   |
+| ----------- | ------------------------ | ------------------------------- | ------------------ |
+| value       | string                   | Current field value.            | 当前字段值。       |
+| placeholder | string                   | Placeholder text.               | 占位提示文本。     |
+| disabled    | boolean                  | Whether the field is disabled.  | 是否禁用。         |
+| name        | string                   | Field name.                     | 字段名称。         |
+| options     | string                   | JSON string of options.         | 选项 JSON 字符串。 |
+| min         | string                   | Minimum value.                  | 最小值。           |
+| max         | string                   | Maximum value.                  | 最大值。           |
+| step        | string                   | Step value.                     | 步长。             |
+| rows        | string                   | Number of rows.                 | 行数。             |
+| inputType   | string                   | Input type attribute.           | 输入类型属性。     |
+| onChange    | (value: unknown) => void | Callback to update field value. | 更新字段值的回调。 |
+
+### Register Example / 注册示例
+
+```ts
+import { FormRegistry } from '@aithe/aithe-ui';
+import { html } from 'lit';
+
+FormRegistry.register({
+  type: 'my-rich-editor',
+  render: (ctx) => html`
+    <my-rich-editor
+      .value=${ctx.value}
+      .placeholder=${ctx.placeholder}
+      ?disabled=${ctx.disabled}
+      @change=${(e: Event) => ctx.onChange((e.target as any).value)}
+    ></my-rich-editor>
+  `,
+  valueTransformer: (v) => v.toUpperCase(),
+});
+```
+
+Then use it in the fields JSON:
+
+```json
+{
+  "name": "content",
+  "type": "my-rich-editor",
+  "label": "Content",
+  "placeholder": "Enter content..."
+}
+```
+
+## Dependency & Linkage / 依赖联动
+
+The autoform supports field dependency linkage through pure JSON configuration. When a dependency field's value changes, the dependent field automatically re-evaluates its rules to update visibility, disabled state, options, or value.
+
+自动表单支持通过纯 JSON 配置实现字段依赖联动。当被依赖字段的值变化时，依赖字段自动重新计算规则，更新可见性、禁用状态、选项或值。
+
+### Field Configuration Properties / 字段配置属性
+
+| Property     | Type       | Description (EN)                                       | Description (CN)             |
+| ------------ | ---------- | ------------------------------------------------------ | ---------------------------- |
+| dependencies | string[]   | Names of fields this field depends on.                 | 当前字段依赖的字段名称列表。 |
+| rules        | FormRule[] | Dependency rules to evaluate when dependencies change. | 依赖变化时计算的联动规则。   |
+
+### FormRule / 联动规则
+
+| Property  | Type   | Required | Description (EN)                                            | Description (CN)                                            |
+| --------- | ------ | -------- | ----------------------------------------------------------- | ----------------------------------------------------------- |
+| type      | string | yes      | Rule type: show / hide / disable / enable / clear / update. | 规则类型：show / hide / disable / enable / clear / update。 |
+| condition | string | no       | Condition expression. Defaults to true if omitted.          | 条件表达式，省略时默认为 true。                             |
+| options   | string | no       | JSON string of options (only for type="update").            | 选项 JSON 字符串（仅 type="update" 时有效）。               |
+
+### Rule Types / 规则类型
+
+| Type    | Description (EN)                                       | Description (CN)               |
+| ------- | ------------------------------------------------------ | ------------------------------ |
+| show    | Show the field when condition is true; hide otherwise. | 条件为真时显示字段，否则隐藏。 |
+| hide    | Hide the field when condition is true; show otherwise. | 条件为真时隐藏字段，否则显示。 |
+| disable | Disable the field when condition is true.              | 条件为真时禁用字段。           |
+| enable  | Enable the field when condition is true.               | 条件为真时启用字段。           |
+| clear   | Clear the field value when condition is true.          | 条件为真时清空字段值。         |
+| update  | Update the field options when condition is true.       | 条件为真时更新字段选项。       |
+
+### Condition Expression Syntax / 条件表达式语法
+
+Expressions use JavaScript-like comparison syntax with field names as variables:
+
+表达式使用类 JavaScript 比较语法，字段名作为变量：
+
+| Operator | Example                | Description (EN)      | Description (CN) |
+| -------- | ---------------------- | --------------------- | ---------------- |
+| ===      | `province === 'BJ'`    | Strict equal          | 严格等于         |
+| !==      | `province !== ''`      | Strict not equal      | 严格不等于       |
+| >        | `age > 18`             | Greater than          | 大于             |
+| >=       | `age >= 18`            | Greater than or equal | 大于等于         |
+| <        | `age < 65`             | Less than             | 小于             |
+| <=       | `age <= 65`            | Less than or equal    | 小于等于         |
+| &&       | `a === 1 && b === 2`   | Logical AND           | 逻辑与           |
+| \|\|     | `a === 1 \|\| b === 2` | Logical OR            | 逻辑或           |
+
+String values use single or double quotes. Boolean values use `true`/`false`. Numeric values are written directly.
+
+字符串值使用单引号或双引号，布尔值使用 `true`/`false`，数值直接书写。
+
+### Province-City Linkage Example / 省市联动示例
+
+```json
+[
+  {
+    "name": "province",
+    "label": "Province",
+    "type": "select",
+    "options": "[{\"label\":\"Beijing\",\"id\":\"BJ\"},{\"label\":\"Shanghai\",\"id\":\"SH\"},{\"label\":\"Guangdong\",\"id\":\"GD\"}]"
+  },
+  {
+    "name": "city",
+    "label": "City",
+    "type": "select",
+    "dependencies": ["province"],
+    "rules": [
+      { "type": "show", "condition": "province !== ''" },
+      {
+        "type": "update",
+        "condition": "province === 'BJ'",
+        "options": "[{\"label\":\"Haidian\",\"id\":\"hd\"},{\"label\":\"Chaoyang\",\"id\":\"cy\"}]"
+      },
+      {
+        "type": "update",
+        "condition": "province === 'SH'",
+        "options": "[{\"label\":\"Pudong\",\"id\":\"pd\"},{\"label\":\"Jing'an\",\"id\":\"ja\"}]"
+      },
+      {
+        "type": "update",
+        "condition": "province === 'GD'",
+        "options": "[{\"label\":\"Guangzhou\",\"id\":\"gz\"},{\"label\":\"Shenzhen\",\"id\":\"sz\"}]"
+      },
+      { "type": "clear" }
+    ]
+  }
+]
+```
+
+### Conditional Show/Hide Example / 条件显示示例
+
+```json
+[
+  {
+    "name": "hasCar",
+    "label": "Do you have a car?",
+    "type": "switch"
+  },
+  {
+    "name": "carModel",
+    "label": "Car Model",
+    "type": "input",
+    "dependencies": ["hasCar"],
+    "rules": [{ "type": "show", "condition": "hasCar === true" }, { "type": "clear" }]
+  }
+]
+```
+
+### Conditional Disable Example / 条件禁用示例
+
+```json
+[
+  {
+    "name": "agreement",
+    "label": "I agree to the terms",
+    "type": "switch"
+  },
+  {
+    "name": "submitField",
+    "label": "Comments",
+    "type": "textarea",
+    "dependencies": ["agreement"],
+    "rules": [{ "type": "disable", "condition": "agreement !== true" }]
+  }
+]
+```
+
+## Examples / 示例
+
+```html
+<aithe-autoform
+  fields='[
+    {"name":"username","type":"input","label":"Username","icon":"user","required":true,"message":"Username is required","placeholder":"Enter username"},
+    {"name":"email","type":"input","label":"Email","tooltip":"Your work email","required":true,"inputType":"email","pattern":"^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$","message":"Invalid email","placeholder":"you@company.com"},
+    {"name":"role","type":"select","label":"Role","options":"[{\\"label\\":\\"Admin\\",\\"id\\":\\"admin\\"},{\\"label\\":\\"Editor\\",\\"id\\":\\"editor\\"},{\\"label\\":\\"Viewer\\",\\"id\\":\\"viewer\\"}]","dft":"viewer"},
+    {"name":"notifications","type":"switch","label":"Notifications","dft":"true"}
+  ]'
+></aithe-autoform>
+```

package/docs/api/form/combobox.md

@@ -16,7 +16,7 @@
 | value | String | '' | Current input value. | 当前输入值。 |
 | title | `string` | `''` | Display title (shown as tooltip). | 显示标题（作为工具提示）。 |
 | icon | `string` | `''` | Icon name to display before the input. | 在输入框前显示的图标名称。 |
-| options | String | '[]' | JSON string of combobox options. Each option supports `icon` and `intent` (AitheIntent) fields. | 组合框选项的 JSON 字符串。每个选项支持 `icon` 和 `intent`（AitheIntent）字段。 |
+| options | String | '[]' | JSON string of combobox options. Each option supports `icon` and `variant` (AitheVariant) fields. | 组合框选项的 JSON 字符串。每个选项支持 `icon` 和 `variant`（AitheVariant）字段。 |
 | filterable | Boolean | true | Whether the input supports filtering options. | 是否支持过滤选项。 |
 | disabled | Boolean | false | Whether the combobox is disabled. | 是否禁用组合框。 |
 | placeholder | String | 'Search or select' | Placeholder text for the input. | 输入框的占位文本。 |
@@ -35,7 +35,7 @@
 | label | `string` | Display text. | 显示文本。 |
 | id | `string` | Unique value emitted on select. | 选择时发出的唯一值。 |
 | icon | `string` | Icon name rendered before the label via aithe-icon. | 通过 aithe-icon 在标签前渲染的图标名称。 |
-| intent | AitheIntent | Visual intent / semantic color for the option. | 选项的视觉意图/语义色。 |
+| variant | AitheVariant | Visual variant / semantic color for the option. | 选项的视觉变体/语义色。 |
 
 ## Examples / 示例
 

package/docs/api/form/select.md

@@ -14,7 +14,7 @@
 | Name | Type | Default | Description (EN) | Description (CN) |
 |------|------|---------|-------------------|-------------------|
 | optionsJson | String | '' | JSON string of select options. | 选项的 JSON 字符串。 |
-| options | AitheSelectOption[] | [] | Array of select option objects. Each option supports `icon` and `intent` (AitheIntent) fields. | 选项对象数组。每个选项支持 `icon` 和 `intent`（AitheIntent）字段。 |
+| options | AitheSelectOption[] | [] | Array of select option objects. Each option supports `icon` and `variant` (AitheVariant) fields. | 选项对象数组。每个选项支持 `icon` 和 `variant`（AitheVariant）字段。 |
 | value | String | '' | Currently selected value. | 当前选中的值。 |
 | title | `string` | `''` | Display title (shown as tooltip). | 显示标题（作为工具提示）。 |
 | icon | `string` | `''` | Icon name to display before the selected value. | 在选中值前显示的图标名称。 |
@@ -41,7 +41,7 @@
 | disabled | `boolean` | Whether the option is non-interactive. | 是否不可交互。 |
 | description | `string` | Secondary description line. | 二级描述行。 |
 | icon | `string` | Icon name rendered before the label via aithe-icon. | 通过 aithe-icon 在标签前渲染的图标名称。 |
-| intent | AitheIntent | Visual intent / semantic color for the option. | 选项的视觉意图/语义色。 |
+| variant | AitheVariant | Visual variant / semantic color for the option. | 选项的视觉变体/语义色。 |
 
 ## Examples / 示例
 

package/docs/api/form/switch.md

@@ -16,7 +16,7 @@
 | checked | Boolean | false | Whether the switch is checked (on). | 是否选中（开启）。 |
 | disabled | Boolean | false | Whether the switch is disabled. | 是否禁用。 |
 | size | 'sm' \| 'md' \| 'lg' | 'md' | Switch size preset. | 开关尺寸预设。 |
-| type | AitheIntent | 'primary' | Color intent when checked. | 选中时的颜色意图。 |
+| variant | AitheVariant | 'primary' | Color variant when checked. | 选中时的颜色变体。 |
 
 ## Events / 事件
 
@@ -27,5 +27,5 @@
 ## Examples / 示例
 
 ```html
-<aithe-switch checked size="md" type="primary"></aithe-switch>
+<aithe-switch checked size="md" variant="primary"></aithe-switch>
 ```

package/docs/api/framework/body.md

@@ -0,0 +1,72 @@
+# AitheBody / AitheBody 页体
+
+> Framework-level page body that sits below `aithe-header`, providing layout density control, automatic scrolling, and a floating action bar.
+> 框架级页面主体区域，位于 `aithe-header` 下方，提供布局密度控制、自动滚动和浮动操作栏。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                                                             | Description (CN)                               |
+| --------- | ---------------------------------------------------------------------------- | ---------------------------------------------- |
+| (default) | Page content.                                                                | 页面内容。                                     |
+| actions   | Extra action buttons in the floating bar (rendered before built-in buttons). | 浮动栏中的额外操作按钮（在内置按钮之前渲染）。 |
+
+## Properties / 属性
+
+| Name               | Type              | Default    | Description (EN)                                                                                           | Description (CN)                                         |
+| ------------------ | ----------------- | ---------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| layout             | `AitheLayoutName` | `'medium'` | Current layout density. Synchronized with global layout state.                                             | 当前布局密度。与全局布局状态同步。                       |
+| show-actions       | `boolean`         | `false`    | Whether to show the floating action bar.                                                                   | 是否显示浮动操作栏。                                     |
+| show-back-top      | `boolean`         | `true`     | Whether to show the "back to top" button in the action bar.                                                | 是否在操作栏中显示"回到顶部"按钮。                       |
+| show-layout-switch | `boolean`         | `true`     | Whether to show the "switch layout" button in the action bar. Hidden automatically on mobile.              | 是否在操作栏中显示"切换布局"按钮。移动端自动隐藏。       |
+| visibility-height  | `number`          | `260`      | Scroll threshold in pixels before the back-to-top button appears.                                          | 回到顶部按钮出现前的滚动阈值（像素）。                   |
+| mobile-breakpoint  | `number`          | `768`      | Viewport width threshold (px); when ≤ this value, layout is forced to `wide` and layout-switch is hidden.  | 移动端断点（像素）；视口宽度 ≤ 此值时强制 wide 布局并隐藏切换按钮。 |
+
+## Layout Widths / 布局宽度
+
+| Layout  | Content Width | Description (EN) | Description (CN) |
+| ------- | ------------- | ---------------- | ---------------- |
+| compact | 60%           | Compact density  | 紧凑密度         |
+| medium  | 80%           | Medium density   | 适中密度         |
+| wide    | 100%          | Wide density     | 宽松密度         |
+
+## Events / 事件
+
+| Name                | Detail               | Cancelable | Description (EN)                                                                                         | Description (CN)                                                     |
+| ------------------- | -------------------- | ---------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| aithe-layout-change | `{ layout: string }` | Yes        | Emitted when layout density is about to change. Call `preventDefault()` to suppress the built-in switch. | 布局密度即将变更时发出。调用 `preventDefault()` 可阻止内置切换逻辑。 |
+
+## Examples / 示例
+
+### Basic usage / 基础用法
+
+```html
+<aithe-header brand="App" show-locale-switch show-theme-switch></aithe-header>
+<aithe-body show-actions>
+  <main>Your content here</main>
+</aithe-body>
+```
+
+### With custom action buttons / 自定义操作按钮
+
+```html
+<aithe-body show-actions>
+  <main>Content</main>
+  <aithe-button slot="actions" type="text" size="small">⚙</aithe-button>
+</aithe-body>
+```
+
+### Overriding built-in layout switch / 覆盖内置布局切换
+
+```js
+const body = document.querySelector('aithe-body');
+body.addEventListener('aithe-layout-change', (e) => {
+  e.preventDefault();
+  console.log('Custom layout:', e.detail.layout);
+});
+```
+
+### Mobile behavior / 移动端行为
+
+When the viewport width is ≤ `mobile-breakpoint` (default 768px), the body automatically forces `wide` layout and hides the layout-switch button. When the viewport returns to desktop width, the previous layout is restored.
+
+当视口宽度 ≤ `mobile-breakpoint`（默认 768px）时，body 自动强制 `wide` 布局并隐藏布局切换按钮。视口恢复桌面宽度后，还原之前的布局。