subay 0.0.13 → 0.1.1

package/skills/subay-application/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: subay-application
+description: 介绍使用 Subay 的基本代码范式。如果需要创建 Subay 应用，参考此文档。
+license: MIT
+metadata:
+    author: j-sen
+    version: '1.0'
+---
+
+# Subay Application
+
+## 最简单的形式
+
+Subay 不要求所有代码都以组件形式组织，可以直接调用 `html` 生成 DOM 节点并插入文档中。
+
+```typescript
+import { o, html } from 'subay';
+const count = o(0);
+const increase = () => {
+    count(count() + 1);
+};
+const decrease = () => {
+    count(count() - 1);
+};
+document.body.append(
+    ...html`
+        <button
+            type="button"
+            onclick="${decrease}"
+        >
+            -
+        </button>
+        ${count}
+        <button
+            type="button"
+            onclick="${increase}"
+        >
+            +
+        </button>
+    `,
+);
+```
+
+## 组件
+
+如果需要复用功能，将数据和模板组织到组件中是更合理的做法。Subay 的组件是普通函数。
+
+```typescript
+import { o, html } from 'subay';
+
+const Counter = () => {
+    const count = o(0);
+    const increase = () => {
+        count(count() + 1);
+    };
+    const decrease = () => {
+        count(count() - 1);
+    };
+    return html`
+        <button
+            type="button"
+            onclick="${decrease}"
+        >
+            -
+        </button>
+        ${count}
+        <button
+            type="button"
+            onclick="${increase}"
+        >
+            +
+        </button>
+    `;
+};
+
+document.body.append(...Counter());
+```
+
+## 在模板中使用组件
+
+在模板中使用组件时，直接调用即可。如果参数中包含可变状态，将其放入一个函数中。更多组件信息参考 [组件](../subay-component/SKILL.md)
+
+```typescript
+import { o, S, html } from 'subay';
+import type { IS } from 'subay';
+
+const Action = (disabled: IS<boolean>, onClick: () => void, children: () => Node[]) => {
+    return html`<button
+        disabled="${disabled}"
+        type="button"
+        onclick="${onClick}"
+    >
+        ${children}
+    </button>`;
+};
+
+const Counter = () => {
+    const count = o(0);
+    const increase = () => {
+        count(count() + 1);
+    };
+    const decrease = () => {
+        count(count() - 1);
+    };
+    return html`
+        ${Action(
+            S(() => count() <= 0),
+            decrease,
+            () => html`-`,
+        )}
+        ${count}
+        ${() =>
+            Action(
+                S(() => count() >= 10),
+                increase,
+                () => html`+`,
+            )}
+    `;
+};
+
+document.body.append(...Counter());
+```

package/skills/subay-component/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: subay-component
+description: 介绍 Subay 组件的声明和使用方式。
+license: MIT
+metadata:
+    author: j-sen
+    version: '1.0'
+---
+
+# Subay Component
+
+Subay 的组件是普通函数，可以接受任意形式的参数。
+
+## 组件引用方式
+
+Subay 的组件不支持在模板的标签位置进行插值，而是通过直接调用或延迟调用的方式使用。
+延迟调用指的是创建一个函数，该函数返回组件调用的结果。
+
+```typescript
+import { html } from 'subay';
+const MyComponent = (type, onClick, children) =>
+    html`<button
+        type="${type}"
+        onclick="${onClick}"
+    >
+        ${children}
+    </button>`;
+
+// ❌ 错误 - 在标签位置插值
+const Appp = () => html`
+  <${MyComponent} type="button" onClick="${() => {}}">My Button</${MyComponent}>
+`;
+// ✅ 正确 - 直接调用
+const App = () => html`
+    ${MyComponent(
+        'button',
+        () => {},
+        () => 'MyButton',
+    )}
+`;
+
+// ✅ 正确 - 延迟调用
+const App = () => html`
+    ${() =>
+        MyComponent(
+            'button',
+            () => {},
+            () => 'MyButton',
+        )}
+`;
+```
+
+具体采用直接调用还是延迟调用，取决于参数何时需要变化。

package/skills/subay-expert/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: subay-expert
+description: 介绍使用 Subay 过程中容易犯错的地方。
+license: MIT
+metadata:
+    author: j-sen
+    version: '1.0'
+---
+
+# Subay Expert
+
+## 避免对 `S` 或 `o` 返回的值过早解引用
+
+对于 `S` 或 `o` 返回的值，应尽量推迟解引用的时机。如果在组件顶层解引用，会导致其失去响应式效果。
+
+```typescript
+import { o, S, html } from 'subay';
+
+const BadComponent = () => {
+    const value = o(1);
+    // ❌ 错误 - 在组件顶层解引用，修改 value 后整个组件会重新执行，value 会以初始值重新创建
+    return html`<input value="${value()}"></input>`;
+};
+
+const GoodComponent = () => {
+    const value = o(1);
+    // ✅ 正确 - 不直接解引用
+    return html`<input value="${value}"></input>`;
+};
+
+const AnotherGoodComponent = () => {
+    const value = o(1);
+    // ✅ 正确 - 不直接解引用，如需基于其值推导新状态，使用 S
+    const doubleValue = S(() => value());
+    return html`<input value="${doubleValue}"></input>`;
+};
+```

package/skills/subay-state/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: subay-state
+description: 介绍在 Subay 应用中创建和使用状态的方式。
+license: MIT
+metadata:
+    author: j-sen
+    version: '1.0'
+---
+
+# Subay State
+
+## 创建可修改的状态
+
+如果应用中需要创建一个状态并在后续修改它，使用 `o`。`o` 接受一个参数作为初始值，返回一个函数。无参数调用此函数可获取值，传参调用则修改值。
+
+```typescript
+import { o } from 'subay';
+// 创建一个初始值为 0 的状态
+const myState = o(0);
+// 获取值
+const myStateValue = myState();
+// 修改值为 1
+myState(1);
+```
+
+## 基于现有状态推导新状态
+
+如果一个状态的值由其他一个或多个状态的值决定，并且应随依赖状态的变化而自动更新，使用 `S` 创建它。
+
+```typescript
+import { o, S } from 'subay';
+// 创建原始状态
+const red = o(0);
+const green = o(0);
+const blue = o(0);
+// 创建推导状态
+const rgb = S(() => {
+    return '#' + [red(), green(), blue()].map((it) => it.toString(16).padStart(2, '0')).join('');
+});
+// 获取推导状态的值，rgbValue1 的值是 #000000
+const rgbValue1 = rgb();
+
+// 更新 red 的值
+red(21);
+
+// rgb() 的值也会自动更新，rgbValue2 的值是 #150000
+const rgbValue2 = rgb();
+```
+
+## 基于状态产生副作用
+
+如果需要一个过程使用某些状态，并在状态变化时自动重新执行，使用 `S`。
+
+```typescript
+import { o, S } from 'subay';
+const docTitle = o('foo');
+S(() => {
+    document.title = docTitle();
+});
+console.assert(document.title === docTitle());
+docTitle('bar');
+console.assert(document.title === docTitle());
+```
+
+## 副作用的清理
+
+如果副作用在重新执行前需要执行特定的清理操作，使用 `cleanup`。
+
+```typescript
+import { o, S, cleanup } from 'subay';
+const className = o('foo');
+S(() => {
+    const cls = className();
+    document.body.classList.add(cls);
+    cleanup(() => document.body.classList.remove(cls));
+});
+console.assert(document.body.className === className());
+className('bar');
+console.assert(document.body.className === className());
+```
+
+## 嵌套的副作用
+
+副作用可以嵌套，当外层副作用重新执行时，内层副作用也会重新执行。
+
+## 创建独立的副作用
+
+在副作用中创建的副作用默认会形成父子关系。若要切断这种关系，使用 `root`。`root` 接受一个函数作为参数，在该函数中创建的副作用的父节点不是外层副作用，而是一个匿名的空副作用，并且不会随外层副作用的重新执行或清理而受到影响。清理它的唯一方式是调用 `root` 提供的清理函数。
+
+```typescript
+import { o, S, root, cleanup } from 'subay';
+const className = o('foo');
+root((cancelSyncClassName) => {
+    S(() => {
+        const cls = className();
+        if ('stop' === cls) {
+            cancelSyncClassName();
+            return;
+        }
+        document.body.classList.add(cls);
+        cleanup(() => document.body.classList.remove(cls));
+    });
+});
+console.assert(document.body.className === className());
+className('bar');
+console.assert(document.body.className === className());
+className('stop');
+console.assert(document.body.className === '');
+className('bar');
+console.assert(document.body.className === '');
+```
+
+## 可在外部主动清理的副作用
+
+如果需要创建一个可在外部手动清理的副作用，使用 `subscribe/unsubscribe`。
+
+```typescript
+import { o, subscribe, unsubscribe } from 'subay';
+const docTitle = o('foo');
+const syncTitle = () => {
+    document.title = docTitle();
+};
+const cancel = subscribe(syncTitle);
+
+console.assert(document.title === docTitle());
+docTitle('bar');
+console.assert(document.title === docTitle());
+cancel(); // 或者调用 unsubscribe(syncTitle)
+docTitle('baz');
+console.assert(document.title === 'bar');
+```
+
+## 避免特定状态参与副作用
+
+副作用会记录所有参与其运算的状态，并在这些状态变化后重新执行。但对于在 `sample` 回调中引用的状态，当前副作用会忽略它们。
+
+```typescript
+import { o, S, sample } from 'subay';
+const docTitle = o('foo');
+document.title = docTitle();
+console.assert(document.title === docTitle());
+S(() => {
+    document.title = sample(() => docTitle());
+});
+docTitle('bar');
+console.assert(document.title === 'foo');
+```
+
+## 批量修改状态
+
+每次修改状态后，所有依赖它的副作用都会重新计算。同时修改多个状态时，可能会触发很多副作用不必要地重新计算。为避免这种情况，使用 `transaction`。
+
+```typescript
+import { o, S, transaction } from 'subay';
+const left = o(0);
+const right = o(1);
+const sum = S(() => left() + right());
+transaction(() => {
+    left(1);
+    right(2);
+});
+```

package/skills/subay-template/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: subay-template
+description: 介绍 Subay 中模板字符串的使用要求。
+license: MIT
+metadata:
+    author: j-sen
+    version: '1.0'
+---
+
+# Subay Template
+
+`html` 后面必须是合法的 HTML 字符串，同理 `svg` 后面必须是合法的 SVG 字符串。
+
+## 与 JSX 的区别
+
+Subay 使用的模板与 JSX 有显著区别：
+
+- JSX 是 XML，而 Subay 模板是 HTML 或 XML
+- JSX 要求所有标签都必须闭合，而 Subay 模板在这方面的要求与 HTML/XML 一致
+- JSX 允许自闭合标签，而 Subay 模板中自闭合标签的处理方式与 HTML/XML 一致
+
+## 允许插值的位置
+
+Subay 的模板允许在以下特定位置使用插值：
+
+- 标签：包含插值的标签必须有对应的闭合标签，例如 `html`<${Com}>Text</${Com}>`
+- 部分标签：例如 `html`<h${Level}>Heading</h${Level}>`
+- 属性名称和值：例如 `html`<input ${eventName}=${eventHandler}></input>`
+- 部分属性名称和值：例如 `html`<input on${eventName}=${eventHandler} value="prefix-${value}"></input>`
+- 带 `...` 的属性：例如 `html`<input ...${attrs}></input>`，表示批量传入属性
+- 标签外的任意位置：例如 `html`<p>${content}</p>`
+
+## 插值的值类型
+
+Subay 模板中的插值值分为三种类型：
+
+- **非函数类型**：值会原样插入
+- **作为属性值的函数类型**：如果值是 [`S`](../subay-state/SKILL.md#基于现有状态推导新状态) 或 [`o`](../subay-state/SKILL.md#创建可修改的状态) 返回的值，Subay 会调用该函数并插入结果，且在值变化时自动更新属性；如果是普通函数，则直接插入函数本身
+- **其他位置的函数类型**：Subay 会使用 [`S`](../subay-state/SKILL.md#基于现有状态推导新状态) 修饰它，插入其返回值，并在值变化时自动更新插值位置