subay 0.0.7 → 0.0.10

package/README.zh.md

@@ -1,377 +1,682 @@
-# 🐣 Subay
-
-一个 <700 LOC 的声明式、响应式 UI 库。
-
-## ✨ 特点
-
-- **轻量小巧**: 不到700行代码，体积小，加载快
-- **声明式渲染**: 使用模板字面量进行声明式UI构建
-- **响应式状态**: 简单而强大的响应式状态管理
-- **高效更新**: 优化的DOM更新，最小化DOM操作
-- **TypeScript支持**: 完整的TypeScript类型定义
-- **零依赖**: 不依赖任何外部库
-
-## 📦 安装
-
-### NPM
-
-```bash
-npm install subay
-```
-
-### Yarn
-
-```bash
-yarn add subay
-```
-
-### 直接引入
-
-```html
-<script type="module">
-    import { html, o, S } from 'https://cdn.jsdelivr.net/npm/subay@latest/lib/index.js';
-    // 使用 Subay
-</script>
-```
-
-## 🔧 基础用法
-
-### 🔄 状态管理
-
-```javascript
-import { o, S } from 'subay';
-
-// 创建可观察值
-const count = o(0);
-
-// 创建计算属性
-const doubled = S(() => count() * 2);
-
-// 读取值
-console.log(count()); // 输出: 0
-console.log(doubled()); // 输出: 0
-
-// 更新值
-count(5);
-console.log(count()); // 输出: 5
-console.log(doubled()); // 输出: 10
-```
-
-### 🎨 渲染
-
-```javascript
-import { html, o } from 'subay';
-
-const name = o('世界');
-const count = o(0);
-
-document.body.append(
-    ...html`
-        <div>
-            <h1>你好，${name}！</h1>
-            <p>计数: ${count}</p>
-            <button onclick="${() => count(count() + 1)}">增加</button>
-            <button onclick="${() => name('Subay')}">更改名称</button>
-        </div>
-    `,
-);
-```
-
-### 📋 列表
-
-```javascript
-import { html, o, map } from 'subay';
-
-const items = o(['苹果', '香蕉', '樱桃']);
-
-document.body.append(
-    ...html`
-        <ul>
-            ${map(
-                () => items(),
-                (item) => html` <li>${item}</li> `,
-            )}
-        </ul>
-        <button onclick="${() => items([...items(), '日期'])}">添加项目</button>
-    `,
-);
-```
-
-## 📚 API
-
-### ⚙️ 状态
-
-#### `o(value)`
-
-创建一个可观察值。
-
-- **参数**: `value` - 初始值
-- **返回值**: 一个函数，调用时返回当前值，传入参数时更新值
-
-```javascript
-const count = o(0);
-count(); // 读取值
-count(5); // 更新值
-```
-
-#### `S(fn, initialValue?)`
-
-创建一个计算属性。
-
-- **参数**:
-    - `fn` - 计算函数，接收前一个值作为参数
-    - `initialValue` - 可选的初始值
-- **返回值**: 一个函数，调用时返回计算结果
-
-```javascript
-const doubled = S(() => count() * 2);
-doubled(); // 读取计算结果
-```
-
-#### `root(fn)`
-
-创建一个根上下文，用于管理计算属性的生命周期。
-
-- **参数**: `fn` - 函数，接收一个销毁函数作为参数
-- **返回值**: 函数执行的结果
-
-```javascript
-root((destroy) => {
-    const count = o(0);
-    const doubled = S(() => count() * 2);
-
-    // 使用 count 和 doubled
-
-    // 可选：在适当的时候调用 destroy() 清理资源
-});
-```
-
-#### `cleanup(fn)`
-
-注册一个清理函数，在计算属性重新计算或销毁时执行。
-
-- **参数**: `fn` - 清理函数
-- **返回值**: 传入的清理函数
-
-```javascript
-S(() => {
-    const timer = setInterval(() => {
-        console.log('tick');
-    }, 1000);
-
-    cleanup(() => clearInterval(timer));
-
-    return count();
-});
-```
-
-#### `transaction(fn)`
-
-批量执行多个更新，减少不必要的计算和渲染。
-
-- **参数**: `fn` - 包含更新操作的函数
-- **返回值**: 函数执行的结果
-
-```javascript
-transaction(() => {
-    count(1);
-    name('Subay');
-    items(['a', 'b', 'c']);
-});
-```
-
-### 🖼️ 渲染
-
-#### `html`
-
-用于创建HTML元素的模板字面量标签。
-
-- **用法**: `html\`...\``
-- **返回值**: 一个DOM节点数组
-
-```javascript
-const element = html`
-    <div class="container">
-        <h1>Hello ${name}!</h1>
-    </div>
-`;
-document.body.append(...element);
-```
-
-#### `svg`
-
-用于创建SVG元素的模板字面量标签。
-
-- **用法**: `svg\`...\``
-- **返回值**: 一个DOM节点数组
-
-```javascript
-const icon = svg /*html*/ `
-  <svg width="24" height="24" viewBox="0 0 24 24">
-    <path d="M12 2L2 7l10 5 10-5-10-5z"/>
-  </svg>
-`;
-document.body.append(...icon);
-```
-
-#### `map(arrayFn, itemFn)`
-
-用于渲染列表的函数。
-
-- **参数**:
-    - `arrayFn` - 返回数组的函数
-    - `itemFn` - 为每个数组项创建DOM节点的函数
-- **返回值**: 一个DOM节点数组
-
-```javascript
-const list = map(
-    () => items(),
-    (item, index) => html` <li key="${index}">${item}</li> `,
-);
-```
-
-### 🛠️ 工具
-
-#### `isObservable(value)`
-
-检查一个值是否是可观察值。
-
-- **参数**: `value` - 要检查的值
-- **返回值**: 布尔值
-
-#### `isComputation(value)`
-
-检查一个值是否是计算属性。
-
-- **参数**: `value` - 要检查的值
-- **返回值**: 布尔值
-
-#### `isReactive(value)`
-
-检查一个值是否是响应式的（可观察值或计算属性）。
-
-- **参数**: `value` - 要检查的值
-- **返回值**: 布尔值
-
-#### `sample(fn)`
-
-运行一个函数，但不追踪其依赖。
-
-- **参数**: `fn` - 要运行的函数
-- **返回值**: 函数执行的结果
-
-```javascript
-const value = sample(() => count()); // 读取count的值但不建立依赖关系
-```
-
-## ⚠️ 注意事项 (Caveats)
-
-### 1. 标签位置的插值
-
-在模板字符串中，如果标签位置使用插值，插值应该是一个字符串或者一个返回字符串的函数，返回的字符串是 HTML/SVG 元素的名字。如果需要使用组件，需要直接调用方法。
-
-**正确用法**:
-
-```javascript
-// 静态标签
-html`<div>Hello</div>`;
-
-// 动态标签（使用字符串）
-const tagName = o('div');
-html`<${tagName}>Hello</${tagName}>`;
-
-// 动态标签（使用返回字符串的函数）
-const getTagName = () => 'div';
-html`<${getTagName}>Hello</${getTagName}>`;
-
-// 使用组件（直接调用方法）
-const MyComponent = () => html`<div>Component</div>`;
-html`<div>${MyComponent()}</div>`;
-```
-
-**错误用法**:
-
-```javascript
-// 错误：组件没有直接调用
-const MyComponent = () => html`<div>Component</div>`;
-html`<${MyComponent}>Hello</${MyComponent}>`; // 这会尝试创建一个名为 "function MyComponent() {...}" 的元素
-```
-
-### 2. 动态属性值
-
-如果需要动态设置 HTML/SVG 元素的属性值，需要传入 `S()` 或 `o()` 的返回值。如果直接传入普通的函数，这个函数将会被当做属性值，而不是函数的返回值。
-
-**正确用法**:
-
-```javascript
-// 使用可观察值
-const disabled = o(false);
-html`<button disabled="${disabled}">Click</button>`;
-
-// 使用计算属性
-const isDisabled = S(() => count() > 5);
-html`<button disabled="${isDisabled}">Click</button>`;
-
-// 事件绑定（直接传入函数）
-html`<button onclick="${() => count(count() + 1)}">Increment</button>`;
-```
-
-**错误用法**:
-
-```javascript
-// 错误：普通函数被当做属性值
-const getDisabled = () => false;
-html`<button disabled="${getDisabled}">Click</button>`; // 这会将 "function getDisabled() {...}" 作为属性值
-```
-
-## 💡 动机
-
-Subay 的创建动机是提供一个轻量级、简单易用的响应式UI库，避免大型框架的复杂性和体积。它的设计理念是：
-
-- **简洁至上**: 保持API简单直观，易于学习和使用
-- **性能优先**: 优化DOM更新，减少不必要的计算
-- **最小化依赖**: 不依赖任何外部库，保持体积小
-- **TypeScript支持**: 提供完整的类型定义，提高开发体验
-
-### 与 Sinuous 的关系
-
-Subay 参考了 [Sinuous](https://github.com/luwes/sinuous) 库的设计思想，`o`、`S` 等API几乎与 Sinuous 保持一致，但在实现细节上有以下不同：
-
-1. **S 的执行时机**: 在 Subay 中，即使某个 S 函数的结果不会被使用，它也会被执行。而在 Sinuous 中，只有当 S 函数的结果被实际使用时，才会执行该函数。
-
-    **示例**:
-
-    ```javascript
-    const userId = o('');
-    const defaultThemeId = o('rainbow');
-
-    const themeId = S(() => {
-        if (!userId()) {
-            return defaultThemeId();
-        }
-        return userTheme();
-    });
-    const userTheme = S(() => {
-        // if !userId(), sinuous 不会执行这里
-        // 但 subay 会执行
-        console.log('side effect on ', userId());
-        return `${userId()}'s theme`;
-    });
-    S(() => {
-        console.log('now the theme is ', themeId());
-    });
-
-    userId('John');
-    userId('');
-    userId('Mary');
-    ```
-
-    在这个例子中，当 `userId()` 为空字符串时，`themeId()` 会返回 `defaultThemeId()`，而不会使用 `userTheme()` 的结果。在 Sinuous 中，`userTheme()` 函数不会被执行；但在 Subay 中，`userTheme()` 函数仍然会被执行，产生副作用。
-
-2. **o 对 S 的引用管理**: 当 S 重新计算时，上次计算时 S 依赖的 o 们不会马上忘记 S，而是等到下次 o 被更新时才过滤掉已经被「忘记」的 S。由于 o 更新的频率通常比 S 重新计算的频率低，这种方式轻微提升了性能。
-
-Subay 适合那些需要轻量级UI解决方案的项目，特别是小型应用、原型开发或对性能有较高要求的场景。
-
-## 📄 License
-
-MIT License - 详见 [LICENSE](LICENSE) 文件。
+# Subay
+
+Subay 是一个轻量级的响应式编程库，提供了状态管理和 DOM 操作的功能。
+
+## API
+
+### root
+
+**简介**
+创建一个根更新上下文，用于管理响应式状态的生命周期。
+
+**语法**
+
+```typescript
+root<T>(fn: (destroy: () => void) => T): T
+```
+
+**参数**
+
+- `fn`: 一个函数，接收一个 `destroy` 函数作为参数，用于手动销毁根上下文。
+
+**返回值**
+
+- `T`: `fn` 函数的返回值。
+
+**例子**
+
+```typescript
+import { root, o, S } from 'subay';
+
+root((destroy) => {
+    const count = o(0);
+    const doubled = S(() => count() * 2);
+
+    console.log(doubled()); // 0
+    count(1);
+    console.log(doubled()); // 2
+
+    // 手动销毁
+    destroy();
+});
+```
+
+**注意**
+
+销毁使用 `root` 创建的上下文的唯一方式就是调用 `destroy` 回调。
+
+### S
+
+**简介**
+创建一个计算值，当依赖的可观察值变化时自动重新计算。
+
+**语法**
+
+```typescript
+S<T>(fn: (pv: T | undefined) => T, value?: T): IS<T>
+```
+
+**参数**
+
+- `fn`: 计算函数，接收上一次的计算值作为参数。
+- `value`: 可选的初始值。
+
+**返回值**
+
+- `IS<T>`: 一个函数，调用时返回计算值。
+
+**例子**
+
+```typescript
+import { S, o } from 'subay';
+
+const count = o(0);
+const doubled = S(() => count() * 2);
+
+console.log(doubled()); // 0
+count(1);
+console.log(doubled()); // 2
+```
+
+### o / observable
+
+**简介**
+创建一个可观察值，用于存储和更新状态。
+
+**语法**
+
+```typescript
+o<T>(value: T): IO<T>
+```
+
+**参数**
+
+- `value`: 初始值。
+
+**返回值**
+
+- `IO<T>`: 一个函数，无参数调用时返回当前值，带参数调用时更新值并返回新值。
+
+**例子**
+
+```typescript
+import { o } from 'subay';
+
+const count = o(0);
+console.log(count()); // 0
+count(1);
+console.log(count()); // 1
+```
+
+### cleanup
+
+**简介**
+注册一个清理函数，当当前更新上下文被销毁时执行。
+
+**语法**
+
+```typescript
+cleanup<T extends () => void>(f: T): T
+```
+
+**参数**
+
+- `f`: 清理函数。
+
+**返回值**
+
+- `T`: 传入的清理函数。
+
+**例子**
+
+```typescript
+import { root, S, o, cleanup } from 'subay';
+
+root(() => {
+    const count = o(0);
+
+    S(() => {
+        console.log(count());
+        cleanup(() => {
+            console.log('Cleanup called');
+        });
+    });
+
+    count(1);
+});
+// 输出: 0, 1, Cleanup called
+```
+
+### transaction
+
+**简介**
+创建一个事务，批量更新可观察值，避免中间状态的计算。
+
+**语法**
+
+```typescript
+transaction<T>(f: () => T): T
+```
+
+**参数**
+
+- `f`: 事务函数，在其中可以更新多个可观察值。
+
+**返回值**
+
+- `T`: `f` 函数的返回值。
+
+**例子**
+
+```typescript
+import { transaction, o, S } from 'subay';
+
+const a = o(1);
+const b = o(2);
+const sum = S(() => a() + b());
+
+S(() => console.log(sum())); // 3
+
+transaction(() => {
+    a(2);
+    b(3);
+});
+// 输出: 5 (只计算一次)
+```
+
+### sample
+
+**简介**
+在不建立依赖关系的情况下获取可观察值的值。
+
+**语法**
+
+```typescript
+sample<T>(f: () => T): T
+```
+
+**参数**
+
+- `f`: 函数，在其中可以访问可观察值但不会建立依赖关系。
+
+**返回值**
+
+- `T`: `f` 函数的返回值。
+
+**例子**
+
+```typescript
+import { sample, o, S } from 'subay';
+
+const count = o(0);
+let cachedValue;
+
+S(() => {
+    // 不建立依赖关系
+    cachedValue = sample(() => count());
+    console.log(cachedValue);
+});
+
+count(1); // 不会触发重新计算
+console.log(cachedValue); // 0
+```
+
+### isListening
+
+**简介**
+检查当前是否处于响应式监听状态。
+
+**语法**
+
+```typescript
+isListening(): boolean
+```
+
+**参数**
+
+- 无
+
+**返回值**
+
+- `boolean`: 当前是否处于响应式监听状态。
+
+**例子**
+
+```typescript
+import { isListening, S } from 'subay';
+
+console.log(isListening()); // false
+
+S(() => {
+    console.log(isListening()); // true
+});
+```
+
+### subscribe
+
+**简介**
+订阅一个函数，当依赖的可观察值变化时自动执行。
+
+**语法**
+
+```typescript
+subscribe(f: () => void): () => void
+```
+
+**参数**
+
+- `f`: 订阅函数。
+
+**返回值**
+
+- `() => void`: 取消订阅的函数。
+
+**例子**
+
+```typescript
+import { subscribe, o } from 'subay';
+
+const count = o(0);
+const unsubscribe = subscribe(() => {
+    console.log(count());
+});
+
+count(1); // 输出: 1
+count(2); // 输出: 2
+
+unsubscribe();
+count(3); // 无输出
+```
+
+### unsubscribe
+
+**简介**
+取消订阅一个函数。
+
+**语法**
+
+```typescript
+unsubscribe(f: () => void): void
+```
+
+**参数**
+
+- `f`: 要取消订阅的函数。
+
+**返回值**
+
+- 无
+
+**例子**
+
+```typescript
+import { subscribe, unsubscribe, o } from 'subay';
+
+const count = o(0);
+const fn = () => console.log(count());
+
+subscribe(fn);
+count(1); // 输出: 1
+
+unsubscribe(fn);
+count(2); // 无输出
+```
+
+### isObservable
+
+**简介**
+检查一个值是否是可观察值。
+
+**语法**
+
+```typescript
+isObservable(o: any): o is IO<any>
+```
+
+**参数**
+
+- `o`: 要检查的值。
+
+**返回值**
+
+- `boolean`: 是否是可观察值。
+
+**例子**
+
+```typescript
+import { isObservable, o, S } from 'subay';
+
+const count = o(0);
+const doubled = S(() => count() * 2);
+
+console.log(isObservable(count)); // true
+console.log(isObservable(doubled)); // false
+```
+
+### isComputed
+
+**简介**
+检查一个值是否是计算值。
+
+**语法**
+
+```typescript
+isComputed(o: any): o is IS<any>
+```
+
+**参数**
+
+- `o`: 要检查的值。
+
+**返回值**
+
+- `boolean`: 是否是计算值。
+
+**例子**
+
+```typescript
+import { isComputed, o, S } from 'subay';
+
+const count = o(0);
+const doubled = S(() => count() * 2);
+
+console.log(isComputed(count)); // false
+console.log(isComputed(doubled)); // true
+```
+
+### isReactive
+
+**简介**
+检查一个值是否是响应式值（可观察值或计算值）。
+
+**语法**
+
+```typescript
+isReactive(o: any): o is IO<any> | IS<any>
+```
+
+**参数**
+
+- `o`: 要检查的值。
+
+**返回值**
+
+- `boolean`: 是否是响应式值。
+
+**例子**
+
+```typescript
+import { isReactive, o, S } from 'subay';
+
+const count = o(0);
+const doubled = S(() => count() * 2);
+
+console.log(isReactive(count)); // true
+console.log(isReactive(doubled)); // true
+console.log(isReactive(42)); // false
+```
+
+### map
+
+**简介**
+将一个数组映射为 DOM 节点数组，当数组变化时自动更新。
+
+**语法**
+
+```typescript
+map<T>(array: () => T[], f: (item: T) => Node[]): Node[]
+```
+
+**参数**
+
+- `array`: 一个返回数组的函数。
+- `f`: 映射函数，将数组项转换为 DOM 节点数组。
+
+**返回值**
+
+- `Node[]`: DOM 节点数组。
+
+**例子**
+
+```typescript
+import { map, o, html } from 'subay';
+
+const items = o(['a', 'b', 'c']);
+const list = map(
+    () => items(),
+    (item) => html`<li>${item}</li>`,
+);
+
+document.body.append(...list);
+// 渲染: <li>a</li><li>b</li><li>c</li>
+
+items(['a', 'b', 'c', 'd']);
+// 自动更新: <li>a</li><li>b</li><li>c</li><li>d</li>
+```
+
+### svg
+
+**简介**
+创建 SVG 元素的模板标签函数。
+
+**语法**
+
+```typescript
+svg(segments: TemplateStringsArray, ...values: any[]): Node[]
+```
+
+**参数**
+
+- `segments`: 模板字符串的静态部分。
+- `values`: 模板字符串的动态部分。
+
+**返回值**
+
+- `Node[]`: SVG 元素节点数组。
+
+**例子**
+
+```typescript
+import { svg, o } from 'subay';
+
+const radius = o(50);
+const circle = svg`<circle cx="100" cy="100" r="${radius}" fill="red"/>`;
+
+document.getElementById('svg').append(...circle);
+```
+
+### html
+
+**简介**
+创建 HTML 元素的模板标签函数。
+
+**语法**
+
+```typescript
+html(segments: TemplateStringsArray, ...values: any[]): Node[]
+```
+
+**参数**
+
+- `segments`: 模板字符串的静态部分。
+- `values`: 模板字符串的动态部分。
+
+**返回值**
+
+- `Node[]`: HTML 元素节点数组。
+
+**例子**
+
+```typescript
+import { html, o } from 'subay';
+
+const count = o(0);
+const counter = html`
+    <div>
+        <p>Count: ${count}</p>
+        <button onclick=${() => count(count() + 1)}>Increment</button>
+    </div>
+`;
+
+document.body.append(...counter);
+// 点击按钮会自动更新 count 的值
+```
+
+**使用 HTML**
+
+Subay 使用 `DOMParser` 解析 HTML 模板， `html` 的参数必须是合法的 HTML 字符串，（同理， `svg` 的参数必须是合法的 SVG 字符串）, 这是有别于 JSX 的地方。
+
+**例子**
+
+```typescript
+import { html } from 'subay';
+
+// 合法的 HTML 字符串
+const validHtml = html`<div><p>Hello</p></div>`;
+
+document.body.append(...validHtml);
+```
+
+**错误示例**
+
+```typescript
+import { html } from 'subay';
+
+// 自闭合标签
+const invalidHtml = html`<div>
+    <span />
+    <span />
+</div>`; // 会导致解析成 <div><span><span></span></span></div>
+```
+
+**传入对象作为元素属性**
+
+如果需要传入一个对象作为元素属性，可以使用 `...` 语法。
+
+**语法**
+
+```typescript
+html`<tag ...${props}></tag>`;
+```
+
+**例子**
+
+```typescript
+import { html, o } from 'subay';
+
+const props = o({
+    className: 'container',
+    style: 'color: red;',
+});
+
+const element = html`<div ...${props}></div>`;
+
+document.body.append(...element);
+```
+
+**组件的声明**
+
+组件是一个返回 Node\[] 的函数，可以接收参数。和 React、Vue 等不同，组件的参数是一个列表。
+
+**语法**
+
+```typescript
+const Component = (text, children: () => Node[]) => {
+    return html`<div>${text}</div>`;
+};
+```
+
+**例子**
+
+```typescript
+import { html } from 'subay';
+
+const Greeting = (name: string, children: () => Node[]) => {
+    return html`
+        <div>
+            <h1>Hello, ${name}!</h1>
+            ${children()}
+        </div>
+    `;
+};
+```
+
+**组件的使用**
+
+在模板中使用组件时，在标签处引用组件。
+因为模板是 HTML 字符串，引用的时候不支持自闭合标签。
+传给组件的参数必须和组件声明的参数顺序一致。
+组件获得的参数总是和传入的保持一致。
+
+**例子**
+
+```typescript
+import { html, o } from 'subay';
+
+const Greeting = (greet: string, name: () => string) => {
+    return html`<h1>${greet}, ${name}!</h1>`;
+};
+
+const name = o('World');
+const app = html` <div><${Greeting} greet=${'Hello'} name=${name}></${Greeting}></div> `;
+
+document.body.append(...app);
+```
+
+**错误示例**
+
+```typescript
+import { html, o } from 'subay';
+
+const Greeting = (greet: string, name: () => string) => {
+    return html`<h1>${greet}, ${name}!</h1>`;
+};
+
+const name = o('World');
+// 错误, 后面的 span 会被当做 Greeting 的子节点。
+const app = html`
+    <div>
+        <${Greeting}
+            greet=${'Hello'}
+            name=${name}
+        />
+        <span></span>
+    </div>
+`;
+// 错误, 参数顺序和 Greeting 的参数不一致
+const app = html` <div><${Greeting} name=${name} greet=${'Hi'} ></${Greeting}></div> `;
+
+document.body.append(...app);
+```
+
+**动态的组件**
+
+标签位置的插值可以是 `S` 或 `o` 的返回值，可以根据条件动态选择要渲染的组件。
+
+**例子**
+
+```typescript
+import { html, o, S } from 'subay';
+
+const Greeting = (name: () => string) => {
+    return html`<h1>Hello, ${name}!</h1>`;
+};
+
+const Farewell = (name: () => string) => {
+    return html`<h1>Goodbye, ${name}!</h1>`;
+};
+
+const showGreeting = o(true);
+const name = o('World');
+const Component = S(() => (showGreeting() ? Greeting : Farewell));
+
+const app = html`
+    <div>
+        <${Component} name=${name} ></${Component}>
+        <button onclick=${() => showGreeting(!showGreeting())}>Toggle</button>
+    </div>
+`;
+
+document.body.append(...app);
+```
+