From b04be8d4371efbfd9b24aabe2850ef4702a2c566 Mon Sep 17 00:00:00 2001 From: AI Engineer Date: Fri, 5 Jun 2026 19:03:52 +0800 Subject: [PATCH] release: v1.0.13 By: AICoder --- README.md | 212 ++---- dist/state.js | 1370 ++++++++++++++++++----------------- dist/state.min.js | 2 +- dist/state.min.mjs | 1 + dist/state.mjs | 715 ++++++++++++++++++ package.json | 2 +- playwright.config.js | 2 +- src/globals.js | 6 + src/index.js | 17 +- test-results/.last-run.json | 2 +- vite.config.js | 22 +- 11 files changed, 1514 insertions(+), 837 deletions(-) create mode 100644 dist/state.min.mjs create mode 100644 dist/state.mjs diff --git a/README.md b/README.md index f81fb00..96596e6 100644 --- a/README.md +++ b/README.md @@ -1,174 +1,80 @@ -# State.js AI 开发指南 +# @apigo.cc/state - AI 逻辑操作说明书 -> ⚠️ **AI 强制指令 (AI Mandate):** -> 1. **尊重原创逻辑**:本项目(State.js)核心架构极其精炼且经过精雕细琢。**严禁擅自修改原有逻辑**(如 `_returnCode`, `_runCode`, `NewState` 等底层函数),除非你能证明修改后的质量、性能与简洁度均显著优于原版。 -> 2. **禁止过度设计**:不要尝试引入复杂的编译器、多语句解析器或防御性代码。任何试图将“简单问题复杂化”的重构大概率会破坏现有结构。 -> 3. **汇报与许可**:若你认为有必要修改库的核心逻辑,**必须首先向人类开发者汇报修改的必要性与潜在影响**,只有在得到明确允许后方可进行。 -> 4. **回归测试**:任何改动必须通过现有 Playwright 自动化测试,确保 `DataTable` 等复杂组件场景的渲染与合并逻辑完全正常。 +本框架基于原生 `Proxy` 和 `MutationObserver` 实现数据与 DOM 的原子级同步。本手册仅供 AI 构建、维护及驱动基于此引擎的应用。 -State.js 是基于 Vanilla JS 的无编译数据驱动 UI 框架。依赖原生 DOM 与 Proxy,通过解析 HTML `$指令` 属性映射状态。 +--- -> **核心设定:** 你是一个追求极致代码压缩和执行效率的资深极客。 -> **编码原则:** -> 1. **拒绝废话变量:** 除非一个变量会被复用两次以上,否则**绝对禁止**声明临时变量。 -> 2. **极致精简:** 极度偏爱链式调用(Chaining)、短路求值、三元运算符和 One-liner。能一行写完的逻辑,绝不拆成三行。 -> 3. **无解释模式:** 假设你的对话者是顶尖黑客,不需要解释基础 API,不需要防御性废话,直接给出最硬核的最终代码即可。 +## 1. 核心状态逻辑映射 -## 一、 核心语法与指令字典 +### `NewState(defaults, getter, setter)` +* **功能**:创建响应式代理。 +* **内部机制**:拦截所有属性读写。若属性值变更,触发所有引用该属性的 DOM 节点的更新任务(异步微任务)。 +* **扩展逻辑**:通过 `getter/setter` 拦截器可实现数据持久化(如同步至 URL Hash 或 LocalStorage)。 +* **原子操作**: + * `obj.__watch(key, cb)`: 建立 key -> callback 的直接依赖。 + * `obj.__unwatch(key, cb)`: 解除依赖。 -### 1\. 属性与数据绑定矩阵 +--- -| 语法 | 类型 | 解析与执行规则 | +## 2. 指令映射全集 (AI-Ready) + +指令语法:`$attribute="code"`。作用域默认为全局,组件内优先访问 `node.state`。 + +### 结构化映射 +| 指令 | 触发逻辑 | DOM 行为 | | :--- | :--- | :--- | -| `$attr="exp"` | 动态 JS 表达式 | 映射为 HTML 属性。若包含 `\${}`,作为模板字符串计算;若不包含,作为纯 JS 表达式执行并保留返回值类型。 | -| `$$attr="exp"` | 双重计算表达式 | **二次评估机制**:首先评估 `exp` 获取字符串结果,若结果为字符串,则将其作为代码再次执行。适用于动态指令场景(如后端下发指令)。 | -| `.prop="val"` | 静态 DOM 属性 | 将字符串字面量赋值给底层 DOM 节点的 JS 属性。 | -| `$.prop="exp"` | 动态 DOM 属性 | 将 JS 执行结果赋值给底层 DOM 节点的 JS 属性。
**对象自动初始化**:对深层路径(如 `$.state.schema`)赋值时,若路径上的中间节点不存在,框架会自动生成空对象(`{}`)以防止报错。 | -| `$bind="exp"` | 双向数据绑定 | 适用于原生表单元素及遵循 `$bind` 契约的组件(如 `` 的显示状态绑定、`` 的数据绑定)。 | +| **`$if`** | `Boolean(result)` | `true`: 挂载节点; `false`: 移除节点。建议配合 `