@xgent-ai/skills 0.3.0 → 0.5.0

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

@@ -1,195 +0,0 @@
----
-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

@@ -1,120 +0,0 @@
-# 绑定表达式 / 值级对象 / 双向绑定 / 内置动作
-
-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

@@ -1,168 +0,0 @@
-# 内置组件 / 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" } }
-```