subay 0.0.6 → 0.0.7

package/README.md

@@ -1,23 +1,42 @@
-# Subay
+# 🐣 Subay
 
-A lightweight reactive UI library with state management and template rendering.
+A < 700 LOC declarative, reactive UI library.
 
 ## ✨ Features
 
-- **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
+- **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
 
 ## 📦 Installation
 
+### NPM
+
 ```bash
 npm install subay
 ```
 
+### Yarn
+
+```bash
+yarn add subay
+```
+
+### Direct Import
+
+```html
+<script type="module">
+    import { html, o, S } from 'https://cdn.jsdelivr.net/npm/subay@latest/lib/index.js';
+    // Use Subay
+</script>
+```
+
 ## 🔧 Basic Usage
 
-### 🔄 Reactive State
+### 🔄 State Management
 
 ```javascript
 import { o, S } from 'subay';
@@ -28,12 +47,17 @@ const count = o(0);
 // Create a computed property
 const doubled = S(() => count() * 2);
 
-// Update the value
+// Read value
+console.log(count()); // Output: 0
+console.log(doubled()); // Output: 0
+
+// Update value
 count(5);
+console.log(count()); // Output: 5
 console.log(doubled()); // Output: 10
 ```
 
-### 🎨 Template Rendering
+### 🎨 Rendering
 
 ```javascript
 import { html, o } from 'subay';
@@ -44,7 +68,7 @@ const count = o(0);
 document.body.append(
     ...html`
         <div>
-            <h1>Hello ${name}!</h1>
+            <h1>Hello, ${name}!</h1>
             <p>Count: ${count}</p>
             <button onclick="${() => count(count() + 1)}">Increment</button>
             <button onclick="${() => name('Subay')}">Change Name</button>
@@ -53,7 +77,7 @@ document.body.append(
 );
 ```
 
-### 📋 List Rendering
+### 📋 List
 
 ```javascript
 import { html, o, map } from 'subay';
@@ -73,30 +97,280 @@ document.body.append(
 );
 ```
 
-## 📚 Core API
+## 📚 API
+
+### ⚙️ State
+
+#### `o(value)`
+
+Create an observable value.
+
+- **Parameters**: `value` - Initial value
+- **Return**: A function that returns the current value when called, and updates the value when passed a parameter
+
+```javascript
+const count = o(0);
+count(); // Read value
+count(5); // Update value
+```
+
+#### `S(fn, initialValue?)`
+
+Create a computed property.
+
+- **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
+
+```javascript
+const doubled = S(() => count() * 2);
+doubled(); // Read computation result
+```
+
+#### `root(fn)`
+
+Create a root context for managing the lifecycle of computed properties.
+
+- **Parameters**: `fn` - Function that receives a destroy function as a parameter
+- **Return**: The result of the function execution
+
+```javascript
+root((destroy) => {
+    const count = o(0);
+    const doubled = S(() => count() * 2);
+
+    // Use count and doubled
+
+    // Optional: Call destroy() to clean up resources when appropriate
+});
+```
+
+#### `cleanup(fn)`
+
+Register a cleanup function that executes when the computed property is recomputed or destroyed.
+
+- **Parameters**: `fn` - Cleanup function
+- **Return**: The passed cleanup function
+
+```javascript
+S(() => {
+    const timer = setInterval(() => {
+        console.log('tick');
+    }, 1000);
 
-### ⚙️ State Management
+    cleanup(() => clearInterval(timer));
 
-- **`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
+    return count();
+});
+```
+
+#### `transaction(fn)`
+
+Batch execute multiple updates to reduce unnecessary computations and rendering.
+
+- **Parameters**: `fn` - Function containing update operations
+- **Return**: The result of the function execution
+
+```javascript
+transaction(() => {
+    count(1);
+    name('Subay');
+    items(['a', 'b', 'c']);
+});
+```
 
 ### 🖼️ Rendering
 
-- **`html`**: Tagged template literal for HTML
-- **`svg`**: Tagged template literal for SVG
-- **`map(arrayFn, itemFn)`**: Render a list of items
+#### `html`
+
+Template literal tag for creating HTML elements.
+
+- **Usage**: `html\`...\``
+- **Return**: An array of DOM nodes
+
+```javascript
+const element = html`
+    <div class="container">
+        <h1>Hello ${name}!</h1>
+    </div>
+`;
+document.body.append(...element);
+```
+
+#### `svg`
+
+Template literal tag for creating SVG elements.
+
+- **Usage**: `svg\`...\``
+- **Return**: An array of DOM nodes
+
+```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)`
+
+Function for rendering lists.
+
+- **Parameters**:
+    - `arrayFn` - Function that returns an array
+    - `itemFn` - Function that creates DOM nodes for each array item
+- **Return**: An array of DOM nodes
+
+```javascript
+const list = map(
+    () => items(),
+    (item, index) => html` <li key="${index}">${item}</li> `,
+);
+```
 
 ### 🛠️ Utilities
 
-- **`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
+#### `isObservable(value)`
+
+Check if a value is an observable.
+
+- **Parameters**: `value` - Value to check
+- **Return**: Boolean
+
+#### `isComputation(value)`
+
+Check if a value is a computed property.
+
+- **Parameters**: `value` - Value to check
+- **Return**: Boolean
+
+#### `isReactive(value)`
+
+Check if a value is reactive (observable or computed property).
+
+- **Parameters**: `value` - Value to check
+- **Return**: Boolean
+
+#### `sample(fn)`
+
+Run a function without tracking its dependencies.
+
+- **Parameters**: `fn` - Function to run
+- **Return**: The result of the function execution
+
+```javascript
+const value = sample(() => count()); // Read count's value without establishing dependency
+```
+
+## ⚠️ Caveats
+
+### 1. Tag Position Interpolation
+
+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.
+
+**Correct Usage**:
+
+```javascript
+// Static tag
+html`<div>Hello</div>`;
+
+// Dynamic tag (using string)
+const tagName = o('div');
+html`<${tagName}>Hello</${tagName}>`;
+
+// Dynamic tag (using function that returns string)
+const getTagName = () => 'div';
+html`<${getTagName}>Hello</${getTagName}>`;
+
+// Using component (calling method directly)
+const MyComponent = () => html`<div>Component</div>`;
+html`<div>${MyComponent()}</div>`;
+```
+
+**Incorrect Usage**:
+
+```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() {...}"
+```
+
+### 2. Dynamic Attribute Values
+
+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.
+
+**Correct Usage**:
+
+```javascript
+// Using observable
+const disabled = o(false);
+html`<button disabled="${disabled}">Click</button>`;
+
+// Using computed property
+const isDisabled = S(() => count() > 5);
+html`<button disabled="${isDisabled}">Click</button>`;
+
+// Event binding (passing function directly)
+html`<button onclick="${() => count(count() + 1)}">Increment</button>`;
+```
+
+**Incorrect Usage**:
+
+```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
+```
+
+## 💡 Motivation
+
+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:
+
+- **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
+
+### Relationship with Sinuous
+
+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:
+
+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.
+
+    **Example**:
+
+    ```javascript
+    const userId = o('');
+    const defaultThemeId = o('rainbow');
+
+    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());
+    });
+
+    userId('John');
+    userId('');
+    userId('Mary');
+    ```
+
+    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.
+
+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.
+
+Subay is suitable for projects that need lightweight UI solutions, especially small applications, prototype development, or scenarios with high performance requirements.
 
 ## 📄 License