iter(g37): llms-full 增加组合配方章节

packages/tools/cli/bin/ua.js

@@ -359,12 +359,21 @@ function renderAgentDocs(index, tokens) {
     }
     lines.push('---', '');
   }
+/*** 读取组合配方（与 CLI 同目录的 recipes.md），缺失时返回空串 ***/
+function loadRecipes() {
+  const p = path.join(ROOT, 'packages', 'tools', 'cli', 'recipes.md');
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf8').trim() : '';
+}
+
   const tokenList = loadTokenList(); // 令牌唯一来源：tokens.css（含字号、间距复合值）
   if (tokenList.length) {
     lines.push('## 设计令牌（--ua-*）', '');
     for (const t of tokenList) lines.push(`- ${t.cssVar}: ${t.value}${t.dark && t.dark !== t.value ? `（暗色 ${t.dark}）` : ''}`);
     lines.push('', '皮肤包只允许消费这些变量：写死 #hex 会被 verify 拦截，拼错变量名会被令牌引用校验拦截。', '');
   }
+
+  const recipes = loadRecipes(); // 组合配方：跨组件的拼装指导，清单参数表表达不了
+  if (recipes) lines.push('', recipes, '');
   return lines.join('\n');
 }
 

packages/tools/cli/recipes.md

@@ -0,0 +1,80 @@
+# 组合配方（Recipes）
+
+> 单个组件的参数表说明「怎么用」，这些配方说明「怎么拼」。所有配方都只消费组件对外 API，不依赖内部文件。
+
+## 配方 1：表单校验 + 提交反馈
+
+```ts
+const name = signal('');
+const email = signal('');
+const formRef = form({ onSubmit: (ok) => (ok ? result({ status: 'success', title: '已保存' }) : toast.error('请检查表单')) }, [
+  formItem({ label: '名称', value: name, required: true, rules: [{ min: 2 }] }, textField({ value: name })),
+  formItem({ label: '邮箱', value: email, required: true, rules: [{ pattern: /^\S+@\S+$/ }] }, textField({ value: email })),
+]);
+```
+
+要点：
+- 校验规则挂在 `formItem`，值信号只有一个来源（`value` 同时给 `formItem` 与控件），避免两处各存一份。
+- 提交结果用 `toast`（轻量、瞬时）或 `result`（整页终态）表达，不要两者同时弹。
+
+## 配方 2：危险操作二次确认
+
+```ts
+const open = signal(false);
+const dangerOpen = (key: string) => {
+  open(true);
+  return modal({
+    title: `确认删除 ${key}？`,
+    open,
+    size: 'sm',
+    onClose: () => open(false),
+    footer: h('div', { class: 'row' },
+      button({ label: '取消', variant: 'ghost', onClick: () => open(false) }),
+      button({ label: '删除', variant: 'danger', onClick: () => { open(false); toast.success('已删除'); } })),
+  }, h('p', null, '删除后不可恢复。'));
+};
+```
+
+要点：
+- `modal` 自带焦点陷阱与 Esc 逐层关闭，不要在业务层再挂 Esc 监听。
+- 确认按钮用 `variant: 'danger'`，取消用 `ghost`，主次分明。
+
+## 配方 3：表格筛选 + 分页 + 批量操作
+
+```ts
+const picked = signal<string[]>([]);
+const page = signal(1);
+dataTable({
+  data: rows,
+  columns: [{ key: 'name', header: '名称', sortable: true }, { key: 'city', header: '城市' }],
+  pageSize: 10,
+  page,          // 同一 page 信号也给 pagination，二者自动联动
+  selectable: true,
+  selected: picked,
+  loading: saving,
+});
+pagination({ page, pageSize: 10, total: rows.length, jumpable: true, onChange: (p) => page(p) });
+```
+
+要点：
+- `page` 信号是表格与分页器的唯一共享状态；外部改页码前自己钳制范围（core 的 `setPage` 不做钳制）。
+- 选中一律存 `rowKey`，翻页/筛选后仍然稳定；全选只作用于当前可见行。
+- 批量操作按钮在 `picked().length === 0` 时禁用，避免空提交。
+
+## 配方 4：长列表数据加载与空态
+
+```ts
+const loading = signal(true);
+const items = signal<ListItem[]>([]);
+list({ items: items(), bordered: true, emptyText: loading() ? '加载中…' : '暂无数据' });
+```
+
+要点：
+- 空态文案随加载态切换；列表本身会在 `items` 为空时渲染 `empty`，不需要业务层再判断一次。
+- 需要骨架屏就换成 `skeleton`，加载完成再 `renderList` 成真实行。
+
+## 通用约定
+
+- 状态一律放信号（`signal` / `computed`），组件只读写信号，不持有业务数据副本。
+- 反馈分层：`toast` 右上角瞬时、`notification` 右下角可长读、`result` 整页终态、`alert` 页内常驻。
+- 样式不要写颜色与间距字面值，先跑 `ua tokens` 查 `--ua-*`（verify 会拦截未定义令牌与 `#hex`）。