@apigo.cc/state 1.0.19 → 1.0.21

package/README.md

@@ -1,71 +1,80 @@
 # @apigo.cc/state - AI 逻辑操作说明书
 
-本框架基于原生 `Proxy` 和 `MutationObserver` 实现数据与 DOM 的原子级同步。采用纯原生、零 ESM、全同步加载架构。
+本框架基于原生 `Proxy` 和 `MutationObserver` 实现数据与 DOM 的原子级同步。本手册仅供 AI 构建、维护及驱动基于此引擎的应用。
 
 ---
 
-## 0. 快速开始 (Quick Start)
-直接在 HTML 中引入（无需打包，完全非 ESM 注入）：
-```html
-<script src="https://cdn.jsdelivr.net/npm/@apigo.cc/state@1.0.19/dist/state.min.js"></script>
-```
+## 1. 核心状态逻辑映射
+
+### `NewState(defaults, getter, setter)`
+*   **功能**：创建响应式代理。
+*   **内部机制**：拦截所有属性读写。若属性值变更，触发所有引用该属性的 DOM 节点的更新任务（异步微任务）。
+*   **扩展逻辑**：通过 `getter/setter` 拦截器可实现数据持久化（如同步至 URL Hash 或 LocalStorage）。
+*   **原子操作**：
+    *   `obj.__watch(key, cb)`: 建立 key -> callback 的直接依赖。
+    *   `obj.__unwatch(key, cb)`: 解除依赖。
 
 ---
 
-## 1. 核心全局 API
+## 2. 指令映射全集 (AI-Ready)
 
-引入后，以下接口直接挂载至 `globalThis`：
+指令语法：`$attribute="code"`。作用域默认为全局，组件内优先访问 `node.state`。
 
-| API | 功能说明 |
-| :--- | :--- |
-| **`NewState(defaults, getter, setter)`** | 创建响应式状态代理对象。 |
-| **`Component.register(name, setup, tpl)`** | 注册自定义组件。支持自动模板合并。 |
-| **`RefreshState(node)`** | (别名 `_unsafeRefreshState`) 手动触发特定树的扫描。仅限极致性能调优。 |
-| **`SetTranslator(fn)`** | 设置国际化翻译函数。 |
-| **`$` / `$$`** | 增强型原生选择器（支持限定作用域）。 |
-| **`Util`** | 常用工具集（`clone`, `makeDom`, `getFunctionBody` 等）。 |
-| **`Hash` / `LocalStorage`** | 自动同步至 URL 或本地存储的响应式单例。 |
-| **`State`** | 框架内置的全局持久化状态单例（含 `exitBlocks` 等控制位）。 |
+### 结构化映射
+| 指令 | 触发逻辑 | DOM 行为 |
+| :--- | :--- | :--- |
+| **`$if`** | `Boolean(result)` | `true`: 挂载节点; `false`: 移除节点。建议配合 `<template>`。 |
+| **`$each`** | `Iterable` | 基于 `key` 属性执行节点复用。无 `key` 时按索引重建。支持 `as`, `index` 定义局部变量。 |
 
----
+### 数据双向绑定 (`$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` 对象。
+
+### 属性操作映射
+- **`$text`**: 映射至 `textContent`。
+- **`$html`**: 映射至 `innerHTML`。
+- **`$class`**: **严格要求使用模板字符串**。范式：`class="static-name ${condition ? 'dynamic-name' : ''}"`。严禁覆盖原有类名。
+- **`.path.to.prop`**: 直接映射至 DOM 对象原生属性。例如：`.style.color="'red'"` 映射为 `el.style.color = 'red'`。
+- **`$src`**: 增强逻辑。若值以 `.svg` 结尾，异步 Fetch 并替换为内联 `<svg>` 节点。
+- **`$$attr`**: 二级求值。`eval(eval(expr))` 逻辑，用于动态生成指令代码。
 
-## 2. 指令映射全集 (AI-Ready)
+---
 
-指令语法：`$attribute="code"`。作用域默认为全局，组件内优先访问 `node.state`。
+## 3. 生命周期与事件逻辑
 
-### 结构化映射 (AI 强制规范)
-| 指令 | 触发逻辑 | DOM 行为 | 运行约束 |
-| :--- | :--- | :--- | :--- |
-| **`$if`** | `Boolean(result)` | `true`: 挂载节点; `false`: 移除节点。 | **必须** 作用于 `<template>`。 |
-| **`$each`** | `Iterable` | 基于 `key` 属性执行节点复用。支持 `as`, `index` 定义局部变量。 | **必须** 作用于 `<template>`。 |
+- **`$on[event]`**: 映射为 `addEventListener`。注入 `event`, `thisNode`, `this`。
+- **生命周期**：
+    - **`$onload`**: `DOMNodeInserted` 且指令解析完成后触发。
+    - **`$onunload`**: `DOMNodeRemoved` 前触发，必须用于清理定时器或外部监听。
+    - **`$onupdate`**: 属性 setter 触发且渲染微任务完成后执行。
 
-**结构化指令铁律**：
-1.  **标签约束**：严禁在非 `<template>` 标签上使用 `$if` 或 `$each`。
-2.  **互斥约束**：严禁在同一个 `<template>` 上同时使用 `$if` 和 `$each`。若需组合，必须嵌套。
+---
 
-### 数据双向绑定 (`$bind`)
-- **`input`, `textarea`, `select`**: 自动监听 `input/change` 事件。
-- **`checkbox`**: 支持数组模式（多选）和布尔模式。
-- **`[contenteditable]`**: 支持。
+## 4. 组件上下文逻辑
 
-### 属性与 Property 绑定
-- **`$text`** / **`$html`**: 映射内容。
-- **`$class`**: **严格要求使用模板字符串**。范式：`class="static ${expr}"`。
-- **`$.path.to.prop`**: 映射 DOM 对象或组件的 Property。
-- **`$src`**: 增强 SVG 内联逻辑。
-- **`$$attr`**: 二级求值（Dynamic Directives）。
+- **初始化**：`Component.register(tagName, setupFn)`。
+- **作用域隔离**：每个组件持有独立 `state`。
+- **穿透访问**：通过 `this.parent` 访问父级作用域链。
+- **插槽映射**：`slot="name"` (声明) -> `slot-id="name"` (宿主)。
 
 ---
 
-## 3. 生命周期与事件
+## 5. 国际化 (I18n) 逻辑
 
-- **`$on[event]`**: 注入 `event`, `thisNode`, `State`, `LocalStorage`, `Hash`。
-- **`$onload`** / **`$onunload`** / **`$onupdate`**: 标准生命周期钩子。
+- **语法结构**：`{# Key{param} || paramValue #}`。
+- **处理链路**：正则匹配 `{# ... #}` -> 提取 Key -> 注入 `||` 后的参数值 -> 调用全局 `_translator` 函数。
 
 ---
 
-## 4. 运行约束 (Constraints)
+## 6. 运行约束 (Constraints)
 
-1.  **零 ESM 依赖**：源码与分发包均不依赖 ESM，确保在 `<head>` 中同步加载。
-2.  **数据流驱动**：严禁直接操作指令生成的 DOM，必须通过 `State` 变更驱动。
-3.  **内敛化设计**：所有以下划线 `_` 开头的 API 均为内部逻辑，业务侧严禁直接调用。
+1.  **禁止滥用同步刷新**：**严禁** 在常规开发中调用 `_unsafeRefreshState()`。该函数仅为极高性能干预（如万级数据表格）预留。
+2.  **数据流向**：所有状态变更必须通过对 `NewState` 代理对象的赋值完成。
+3.  **Key 的必要性**：在大规模数据（>100条）或复杂交互列表中，必须提供唯一 `key` 以激活节点复用逻辑。