# TokUI DSL 语法速查（完整版）

> TokUI 是零依赖的流式 UI 描述语言。后端用 DSL 字符串描述组件，经 SSE 推送到前端，前端增量解析并渲染为真实 DOM。
> 本文件是**权威速查**：以源码为准（`src/core/parser.js` 的 `CONTAINERS` / `BOOLEAN_ATTRS`、`src/core/renderer.js` 的 `VARIANTS`、`src/components/*` 的各渲染函数）。中文文档站分册见 `docs/components/*.md`，图表细节见 `docs/components/chart.md`。

---

## 0. 铁律速记（写之前先读，违反即渲染失败）

1. **属性之间必须空格分隔**——CJK/全角字符（`（）。，！？`）后接新属性也要空格。错 `[item l:服务费（10%）tx:¥48]` → 对 `[item l:服务费（10%） tx:¥48]`。
2. **`tr` 单元格用英文逗号**，含逗号的 cell 双引号包（`[tr 1,"x,y",2]`），**tr 不要外层引号**。唯二例外：① 单元格是带空格的内联组件（`btn:`/`tag:`/`progress`/`[xxx]`）→ 整行外层引号 + `|` 分隔多钮；② **货币符号金额（`¥/$/€/£/₩` 等）千分位自动识别、无需引号**——`¥2,688.00`、`$1,234,567` 直接裸写，parser 不切。
3. **变体必须带 `v:` 前缀**，多变体逗号合并 `v:"primary,sm"`。裸写 `muted`/`primary` 会变正文乱码。
4. **`card` 有子元素时禁用 `tx`**（`tx` = 自闭合叶子卡，子内容会漏到卡外）。价签用 `[h3]`/`[stat]`。
5. **`p` 双模**：有正文=叶子自闭合（可夹内联子节点），无正文=容器 `[p]...[/p]`（放块级组件）。
6. **正文里别写 `英文:值`**（`Q:`/`A:`/`step:1` 会被当属性）→ 用全角 `：` 或双引号包。
7. **正文含字面 `[` `]` 整段双引号包**：`[item "arr[0] 与 arr[1]"]`。
8. **`chart` 属性顺序**：`t 类型 → 样式/布局 → l 标签 → 数据 d/tasks/...`（流式强约束，否则预览翻转）。
9. **组件名必须在本清单内**，禁止臆造（`barcode-box`/`price-card` 等都不存在）。
10. **正文文本块（`p`/`h1~h6`/`item`）用裸内容**，`tx:` 是 `btn`/`tag`/`callout`/`stat`/`badge` 等自闭合展示组件的文本属性。

---

## 1. 基本语法

```tokui
[h1 标题]                                    ;; 自闭合标签
[card tt:标题] 内容 [/card]                  ;; 容器标签，必须 [/type] 闭合
[btn tx:"点击我" v:primary clk:onClick]      ;; 多属性用空格分隔
[tr 张三,25,北京]                            ;; 同类型多值用逗号分隔
ph:"含空格的值"                              ;; 值含空格用双引号包裹
v:"primary,sm"                               ;; 多变体用逗号分隔，渲染器白名单校验
```

- `[type attrs... content]`：第一个 token 为组件类型，后续 `key:value` 为属性，最后剩余文本为内容。
- **容器组件**必须写闭合标签 `[/type]`，自闭合组件不能包含子元素。
- **布尔属性**只写 key 即可生效（见 §3）。
- 属性 key 须为英文标识符（`tt`/`tx`/`clk`/`data-*` 等）；含中文的 `标签:值`（如 `框架:React`）按正文处理。
- **智能变体吸收**：标签已出 `v:` 时，紧跟的裸 token 若命中该组件已知变体名，会并入 `v`（逗号续写）而非当正文。兼容 `[p v:center muted 文本]`，但仍建议规范写 `v:"center,muted"`。
- **漏空格容错**：CJK 值尾部若粘连「非 ASCII + 已知属性 key + `:`」会被自动切分（仅 CJK 边界触发，URL/时间/版本号等 ASCII 冒号值不误切）；仍以写空格为规范。
- **别名**：`ol`/`ul` → `list`（带 `t:ol`/`t:ul`）；`i` → `item`；`case` → `test-case`；`feature` → `welcome-feature`（自闭合简写）。

### 值类型与颜色

- 颜色：语义名 `primary/success/warning/danger/info/dark/light`，或 6 位 hex **不带 `#`**（`bg:FF0000`），部分组件支持 `#hex`/`rgb()`/`var(--x)`（图表 `c`）。
- 数值：纯数字（`w:480`、`span:6`、`v:72`）；含逗号/竖线/分号的值必须双引号包（`d:"1,2|3,4"`）。
- 布尔：只写 key（`stripe`、`req`、`dis`）。

---

## 2. 通用属性

| 简写 | 含义 | 说明 |
|------|------|------|
| `id` | 元素 ID | 也用于 `upd` 动态更新目标、`print:ID` / `form:ID` / `openDialog data-target` 解析 |
| `tt` | title | 提示标题 / 弹窗 / 卡片标题 |
| `tx` | text | 文本内容（自闭合展示组件专用，p/h 用裸内容） |
| `l` | label | 表单标签 / gauge 指标名 / desc 项标签 |
| `ph` | placeholder | 占位提示 |
| `u` | url | 链接地址 / gauge 单位 |
| `s` | src / source / size | 图片/视频/音频源；或尺寸（视组件） |
| `n` | name | 表单字段名、文件名 |
| `v` | value / variant | 值或变体（见 §4 与各组件） |
| `val` | value | 仅 `input`/`pwd` 用此存初值（`v` 在它们身上是变体） |
| `t` | type | 组件子类型 / 按钮变体 / 图表类型 / tag 颜色 |
| `act` | action | 表单提交地址 / `upd` 动作（`act:open`/`act:close`） |
| `mtd` | method | 表单提交方法 |
| `clk` | onclick | 点击处理器名（需 `TokUI.registerHandler` 预注册） |
| `sub` | onsubmit | 提交处理器名 / 按钮内置提交动作 |
| `dis` | disabled | 禁用 |
| `ro` | readonly | 只读 |
| `req` | required | 必填 |
| `chk` | checked | 选中 |
| `multi` | multiple | 多选 |
| `opt` | options | 选项简写串 `v:label;…`，radio/checkbox/select 共用，**必须双引号** |
| `w` `h` | width / height | 宽 / 高 |
| `bg` `fc` | background / font-color | 背景色 / 文字色 |
| `target` | target | `a` 打开方式，默认 `_blank` |
| `alt` | alt | `img` 替代文本 |
| `pos` | position | `top/bottom/left/right`（tooltip/drawer/popover/popconfirm/hover-card 等） |
| `icon` | SVG 图标名 | btn / 表格操作列，取内置 Lucide 图标（见 §7），stroke=currentColor 自动配色 |
| `i` | emoji / 字符图标 | btn / menu-item / welcome-feature |
| `form` | 表单 ID | btn 显式绑定表单（按钮在 form 外时收集其数据） |
| `reset` | 重置动作 | btn 内置：裸写或 `reset:H` |
| `print` | 打印动作 | btn 内置：`print:ID` / `print:self` / 裸写 |
| `data-*` | 任意自定义数据 | 透传为 `data-*` 属性（如 `data-prompt:`、`data-target:`） |
| `cls` | 自定义类名 | **全组件**根元素追加类名（空格分隔多个，**含空格必须双引号**），见 §2.1 |
| `style` | 内联样式 | **全组件**根元素白名单内联样式（**含空格必须双引号**），见 §2.1 |
| `on` | 事件上报声明 | `on:"事件:处理器,…"`（**必须双引号**），如 `on:"change:onInput,close:onClose"`，见 §8.4 |

> `clk:` / `sub:` 处理器签名 `(data, event, element)`；表单按钮的 `data` 为 `_collectFormData(form)` 收集结果，同 name 多值自动聚合为数组。

### 2.1 样式定制通道：`cls:` / `style:`（全组件根级）

两个通用属性对**全部已注册组件**生效，集中落在组件根元素上（`src/core/style-guard.js` 安全过滤）：

```
[card tt:渐变品牌卡 cls:"pricing fade-in" style:"background:linear-gradient(135deg,var(--tokui-primary-1),var(--tokui-bg));border-radius:16px"]
[btn t:primary cls:cta-btn style:"border-radius:16px"]   ← 单类名/无空格值可不加引号
[p 导语文字 cls:lead style:"font-size:22px;font-weight:700;letter-spacing:1px"]
```

**`style:` 白名单（属性名）**：`background(-image/-color/-size/-position/-repeat/-clip)`、`color`、`border`（含四边/圆角全套）、`padding`/`margin`（含四边）、`text-align`、`text-decoration`、`letter-spacing`、`line-height`、`(max/min)-width/height`、`box-shadow`、`opacity`、`font-size/weight/family`、`overflow(-x/-y)`、`cursor`、`gap`/`row-gap`/`column-gap`、`display`、`flex`（direction/wrap/grow/shrink/basis）、`order`、`align/justify-*`、`width`/`height`、`white-space`、`word-break`、`vertical-align`、`transition`、`transform`、`backdrop-filter`、`aspect-ratio`、`object-fit/-position`、`z-index`、`list-style`、`grid-template-columns/rows`。

**值级安全规则**（违规声明**静默丢弃**，其余声明正常生效）：
- 拒绝 `expression(...)`、`javascript:`、`vbscript:`、`behavior:`、`@import`、尖括号；
- `url()` 仅放行 `http(s)://` 绝对地址与站内相对路径（`/x`、`./x`、`../x`）；`data:`/`ftp:` 等拒绝；
- `transform` 仅放行 `translate/scale/rotate` 函数族（`matrix` 等拒绝）；
- **不在白名单**：`position`、`top/left/right/bottom`（防布局逃逸伪造遮罩）。

**`cls:` 规则**：每个类名须匹配 `^[a-zA-Z][\w-]{0,63}$`（字母开头，1~64 字符）；**拒绝 `tokui-` 前缀**（框架保留字）；最多 8 个、自动去重；非法词逐个静默丢弃。

> 通道定位是「根级增强」：只落组件根元素、内部元素不透传；与组件私有 `w:`/`bg:`/`fc:`/`hc:` 等散点属性叠加共存（`style:` 声明追加在私有样式之后，同名属性以 `style:` 为准）。未知组件降级（`tokui-unknown`）不走此通道。

---

## 3. 布尔属性

只写 key 即生效（出现即为 true）。完整列表以 `parser.js` 的 `BOOLEAN_ATTRS` Set 为准：

```
stripe  dis  ro  req  chk  multi  disabled  readonly  required  checked  multiple  striped
auto  plain  round  closable  bordered  open  pill  dot  leaf  inline  rounded  container
copy  regenerate  like  dislike  visible  delete  controls  active  collapsible  collapsed  toggle
search  thumb  reset  print  approval  streaming  mask
```

> `reset` / `print` 是按钮内置动作；`thumb`/`delete` 多用于 `msg-actions` 等生成默认按钮；`controls` 用于 `video` 显示原生控件栏；`leaf` 让 `tn` 自闭合；`collapsible` 用于 `sidebar`；`collapsed` 让 `tool-call` 初始收起（§6.4）；`approval` 让 `tool-call` 进入人工审批模式（§6.4）；`streaming` 让 `chat-input` 显示停止生成按钮（§6.4）。

> ⚠️ **布尔属性没有「false 值」**：出现即为 true。想表达「初始不禁用」就**省略该属性**，不要写 `dis:false`——初始渲染时 `'false'` 是字符串（truthy），照样禁用。只有 `upd` 指令里 `dis:false` / `ro:false` / `chk:false` 才是「主动关闭」语义（渲染端判 `=== 'false'`，见 §8.1）。

---

## 4. 变体系统

DSL 写 `v:primary` → 渲染器生成 CSS 类 `tokui-{type}--primary`。多变体逗号组合：`v:"primary,sm,pill"`。变体名经 `renderer.js` 的 `VARIANTS` 白名单校验，未知变体**静默丢弃**。

**完整白名单**（以 `VARIANTS` 为准）：

| 组件 | 允许的变体 |
|------|-----------|
| `btn` | `primary` `danger` `success` `warning` `ghost` `sm` `lg` `pill` `square` `block`（图标走 `icon:` / `i:` 属性，非变体） |
| `btngroup` | `vertical` `pill` |
| `card` | `highlight` `flat` `bordered` `center` `right` |
| `table` | `bordered` `compact` |
| `h1`~`h6` | `left` `center` `right` `ribbon` `underline` `badge` `pill` |
| `p` | `left` `center` `right` `muted` `bold` `sm` `lg` |
| `a` | `muted` `danger` `success` `underline` |
| `ft` | `left` `center` `right` |
| `row` | `left` `center` `right` `inline` |
| `dv` | `dashed` `dotted` `sm` `md` `lg` `vert` `plain` |
| `img` | `avatar` `rounded` `bordered` |
| `dot` | `sm` `lg` |
| `avatar` | `sm` `md` `lg` `xl` |
| `tooltip` `drawer` | `top` `bottom` `left` `right` |
| `pagination` `switch` `slider` `rate` `transfer` `upload` `tree` | `sm` `lg` |
| `input` `pwd` | `error` `success` `sm` `lg` `underline` `pill`（另有 `inline` 非白名单，单独处理） |
| `select` `picker` `cascader` | `error` `success` |
| `breadcrumb` | `arrow` |
| `menu` | `horizontal` `inline`（`vertical` 为默认无类；历史别名 `v:h` 归一为 `horizontal`） |
| `segmented` | `sm` `lg` `block` `pill` `vertical` |
| `anchor` | `horizontal` |
| `kbd` | `sm` `lg` |

> `radio`/`checkbox` 的 `v:inline`（标签与控件同行）/ `v:vertical`（竖排左对齐）是**手动标记**，不在 `VARIANTS` 白名单内，由组件自身解析；二者互斥。`timeline` 的 `v:h`/`horizontal`/`alt`/`alternate`/`card`、`steps` 的 `vd:v`/`vertical` 同理。注意 `steps`/`tabs` 的 `v` 是**值语义**（当前步序号 / 激活页序号，见 §8.1），不是外观变体。

---

## 5. 容器与自闭合规则

**容器组件**（在 `CONTAINERS` Set 内，需 `[/type]` 闭合）：

```
form table thead tbody card ft row col list select radio checkbox code imgs md
textarea tabs tab accordion collapse dialog btngroup picker timeline steps drawer
ol ul i item think think-chain think-step bubble toolbar badge-box dropdown transfer callout
cascader tree tn desc carousel popover input-tag watermark menu print-area
chat-input msg-actions tool-call diff quick-reply plan file-tree ft-folder
terminal sandbox test-result quote toggle-group conversations welcome welcome-feature
suggestions attachments artifact artifact-code artifact-preview scroll-area
sidebar sidebar-content sidebar-footer command command-group hover-card hover-trigger hover-content
resizable canvas canvas-content chart p tour affix preview-group segmented anchor float-button masonry
panel kpi scrollboard fit-screen page page-header page-sidebar page-content page-tabs page-tab
```

**自闭合逃逸**（在容器清单内但特定条件下自动当自闭合叶子）：

- 有 `tx` 属性的容器 → 自闭合（`[callout t:info tx:说明]`），**除外**：`tn` / `popover` / `input-tag` / `watermark` / `badge-box`（其 `tx` 是触发文本/水印文本，不当 body）。
- `tn` 带 `leaf` → 自闭合叶子节点。
- `input-tag` 带 `tags` → 自闭合（初始标签串）。
- `radio`/`select`/`checkbox` 带 `opt:"..."` → 自闭合简写。
- `checkbox` 单布尔（无 `opt` 无 `multi`）→ 自闭合（legacy 兼容）。
- `thead` 带 `cols` → 自闭合（多行表头串）。
- `chart` 带 `d`/`tasks`/`rows`/（`nodes`+`flows`）/（`gauge`/`progress` 的 `v`）→ 自闭合；否则容器模式收 `pt`/`hrow`/`flow`/`task`/`ms` 子节点。
- `desc`/`suggestions`/`chart` 的 `cols` 是数据/布局属性，**不**触发自闭合。

**原始内容模式**（容器内 `[` 视为字面文本，直到 `[/type]`）：`code`、`md`、`diff`、`terminal`、`sandbox`、`artifact-code`。

---

## 6. 组件分册

### 6.1 文本与基础

| Tag | 类型 | 常用属性 | 说明 |
|-----|------|----------|------|
| `h1`~`h6` | 自闭合 | `tx`/裸内容 `v` `bg` `fc` | 标题。`v:underline` 时 bg 走 `::after` 下划线色；其余变体见 §4 |
| `p` | 叶子/容器 | `v` 裸内容 | 段落，**双模**：有正文=叶子自闭合（内联白名单 `a`/`tag`/`b`/`strong`/`em`/`mark`/`spin`/`sub`/`sup`/`code`/`i`/`kbd`），遇块级兄弟自动闭合；无正文=容器 `[p]...[/p]` 放块级组件 |
| `a` | 自闭合 | `u` `tx`/裸内容 `tt` `target` `dis` `v` | 链接。href 协议白名单 `http(s)`/`mailto`/`tel`/`/`/`#`，其余强制 `#` |
| `img` | 自闭合 | `s` `alt` `w` `h` `tt` `v` | 图片，点击灯箱预览。变体 `avatar`/`rounded`/`bordered` |
| `preview-group` | 容器 | `id` | 图片预览组。子项 `img` 共享灯箱预览会话（缩放/旋转/翻转/计数/前后切换），流式后到的图自动入组；与 `imgs`（九宫格简写布局）不同，是显式「一组图共享预览」语义，排版照旧 |
| `hr` | 自闭合 | — | 水平分割线 |
| `dv` | 自闭合 | `tx`/裸内容 `v` `vert` `size` `align` `bg` `th` `plain` | 带文本分割线。`vert` 垂直，`align` 对齐，`th` 边框宽度 |
| `md` | 容器·原始 | — | Markdown 渲染（表格/列表/任务/引用/代码围栏/链接图片）。可选插件增强：` ```mermaid ` 围栏与 `$$公式$$`/`$公式$` 在宿主加载 mermaid/katex 全局对象时自动增强渲染，无插件回退源码展示（零依赖不受损） |
| `katex` | 容器·原始/自闭合 | `f` | 独立公式组件（md KaTeX 管线别名）。容器 `[katex]公式[/katex]` 块级；`[katex f:"公式"]` 行内。宿主加载 katex 才渲染，无插件回退源码。内容为 raw 且豁免转义解码，LaTeX 命令（`\nabla`/`\times`/`\to` 等）按标准语法直接书写 |
| `mermaid` | 容器·原始 | — | 独立图组件（md mermaid 管线别名）。`[mermaid]图源[/mermaid]`，宿主加载 mermaid 才渲染，无插件回退代码块 |
| `code` | 容器·原始 | `lang` | 语法高亮代码块，带复制按钮 + 行号。`lang`：`js`/`ts`/`py`/`html`/`css`/`sql`/`json`/`java`/`go`/`rust`/`bash` 及别名 |
| `tag` | 自闭合 | `tx` `t` `s` `round` `bordered` `closable` `dis` `bg` `fc` | 标签。颜色用 `t:`（`default`/`primary`/`success`/`warning`/`danger`/`info`），尺寸 `s:small`/`medium`/`large` |
| `kbd` | 自闭合 | 裸内容/`tx` | 键盘按键（行内键帽）。变体 `sm`/`lg`；可作 `p` 行内子节点与文字混排 |
| `b`/`strong`/`em`/`mark`/`del`/`sub`/`sup` | 自闭合 | 裸内容 | 行内格式（加粗/斜体/高亮/删除/上下标） |

### 6.2 状态、反馈与交互

| Tag | 类型 | 常用属性 | 说明 |
|-----|------|----------|------|
| `callout` | 自闭合/容器 | `t` `tt` `tx`/裸内容 | 警示框。`t:info`/`success`/`warning`/`error`/`tip`。流式优先容器模式 `[callout t:info]文[/callout]`（真流式）；自闭合 `tx:` 一次性 |
| `spin` | 自闭合 | `t` `s` `tx` | 加载指示器。`t:spinner`/`dots`/`pulse` |
| `skeleton` | 自闭合 | `t` `rows` `w` `h` | 骨架屏。`t:text`/`card`/`avatar`/`image` |
| `shimmer` | 自闭合 | `t` `rows` | 闪光骨架。`t:text`/`card`/`avatar` |
| `empty` | 自闭合 | `tx` `icon` `s` | 空状态。`icon:default`/`box`/`folder`/`search`；`s` 自定义图源 |
| `result` | 自闭合 | `t` `tt` `tx` | 结果页。`t:success`/`error`/`warning`/`info` |
| `barcode` | 自闭合 | `tx` `l` `s` | Code128 Set B 条码（纯 SVG，扫描器识别）。`s:sm`/`md`/`lg`。运单号/订单号/序列号 |
| `qrcode` | 自闭合 | `tx` `l` `s` `ec` | QR 二维码（纯 SVG）。`ec:L`/`M`/`Q`/`H`（默认 M）。URL/文本/UTF-8/Wi-Fi |
| `dot` | 自闭合 | `t` `tx` `s` `pulse` | 状态点。`t:success`/`warning`/`error`/`info`/`primary` |
| `badge` | 自闭合 | `count` `overflow` `dot` `t`/`status` `tx` `pill` `size` `title` | 徽标。`count` 0-999，`overflow` 默认 99；版本号/小数用 `tx`（`count` 走 parseInt 会截断） |
| `badge-box` | 容器 | `t`/`status` `dot` `count` `overflow` `tx`/`label` `size` | 包裹子元素 + 角标（点/数字/文字）。`t` 颜色 |
| `toast` | 自闭合 | `id` `t` `tx` `duration` `pos` | 全局 Toast。`pos:top`/`bottom`，`duration` 默认 2000ms |
| `notification` | 自闭合 | `id` `t` `tt` `tx` `duration` `pos` `clk` | 全局通知。`pos:top-right` 等，`duration` 默认 4500ms（0=手动） |
| `progress` | 自闭合 | `v` `t` `l` `s` `stripe` `status` `id` | 进度条。`v` 百分比 0-100；`t:line`/`circle`/`span`；`status:success`/`error` |
| `stat` | 自闭合 | `tt` `v` `pre` `suf` `trend` `anim` `dec` `l` `id` | 统计数字。`pre:¥` `suf:%` `trend:up`/`down` `anim` 滚动动画 ms `dec` 小数位；`tt` 顶部标题、`l` 底部小标签 |
| `countdown` | 自闭合 | `target`/`dur` `fmt` `tx` `l` `s` `clk` `id` | 倒计时。`target` ms 时间戳或 `dur` 秒；`fmt:dhms`/`hms`/`ms`/`s`（每字母启用一单位）；`clk` 结束回调 |
| `thumb` | 自闭合 | `t` `v` `s` `clk` | 赞/踩。`t:up`/`down`，点击 emit `{direction, active}`（clk 通道）；统一出口上报 `like` `{value:'up'/'down'}`（§8.4） |
| `toggle` | 自闭合 | `tx` `chk` `clk` `s` `dis` | 切换按钮 |
| `toggle-group` | 容器 | `multi` `s` `clk` | 切换按钮组。单选互斥（默认）/`multi` 多选；子项 `toggle` |
| `copy` | 自闭合 | `id` `tx` `tt` | 复制到剪贴板。`id` 目标元素，`tx` 按钮文字，`tt` 成功提示 |
| `upd` | 自闭合 | `id` + 更新键 | 动态更新已渲染组件（`v`/`tx`/`dis`/`tt`/`status`/`act`/`trend`/`count`/`chk` 等，取决于目标 `_update`） |
| `tooltip` | 自闭合 | `tt` `pos` `tx`/裸内容 | 文字提示。`pos:top`/`bottom`/`left`/`right` |
| `popover` | 容器 | `tx` `tt` `pos` `w` `trig` | 气泡卡片。`trig:click`/`hover` |
| `popconfirm` | 自闭合 | `tt` `tx` `clk` `t` `pos` `ok-text` `cancel-text` | 确认气泡。`t:primary`/`danger`；`ok-text`/`cancel-text` 自定义按钮文字 |
| `hover-card` | 容器 | `pos` `w` `delay` | 悬停卡片。子项须为 `hover-trigger` + `hover-content` |
| `hover-trigger` / `hover-content` | 容器 | — | `hover-card` 的子结构 |
| `input-tag` | 容器 | `ph` `n` `id` `max` `tags` `clk` `l` | 标签输入框。带 `tags` 自闭合（初始逗号分隔标签）；Enter 添加/Backspace 删除 |
| `dropdown` | 容器 | `tx`/`tt` `v` | 下拉菜单。`v` 按钮变体；子项 `dd-item`；键盘导航 |
| `dd-item` | 自闭合 | `tx` `clk` `dis` `v` | 下拉菜单项 |
| `backtop` | 自闭合 | `t` `v` `tx` `s` `bottom` `right` `container` | 回到顶部。`t` 滚动阈值 px；`v:circle`/`round`/`square` |
| `pagination` | 自闭合 | `page` `total` `count` `show-total` `s` `clk` | 分页。点击 emit `{page}` |
| `breadcrumb` | 自闭合 | `items` `sep` `clk` `v` | 面包屑。`items` 逗号路径；`v:arrow` 用 › |
| `calendar` | 自闭合 | `month` `v` `tt` `marks` `sel`/`selected` `range` `ranges` | 日历。`v:card`/`mini`；`marks:"3,15"` 标记日；`sel:"15,20"` 离散选中；`range:"15-21"` 单区间；`ranges:"1-3;15-21"` 多区间 |
| `watermark` | 容器 | `tx` `s` `font` `c` `gap` `ro` | 水印容器。`ro` 旋转角度（默认 -22），`gap` 间距（默认 40），canvas 平铺 |
| `avatar` | 自闭合 | `s` `tx` `size` `bg` `fc` | 头像。无 src 时文字头像（取前 2 字），无 bg 时按 hash 自动配色 |
| `file` | 自闭合 | `n` `s` `t` `u` `tt` | 文件卡片。`t:pdf`/`word`/`excel`/`ppt`/`image`/`zip`/`code`/`default` |
| `chat-input` | 容器 | `ph` `clk` `dis` `max` `auto` `rows` `streaming` `mention` `on` | 对话输入框。Enter 发送/Shift+Enter 换行；Enter/发送按钮触发 clk handler，负载 `{value}`；`streaming` 显示停止生成按钮（`on:"stop:h"` 或默认断开 SSE，见 §8.4）；`mention:数据源handler名` 启用 @ 提及下拉（数据源 fn({value:查询词}) 返回数组或 Promise，项为字符串或 `{v,tx}`；↑↓ 导航 Enter 选定，选定上报 `mention` 事件）；`id` 落 DOM，`dis`/`streaming` 经 `[upd id:x …]` 全通路生效（§8.1） |
| `msg-actions` | 容器 | `clk` `copy` `regenerate` `like`/`dislike` `delete` `visible` | 消息操作栏。布尔属性生成默认按钮 |
| `tour` | 容器 | `open` `mask` `id` `on` | 漫游引导；子项 `tour-step`（自闭合标记：`tgt` 目标元素 id（可带 `#`）/`tt` 标题/`tx` 说明/`pos` 面板方位，默认 bottom；无 `tgt` 居中显示）。`open` 容器闭合后自动开启；`mask:false` 关遮罩（默认开）；键盘 Esc 关、←/→ 切步；事件 `change`（切步 `{index,target}`）/`finish`（完成）/`close`（跳过·✕·Esc）；upd 契约 `act:open`（`v` 可选起始步）/`act:goto v:N`/`act:close`，程序化均 silent 不上报 |
| `modal.confirm` | 命令式 API | `TokUI.modal.confirm(opts)` / `TokUI.confirm(opts)` | 命令式确认对话框（宿主侧 JS API，非 DSL）。opts `{tt, tx, t:'danger'|'primary', 'ok-text', 'cancel-text', onOk, onCancel}` → `Promise<boolean>`；Esc/遮罩点击=取消；按钮与 aria 文案走 i18n（`common.ok`/`common.cancel`/`modal.aria`） |

### 6.3 思考与计划

| Tag | 类型 | 常用属性 | 说明 |
|-----|------|----------|------|
| `think` | 容器 | `tt` `open` | 思考块（`<details>` 折叠），默认展开 |
| `think-chain` | 容器 | `tt` `status` `open` | 推理链。`status:running`/`done`；子项 `think-step` |
| `think-step` | 容器 | `status` `tt` `dur` | 推理步骤。`status:done`/`running`/`pending`/`error` |
| `plan` | 容器 | `tt` | 执行计划；子项 `plan-step` |
| `plan-step` | 自闭合 | `status` `tt` `desc` `id` | 计划步骤。`status:pending`/`doing`/`done`/`error`/`skipped`（接受 `running`/`complete`/`fail` 等同义词，upd 同表归一化）；带 `id` 可经 `[upd id:x status:doing]` 逐步推进（支持 `status`/`tt`/`desc`，见 §8.1） |
| `agent` | 自闭合 | `name` `status` `action` `duration` `id` | 智能体状态。`status:idle`/`running`/`paused`/`done`/`error` |

### 6.4 AI / 对话

| Tag | 类型 | 常用属性 | 说明 |
|-----|------|----------|------|
| `bubble` | 容器 | `role` `model` `time` | 对话气泡。`role:user`/`ai`/`system`（chat 场景系统已包气泡，勿嵌套） |
| `toolbar` | 容器 | `pos` `align` | 工具栏。`pos:top`/`bottom`，`align:left`/`center`/`right` |
| `tool-call` | 容器 | `name` `status` `duration` `id` `approval` `collapsed` `clk` | 工具调用卡片。`status:pending`/`running`/`done`/`error`/`denied`；`collapsed` 初始收起 body（header 点击 / Enter/Space 收展，`aria-expanded` 同步，状态徽章常显；body 只切 display 不销毁内容，`upd` 改状态保留收展态）；`approval` + `status:pending` 渲染批准/拒绝按钮（HITL 人工审批），决定经 `clk` handler 或 `on:"approval:h"` 回传 `{approved, id, name}`（§8.4），后续状态用 `upd` 推送 |
| `typing` | 自闭合 | `text` | 输入中指示（注意用 `text` 非 `tx`） |
| `quick-reply` | 容器 | `items` `clk` | 快捷回复。`items` 逗号标签；或子节点追加 |
| `suggestions` | 容器 | `cols` `clk` `id` | 建议卡片网格。`cols` 1-4（默认 2）；子项 `suggestion` |
| `suggestion` | 自闭合 | `tt` `tx` `clk` `icon` `dis` | 建议项 |
| `source` | 自闭合 | `n` `tt` `sn` `u`/`url` | 引用源。`n` 序号，`sn` 片段 |
| `diff` | 容器·原始 | `title` `lang` | 代码差异。内容行以 `+` 增（绿）/`-` 删（红）/其它上下文 |
| `file-tree` | 容器 | — | 文件树；子项 `ft-folder` / `ft-file` |
| `ft-folder` | 容器 | `name` `open` | 文件夹 |
| `ft-file` | 自闭合 | `name` `badge` | 文件 |
| `terminal` | 容器·原始 | `title` `status` | 终端输出。`status` 非 0 则 error 样式 |
| `sandbox` | 容器·原始 | `lang` `title` `height` | 代码预览沙箱。`lang:html` 用 iframe srcdoc 沙箱；否则 `<pre>` |
| `test-result` | 容器 | `pass` `fail` `skip` `total` `duration` | 测试结果；子项 `test-case` 或 `case`（推荐 `case`） |
| `test-case` / `case` | 自闭合 | `status` `name` `duration` `error` | 测试用例。`status:pass`/`fail`/`skip`；`case` 是简写别名 |
| `commit` | 自闭合 | `hash` `msg` `author` `branch` `time` `additions` `deletions` | Git 提交 |
| `quote` | 容器 | `role` `tx` `msgid` | 引用消息 |
| `latency` | 自闭合 | `v` `t` | 延迟指标。`t:thinking`/`generating`/`total` |
| `video` | 自闭合 | `s` `poster` `ratio` `w` `h` `fit` | 视频。`ratio:16:9`/`4:3`/`1:1`/`21:9`；`fit:cover`/`contain`/`fill`；poster 与画面共用同一比例盒 |
| `audio` | 自闭合 | `s` `tt` `duration` `w` | 音频播放器 |
| `conversations` | 容器 | `clk` `act` | 会话列表；子项 `conv`；按 `time` 自动分组 今天/昨天/更早。`clk` 选中回调 emit `{tt, time, act}`（流式同样生效） |
| `conv` | 自闭合 | `tt` `time` `active` `act` | 会话项 |
| `welcome` | 容器 | `tt` `st` `bd` `hd` `ft` | 欢迎页。`st` 副标题、`bd` 能力徽标（逗号）、`hd` 卡分区标题、`ft` 页脚引导语；子项 `welcome-feature`/`feature` |
| `welcome-feature` / `feature` | 容器/自闭合 | `tt` `tx` `i` `clk` | 欢迎特性卡片。`i:code`/`chart`/`doc`/`dashboard`/`print`/`chat`/`table`/`form`；推荐简写 `feature`（自闭合） |
| `attachments` | 容器 | `clk` | 附件列表；子项 `attach` |
| `attach` | 自闭合 | `t` `s` `u` `size` `clk` | 附件项。`t:image`/`pdf`/`word`/`excel`/`ppt`/`zip`/`code`/`video`/`audio` |
| `artifact` | 容器 | `tt` `lang` `pos` `w` | Artifact 侧边预览。`pos:left`/`right`，`w` 百分比；子项 `artifact-code` + `artifact-preview` |
| `artifact-code` | 容器·原始 | — | Artifact 代码槽 |
| `artifact-preview` | 容器 | — | Artifact 预览槽 |
| `command` | 容器 | `ph` `clk` `id` `hotkey` | 命令面板。`hotkey` 启用 Cmd/Ctrl+K（页面只应一个）；按钮唤起 `clk:openCommand data-target:"<id>"`；子项 `command-group`。选中项时根 `clk` 回调 emit `{value, text, clk}`；统一出口上报 `select` `{value, text}`（§8.4）；点面板空白不触发 |
| `command-group` | 容器 | `tt` | 命令分组；子项 `command-item` 或 `item`（等价，推荐 `item`） |
| `command-item` | 自闭合 | `tx` `v` `clk` `shortcut` | 命令项，`clk` 选中回调 emit `{value, text}`；推荐改用 `item`（command-group 内行为一致） |
| `canvas` | 容器 | `tt` `pos` `w` `tx` `open` `closable` | 画布面板。`pos:left`/`right`，`w` px；子项 `canvas-content` |
| `canvas-content` | 容器 | — | 画布内容（透传） |

### 6.5 布局容器

| Tag | 类型 | 常用属性 | 说明 |
|-----|------|----------|------|
| `card` | 容器 | `tt` `tx` `v` `w` `hc` `ht` | 卡片。`hc` 头部自定义色；`ht:fill`/`accent`/`underline`/`dot`/`pill` 头部类型。**`tx`=自闭合叶子卡**，有子元素时禁用 |
| `ft` | 容器 | `tx`/裸内容 `v` | 卡片页脚（card/dialog/drawer 内自动分离为页脚区）。无内容时不渲染 |
| `row` | 容器 | `v` `gutter` `gy` | 栅格行。默认 12 列 grid；`v:inline` 转 flex（并排标题+徽标用）；`gutter` 统一间距、`gy` 行间距（数字按 px 或 CSS 长度） |
| `col` | 容器 | `span` `offset` `rspan` `xs` `sm` `md` `lg` `xl` | 栅格列（`span` 1-12，默认 1）；`offset` 左空列数（1-11，offset+span 钳制不超 12）；`rspan` 行跨（1-12，多行 row 跨行用）；断点属性见下方「响应式断点」节 |
| `grid` | 容器 | `cols` `rows` `areas` `gap`/`gx`/`gy` `h` `minh` `theme` `v` `skel` `xs` `sm` `md` `lg` `xl` | 高级二维网格（与 12 栅格并行），语法见下方「高级网格 grid/cell」专节；断点属性=列数 1-12，见「响应式断点」节；流式+areas 时按区名先铺骨架占位（布局即终布局，真实 cell 到达按区替换，`skel:"false"` 关） |
| `cell` | 容器 | `area` `c` `r` `align` `justify` | grid 子项（可装任意组件）。`area` 模板区域名；`c` 列跨 N(1-24) 或 `"start/end"`；`r` 行跨 N(1-24)；`align`/`justify` 对齐 start/center/end/stretch。定高行内内容超高会被裁剪在本格（防护叠压，不蔓延邻区）；定高格内子项布局用嵌套 grid，勿用 row/col |
| `list` | 容器 | `t` `plain` | 列表。`t:ol` 有序/默认无序；`plain` 去标记 |
| `item` | 容器 | `tx`/裸内容 `l` `span` | 同名按父级区分：`list` 内=`<li>`（文本当首段，可嵌套子 `list`，靠 `[/item]`/下个 `[item]`/父闭标签隐式闭合）；`desc` 内=描述项（`l` 标签 `tx` 值）；`carousel` 内=幻灯片；`command-group` 内=命令项。别名 `i` |
| `tabs` | 容器 | — | 标签页容器；子项 `tab`；默认激活第 0 个 |
| `tab` | 容器 | `tt` | 标签项（`tt` 为标签名） |
| `accordion` | 容器 | — | 手风琴；子项 `collapse` |
| `collapse` | 容器 | `tt` `open` `id` | 折叠面板（原生 details）。`upd` 支持 `act:open`/`act:close` |
| `dialog` | 容器 | `tt` `id` `clk` `w` | 对话框（原生 dialog）。`upd` 支持 `act:open`/`act:close`；`w` 弹窗宽 px（480~1200 落 max-width，默认 480）——编辑表单（cols:2/transfer）等宽内容用 `w:720` |
| `drawer` | 容器 | `tt` `pos` `w` `h` `id` | 抽屉。`pos:left`/`right`/`top`/`bottom` |
| `imgs` | 容器 | `s` | 图片网格（`s` 逗号图源，或子项 `img`）；点击灯箱 |
| `timeline` | 容器 | `v` | 时间轴。`v:h`/`horizontal`/`alt`/`alternate`/`card`；子项 `ti` |
| `ti` | 自闭合 | `tm` `t` `tt` 裸内容 | 时间轴项。`t:primary`/`success`/`warning`/`error`/`info` |
| `steps` | 容器 | `v` `s` `vd` `id` | 步骤条。`v` 当前步（1-based）；`vd:v`/`vertical`；子项 `step` |
| `step` | 容器 | `tt` `status` 裸内容 | 步骤。`status:error`/`danger` |
| `desc` | 容器 | `cols` `stripe` `bordered` `v` `lw` | 描述列表。`cols` 每行列数；`v:h`/`horizontal`；`lw` 标签宽；子项 `item`（推荐）或 `desc-item` |
| `desc-item` | 自闭合 | `l` `tx` `span` | 描述项；推荐改用 `item`（desc 内自动按描述项渲染） |
| `carousel` | 容器 | `id` `auto` `thumb` `w` `h` `ratio` | 轮播。`auto` 毫秒自动播放；`thumb` 缩略图图例；`ratio:16:9`/`4:3`/`1`；子项 `carousel-item`/`item`/`img` |
| `carousel-item` | 自闭合 | `s` `tt` `tx` | 轮播项 |
| `tree` | 容器 | `id` `l` `clk` `chk` `dis` | 树。`chk` 可勾选（父子联动）；子项 `tn` |
| `tn` | 容器/自闭合 | `v` `tx` `open` `leaf` `chk` `dis` `load` | 树节点。`leaf` 自闭合；可递归嵌套 `tn`；`load:数据handler名` 懒加载（首次展开调 fn({id,value})，返回子节点对象数组或 Promise，加载完成上报 `load` 事件） |
| `menu` | 容器 | `v` `act` `bg` `fc` `id` | 菜单。`v:vertical`/`horizontal`/`inline`；子项 `menu-item` |
| `menu-item` | 自闭合 | `tx` `clk` `i` `dis` `act` | 菜单项 |
| `resizable` | 容器 | `dir` `min` `max` `default` `w` | 分割面板。`dir:h`/`v`；须 2 个子面板 |
| `scroll-area` | 容器 | `h` `w` `minh` `maxh` `dir` `id` `virtual` `ih` | 智能滚动区域。`h`/`w` 纯数字按 px（亦可 `100%`/`50vh`），宽缺省 100%；`minh`/`maxh` 弹性高度（内容少时收缩、多时封顶）；`dir:x` 仅横向 / `dir:y` 仅纵向（缺省双向按需）；变体 `v:flush` 去内边距。滚动条默认隐藏，hover / 滚动中（停止 0.8s 淡出）/ 键盘聚焦时浮现，色随 `--tokui-scrollbar-*` 主题令牌四主题适配。`virtual` 虚拟滚动（均匀行高模式，`ih:N` 行高默认 36px，仅可视窗口+buffer 挂 DOM）；滚动到底部阈值上报 `loadmore` 事件（长列表/对话历史加载更多用） |
| `sidebar` | 容器 | `w` `pos` `collapsible` `tt` `bg` `fc` `id` | 侧边栏。`pos:left`/`right`；子项 `sidebar-content` / `sidebar-footer` |
| `sidebar-content` / `sidebar-footer` | 容器 | — | 侧边栏内容区 / 页脚 |
| `anchor` | 双模式 | `opt` `top` `on` `id` | 锚点导航。简写 `opt:"目标id:标题;…"` 原子自闭合；容器 `[lk h:目标 tx:标题 d:层级]` 支持二级锚点；`top` spy 激活偏移（缺省 12）；变体 `horizontal`；点击平滑滚动 + scroll-spy 高亮（目标需带 id）；`upd v:目标id` 程序化高亮（silent） |
| `affix` | 容器 | `top` `bottom` `target` `on` | 固钉。滚动越过偏移即 `position:fixed` 固定：`top` 固顶（缺省 0）/ `bottom` 固底（经过原位置后释放）/ `target` 显式滚动容器；自动插占位防跳动；`change` 上报 `{fixed}`；监听 window 捕获阶段，嵌套滚动容器可感知 |
| `masonry` | 容器 | `cols` `minw` `gap` | 瀑布流。`cols` 固定列数(1-6 缺省2)、`minw` 自动列（子项最小宽度 px，列数随宽度自适应，优先于 cols）、`gap` 间距(px 缺省8)；CSS columns 自动分列，子项 break-inside: avoid 不截断 |
| `panel` | 容器 | `tt` `v` `theme` | 数据大屏科技边框容器（M1）。`tt` 标题栏（左右装饰线）；`v:corner` 四角角标 / `v:glow` 发光 / `v:plain`；`theme:tech` 子树切换科技主题 |
| `kpi` | 容器 | `tt` `v` `pre` `suf` `unit` `trend` `dec` `icon` `clk` `t` | 指标卡（M1）。数值滚动动画（easeOutExpo）；`trend:12.4`/`-1.2`/`up`/`down` 自动 ↑↓ 徽章着色；`t:danger/success/warning` 状态色；`icon:` 注册表图标；`[upd id: v:/trend:/tt:]` 更新走动画 |
| `flip-num` | 自闭合 | `v` `dur` `s` | 数字翻牌器（M1）。`v` 数字串（可含逗号/小数点/百分号，逐位翻牌）；`dur` 单位过渡 ms 默认 600；`s:sm/lg` 尺寸档；reduced-motion 直显；`[upd v:]` 各位滚到位 |
| `chart t:map` | 自闭合 | `region` `d` `label` `unit` `vmin` `vmax` `w` `on` | 中国地图。`region:"浙江:86\|江苏:74"` 省级热力（34 省级行政区含港澳台，省名简称/全名均可；多 stop 色阶 蓝→青→绿→黄→红）；`d:"120.15,30.28,88,name:杭州"` 散点层（经纬度+值+名称，对数映射半径，越界钳制画布内）；`label:full\|name\|off` 标注三档（默认 full：含数据省 名+值 两行、无数据省灰名，文字盒碰撞自动避让；name=仅含数据省显名；off=纯色块）；`unit` 单位（tooltip/色阶刻度/半径图例共用，≤8 字符）；`vmin/vmax` 锁定色阶域。交互：hover 省份/散点多行 tooltip（省名 / 值+单位+占比）+ 高亮描边压暗其余；点击含数据省份上报 `mapClick {province,value}`（`on:"mapClick:handler"`）。图内左下 visualMap 色阶条（仅散点时自动换为半径图例），右下南海诸岛小图（九段线+西沙/中沙黄岩/南沙/曾母暗沙）。数据源 vendor/china-geo.js（~33KB 按需加载） |
| `fit-screen` | 容器 | `w` `h` `mode` `maxh` | 大屏缩放容器（M1）。`w/h` 设计稿尺寸默认 1920×1080；`mode:scale` 等比缩放居中留空（默认）/`width` 等宽缩放贴合内容高（配 `maxh:` 视口高上限后内容超高纵滚）/`full` 双轴拉伸铺满；内部 grid 必带 h:100% 满幅挂载（缺省 fr 行按内容解析、底行被画布裁剪）；ResizeObserver 随挂载区重算；scale/full 要求挂载区有确定高度 |
| `scrollboard` | 容器 | `h` `speed` `gap` `cols` `rows` `clk` | 轮播榜单（M1）。`h` 视口高默认 300；`speed` px/s 默认 36（0=静止）；`cols:"列1,列2"` 表头；`rows:"a,1,↑2\|b,2,↓3"` 简写行（或 `[tr]` 子节点）；↑↓ 列自动着色；hover 暂停 + 无缝循环；空态 i18n |
| `page` | 容器 | `w` `theme` | 后台应用壳（M2）。grid areas 三区骨架（header 横贯顶 / sidebar+content 两列）；`w` 侧栏宽 px 默认 240；宿主有确定高度自动铺满，否则按内容；子元素约定为 page-header/page-sidebar/page-content 三件套（其余子元素 CSS 兜底落主区） |
| `page-header` | 容器 | `tt` `bc` `sticky` | 页头。`bc:"首页,系统,用户"` 逗号分级面包屑（末项自动当前页）；`sticky` 吸顶；子节点（btn 等）落右侧动作插槽；`[upd id: tt:/bc:]` 就地更新 |
| `page-sidebar` | 容器 | `tt` | 侧栏。品牌行 + 折叠钮（联动 page 列宽 240⇄64 过渡，上报 `toggle {folded}`）+ 滚动主体；脱离 page 单独用折叠自身类不崩 |
| `page-content` | 容器 | — | 主区薄包装。纵列 + 自滚动 + overflow 裁剪防护 |
| `page-tabs` | 容器 | `act` `on` `id` | 多页签容器。`act` 初始激活 key（未命中回落首个可用）；点击页签上报 `change {key,title}`；`[upd id: act:key]` 静默切换；键盘 ←→ 导航 |
| `page-tab` | 容器 | `n` `tt` `closeable` `dis` | 单页签。`n` key（缺省用 tt）；`closeable` × 关闭（上报 `close {key,title}`，激活让位邻签）；`dis` 禁用；`[del id:]` 整签移除（按钮+面板一体） |
| `float-button` | 容器 | `pos` `offset` | 浮动按钮组。`pos` 四角固位(right-bottom 缺省/right-top/left-bottom/left-top)、`offset` 边距(px 缺省24)；子组件自动圆形悬浮化 |

#### 响应式断点（T0.3，容器查询）

`col` 与 `grid` 支持 `xs`/`sm`/`md`/`lg`/`xl` 五档断点属性，声明式响应式——**断点基于容器（row/grid 自身）宽度而非视口**，嵌套布局（dialog 内栅格、sidebar 内卡片墙）各自独立响应：

```
[col span:4 xs:12 sm:6 lg:3]           ← col：值 = span 1-12；「桌面 3 列 → 平板 2 列 → 手机 1 列」
[col xs:"8/2"]                          ← col 组合值 "span/offset"（offset 1-11，含空格必须双引号——「"8/2"」本身无空格可不引）
[grid gap:12 xs:1 sm:2 lg:3]           ← grid：值 = 列数 1-12
```

- 档位：`xs` 基础档（全宽度生效）→ `sm` ≥576px → `md` ≥768px → `lg` ≥992px → `xl` ≥1200px 递增覆盖（未写某档继承上一档）；
- 断点属性只做**覆盖**：未写断点时行为与旧版完全一致（`span`/`offset` 基础值不变）；
- 非法值（越界/非数字）静默丢弃该档；浏览器不支持容器查询时（Safari<16 等）断点不生效，自动回退全局 1024/640 两档媒体查询兜底（移动端栅格单列化），不破版；
- 实现：属性落 `data-bp-*` → CSS `@container` 规则应用；带断点的 grid 外层自动包 `.tokui-grid-cq` 容器（元素不能查询自身容器）。

#### 高级网格 grid/cell（显式二维网格，与 12 栅格并行）
面向圣杯骨架、监控大屏、车机 HMI、杂志混排等二维不对称布局。**选型规则：一维并排均分用 `row`/`col`；二维不对称 / 区域命名 / 固定+弹性混合轨道 / 跨行跨列 / 整页骨架用 `grid`/`cell`。**

**`grid` 属性**（所有值白名单校验，任一非法 → 该属性整体不输出）：

| 属性 | 说明 |
|------|------|
| `cols` | 列轨道。纯数字 N(1-24) → `repeat(N,1fr)`；`auto:180px` → `repeat(auto-fill,minmax(180px,1fr))`；或空格分隔显式轨道列表 |
| `rows` | 行轨道，语法同 `cols`，可省 |
| `areas` | 模板区域。`\|` 分行、空格分列、`.` 空位；区名限 `[a-zA-Z][a-zA-Z0-9_-]*` |
| `gap` / `gx` / `gy` | 间距 / 列间距 / 行间距。纯数字按 px，或 CSS 长度 |
| `h` / `minh` | 高度 / 最小高度（纯数字按 px） |
| `v` | 变体：`dense`（grid-auto-flow:dense 自动填坑）、`flush`（gap:0） |
| `theme` | 子树级主题：`dark`/`modern`/`modern-dark`/`default`。落 `data-tokui-theme` 到该元素，自身及后代令牌（stat/chart/btn/文本）全部跟随。`grid`/`cell`/`card` 均支持 |

轨道 token 白名单：长度（px/%/em/rem/vw/vh）、`Nfr`、`auto`、`min-content`、`max-content`、`minmax(a,b)`、`fit-content(len)`。

> ⚠️ 固定轨道溢出：`rows`/`h` 定死后内容超高不会撑开行轨，会溢出盖住相邻区域（`chart` 的 `h` 仅 viewBox 高，SVG 按宽度 100% 等比缩放，宽 cell 内实际更高）。内容高度不确定时省略 `rows` 用自动行；`h` 只用于确知内容高度的骨架（如车机 HMI）。

**`cell` 属性**：`area` 模板区域名；`c` 列跨 N(1-24) 或 `"start/end"`（如 `c:"1/3"`）；`r` 行跨 N(1-24)；`align`/`justify` 单元格内容对齐（`start`/`center`/`end`/`stretch`）。无需跨区/跨行列时，子组件可直接作 `grid` 子项，不必包 `cell`。

```tokui
;; 圣杯布局：areas 区域命名，nav 通高、main 两列宽
[grid cols:"200px 1fr 1fr" rows:"64px 1fr" gap:12 h:480 areas:"nav main main|nav aside aside"][cell area:nav][card tt:导航][list][item 仪表盘][item 订单][item 设置][/list][/card][/cell][cell area:main][card tt:主内容区][p 两列宽的主区域。][/card][/cell][cell area:aside][card tt:侧栏][p 辅助信息。][/card][/cell][/grid]

;; auto-fill 卡片墙：随容器宽度自动列数，每张最小 180px（子组件直接作 grid 子项）
[grid cols:"auto:180px" gap:12][card tt:Alpha tx:自动填满整行][card tt:Beta tx:无需媒体查询][card tt:Gamma tx:最小 180px][card tt:Delta tx:宽度自适应][/grid]
```

### 6.6 表单组件

| Tag | 类型 | 常用属性 | 说明 |
|-----|------|----------|------|
| `form` | 容器 | `act` `mtd` `sub` `clk` `id` `cols` `lw` `gap` `v:inline` | 表单。`act` 提交地址、`sub` 提交处理器；提交前执行原生 reportValidity（`req`/`pat` 不过则拦截）。**M2 布局属性**：`cols:1~4` 字段网格列数；`lw` 标签统一宽 px（40~320）；`gap` 间距 px（0~48）；`v:inline` 全字段行内过滤条（与 cols 同写 cols 优先）；字段 `v:full` 跨整行（input/pwd/select/textarea/picker/cascader/transfer/upload/numinput/日历时件均支持） |
| `input` | 自闭合 | `t` `l` `ph` `id` `n` `val` `ml` `min` `max` `step` `req` `dis` `ro` `w` `hint` `pat` `err` `ok` `live` `search` `v` `pre`/`app`/`prebtn`/`appbtn` `rule` `msg` `sug` `db` | 输入框。`val` 存初值（`v` 是变体）；`ml` maxlength；`hint` 提示；`pat` 原生 pattern 校验；`err` 自定义校验错误文案；`live` 纯前端实时校验（blur 本地 checkValidity：失败出 `err` 红 hint，通过出 `ok` 绿 hint，默认 `✓ 格式正确`；`live:input` 即时模式边输边验）；`rule`/`msg` DSL 校验规则（见下方专节）；`sug:数据源handler名` 输入联想下拉（fn({value}) 返回数组或 Promise，项为字符串或 `{v,tx}`；↑↓/Enter/Esc 导航，选定触发 change 上报）；`search` 加搜索图标（`search right` 右侧）；`pre`/`app` 前置/后置文本（可 `文本\|变体`）；`prebtn`/`appbtn` 前置/后置按钮（`文本:处理器\|变体`） |
| `pwd` | 自闭合 | 同 `input` + `toggle` | 密码框。`toggle` 显隐开关 |
| `textarea` | 容器 | `l` `id` `n` `ph` `rows` `maxlen` `maxrows` `auto` `tx`/裸内容 `req` `dis` `ro` | 多行文本。`auto` 自适应高度 |
| `select` | 容器 | `l` `ph` `multi` `id` `n` `req` `v` `opt` | 下拉选择。子项 `opt`；或 `opt:"v:标签;…"` 简写自闭合 |
| `radio` | 容器 | `l` `id` `n` `v` `opt` | 单选组。子项 `opt`；或简写 `opt:"…"`；同 name 互斥 |
| `opt` | 自闭合 | `v` `tx` `chk` `p` | 选项。随父容器变 select/radio/checkbox/picker/cascader/transfer 选项；`p` 指定父值（仅 cascader） |
| `checkbox` | 自闭合/容器 | `l` `chk` `id` `n` `v` `opt` `multi` | 复选框（**三态**：见下方专节） |
| `switch` | 自闭合 | `l` `chk` `dis` `clk` `id` `n` `v` | 开关 |
| `slider` | 自闭合 | `l` `min` `max` `step` `v` `dis` `clk` `id` `n` `range` `marks` | 滑块。`range` 双滑块（`v:"20,60"`，change 报 `{value:[min,max]}`）；`marks:"0:免费,50:标准,100:旗舰"` 刻度 |
| `rate` | 自闭合 | `l` `v` `max` `tx` `ro` `dis` `clk` `id` `n` `half` | 评分。`max` 默认 5；`ro` 只读（报告/展示类必加）；`half` 半选（0.5 步进，同值再点清零） |
| `numinput` | 自闭合 | `l` `v` `min` `max` `step` `dis` `id` `n` | 数字输入 |
| `segmented` | 双模式 | `opt` `v` `n` `l` `dis` `on` `id` | 分段控制器。简写 `opt:"v:label;…"` 原子自闭合；容器 `[opt v:值 tx:文 i:图标 chk dis]` 支持图标/单项禁用；`v` 当前值（可与变体组合 `v:"sm,grid"`）；变体 `sm`/`lg`/`block`/`pill`/`vertical`；`upd v:值` 程序化切换；form reset 恢复 |
| `editable` | 自闭合 | `tx` `v` `ph` `n` `dis` `on` `id` | 行内编辑。点击虚线文本进编辑态：Enter/失焦提交（`change` 上报 `{value,name}`）、Esc 还原不上报；`upd tx:值` 程序化改值（silent）、`upd dis:false` 解锁 |
| `color-picker` | 自闭合 | `v` `presets` `n` `l` `dis` `on` `id` | 颜色选择。面板含饱和明度取色区 + hue 滑条 + hex 输入 + 预设色 + 清除，开启时 portal 到 body fixed 定位（不被父容器裁切，滚动跟随重定位，外点/Esc 关）；`v` 初始 `#rrggbb`（缺省 `#1677ff`）；`presets` 逗号分隔 hex；`upd v:#hex` / `upd dis:false`；form reset 恢复 |
| `btn` | 自闭合 | `tx` `t` `sub` `clk` `id` `dis` `w` `bg` `fc` `radius` `icon` `i` `l`/`tt` `form` `reset` `print` | 按钮（见下方专节）。`t:submit` = 提交语义（渲染 `type=submit`，点击走 `_doSubmit` 校验闸门：`req`/`pat` 不过则拦截；`clk:H` 作提交 handler，缺省回退表单自身 `sub`；不在 form 内时退化为普通点击）。`w`/`radius` 仅接受 数字+px/%/em/rem/vw/vh，非法值静默丢弃 |
| `btngroup` | 容器 | `id` `v` | 按钮组。`v:vertical`/`pill` |
| `print-area` | 容器 | `id` `tt` | 打印区（配合 `[btn print:ID]` 1:1 打印） |
| `picker` | 容器 | `l` `ph` `multi` `dis` `id` `n` `v` | 选择器（搜索下拉）；子项 `opt` |
| `cascader` | 容器 | `l` `ph` `dis` `clk` `v` `id` `n` | 级联选择。`v` 预选路径（`/` 分隔）；扁平 `opt` 用 `p` 指定父值 |
| `transfer` | 容器 | `l` `tt` `tt2` `clk` `id` `dis` `n` `h` `mh` | 穿梭框。`tt`/`tt2` 左/右标题；`h`/`mh` 固定/最大高度；子项 `opt`（`chk` 进右栏） |
| `upload` | 自闭合 | `l` `ph` `accept` `multi` `dis` `clk` `max` `id` `n` `u` `mtd` | 文件上传。`u:` 上传地址（仅 http(s)/相对路径）启用自动传输：XHR 逐个上传，进度条/成功 ✓/失败 ✗+重试三态，上报 `progress`/`success`/`error` 事件；无 `u` 仅前端选择 |
| `datepicker` | 自闭合 | `l` `ph` `fmt` `v` `clk` `dis` `id` `n` `range` | 日期选择。`fmt` 默认 `YYYY-MM-DD`；`range` 范围模式（两次点击选起止，值格式 `YYYY-MM-DD ~ YYYY-MM-DD`） |
| `timepicker` | 自闭合 | `l` `ph` `fmt` `v` `clk` `dis` `id` `n` | 时间选择。`fmt` 默认 `HH:mm`（含 `ss` 显示秒） |
| `datetimepicker` | 自闭合 | `l` `ph` `fmt` `v` `clk` `dis` `id` `n` | 日期时间选择。`fmt` 默认 `YYYY-MM-DD HH:mm` |

#### DSL 校验规则（`rule:` + `msg:`）

`input`/`pwd`/`textarea`/`select` 支持声明式校验规则，**提交时统一执行**（`sub`/`t:submit` 全部路径），失败拦截提交、错误字段标红 + hint 出文案并聚焦：

```tokui
[input n:email l:"邮箱" rule:"required|email"]
[input n:code l:"验证码" rule:"required|len:6" msg:"请输入 6 位验证码"]
[select n:city l:"城市" rule:"required" opt:"bj:北京;sh:上海"]
```

- 规则管道分隔按序短路：`required` `email` `url` `number` `len:N`（精确长度）`min:N` `max:N`（字符数）`re:正则`
- 空值跳过非 `required` 规则（HTML5 同语义：空且非必填 = 合法）
- `msg:` 自定义错误文案（缺省用内置 i18n 文案）；未知规则名/非法正则 `console.warn` 跳过
- 与 `live` 组合：blur 实时校验，error 态下输入即时重检
- `select` 的 `req` 会写原生 `required` 属性（多选除外，语义不符）

#### 编辑回填闭环（M2 / T2.4：打开弹窗 → 逐字段 `upd` → 提交）

全控件支持 `[upd id:]` 回填，「编辑」场景一条范式打通（dialog 常驻 DOM，`upd` 填值后 `showModal`）：

```tokui
[dialog tt:编辑用户 id:editDlg]
  [form cols:2 lw:84 sub:saveUser]
    [input n:name l:姓名 id:f-name]
    [select n:dept l:部门 opt:"1:研发;2:销售" id:f-dept]
    [datepicker n:entry l:入职 id:f-entry]
    [cascader n:area l:区域 id:f-area][opt v:gd tx:广东][opt v:gz tx:广州 p:gd][/cascader]
    [transfer n:perm l:权限 id:f-perm][opt v:1 tx:查看][opt v:2 tx:编辑][/transfer]
  [/form]
[/dialog]
```

| 控件 | 回填指令 | 语义 |
|---|---|---|
| input/pwd/textarea/numinput | `[upd id:x v:值]` | 直写 |
| select | `[upd id:x v:key]`（多选 `v:"a,b"` 覆盖式） | 选中项 |
| radio / checkbox | `[upd id:x v:key]` / `v:"a,c"` | 单选/多选集合 |
| datepicker（含 range） | `[upd id:x v:2024-06-01]` / `"起 ~ 止"` | 写入 + 面板状态重定位 |
| timepicker / datetimepicker | `[upd id:x v:"09:30"]` / `"2024-06-01 09:30"` | 写入 + 时/日期状态重解析 |
| cascader | `[upd id:x v:"gd/gz"]` | 路径合法才写（文本+hidden 同步，非法静默） |
| transfer | `[upd id:x v:"1,2"]` | 右栏按序重排 + 勾选清零 |
| upload | `[upd id:x act:fill files:"名,url,大小|…"]` | 回显已传文件（✕ 可删） |
| 通用 | `[upd id:x dis:true/false]`（radio 整组 / transfer 移动钮 / picker 同步） | 禁用态 |

配套：`[btn tx:重置 reset]` 广播 tokuireset——cascader / 日历时件 / transfer / upload 等自定义控件按初始值复原（`data-tokui-resettable` 契约）。

#### 表格「翻页事件 → 宿主重渲」范式（data: 后端分页对接铺路，M2/T2.3 批3）

`pagination` 的 `page` 事件载荷完整化 `{page, size, filter, sort}`（`value` 兼容保留）。后端分页的标准接法（T5.1 `data:` 数据源落地前的文档化范式）：

```js
TokUI.registerHandler('onPage', (d) => {
  // d = { page, size, filter, sort } → 拉取对应页数据后 del 旧行 + ins 新行
  const rows = fetchPage(d.page, d.size);
  conn.push('[del id:tblBody]');
  conn.push('[ins into:tblBody]' + rows.map(r => `[tr ${r.name},${r.qty}]`).join('') + '[/ins]');
});
```

要点：`table` 需带 `id`；宿主持有行数据时优先 `del`+`ins` 增量；客户端 `sortable`/`filter` 关闭（服务端排序筛选取代）。

#### `opt:"..."` 选项简写（radio / checkbox / select 通用）

`;` 分隔项，`:` 分隔 value:label（可缺，则等于 value），整串**必须双引号**：

```tokui
[radio n:gender l:性别 opt:"1:男;2:女"]              ;; 等价 [radio n:gender l:性别][opt v:1 tx:男][opt v:2 tx:女][/radio]
[select n:city l:城市 opt:"bj:北京;sh:上海"]
[checkbox n:brand l:品牌 opt:"1:篮球;2:足球;3:羽毛球"]
```

#### checkbox 三态（按是否带 `opt` / `multi` 自动判定）

| 形态 | 判定 | 写法 | 提交值 |
|------|------|------|--------|
| 单布尔（legacy） | 无 `opt` 无 `multi` | `[checkbox l:同意协议 n:agree]`（自闭合） | 勾选=该 name 出现 |
| 简写多选 | 有 `opt` | `[checkbox n:brand l:品牌 opt:"1:篮球;2:足球"]`（自闭合） | `data[brand]` = 数组 |
| 容器多选 | 有 `multi` | `[checkbox n:brand l:品牌 multi][opt v:1 tx:篮球]…[/checkbox]` | `data[brand]` = 数组 |

#### radio/checkbox 排列（`v:` 手动标记）

| 标记 | 排列 |
|------|------|
| 默认 | 横排（flex 自动换行，移动端 ≤640px 转竖排） |
| `v:inline` | 标签与控件同行 |
| `v:vertical` | 竖排左对齐（与 `inline` 互斥） |

> 多选提交走原生 FormData → `data[name]` 为**数组**；radio 始终单值；select 多值由原生 `multiple` 决定。

#### btn 内置动作（renderer 自动解析，无需 registerHandler）

优先级 `print > reset > submit > clk`：

```tokui
[form id:login sub:onLogin]...[/form]
[btn tx:提交 form:login sub:onLogin t:primary]    ;; form:ID 显式绑定表单（优先于 DOM 祖先推断）
[btn tx:重置 form:login reset]                     ;; reset 裸写：重置绑定表单
[btn tx:重置 form:login reset:onReset]             ;; reset:H：复位后回调
[btn tx:打印 print:pa1]                            ;; 打印 print-area#pa1（1:1）
[btn tx:打印本卡 print:self]                       ;; 打印最近祖先 print-area / card
[btn print]                                        ;; 裸写 = print:self
[print-area id:pa1 tt:订单详情]...[/print-area]
```

- `reset`：原生 input 由 `form.reset()` 复位；自定义控件（slider/rate/numinput/switch/transfer/picker/cascader）实现 `_tokuiReset()` + `data-tokui-resettable` 印章，renderer 遍历调用并向 form 广播 `tokuireset` 事件。
- `print`：给目标加 `.tokui-print-target` + `body[data-tokui-printing="1"]`，`@media print` 仅该作用域可见（1:1），`[data-tokui-print-trigger]` 按钮自身隐藏。`form:ID` 用 `getElementById` 解析且校验为 FORM（防 id 伪造）。

#### btn 图标（`icon:` SVG / `i:` emoji / icon-only）

```tokui
[btn tx:查看 icon:view t:primary clk:view]         ;; icon: 取 icons.js 的 Lucide SVG 名，stroke=currentColor 自动配色
[btn icon:edit l:保存 clk:save]                    ;; 无 tx 仅有 icon → icon-only 紧凑钮，l:/tt: 作 aria-label + CSS tooltip
[btn tx:复制 i:📋 clk:copy]                        ;; i: 注入 emoji / 字面字符
```

可用图标名（24 个，见 §7）：`view edit delete add copy download upload refresh check close search setting warn info lock unlock more save export filter sort star link menu`。

### 6.7 数据与表格

| Tag | 类型 | 常用属性 | 说明 |
|-----|------|----------|------|
| `table` | 容器 | `stripe` `cap`/`caption` `v` `id` `sortable` `filter` `pagination` `ps` `fixed` `fc` `loading` `empty` | 表格。`cap` 标题；`v:bordered`/`compact`（注：bordered 由 CSS 类驱动）；`sortable` 客户端排序（点击表头 asc/desc 切换，数值感知）；`filter` 客户端筛选（表头下筛选行，子串 AND 多列，300ms 防抖）；`pagination` + `ps:N` 客户端分页（默认 10/页）；三者可组合（先筛后分）；排序/筛选/翻页上报 `sort`/`filter`/`page` 事件。**M2 增强**：`fixed` 首列钉左 / `fc:N` 尾 N 列钉右（横向滚动时固定 + 分界阴影，配 `w:` 列宽效果最佳，流式行后到自动重算）；`loading` 表体骨架覆盖（`[upd id: loading:false]` 撤除）；`empty` 无数据空态占位（i18n，行到达自动隐藏）；翻页 `page` 载荷完整化 `{page,size,filter,sort}`（`value` 兼容保留） |
| `thead` | 容器/自闭合 | `cols` | 表头。`cols:"姓名,年龄"` 支持 `chk`（全选列）/`#`（序号列）；`;` 分多行；列名后 `/c`/`/r`/`/l` 对齐、`/primary`/`/danger`/`/success`/`/warning`/`/info` 配色；**`名称 w:180` 列宽**（24~2000px，可与对齐/配色组合如 `金额 w:120/r`，th 显式宽传导 body 列，固定列必配） |
| `tbody` | 容器 | — | 表体（区间勾选 + 列位追踪） |
| `tr` | 自闭合 | `cs`(legacy) `v:total` `id` `pid` `clk` | 表格行，内容逗号分隔单元格；cell 尾缀 `=cN`/`=rN`/`=cNrM` 合并。**M2**：`clk:handler` 行点击上报 `{index,row[]}`（整行数据载荷）；`id` + `pid:父行id` 树形行（子行默认折叠、按 pid 链缩进，父行首格展开钮，`[upd id:父行id act:expand/collapse]` 程序化） |
| `tcol` | 自闭合 | `n` | 列占位（thead 无 cols 时用） |

#### `tr` 单元格内联渲染（除纯文本外）

- **序号列**：thead 写 `#`，tr 对应位置留空。
- **勾选列**：thead 写 `chk`。
- **进度条**：`progress v:98 t:span`（≥80 自动绿，或 `status:error`）。
- **标签**：`tag:VIP t:success`。
- **操作按钮**：`btn:详情 clk:fillSubmit data-prompt:查看详情:<行ID>|btn:删除 v:danger clk:fillSubmit data-prompt:删除:<行ID>`（多个 `|` 分隔，属性空格分）。icon 操作钮 `btn: icon:edit l:编辑 v:warning clk:fillSubmit data-prompt:编辑:<行ID>`。
- **任意内联组件**：`[badge count:5]`、`[dot t:success tx:运行中]`（方括号包裹组件会内联渲染）。

> **🔴 带空格属性的内联组件格 / 多按钮格 → 整行外层双引号包**：凡 tr 行内有 `btn:`/`progress v:`/`tag:`/`[xxx]` 这类**带空格属性**的格，整行外层双引号包，单元格内不含逗号、多按钮用 `|` 分隔。**货币符号金额（¥/$/€/£ 等）千分位无需引号、整行包也无需内层转义**：
>
> ```tokui
> [tr "ZS001,张三,¥2,688.00,progress v:90 t:span,tag:在职 t:success,btn:详情 clk:fillSubmit data-prompt:详情:ZS001"]
> ```

#### 各列类型引号速查（系统性）

| 列类型 | 示例 | 含空格 | 含逗号 | 引号处理 |
|---|---|---|---|---|
| 纯文本 | `张三` / `技术部` | 否 | 否 | 无需 |
| 普通数字 | `42` / `320` | 否 | 否 | 无需 |
| **货币符号金额** | `¥2,688.00` / `$1,234,567` | 否 | 是（千分位） | **无需**（parser 自动识别千分位） |
| 百分比/单位 | `0.8%` / `95分` | 否 | 否 | 无需 |
| 裸数字千分位（无符号） | `12800,00` | 否 | 是 | **该格双引号包**（无符号歧义） |
| 多值文本（逗号） | `量程0-50MPa,精度0.1%` | 否 | 是 | **该格双引号包** |
| 标签 `tag:` | `tag:已发货 t:primary` | 是 | 否 | 整行外层引号（或该格引号） |
| 进度 `progress` | `progress v:80 t:span` | 是 | 否 | 整行外层引号（或该格引号） |
| 按钮 `btn:` | `btn:详情 clk:...` | 是 | 否 | 整行外层引号（或该格引号） |
| 多按钮 | `btn:...|btn:...` | 是 | 否 | 整行外层引号（`|` 分隔） |

**混搭规则**：一行里既有货币金额又有组件格 → 整行外层引号包，货币金额无需内层转义（千分位自动识别）：`[tr ",ORD-001,星辰,¥2,688.00,tag:已发货 t:primary,btn:查看 clk:x"]`。一行里有多值文本逗号格 + 组件格 → 整行外层引号 + 多值格内层 `\"` 转义。
>
> **不引号包的后果（实测高频翻车点）**：parser 按**空格**切 tr token，`btn:详情 clk:fillSubmit data-prompt:...` 里的 `clk:`/`data-prompt:` 会被吃成 **tr 自身属性**、content 被截断、操作列/进度列整列渲染不出来。错例：
>
> ```tokui
> [tr 01,项目01,42,0.8%,progress v:42 t:span,btn:详情 clk:fillSubmit data-prompt:查看详情:项目01]
> ```
>
> → `tr.attrs` 变 `{v:"42", t:"span,btn:详情", clk:"fillSubmit", data-prompt:"查看详情:项目01"}`、`tr.content` 只剩前 5 格 `"01,项目01,42,0.8%,progress"`、操作列消失。
>
> **改法（整行外层引号包即可）**：`[tr "01,项目01,42,0.8%,progress v:42 t:span,btn:详情 clk:fillSubmit data-prompt:查看详情:项目01"]`。无空格组件格不需引号。

#### 操作列范例（多按钮 + icon-only）

整行 tr 外层引号包（btn 格含空格）；多按钮 `|` 分隔；`v:danger` 删钮红；**每行 ID 烧进 `data-prompt`**（`动作:ID`）；icon-only 用 `l:` 作 tooltip+无障碍；可用 icon 名：view/edit/delete/copy/download/refresh/check/close/search 等。

```tokui
[table stripe bordered]
[thead cols:"#,项目,数值,趋势,操作"]
[tbody]
[tr ",P01,42,progress v:42 t:span,btn:详情 clk:fillSubmit data-prompt:查看详情:P01|btn:编辑 clk:fillSubmit data-prompt:编辑:P01|btn:删除 v:danger clk:fillSubmit data-prompt:删除:P01"]
[tr ",P02,88,progress v:88 t:span,btn: icon:view l:详情 v:primary clk:fillSubmit data-prompt:查看详情:P02|btn: icon:edit l:编辑 v:warning clk:fillSubmit data-prompt:编辑:P02|btn: icon:delete l:删除 v:danger clk:fillSubmit data-prompt:删除:P02"]
[/tbody]
[/table]
```

#### 表格合并 / 对齐 / 配色 / 汇总（cell 尾缀，表头+表体通用）

- **横向合并**：`值=cN` 横跨 N 列（**无需 `,,,` 占位**）。
- **纵向合并**：`值=rN` 纵跨 N 行（被占列下行直接省略，浏览器自动占位）。
- **组合**：`值=c2r2`（`c`/`r` 顺序无关）。严格尾缀正则 `=([cr]\d+){1,2}$`，`公式=x=2`/`版本=v2` 不误判。
- **多行表头**：`thead cols` 用 `;` 分行（thead 仍单自闭合标签）。
- **列对齐**：cell 后 `/c` 居中 `/r` 居右 `/l` 居左。
- **列配色**：对齐后再 `/primary` `/success` `/warning` `/danger` `/info`。
- **传导**：表头某格的 `/align`/`/color` 按列位传导到 body（renderer 用列位追踪器 `placeRow` 修正 rowspan 偏移）。
- **汇总行**：`tr v:total` → 整行加粗、汇总格（行首）居右、末格（金额）加粗居中带 `--danger` 色。常配 `汇总=c8`（整行横跨）。
- **旧 `cs:N`**：仅首格 colspan 且要 `,,,` 占位，已由 `=cN` 取代但向后兼容。

col spec 顺序：`列名[=cN[rM]][/对齐][/配色]`。

```tokui
[thead cols:"大区=r2/c,订单=c2/c,商品=r2/c,交易=c3/c,状态=r2/c,操作=r2/c;订单号,客户,数量/c/primary,单价/r/warning,金额/r/danger"]
[tbody]
[tr "华北区=r4,ORD-1,字节,键盘,5,¥1280,¥6400,tag:已发货 t:success,btn: icon:view l:详情 v:primary clk:fillSubmit data-prompt:详情:ORD-1"]
[tr "ORD-2,星辰,鼠标,8,¥336,¥2688,tag:待付款 t:warning,btn: icon:view l:详情 v:primary clk:fillSubmit data-prompt:详情:ORD-2"]
[tr 汇总=c8,"¥17,129" v:total]
[/tbody]
```

### 6.8 图表（`chart`，纯 SVG 零依赖，20 种）

**🔴 属性输出顺序铁律（流式强约束）**：`t 类型 → 样式/布局 → l 标签 → 数据`。样式属性必须在数据之前、`l` 必须在 `d` 之前，否则流式预览先按默认布局画、闭合才翻转。

```
正确：[chart t:bar tt:日产量 orient:h vals w:800 h:600 l:"Mon,Tue,Wed,Thu,Fri" d:"10,24,18,30,22"]
错误：[chart t:bar d:"10,24,18,30,22" l:"Mon,..." vals orient:h]   ;; 样式写在数据后 → 预览翻转
```

支持类型（20）：`bar` `line` `area` `pie` `donut` `rose` `funnel` `radar` `scatter` `bubble` `heatmap` `histogram` `waterfall` `boxplot` `treemap` `sankey` `candlestick` `progress` `gauge` `gantt`。

#### 通用属性

| 属性 | 含义 |
|------|------|
| `t` | 图表类型（恒首） |
| `tt` | 标题 |
| `d` | 数据（格式随类型，见下表） |
| `l` | 标签（数量须 = 数据点数/类别数） |
| `c` | 颜色序列（逗号分隔；缺省 10 色板；heatmap 当色阶 stops） |
| `w` `h` | SVG 宽/高（仅影响内部坐标系比例，不决定最终渲染大小；定高容器（grid 格/panel 体）内自动按格位纵横比重绘铺满，map 除外） |
| `v` | 单值（gauge/progress/donut 中心） |
| `area` | 折线填充（布尔） |
| `vals` | 柱/线显数值（布尔） |
| `stack` | 堆叠（布尔，bar/line/area/donut 多系列） |
| `smooth` | 折线/面积平滑（布尔） |
| `orient` | `h` 横向柱（默认纵向） |
| `xl` `yl` `sl` | X / Y / 第三维 轴名 |
| `xmin`/`xmax`/`ymin`/`ymax` | 显式锁轴（scatter/bubble，流式防已画点跳） |
| `range` | gauge 扫掠角 180（默认）/270/360 |
| `anim` | 数值动画 ms（progress/gauge，尊重无障碍偏好自动停） |
| `interval` | X 轴标签密度：`auto`（默认，横排→-45°旋转→跳过三级降级）/ `0`（全显）/ `N`（每 N 个显一个，保留首末） |
| `zoom` | dataZoom 拖拽缩放：`auto`（>30 点自动开）/ `N`（>N 开）/ `on`/`off`。bar（纵向）/line/area/boxplot/candlestick 支持；横柱 `orient:h` 与 histogram 不支持 |

#### 数据格式 `d` 速查

| 图表 | `d` 格式 | 例 |
|------|---------|-----|
| `bar` `line` `area` `radar` | 多系列 `|`、点 `,` | `d:"10,20,30\|15,25,35"` |
| `pie` `donut`(单环) `rose` `funnel` `waterfall` `histogram` | 单系列 `,` | `d:"10,20,30"` |
| `donut` 多环 | 环 `|`、点 `,` | `d:"40,30,20,10\|35,25,30,10"` |
| `scatter` | 点 `;`、坐标 `,` | `d:"1,2;3,5;6,4"` |
| `bubble` | 点 `;`、`x,y,size` `,` | `d:"1,2,5;3,4,10"` |
| `boxplot` | 组 `;`、五数 `,`（min,Q1,中,Q3,max） | `d:"1,3,5,7,9;2,4,6,8,10"` |
| `candlestick` | 根 `;`、OHLC `,` | `d:"10,12,8,11;11,13,9,10"` |
| `heatmap` | `rows` 属性：行 `|`、列 `,` | `rows:"1,2,3\|4,5,6"` |
| `treemap` | `名:值` `,` | `d:"A:100,B:60,C:40"` |
| `sankey` | `flows` 属性：`源->目标:值` `,` | `flows:"A->B:10,B->C:5"` |
| `gauge` `progress` | `v` 单值 | `v:72` |

#### 各类型专属属性

- **bar**：`stack` `orient:h` `vals` `ymax`。横向柱（`orient:h`）高度随类别数自动增长（viewBox 高 ≈ 36+26px×类别数，钳 200–1200，CSS 显示上限 1200），**无需手设 `h`**；显式 `h` 原样优先（>1200 部分被 CSS 截断）。
- **line**：`area` `smooth` `stack` `vals`。
- **area**：= line + 默认填充，同 line。
- **pie**/**donut**/**rose**：`l` 各项名；donut `v` 中心文字（单环）。
- **funnel**：建议数据**降序**（首层=漏斗口），自动标相对首层转化率。
- **radar**：多系列 `|` 对比。
- **scatter**/**bubble**：`xl`/`yl`（bubble 加 `sl` 第三维名）+ `xmin/xmax/ymin/ymax` 锁轴。
- **heatmap**：`rows` 矩阵、`cols` 列标签、`l` 行标签（须匹配）、`vmin`/`vmax` 锁值域、`c` 色阶 stops。
- **histogram**：`d` 原始值序列（前端分箱）；`bins` 箱数（须 = `l` 段数）；`l` 范围段标签（`40-50,...,90-100` 自动锁 lo/hi/bins）；`min`/`max`/`ymax` 锁值域/频次。
- **waterfall**：`d` 带符号增减；`c` 前 2 个为正/负色（默认绿/红）。
- **boxplot**：`d` 五数；`l` 组名。
- **treemap**：`d` `名:值`；`c` 配色。
- **sankey**：`nodes`（可省，从 flows 提）+ `flows`；`c` 配色。
- **candlestick**：`d` OHLC；`l` 日期；`c` 阳/阴色（默认红涨绿跌，中国惯例）。
- **progress**：`v` `max`/`min` `u` `l` `c` `anim`。
- **gauge**：见下方专节。

#### X 轴密度 + dataZoom 缩放（大数据点）

- bar/line/area/histogram/boxplot/candlestick 的 X 轴标签自动【横排 → -45° 旋转 → 按步长跳过（保留首末）】三级降级，默认 `interval:auto`。
- `interval:N` 锁步长（每 N 个显一个，保留首末）；`interval:0` 强制全显（仅按需旋转）。
- 数据点 >30（长时间序列、大规模柱/线、多根 K 线/多组箱线）加 `zoom:auto` 开底部 dataZoom 滑块，用户拖拽看局部（单系列柱图池化、丝滑跟手）。

```tokui
[chart t:line tt:"近90天访问趋势" zoom:auto l:"D1,D2,...,D90" d:"30,45,38,60,..."]
[chart t:bar tt:"50点柱状" interval:5 l:"D1,D2,...,D50" d:"120,200,150,80,..."]
```

#### gauge 仪表盘完整属性

| 属性 | 含义 | 默认 |
|------|------|------|
| `v` | 当前值（必填） | — |
| `max`/`min` | 上/下限 | 100 / 0 |
| `u` | 单位（min:0&max:100 时自动 `%`） | — |
| `dec` | 小数位 | span≤10→1，否则 0 |
| `range` | 扫掠角 180/270/360 | 180 |
| `status` | 语义染弧色 + 角标：`success`/`warning`/`danger`/`info` | — |
| `zones` | 阶段阈值逗号分隔（如 `60,85`），多色带分段 | — |
| `zc` | zones 段色（low→high，默认 `绿,黄,红`） | `#52c41a,#faad14,#f5222d` |
| `ticks` | 刻度密度 | 6 |
| `l` | 指标名（中心） | — |
| `sub` | 副标题（底部） | — |
| `anim` | 数字+弧+指针动画 ms | 0 |
| `c` | 自定义弧色（优先级低于 zones/status） | — |

色判定优先级：`zones` 命中段色 > `status` 语义色 > `c` > 默认调色板。

```tokui
[chart t:gauge tt:CPU使用率 status:warning sub:"数据来源:监控系统" l:8核均值 v:72]
[chart t:gauge tt:达标率 zones:"60,85" anim:1200 sub:"红线85%" l:Q2目标90% v:92]
[chart t:gauge tt:错误率 zones:"3,8" zc:"#52c41a,#faad14,#f5222d" u:% dec:1 v:3.4]   ;; 反向配色（高值=差）
```

#### gantt 甘特图完整属性（不用 d/l）

| 属性 | 含义 |
|------|------|
| `tasks` | 任务 `名称,开始,结束[,进度[,组号]]`，多条 `|` 分隔。进度 0-100，组号从 0 起 |
| `gnames` | 组名 `|` 分隔，按组号映射图例。**用了组号就必须给 gnames**，否则图例显「组1/组2」 |
| `deps` | 依赖 `源索引->目标索引`（finish→start），多条 `,` 分隔。索引 0 起，须 < tasks 总数 |
| `ms` | 里程碑 `名称,时间点[,组号]`，多条 `|` 分隔，渲染为菱形 ◆ |
| `mode` | `days`（数字天数）/ `dates`（`2026-06-15` 或 `2026/6/15`）。留空自动判（含 `-`/`/` 为日期） |
| `w` | 宽（默认 720） |

> dates 模式自动画「今天」竖线。点击任务条高亮其依赖传递闭包。task 名严禁含空格/逗号/`|`。

```tokui
[chart t:gantt tt:V2.0排期 w:720 tasks:"需求,1,3,100,0|设计,3,5,100,0|开发,5,14,60,1|测试,14,18,0,2" ms:"评审,5,0|上线,18,2" gnames:"设计|开发|测试" deps:"0->1,1->2,2->3"]
[chart t:gantt tt:工单排程 mode:dates w:720 tasks:"下发,2026-06-15,2026-06-16,100,0|生产,2026-06-16,2026-06-20,40,0|质检,2026-06-20,2026-06-22,0,1" ms:"放行,2026-06-22,1" gnames:"生产|质检" deps:"0->1,1->2"]
```

#### 容器模式（流式逐点喂入，数据增长过程可见）

无 `d`/`tasks`/`rows`/`nodes+flows`/（gauge·progress 的 `v`）时，`chart` 走容器模式收子节点：

| 子节点 | 适用图表 | `v` 内容 |
|--------|---------|---------|
| `pt` | scatter/bubble/treemap/其他点图 | scatter/bubble/treemap 保留原串（`x,y[,s]` / `名:值`），其余 parseFloat |
| `hrow` | heatmap | `v,v,v` 一行（逗号分隔，勿含 `|`） |
| `flow` | sankey | `源->目标:值` |
| `task` | gantt | `名,起,止,进度,组` |
| `ms` | gantt | `名,时间,组` |

```tokui
[chart t:bar tt:日产量 vals l:"Mon,Tue,Wed,Thu,Fri"]
[pt v:10][pt v:24][pt v:18][pt v:30][pt v:22]
[/chart]

[chart t:heatmap tt:访问热力 cols:"周一,周二,周三" l:"早,中,晚"]
[hrow v:"1,2,3"][hrow v:"4,5,6"][hrow v:"7,8,9"]
[/chart]
```

> 自闭合 `[chart ... d:...]` 与容器写法**都支持流式**（含 gantt 长数据、双引号多任务值）。数据点少/单值用自闭合更简洁；数据点多或 gantt 复杂用容器更直观。

---

## 7. 内置图标名（icons.js，61 个 + registerIcon 扩展）

`btn` 的 `icon:` 属性与表格操作列 `btn: icon:NAME` 取这些 Lucide 风格 SVG 名（stroke=currentColor，自动继承钮色，彩色图标无需另配色）。**T0.4 起全库组件 chrome 图标（树控件/文件树/音频/警示框/通知/终端三色点等）统一走本注册表，不再使用 emoji**：

```
操作类:  view  edit  delete  add  copy  download  upload  refresh  check  close
         save  export  filter  sort  more  plus  minus  play  pause
状态类:  warn  info  circle-check  circle-x  circle-alert  circle-info  circle-help
导航类:  chevron-up  chevron-down  chevron-left  chevron-right
         arrow-up  arrow-down  arrow-left  arrow-right  external-link  menu  panel-left
对象类:  folder  folder-open  file-text  user  users  home  inbox  bell  calendar
         clock  map-pin  star  link  lock  unlock  search  setting
图表AI:  trending-up  trending-down  sparkles  lightbulb  zap  terminal  volume-high  volume-x
```

**扩展 API**：`TokUI.registerIcon(name, pathContent, { alias })` 注册自定义图标——`name` 须 `^[a-zA-Z][\w-]{0,63}$`；`pathContent` 为 SVG 元素串（如 `'<path d="..."/>'`），仅允许 path/circle/rect/line/polyline/polygon 几何标签（防注入）；可覆盖内置图标（自动刷新节点缓存）。

未知名返回空字符串。

---

## 8. 动态更新与交互回路

### 8.1 `upd` 属性更新

```tokui
[progress id:prog v:0 l:处理进度]
[upd id:prog v:50]
[upd id:prog v:100 status:success]
```

`id` 支持逗号分隔多目标批量更新：`[upd id:prog1,prog2 status:success]`（同属性应用到每个命中组件）。

`upd` 找目标后向上爬到有 `_update` 的组件根，按组件支持的键更新：

- `progress`：`v` / `status`
- `stat`：`v` / `trend`
- `badge`：`tx` / `count` / `overflow` / `act:hide`
- `tag`：`tx` / `act:close`
- `collapse`/`dialog`/`drawer`/`canvas`：`act:open` / `act:close` / `act:toggle` / `tt`
- `input`/`pwd`/`select`/`slider`/`rate`/`numinput`/`switch`/`textarea`/`chat-input`/`input-tag`：`v` / `dis` / `ph` / `ro` / `hint` / `chk` 等
- `input`/`pwd` 另支持 `status:error` / `status:success`：联动输入框变体类、hint 配色与 `aria-invalid`（校验反馈场景）；`status:` 空值清除状态
- `steps`/`tabs`：`v`（切当前步 / 激活页）
- `chat-input` 另支持 `streaming`：`streaming:true` 显示停止按钮、`streaming:false` 恢复发送按钮。chat-input 的 `id` 落 DOM，`dis` / `streaming` 经 `[upd id:x …]` 全通路生效（`dis:false` 字符串按「主动启用」处理）
- `tool-call`：`status` / `duration` / `result` / `error`（审批后续状态由此推送；`result`/`error` 幂等——同状态重复推送就地更新，不堆叠新节点；改 `status` 保留当前收展态）
- `plan-step`：`status`（同义词归一化，`running`→`doing` 等）/ `tt` / `desc`——`[upd id:step1 status:done]` 逐步推进计划
- `menu`：`act:activate` + `v:项标识`（程序化激活菜单项）
- `calendar`：`v` / `sel`（重设选中天，逗号分隔日号，全量替换）
- `upload`：`act:clear`（清空已选文件列表）

> `upd` 的 `dis:false` / `ro:false` / `chk:false` 是「主动关闭」语义（渲染端判 `=== 'false'`）；初始渲染的 `dis:false` 会被 parser 读成字符串 `'false'`（truthy），故初始禁用应省略而非写 `false`。

> 目标查找：页面存在多个同 `id` 元素时（多轮消息重名常见），`upd` 优先命中当前流式容器内的元素，容器内无匹配才回退全文档查找。

> **AI 组件 `id` 锚点**：`bubble` / `typing` / `terminal` / `diff` / `artifact` / `quick-reply` / `msg-actions` / `think` / `think-chain` 的 `id` 均落 DOM，作 `del`/`ins` 定位锚点（无 `_update`，改内容用 del+ins 替换）。典型模式——typing 占位切换正文：`[typing id:t1 text:正在生成]` → 正文到达后 `[del id:t1]`，再流式推 `[bubble role:ai]…[/bubble]`。

> **`id` 全组件兜底**：所有组件的 `id:` 都会落 DOM（组件自身未放置时由渲染器补到组件根），`del`/`ins` 对全组件可用——仅 `tcol`（列定义，无独立 DOM）除外。`input`/`select` 等表单组件的 `id` 仍挂内层输入元素（`upd` 兼容），根不重复盖。

### 8.2 `del` 删除指令（自闭合）

```tokui
[del id:old-card]
```

移除指定 `id` 的组件。命中内层元素（如 hidden input）时向上爬到组件根再整体删除；目标不存在时 `console.warn` 告警（并向统一出口回报 `removed:false`）。不产生 DOM。

- `delay:毫秒`：延迟删除，到点后重新查找目标再执行（期间目标已被删则告警跳过）；先回报 `{removed:false, delayed:ms}`，执行时再回报 `{removed}`。定时器随 `destroy()` 取消。典型场景——toast 式自动退场：`[notification id:n1 …][del id:n1 delay:3000]`。

> 目标是**仍在流式输出中**（未闭合）的容器时，`del` 会排队（回报 `queued:true`），待容器闭合（或流结束）后自动执行——`del` 先于闭标签到达不再丢指令。

### 8.3 `ins` 插入指令（容器）

```tokui
[ins after:target-id][p 插到目标之后][/ins]
[ins before:target-id][p 插到目标之前][/ins]
[ins into:target-id][p 追加为目标的子元素][/ins]
```

子节点在流式期间先入脱离文档的暂存区，闭标签到达时一次性搬到目标位置（页面无错位闪动）。`into` 追加到目标的 `_slot`（内容插入点）。目标必须是**已渲染完成**的组件（顺序渲染保证之前的节点可用）；目标不存在则内容丢弃。

> `into` 只适用于「内容是普通子元素流」的容器（card/list/callout/collapse/bubble/dialog 的 body 等）。结构性容器（`tabs`/`table`/`chart`/`select`/`radio`/`checkbox`/`picker`/`transfer`/`cascader`/`steps`/`menu`/`tree` 等子节点有专用挂载协议）禁止 `into`，会 `console.warn` 并跳过——往这类组件追加内容请用各自的流式子节点协议。

### 8.4 交互事件上报（「用户 → AI」回路）

DSL 用 `on:"事件:处理器,…"`（**必须双引号**）声明组件交互上报，处理器经 `TokUI.registerHandler` 预注册：

```tokui
[input n:city ph:"城市" on:"change:onCityChange"]
[tabs on:"change:onTabSwitch"][tab tt:A]…[/tab][tab tt:B]…[/tab][/tabs]
[dialog tt:"确认" id:dlg on:"close:onDialogClose"]…[/dialog]
```

handler 签名 `(detail, event, element)`，`detail` 携带上下文（如 `{value}` / `{index, title}`）。除命名 handler 外，所有交互同时发到 `new TokUI({ onEvent })` 的统一出口：`onEvent('component', { type, id, event, detail })`——不声明 `on:` 也能在宿主侧全量监听；`new TokUI({ eventFilter })` 可按需过滤（返回 false 丢弃）。

> 引用未注册的 handler 名（`on:`/`clk:` 拼错）会 `console.warn` 提醒（每名称一次），事件不再静默丢弃。
> 程序化行为（`upd` 切换/关闭、autoplay、初始渲染）一律**不上报**——只报用户真实操作，防「服务端 upd → 前端回报 → 再 upd」回环。

各组件支持的事件：

| 组件 | 事件 | detail |
|------|------|--------|
| `input`/`pwd`/`textarea`/`numinput` | `change`（输入防抖 300ms，`db:` 可覆盖毫秒数） | `{value, name}` |
| `select`/`radio`/`checkbox`/`switch`/`slider`/`rate`/`picker`/`transfer`/`cascader`/`input-tag`/`datepicker` 系列 | `change`（值变即报） | `{value, name}` |
| `upload` | `change`（选择/移除文件）/ `progress` / `success` / `error`（后三个仅 `u:` 传输模式） | `{value: 文件名数组, name}` / `{file, percent}` / `{file, response}` / `{file, error}` |
| `tabs` | `change`（用户切页） | `{index, title}` |
| `steps` | `change`（点击步骤，声明 `on` 时步骤可点） | `{index, title}` |
| `menu` | `change`（激活项变化） | `{value}`（项标识：id > v > 文本） |
| `pagination` | `change`（翻页/跳转） | `{value: 页码}` |
| `tree` | `change`（选中节点）/ `check`（复选变化）/ `load`（懒加载完成） | `{value, id}` / `{value: 选中值数组}` / `{value, count}` |
| `table` | `sort`（排序）/ `filter`（筛选）/ `page`（翻页） | `{column, dir}` / `{filters}` / `{value: 页码}` |
| `scroll-area` | `loadmore`（滚动触底） | `{}` |
| `carousel` | `change`（手动切换，autoplay 不报） | `{index}` |
| `conversations` | `change`（选中会话）/ `delete`（删除会话） | `{value}`（会话标识） |
| `dialog`/`drawer` | `close`（仅用户路径；程序化 `act:close` 不报） | `{}` |
| `artifact` | `close`（关闭面板）/ `copy`（复制代码） | `{}` |
| `chat-input` | `send`（发送）/ `stop`（streaming 态点停止按钮）/ `mention`（@ 提及选定） | `{value}` / `{}` / `{value, name}` |
| `msg-actions` | `action`（默认按钮） | `{act: 'copy'/'regenerate'/'like'/'dislike'/'delete'}` |
| `quick-reply` / `suggestion` | `select`（点击项） | `{value: 标签/标题}` |
| `tool-call` | `approval`（HITL 审批，也可用 `clk:` 收） | `{approved, id, name}` |
| `thumb` | `like`（赞/踩；`clk` 通道负载 `{direction, active}` 不变） | `{value: 'up'/'down'}` |
| `source` | `open`（点击标题链接，原生跳转不变） | `{url, title}` |
| `code` / `terminal` / `copy` | `copy`（复制按钮） | `{}` |
| `command` | `select`（选中命令项；`clk` 通道 `{value, text, clk}` 不变） | `{value, text}` |
| `sidebar` | `toggle`（折叠钮切换） | `{collapsed}` |
| `ft-folder`（file-tree 文件夹） | `toggle`（折叠/展开） | `{name, open}` |
| `attach` | `delete`（删除附件） | `{name, url, type}` |
| `welcome-feature` | `select`（点击特性卡片） | `{value: 标题}` |

> `chat-input` 停止按钮未声明 `on:"stop:…"` 时，默认行为是断开**该组件所属** TokUI 实例的 SSE 连接（`disconnect()`，幂等安全；多实例页面不会误停别的实例）。点击后输入框立即恢复发送态（乐观 UI，流未停时服务端可 `upd streaming:true` 恢复）。

> `upd`/`del`/`ins` 指令执行后会向统一出口回报执行结果：`{type:'upd'|'del'|'ins', id, event:'applied', detail:{applied}}` / `{removed}` / `{moved}`——服务端可借此确认指令落地（目标不存在时 applied/removed 为 false、moved 为 0）。

> 命令式确认 `TokUI.modal.confirm(opts)`（别名 `TokUI.confirm(opts)`）→ `Promise<boolean>`：宿主侧 JS API（非 DSL），opts `{tt, tx, t:'danger'|'primary', 'ok-text', 'cancel-text', onOk, onCancel}`，Esc/遮罩点击视为取消，按钮与 aria 文案走 i18n。Agent 需要「是/否」决策时可由宿主桥接此 API 再回传结果。

---

## 9. 完整示例

```tokui
[h1 欢迎使用 TokUI]
[p v:muted 这是一段带样式的文本段落]

[btn tx:"点击我" v:primary clk:handleClick]

;; 图标按钮：icon:NAME 出内置 SVG（自动继承钮色），i:GLYPH 出 emoji，l: 提供 icon-only 的 tooltip+无障碍
[btn icon:view tx:详情 t:primary clk:handleView]
[btn icon:delete l:删除 t:danger clk:handleDelete]   ;; icon-only，悬停显"删除"
[btn i:🔍 tx:搜索 clk:handleSearch]

[card tt:"用户信息"]
  [row]
    [col span:6]
      [input l:"姓名" ph:"请输入" req]
    [/col]
    [col span:6]
      [select l:"部门"]
        [opt 技术部]
        [opt 市场部]
      [/select]
    [/col]
  [/row]
  [ft]
    [btn tx:"提交" v:primary sub:handleSubmit]
    [btn tx:"取消"]
  [/ft]
[/card]

[table stripe]
  [thead cols:"姓名,年龄,城市"]
  [tbody]
    [tr 张三,25,北京]
    [tr 李四,30,上海]
  [/tbody]
[/table]

;; 操作列：单元格以 btn: 开头，| 分隔多钮；支持 icon(SVG)/i(emoji)/l(标签+tooltip)/v(配色)
[table stripe]
  [thead cols:"姓名,操作"]
  [tbody]
    [tr "张三,btn: icon:view l:详情 v:primary clk:handleView|btn: icon:edit l:编辑 v:warning clk:handleEdit|btn: icon:delete l:删除 v:danger clk:handleDelete"]
  [/tbody]
[/table]

[chart t:bar tt:"月度销售" vals l:"1月,2月,3月" d:"120,190,300"]

[bubble role:ai]
  [p 你好，有什么可以帮你的？]
[/bubble]

[progress id:prog v:0 l:"处理进度"]
[upd id:prog v:50]
[upd id:prog v:100 status:success]
```

> 提示：`clk:handleClick` / `sub:handleSubmit` 处理器名需通过 `TokUI.registerHandler(name, fn)` 预注册，服务端不下发可执行代码。