cajoa 0.1.0 → 0.2.0

package/README.md

@@ -3,12 +3,12 @@
 A small, beginner-friendly frontend framework built on **signals**.
 No virtual DOM, no hooks rules, no re-rendering components.
 
-> ⚠️ **v0.1 (early stage).** The API will change. Not production-ready yet.
+> ⚠️ **v0.2 (early stage).** The API may still change. Not production-ready yet.
 
 ## Why Cajoa?
 
 - **Components run once.** A component is just a function that builds DOM. Only the parts that depend on a signal update.
-- **Tiny and readable.** The whole core is a few hundred lines you can read in one sitting.
+- **Tiny and readable.** The whole core is small enough to read in one sitting.
 - **TypeScript-first**, ESM + CommonJS, zero runtime dependencies.
 
 ## Install
@@ -39,26 +39,80 @@ render(Counter, document.getElementById("app")!);
 
 Passing `count` (the function itself, not `count()`) is what makes that part of the DOM reactive.
 
+## Lists and conditions
+
+```ts
+import { createSignal, h, Show, For } from "cajoa";
+
+const [todos, setTodos] = createSignal([{ id: 1, text: "Learn Cajoa" }]);
+
+h(
+  "div",
+  null,
+  Show({
+    when: () => todos().length > 0,
+    fallback: () => h("p", null, "Nothing to do."),
+    children: () =>
+      h(
+        "ul",
+        null,
+        For({
+          each: todos,
+          children: (todo) => h("li", null, todo.text),
+        }),
+      ),
+  }),
+);
+```
+
 ## API
 
-| Function                             | What it does                                                             |
-| ------------------------------------ | ------------------------------------------------------------------------ |
-| `createSignal(value)`                | Returns `[get, set]`. Reading `get()` inside an effect subscribes to it. |
-| `createEffect(fn)`                   | Runs `fn` now and again whenever a signal it read changes.               |
-| `h(tag, props, ...children)`         | Creates a real DOM element. Function props/children are reactive.        |
-| `render(component, container)`       | Mounts a component. Returns a `dispose` function.                        |
-| `Show({ when, children, fallback })` | Conditional rendering.                                                   |
-| `For({ each, children })`            | List rendering.                                                          |
-| `onMount(fn)`                        | Runs `fn` after the component is rendered.                               |
-| `onCleanup(fn)`                      | Runs `fn` before an effect re-runs or when its owner is disposed.        |
-| `createRoot(fn)`                     | Creates a top-level owner you can dispose manually.                      |
+### Reactivity
+
+| Function              | What it does                                                                                                           |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `createSignal(value)` | Returns `[get, set]`. Reading `get()` inside an effect subscribes to it. `set` accepts a value or an updater function. |
+| `createEffect(fn)`    | Runs `fn` now and again whenever a signal it read changes.                                                             |
+| `createMemo(fn)`      | Cached computed value. Only notifies when the result changes.                                                          |
+| `batch(fn)`           | Groups several `set` calls into one update.                                                                            |
+
+### DOM
+
+| Function                             | What it does                                                                           |
+| ------------------------------------ | -------------------------------------------------------------------------------------- |
+| `h(tag, props, ...children)`         | Creates a real DOM element. Function props/children are reactive.                      |
+| `render(component, container)`       | Mounts a component. Returns a `dispose` function.                                      |
+| `Show({ when, children, fallback })` | Conditional rendering.                                                                 |
+| `For({ each, children, key? })`      | List rendering. Reuses DOM nodes for unchanged items. `children` must return a `Node`. |
+
+### Lifecycle
+
+| Function         | What it does                                                      |
+| ---------------- | ----------------------------------------------------------------- |
+| `onMount(fn)`    | Runs `fn` after the component is rendered.                        |
+| `onCleanup(fn)`  | Runs `fn` before an effect re-runs or when its owner is disposed. |
+| `createRoot(fn)` | Creates a top-level owner you can dispose manually.               |
+
+### Context
+
+| Function                  | What it does                                           |
+| ------------------------- | ------------------------------------------------------ |
+| `createContext(default)`  | Creates a context with a default value.                |
+| `provide(ctx, value, fn)` | Runs `fn`; everything created inside can read `value`. |
+| `useContext(ctx)`         | Reads the nearest provided value (or the default).     |
+
+## Good to know
+
+- `For` uses the item itself as the key by default. If you pass `key`, items with the same key are **not** re-rendered when their data changes, so keys must be unique and the item should hold its own signals if it needs to update.
+- `useContext` only works while a component is being created (or inside `onMount` / effects). Read it at the top of your component and use the value later in handlers.
+- Updating an object in place will not trigger effects. Set a new object instead.
 
 ## Known limitations
 
-- `For` rebuilds the whole list on every change (keyed diffing is planned).
-- No `createMemo`, `batch`, or context yet.
 - No JSX support yet (`h()` only).
 - No SSR.
+- `createMemo` can show a brief inconsistent state when memos depend on each other.
+- `set` calls are not batched automatically inside event handlers. Wrap them in `batch()`.
 
 ## Roadmap
 
@@ -66,11 +120,12 @@ Passing `count` (the function itself, not `count()`) is what makes that part of
 - [x] DOM bindings (`h`, `render`)
 - [x] `Show`, `For`
 - [x] Lifecycle (`onMount`, `onCleanup`) and disposal
-- [ ] `createMemo`, `batch`
-- [ ] Keyed `For`
-- [ ] Context
+- [x] `createMemo`, `batch`
+- [x] Keyed `For`
+- [x] Context
 - [ ] JSX support
 - [ ] Router
+- [ ] SSR
 
 ## Development
 

package/dist/index.cjs

@@ -22,13 +22,18 @@ var index_exports = {};
 __export(index_exports, {
   For: () => For,
   Show: () => Show,
+  batch: () => batch,
+  createContext: () => createContext,
   createEffect: () => createEffect,
+  createMemo: () => createMemo,
   createRoot: () => createRoot,
   createSignal: () => createSignal,
   h: () => h,
   onCleanup: () => onCleanup,
   onMount: () => onMount,
-  render: () => render
+  provide: () => provide,
+  render: () => render,
+  useContext: () => useContext
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -45,6 +50,22 @@ function cleanComputation(c) {
   c.deps.clear();
   clean(c);
 }
+var batchDepth = 0;
+var pending = /* @__PURE__ */ new Set();
+function flush() {
+  const effects = [...pending];
+  pending.clear();
+  effects.forEach((effect) => effect.run());
+}
+function batch(fn) {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) flush();
+  }
+}
 function createSignal(value) {
   const subs = /* @__PURE__ */ new Set();
   const get = () => {
@@ -58,13 +79,18 @@ function createSignal(value) {
     const v = typeof next === "function" ? next(value) : next;
     if (Object.is(v, value)) return;
     value = v;
-    [...subs].forEach((effect) => effect.run());
+    for (const effect of [...subs]) {
+      if (batchDepth > 0)
+        pending.add(effect);
+      else effect.run();
+    }
   };
   return [get, set];
 }
 function createEffect(fn) {
   const effect = {
     cleanups: [],
+    parent: currentOwner,
     deps: /* @__PURE__ */ new Set(),
     disposed: false,
     run() {
@@ -92,7 +118,7 @@ function onCleanup(fn) {
   currentOwner?.cleanups.push(fn);
 }
 function createRoot(fn) {
-  const root = { cleanups: [] };
+  const root = { cleanups: [], parent: currentOwner };
   const prevOwner = currentOwner;
   const prevEffect = currentEffect;
   currentOwner = root;
@@ -119,6 +145,30 @@ function onMount(fn) {
     }
   });
 }
+function createContext(defaultValue) {
+  return { id: /* @__PURE__ */ Symbol("cajoa-context"), defaultValue };
+}
+function provide(ctx, value, fn) {
+  const owner = {
+    cleanups: [],
+    parent: currentOwner,
+    context: /* @__PURE__ */ new Map([[ctx.id, value]])
+  };
+  onCleanup(() => clean(owner));
+  const prev = currentOwner;
+  currentOwner = owner;
+  try {
+    return fn();
+  } finally {
+    currentOwner = prev;
+  }
+}
+function useContext(ctx) {
+  for (let o = currentOwner; o; o = o.parent) {
+    if (o.context?.has(ctx.id)) return o.context.get(ctx.id);
+  }
+  return ctx.defaultValue;
+}
 
 // src/dom/h.ts
 function h(tag, props, ...children) {
@@ -152,12 +202,12 @@ function toNodes(value) {
   return out;
 }
 function appendChildren(parent, children) {
-  const pending = [...children].reverse();
-  while (pending.length > 0) {
-    const child = pending.pop();
+  const pending2 = [...children].reverse();
+  while (pending2.length > 0) {
+    const child = pending2.pop();
     if (Array.isArray(child)) {
       for (let i = child.length - 1; i >= 0; i--) {
-        pending.push(child[i]);
+        pending2.push(child[i]);
       }
       continue;
     }
@@ -166,17 +216,29 @@ function appendChildren(parent, children) {
       const end = document.createComment("");
       parent.append(start, end);
       createEffect(() => {
-        const nodes = toNodes(child());
-        while (start.nextSibling && start.nextSibling !== end) {
-          start.nextSibling.remove();
-        }
-        end.before(...nodes);
+        reconcile(start, end, toNodes(child()));
       });
     } else {
       parent.append(...toNodes(child));
     }
   }
 }
+function reconcile(start, end, next) {
+  const keep = new Set(next);
+  let cur = start.nextSibling;
+  while (cur && cur !== end) {
+    const after = cur.nextSibling;
+    if (!keep.has(cur)) cur.remove();
+    cur = after;
+  }
+  const parent = end.parentNode;
+  let ref = start.nextSibling;
+  for (const node of next) {
+    if (node === ref)
+      ref = ref.nextSibling;
+    else parent.insertBefore(node, ref);
+  }
+}
 
 // src/dom/render.ts
 function render(component, container) {
@@ -196,17 +258,55 @@ function Show(props) {
 
 // src/components/for.ts
 function For(props) {
-  return () => props.each().map((item, i) => props.children(item, i));
+  let cache = /* @__PURE__ */ new Map();
+  onCleanup(() => {
+    cache.forEach((e) => e.dispose());
+    cache.clear();
+  });
+  return () => {
+    const items = props.each();
+    const next = /* @__PURE__ */ new Map();
+    const nodes = [];
+    items.forEach((item, i) => {
+      const k = props.key ? props.key(item, i) : item;
+      let entry = cache.get(k);
+      if (!entry) {
+        entry = createRoot((dispose) => ({
+          node: props.children(item, i),
+          dispose
+        }));
+      }
+      next.set(k, entry);
+      nodes.push(entry.node);
+    });
+    cache.forEach((entry, k) => {
+      if (!next.has(k)) entry.dispose();
+    });
+    cache = next;
+    return nodes;
+  };
+}
+
+// src/reactivity/memo.ts
+function createMemo(fn) {
+  const [value, setValue] = createSignal(void 0);
+  createEffect(() => setValue(() => fn()));
+  return value;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   For,
   Show,
+  batch,
+  createContext,
   createEffect,
+  createMemo,
   createRoot,
   createSignal,
   h,
   onCleanup,
   onMount,
-  render
+  provide,
+  render,
+  useContext
 });

package/dist/index.d.cts

@@ -1,9 +1,17 @@
 type Cleanup = () => void;
+declare function batch<T>(fn: () => T): T;
 declare function createSignal<T>(value: T): readonly [() => T, (next: T | ((prev: T) => T)) => void];
 declare function createEffect(fn: () => void): void;
 declare function onCleanup(fn: Cleanup): void;
 declare function createRoot<T>(fn: (dispose: () => void) => T): T;
 declare function onMount(fn: () => void): void;
+interface Context<T> {
+    readonly id: symbol;
+    readonly defaultValue: T;
+}
+declare function createContext<T>(defaultValue: T): Context<T>;
+declare function provide<T, R>(ctx: Context<T>, value: T, fn: () => R): R;
+declare function useContext<T>(ctx: Context<T>): T;
 
 type Child = string | number | boolean | null | undefined | Node | (() => unknown) | Child[];
 declare function h(tag: string, props: Record<string, any> | null, ...children: Child[]): HTMLElement;
@@ -18,8 +26,11 @@ declare function Show<T>(props: {
 
 declare function For<T>(props: {
     each: () => T[];
-    children: (item: T, index: number) => Child;
-}): () => Child[];
+    children: (item: T, index: number) => Node;
+    key?: (item: T, index: number) => unknown;
+}): () => Node[];
 
-export { For, Show, createEffect, createRoot, createSignal, h, onCleanup, onMount, render };
-export type { Child };
+declare function createMemo<T>(fn: () => T): () => T;
+
+export { For, Show, batch, createContext, createEffect, createMemo, createRoot, createSignal, h, onCleanup, onMount, provide, render, useContext };
+export type { Child, Context };

package/dist/index.d.ts

@@ -1,9 +1,17 @@
 type Cleanup = () => void;
+declare function batch<T>(fn: () => T): T;
 declare function createSignal<T>(value: T): readonly [() => T, (next: T | ((prev: T) => T)) => void];
 declare function createEffect(fn: () => void): void;
 declare function onCleanup(fn: Cleanup): void;
 declare function createRoot<T>(fn: (dispose: () => void) => T): T;
 declare function onMount(fn: () => void): void;
+interface Context<T> {
+    readonly id: symbol;
+    readonly defaultValue: T;
+}
+declare function createContext<T>(defaultValue: T): Context<T>;
+declare function provide<T, R>(ctx: Context<T>, value: T, fn: () => R): R;
+declare function useContext<T>(ctx: Context<T>): T;
 
 type Child = string | number | boolean | null | undefined | Node | (() => unknown) | Child[];
 declare function h(tag: string, props: Record<string, any> | null, ...children: Child[]): HTMLElement;
@@ -18,8 +26,11 @@ declare function Show<T>(props: {
 
 declare function For<T>(props: {
     each: () => T[];
-    children: (item: T, index: number) => Child;
-}): () => Child[];
+    children: (item: T, index: number) => Node;
+    key?: (item: T, index: number) => unknown;
+}): () => Node[];
 
-export { For, Show, createEffect, createRoot, createSignal, h, onCleanup, onMount, render };
-export type { Child };
+declare function createMemo<T>(fn: () => T): () => T;
+
+export { For, Show, batch, createContext, createEffect, createMemo, createRoot, createSignal, h, onCleanup, onMount, provide, render, useContext };
+export type { Child, Context };

package/dist/index.js

@@ -11,6 +11,22 @@ function cleanComputation(c) {
   c.deps.clear();
   clean(c);
 }
+var batchDepth = 0;
+var pending = /* @__PURE__ */ new Set();
+function flush() {
+  const effects = [...pending];
+  pending.clear();
+  effects.forEach((effect) => effect.run());
+}
+function batch(fn) {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) flush();
+  }
+}
 function createSignal(value) {
   const subs = /* @__PURE__ */ new Set();
   const get = () => {
@@ -24,13 +40,18 @@ function createSignal(value) {
     const v = typeof next === "function" ? next(value) : next;
     if (Object.is(v, value)) return;
     value = v;
-    [...subs].forEach((effect) => effect.run());
+    for (const effect of [...subs]) {
+      if (batchDepth > 0)
+        pending.add(effect);
+      else effect.run();
+    }
   };
   return [get, set];
 }
 function createEffect(fn) {
   const effect = {
     cleanups: [],
+    parent: currentOwner,
     deps: /* @__PURE__ */ new Set(),
     disposed: false,
     run() {
@@ -58,7 +79,7 @@ function onCleanup(fn) {
   currentOwner?.cleanups.push(fn);
 }
 function createRoot(fn) {
-  const root = { cleanups: [] };
+  const root = { cleanups: [], parent: currentOwner };
   const prevOwner = currentOwner;
   const prevEffect = currentEffect;
   currentOwner = root;
@@ -85,6 +106,30 @@ function onMount(fn) {
     }
   });
 }
+function createContext(defaultValue) {
+  return { id: /* @__PURE__ */ Symbol("cajoa-context"), defaultValue };
+}
+function provide(ctx, value, fn) {
+  const owner = {
+    cleanups: [],
+    parent: currentOwner,
+    context: /* @__PURE__ */ new Map([[ctx.id, value]])
+  };
+  onCleanup(() => clean(owner));
+  const prev = currentOwner;
+  currentOwner = owner;
+  try {
+    return fn();
+  } finally {
+    currentOwner = prev;
+  }
+}
+function useContext(ctx) {
+  for (let o = currentOwner; o; o = o.parent) {
+    if (o.context?.has(ctx.id)) return o.context.get(ctx.id);
+  }
+  return ctx.defaultValue;
+}
 
 // src/dom/h.ts
 function h(tag, props, ...children) {
@@ -118,12 +163,12 @@ function toNodes(value) {
   return out;
 }
 function appendChildren(parent, children) {
-  const pending = [...children].reverse();
-  while (pending.length > 0) {
-    const child = pending.pop();
+  const pending2 = [...children].reverse();
+  while (pending2.length > 0) {
+    const child = pending2.pop();
     if (Array.isArray(child)) {
       for (let i = child.length - 1; i >= 0; i--) {
-        pending.push(child[i]);
+        pending2.push(child[i]);
       }
       continue;
     }
@@ -132,17 +177,29 @@ function appendChildren(parent, children) {
       const end = document.createComment("");
       parent.append(start, end);
       createEffect(() => {
-        const nodes = toNodes(child());
-        while (start.nextSibling && start.nextSibling !== end) {
-          start.nextSibling.remove();
-        }
-        end.before(...nodes);
+        reconcile(start, end, toNodes(child()));
       });
     } else {
       parent.append(...toNodes(child));
     }
   }
 }
+function reconcile(start, end, next) {
+  const keep = new Set(next);
+  let cur = start.nextSibling;
+  while (cur && cur !== end) {
+    const after = cur.nextSibling;
+    if (!keep.has(cur)) cur.remove();
+    cur = after;
+  }
+  const parent = end.parentNode;
+  let ref = start.nextSibling;
+  for (const node of next) {
+    if (node === ref)
+      ref = ref.nextSibling;
+    else parent.insertBefore(node, ref);
+  }
+}
 
 // src/dom/render.ts
 function render(component, container) {
@@ -162,16 +219,54 @@ function Show(props) {
 
 // src/components/for.ts
 function For(props) {
-  return () => props.each().map((item, i) => props.children(item, i));
+  let cache = /* @__PURE__ */ new Map();
+  onCleanup(() => {
+    cache.forEach((e) => e.dispose());
+    cache.clear();
+  });
+  return () => {
+    const items = props.each();
+    const next = /* @__PURE__ */ new Map();
+    const nodes = [];
+    items.forEach((item, i) => {
+      const k = props.key ? props.key(item, i) : item;
+      let entry = cache.get(k);
+      if (!entry) {
+        entry = createRoot((dispose) => ({
+          node: props.children(item, i),
+          dispose
+        }));
+      }
+      next.set(k, entry);
+      nodes.push(entry.node);
+    });
+    cache.forEach((entry, k) => {
+      if (!next.has(k)) entry.dispose();
+    });
+    cache = next;
+    return nodes;
+  };
+}
+
+// src/reactivity/memo.ts
+function createMemo(fn) {
+  const [value, setValue] = createSignal(void 0);
+  createEffect(() => setValue(() => fn()));
+  return value;
 }
 export {
   For,
   Show,
+  batch,
+  createContext,
   createEffect,
+  createMemo,
   createRoot,
   createSignal,
   h,
   onCleanup,
   onMount,
-  render
+  provide,
+  render,
+  useContext
 };

package/package.json

@@ -1,57 +1,57 @@
-{
-  "name": "cajoa",
-  "version": "0.1.0",
-  "description": "A beginner-friendly, signals-based frontend framework.",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "sideEffects": false,
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "dev": "vite --open /playground/",
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "test": "vitest",
-    "prepublishOnly": "vitest run && npm run build"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/cjmgrc/Cajoa.git"
-  },
-  "keywords": [
-    "frontend",
-    "framework",
-    "signals",
-    "reactive",
-    "ui",
-    "cajoa"
-  ],
-  "author": "cjmgrc",
-  "license": "Apache-2.0",
-  "bugs": {
-    "url": "https://github.com/cjmgrc/Cajoa/issues"
-  },
-  "homepage": "https://github.com/cjmgrc/Cajoa#readme",
-  "devDependencies": {
-    "jsdom": "^29.1.1",
-    "tsup": "^9.0.0",
-    "typescript": "^5.9.3",
-    "vite": "^8.3.4",
-    "vitest": "^5.0.5"
-  }
-}
+{
+  "name": "cajoa",
+  "version": "0.2.0",
+  "description": "A beginner-friendly, signals-based frontend framework.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "dev": "vite --open /playground/",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest",
+    "prepublishOnly": "vitest run && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cjmgrc/Cajoa.git"
+  },
+  "keywords": [
+    "frontend",
+    "framework",
+    "signals",
+    "reactive",
+    "ui",
+    "cajoa"
+  ],
+  "author": "cjmgrc",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/cjmgrc/Cajoa/issues"
+  },
+  "homepage": "https://github.com/cjmgrc/Cajoa#readme",
+  "devDependencies": {
+    "jsdom": "^29.1.1",
+    "tsup": "^9.0.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.5"
+  }
+}