subay 0.0.7 → 0.0.8

package/README.md

@@ -1,377 +1,681 @@
-# 🐣 Subay
+# Subay
 
-A < 700 LOC declarative, reactive UI library.
+Subay is a lightweight reactive programming library that provides state management and DOM manipulation capabilities.
 
-## ✨ Features
+## API
 
-- **Lightweight**: Less than 700 lines of code, small size, fast loading
-- **Declarative Rendering**: Use template literals for declarative UI construction
-- **Reactive State**: Simple yet powerful reactive state management
-- **Efficient Updates**: Optimized DOM updates with minimal DOM operations
-- **TypeScript Support**: Complete TypeScript type definitions
-- **Zero Dependencies**: No external library dependencies
+### root
 
-## 📦 Installation
+**Introduction**
+Creates a root update context for managing the lifecycle of reactive states.
 
-### NPM
+**Syntax**
 
-```bash
-npm install subay
+```typescript
+root<T>(fn: (destroy: () => void) => T): T
 ```
 
-### Yarn
+**Parameters**
 
-```bash
-yarn add subay
-```
+- `fn`: A function that receives a `destroy` function as a parameter, used to manually destroy the root context.
 
-### Direct Import
+**Return Value**
 
-```html
-<script type="module">
-    import { html, o, S } from 'https://cdn.jsdelivr.net/npm/subay@latest/lib/index.js';
-    // Use Subay
-</script>
-```
+- `T`: The return value of the `fn` function.
 
-## 🔧 Basic Usage
+**Example**
 
-### 🔄 State Management
+```typescript
+import { root, o, S } from 'subay';
 
-```javascript
-import { o, S } from 'subay';
+root((destroy) => {
+    const count = o(0);
+    const doubled = S(() => count() * 2);
 
-// Create an observable value
-const count = o(0);
+    console.log(doubled()); // 0
+    count(1);
+    console.log(doubled()); // 2
 
-// Create a computed property
-const doubled = S(() => count() * 2);
+    // Manual destruction
+    destroy();
+});
+```
+
+**Note**
+
+The only way to destroy a context created with `root` is to call the `destroy` callback.
+
+### S
+
+**Introduction**
+Creates a computed value that automatically recalculates when its dependent observables change.
 
-// Read value
-console.log(count()); // Output: 0
-console.log(doubled()); // Output: 0
+**Syntax**
 
-// Update value
-count(5);
-console.log(count()); // Output: 5
-console.log(doubled()); // Output: 10
+```typescript
+S<T>(fn: (pv: T | undefined) => T, value?: T): IS<T>
 ```
 
-### 🎨 Rendering
+**Parameters**
 
-```javascript
-import { html, o } from 'subay';
+- `fn`: A computation function that receives the previous computed value as a parameter.
+- `value`: Optional initial value.
+
+**Return Value**
+
+- `IS<T>`: A function that returns the computed value when called.
+
+**Example**
+
+```typescript
+import { S, o } from 'subay';
 
-const name = o('World');
 const count = o(0);
+const doubled = S(() => count() * 2);
 
-document.body.append(
-    ...html`
-        <div>
-            <h1>Hello, ${name}!</h1>
-            <p>Count: ${count}</p>
-            <button onclick="${() => count(count() + 1)}">Increment</button>
-            <button onclick="${() => name('Subay')}">Change Name</button>
-        </div>
-    `,
-);
+console.log(doubled()); // 0
+count(1);
+console.log(doubled()); // 2
 ```
 
-### 📋 List
+### o / observable
 
-```javascript
-import { html, o, map } from 'subay';
+**Introduction**
+Creates an observable value for storing and updating state.
 
-const items = o(['Apple', 'Banana', 'Cherry']);
+**Syntax**
 
-document.body.append(
-    ...html`
-        <ul>
-            ${map(
-                () => items(),
-                (item) => html` <li>${item}</li> `,
-            )}
-        </ul>
-        <button onclick="${() => items([...items(), 'Date'])}">Add Item</button>
-    `,
-);
+```typescript
+o<T>(value: T): IO<T>
 ```
 
-## 📚 API
+**Parameters**
+
+- `value`: Initial value.
 
-### ⚙️ State
+**Return Value**
 
-#### `o(value)`
+- `IO<T>`: A function that returns the current value when called without arguments, and updates the value and returns the new value when called with arguments.
 
-Create an observable value.
+**Example**
 
-- **Parameters**: `value` - Initial value
-- **Return**: A function that returns the current value when called, and updates the value when passed a parameter
+```typescript
+import { o } from 'subay';
 
-```javascript
 const count = o(0);
-count(); // Read value
-count(5); // Update value
+console.log(count()); // 0
+count(1);
+console.log(count()); // 1
 ```
 
-#### `S(fn, initialValue?)`
+### cleanup
 
-Create a computed property.
+**Introduction**
+Registers a cleanup function that executes when the current update context is destroyed.
 
-- **Parameters**:
-    - `fn` - Computation function, receives the previous value as a parameter
-    - `initialValue` - Optional initial value
-- **Return**: A function that returns the computation result when called
+**Syntax**
 
-```javascript
-const doubled = S(() => count() * 2);
-doubled(); // Read computation result
+```typescript
+cleanup<T extends () => void>(f: T): T
 ```
 
-#### `root(fn)`
+**Parameters**
 
-Create a root context for managing the lifecycle of computed properties.
+- `f`: Cleanup function.
 
-- **Parameters**: `fn` - Function that receives a destroy function as a parameter
-- **Return**: The result of the function execution
+**Return Value**
 
-```javascript
-root((destroy) => {
+- `T`: The passed cleanup function.
+
+**Example**
+
+```typescript
+import { root, S, o, cleanup } from 'subay';
+
+root(() => {
     const count = o(0);
-    const doubled = S(() => count() * 2);
 
-    // Use count and doubled
+    S(() => {
+        console.log(count());
+        cleanup(() => {
+            console.log('Cleanup called');
+        });
+    });
+
+    count(1);
+});
+// Output: 0, 1, Cleanup called
+```
+
+### transaction
 
-    // Optional: Call destroy() to clean up resources when appropriate
+**Introduction**
+Creates a transaction for batch updating observables, avoiding intermediate state calculations.
+
+**Syntax**
+
+```typescript
+transaction<T>(f: () => T): T
+```
+
+**Parameters**
+
+- `f`: Transaction function where multiple observables can be updated.
+
+**Return Value**
+
+- `T`: The return value of the `f` function.
+
+**Example**
+
+```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);
 });
+// Output: 5 (calculated only once)
 ```
 
-#### `cleanup(fn)`
+### sample
 
-Register a cleanup function that executes when the computed property is recomputed or destroyed.
+**Introduction**
+Gets the value of an observable without establishing a dependency relationship.
 
-- **Parameters**: `fn` - Cleanup function
-- **Return**: The passed cleanup function
+**Syntax**
+
+```typescript
+sample<T>(f: () => T): T
+```
+
+**Parameters**
+
+- `f`: A function where observables can be accessed without establishing dependency relationships.
+
+**Return Value**
+
+- `T`: The return value of the `f` function.
+
+**Example**
+
+```typescript
+import { sample, o, S } from 'subay';
+
+const count = o(0);
+let cachedValue;
 
-```javascript
 S(() => {
-    const timer = setInterval(() => {
-        console.log('tick');
-    }, 1000);
+    // No dependency relationship established
+    cachedValue = sample(() => count());
+    console.log(cachedValue);
+});
+
+count(1); // Will not trigger recalculation
+console.log(cachedValue); // 0
+```
+
+### isListening
 
-    cleanup(() => clearInterval(timer));
+**Introduction**
+Checks if the current state is in reactive listening mode.
 
-    return count();
+**Syntax**
+
+```typescript
+isListening(): boolean
+```
+
+**Parameters**
+
+- None
+
+**Return Value**
+
+- `boolean`: Whether the current state is in reactive listening mode.
+
+**Example**
+
+```typescript
+import { isListening, S } from 'subay';
+
+console.log(isListening()); // false
+
+S(() => {
+    console.log(isListening()); // true
 });
 ```
 
-#### `transaction(fn)`
+### subscribe
 
-Batch execute multiple updates to reduce unnecessary computations and rendering.
+**Introduction**
+Subscribes to a function that automatically executes when dependent observables change.
 
-- **Parameters**: `fn` - Function containing update operations
-- **Return**: The result of the function execution
+**Syntax**
 
-```javascript
-transaction(() => {
-    count(1);
-    name('Subay');
-    items(['a', 'b', 'c']);
+```typescript
+subscribe(f: () => void): () => void
+```
+
+**Parameters**
+
+- `f`: Subscription function.
+
+**Return Value**
+
+- `() => void`: A function to unsubscribe.
+
+**Example**
+
+```typescript
+import { subscribe, o } from 'subay';
+
+const count = o(0);
+const unsubscribe = subscribe(() => {
+    console.log(count());
 });
+
+count(1); // Output: 1
+count(2); // Output: 2
+
+unsubscribe();
+count(3); // No output
 ```
 
-### 🖼️ Rendering
+### unsubscribe
 
-#### `html`
+**Introduction**
+Unsubscribes a function.
 
-Template literal tag for creating HTML elements.
+**Syntax**
 
-- **Usage**: `html\`...\``
-- **Return**: An array of DOM nodes
+```typescript
+unsubscribe(f: () => void): void
+```
 
-```javascript
-const element = html`
-    <div class="container">
-        <h1>Hello ${name}!</h1>
-    </div>
-`;
-document.body.append(...element);
+**Parameters**
+
+- `f`: The function to unsubscribe.
+
+**Return Value**
+
+- None
+
+**Example**
+
+```typescript
+import { subscribe, unsubscribe, o } from 'subay';
+
+const count = o(0);
+const fn = () => console.log(count());
+
+subscribe(fn);
+count(1); // Output: 1
+
+unsubscribe(fn);
+count(2); // No output
 ```
 
-#### `svg`
+### isObservable
 
-Template literal tag for creating SVG elements.
+**Introduction**
+Checks if a value is an observable.
 
-- **Usage**: `svg\`...\``
-- **Return**: An array of DOM nodes
+**Syntax**
 
-```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);
+```typescript
+isObservable(o: any): o is IO<any>
 ```
 
-#### `map(arrayFn, itemFn)`
+**Parameters**
+
+- `o`: The value to check.
 
-Function for rendering lists.
+**Return Value**
 
-- **Parameters**:
-    - `arrayFn` - Function that returns an array
-    - `itemFn` - Function that creates DOM nodes for each array item
-- **Return**: An array of DOM nodes
+- `boolean`: Whether it is an observable.
 
-```javascript
+**Example**
+
+```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
+
+**Introduction**
+Checks if a value is a computed value.
+
+**Syntax**
+
+```typescript
+isComputed(o: any): o is IS<any>
+```
+
+**Parameters**
+
+- `o`: The value to check.
+
+**Return Value**
+
+- `boolean`: Whether it is a computed value.
+
+**Example**
+
+```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
+
+**Introduction**
+Checks if a value is a reactive value (observable or computed value).
+
+**Syntax**
+
+```typescript
+isReactive(o: any): o is IO<any> | IS<any>
+```
+
+**Parameters**
+
+- `o`: The value to check.
+
+**Return Value**
+
+- `boolean`: Whether it is a reactive value.
+
+**Example**
+
+```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
+
+**Introduction**
+Maps an array to a DOM node array, automatically updating when the array changes.
+
+**Syntax**
+
+```typescript
+map<T>(array: () => T[], f: (item: T) => Node[]): Node[]
+```
+
+**Parameters**
+
+- `array`: A function that returns an array.
+- `f`: A mapping function that converts array items to DOM node arrays.
+
+**Return Value**
+
+- `Node[]`: DOM node array.
+
+**Example**
+
+```typescript
+import { map, o, html } from 'subay';
+
+const items = o(['a', 'b', 'c']);
 const list = map(
     () => items(),
-    (item, index) => html` <li key="${index}">${item}</li> `,
+    (item) => html`<li>${item}</li>`,
 );
+
+document.body.append(...list);
+// Renders: <li>a</li><li>b</li><li>c</li>
+
+items(['a', 'b', 'c', 'd']);
+// Automatically updates: <li>a</li><li>b</li><li>c</li><li>d</li>
 ```
 
-### 🛠️ Utilities
+### svg
 
-#### `isObservable(value)`
+**Introduction**
+Template tag function for creating SVG elements.
 
-Check if a value is an observable.
+**Syntax**
 
-- **Parameters**: `value` - Value to check
-- **Return**: Boolean
+```typescript
+svg(segments: TemplateStringsArray, ...values: any[]): Node[]
+```
 
-#### `isComputation(value)`
+**Parameters**
 
-Check if a value is a computed property.
+- `segments`: Static parts of the template string.
+- `values`: Dynamic parts of the template string.
 
-- **Parameters**: `value` - Value to check
-- **Return**: Boolean
+**Return Value**
 
-#### `isReactive(value)`
+- `Node[]`: SVG element node array.
 
-Check if a value is reactive (observable or computed property).
+**Example**
 
-- **Parameters**: `value` - Value to check
-- **Return**: Boolean
+```typescript
+import { svg, o } from 'subay';
 
-#### `sample(fn)`
+const radius = o(50);
+const circle = svg`<circle cx="100" cy="100" r="${radius}" fill="red"/>`;
 
-Run a function without tracking its dependencies.
+document.getElementById('svg').append(...circle);
+```
+
+### html
 
-- **Parameters**: `fn` - Function to run
-- **Return**: The result of the function execution
+**Introduction**
+Template tag function for creating HTML elements.
 
-```javascript
-const value = sample(() => count()); // Read count's value without establishing dependency
+**Syntax**
+
+```typescript
+html(segments: TemplateStringsArray, ...values: any[]): Node[]
 ```
 
-## ⚠️ Caveats
+**Parameters**
 
-### 1. Tag Position Interpolation
+- `segments`: Static parts of the template string.
+- `values`: Dynamic parts of the template string.
 
-In template strings, if interpolation is used in the tag position, the interpolation should be a string or a function that returns a string, where the returned string is the name of the HTML/SVG element. If you need to use a component, you need to call the method directly.
+**Return Value**
 
-**Correct Usage**:
+- `Node[]`: HTML element node array.
 
-```javascript
-// Static tag
-html`<div>Hello</div>`;
+**Example**
 
-// Dynamic tag (using string)
-const tagName = o('div');
-html`<${tagName}>Hello</${tagName}>`;
+```typescript
+import { html, o } from 'subay';
 
-// Dynamic tag (using function that returns string)
-const getTagName = () => 'div';
-html`<${getTagName}>Hello</${getTagName}>`;
+const count = o(0);
+const counter = html`
+    <div>
+        <p>Count: ${count}</p>
+        <button onclick=${() => count(count() + 1)}>Increment</button>
+    </div>
+`;
 
-// Using component (calling method directly)
-const MyComponent = () => html`<div>Component</div>`;
-html`<div>${MyComponent()}</div>`;
+document.body.append(...counter);
+// Clicking the button will automatically update the count value
 ```
 
-**Incorrect Usage**:
+**Using HTML**
 
-```javascript
-// Error: Component not called directly
-const MyComponent = () => html`<div>Component</div>`;
-html`<${MyComponent}>Hello</${MyComponent}>`; // This will try to create an element named "function MyComponent() {...}"
+Subay uses `DOMParser` to parse HTML templates. The `html` parameter must be a valid HTML string (similarly, the `svg` parameter must be a valid SVG string), which is different from JSX.
+
+**Example**
+
+```typescript
+import { html } from 'subay';
+
+// Valid HTML string
+const validHtml = html`<div><p>Hello</p></div>`;
+
+document.body.append(...validHtml);
 ```
 
-### 2. Dynamic Attribute Values
+**Don't Do This**
+
+```typescript
+import { html } from 'subay';
 
-If you need to dynamically set HTML/SVG element attribute values, you need to pass the return value of `S()` or `o()`. If you directly pass a regular function, this function will be treated as the attribute value, not the return value of the function.
+// Self-closing tags
+const invalidHtml = html`<div>
+    <span />
+    <span />
+</div>`; // Will be parsed as <div><span><span></span></span></div>
+```
 
-**Correct Usage**:
+**Passing Objects as Element Attributes**
 
-```javascript
-// Using observable
-const disabled = o(false);
-html`<button disabled="${disabled}">Click</button>`;
+If you need to pass an object as element attributes, you can use the `...` syntax.
 
-// Using computed property
-const isDisabled = S(() => count() > 5);
-html`<button disabled="${isDisabled}">Click</button>`;
+**Syntax**
 
-// Event binding (passing function directly)
-html`<button onclick="${() => count(count() + 1)}">Increment</button>`;
+```typescript
+html`<tag ...${props}></tag>`;
 ```
 
-**Incorrect Usage**:
+**Example**
 
-```javascript
-// Error: Regular function treated as attribute value
-const getDisabled = () => false;
-html`<button disabled="${getDisabled}">Click</button>`; // This will set "function getDisabled() {...}" as the attribute value
+```typescript
+import { html, o } from 'subay';
+
+const props = o({
+    className: 'container',
+    style: 'color: red;',
+});
+
+const element = html`<div ...${props}></div>`;
+
+document.body.append(...element);
 ```
 
-## 💡 Motivation
+**Component Declaration**
 
-The motivation behind Subay is to provide a lightweight, easy-to-use reactive UI library that avoids the complexity and size of large frameworks. Its design philosophy is:
+A component is a function that returns Node[], and can receive parameters. Unlike React, Vue, etc., component parameters are a list.
 
-- **Simplicity First**: Keep the API simple and intuitive, easy to learn and use
-- **Performance Priority**: Optimize DOM updates, reduce unnecessary computations
-- **Minimal Dependencies**: No external library dependencies, keep size small
-- **TypeScript Support**: Provide complete type definitions, improve development experience
+**Syntax**
 
-### Relationship with Sinuous
+```typescript
+const Component = (text, children: () => Node[]) => {
+    return html`<div>${text}</div>`;
+};
+```
 
-Subay references the design ideas of the [Sinuous](https://github.com/luwes/sinuous) library. The `o` and `S` APIs are almost identical to Sinuous, but there are the following differences in implementation details:
+**Example**
 
-1. **S Execution Timing**: In Subay, even if the result of an S function is not used, it will still be executed. In Sinuous, an S function is only executed when its result is actually used.
+```typescript
+import { html } from 'subay';
 
-    **Example**:
+const Greeting = (name: string, children: () => Node[]) => {
+    return html`
+        <div>
+            <h1>Hello, ${name}!</h1>
+            ${children()}
+        </div>
+    `;
+};
+```
 
-    ```javascript
-    const userId = o('');
-    const defaultThemeId = o('rainbow');
+**Component Usage**
 
-    const themeId = S(() => {
-        if (!userId()) {
-            return defaultThemeId();
-        }
-        return userTheme();
-    });
-    const userTheme = S(() => {
-        // if !userId(), sinuous won't execute here
-        // but subay will execute
-        console.log('side effect on ', userId());
-        return `${userId()}'s theme`;
-    });
-    S(() => {
-        console.log('now the theme is ', themeId());
-    });
+When using a component in a template, reference the component at the tag position.
+Because the template is an HTML string, self-closing tags are not supported when referencing.
+The parameters passed to the component must be in the same order as the component's declared parameters.
+The parameters received by the component are always consistent with those passed in.
+
+**Example**
+
+```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);
+```
+
+**Don't Do This**
+
+```typescript
+import { html, o } from 'subay';
 
-    userId('John');
-    userId('');
-    userId('Mary');
-    ```
+const Greeting = (greet: string, name: () => string) => {
+    return html`<h1>${greet}, ${name}!</h1>`;
+};
 
-    In this example, when `userId()` is an empty string, `themeId()` will return `defaultThemeId()` and not use the result of `userTheme()`. In Sinuous, the `userTheme()` function will not be executed; but in Subay, the `userTheme()` function will still be executed, producing a side effect.
+const name = o('World');
+// Error, the following span will be treated as a child node of Greeting.
+const app = html`
+    <div>
+        <${Greeting}
+            greet=${'Hello'}
+            name=${name}
+        />
+        <span></span>
+    </div>
+`;
+// Error, parameter order is inconsistent with Greeting's parameters
+const app = html` <div><${Greeting} name=${name} greet=${'Hi'} ></${Greeting}></div> `;
+
+document.body.append(...app);
+```
+
+**Dynamic Components**
+
+The interpolation at the tag position can be the return value of `S` or `o`, and components can be dynamically selected for rendering based on conditions.
 
-2. **o's Reference Management for S**: When S is recomputed, the o's that S depended on during the last computation won't immediately forget S. Instead, they will filter out the "forgotten" S only when o is updated next time. Since o updates are usually less frequent than S recomputations, this approach slightly improves performance.
+**Example**
 
-Subay is suitable for projects that need lightweight UI solutions, especially small applications, prototype development, or scenarios with high performance requirements.
+```typescript
+import { html, o, S } from 'subay';
 
-## 📄 License
+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>
+`;
 
-MIT License - see the [LICENSE](LICENSE) file for details.
+document.body.append(...app);
+```