reatom-jsx

Reatom JSX

在实现或讲解 @reatom/jsx 时使用此技能。将 REFERENCE.md 视为此技能附带的权威参考。

使用方法

1. 阅读 REFERENCE.md 中的相关章节——不要假设其遵循 React/Vue JSX 语义（没有虚拟 DOM、差异比较或组件重新渲染）。
2. 对于 Reatom 核心（atoms、wrap、async、routing），使用 reatom 技能。
3. 对于拉取请求和审慎验证，使用 reatom-review，并结合此技能了解 JSX 专属模式。

章节索引

使用此索引，只打开 REFERENCE.md 中相关的部分：

主题	章节
安装、tsconfig、Vite	Installation、Framework compatibility
应用引导	Example、Hot module replacement
Props、子项、绑定	Reference → Props、Children、Models
行内样式和 css-prop 样式	Reference → style props、style:*、CSS-in-JS
类名	Reference → class 或 className、reatomClassName
条件样式／主题样式	Reference → Conditional Styles with Attributes、cssVar
组件和列表	Reference → Components
批量绑定 prop	Reference → $spread
SVG 和原始标记	Reference → SVG
挂载副作用	Reference → ref props
错误、边界、jsxError	Error handling
实用工具	Utilities → reatomClassName、css、cssVar、<Bind>
TypeScript	TypeScript
SSR 和键控列表	Limitations

实现默认约定

• 组件是普通函数，在挂载时求值一次；更新时使用 atoms 和响应式 props。
• 读取：调用零参数 atom。写入：使用 .set(...)。
• 会操作 Reatom 状态的 on:* 处理器会自动包装；在 JSX 中不要手动包装。
• 不要在多个位置重复使用同一个 JSX 元素实例——每次都调用组件函数或工厂。
• 普通可写 atom：搜索、切换开关和链表行 atom 使用 model:value / model:checked。
• 真正的表单：使用 @reatom/core 中的 reatomForm，配合 <form model={form}> 和 model:field={form.fields.x}——字段 atom 上绝不要使用 model:value（这会绕过 field.change）。
• 表单提交加载指示器：在表单上设置 [data-submitting] 样式（由 model={form} 自动设置）；在 [type='submit']::after 上使用纯 CSS 加载动画。
• SPA 导航使用 reatomRoute：通过 href={route.path(params)} 创建链接，通过 route.go(params) 进行程序化跳转——参见 reatom 技能中的 Routing 部分。
• DOM 属性使用 prop:*；语义有要求时使用 attr:* 设置属性。
• 使用 mount(root, <App />) 挂载；拆卸时调用 unmount()（包括 Vite HMR）。优先使用 @reatom/vite（reatom() 插件），以便自动处理 mount/route HMR dispose。
• 动态列表：将元素存储在 atoms 中，或在响应式子元素中进行映射——不进行 keyed reconciliation。
• 使用 <ErrorBoundary fallback={...}> 和惰性子元素 {() => <Child />} 隔离 UI 故障；使用 jsxError / addCallHook(jsxError, ...) 进行全局跟踪。
• 绝不要在 css prop 中写 [data-x] &（或 :where(...) &）。同一元素上的状态：绑定 data-x={state}，并使用 &[data-x='v'] 进行选择。祖先上的状态：使用 cssVar(...).provide(state) 提供状态，并通过 ${token.container('v')} { … } 查询。值的差异优先使用自定义属性，内容的差异优先使用响应式子元素；选择器和样式查询仅用于结构差异。

如果 REFERENCE.md 与本地示例不一致，以参考文档为准；如果示例有误，请修正示例。