cajoa 0.3.0 → 0.4.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.3 (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?
 
@@ -80,6 +80,32 @@ const [todos, setTodos] = createSignal([{ id: 1, text: "Learn Cajoa" }]);
 </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
@@ -121,16 +147,31 @@ const [todos, setTodos] = createSignal([{ id: 1, text: "Learn Cajoa" }]);
 | `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 Fragments (`<>...</>`) yet. Wrap siblings in an element.
 - 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()`.
 
@@ -143,9 +184,9 @@ const [todos, setTodos] = createSignal([{ id: 1, text: "Learn Cajoa" }]);
 - [x] `createMemo`, `batch`
 - [x] Context
 - [x] JSX support
-- [ ] Fragments
+- [x] Fragments
 - [ ] Vite plugin (removes the two rules above)
-- [ ] Router
+- [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,
@@ -32,11 +36,15 @@ __export(index_exports, {
   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);
 
@@ -172,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) {
@@ -254,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
@@ -290,13 +315,6 @@ 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 ?? {});
@@ -306,9 +324,88 @@ function jsx(type, props) {
 }
 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,
@@ -320,9 +417,13 @@ var jsxDEV = jsx;
   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;
@@ -44,6 +45,32 @@ declare namespace JSX {
         children: {};
     }
 }
+declare function Fragment(props: {
+    children?: Child;
+}): DocumentFragment;
 
-export { For, JSX, Show, batch, createContext, createEffect, createMemo, createRoot, createSignal, h, jsx, jsxDEV, jsxs, onCleanup, onMount, provide, render, useContext };
-export type { Child, Context };
+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;
@@ -44,6 +45,32 @@ declare namespace JSX {
         children: {};
     }
 }
+declare function Fragment(props: {
+    children?: Child;
+}): DocumentFragment;
 
-export { For, JSX, Show, batch, createContext, createEffect, createMemo, createRoot, createSignal, h, jsx, jsxDEV, jsxs, onCleanup, onMount, provide, render, useContext };
-export type { Child, Context };
+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,13 +265,6 @@ 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 ?? {});
@@ -264,8 +274,87 @@ function jsx(type, props) {
 }
 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,
@@ -277,9 +366,13 @@ export {
   jsx,
   jsxDEV,
   jsxs,
+  navigate,
   onCleanup,
   onMount,
   provide,
   render,
-  useContext
+  untrack,
+  useContext,
+  useParams,
+  usePath
 };

package/package.json

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