@apigo.cc/state 1.0.16 → 1.0.19

package/README.md

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