cajoa 0.2.0 → 0.4.0

package/README.md

@@ -1,13 +1,14 @@
 # Cajoa
 
-A small, beginner-friendly frontend framework built on **signals**.
+A small, beginner-friendly frontend framework built on **signals** and **JSX**.
 No virtual DOM, no hooks rules, no re-rendering components.
 
-> ⚠️ **v0.2 (early stage).** The API may still change. Not production-ready yet.
+> ⚠️ **v0.4 (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.
+- **Plain JSX.** Write `<button onClick={...}>`, no special syntax to learn.
 - **Tiny and readable.** The whole core is small enough to read in one sitting.
 - **TypeScript-first**, ESM + CommonJS, zero runtime dependencies.
 
@@ -17,54 +18,94 @@ No virtual DOM, no hooks rules, no re-rendering components.
 npm install cajoa
 ```
 
+## Setup (JSX)
+
+In your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "cajoa"
+  }
+}
+```
+
+If you use Vite and your JSX is not transformed, also set it in `vite.config.ts`
+(`oxc: { jsx: { runtime: "automatic", importSource: "cajoa" } }` on newer Vite,
+or `esbuild: { jsx: "automatic", jsxImportSource: "cajoa" }` on older ones).
+
 ## Quick start
 
-```ts
-import { createSignal, h, render } from "cajoa";
+```tsx
+import { createSignal, render } from "cajoa";
 
 function Counter() {
   const [count, setCount] = createSignal(0);
 
-  return h(
-    "button",
-    { onClick: () => setCount((c) => c + 1) },
-    "Clicked ",
-    count,
-    " times",
+  return (
+    <button onClick={() => setCount((c) => c + 1)}>
+      Clicked {count} times
+    </button>
   );
 }
 
 render(Counter, document.getElementById("app")!);
 ```
 
-Passing `count` (the function itself, not `count()`) is what makes that part of the DOM reactive.
+## Two rules to remember
+
+Cajoa has no compiler, so JSX expressions run exactly once. That gives two rules:
+
+1. **Pass the signal, don't call it.**
+   `{count}` is reactive. `{count()}` is read once and never updates.
+   For computed values, pass a function: `{() => count() * 2}`.
+2. **`Show` children are a function.**
+   `<Show when={on}>{() => <p>Hello</p>}</Show>`
+   Otherwise the element is created even when it is hidden.
 
 ## Lists and conditions
 
-```ts
-import { createSignal, h, Show, For } from "cajoa";
+```tsx
+import { createSignal, 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),
-        }),
-      ),
-  }),
+<Show when={() => todos().length > 0} fallback={() => <p>Nothing to do.</p>}>
+  {() => (
+    <ul>
+      <For each={todos}>{(todo) => <li>{todo.text}</li>}</For>
+    </ul>
+  )}
+</Show>;
+```
+
+## Routing
+
+```tsx
+import { render, Router, Route, Link, useParams } from "cajoa";
+
+const User = () => <h1>User {useParams().id}</h1>;
+
+render(
+  () => (
+    <div>
+      <nav>
+        <Link href="/">Home</Link> <Link href="/users/7">User 7</Link>
+      </nav>
+      <Router>
+        <Route path="/" component={() => <h1>Home</h1>} />
+        <Route path="/users/:id" component={User} />
+        <Route path="*" component={() => <h1>Not found</h1>} />
+      </Router>
+    </div>
+  ),
+  document.getElementById("app")!,
 );
 ```
 
+Routes are matched in order, so put `path="*"` last.
+
 ## API
 
 ### Reactivity
@@ -76,14 +117,19 @@ h(
 | `createMemo(fn)`      | Cached computed value. Only notifies when the result changes.                                                          |
 | `batch(fn)`           | Groups several `set` calls into one update.                                                                            |
 
-### DOM
+### Components
+
+| Component              | What it does                                                                                         |
+| ---------------------- | ---------------------------------------------------------------------------------------------------- |
+| `<Show when fallback>` | Conditional rendering. `children` and `fallback` are functions.                                      |
+| `<For each key?>`      | List rendering. Reuses DOM nodes for unchanged items. The child is a function that returns a `Node`. |
 
-| 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`. |
+### Rendering
+
+| Function                       | What it does                                      |
+| ------------------------------ | ------------------------------------------------- |
+| `render(component, container)` | Mounts a component. Returns a `dispose` function. |
+| `h(tag, props, ...children)`   | Low-level element creator. JSX compiles to this.  |
 
 ### Lifecycle
 
@@ -101,30 +147,46 @@ h(
 | `provide(ctx, value, fn)` | Runs `fn`; everything created inside can read `value`. |
 | `useContext(ctx)`         | Reads the nearest provided value (or the default).     |
 
+### Router
+
+| Function                     | What it does                                               |
+| ---------------------------- | ---------------------------------------------------------- |
+| `<Router>`                   | Renders the first `<Route>` that matches the current path. |
+| `<Route path component>`     | Maps a path (`/users/:id`, `*`) to a component.            |
+| `<Link href>`                | An `<a>` that navigates without reloading the page.        |
+| `navigate(to, { replace? })` | Navigates programmatically.                                |
+| `useParams()`                | Reads the route params (`{ id: "7" }`).                    |
+| `usePath()`                  | Returns a signal getter for the current pathname.          |
+| `untrack(fn)`                | Runs `fn` without subscribing to signals.                  |
+
 ## 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.
+- Fragments (`<>...</>`) work anywhere, but inside `<For>` the child must be a single element, because `For` reuses that node.
 
 ## Known limitations
 
-- No JSX support yet (`h()` only).
 - No SSR.
+- Router: pathname only (no query/hash handling), no nested routes, no `base` path.
+- `<Show>` and `<Router>` return a function, so they must sit inside an element, not be the root returned by `render`.
+- 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()`.
 
 ## Roadmap
 
 - [x] Signals and effects
-- [x] DOM bindings (`h`, `render`)
-- [x] `Show`, `For`
-- [x] Lifecycle (`onMount`, `onCleanup`) and disposal
+- [x] DOM bindings and `render`
+- [x] `Show`, `For` (keyed)
+- [x] Lifecycle and disposal
 - [x] `createMemo`, `batch`
-- [x] Keyed `For`
 - [x] Context
-- [ ] JSX support
-- [ ] Router
+- [x] JSX support
+- [x] Fragments
+- [ ] Vite plugin (removes the two rules above)
+- [x] Router
 - [ ] SSR
 
 ## Development

package/dist/index.cjs

@@ -21,6 +21,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   For: () => For,
+  Fragment: () => Fragment,
+  Link: () => Link,
+  Route: () => Route,
+  Router: () => Router,
   Show: () => Show,
   batch: () => batch,
   createContext: () => createContext,
@@ -29,11 +33,18 @@ __export(index_exports, {
   createRoot: () => createRoot,
   createSignal: () => createSignal,
   h: () => h,
+  jsx: () => jsx,
+  jsxDEV: () => jsxDEV,
+  jsxs: () => jsxs,
+  navigate: () => navigate,
   onCleanup: () => onCleanup,
   onMount: () => onMount,
   provide: () => provide,
   render: () => render,
-  useContext: () => useContext
+  untrack: () => untrack,
+  useContext: () => useContext,
+  useParams: () => useParams,
+  usePath: () => usePath
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -169,6 +180,15 @@ function useContext(ctx) {
   }
   return ctx.defaultValue;
 }
+function untrack(fn) {
+  const prev = currentEffect;
+  currentEffect = null;
+  try {
+    return fn();
+  } finally {
+    currentEffect = prev;
+  }
+}
 
 // src/dom/h.ts
 function h(tag, props, ...children) {
@@ -251,9 +271,17 @@ function render(component, container) {
   });
 }
 
+// src/reactivity/memo.ts
+function createMemo(fn) {
+  const [value, setValue] = createSignal(void 0);
+  createEffect(() => setValue(() => fn()));
+  return value;
+}
+
 // src/components/show.ts
 function Show(props) {
-  return () => props.when() ? props.children() : props.fallback?.() ?? null;
+  const visible = createMemo(() => !!props.when());
+  return () => visible() ? untrack(() => props.children()) : untrack(() => props.fallback?.() ?? null);
 }
 
 // src/components/for.ts
@@ -287,15 +315,97 @@ function For(props) {
   };
 }
 
-// src/reactivity/memo.ts
-function createMemo(fn) {
-  const [value, setValue] = createSignal(void 0);
-  createEffect(() => setValue(() => fn()));
-  return value;
+// src/jsx-runtime.ts
+function jsx(type, props) {
+  if (typeof type === "function") return type(props ?? {});
+  const { children, ...rest } = props ?? {};
+  const kids = children === void 0 ? [] : [children];
+  return h(type, rest, ...kids);
+}
+var jsxs = jsx;
+var jsxDEV = jsx;
+function Fragment(props) {
+  const frag = document.createDocumentFragment();
+  appendChildren(frag, props.children === void 0 ? [] : [props.children]);
+  return frag;
+}
+
+// src/router.ts
+var read = () => typeof location === "undefined" ? "/" : location.pathname;
+var [path, setPath] = createSignal(read());
+var listening = false;
+function listen() {
+  if (listening || typeof window === "undefined") return;
+  listening = true;
+  window.addEventListener("popstate", () => setPath(read()));
+}
+function navigate(to, options = {}) {
+  if (new URL(to, location.href).href === location.href) return;
+  history[options.replace ? "replaceState" : "pushState"](null, "", to);
+  setPath(read());
+}
+var usePath = () => path;
+var Params = createContext({});
+function useParams() {
+  return useContext(Params);
+}
+var split = (s) => s.split("/").filter(Boolean);
+function decode(s) {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+function match(pattern, pathname) {
+  if (pattern === "*") return {};
+  const p = split(pattern);
+  const u = split(pathname);
+  if (p.length !== u.length) return null;
+  const params = {};
+  for (let i = 0; i < p.length; i++) {
+    if (p[i].startsWith(":")) params[p[i].slice(1)] = decode(u[i]);
+    else if (p[i] !== u[i]) return null;
+  }
+  return params;
+}
+function Route(props) {
+  return { __route: true, path: props.path, component: props.component };
+}
+function Router(props) {
+  listen();
+  const routes = [props.children].flat(Infinity).filter(
+    (r) => r?.__route === true
+  );
+  return () => {
+    const current = path();
+    for (const route of routes) {
+      const params = match(route.path, current);
+      if (params) {
+        return untrack(() => provide(Params, params, () => route.component()));
+      }
+    }
+    return null;
+  };
+}
+function Link(props) {
+  const { href, children, ...rest } = props;
+  const onClick = (e) => {
+    if (/^[a-z][a-z0-9+.-]*:|^\/\//i.test(href)) return;
+    if (e.defaultPrevented || e.button !== 0) return;
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    e.preventDefault();
+    navigate(href);
+  };
+  return h("a", { ...rest, href, onClick }, children);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   For,
+  Fragment,
+  Link,
+  Route,
+  Router,
   Show,
   batch,
   createContext,
@@ -304,9 +414,16 @@ function createMemo(fn) {
   createRoot,
   createSignal,
   h,
+  jsx,
+  jsxDEV,
+  jsxs,
+  navigate,
   onCleanup,
   onMount,
   provide,
   render,
-  useContext
+  untrack,
+  useContext,
+  useParams,
+  usePath
 });

package/dist/index.d.cts

@@ -12,6 +12,7 @@ interface Context<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;
+declare function untrack<T>(fn: () => 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;
@@ -32,5 +33,44 @@ declare function For<T>(props: {
 
 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 };
+declare function jsx(type: any, props: Record<string, any> | null): any;
+declare const jsxs: typeof jsx;
+declare const jsxDEV: typeof jsx;
+declare namespace JSX {
+    type Element = any;
+    interface IntrinsicElements {
+        [tag: string]: any;
+    }
+    interface ElementChildrenAttribute {
+        children: {};
+    }
+}
+declare function Fragment(props: {
+    children?: Child;
+}): DocumentFragment;
+
+declare function navigate(to: string, options?: {
+    replace?: boolean;
+}): void;
+declare const usePath: () => () => string;
+declare function useParams(): Record<string, string>;
+interface RouteDef {
+    __route: true;
+    path: string;
+    component: () => unknown;
+}
+declare function Route(props: {
+    path: string;
+    component: () => unknown;
+}): RouteDef;
+declare function Router(props: {
+    children?: unknown;
+}): () => unknown;
+declare function Link(props: {
+    href: string;
+    children?: unknown;
+    [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 };

package/dist/index.d.ts

@@ -12,6 +12,7 @@ interface Context<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;
+declare function untrack<T>(fn: () => 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;
@@ -32,5 +33,44 @@ declare function For<T>(props: {
 
 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 };
+declare function jsx(type: any, props: Record<string, any> | null): any;
+declare const jsxs: typeof jsx;
+declare const jsxDEV: typeof jsx;
+declare namespace JSX {
+    type Element = any;
+    interface IntrinsicElements {
+        [tag: string]: any;
+    }
+    interface ElementChildrenAttribute {
+        children: {};
+    }
+}
+declare function Fragment(props: {
+    children?: Child;
+}): DocumentFragment;
+
+declare function navigate(to: string, options?: {
+    replace?: boolean;
+}): void;
+declare const usePath: () => () => string;
+declare function useParams(): Record<string, string>;
+interface RouteDef {
+    __route: true;
+    path: string;
+    component: () => unknown;
+}
+declare function Route(props: {
+    path: string;
+    component: () => unknown;
+}): RouteDef;
+declare function Router(props: {
+    children?: unknown;
+}): () => unknown;
+declare function Link(props: {
+    href: string;
+    children?: unknown;
+    [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 };

package/dist/index.js

@@ -130,6 +130,15 @@ function useContext(ctx) {
   }
   return ctx.defaultValue;
 }
+function untrack(fn) {
+  const prev = currentEffect;
+  currentEffect = null;
+  try {
+    return fn();
+  } finally {
+    currentEffect = prev;
+  }
+}
 
 // src/dom/h.ts
 function h(tag, props, ...children) {
@@ -212,9 +221,17 @@ function render(component, container) {
   });
 }
 
+// src/reactivity/memo.ts
+function createMemo(fn) {
+  const [value, setValue] = createSignal(void 0);
+  createEffect(() => setValue(() => fn()));
+  return value;
+}
+
 // src/components/show.ts
 function Show(props) {
-  return () => props.when() ? props.children() : props.fallback?.() ?? null;
+  const visible = createMemo(() => !!props.when());
+  return () => visible() ? untrack(() => props.children()) : untrack(() => props.fallback?.() ?? null);
 }
 
 // src/components/for.ts
@@ -248,14 +265,96 @@ function For(props) {
   };
 }
 
-// src/reactivity/memo.ts
-function createMemo(fn) {
-  const [value, setValue] = createSignal(void 0);
-  createEffect(() => setValue(() => fn()));
-  return value;
+// src/jsx-runtime.ts
+function jsx(type, props) {
+  if (typeof type === "function") return type(props ?? {});
+  const { children, ...rest } = props ?? {};
+  const kids = children === void 0 ? [] : [children];
+  return h(type, rest, ...kids);
+}
+var jsxs = jsx;
+var jsxDEV = jsx;
+function Fragment(props) {
+  const frag = document.createDocumentFragment();
+  appendChildren(frag, props.children === void 0 ? [] : [props.children]);
+  return frag;
+}
+
+// src/router.ts
+var read = () => typeof location === "undefined" ? "/" : location.pathname;
+var [path, setPath] = createSignal(read());
+var listening = false;
+function listen() {
+  if (listening || typeof window === "undefined") return;
+  listening = true;
+  window.addEventListener("popstate", () => setPath(read()));
+}
+function navigate(to, options = {}) {
+  if (new URL(to, location.href).href === location.href) return;
+  history[options.replace ? "replaceState" : "pushState"](null, "", to);
+  setPath(read());
+}
+var usePath = () => path;
+var Params = createContext({});
+function useParams() {
+  return useContext(Params);
+}
+var split = (s) => s.split("/").filter(Boolean);
+function decode(s) {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+function match(pattern, pathname) {
+  if (pattern === "*") return {};
+  const p = split(pattern);
+  const u = split(pathname);
+  if (p.length !== u.length) return null;
+  const params = {};
+  for (let i = 0; i < p.length; i++) {
+    if (p[i].startsWith(":")) params[p[i].slice(1)] = decode(u[i]);
+    else if (p[i] !== u[i]) return null;
+  }
+  return params;
+}
+function Route(props) {
+  return { __route: true, path: props.path, component: props.component };
+}
+function Router(props) {
+  listen();
+  const routes = [props.children].flat(Infinity).filter(
+    (r) => r?.__route === true
+  );
+  return () => {
+    const current = path();
+    for (const route of routes) {
+      const params = match(route.path, current);
+      if (params) {
+        return untrack(() => provide(Params, params, () => route.component()));
+      }
+    }
+    return null;
+  };
+}
+function Link(props) {
+  const { href, children, ...rest } = props;
+  const onClick = (e) => {
+    if (/^[a-z][a-z0-9+.-]*:|^\/\//i.test(href)) return;
+    if (e.defaultPrevented || e.button !== 0) return;
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    e.preventDefault();
+    navigate(href);
+  };
+  return h("a", { ...rest, href, onClick }, children);
 }
 export {
   For,
+  Fragment,
+  Link,
+  Route,
+  Router,
   Show,
   batch,
   createContext,
@@ -264,9 +363,16 @@ export {
   createRoot,
   createSignal,
   h,
+  jsx,
+  jsxDEV,
+  jsxs,
+  navigate,
   onCleanup,
   onMount,
   provide,
   render,
-  useContext
+  untrack,
+  useContext,
+  useParams,
+  usePath
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cajoa",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A beginner-friendly, signals-based frontend framework.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -16,6 +16,26 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./jsx-runtime": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./jsx-dev-runtime": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [
@@ -31,7 +51,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cjmgrc/Cajoa.git"
+    "url": "git+https://github.com/CajoaTS/Cajoa.git"
   },
   "keywords": [
     "frontend",
@@ -44,10 +64,11 @@
   "author": "cjmgrc",
   "license": "Apache-2.0",
   "bugs": {
-    "url": "https://github.com/cjmgrc/Cajoa/issues"
+    "url": "https://github.com/CajoaTS/Cajoa/issues"
   },
-  "homepage": "https://github.com/cjmgrc/Cajoa#readme",
+  "homepage": "https://github.com/CajoaTS/Cajoa#readme",
   "devDependencies": {
+    "@types/node": "^26.6.5",
     "jsdom": "^29.1.1",
     "tsup": "^9.0.0",
     "typescript": "^5.9.3",