cajoa 0.4.0 → 0.5.0

package/README.md

@@ -3,7 +3,7 @@
 A small, beginner-friendly frontend framework built on **signals** and **JSX**.
 No virtual DOM, no hooks rules, no re-rendering components.
 
-> ⚠️ **v0.4 (early stage).** The API may still change. Not production-ready yet.
+> ⚠️ **v0.5 (early stage).** The API may still change. Not production-ready yet.
 
 ## Why Cajoa?
 
@@ -15,7 +15,7 @@ No virtual DOM, no hooks rules, no re-rendering components.
 ## Install
 
 ```bash
-npm install cajoa
+npm create cajoa@latest my-app
 ```
 
 ## Setup (JSX)
@@ -159,6 +159,14 @@ Routes are matched in order, so put `path="*"` last.
 | `usePath()`                  | Returns a signal getter for the current pathname.          |
 | `untrack(fn)`                | Runs `fn` without subscribing to signals.                  |
 
+### Renderer
+
+| Function                | What it does                                                       |
+| ----------------------- | ------------------------------------------------------------------ |
+| `setRenderer(renderer)` | Swaps the renderer (default: DOM). Used to target other platforms. |
+| `getRenderer()`         | Returns the current renderer.                                      |
+| `domRenderer`           | The built-in DOM renderer.                                         |
+
 ## 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.
@@ -174,6 +182,7 @@ Routes are matched in order, so put `path="*"` last.
 - Single-page apps need a server fallback to `index.html` for unknown paths.
 - `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()`.
+- The Router and event names (`onClick`) are still web-specific for now.
 
 ## Roadmap
 
@@ -185,8 +194,11 @@ Routes are matched in order, so put `path="*"` last.
 - [x] Context
 - [x] JSX support
 - [x] Fragments
-- [ ] Vite plugin (removes the two rules above)
 - [x] Router
+- [x] Renderer abstraction (core no longer depends on DOM)
+- [ ] Split into packages ('@cajoa/core', '@cajoa/dom')
+- [ ] Vite plugin (removes the two rules above)
+- [ ] Native renderer (mobile, desktop)
 - [ ] SSR
 
 ## Development

package/dist/index.cjs

@@ -32,6 +32,8 @@ __export(index_exports, {
   createMemo: () => createMemo,
   createRoot: () => createRoot,
   createSignal: () => createSignal,
+  domRenderer: () => domRenderer,
+  getRenderer: () => getRenderer,
   h: () => h,
   jsx: () => jsx,
   jsxDEV: () => jsxDEV,
@@ -41,6 +43,7 @@ __export(index_exports, {
   onMount: () => onMount,
   provide: () => provide,
   render: () => render,
+  setRenderer: () => setRenderer,
   untrack: () => untrack,
   useContext: () => useContext,
   useParams: () => useParams,
@@ -190,83 +193,109 @@ function untrack(fn) {
   }
 }
 
+// src/renderer/dom.ts
+var domRenderer = {
+  createElement: (tag) => document.createElement(tag),
+  createText: (value) => document.createTextNode(value),
+  createMarker: () => document.createComment(""),
+  createFragment: () => document.createDocumentFragment(),
+  isNode: (v) => typeof Node !== "undefined" && v instanceof Node,
+  insert: (parent, node, anchor = null) => {
+    parent.insertBefore(node, anchor);
+  },
+  remove: (node) => {
+    node.remove();
+  },
+  nextSibling: (node) => node.nextSibling,
+  parentNode: (node) => node.parentNode,
+  clear: (parent) => {
+    parent.replaceChildren();
+  },
+  setProp(el, key, value) {
+    const e = el;
+    if (key.startsWith("on") && typeof value === "function") {
+      e.addEventListener(key.slice(2).toLowerCase(), value);
+      return;
+    }
+    const name = key === "className" ? "class" : key;
+    if (value == null || value === false) e.removeAttribute(name);
+    else e.setAttribute(name, value === true ? "" : String(value));
+  }
+};
+
+// src/renderer/index.ts
+var current = domRenderer;
+function setRenderer(renderer) {
+  current = renderer;
+}
+function getRenderer() {
+  return current;
+}
+
 // src/dom/h.ts
 function h(tag, props, ...children) {
-  const el = document.createElement(tag);
+  const r = getRenderer();
+  const el = r.createElement(tag);
   for (const [key, value] of Object.entries(props ?? {})) {
-    setProp(el, key, value);
+    if (typeof value === "function" && !key.startsWith("on")) {
+      createEffect(() => r.setProp(el, key, value()));
+    } else {
+      r.setProp(el, key, value);
+    }
   }
   appendChildren(el, children);
   return el;
 }
-function setProp(el, key, value) {
-  if (key.startsWith("on") && typeof value === "function") {
-    el.addEventListener(key.slice(2).toLowerCase(), value);
-  } else if (typeof value === "function") {
-    createEffect(() => applyAttr(el, key, value()));
-  } else {
-    applyAttr(el, key, value);
-  }
-}
-function applyAttr(el, key, value) {
-  const name = key === "className" ? "class" : key;
-  if (value == null || value === false) el.removeAttribute(name);
-  else el.setAttribute(name, value === true ? "" : String(value));
-}
 function toNodes(value) {
+  const r = getRenderer();
   const out = [];
   for (const v of [value].flat(Infinity)) {
     if (v == null || typeof v === "boolean") continue;
-    out.push(v instanceof Node ? v : document.createTextNode(String(v)));
+    out.push(r.isNode(v) ? v : r.createText(String(v)));
   }
   return out;
 }
-function appendChildren(parent, children) {
-  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--) {
-        pending2.push(child[i]);
-      }
-      continue;
-    }
-    if (typeof child === "function") {
-      const start = document.createComment("");
-      const end = document.createComment("");
-      parent.append(start, end);
-      createEffect(() => {
-        reconcile(start, end, toNodes(child()));
-      });
-    } else {
-      parent.append(...toNodes(child));
-    }
-  }
-}
 function reconcile(start, end, next) {
+  const r = getRenderer();
   const keep = new Set(next);
-  let cur = start.nextSibling;
+  let cur = r.nextSibling(start);
   while (cur && cur !== end) {
-    const after = cur.nextSibling;
-    if (!keep.has(cur)) cur.remove();
+    const after = r.nextSibling(cur);
+    if (!keep.has(cur)) r.remove(cur);
     cur = after;
   }
-  const parent = end.parentNode;
-  let ref = start.nextSibling;
+  const parent = r.parentNode(end);
+  let ref = r.nextSibling(start);
   for (const node of next) {
-    if (node === ref)
-      ref = ref.nextSibling;
-    else parent.insertBefore(node, ref);
+    if (node === ref) ref = r.nextSibling(ref);
+    else r.insert(parent, node, ref);
+  }
+}
+function appendChildren(parent, children) {
+  const r = getRenderer();
+  for (const child of children.flat(Infinity)) {
+    if (typeof child === "function") {
+      const start = r.createMarker();
+      const end = r.createMarker();
+      r.insert(parent, start);
+      r.insert(parent, end);
+      createEffect(() => reconcile(start, end, toNodes(child())));
+    } else {
+      for (const node of toNodes(child)) r.insert(parent, node);
+    }
   }
 }
 
 // src/dom/render.ts
 function render(component, container) {
   return createRoot((dispose) => {
-    container.replaceChildren(component());
+    const r = getRenderer();
+    const node = component();
+    r.clear(container);
+    r.insert(container, node);
     return () => {
       dispose();
-      container.replaceChildren();
+      r.clear(container);
     };
   });
 }
@@ -325,7 +354,7 @@ function jsx(type, props) {
 var jsxs = jsx;
 var jsxDEV = jsx;
 function Fragment(props) {
-  const frag = document.createDocumentFragment();
+  const frag = getRenderer().createFragment();
   appendChildren(frag, props.children === void 0 ? [] : [props.children]);
   return frag;
 }
@@ -378,9 +407,9 @@ function Router(props) {
     (r) => r?.__route === true
   );
   return () => {
-    const current = path();
+    const current2 = path();
     for (const route of routes) {
-      const params = match(route.path, current);
+      const params = match(route.path, current2);
       if (params) {
         return untrack(() => provide(Params, params, () => route.component()));
       }
@@ -413,6 +442,8 @@ function Link(props) {
   createMemo,
   createRoot,
   createSignal,
+  domRenderer,
+  getRenderer,
   h,
   jsx,
   jsxDEV,
@@ -422,6 +453,7 @@ function Link(props) {
   onMount,
   provide,
   render,
+  setRenderer,
   untrack,
   useContext,
   useParams,

package/dist/index.d.cts

@@ -47,7 +47,7 @@ declare namespace JSX {
 }
 declare function Fragment(props: {
     children?: Child;
-}): DocumentFragment;
+}): any;
 
 declare function navigate(to: string, options?: {
     replace?: boolean;
@@ -72,5 +72,24 @@ declare function Link(props: {
     [key: string]: unknown;
 }): HTMLElement;
 
-export { For, Fragment, JSX, Link, Route, Router, Show, batch, createContext, createEffect, createMemo, createRoot, createSignal, h, jsx, jsxDEV, jsxs, navigate, onCleanup, onMount, provide, render, untrack, useContext, useParams, usePath };
-export type { Child, Context, RouteDef };
+interface Renderer<N = any> {
+    createElement(tag: string): N;
+    createText(value: string): N;
+    createMarker(): N;
+    createFragment(): N;
+    isNode(value: unknown): value is N;
+    insert(parent: N, node: N, anchor?: N | null): void;
+    remove(node: N): void;
+    nextSibling(node: N): N | null;
+    parentNode(node: N): N | null;
+    clear(parent: N): void;
+    setProp(el: N, name: string, value: unknown): void;
+}
+
+declare function setRenderer(renderer: Renderer): void;
+declare function getRenderer(): Renderer;
+
+declare const domRenderer: Renderer<Node>;
+
+export { For, Fragment, JSX, Link, Route, Router, Show, batch, createContext, createEffect, createMemo, createRoot, createSignal, domRenderer, getRenderer, h, jsx, jsxDEV, jsxs, navigate, onCleanup, onMount, provide, render, setRenderer, untrack, useContext, useParams, usePath };
+export type { Child, Context, Renderer, RouteDef };

package/dist/index.d.ts

@@ -47,7 +47,7 @@ declare namespace JSX {
 }
 declare function Fragment(props: {
     children?: Child;
-}): DocumentFragment;
+}): any;
 
 declare function navigate(to: string, options?: {
     replace?: boolean;
@@ -72,5 +72,24 @@ declare function Link(props: {
     [key: string]: unknown;
 }): HTMLElement;
 
-export { For, Fragment, JSX, Link, Route, Router, Show, batch, createContext, createEffect, createMemo, createRoot, createSignal, h, jsx, jsxDEV, jsxs, navigate, onCleanup, onMount, provide, render, untrack, useContext, useParams, usePath };
-export type { Child, Context, RouteDef };
+interface Renderer<N = any> {
+    createElement(tag: string): N;
+    createText(value: string): N;
+    createMarker(): N;
+    createFragment(): N;
+    isNode(value: unknown): value is N;
+    insert(parent: N, node: N, anchor?: N | null): void;
+    remove(node: N): void;
+    nextSibling(node: N): N | null;
+    parentNode(node: N): N | null;
+    clear(parent: N): void;
+    setProp(el: N, name: string, value: unknown): void;
+}
+
+declare function setRenderer(renderer: Renderer): void;
+declare function getRenderer(): Renderer;
+
+declare const domRenderer: Renderer<Node>;
+
+export { For, Fragment, JSX, Link, Route, Router, Show, batch, createContext, createEffect, createMemo, createRoot, createSignal, domRenderer, getRenderer, h, jsx, jsxDEV, jsxs, navigate, onCleanup, onMount, provide, render, setRenderer, untrack, useContext, useParams, usePath };
+export type { Child, Context, Renderer, RouteDef };

package/dist/index.js

@@ -140,83 +140,109 @@ function untrack(fn) {
   }
 }
 
+// src/renderer/dom.ts
+var domRenderer = {
+  createElement: (tag) => document.createElement(tag),
+  createText: (value) => document.createTextNode(value),
+  createMarker: () => document.createComment(""),
+  createFragment: () => document.createDocumentFragment(),
+  isNode: (v) => typeof Node !== "undefined" && v instanceof Node,
+  insert: (parent, node, anchor = null) => {
+    parent.insertBefore(node, anchor);
+  },
+  remove: (node) => {
+    node.remove();
+  },
+  nextSibling: (node) => node.nextSibling,
+  parentNode: (node) => node.parentNode,
+  clear: (parent) => {
+    parent.replaceChildren();
+  },
+  setProp(el, key, value) {
+    const e = el;
+    if (key.startsWith("on") && typeof value === "function") {
+      e.addEventListener(key.slice(2).toLowerCase(), value);
+      return;
+    }
+    const name = key === "className" ? "class" : key;
+    if (value == null || value === false) e.removeAttribute(name);
+    else e.setAttribute(name, value === true ? "" : String(value));
+  }
+};
+
+// src/renderer/index.ts
+var current = domRenderer;
+function setRenderer(renderer) {
+  current = renderer;
+}
+function getRenderer() {
+  return current;
+}
+
 // src/dom/h.ts
 function h(tag, props, ...children) {
-  const el = document.createElement(tag);
+  const r = getRenderer();
+  const el = r.createElement(tag);
   for (const [key, value] of Object.entries(props ?? {})) {
-    setProp(el, key, value);
+    if (typeof value === "function" && !key.startsWith("on")) {
+      createEffect(() => r.setProp(el, key, value()));
+    } else {
+      r.setProp(el, key, value);
+    }
   }
   appendChildren(el, children);
   return el;
 }
-function setProp(el, key, value) {
-  if (key.startsWith("on") && typeof value === "function") {
-    el.addEventListener(key.slice(2).toLowerCase(), value);
-  } else if (typeof value === "function") {
-    createEffect(() => applyAttr(el, key, value()));
-  } else {
-    applyAttr(el, key, value);
-  }
-}
-function applyAttr(el, key, value) {
-  const name = key === "className" ? "class" : key;
-  if (value == null || value === false) el.removeAttribute(name);
-  else el.setAttribute(name, value === true ? "" : String(value));
-}
 function toNodes(value) {
+  const r = getRenderer();
   const out = [];
   for (const v of [value].flat(Infinity)) {
     if (v == null || typeof v === "boolean") continue;
-    out.push(v instanceof Node ? v : document.createTextNode(String(v)));
+    out.push(r.isNode(v) ? v : r.createText(String(v)));
   }
   return out;
 }
-function appendChildren(parent, children) {
-  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--) {
-        pending2.push(child[i]);
-      }
-      continue;
-    }
-    if (typeof child === "function") {
-      const start = document.createComment("");
-      const end = document.createComment("");
-      parent.append(start, end);
-      createEffect(() => {
-        reconcile(start, end, toNodes(child()));
-      });
-    } else {
-      parent.append(...toNodes(child));
-    }
-  }
-}
 function reconcile(start, end, next) {
+  const r = getRenderer();
   const keep = new Set(next);
-  let cur = start.nextSibling;
+  let cur = r.nextSibling(start);
   while (cur && cur !== end) {
-    const after = cur.nextSibling;
-    if (!keep.has(cur)) cur.remove();
+    const after = r.nextSibling(cur);
+    if (!keep.has(cur)) r.remove(cur);
     cur = after;
   }
-  const parent = end.parentNode;
-  let ref = start.nextSibling;
+  const parent = r.parentNode(end);
+  let ref = r.nextSibling(start);
   for (const node of next) {
-    if (node === ref)
-      ref = ref.nextSibling;
-    else parent.insertBefore(node, ref);
+    if (node === ref) ref = r.nextSibling(ref);
+    else r.insert(parent, node, ref);
+  }
+}
+function appendChildren(parent, children) {
+  const r = getRenderer();
+  for (const child of children.flat(Infinity)) {
+    if (typeof child === "function") {
+      const start = r.createMarker();
+      const end = r.createMarker();
+      r.insert(parent, start);
+      r.insert(parent, end);
+      createEffect(() => reconcile(start, end, toNodes(child())));
+    } else {
+      for (const node of toNodes(child)) r.insert(parent, node);
+    }
   }
 }
 
 // src/dom/render.ts
 function render(component, container) {
   return createRoot((dispose) => {
-    container.replaceChildren(component());
+    const r = getRenderer();
+    const node = component();
+    r.clear(container);
+    r.insert(container, node);
     return () => {
       dispose();
-      container.replaceChildren();
+      r.clear(container);
     };
   });
 }
@@ -275,7 +301,7 @@ function jsx(type, props) {
 var jsxs = jsx;
 var jsxDEV = jsx;
 function Fragment(props) {
-  const frag = document.createDocumentFragment();
+  const frag = getRenderer().createFragment();
   appendChildren(frag, props.children === void 0 ? [] : [props.children]);
   return frag;
 }
@@ -328,9 +354,9 @@ function Router(props) {
     (r) => r?.__route === true
   );
   return () => {
-    const current = path();
+    const current2 = path();
     for (const route of routes) {
-      const params = match(route.path, current);
+      const params = match(route.path, current2);
       if (params) {
         return untrack(() => provide(Params, params, () => route.component()));
       }
@@ -362,6 +388,8 @@ export {
   createMemo,
   createRoot,
   createSignal,
+  domRenderer,
+  getRenderer,
   h,
   jsx,
   jsxDEV,
@@ -371,6 +399,7 @@ export {
   onMount,
   provide,
   render,
+  setRenderer,
   untrack,
   useContext,
   useParams,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cajoa",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A beginner-friendly, signals-based frontend framework.",
   "type": "module",
   "main": "./dist/index.cjs",