state/README.md

@apigo.cc/state - AI 逻辑操作说明书

本框架基于原生 Proxy 和 MutationObserver 实现数据与 DOM 的原子级同步。本手册仅供 AI 构建、维护及驱动基于此引擎的应用。

---

1. 核心状态逻辑映射

NewState(defaults, getter, setter)

• 功能：创建响应式代理。
• 内部机制：拦截所有属性读写。若属性值变更，触发所有引用该属性的 DOM 节点的更新任务（异步微任务）。
• 扩展逻辑：通过 getter/setter 拦截器可实现数据持久化（如同步至 URL Hash 或 LocalStorage）。
• 原子操作：
  • obj.__watch(key, cb): 建立 key -> callback 的直接依赖。
  • obj.__unwatch(key, cb): 解除依赖。

---

2. 指令映射全集 (AI-Ready)

指令语法：$attribute="code"。作用域默认为全局，组件内优先访问 node.state。

结构化映射 (AI 强制规范)

指令	触发逻辑	DOM 行为	运行约束
$if	Boolean(result)	true: 挂载节点; false: 移除节点。	必须 作用于 <template>。
$each	Iterable	基于 key 属性执行节点复用。无 key 时按索引重建。支持 as, index 定义局部变量。	必须 作用于 <template>。

结构化指令铁律：

1. 标签约束：严禁在非 <template> 标签上使用 $if 或 $each。
2. 互斥约束：严禁在同一个 <template> 上同时使用 $if 和 $each。若需组合，必须嵌套（如：$if 模版包裹 $each 模版）。

数据双向绑定 ($bind)

AI 必须根据不同的元素类型执行以下逻辑：

• input[type=text/password], textarea: 监听 input 事件，同步字符串。
• input[type=checkbox]:
  • 绑定值为 Array: 若选中，push(value)（去重）；若取消，splice(index, 1)。
  • 绑定值为非 Array: 同步 checked 为 true/false。
• input[type=radio]: 选中项 value === 绑定值 时设置 checked 为 true。
• select: 同步选中项的 value。
• [contenteditable]: 监听 input，同步 innerHTML。
• input[type=file]: 同步 files 对象。

属性与 Property 绑定

• $text: 映射至 textContent。
• $html: 映射至 innerHTML。
• $class: 严格要求使用模板字符串。范式：class="static-name ${condition ? 'dynamic-name' : ''}"。严禁覆盖原有类名。
• $.path.to.prop: 直接映射至 DOM 对象或组件的 Property。初始化 Property 绑定必须带 . 前缀。
• $src: 增强逻辑。若值以 .svg 结尾，异步 Fetch 并替换为内联 <svg> 节点。
• $$attr: 二级求值。eval(eval(expr)) 逻辑，用于动态生成指令代码。

---

3. 生命周期与事件逻辑

• $on[event]: 映射为 addEventListener。注入 event, thisNode, State, LocalStorage, Hash。
• 生命周期：
  • $onload: 节点进入 DOM 且指令解析完成后触发。
  • $onunload: 节点从 DOM 移除前触发。
  • $onupdate: 绑定的数据变更且渲染任务完成后执行。

---

4. 组件上下文逻辑

• 初始化：Component.register(tagName, setupFn)。
• 作用域隔离：每个组件持有独立 state。
• 穿透访问：通过 this.parent 访问父级作用域链。
• 插槽映射：slot="name" (声明) -> slot-id="name" (宿主)。

---

5. 国际化 (I18n) 逻辑

• 语法结构：{# Key{param} || paramValue #}。
• 处理链路：正则匹配 {# ... #} -> 提取 Key -> 注入 || 后的参数值 -> 调用全局 _translator 函数。

---

6. 运行约束 (Constraints)

1. 禁止滥用同步刷新：严禁 在常规开发中调用 _unsafeRefreshState()。该函数仅为极高性能干预（如万级数据表格）预留。
2. 数据流向：所有状态变更必须通过对 NewState 代理对象的赋值完成。
3. Key 的必要性：在大规模数据（>100条）或复杂交互列表中，必须提供唯一 key 以激活节点复用逻辑。