@aithe/aithe-ui 26.2.2 → 26.3.1

package/docs/api/utils/icon.md

@@ -0,0 +1,192 @@
+# IconUtil / 图标工具
+
+> Utility class for parsing and rendering icons in the extended `(type)value` format. Supports five icon source types: built-in class, auto-generated from text, and URL-loaded images with alt fallback.
+> 图标工具类，用于解析和渲染扩展的 `(type)value` 格式图标。支持五种图标来源类型：内置 class、文本自动生成和 URL 加载（带 alt 占位）。
+
+## Import / 导入
+
+```ts
+import { IconUtil } from '@utils';
+
+// Or directly / 或直接导入
+import { IconUtil } from '@/utils/icon';
+```
+
+## Methods / 方法
+
+### `IconUtil.parse(input)`
+
+Parse an icon string in `(type)value` format.
+解析 `(type)value` 格式的图标字符串。
+
+| Param | Type | Default | Description (EN) | Description (CN) |
+|-------|------|---------|-------------------|-------------------|
+| `input` | `string` | — | The icon string to parse. | 要解析的图标字符串。 |
+
+**Returns**: [`IconDescriptor`](#iconDescriptor)
+
+If the input does not match the format, defaults to `{ type: 'class', value: input }`.
+若输入不匹配格式，默认返回 `{ type: 'class', value: input }`。
+
+### `IconUtil.resolveSize(size, fallback?)`
+
+Resolve a size preset or CSS value to a normalized CSS dimension.
+将尺寸预设或 CSS 值解析为规范化的 CSS 尺寸。
+
+| Param | Type | Default | Description (EN) | Description (CN) |
+|-------|------|---------|-------------------|-------------------|
+| `size` | `string` | — | Size preset or CSS value. | 尺寸预设或 CSS 值。 |
+| `fallback` | `string` | `'20px'` | Fallback value if input is empty. | 输入为空时的后备值。 |
+
+**Returns**: `string`
+
+If the input matches a preset key in `ICON_SIZE_MAP`, returns the mapped value. Otherwise, treats it as a raw CSS value (bare numbers get `px` suffix).
+若输入匹配 `ICON_SIZE_MAP` 中的预设键，返回映射值；否则视为原始 CSS 值（纯数字自动加 `px`）。
+
+### `IconUtil.render(input, size?, cls?, iconStyle?)`
+
+Render an icon string into a Lit HTML template result.
+将图标字符串渲染为 Lit HTML 模板结果。
+
+| Param | Type | Default | Description (EN) | Description (CN) |
+|-------|------|---------|-------------------|-------------------|
+| `input` | `string` | — | The icon string. | 图标字符串。 |
+| `size` | `string` | `'16'` | Icon size. Accepts bare number (auto `px`) or CSS value. | 图标尺寸。支持纯数字（自动加 px）或 CSS 值。 |
+| `cls` | `string` | `''` | Additional CSS class for the wrapper element. | 包装元素的额外 CSS 类。 |
+| `iconStyle` | `string` | `''` | Additional inline style for the wrapper element. | 包装元素的额外内联样式。 |
+
+**Returns**: `TemplateResult`
+
+Rendering behavior per type / 各类型渲染行为：
+
+| Type | Output | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| `class` | `<aithe-icon>` | Delegates to the `<aithe-icon>` component. | 委托给 `<aithe-icon>` 组件。 |
+| `auto` | `<span>` | Renders a span with the first character of the text. | 渲染包含首字符的 span。 |
+| `url` / `share` / `remote` | `<img>` + fallback | Renders an img tag. Supports `URL\|AltText` format — shows alt first char on load error. | 渲染 img 标签。支持 `URL\|AltText` 格式，加载失败时显示 alt 首字符。 |
+
+### `IconUtil.renderSvg(input, size?, iconStyle?)`
+
+Render an icon string into an inline SVG template (for embedding inside other SVGs).
+将图标字符串渲染为内联 SVG 模板（用于嵌入到其他 SVG 中）。
+
+| Param | Type | Default | Description (EN) | Description (CN) |
+|-------|------|---------|-------------------|-------------------|
+| `input` | `string` | — | The icon string. | 图标字符串。 |
+| `size` | `string` | `'16'` | Icon size. | 图标尺寸。 |
+| `iconStyle` | `string` | `''` | Reserved, not used in SVG context. | 预留，SVG 上下文中未使用。 |
+
+**Returns**: `TemplateResult`
+
+Rendering behavior per type / 各类型渲染行为：
+
+| Type | Output | Description (EN) | Description (CN) |
+|------|--------|-------------------|-------------------|
+| `class` | Empty SVG | Returns an empty SVG (delegates to `<aithe-icon>` at HTML level). | 返回空 SVG（在 HTML 层面委托给 `<aithe-icon>`）。 |
+| `auto` | `<text>` | Renders a text element with the first character. | 渲染包含首字符的 text 元素。 |
+| `url` / `share` / `remote` | `<image>` | Renders an image element. Supports `URL\|AltText` format. | 渲染 image 元素。支持 `URL\|AltText` 格式。 |
+
+## Types / 类型
+
+### `IconType`
+
+```ts
+type IconType = 'class' | 'auto' | 'url' | 'share' | 'remote';
+```
+
+| Value | Description (EN) | Description (CN) |
+|-------|-------------------|-------------------|
+| `class` | Built-in icon name from the SVG glyph map. | 内置 SVG 图标名称。 |
+| `auto` | Auto-generate icon from the first character of text. | 取文本首字符自动生成图标。 |
+| `url` | Load icon from a URL via `<img>`. | 通过 URL 加载图标。 |
+| `share` | Alias for `url`. | `url` 的别名。 |
+| `remote` | Alias for `url`. | `url` 的别名。 |
+
+### `IconDescriptor` {#iconDescriptor}
+
+```ts
+interface IconDescriptor {
+  type: IconType;
+  value: string;
+}
+```
+
+### `ICON_SIZE_MAP`
+
+```ts
+const ICON_SIZE_MAP: Record<string, string>;
+```
+
+Icon size preset map. Maps preset names to CSS pixel values.
+图标尺寸预设映射表，将预设名称映射为 CSS 像素值。
+
+| Preset | Value | Description (EN) | Description (CN) |
+|--------|-------|-------------------|-------------------|
+| `xs` | `12px` | Extra small for dense inline text. | 超小，用于紧凑行内文本。 |
+| `sm` | `16px` | Small icon for inline text or tight layouts. | 小图标，用于行内文本或紧凑布局。 |
+| `md` | `20px` | Default medium icon. | 默认中等图标。 |
+| `lg` | `24px` | Large icon for headings or standalone display. | 大图标，用于标题或独立展示。 |
+| `xl` | `28px` | Extra large for section headers. | 超大，用于章节标题。 |
+| `2xl` | `32px` | Double extra large. | 2 倍超大。 |
+| `3xl` | `48px` | Triple extra large for hero areas. | 3 倍超大，用于主视觉区域。 |
+| `4xl` | `64px` | 4× extra large. | 4 倍超大。 |
+| `5xl` | `96px` | 5× extra large. | 5 倍超大。 |
+| `6xl` | `128px` | Maximum preset for large displays. | 最大预设，用于大屏展示。 |
+
+## Format / 格式说明
+
+The extended icon format is: `(type)value`
+
+```
+(class)sparkles                       → Built-in SVG icon / 内置 SVG 图标
+(auto)User Name                       → Auto-generated from first char "U" / 取首字符 "U" 自动生成
+(url)https://example.com/icon.svg     → Load from URL / 从 URL 加载
+(url)https://example.com/icon.svg|Alt → Load from URL, fallback to "A" on error / 从 URL 加载，失败时显示 "A"
+(share)https://example.com/icon.svg   → Alias for url / url 别名
+(remote)https://example.com/icon.svg  → Alias for url / url 别名
+sparkles                              → Bare name defaults to class / 裸名称默认视为 class 类型
+```
+
+## Examples / 示例
+
+### Parse an icon string / 解析图标字符串
+
+```ts
+const { type, value } = IconUtil.parse('(auto)User');
+// → { type: 'auto', value: 'User' }
+
+const { type, value } = IconUtil.parse('sparkles');
+// → { type: 'class', value: 'sparkles' }
+```
+
+### Render as Lit HTML / 渲染为 Lit HTML
+
+```ts
+// Built-in icon / 内置图标
+IconUtil.render('sparkles', '24', 'my-icon');
+
+// Auto-generated from text / 文本首字符自动生成
+IconUtil.render('(auto)John Doe', '32');
+
+// URL image / URL 图片
+IconUtil.render('(url)https://example.com/icon.svg', '24');
+
+// URL image with alt fallback / URL 图片带 alt 占位
+IconUtil.render('(url)https://example.com/icon.svg|User', '24');
+
+// With inline style / 带内联样式
+IconUtil.render('sparkles', '24', '', 'margin-right: 8px;');
+```
+
+### Render as inline SVG / 渲染为内联 SVG
+
+```ts
+// Auto-generated text inside SVG / SVG 内文本首字符
+IconUtil.renderSvg('(auto)User', '24');
+
+// URL image inside SVG / SVG 内 URL 图片
+IconUtil.renderSvg('(url)https://example.com/icon.svg', '24');
+
+// Class type returns empty SVG / class 类型返回空 SVG
+IconUtil.renderSvg('sparkles', '24');  // → svg``
+```

package/docs/autoform.md

@@ -0,0 +1,339 @@
+# Autoform 技术文档
+
+## 概述
+
+Autoform 是一个 **JSON 驱动的自动表单系统**，基于 Lit Web Components 构建。它接收 JSON 配置数组，自动渲染表单项，支持实时校验、依赖联动和自定义控件扩展。
+
+> **表单数据提交**：autoform 本身只负责表单 UI 渲染和联动逻辑。表单数据提交通过 [DataHub](datahub.md) 数据中间层完成，DataHub 的 **APIStyle** 机制可自动处理请求体包装（如 `{ data: ... }`）和响应解包（如 `{ code, message, data }`），参见 [APIStyle 文档](datahub.md#apis-tyle-业务协议解析)。
+
+---
+
+## JSON 规范
+
+### 顶层结构
+
+`fields` 属性接收一个 JSON 字符串，解析后为 `FormFieldConfig[]`：
+
+```typescript
+interface FormFieldConfig {
+  name?: string; // 字段唯一标识
+  type?: string; // 控件类型
+  label?: string; // 标签文本
+  icon?: string; // 图标名称
+  tooltip?: string; // 悬停提示
+  description?: string; // 说明文字
+  dft?: string; // 缺省值
+  placeholder?: string; // 占位提示
+  disabled?: boolean; // 是否禁用
+  required?: boolean; // 是否必填
+  pattern?: string; // 校验正则
+  message?: string; // 校验失败提示
+  options?: string | FormItemOption[]; // 选项
+  inputType?: string; // HTML input type
+  min?: string; // 最小值
+  max?: string; // 最大值
+  step?: string; // 步长
+  rows?: string; // 文本域行数
+  dependencies?: string[]; // 依赖字段列表
+  rules?: FormRule[]; // 联动规则
+}
+```
+
+### 内置控件类型
+
+### 顶层结构
+
+`fields` 属性接收一个 JSON 字符串，解析后为 `FormFieldConfig[]`：
+
+```typescript
+interface FormFieldConfig {
+  name?: string; // 字段唯一标识
+  type?: string; // 控件类型
+  label?: string; // 标签文本
+  icon?: string; // 图标名称
+  tooltip?: string; // 悬停提示
+  description?: string; // 说明文字
+  dft?: string; // 缺省值
+  placeholder?: string; // 占位提示
+  disabled?: boolean; // 是否禁用
+  required?: boolean; // 是否必填
+  pattern?: string; // 校验正则
+  message?: string; // 校验失败提示
+  options?: string | FormItemOption[]; // 选项
+  inputType?: string; // HTML input type
+  min?: string; // 最小值
+  max?: string; // 最大值
+  step?: string; // 步长
+  rows?: string; // 文本域行数
+  dependencies?: string[]; // 依赖字段列表
+  rules?: FormRule[]; // 联动规则
+}
+```
+
+### 内置控件类型
+
+| type           | 说明       | 特有属性                                |
+| -------------- | ---------- | --------------------------------------- |
+| `input`        | 文本输入框 | `inputType`（如 `email`、`url`、`tel`） |
+| `textarea`     | 多行文本域 | `rows`                                  |
+| `select`       | 下拉选择   | `options`                               |
+| `radio`        | 单选组     | `options`                               |
+| `checkbox`     | 多选组     | `options`                               |
+| `switch`       | 开关       | —                                       |
+| `number`       | 数字输入   | `min`、`max`、`step`                    |
+| `slider`       | 滑块       | `min`、`max`、`step`                    |
+| `rate`         | 评分       | `step`                                  |
+| `color-picker` | 颜色选择器 | —                                       |
+| `date-picker`  | 日期选择   | —                                       |
+| `time-picker`  | 时间选择   | —                                       |
+| `combobox`     | 可搜索下拉 | `options`                               |
+
+### 选项格式
+
+```typescript
+interface FormItemOption {
+  label: string; // 显示文本
+  id: string; // 选项值
+  disabled?: boolean; // 是否禁用
+}
+```
+
+### 联动规则
+
+```typescript
+interface FormRule {
+  type: FormRuleType; // 规则类型
+  condition?: string; // 条件表达式（省略时视为 true）
+  options?: string | FormItemOption[]; // 仅 update 规则使用
+}
+
+type FormRuleType = 'show' | 'hide' | 'disable' | 'enable' | 'clear' | 'update';
+```
+
+| 规则类型  | 条件为 true 时的效果 |
+| --------- | -------------------- |
+| `show`    | 显示字段             |
+| `hide`    | 隐藏字段             |
+| `disable` | 禁用字段             |
+| `enable`  | 启用字段             |
+| `clear`   | 清空字段值           |
+| `update`  | 更新字段的 `options` |
+
+---
+
+## 使用方法
+
+### 基本用法
+
+```html
+<aithe-autoform
+  fields='[
+    {"name":"username","type":"input","label":"用户名","required":true,"placeholder":"请输入用户名"},
+    {"name":"email","type":"input","label":"邮箱","inputType":"email","required":true},
+    {"name":"role","type":"select","label":"角色","options":[{"label":"管理员","id":"admin"},{"label":"用户","id":"user"}]},
+    {"name":"notifications","type":"switch","label":"开启通知","dft":"true"}
+  ]'
+></aithe-autoform>
+```
+
+### JavaScript API
+
+```typescript
+const form = document.querySelector('aithe-autoform');
+
+// 校验所有可见字段
+const isValid: boolean = form.validate();
+
+// 获取所有可见字段值
+const values: Record<string, unknown> = form.getValues();
+
+// 重置为缺省值
+form.reset();
+
+// 编程触发表单提交（校验通过后触发 aithe-submit 事件）
+form.submit();
+
+// 监听提交事件
+form.addEventListener('aithe-submit', (e: CustomEvent<{ values: Record<string, unknown> }>) => {
+  console.log('提交数据：', e.detail.values);
+});
+
+// 监听字段变更
+form.addEventListener('aithe-change', (e: CustomEvent<{ name: string; value: unknown }>) => {
+  console.log(`字段 "${e.detail.name}" 变更为：`, e.detail.value);
+});
+```
+
+### 依赖联动示例（省市区）
+
+```json
+[
+  {
+    "name": "province",
+    "type": "select",
+    "label": "省份",
+    "options": [
+      { "label": "北京", "id": "BJ" },
+      { "label": "上海", "id": "SH" },
+      { "label": "广东", "id": "GD" }
+    ]
+  },
+  {
+    "name": "city",
+    "type": "select",
+    "label": "城市",
+    "dependencies": ["province"],
+    "rules": [
+      { "type": "show", "condition": "province !== ''" },
+      {
+        "type": "update",
+        "condition": "province === 'BJ'",
+        "options": [
+          { "label": "海淀", "id": "hd" },
+          { "label": "朝阳", "id": "cy" }
+        ]
+      },
+      {
+        "type": "update",
+        "condition": "province === 'SH'",
+        "options": [
+          { "label": "浦东", "id": "pd" },
+          { "label": "静安", "id": "ja" }
+        ]
+      },
+      {
+        "type": "update",
+        "condition": "province === 'GD'",
+        "options": [
+          { "label": "广州", "id": "gz" },
+          { "label": "深圳", "id": "sz" }
+        ]
+      },
+      { "type": "clear" }
+    ]
+  }
+]
+```
+
+### 条件联动示例（开关控制显隐）
+
+```json
+[
+  { "name": "hasCar", "type": "switch", "label": "是否有车？", "dft": "false" },
+  {
+    "name": "carModel",
+    "type": "input",
+    "label": "车型",
+    "placeholder": "请输入车型",
+    "dependencies": ["hasCar"],
+    "rules": [{ "type": "show", "condition": "hasCar === true" }, { "type": "clear" }]
+  }
+]
+```
+
+### 注册自定义控件
+
+```typescript
+import { FormRegistry } from '@aithe/aithe-ui';
+import { html } from 'lit';
+
+FormRegistry.register({
+  type: 'my-editor', // 匹配 JSON 中的 type 字段
+  render: (ctx) => html`
+    <my-editor
+      .value=${ctx.value}
+      .placeholder=${ctx.placeholder}
+      ?disabled=${ctx.disabled}
+      @change=${(e: Event) => ctx.onChange((e.target as any).value)}
+    ></my-editor>
+  `,
+  valueTransformer: (v) => v.toUpperCase(),
+  styles: 'my-editor { border: 1px solid #ccc; }',
+});
+```
+
+然后在 JSON 中使用：
+
+```json
+{ "name": "content", "type": "my-editor", "label": "内容" }
+```
+
+### 自定义提交按钮
+
+通过 slot 和 `show-submit` 属性控制操作区域：
+
+```html
+<!-- 使用 slot 添加自定义按钮，同时保留内置提交按钮 -->
+<aithe-autoform fields="[...]">
+  <aithe-button>取消</aithe-button>
+</aithe-autoform>
+
+<!-- 关闭内置提交按钮，完全使用 slot 自定义 -->
+<aithe-autoform fields="[...]" show-submit="false">
+  <aithe-button type="primary">保存</aithe-button>
+  <aithe-button>取消</aithe-button>
+</aithe-autoform>
+```
+
+---
+
+## API 参考
+
+### `<aithe-autoform>` 属性
+
+| 属性                 | 类型      | 默认值  | 说明                     |
+| -------------------- | --------- | ------- | ------------------------ |
+| `fields`             | `String`  | `'[]'`  | 字段配置的 JSON 字符串   |
+| `submit-text`        | `String`  | `''`    | 提交按钮文本             |
+| `loading`            | `Boolean` | `false` | 提交中状态               |
+| `validate-on-change` | `Boolean` | `true`  | 是否在每次变更时实时校验 |
+| `initial-values`     | `Object` / `String` | `{}` | 表单字段初始值，支持对象或 JSON 字符串，覆盖对应字段的 `dft` |
+| `show-submit`        | `Boolean` | `true`  | 是否显示内置提交按钮，设为 `false` 时使用自定义 slot |
+
+### `<aithe-autoform>` 方法
+
+| 方法          | 返回值                    | 说明                 |
+| ------------- | ------------------------- | -------------------- |
+| `validate()`  | `boolean`                 | 校验所有可见字段     |
+| `getValues()` | `Record<string, unknown>` | 获取所有可见字段值   |
+| `reset()`     | `void`                    | 重置所有字段为缺省值 |
+| `submit()`    | `void`                    | 编程触发表单校验和提交，通过后触发 `aithe-submit` 事件 |
+
+### 事件
+
+| 事件             | detail              | 说明                 |
+| ---------------- | ------------------- | -------------------- |
+| `aithe-submit`   | `{ values }`        | 有效表单提交时触发   |
+| `aithe-validate` | `{ valid, errors }` | 校验完成后触发       |
+| `aithe-change`   | `{ name, value }`   | 任意字段值变更时触发 |
+
+### `FormRegistry` API
+
+| 方法                   | 说明                 |
+| ---------------------- | -------------------- |
+| `register(definition)` | 注册自定义控件类型   |
+| `unregister(type)`     | 注销控件类型         |
+| `get(type)`            | 获取控件定义         |
+| `has(type)`            | 检查是否已注册       |
+| `types()`              | 获取所有已注册类型名 |
+
+### `FormRuleEngine` API
+
+| 方法                                 | 说明                                 |
+| ------------------------------------ | ------------------------------------ |
+| `evaluate(rules, values, baseState)` | 评估规则，返回新的 `DependencyState` |
+| `parseCondition(condition)`          | 解析条件表达式为 AST                 |
+
+---
+
+## 核心文件
+
+| 文件                                   | 职责                                                               |
+| -------------------------------------- | ------------------------------------------------------------------ |
+| `src/components/form/autoform.ts`      | `<aithe-autoform>` 表单容器组件                                    |
+| `src/components/form/autoform-item.ts` | `<aithe-autoform-item>` 表单项组件                                 |
+| `src/core/autoform/index.ts`           | `FormRegistry`、`FormRuleEngine` 导出入口                          |
+| `src/core/autoform/types.ts`           | `FormFieldConfig`、`FormRule` 等类型定义                           |
+| `src/core/autoform/autoform.ts`        | `FormRuleEngine` 依赖联动规则引擎、`FormRegistry` 自定义控件注册表 |
+| `src/core/autoform/condition.ts`       | `FormCondition` 条件表达式解析器                                   |
+| `src/apps/demo/pages/autoform.ts`      | 7 个示例配置（基础/选择/高级/校验/禁用/完整/联动）                 |

package/docs/changelog/AGENTS.md

@@ -0,0 +1,23 @@
+# docs/changelog/ — 版本变更日志
+
+## 概述
+
+记录每个版本的详细变更内容，包含版本文档和摘要索引。
+
+## 目录结构
+
+| 文件                   | 说明                 |
+| ---------------------- | -------------------- |
+| `CHANGELOG.md`         | 版本变更摘要索引     |
+| `VERSION_{version}.md` | 各版本的详细变更文档 |
+
+## 文档格式
+
+版本文档包含：版本信息、变更记录（按 Issue 分组）、概述、核心特性、组件详细列表、技术架构等。
+
+## 关键约定
+
+- **这些文件是历史记录，禁止修改已发布的版本文档**
+- 新增版本时，创建 `VERSION_{version}.md` 并更新 `CHANGELOG.md`
+- 版本号格式：`年.季度.小版本`（如 `26.2.3`）
+- 变更分类：新增 / 修改 / 删除