@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/grafton-view-dev/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: grafton-view-dev
+description: '用 @xgent-ai/grafton 做 schema 驱动 UI 开发的工作流与速查。当需要：(1) 用 JSON schema 写/改一个 grafton view，(2) 写绑定表达式（@store:: / @view:: / @local:: / @action:: / @form::），(3) 写 zustood store（createStore / extendSelectors / extendActions / createApiStore 等）并在 schema 中读写，(4) 写列表模板、条件渲染、双向绑定、表单，(5) 写带 Component.grafton 元数据的自定义 widget，(6) 排查 grafton 渲染报错（hooks 顺序崩溃、bindable 组件点不动、Fragment className、$type 解析失败）时，使用此 Skill。凡是涉及 createView / grafton schema / @store:: 表达式 / grafton widget 的活，都先用它，别凭记忆硬写。注意：配置 grafton-app.json 用 web-app-dev，创建模块脚手架用 web-module-dev。'
+---
+
+# Grafton View Dev
+
+`@xgent-ai/grafton` 把 **JSON schema 解析为 React 组件树**：schema 声明组件类型、props、插槽、列表模板、条件渲染，以及对 store / 表单 / 本地上下文的数据绑定与动作绑定。
+
+本文是**开发时的高频速查 + 标准工作流 + 必避的坑**；详尽细节按主题拆进 `references/`，**写到拿不准时按需读对应文件**(不要一次性全读)：
+
+| 要做的事 | 读 |
+|---|---|
+| 写绑定 / 值级条件对象 / `.$` 操作符 / `<>` 双向绑定 / 导航动作 | [references/bindings.md](references/bindings.md) |
+| 节点特殊键全集 / `$type` 解析 / createView · createLazyView 参数 | [references/schema.md](references/schema.md) |
+| store / selector / action / 持久化 / hooks / 三件套 / HTTP 获取 | [references/stores.md](references/stores.md) |
+| 内置组件清单 / 自定义 widget(grafton 元数据) / slots / renderers / 表单 / i18n | [references/components.md](references/components.md) |
+| 可直接抄改的完整示例(列表 / 异步加载 / 双绑过滤器 / widget / 表单 / 路由重挂载) | [references/recipes.md](references/recipes.md) |
+
+> 本 skill 不覆盖 WiseView 扩展与流式视图(`createStreamingView`)——那两块直接看源码。
+
+## 心智模型
+
+```
+schema (JSON)  +  registry (组件表)  +  stores (zustood 状态)
+        │
+        ▼
+   createView()  ──►  React 组件
+```
+
+- **schema**：嵌套 JSON 节点，`$type` 指组件，其余键为 props，`$content` 为子节点。
+- **registry**：`$type` 名 → React 组件。grafton 内置组件(`graftons`)自动并入，不用注册。
+- **stores**：zustood store，schema 里用 `@store::` 等前缀读写，**响应式**。
+- **payload**：沿组件树向下传的本地上下文(列表项数据 `{data, index}`、`$payload` 变量、局部 registry)，用 `@local::` 读。
+
+数据流：`store → UI`(绑定)、`事件 → @action → store`(动作)、`<>` 双向绑定让一个 prop 同时读写。
+
+## 标准工作流：写一个 view
+
+1. **定义 store**(工厂函数,见下) → verify：`bun test` 或在视图里读得到值。
+2. **`createView({ schema, registry, stores, ns })`** → verify：页面渲染无红色 ErrorPanel。
+3. **schema 里用绑定接数据**(`@store::`/`@view::`/`@local::`) → verify：改 store 数据 UI 跟着变。
+4. **接动作**(`onClick: '@action::...'` 或动作对象) → verify：点击触发、状态变化。
+5. **列表/条件/表单** 按需加(见下)。
+6. **UI 改动必须在浏览器里验证**(项目约定)：用 Chrome extension 跑通主路径，别只看 diff/类型检查。设计阶段先过 `impeccable`。
+
+注册组件：内置组件自动可用；`Button` / `NavSelect` / `Form` 等来自 `@xgent-ai/ui-shadcn`，**必须** 传进 `createView` 的 `registry`。
+
+## 绑定表达式速查（最高频）
+
+字符串值形如 `[!][<>]@source::path` 时按引用解析，否则按字面量。
+
+### 数据源前缀
+
+| 前缀 | 解析自 | 双向 | 例 |
+|------|--------|------|----|
+| `@store::` | StoresProvider 的 store | ✓ | `@store::tasks.remaining`、`@store::test.formData.tags` |
+| `@view::` | 内置 view store(视图局部态 + 工具 selector) | ✓ | `@view::subtitle`、`@view::_isEmpty` |
+| `@local::` / `@payload::` | 当前 payload | ✗ | `@local::data.title`、`@local::index` |
+| `@action::` | 内置动作 或 store 动作 | ✗ | `@action::navPush`、`@action::tasks.addTask` |
+| `@form::` | react-hook-form 上下文(需在 `Form` 内) | ✗ | `{ "$selector": "@form::watch", "$args": ["title"] }` |
+| `@fieldArray::` / `@fieldArrayItem::` / `@fieldArrayValues::` | 数组字段 / 当前项 / 当前项值 | ✗ | `@fieldArray::append` |
+| `@hook::` / `@context::` / `@registry::` | 注册的 hook / 渲染上下文 / factory registry | ✗ | `@hook::useSidebar` |
+
+### 修饰符
+
+- **`!` 取反**：`"!@store::app.loading"`(`@action::` 不支持)。⚠️ 取反**只有 `!` 前缀**,没有 `$not`/`$negate` 字段——写了会被无视、逻辑反掉。
+- **`<>` 双向绑定**：`"<>@store::tasks.filter"`。**只支持 `store`/`view` 源**，且目标 prop 必须在组件 `grafton.bindable` 中声明。
+- **动态键 `.[...]`**：`"@store::perms.[@local::data.roleId].name"`,方括号内引用先求值再拼路径。
+- **`.$` 操作符**(对取到的值加工)：`$size` `$keys` `$values` `$pick:a,b` `$slice:0,3` `$join:,` `$split:,` `$remap:to=from` `$mapGet:path` `$cast:type` 等。例 `"@store::tasks.tasks.$size"`。
+
+### 值级表达式对象（任意 prop 值都能用，可嵌套）
+
+```jsonc
+{ "$selector": "@store::tasks.visibleTasks", "$args": ["active"] }   // 带参 selector，! 可取反
+{ "$action": "@action::tasks.addTask", "$args": ["x"], "$withEventArgs": false }  // 动作对象
+{ "$if": "@local::data.done", "$then": "line-through", "$else": "" }  // 条件取值
+{ "$and": ["@store::a.ready", "!@store::a.error"] }
+{ "$or": ["@local::data.urgent", "@local::data.pinned"] }
+{ "$ifNull": "@store::tasks.filter", "$then": "all" }    // 空值兜底
+{ "$extends": ["@store::app.baseProps"], "size": "sm" }  // 对象浅合并(后者覆盖)
+{ "$concats": ["@store::a.list1", "@store::a.list2"] }   // 数组拼接
+{ "$effect": "report.track", "$args": ["click"] }        // store side effect
+```
+
+**动作对象字段**：`$action`(必填) · `$args`(预置参数,走绑定解析) · `$withEventArgs`(默认 `true`,把事件参数附在 `$args` 后 —— 给 action 传精确参数时**关掉**) · `$eventArgsFirst` · `$preventDefault` / `$stopPropagation` · `$debounced: {throttled, interval, leading, tailing}`。
+
+## Schema 节点特殊键速查
+
+| 键 | 语义 |
+|----|------|
+| `$type` | 组件类型(必填)。解析顺序：HTML 白名单 → 当前组件局部 registry → 祖先 payload registry → view registry+内置。全未命中→红色 ErrorPanel |
+| `$content` | 子内容→children。只渲染 truthy 值；数组渲染为列表；`leaf` 组件禁用 |
+| `$when` | 求值**严格 === `false`** 才隐藏节点。⚠️ `0`/`""`/`null` 不隐藏 —— 要布尔语义配 `_isEmpty`/`_isNull` 或 `!` |
+| `$payload` | 声明 payload 变量(支持绑定),与父级合并下发,子树 `@local::` 读 |
+| `$clearParentPayload` | 切断父级 payload 继承(含累积 registry) |
+| `$style` | 追加 className(与 `className` 用 `cn()` 合并)。惯例：基础类写 `className`,动态/附加写 `$style` |
+| `$tooltip` | 包一层 Tooltip,字符串等价 `{title}` |
+| `$action` | 快捷链接：字符串→href(`"_target:href"` 指定 target),函数→`<a onClick>` |
+| `$breakpointProps` | 响应式 props `{sm:{...}, md:{...}}`,按断点级联合并 |
+| `$mapping` | 列表模板里把数据项字段直通 props：`{propName: fieldName}` |
+| `$key` | 渲染时剥离。列表项 key 只在**数据项自身**含 `$key` 时由 `ListRenderer` 用 |
+| `$effects` | 副作用列表,项为 `"store.effectName"` 或 `{$effect, $args}` |
+| `$extendSchema` / `$comment` / `$debug` | 运行时扩展 / 注释 / 调试输出 |
+
+## Store 速查
+
+store 永远是**工厂函数**,交给 `createView`(或 `StoresProvider`)在渲染时实例化：
+
+```js
+const myStore = (props, parentStores, getStores) =>
+  createStore('my')({ count: 0 /* initialState 必填 */ }, { /* options 可选 */ })
+    .extendSelectors((api) => ({
+      doubled: (state) => state.count * 2,            // (state, ...args) => value
+      hasItem: (state, id) => state.items.some(i => i.id === id),
+    }))
+    .extendActions((api) => ({
+      inc: () => api.set.count(api.get.count() + 1),
+      addItem: (it) => api.set.state(draft => { draft.items.push(it); }),  // immer draft
+      load: async () => { api.set.items(await Runtime.$api.get_('/items')); },
+    }));
+```
+
+**每个状态 key 自动生成**：`get.x()`(同步读) · `set.x(v)`(写,**新旧 `===` 时跳过**) · `use.x()`(hook 订阅)。schema 侧：`@store::my.x` 读 → `use.x()`；`@action::my.x` 写 → `set.x`。
+
+**`set` 上始终可用**：`set.state(objOrFn)`(immer) · `set.toggleState(path)`(翻转布尔,支持深路径) · `set.enableState/disableState(path)` · `set.useSideEffect(key, ...args)`。
+
+**链式扩展**：
+- `extendSelectors` —— 派生值;selector 之间可 `api.get.x()` 复用。⚠️ 返回**每次新建的深对象**会绕过浅比较致多余重渲染。
+- `extendMemoSelectors` —— 带缓存：`{ deps: (state)=>({...}), selector: (depsResult)=>... }`,deps 浅比较未变则不重算。⚠️ **只有一个缓存槽**,不适合参数高频交替。
+- `extendActions` —— 闭包函数挂到 `set`;重名覆盖,旧实现存于 `新函数.origin`;可 async。
+- `extendSideEffect` —— `useEffect` 驱动的副作用:`{ deps: (state,...a)=>[...], effect: (...deps)=>cleanup? }`,经 `$effects` 或 `set.useSideEffect` 消费。
+
+**配置项**(`createStore(name)(init, options)`)：`isGlobal`(注册进 `Runtime.stores`) · `middlewares`(immer 始终内置) · `devtools`(⚠️ 须先在 `Runtime.init` 的 `addons` 注入 `storeDevTools`) · `persist` / 任意 `persist*` 前缀(各为一条持久化通道)。
+
+**内置 view store**：每个视图自带,`@view::` 读。渲染时 `data` prop 成其初始状态(每 key 有自动 setter,支持 `<>` / `@action::view.x`);`selectors` prop 追加自定义 selector。工具 selector：`_isEmpty` `_isNull` `_isEqual` `_and` `_or` `_template(text,data)` `_toPath(...parts)` `_filterOut(data,key,value)` `_parent` 等。
+
+**专用 store 三件套**(完整配置见 [references/stores.md](references/stores.md),用到再查)：
+- `createApiStore` —— API 获取+缓存+Suspense,每个 API 一个惰性 selector。⚠️ 默认 `transformer` 假定响应形如 `{data, ...}`,不是这形状必须自定义。
+- `createEntityStore` —— 按 id 缓存实体,`use.byId(id)` / `use.entities` Proxy。
+- `createListStore` —— 列表/表格,`load` 须 resolve `{schema, rows, totalRows?, cursor?}`,`set.loadMore()` 追加。
+
+## 列表 / 条件 / 双向绑定 / 表单（高频模式）
+
+**列表**：`List` 接 `data` + `itemTemplate`;每项往 payload 注入 `{data, index}`,模板内 `@local::data.x` 读。`$mapping` 字段直通。**列表 key 必须由数据携带**(`{ "$key": "id", "id": 1, ... }`),写在 itemTemplate 上的 `$key` 不参与外层 key,`$mapping` 也不能稳定 key。⚠️ 空状态用 `emptyState` slot(`List`/`PlainList`/`DataList` 都支持,data 空/null 时渲染)。想要网格/容器样式 → 挂在 `List` 的 `className`(真实 `ul`/`ol` 容器);`PlainList` 容器是 `Fragment`、挂 className 无效;`before`/`after` 是夹在列表项前后的**兄弟节点不是包裹层**(网格容器别放 before),且空分支下 before/after 不渲染。详见 [references/components.md](references/components.md)。
+
+**条件**：节点级用 `$when`(严格 `=== false` 隐藏);prop 级用 `$if`/`$and`/`$or`/`$ifNull`;整块 UI 二选一用 `IfElse`/`Switch` 组件。
+
+**双向绑定**：`"value": "<>@store::tasks.filter"`。组件侧用 `signal()` 解包成 `[value, setter]`。
+
+**表单**(`Form` 等来自 `@xgent-ai/ui-shadcn/widgets`,grafton 本体不含)：`Form` 接 `defaultValues`/`onSubmit`/`resolver`,通过局部 registry 注入 rhf 上下文,字段组件**必须**在 `Form` 子树内;`onSubmit` 的 action 收到表单值对象。
+
+## 自定义 widget（Component.grafton 元数据）
+
+任何 React 组件注册进 registry 即可用;带 `Component.grafton` 静态元数据的才是 **grafton widget**：
+
+```jsx
+function TaskItem({ title, done, statusIcon, actions }) { /* ... */ }
+TaskItem.grafton = {
+  leaf: true,                  // 禁止 $content
+  bindable: ['value'],         // 允许 "<>" 双向绑定的 prop
+  slots: ['statusIcon', 'actions'],  // 值是 schema，grafton 先渲染成 ReactNode 再传入
+  registry: { Title: SheetTitle },   // 局部注册表，只在该组件子树内解析 $type
+};
+```
+
+元数据字段：`leaf` · `t`(注入 i18n `t`) · `bindable` · `slots`(`'name'` 或 `{name, required?, template?}`) · `renderers`(schema prop → `(item,index)=>El`,`List` 的 `itemTemplate` 即此) · `registry` · `factory` / `payload` / `schema`(元组件用)。
+
+**bindable + signal()**：`signal(value)` 在绑定时返回真 setter,**传普通值时 setter 是 no-op**(`isNotSetter` 标志)——见下方坑 #1。
+
+## ⚠️ 必避的坑（LLM 最容易写错的）
+
+1. **bindable 受控组件传静态值是只读且无报错的**。`NavSelect`/`SelectWidget`/`SliderWidget`/`ToggleGroupWidget`/`FilterTabs` 等,`value` **必须** `<>@store::`/`<>@view::` 绑定才能交互。"组件渲染正常但点不动/拖不动"先查这里。
+2. **`Text` 的 `variant: "plain"` 渲染为 Fragment,不能带 className**(报 "Invalid prop className supplied to React.Fragment")。要样式包一层 `div`/`span`。
+3. **SPA 路由切换,不同 schema 的页面级树必须按路由 key 重挂载**:`<StoresProvider key={pathname}>` 或路由出口包 `<Fragment key={pathname}>`。否则 React 同位复用实例、hooks 数量不一致直接崩("change in the order of Hooks called by Grafton")。
+4. **响应式状态用"已存在 store 的 setter + selector"**,不要靠重建 view store(给视图传新 `data`)刷新已挂载节点 —— 已渲染节点的订阅不跟随 store 实例重建。
+5. **内置 `Link` 不转发 ref**:放进 Radix `asChild`/Slot 位置时改用 `@xgent-ai/router-lite` 的 `Link`(forwardRef,`to` 属性)。
+6. **局部注册表只在子树内有效**:`Title`/`Close` 这类名字必须出现在声明它们的组件(如 `DialogWidget`)的 slots/子树内,校验/预览解析 `$type` 时才找得到。
+7. **`devtools: {enabled:true}` 须先注入 addon**(`Runtime.init` 的 `addons.storeDevTools`),否则创建 store 直接抛错。
+8. **selector 返回新建深对象**绕过浅比较致多余重渲染 → 用 `extendMemoSelectors`(但注意单缓存槽)。
+9. **来自数据的字符串都应 `noTranslate: true`**,否则碰巧与翻译 key 同形会被误翻。
+10. **Tailwind v4 不扫 node_modules**:grafton/ui-shadcn 的类要靠 `@source` 显式纳入,否则组件"没样式"(项目搭建/配置属 `web-app-dev` skill 范畴)。
+
+## 自检清单
+
+写完一个 view,逐项核对：
+
+- [ ] 自定义组件(Button/Form/...)都进了 `registry`？内置组件不用注册。
+- [ ] 交互型 bindable 组件都用了 `<>` 绑定,不是静态值？(坑 #1)
+- [ ] 列表数据项都带了 `$key` 字段稳定 key？(不是写在 itemTemplate 上)
+- [ ] `$when` 想要布尔语义时配了 `_isEmpty`/`_isNull`/`!`,没指望 falsy 隐藏？(坑 #2 of `$when`)
+- [ ] 给 action 传精确参数时 `$withEventArgs: false`？
+- [ ] 数据来源字符串都 `noTranslate`,文案用了翻译 key？
+- [ ] 多页应用页面级树按路由 key 重挂载？(坑 #3)
+- [ ] **在浏览器里真的跑通了**(不是只看 diff/类型检查)？

package/skills/grafton-view-dev/references/bindings.md

@@ -0,0 +1,120 @@
+# 绑定表达式 / 值级对象 / 双向绑定 / 内置动作
+
+schema 里如何读写数据。读本文当：写 `@store::`/`@view::`/`@local::`/`@action::`/`@form::`、值级条件对象、`<>` 双向绑定、导航动作。
+
+## 引用 vs 字面量
+
+字符串值形如 `[!][<>]@source::path` 时按**引用**解析，否则按**字面量**。
+
+## 数据源前缀
+
+| 前缀 | 解析自 | 双向 | 说明 / 例 |
+|------|--------|------|----------|
+| `@store::` / `@stores::` | StoresProvider 里的 store | ✓ | 路径点号取值；命中 selector 可配 `$args`。`@store::test.formData.tags` |
+| `@view::` | 内置 view store | ✓ | 视图局部态 + 工具 selector。`@view::subtitle`、`@view::_isEmpty` |
+| `@local::` / `@payload::` | 当前 payload | ✗ | 列表项 `@local::data.label`、`@local::index`、`$payload` 声明的变量 |
+| `@action::` / `@actions::` | 内置动作 或 store 动作 | ✗ | 无点号→内置动作；`store.x`→store 的 action/setter |
+| `@form::` | react-hook-form 上下文(需在 `Form` 内) | ✗ | `@form::watch` 带 `$args`；自动注入 `hook::useFormContext` |
+| `@fieldArray::` | useFieldArray 上下文 | ✗ | 数组字段操作 `append`/`remove` 等 |
+| `@fieldArrayItem::` | 当前数组项上下文 | ✗ | `index`、`namePrefix` 等 |
+| `@fieldArrayValues::` | 当前数组项的表单值 | ✗ | watch + getValues 合并 |
+| `@hook::` | registry 中注册的 hook | ✗ | `@hook::useSidebar`(注册名 `hook::useSidebar`) |
+| `@context::` | 渲染上下文对象 | ✗ | 取 context 上的值 |
+| `@registry::` | view factory registry | ✗ | 读 registry 条目(等价 `context.factory.registry`) |
+
+## 修饰符
+
+- **`!` 取反**：`"!@store::app.loading"` → 布尔取反(字符串前缀,或 `$selector` 字符串前缀)。`@action::` **不支持**。⚠️ 取反**只有 `!` 前缀这一种**——`$selector`/值级对象上**没有 `$not`/`$negate` 之类的键**(见 `translateSelector`),写了会被无视、逻辑悄悄反掉。
+- **`<>` 双向绑定**：`"<>@store::test.sortedBy"`。**只支持 `store`/`view` 源**，且目标 prop 必须在组件 `grafton.bindable` 中声明。组件侧收到 `[value, setter]` 元组，用 `signal()` 解包（见末尾）。
+- **动态键 `.[...]`**：`"@store::permissions.[@local::data.roleId].name"` —— 方括号内是另一个引用，运行时求值为字符串后拼进路径。
+- **路径 `.$` 操作符**（对取到的值再加工）：
+
+| 操作符 | 作用 |
+|--------|------|
+| `$get` | 取整体 |
+| `$keys` / `$values` | 对象键 / 值数组 |
+| `$size` | 长度 / 元素数。`"@store::test.tags.$size"` |
+| `$pick:a,b` | 取指定字段子对象 |
+| `$remap:to=from` | 字段改名 |
+| `$mapGet:path` | 对数组每项取 path |
+| `$slice:0,3` | 切片 |
+| `$split:,` / `$join:,` | 字符串拆 / 数组合 |
+| `$padLeft:x` / `$padRight:x` | 补齐 |
+| `$box:key` | 包成 `{key: value}` |
+| `$cast:type` | 类型转换 |
+
+## 值级表达式对象
+
+任意 prop 的值都可以是下列对象（可嵌套，`$args` 的每一项也走同样解析）。
+
+### 选择器调用
+
+```json
+{ "$selector": "@store::library.isEntryActive", "$args": ["widget", "@local::data.name"] }
+```
+
+`$selector` 指向 store selector（`extendSelectors`，签名 `(state, ...args)`）或内置 view selector，`$args` 为参数。前缀 `!` 可取反。
+
+### 动作对象
+
+```json
+{ "$action": "@action::test.toggleState", "$args": ["showAlert"], "$withEventArgs": false }
+```
+
+| 字段 | 默认 | 说明 |
+|------|------|------|
+| `$action` | 必填 | 动作引用；无 `@` 前缀时自动按 `@action::` 解析 |
+| `$args` | `[]` | 预置参数（支持绑定表达式） |
+| `$withEventArgs` | `true` | 是否把事件参数附加在 `$args` **之后**。给 action 传精确参数时**关掉** |
+| `$eventArgsFirst` | `false` | 事件参数放在 `$args` **之前** |
+| `$preventDefault` / `$stopPropagation` | — | 调用对应事件方法 |
+| `$debounced` | — | `{throttled, interval=2000, leading=true, tailing}` 防抖/节流 |
+
+### 条件与组合（值级，可出现在任何 prop 值）
+
+```jsonc
+{ "$if": "@store::app.loading", "$then": "Loading...", "$else": "Submit" }
+{ "$and": ["@store::a.ready", "!@store::a.error"] }
+{ "$or": ["@local::data.urgent", "@local::data.pinned"] }
+{ "$ifNull": "@store::user.nickname", "$then": "Anonymous" }   // 空值兜底
+{ "$extends": ["@store::app.baseProps"], "size": "sm" }         // 对象浅合并(后者覆盖)
+{ "$concats": ["@store::a.list1", "@store::a.list2"] }          // 数组拼接
+{ "$effect": "report.track", "$args": ["click"] }               // store side effect
+```
+
+> schema 级（整块 UI 二选一）的分支用 `IfElse` / `Switch` 组件，见 [components.md](components.md)。prop 级条件优先 `$if`。
+
+## 内置动作
+
+`@action::xxx`（无点号）解析为内置动作：
+
+| 动作 | 参数 | 行为 |
+|------|------|------|
+| `alert` | `(message)` | 浏览器 alert |
+| `navPush` | `(href)` | SPA 路由 push |
+| `navReplace` | `(href)` | SPA 路由 replace |
+| `navBack` / `navForward` | — | 历史前进/后退 |
+| `navReload` | — | 整页刷新 |
+| `navRedirect` | `(href)` | `window.location` 硬跳转 |
+| `navUpdate` | `(query, reload?)` | 更新当前 URL query |
+
+> 导航动作依赖 router 上下文 —— 这就是视图必须渲染在 `RouterProvider` 之内的原因。
+
+`@action::store.x`（有点号）按顺序匹配：store 的 **action → 自动 setter → 内置 set 动作**（`toggleState`/`enableState`/`disableState`，见 [stores.md](stores.md)）。
+
+## 双向绑定与 signal
+
+声明了 `bindable: ['value']` 的组件，prop 以 `"<>@store::x.y"` 绑定时，组件实际收到 `[value, setter]` 元组。组件内用 `signal()` 解包：
+
+```js
+import { signal } from '@xgent-ai/grafton';
+
+function SliderWidget({ value, ... }) {
+  const [current, setCurrent] = signal(value ?? min);
+  // 绑定时:setCurrent 写回 store;传普通值时:setCurrent 是 no-op!
+}
+```
+
+⚠️ **`signal(普通值)` 返回的 setter 是 no-op**（函数带 `isNotSetter = true` 标志）。受控型 bindable 组件（SliderWidget、RangeWidget、SelectWidget、ToggleGroupWidget、NavSelect 等）**传静态值时只读** —— 滑杆拖不动、选择不生效且无报错。要交互必须 `<>@store::` / `<>@view::` 绑定。
+
+写回落点：绑定路径单段 → `store.set.<key>`（自动 setter **或同名 action**）；多段 → `set.state` 深路径写入（`useSignal` 语义）。

package/skills/grafton-view-dev/references/components.md

@@ -0,0 +1,168 @@
+# 内置组件 / Widget 元数据 / 表单 / i18n
+
+读本文当：选用内置组件、写带 `Component.grafton` 元数据的自定义 widget、用 slots/renderers/局部注册表、接表单、配 i18n。
+
+## 内置组件（graftons，自动并入 registry，无需注册）
+
+| 组件 | 要点 |
+|------|------|
+| `Box` / `VBox` / `HBox` / `Container` | 布局容器；`as` 换标签；V/H 为 flex 列/行 |
+| `ResponsiveContainer` | 监听容器宽度，经 `ResponsiveContext` 向子树提供宽度；宽度初始化后才渲染 children |
+| `Wrap` | 有 `before`/`after` slot 时才包一层 `with` 指定容器，否则裸渲染 children |
+| `Text` | `text` + `variant`（`default`/`heading`/`blockquote`/`code`/`keyboard`/`emphasis`/`strong`/`quote`/`span`/`plain`）。⚠️ **`plain` 渲染为 Fragment，不能带 className**；`noTranslate` 跳过翻译；`values` 模板插值 |
+| `Icon` | `variant: "registry"`（查 `icon::name`）/ `"asset"`（SVG sprite）/ `"url"`（mask-image） |
+| `List` / `PlainList` | 数据列表；`data` + `itemTemplate`；都支持 `emptyState` slot。⚠️ `List` 有真实容器(`ul`/`ol`)→ 布局/网格类挂 `List` 的 `className` 生效;`PlainList` 容器是 `Fragment` → className 无效、做不了容器样式。详见下「列表容器、布局与空状态」 |
+| `DataList` | key-value 展示（Radix DataList）；`icons`/`itemProps`/`i18nPrefix` |
+| `ListRenderer` | 底层列表渲染器（`as`/`itemContainerAs`/`keyExtractor`…），组件作者用 |
+| `Link` | `link` 为绝对 URL 渲染 `<a>`，否则 RouterLink(SPA)。⚠️ **不转发 ref**，配 `asChild`/Slot 时换 `@xgent-ai/router-lite` 的 `Link` |
+| `Action` | `action` prop：字符串(URL) / 函数 / `{type:'link'\|'action', value}`，渲染为链接或可点击元素 |
+| `RegistryView` | 按 `name` 渲染 registry 中的命名 schema（`schema::name`） |
+| `DynamicView` | 渲染任意 `schema` prop，自带 ErrorBoundary（用于渲染来自数据的任意 schema） |
+| `IfElse` | `value` ? 渲染 `then` schema : `else` schema；分支为 `"/path"` 字符串时跳转 |
+| `Switch` | 按 `value` 在 `cases` 映射中选 schema，`default` 兜底 |
+| `Tooltip` | `title`（经 i18n）+ children；`TooltipProvider` 已由 createView 提供 |
+| `Image` | `<img>` + object-contain |
+| `ErrorPanel` / `ErrorBoundary` | 错误面板（红底 `role="alert"`，prop 为 `error` 对象，显示 `error.message`）与边界 |
+| `SlotsContainer` / `Slot` / `SlotContent` / `Fragment` | 显式插槽组合原语 |
+| `Outlet` | `@xgent-ai/router-lite` 的子路由出口 |
+| `Delegate` | `@radix-ui/react-slot` 的 `Slot` 别名，把 props 委托给子元素 |
+
+> `Form` 及字段组件**不在**内置中，由组件库（`@xgent-ai/ui-shadcn`）提供；grafton 只提供 hook 注入与 `@form::` 解析机制（见末尾「表单」）。
+
+## 组件 grafton 元数据
+
+组件用静态属性 `Component.grafton = {...}` 声明能力，grafton 渲染时按此注入：
+
+| 字段 | 说明 |
+|------|------|
+| `leaf` | 叶子组件，禁止 `$content`（传了报错） |
+| `t` | 注入 i18n 翻译函数为 `t` prop（配合节点 `ns`） |
+| `factory` | 注入 view factory（组件内手动渲染 schema / 取 registry 组件） |
+| `payload` | 注入当前 payload 为 prop |
+| `schema` | 注入当前节点 schema 为 prop（元组件/编辑器用） |
+| `dir` | 布局方向标注（`'v'`/`'h'`，文档性质） |
+| `bindable` | 允许 `<>` 双向绑定的 prop 名数组（见 [bindings.md](bindings.md)） |
+| `slots` | 具名插槽，项为 `'name'` 或 `{name, required?, template?}` |
+| `renderers` | 模板渲染器，项为 `'name'` 或 `{name, fromProp, template}` |
+| `registry` | 局部注册表：`$type` 名 → 组件，只在该组件子树内可解析，沿子树累积 |
+
+```jsx
+import { cn } from '@xgent-ai/grafton/utils';
+
+function TaskItem({ title, done, statusIcon, actions, className }) {
+  return (
+    <div className={cn('flex items-center gap-3 rounded-lg border p-3', className)}>
+      {statusIcon}
+      <span className={cn(done && 'line-through text-muted-foreground')}>{title}</span>
+      <div className="ml-auto flex gap-1">{actions}</div>
+    </div>
+  );
+}
+TaskItem.grafton = { leaf: true, slots: ['statusIcon', 'actions'] };
+```
+
+## slots：插槽
+
+slot 类 prop 的值是一段 schema（单个或数组），grafton 在组件渲染前先渲染成 React 元素再传入（组件作者拿到的是普通 `ReactNode`）：
+
+- `required: true` 且未提供时：有 `template` 用模板兜底，否则报错；
+- 提供的 schema 会与 `template` 合并（数组逐项合并）；
+- 插槽 schema 里照常可用 `@local::`（在当前节点 payload 上下文渲染）。
+
+```js
+SideSheet.grafton = { slots: ['trigger', 'header', 'footer'], registry: { Title: SheetTitle, Close: SheetClose } };
+```
+```json
+{ "$type": "SideSheet", "trigger": { "$type": "Button", "$content": "Open" }, "header": [{ "$type": "Title", "$content": "标题" }] }
+```
+
+## renderers：列表与模板
+
+`renderers` 把一个 schema prop 转成 `(itemData, index) => ReactElement` 渲染函数。约定：渲染函数名 `renderItem`，来源 prop 名 `itemTemplate`（`List` 即此）。
+
+模板渲染每项时，payload 注入 `{ data: item, index }`，故模板内：
+- `@local::data.xxx` 读当前项字段；
+- `$mapping: { "toProp": "fromField" }` 把项字段直接映射成模板 props；
+- **外层列表项 React key**：数据项自身有 `$key` 时取 `item[item.$key]`；否则用组件 `keyExtractor(item, index)`；再否则用 index。⚠️ `itemTemplate.$key` **不**参与外层 list item key，`$mapping` 也不能稳定外层 key。
+
+## 列表容器、布局与空状态
+
+底层 `ListRenderer` 的渲染分两支:
+
+```jsx
+data?.length
+  ? <ListContainer {...props}>{before}{items}{after}</ListContainer>   // 非空
+  : children                                                          // 空/null:兜底分支
+```
+
+由此推出三条必须记牢的事实:
+
+- **要网格/容器样式 → 挂在 `List` 的 `className`(它是真实 `ul`/`ol`,className 落在容器上)。** `PlainList` 的容器是 `Fragment`,挂 className 完全无效,做不了网格;它用于"无容器样式的裸列表"。`variant: "column"` 是 `List` 的内置网格预设。
+- **`before`/`after` 不是包裹层**:它们是容器内夹在列表项前后的**兄弟节点**。把网格容器放进 `before` 不会套住卡片(网格不生效)——这是常见错误。
+- **空状态**:`List` / `PlainList` / `DataList` **都有 `emptyState` slot**(与组件库的 `Grid`/`Pane`/`Table` 一致),`data` 为 null 或空数组时渲染它。⚠️ 进入 emptyState 分支时,`before`/`after`/列表项都**不渲染**(整个容器被 emptyState 取代)。也可不用 slot,在列表外面用 `$when:_isEmpty` 的对偶节点控制(见 [recipes.md](recipes.md) #2),但 `emptyState` slot 更简洁、是推荐写法。
+
+```json
+{
+  "$type": "List", "variant": "column",
+  "data": "@store::test.actions",
+  "itemTemplate": { "$type": "MenuItem", "$mapping": { "label": "label" }, "$content": "@local::data.label" }
+}
+```
+
+要用数据稳定 key，让每项携带 key 字段与 `$key` 指示：
+```json
+{ "data": [ { "$key": "value", "value": "open", "label": "Open" }, { "$key": "value", "value": "close", "label": "Close" } ] }
+```
+
+## registry：局部注册表
+
+局部注册表中的 `$type` 只在该组件 slots/子树内可解析，并向更深子树累积（`$clearParentPayload` 切断）。除组件外支持命名空间条目：
+
+- `hook::xxx` —— 注册 hook，供 `@hook::xxx`（内置已注册 `useRef`、`useId` 等）；
+- `icon::xxx` —— 注册图标，`Icon` 的 `variant:"registry"` 按 name 查；
+- `schema::xxx` —— 注册命名 schema，`RegistryView` 按 name 查；
+- `style::xxx` —— 注册样式串。
+
+`createView` 的 registry 里传 `icons: {...}` / `schemas: {...}` / `hooks: {...}` 对象，自动展开成上述命名空间条目：
+
+```jsx
+import { Plus } from 'lucide-react';
+createView({
+  registry: {
+    TaskItem,
+    icons: { Plus },                                                          // → icon::Plus
+    schemas: { taskCard: { $type: 'TaskItem', $mapping: { title: 'title' } } }, // → schema::taskCard
+  },
+});
+```
+```json
+{ "$type": "Icon", "variant": "registry", "name": "Plus", "className": "size-4" }
+{ "$type": "RegistryView", "name": "taskCard" }
+```
+
+> ⚠️ 局部注册表只在子树内有效：校验/预览解析 `$type` 时，`Title`/`Close` 这类名字必须出现在声明它们的组件（如 `DialogWidget`）的 slots/子树内。
+
+## 表单
+
+`Form`（组件库提供，如 `@xgent-ai/ui-shadcn/widgets`）通过 `registry: {'hook::useFormContext':..., 'hook::useWatch':...}` 向子树暴露 react-hook-form 上下文；字段组件（`FormInput` 等）在 `Form` 内**自动注册**，因此**必须**位于 `Form` 子树内。
+
+- `Form` 接 `defaultValues` / `onSubmit` / `onError` / `mode`（默认 `onTouched`）/ `resolver`（可挂 zod）；
+- 字段组件用 `name` 注册字段，`rules` 写 rhf 校验规则；
+- `onSubmit` 是普通动作绑定，action 收到表单值对象；
+- `ButtonWidget` 是 `leaf`，文案用 `text` prop（不能 `$content`）。
+
+schema 侧前缀（详见 [bindings.md](bindings.md)）：`@form::xxx`（值/方法，如 `@form::watch` 带 `$args`）、`@fieldArray::append`/`remove`、`@fieldArrayItem::index`/`namePrefix`、`@fieldArrayValues::xxx`。`FormFieldArray` 的 `itemTemplate` 内子字段 `name` 自动按 `namePrefix.index.name` 嵌套。
+
+## i18n
+
+- `Runtime.init` 的 `i18n` 配置初始化 i18next（http-backend `/locales/{lng}/{ns}.json` + 浏览器语言探测），**`ns` 命名空间数组必填**；
+- 声明 `grafton.t` 的组件（内置 `Text` 即此）收到注入的 `t`，文案 props（`text`、`label`、`title` 等）**默认翻译**；
+- 节点级键：`ns`（单节点换命名空间）、`noTranslate: true`（跳过翻译）、`i18nPrefix`（给子树 key 加前缀）、`values`（`Text` 模板插值）；
+- 缺失 key 原样显示（开发期"写原文 + `noTranslate`"与"写 key"可共存）；
+- ⚠️ **来自数据的字符串都应 `noTranslate`**，否则碰巧与 key 同形会被误翻；
+- 语言切换：`Runtime.i18n.changeLanguage(lng)`（配 `detection: {order: ['querystring', ...]}` 时也可 URL `?lng=` 切换）。
+
+```json
+{ "$type": "Text", "variant": "heading", "text": "app.title" }
+{ "$type": "Text", "text": "app.remaining", "values": { "count": "@store::tasks.remaining", "total": "@store::tasks.total" } }
+```