@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/api/form/autoform-item.md

@@ -0,0 +1,100 @@
+# AitheAutoformItem / AitheAutoformItem 自动表单项
+
+> JSON-driven auto form item with three-section layout (header / control / footer) and built-in validation. Supports dependency rules for dynamic visibility, disabled state, and options.
+> JSON 驱动的自动表单项，三段式布局（头部 / 控件 / 底部），内置校验。支持依赖联动规则动态控制可见性、禁用状态和选项。
+
+## Slots / 插槽
+
+| Name      | Description (EN)                           | Description (CN)   |
+| --------- | ------------------------------------------ | ------------------ |
+| (default) | Default slot for the form control element. | 表单控件元素内容。 |
+
+## Properties / 属性
+
+| Name               | Type                      | Default   | Description (EN)                                                                                                                                                | Description (CN)           |
+| ------------------ | ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| name               | `string`                  | `''`      | Field unique identifier.                                                                                                                                        | 字段唯一标识。             |
+| type               | `AutoformItemType`        | `'input'` | Control type: input \| textarea \| select \| radio \| checkbox \| switch \| number \| slider \| rate \| color-picker \| date-picker \| time-picker \| combobox. | 控件类型。                 |
+| label              | `string`                  | `''`      | Label text.                                                                                                                                                     | 标签文本。                 |
+| icon               | `string`                  | `''`      | Icon name displayed before the label.                                                                                                                           | 标签前显示的图标名称。     |
+| tooltip            | `string`                  | `''`      | Tooltip text shown on hover.                                                                                                                                    | 悬停提示文本。             |
+| description        | `string`                  | `''`      | Description text below the control.                                                                                                                             | 控件下方的说明文字。       |
+| dft                | `string`                  | `''`      | Default value.                                                                                                                                                  | 缺省值。                   |
+| placeholder        | `string`                  | `''`      | Placeholder text.                                                                                                                                               | 占位提示文本。             |
+| disabled           | `boolean`                 | `false`   | Whether the field is disabled.                                                                                                                                  | 是否禁用。                 |
+| required           | `boolean`                 | `false`   | Whether the field is required.                                                                                                                                  | 是否必填。                 |
+| pattern            | `string`                  | `''`      | Validation regex pattern string.                                                                                                                                | 校验正则表达式字符串。     |
+| message            | `string`                  | `''`      | Validation failure message.                                                                                                                                     | 校验失败提示语。           |
+| options            | `FormItemOption[]`        | `[]`      | Options for select/radio/checkbox.                                                                                                                              | 选择类控件的选项。         |
+| value              | `string`                  | `''`      | Current field value.                                                                                                                                            | 当前字段值。               |
+| inputType          | `string`                  | `'text'`  | Input type attribute for type="input".                                                                                                                          | input 控件的 type 属性。   |
+| min                | `string`                  | `''`      | Minimum value for number/slider.                                                                                                                                | 数字/滑块最小值。          |
+| max                | `string`                  | `''`      | Maximum value for number/slider.                                                                                                                                | 数字/滑块最大值。          |
+| step               | `string`                  | `''`      | Step value for number/slider/rate.                                                                                                                              | 数字/滑块/评分步长。       |
+| rows               | `string`                  | `'3'`     | Number of rows for textarea.                                                                                                                                    | 文本域行数。               |
+| validate-on-change | `boolean`                 | `true`    | Whether to validate on every change.                                                                                                                            | 是否在每次变更时实时校验。 |
+| dependencies       | `string[]`                | `[]`      | Dependency field names.                                                                                                                                         | 依赖字段名称列表。         |
+| rules              | `FormRule[]`              | `[]`      | Dependency rules.                                                                                                                                               | 依赖联动规则。             |
+| dependencyValues   | `Record<string, unknown>` | `{}`      | Current values of dependency fields.                                                                                                                            | 依赖字段的当前值。         |
+
+## Events / 事件
+
+| Name         | Detail                             | Cancelable | Description (EN)                      | Description (CN)   |
+| ------------ | ---------------------------------- | ---------- | ------------------------------------- | ------------------ |
+| aithe-change | `{ name: string, value: unknown }` | No         | Emitted when the field value changes. | 字段值变更时触发。 |
+
+## Methods / 方法
+
+| Name            | Return Type | Description (EN)                                                   | Description (CN)                          |
+| --------------- | ----------- | ------------------------------------------------------------------ | ----------------------------------------- |
+| validate()      | `boolean`   | Validates the field and sets error state. Returns `true` if valid. | 校验字段并设置错误状态，有效返回 `true`。 |
+| clearError()    | `void`      | Clears the validation error.                                       | 清除校验错误。                            |
+| getError()      | `string`    | Returns the current validation error message.                      | 返回当前校验错误消息。                    |
+| getFieldValue() | `unknown`   | Returns the current field value (type-aware).                      | 返回当前字段值（类型感知）。              |
+
+## Properties (Getters) / 只读属性
+
+| Name    | Type      | Description (EN)                                               | Description (CN)                 |
+| ------- | --------- | -------------------------------------------------------------- | -------------------------------- |
+| visible | `boolean` | Whether the field is visible (controlled by dependency rules). | 字段是否可见（由依赖规则控制）。 |
+
+## Examples / 示例
+
+### 基本用法
+
+```html
+<aithe-autoform-item
+  name="email"
+  type="input"
+  label="Email"
+  icon="mail"
+  tooltip="Your work email"
+  description="We will never share your email."
+  required
+></aithe-autoform-item>
+```
+
+### 选择类控件
+
+```html
+<aithe-autoform-item
+  name="country"
+  type="select"
+  label="Country"
+  .options='[{ "id": "cn", "label": "China" }, { "id": "us", "label": "USA" }]'
+></aithe-autoform-item>
+```
+
+### 带校验规则
+
+```html
+<aithe-autoform-item
+  name="phone"
+  type="input"
+  inputType="tel"
+  label="Phone"
+  required
+  pattern="^1[3-9]\d{9}$"
+  message="Please enter a valid phone number"
+></aithe-autoform-item>
+```

package/docs/api/form/autoform.md

@@ -0,0 +1,271 @@
+# 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 (buttons) below the form items. Use together with `show-submit` to control the built-in submit button. | 表单项下方的自定义操作区域（按钮），配合 `show-submit` 属性控制内置提交按钮的显隐。 |
+
+## 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.                                                                                                                                                                        | 是否在每次字段变更时实时校验。                                                                                                                                                                 |
+| initial-values     | Object / String | {}     | Initial values for form fields, as an object or JSON string. Overrides `dft` for each matching field.                                                                                                             | 表单字段初始值，支持对象或 JSON 字符串，覆盖对应字段的 `dft`。                                                                                                                                |
+| show-submit        | Boolean | true    | Whether to show the built-in submit button. Set to `false` when using custom action slot.                                                                                                                         | 是否显示内置提交按钮，设为 `false` 时使用自定义 slot。                                                                                                                                         |
+
+## 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. | 重置所有字段为缺省值并清除错误。 |
+| submit    | —          | void                    | Trigger form validation and submission programmatically. Emits aithe-submit if valid. | 编程触发表单校验和提交，通过后触发 aithe-submit 事件。 |
+
+## 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

@@ -5,43 +5,43 @@
 
 ## Slots / 插槽
 
-| Name | Description (EN) | Description (CN) |
-|------|-------------------|-------------------|
+| Name      | Description (EN)                                  | Description (CN)                          |
+| --------- | ------------------------------------------------- | ----------------------------------------- |
 | (default) | Default slot (unused; content driven by options). | 默认插槽（未使用，内容由 options 控制）。 |
 
 ## Properties / 属性
 
-| 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）字段。 |
-| value | String | '' | Currently selected value. | 当前选中的值。 |
-| title | `string` | `''` | Display title (shown as tooltip). | 显示标题（作为工具提示）。 |
-| icon | `string` | `''` | Icon name to display before the selected value. | 在选中值前显示的图标名称。 |
-| placeholder | String | '请选择' | Placeholder text shown when no value is selected. | 无选中值时的占位文本。 |
-| searchable | Boolean | false | Whether the select supports search/filter. | 是否支持搜索过滤。 |
-| clearable | Boolean | false | Whether the selected value can be cleared. | 是否允许清除选中值。 |
-| disabled | Boolean | false | Whether the select is disabled. | 是否禁用。 |
-| placement | 'bottom-start' \| 'top-start' | 'bottom-start' | Dropdown panel placement. | 下拉面板位置。 |
+| 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 `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.                                                  | 在选中值前显示的图标名称。                                           |
+| placeholder | String                        | '请选择'       | Placeholder text shown when no value is selected.                                                | 无选中值时的占位文本。                                               |
+| searchable  | Boolean                       | false          | Whether the select supports search/filter.                                                       | 是否支持搜索过滤。                                                   |
+| clearable   | Boolean                       | false          | Whether the selected value can be cleared.                                                       | 是否允许清除选中值。                                                 |
+| disabled    | Boolean                       | false          | Whether the select is disabled.                                                                  | 是否禁用。                                                           |
+| placement   | 'bottom-start' \| 'top-start' | 'bottom-start' | Dropdown panel placement.                                                                        | 下拉面板位置。                                                       |
 
 ## Events / 事件
 
-| Name | Detail | Description (EN) | Description (CN) |
-|------|--------|-------------------|-------------------|
-| aithe-change | { option, value } | Emitted when a value is selected. | 选中值变更时触发。 |
-| aithe-clear | — | Emitted when the value is cleared. | 值被清除时触发。 |
-| aithe-open-change | { open } | Emitted when the dropdown opens or closes. | 下拉框开关状态变更时触发。 |
+| Name                  | Detail            | Description (EN)                           | Description (CN)           |
+| --------------------- | ----------------- | ------------------------------------------ | -------------------------- |
+| aithe-change          | { option, value } | Emitted when a value is selected.          | 选中值变更时触发。         |
+| aithe-clear           | —                 | Emitted when the value is cleared.         | 值被清除时触发。           |
+| aithe-dropdown-change | { open }          | Emitted when the dropdown opens or closes. | 下拉框开关状态变更时触发。 |
 
 ## Option Fields / 选项字段
 
-| Field | Type | Description (EN) | Description (CN) |
-|-------|------|-------------------|-------------------|
-| label | `string` | Display text. | 显示文本。 |
-| id | `string` | Unique value emitted on select. | 选择时发出的唯一值。 |
-| 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. | 选项的视觉意图/语义色。 |
+| Field       | Type         | Description (EN)                                    | Description (CN)                         |
+| ----------- | ------------ | --------------------------------------------------- | ---------------------------------------- |
+| label       | `string`     | Display text.                                       | 显示文本。                               |
+| id          | `string`     | Unique value emitted on select.                     | 选择时发出的唯一值。                     |
+| 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 在标签前渲染的图标名称。 |
+| variant     | AitheVariant | Visual variant / semantic color for the option.     | 选项的视觉变体/语义色。                  |
 
 ## Examples / 示例
 
@@ -53,4 +53,4 @@
   searchable
   clearable
 ></aithe-select>
-```
+```

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` 布局并隐藏布局切换按钮。视口恢复桌面宽度后，还原之前的布局。