rask-ui 0.3.3 → 0.4.0

package/README.md

@@ -4,13 +4,13 @@
   <img src="logo.png" alt="Logo" width="200">
 </p>
 
-A lightweight reactive component library that combines the simplicity of observable state management with the full power of a virtual DOM reconciler.
+A lightweight reactive component library that combines the simplicity of observable state management with the full power of a virtual DOM reconciler. Ideal for single page applications, using web technology.
 
 ```bash
 npm install rask-ui
 ```
 
-## The Problem with Modern UI Frameworks
+## The Itch with Modern UI Frameworks
 
 Modern UI frameworks present developers with a fundamental tradeoff between state management and UI expression:
 
@@ -42,9 +42,9 @@ function MyApp() {
 }
 ```
 
-Solid offers a simpler mental model with fine-grained reactivity. Updates don't happen by calling the component function again, but in "hidden" parts of expressions in the UI. However:
+Solid offers a seamingly simpler mental model with fine-grained reactivity. Updates don't happen by calling the component function again, which resolves the mental strain of expressing state management, however:
 
-- Requires understanding special compiler transformations
+- The code you write is compiled to balance DX vs requirements of the runtime
 - Special components for expressing dynamic UIs (`<Show>`, `<For>`, etc.)
 - Different signatures for accessing reactive values: `count()` VS `state.count`
 
@@ -60,13 +60,13 @@ function MyApp() {
 
 RASK gives you:
 
-- **Predictable observable state management** - No reconciler interference, just plain reactivity
-- **Full reconciler power** - Express complex UIs naturally with components
+- **Simple state management** - No reconciler interference with your state management
+- **Full reconciler power** - Express complex UIs naturally with the language
 - **No special syntax** - Access state properties directly, no function calls
 - **No compiler magic** - Plain JavaScript/TypeScript
-- **Simple mental model** - State updates trigger only affected components
+- **Simple mental model** - Just implement state and UI. No manual optimizations, special syntax or compiler magic
 
-Built on [Inferno JS](https://github.com/infernojs/inferno).
+:fire: Built on [Inferno JS](https://github.com/infernojs/inferno).
 
 ## Getting Started
 
@@ -182,9 +182,9 @@ function Parent() {
 
 When `state.count` changes in Parent, only Child re-renders because it accesses `props.value`.
 
-### Important: Do Not Destructure Reactive Objects
+### One Rule To Accept
 
-**RASK follows the same rule as Solid.js**: Never destructure reactive objects (state, props, context values, async, query, mutation). Destructuring extracts plain values and breaks reactivity.
+**RASK has observable primitives**: Never destructure reactive objects (state, props, context values, async, query, mutation). Destructuring extracts plain values and breaks reactivity.
 
 ```tsx
 // ❌ BAD - Destructuring breaks reactivity
@@ -234,6 +234,7 @@ Reactive objects are implemented using JavaScript Proxies. When you access a pro
 - `createQuery()` - Never destructure query objects
 - `createMutation()` - Never destructure mutation objects
 - `createView()` - Never destructure view objects
+- `createComputed()` - Never destructure computed objects
 
 ## API Reference
 
@@ -300,24 +301,26 @@ Creates a view that merges multiple objects (reactive or plain) into a single ob
 ```tsx
 import { createView, createState } from "rask-ui";
 
-function Counter() {
+function createCounter() {
   const state = createState({ count: 0, name: "Counter" });
-  const helpers = {
-    increment: () => state.count++,
-    decrement: () => state.count--,
-    reset: () => (state.count = 0),
-  };
+  const increment = () => state.count++;
+  const decrement = () => state.count--;
+  const reset = () => (state.count = 0);
+
+  return createView(state, { increment, decrement, reset });
+}
 
-  const view = createView(state, helpers);
+function Counter() {
+  const counter = createCounter();
 
   return () => (
     <div>
       <h1>
-        {view.name}: {view.count}
+        {counter.name}: {counter.count}
       </h1>
-      <button onClick={view.increment}>+</button>
-      <button onClick={view.decrement}>-</button>
-      <button onClick={view.reset}>Reset</button>
+      <button onClick={counter.increment}>+</button>
+      <button onClick={counter.decrement}>-</button>
+      <button onClick={counter.reset}>Reset</button>
     </div>
   );
 }
@@ -329,38 +332,6 @@ function Counter() {
 
 **Returns:** A view object with getters for all properties, maintaining reactivity
 
-**Use Cases:**
-
-1. **Merge state with helper methods:**
-
-   ```tsx
-   const state = createState({ count: 0 });
-   const helpers = { increment: () => state.count++ };
-   const view = createView(state, helpers);
-   // Access both: view.count, view.increment()
-   ```
-
-2. **Combine multiple reactive objects:**
-
-   ```tsx
-   const user = createState({ name: "Alice" });
-   const settings = createState({ theme: "dark" });
-   const view = createView(user, settings);
-   // Access both: view.name, view.theme
-   ```
-
-3. **Override properties with computed values:**
-   ```tsx
-   const state = createState({ firstName: "John", lastName: "Doe" });
-   const computed = {
-     get fullName() {
-       return `${state.firstName} ${state.lastName}`;
-     },
-   };
-   const view = createView(state, computed);
-   // view.fullName returns "John Doe" and updates when state changes
-   ```
-
 **Notes:**
 
 - Reactivity is maintained through getters that reference the source objects
@@ -403,25 +374,170 @@ function Example() {
 
 Pass the ref to an element's `ref` prop. The `current` property will be set to the DOM element when mounted and `null` when unmounted.
 
-**Example with SVG:**
+---
+
+### Reactivity Primitives
+
+#### `createEffect(callback)`
+
+Creates an effect that automatically tracks reactive dependencies and re-runs whenever they change. The effect runs immediately on creation.
 
 ```tsx
-function Drawing() {
-  const svgRef = createRef<SVGSVGElement>();
+import { createEffect, createState } from "rask-ui";
 
-  const getSize = () => {
-    if (svgRef.current) {
-      const bbox = svgRef.current.getBBox();
-      console.log(`Width: ${bbox.width}, Height: ${bbox.height}`);
-    }
+function Timer() {
+  const state = createState({ count: 0, log: [] });
+
+  // Effect runs immediately and whenever state.count changes
+  createEffect(() => {
+    console.log("Count changed:", state.count);
+    state.log.push(`Count: ${state.count}`);
+  });
+
+  return () => (
+    <div>
+      <p>Count: {state.count}</p>
+      <button onClick={() => state.count++}>Increment</button>
+      <ul>
+        {state.log.map((entry, i) => (
+          <li key={i}>{entry}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+**Parameters:**
+
+- `callback: () => void` - Function to run when dependencies change
+
+**Features:**
+
+- Runs immediately on creation
+- Automatically tracks reactive dependencies accessed during execution
+- Re-runs on microtask when dependencies change (prevents synchronous cascades)
+- Automatically cleaned up when component unmounts
+- Can be used for side effects like logging, syncing to localStorage, or updating derived state
+
+**Notes:**
+
+- Only call during component setup phase (not in render function)
+- Effects are queued on microtask to avoid synchronous execution from prop changes
+- Be careful with effects that modify state - can cause infinite loops if not careful
+
+---
+
+#### `createComputed<T>(computed)`
+
+Creates an object with computed properties that automatically track dependencies and cache results until dependencies change.
+
+```tsx
+import { createComputed, createState } from "rask-ui";
+
+function ShoppingCart() {
+  const state = createState({
+    items: [
+      { id: 1, name: "Apple", price: 1.5, quantity: 3 },
+      { id: 2, name: "Banana", price: 0.8, quantity: 5 },
+    ],
+    taxRate: 0.2,
+  });
+
+  const computed = createComputed({
+    subtotal: () =>
+      state.items.reduce((sum, item) => sum + item.price * item.quantity, 0),
+    tax: () => computed.subtotal * state.taxRate,
+    total: () => computed.subtotal + computed.tax,
+    itemCount: () =>
+      state.items.reduce((sum, item) => sum + item.quantity, 0),
+  });
+
+  return () => (
+    <div>
+      <h2>Cart ({computed.itemCount} items)</h2>
+      <ul>
+        {state.items.map((item) => (
+          <li key={item.id}>
+            {item.name}: ${item.price} x {item.quantity}
+            <button onClick={() => item.quantity++}>+</button>
+            <button onClick={() => item.quantity--}>-</button>
+          </li>
+        ))}
+      </ul>
+      <div>
+        <p>Subtotal: ${computed.subtotal.toFixed(2)}</p>
+        <p>Tax ({state.taxRate * 100}%): ${computed.tax.toFixed(2)}</p>
+        <p>
+          <strong>Total: ${computed.total.toFixed(2)}</strong>
+        </p>
+      </div>
+    </div>
+  );
+}
+```
+
+**Parameters:**
+
+- `computed: T` - Object where each property is a function returning a computed value
+
+**Returns:** Reactive object with cached computed properties
+
+**Features:**
+
+- **Lazy evaluation** - Computed values are only calculated when accessed
+- **Automatic caching** - Results are cached until dependencies change
+- **Dependency tracking** - Automatically tracks what state each computed depends on
+- **Composable** - Computed properties can depend on other computed properties
+- **Efficient** - Only recomputes when dirty (dependencies changed)
+- **Automatic cleanup** - Cleaned up when component unmounts
+
+**Notes:**
+
+- Access computed properties directly (e.g., `computed.total`), don't call as functions
+- Computed properties are getters, not functions
+- **Do not destructure** - Breaks reactivity (see warning section above)
+- Only call during component setup phase
+
+---
+
+### Automatic Batching
+
+RASK automatically batches state updates to minimize re-renders. This happens transparently without any special syntax.
+
+**How it works:**
+
+- **User interactions** (clicks, inputs, keyboard, etc.) - State changes are batched and flushed synchronously at the end of the event
+- **Other updates** (setTimeout, fetch callbacks, etc.) - State changes are batched and flushed on the next microtask
+
+```tsx
+function BatchingExample() {
+  const state = createState({ count: 0, clicks: 0 });
+
+  const handleClick = () => {
+    // All three updates are batched into a single render
+    state.count++;
+    state.clicks++;
+    state.count++;
+    // UI updates once with count=2, clicks=1
+  };
+
+  const handleAsync = () => {
+    setTimeout(() => {
+      // These updates are also batched (async batch)
+      state.count++;
+      state.clicks++;
+      // UI updates once on next microtask
+    }, 100);
   };
 
   return () => (
     <div>
-      <svg ref={svgRef} width="200" height="200">
-        <circle cx="100" cy="100" r="50" />
-      </svg>
-      <button onClick={getSize}>Get SVG Size</button>
+      <p>
+        Count: {state.count}, Clicks: {state.clicks}
+      </p>
+      <button onClick={handleClick}>Sync Update</button>
+      <button onClick={handleAsync}>Async Update</button>
     </div>
   );
 }
@@ -543,13 +659,16 @@ import { createAsync } from "rask-ui";
 function UserProfile() {
   const user = createAsync(fetch("/api/user").then((r) => r.json()));
 
-  return () => (
-    <div>
-      {user.isPending && <p>Loading...</p>}
-      {user.error && <p>Error: {user.error}</p>}
-      {user.value && <p>Hello, {user.value.name}!</p>}
-    </div>
-  );
+  return () => }
+    if (user.isPending) {
+      return <p>Loading...</p>
+    }
+
+    if (user.error) {
+      return <p>Error: {user.error}</p>
+    }
+
+    return <p>Hello, {user.value.name}!</p>
 }
 ```
 
@@ -580,16 +699,25 @@ import { createQuery } from "rask-ui";
 
 function Posts() {
   const posts = createQuery(() => fetch("/api/posts").then((r) => r.json()));
+  const renderPosts = () => {
+    if (posts.isPending) {
+      return <p>Loading...</p>;
+    }
+
+    if (posts.error) {
+      return <p>Error: {posts.error}</p>;
+    }
+
+    return posts.data.map((post) => (
+      <article key={post.id}>{post.title}</article>
+    ));
+  };
 
   return () => (
     <div>
       <button onClick={() => posts.fetch()}>Refresh</button>
       <button onClick={() => posts.fetch(true)}>Force Refresh</button>
-
-      {posts.isPending && <p>Loading...</p>}
-      {posts.error && <p>Error: {posts.error}</p>}
-      {posts.data &&
-        posts.data.map((post) => <article key={post.id}>{post.title}</article>)}
+      {renderPosts()}
     </div>
   );
 }
@@ -630,7 +758,7 @@ function CreatePost() {
     fetch("/api/posts", {
       method: "POST",
       body: JSON.stringify(data),
-    }).then((r) => r.json())
+    }))
   );
 
   const handleSubmit = () => {
@@ -768,7 +896,9 @@ Keys prevent component recreation when list order changes.
 
 ### Computed Values
 
-Create computed values using functions in setup:
+You can create computed values in two ways:
+
+**1. Simple computed functions** - For basic derived values:
 
 ```tsx
 function ShoppingCart() {
@@ -799,6 +929,48 @@ function ShoppingCart() {
 
 Computed functions automatically track dependencies when called during render.
 
+**2. Using `createComputed`** - For cached, efficient computed values with automatic dependency tracking:
+
+```tsx
+function ShoppingCart() {
+  const state = createState({
+    items: [
+      { id: 1, price: 10, quantity: 2 },
+      { id: 2, price: 20, quantity: 1 },
+    ],
+    taxRate: 0.1,
+  });
+
+  const computed = createComputed({
+    subtotal: () =>
+      state.items.reduce((sum, item) => sum + item.price * item.quantity, 0),
+    tax: () => computed.subtotal * state.taxRate,
+    total: () => computed.subtotal + computed.tax,
+  });
+
+  return () => (
+    <div>
+      <ul>
+        {state.items.map((item) => (
+          <li key={item.id}>
+            ${item.price} x {item.quantity}
+          </li>
+        ))}
+      </ul>
+      <p>Subtotal: ${computed.subtotal}</p>
+      <p>Tax: ${computed.tax}</p>
+      <p>Total: ${computed.total}</p>
+    </div>
+  );
+}
+```
+
+Benefits of `createComputed`:
+- **Cached** - Only recalculates when dependencies change
+- **Lazy** - Only calculates when accessed
+- **Composable** - Computed properties can depend on other computed properties
+- **Efficient** - Better performance for expensive calculations
+
 ### Composition
 
 Compose complex logic by combining state and methods using `createView`:

package/dist/batch.d.ts

@@ -0,0 +1,4 @@
+export declare function queue(cb: () => void): void;
+export declare function syncBatch(cb: () => void): void;
+export declare function installEventBatching(target?: EventTarget): void;
+//# sourceMappingURL=batch.d.ts.map

package/dist/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAmDA,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,IAAI,QAWnC;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,QAOvC;AAED,wBAAgB,oBAAoB,CAAC,MAAM,GAAE,WAAsB,QA0BlE"}

package/dist/batch.js

@@ -0,0 +1,86 @@
+const INTERACTIVE_EVENTS = [
+    // DISCRETE
+    "beforeinput",
+    "input",
+    "change",
+    "compositionend",
+    "keydown",
+    "keyup",
+    "click",
+    "contextmenu",
+    "submit",
+    "reset",
+    // GESTURE START
+    "pointerdown",
+    "mousedown",
+    "touchstart",
+    // GESTURE END
+    "pointerup",
+    "mouseup",
+    "touchend",
+    "touchcancel",
+];
+let inInteractive = 0;
+let hasAsyncQueue = false;
+let hasSyncQueue = false;
+const flushQueue = new Set();
+const syncFlushQueue = new Set();
+function queueAsync() {
+    if (hasAsyncQueue) {
+        return;
+    }
+    hasAsyncQueue = true;
+    queueMicrotask(() => {
+        hasAsyncQueue = false;
+        if (!flushQueue.size) {
+            return;
+        }
+        const queued = Array.from(flushQueue);
+        flushQueue.clear();
+        queued.forEach((cb) => cb());
+    });
+}
+export function queue(cb) {
+    if (hasSyncQueue) {
+        syncFlushQueue.add(cb);
+        return;
+    }
+    flushQueue.add(cb);
+    if (!inInteractive) {
+        queueAsync();
+    }
+}
+export function syncBatch(cb) {
+    hasSyncQueue = true;
+    cb();
+    hasSyncQueue = false;
+    const queued = Array.from(syncFlushQueue);
+    syncFlushQueue.clear();
+    queued.forEach((cb) => cb());
+}
+export function installEventBatching(target = document) {
+    const captureOptions = { capture: true, passive: true };
+    const bubbleOptions = { passive: true };
+    const onCapture = () => {
+        inInteractive++;
+        // Backup in case of stop propagation
+        queueAsync();
+    };
+    const onBubble = () => {
+        if (--inInteractive === 0 && flushQueue.size) {
+            const queued = Array.from(flushQueue);
+            flushQueue.clear();
+            queued.forEach((cb) => cb());
+        }
+    };
+    // 1) open scope before handlers
+    INTERACTIVE_EVENTS.forEach((type) => {
+        target.addEventListener(type, onCapture, captureOptions);
+    });
+    queueMicrotask(() => {
+        // 2) close + flush after handlers (bubble on window/document)
+        INTERACTIVE_EVENTS.forEach((type) => {
+            target.addEventListener(type, onBubble, bubbleOptions);
+        });
+    });
+}

package/dist/component.d.ts

@@ -8,15 +8,24 @@ declare class RaskComponent<P extends Props<any>> extends Component<P & {
 }> {
     private renderFn?;
     private reactiveProps?;
-    private prevChildren;
     private observer;
-    private hasDirtyProps;
+    private isRendering;
+    effects: Array<{
+        isDirty: boolean;
+        run: () => void;
+    }>;
     contexts: Map<any, any>;
     getChildContext(): any;
     onMounts: Array<() => void>;
     onCleanups: Array<() => void>;
+    private createReactiveProps;
     componentDidMount(): void;
     componentWillUnmount(): void;
+    /**
+     *
+     */
+    componentWillUpdate(nextProps: any): void;
+    componentWillReceiveProps(): void;
     shouldComponentUpdate(nextProps: Props<any>): boolean;
     render(): any;
 }

package/dist/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,EACL,SAAS,EACT,KAAK,EAEN,MAAM,SAAS,CAAC;AAMjB,wBAAgB,mBAAmB,uBAMlC;AAED,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,QAMrC;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,QAMvC;AAED,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,IAClD,CAAC,MAAM,MAAM,KAAK,CAAC,GACnB,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,KAAK,CAAC,CAAC;AAEhC,cAAM,aAAa,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,CAAE,SAAQ,SAAS,CACzD,CAAC,GAAG;IAAE,WAAW,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAA;CAAE,CAC9C;IACC,OAAO,CAAC,QAAQ,CAAC,CAAc;IAC/B,OAAO,CAAC,aAAa,CAAC,CAAa;IACnC,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAEb;IACH,OAAO,CAAC,aAAa,CAAS;IAC9B,QAAQ,gBAAa;IACrB,eAAe;IAUf,QAAQ,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAM;IACjC,UAAU,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAM;IACnC,iBAAiB,IAAI,IAAI;IAIzB,oBAAoB,IAAI,IAAI;IAG5B,qBAAqB,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO;IAYrD,MAAM;CAuCP;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,SAO9D"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,EACL,SAAS,EACT,KAAK,EAEN,MAAM,SAAS,CAAC;AAOjB,wBAAgB,mBAAmB,uBAMlC;AAED,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,QAMrC;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,QAMvC;AAED,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,IAClD,CAAC,MAAM,MAAM,KAAK,CAAC,GACnB,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,KAAK,CAAC,CAAC;AAEhC,cAAM,aAAa,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,CAAE,SAAQ,SAAS,CACzD,CAAC,GAAG;IAAE,WAAW,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAA;CAAE,CAC9C;IACC,OAAO,CAAC,QAAQ,CAAC,CAAc;IAC/B,OAAO,CAAC,aAAa,CAAC,CAAa;IACnC,OAAO,CAAC,QAAQ,CAEb;IACH,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAM;IAC3D,QAAQ,gBAAa;IACrB,eAAe;IAUf,QAAQ,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAM;IACjC,UAAU,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAM;IACnC,OAAO,CAAC,mBAAmB;IAgC3B,iBAAiB,IAAI,IAAI;IAGzB,oBAAoB,IAAI,IAAI;IAG5B;;OAEG;IACH,mBAAmB,CAAC,SAAS,EAAE,GAAG;IAYlC,yBAAyB,IAAI,IAAI;IACjC,qBAAqB,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO;IAerD,MAAM;CAyCP;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,SAO9D"}