subay 0.0.6 → 0.0.8

package/README.md

@@ -1,103 +1,681 @@
 # Subay
 
-A lightweight reactive UI library with state management and template rendering.
+Subay is a lightweight reactive programming library that provides state management and DOM manipulation capabilities.
 
-## ✨ Features
+## API
 
-- **Reactive State Management**: Create observable values and computed properties
-- **Template Rendering**: Use tagged template literals for HTML and SVG
-- **Efficient DOM Updates**: Optimized rendering with minimal DOM operations
-- **TypeScript Support**: Full TypeScript integration
+### root
 
-## 📦 Installation
+**Introduction**
+Creates a root update context for managing the lifecycle of reactive states.
 
-```bash
-npm install subay
+**Syntax**
+
+```typescript
+root<T>(fn: (destroy: () => void) => T): T
+```
+
+**Parameters**
+
+- `fn`: A function that receives a `destroy` function as a parameter, used to manually destroy the root context.
+
+**Return Value**
+
+- `T`: The return value of the `fn` function.
+
+**Example**
+
+```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
+
+    // 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.
+
+**Syntax**
+
+```typescript
+S<T>(fn: (pv: T | undefined) => T, value?: T): IS<T>
+```
+
+**Parameters**
+
+- `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 count = o(0);
+const doubled = S(() => count() * 2);
+
+console.log(doubled()); // 0
+count(1);
+console.log(doubled()); // 2
+```
+
+### o / observable
+
+**Introduction**
+Creates an observable value for storing and updating state.
+
+**Syntax**
+
+```typescript
+o<T>(value: T): IO<T>
+```
+
+**Parameters**
+
+- `value`: Initial value.
+
+**Return 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.
+
+**Example**
+
+```typescript
+import { o } from 'subay';
+
+const count = o(0);
+console.log(count()); // 0
+count(1);
+console.log(count()); // 1
+```
+
+### cleanup
+
+**Introduction**
+Registers a cleanup function that executes when the current update context is destroyed.
+
+**Syntax**
+
+```typescript
+cleanup<T extends () => void>(f: T): T
+```
+
+**Parameters**
+
+- `f`: Cleanup function.
+
+**Return Value**
+
+- `T`: The passed cleanup function.
+
+**Example**
+
+```typescript
+import { root, S, o, cleanup } from 'subay';
+
+root(() => {
+    const count = o(0);
+
+    S(() => {
+        console.log(count());
+        cleanup(() => {
+            console.log('Cleanup called');
+        });
+    });
+
+    count(1);
+});
+// Output: 0, 1, Cleanup called
+```
+
+### transaction
+
+**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)
+```
+
+### sample
+
+**Introduction**
+Gets the value of an observable without establishing a dependency relationship.
+
+**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;
+
+S(() => {
+    // No dependency relationship established
+    cachedValue = sample(() => count());
+    console.log(cachedValue);
+});
+
+count(1); // Will not trigger recalculation
+console.log(cachedValue); // 0
+```
+
+### isListening
+
+**Introduction**
+Checks if the current state is in reactive listening mode.
+
+**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
+});
+```
+
+### subscribe
+
+**Introduction**
+Subscribes to a function that automatically executes when dependent observables change.
+
+**Syntax**
+
+```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
+```
+
+### unsubscribe
+
+**Introduction**
+Unsubscribes a function.
+
+**Syntax**
+
+```typescript
+unsubscribe(f: () => void): void
+```
+
+**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
+```
+
+### isObservable
+
+**Introduction**
+Checks if a value is an observable.
+
+**Syntax**
+
+```typescript
+isObservable(o: any): o is IO<any>
 ```
 
-## 🔧 Basic Usage
+**Parameters**
 
-### 🔄 Reactive State
+- `o`: The value to check.
 
-```javascript
-import { o, S } from 'subay';
+**Return Value**
+
+- `boolean`: Whether it is an observable.
+
+**Example**
+
+```typescript
+import { isObservable, o, S } from 'subay';
 
-// Create an observable value
 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).
 
-// Create a computed property
+**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);
 
-// Update the value
-count(5);
-console.log(doubled()); // Output: 10
+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[]
 ```
 
-### 🎨 Template Rendering
+**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) => 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>
+```
+
+### svg
+
+**Introduction**
+Template tag function for creating SVG elements.
+
+**Syntax**
+
+```typescript
+svg(segments: TemplateStringsArray, ...values: any[]): Node[]
+```
+
+**Parameters**
+
+- `segments`: Static parts of the template string.
+- `values`: Dynamic parts of the template string.
+
+**Return Value**
 
-```javascript
+- `Node[]`: SVG element node array.
+
+**Example**
+
+```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
+
+**Introduction**
+Template tag function for creating HTML elements.
+
+**Syntax**
+
+```typescript
+html(segments: TemplateStringsArray, ...values: any[]): Node[]
+```
+
+**Parameters**
+
+- `segments`: Static parts of the template string.
+- `values`: Dynamic parts of the template string.
+
+**Return Value**
+
+- `Node[]`: HTML element node array.
+
+**Example**
+
+```typescript
 import { html, o } from 'subay';
 
-const name = o('World');
 const count = o(0);
+const counter = html`
+    <div>
+        <p>Count: ${count}</p>
+        <button onclick=${() => count(count() + 1)}>Increment</button>
+    </div>
+`;
+
+document.body.append(...counter);
+// Clicking the button will automatically update the count value
+```
+
+**Using HTML**
+
+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);
+```
+
+**Don't Do This**
+
+```typescript
+import { html } from 'subay';
+
+// Self-closing tags
+const invalidHtml = html`<div>
+    <span />
+    <span />
+</div>`; // Will be parsed as <div><span><span></span></span></div>
+```
+
+**Passing Objects as Element Attributes**
+
+If you need to pass an object as element attributes, you can use the `...` syntax.
+
+**Syntax**
 
-document.body.append(
-    ...html`
+```typescript
+html`<tag ...${props}></tag>`;
+```
+
+**Example**
+
+```typescript
+import { html, o } from 'subay';
+
+const props = o({
+    className: 'container',
+    style: 'color: red;',
+});
+
+const element = html`<div ...${props}></div>`;
+
+document.body.append(...element);
+```
+
+**Component Declaration**
+
+A component is a function that returns Node[], and can receive parameters. Unlike React, Vue, etc., component parameters are a list.
+
+**Syntax**
+
+```typescript
+const Component = (text, children: () => Node[]) => {
+    return html`<div>${text}</div>`;
+};
+```
+
+**Example**
+
+```typescript
+import { html } from 'subay';
+
+const Greeting = (name: string, children: () => Node[]) => {
+    return html`
         <div>
-            <h1>Hello ${name}!</h1>
-            <p>Count: ${count}</p>
-            <button onclick="${() => count(count() + 1)}">Increment</button>
-            <button onclick="${() => name('Subay')}">Change Name</button>
+            <h1>Hello, ${name}!</h1>
+            ${children()}
         </div>
-    `,
-);
+    `;
+};
 ```
 
-### 📋 List Rendering
+**Component Usage**
 
-```javascript
-import { html, o, map } from 'subay';
+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.
 
-const items = o(['Apple', 'Banana', 'Cherry']);
+**Example**
 
-document.body.append(
-    ...html`
-        <ul>
-            ${map(
-                () => items(),
-                (item) => html` <li>${item}</li> `,
-            )}
-        </ul>
-        <button onclick="${() => items([...items(), 'Date'])}">Add Item</button>
-    `,
-);
+```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';
+
+const Greeting = (greet: string, name: () => string) => {
+    return html`<h1>${greet}, ${name}!</h1>`;
+};
+
+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);
 ```
 
-## 📚 Core API
+**Dynamic Components**
 
-### ⚙️ State Management
+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.
 
-- **`o(value)`**: Create an observable value
-- **`S(fn, initialValue?)`**: Create a computed property
-- **`root(fn)`**: Create a root context for reactive computations
-- **`cleanup(fn)`**: Register a cleanup function
-- **`transaction(fn)`**: Batch multiple updates
-- **`sample(fn)`**: Run a function without tracking dependencies
+**Example**
 
-### 🖼️ Rendering
+```typescript
+import { html, o, S } from 'subay';
 
-- **`html`**: Tagged template literal for HTML
-- **`svg`**: Tagged template literal for SVG
-- **`map(arrayFn, itemFn)`**: Render a list of items
+const Greeting = (name: () => string) => {
+    return html`<h1>Hello, ${name}!</h1>`;
+};
 
-### 🛠️ Utilities
+const Farewell = (name: () => string) => {
+    return html`<h1>Goodbye, ${name}!</h1>`;
+};
 
-- **`isObservable(value)`**: Check if a value is an observable
-- **`isComputed(value)`**: Check if a value is a computed property
-- **`isReactive(value)`**: Check if a value is reactive
-- **`subscribe(fn)`**: Subscribe to changes
-- **`unsubscribe(fn)`**: Unsubscribe from changes
+const showGreeting = o(true);
+const name = o('World');
+const Component = S(() => (showGreeting() ? Greeting : Farewell));
 
-## 📄 License
+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);
+```