creo 0.2.6 → 0.2.7

package/docs/how-to/data-fetching.md

@@ -0,0 +1,155 @@
+# Data Fetching
+
+Creo has no built-in data-fetching library. The state primitive (`use()`) is enough — it supports async updates, and render reads the current value synchronously.
+
+## The basic pattern
+
+Track three things: the data, a loading flag, and an error.
+
+```ts
+const UserProfile = view<{ id: string }>(({ props, use }) => {
+  const user = use<User | null>(null);
+  const loading = use(false);
+  const error = use<string | null>(null);
+
+  const load = async () => {
+    loading.set(true);
+    error.set(null);
+    try {
+      const res = await fetch(`/api/users/${props().id}`);
+      if (!res.ok) throw new Error(res.statusText);
+      user.set(await res.json());
+    } catch (e) {
+      error.set((e as Error).message);
+    } finally {
+      loading.set(false);
+    }
+  };
+
+  return {
+    onMount: load,
+    render() {
+      if (loading.get()) return Spinner();
+      if (error.get()) return ErrorBanner({ message: error.get()! });
+      const u = user.get();
+      if (!u) return null;
+      UserCard({ user: u });
+    },
+  };
+});
+```
+
+## Using `update()` with async
+
+`update()` accepts an async function and chains through pending updates safely:
+
+```ts
+const refresh = () => user.update(async (current) => {
+  const fresh = await api.getUser(current.id);
+  return fresh;
+});
+```
+
+## Refetching on prop change
+
+Use `shouldUpdate` combined with `onUpdateAfter` to refetch when a prop changes:
+
+```ts
+const UserProfile = view<{ id: string }>(({ props, use }) => {
+  let lastId = props().id;
+  const user = use<User | null>(null);
+
+  const load = async (id: string) => {
+    user.set(await api.getUser(id));
+  };
+
+  return {
+    onMount: () => load(lastId),
+    onUpdateAfter() {
+      if (props().id !== lastId) {
+        lastId = props().id;
+        load(lastId);
+      }
+    },
+    render() { /* ... */ },
+  };
+});
+```
+
+## Sharing data across views
+
+For data used by many views, put it in a `store`. Views subscribe with `use(store)` and all re-render when the data updates.
+
+```ts
+import { store } from "creo";
+
+type UsersState = {
+  byId: Record<string, User>;
+  loading: Set<string>;
+};
+
+const UsersStore = store.new<UsersState>({ byId: {}, loading: new Set() });
+
+export async function loadUser(id: string) {
+  const state = UsersStore.get();
+  if (state.byId[id] || state.loading.has(id)) return;
+
+  UsersStore.update((s) => ({
+    ...s,
+    loading: new Set([...s.loading, id]),
+  }));
+
+  const user = await api.getUser(id);
+
+  UsersStore.update((s) => {
+    const loading = new Set(s.loading);
+    loading.delete(id);
+    return {
+      byId: { ...s.byId, [id]: user },
+      loading,
+    };
+  });
+}
+```
+
+Any view can now do `use(UsersStore)` and read `state.byId[id]` synchronously.
+
+## Cancellation
+
+For requests that may outlive the view (e.g., user navigates away), use an `AbortController`:
+
+```ts
+const list = use<Item[]>([]);
+let controller: AbortController | null = null;
+
+const load = async () => {
+  controller?.abort();
+  controller = new AbortController();
+  try {
+    const res = await fetch("/api/items", { signal: controller.signal });
+    list.set(await res.json());
+  } catch (e) {
+    if ((e as Error).name === "AbortError") return;
+    throw e;
+  }
+};
+```
+
+## Avoiding waterfalls
+
+If two requests don't depend on each other, kick them off in parallel:
+
+```ts
+const load = async () => {
+  const [u, posts] = await Promise.all([
+    api.getUser(id),
+    api.getPosts(id),
+  ]);
+  user.set(u);
+  postList.set(posts);
+};
+```
+
+## See also
+
+- [Suspense pattern](#/how-to/suspense) — a helper view that wraps the loading/error/data dance into one component.

package/docs/how-to/deploy-vercel.md

@@ -0,0 +1,130 @@
+# Host on Vercel
+
+A Creo app built with [`creo-create-app`](#/create-app) is a standard Vite project, so Vercel deploys it with zero configuration. This recipe covers both variants:
+
+- **Client-only** — static site, served from Vercel's edge.
+- **With Hono server** — static frontend plus a serverless API function.
+
+## Client-only (static)
+
+### 1. Push the project to GitHub
+
+```bash
+git init
+git add .
+git commit -m "init"
+git remote add origin git@github.com:you/my-app.git
+git push -u origin main
+```
+
+### 2. Import it on Vercel
+
+Go to [vercel.com/new](https://vercel.com/new), pick the repo, and accept the defaults. Vercel auto-detects Vite:
+
+| Setting | Value |
+|---|---|
+| Framework preset | **Vite** |
+| Build command | `vite build` (or `bun run build`) |
+| Output directory | `dist` |
+| Install command | `bun install` (or your preferred package manager) |
+
+No `vercel.json` needed.
+
+### 3. (Optional) pin it in a config file
+
+If you want the settings committed to the repo, add a `vercel.json`:
+
+```json
+{
+  "buildCommand": "bun run build",
+  "outputDirectory": "dist",
+  "installCommand": "bun install"
+}
+```
+
+### Hash routes work out of the box
+
+`creo-router` is hash-based (`/#/about`), so every request is served `index.html` — no rewrite rules needed. If you later move to path-based routing, add this to `vercel.json` so deep links resolve:
+
+```json
+{
+  "rewrites": [{ "source": "/(.*)", "destination": "/" }]
+}
+```
+
+## With Hono server (API routes)
+
+The Hono server generated by `creo-create-app` runs as a Vercel **Serverless Function**. You keep Vite for the frontend and expose the Hono app under `/api/*`.
+
+### 1. Install the Vercel adapter
+
+```bash
+bun add @hono/node-server
+```
+
+### 2. Create `api/[[...route]].ts`
+
+Vercel treats files in `/api` as serverless functions. The `[[...route]]` catch-all forwards everything to your Hono app:
+
+```ts
+// api/[[...route]].ts
+import { handle } from "hono/vercel";
+import app from "../src/server";
+
+export const config = { runtime: "nodejs" };
+export default handle(app);
+```
+
+Make sure `src/server.ts` exports the Hono `app` as its default export:
+
+```ts
+// src/server.ts
+import { Hono } from "hono";
+
+const app = new Hono();
+app.get("/api/health", (c) => c.json({ ok: true }));
+
+// Still runnable locally as a Bun server:
+export default { port: 3000, fetch: app.fetch };
+```
+
+> **Tip.** Keep both exports — the `{ port, fetch }` default lets `bun run src/server.ts` keep working locally; Vercel uses the named `app` import.
+
+### 3. Configure `vercel.json`
+
+```json
+{
+  "buildCommand": "bun run build",
+  "outputDirectory": "dist",
+  "installCommand": "bun install",
+  "rewrites": [
+    { "source": "/api/:path*", "destination": "/api/[[...route]]" }
+  ]
+}
+```
+
+### 4. Deploy
+
+```bash
+bunx vercel
+```
+
+On push, Vercel builds the frontend with Vite and deploys `api/[[...route]].ts` as a function. The static site and the API share one domain — no CORS, no proxy config.
+
+## Environment variables
+
+Set them in **Project Settings → Environment Variables**. In your code, read them the same way as any Vite / Node app:
+
+```ts
+// Client (Vite inlines at build time):
+const apiKey = import.meta.env.VITE_API_KEY;
+
+// Server function:
+const secret = process.env.SESSION_SECRET;
+```
+
+## Troubleshooting
+
+- **404 on `/foo` after refresh** — you're on path-based routing without the SPA rewrite. Add the `rewrites` rule from the client-only section.
+- **`Cannot find module 'hono/vercel'`** — install `@hono/node-server` (it ships the Vercel handler) and redeploy.
+- **API routes hit `/api/[[...route]]` literally** — confirm the `rewrites` entry is present and that the filename uses **double square brackets**.

package/docs/how-to/router.md

@@ -0,0 +1,111 @@
+# Router
+
+Creo ships a separate package, [`creo-router`](https://www.npmjs.com/package/creo-router), that provides a minimal hash-based router built on top of the `store` primitive. It weighs a few hundred bytes gzipped.
+
+## Install
+
+```bash
+bun add creo creo-router
+```
+
+## Setup
+
+`createRouter` takes a list of routes and a fallback, and returns a bundle of tools: a route store, a `navigate` helper, a `RouterView` to render the matched view, and a `Link` that intercepts clicks.
+
+```ts
+import { createRouter } from "creo-router";
+
+const { routeStore, navigate, RouterView, Link } = createRouter({
+  routes: [
+    { path: "/", view: () => HomePage() },
+    { path: "/about", view: () => AboutPage() },
+    { path: "/users/:id", view: () => UserPage() },
+  ],
+  fallback: () => NotFoundPage(),
+});
+```
+
+Routes support:
+
+- Static segments: `/about`
+- Dynamic params: `/users/:id`, read via `route.params.id`
+
+## Rendering
+
+Mount `RouterView()` wherever you want route content to appear — typically inside a layout view.
+
+```ts
+import { _ } from "creo";
+
+const App = view(() => ({
+  render() {
+    div({ class: "shell" }, () => {
+      nav(_, () => {
+        Link({ href: "/" }, "Home");
+        Link({ href: "/about" }, "About");
+      });
+      main(_, () => {
+        RouterView();
+      });
+    });
+  },
+}));
+```
+
+## Reading route params
+
+`routeStore` is a regular Creo store. Subscribe from any view with `use(routeStore)`:
+
+```ts
+const UserPage = view(({ use }) => {
+  const route = use(routeStore);
+
+  return {
+    render() {
+      const { id } = route.get().params;
+      h1(_, `User ${id}`);
+    },
+  };
+});
+```
+
+## Programmatic navigation
+
+`navigate(path)` updates the hash — the store reacts automatically, and any view subscribed to it re-renders.
+
+```ts
+const handleSave = async () => {
+  await api.save(form);
+  navigate("/success");
+};
+```
+
+## Handling the back button
+
+The browser's back/forward buttons fire `hashchange`, which the router listens to. No extra work needed.
+
+## Active link styling
+
+Since `Link` just renders an `<a>`, you can compare against `routeStore` to style it:
+
+```ts
+const NavLink = view<{ href: string }>(({ props, use, slot }) => {
+  const route = use(routeStore);
+
+  return {
+    render() {
+      const p = props();
+      const active = route.get().path === p.href;
+      Link(
+        { href: p.href, class: active ? "nav-link active" : "nav-link" },
+        slot,
+      );
+    },
+  };
+});
+```
+
+## Notes
+
+- The router is **hash-based** (`#/path`). This means no server config is required — works on GitHub Pages, static hosts, and `file://` out of the box.
+- All route changes go through the store, so they integrate with Creo's scheduler: a single render pass handles the route change and any state updates triggered by it.

package/docs/how-to/styles.md

@@ -0,0 +1,124 @@
+# Styles
+
+Creo is framework-agnostic about styling. Every primitive accepts a `class` prop and a `style` string prop — pick whichever approach your project already uses.
+
+## Global CSS
+
+The simplest option: a plain `.css` file imported once from your entry module.
+
+```ts
+// main.ts
+import "./styles.css";
+import { createApp, HtmlRender } from "creo";
+// ...
+```
+
+```css
+/* styles.css */
+.button {
+  padding: 8px 16px;
+  border-radius: 6px;
+  background: #4a90d9;
+  color: #fff;
+}
+.button:hover { background: #357ac2; }
+```
+
+```ts
+button({ class: "button", on: { click: handler } }, "Save");
+```
+
+## Conditional classes
+
+Plain string concatenation works — no helper needed:
+
+```ts
+const cls = "nav-link" + (active ? " active" : "");
+a({ href, class: cls }, title);
+```
+
+For more complex cases, a tiny helper keeps the render clean:
+
+```ts
+const cx = (...xs: (string | false | null | undefined)[]) =>
+  xs.filter(Boolean).join(" ");
+
+a({ class: cx("nav-link", active && "active", disabled && "is-disabled") }, title);
+```
+
+## Inline styles
+
+The `style` prop is a string — the same format as HTML's `style` attribute.
+
+```ts
+div({ style: `width: ${width}px; color: ${color}` }, () => { /* ... */ });
+```
+
+For dynamic values that change often, inline styles are fine. For static design, prefer classes — they're cheaper to diff.
+
+## CSS Modules
+
+Vite supports CSS Modules out of the box. Name the file `*.module.css`:
+
+```css
+/* Card.module.css */
+.card {
+  padding: 16px;
+  border: 1px solid #eee;
+}
+.title { font-weight: 600; }
+```
+
+```ts
+import styles from "./Card.module.css";
+
+const Card = view<{ title: string }>(({ props, slot }) => ({
+  render() {
+    div({ class: styles.card }, () => {
+      h2({ class: styles.title }, props().title);
+      slot?.();
+    });
+  },
+}));
+```
+
+The `styles` object is keyed by the class names you wrote — the values are hashed and isolated per module.
+
+## Tailwind
+
+Works with no extra wiring. Install Tailwind, include its CSS, and pass utility strings to `class`:
+
+```ts
+button({ class: "px-4 py-2 rounded-md bg-blue-500 text-white hover:bg-blue-600" },
+  "Save");
+```
+
+## Scoped styles without a CSS toolchain
+
+If you want per-component styles without a bundler plugin, declare them inside a `<style>` tag in your HTML shell with a naming convention (BEM or a short prefix).
+
+## Dynamic class lists for keyed lists
+
+When a class depends on reactive state, compute it in `render()` — it's just a string:
+
+```ts
+for (const task of tasks.get()) {
+  li(
+    { key: task.id, class: task.done ? "task done" : "task" },
+    task.title,
+  );
+}
+```
+
+Creo diffs `class` as a single string — no array or object normalization needed.
+
+## Setting arbitrary attributes
+
+`HtmlAttrs` has an index signature, so you can pass `data-*`, `aria-*`, or any custom attribute directly:
+
+```ts
+div(
+  { class: "tab", role: "tab", "aria-selected": "true", "data-tab-id": id },
+  title,
+);
+```

package/docs/how-to/suspense.md

@@ -0,0 +1,116 @@
+# Suspense Pattern
+
+Creo has no `<Suspense>` primitive and doesn't need one — you can compose the same behavior from a plain view. The goal: take an async loader, show a fallback while it runs, and render the data on success.
+
+## A reusable `Suspense` view
+
+```ts
+import { view, div, _ } from "creo";
+import type { SlotContent } from "creo";
+
+type SuspenseProps<T> = {
+  load: () => Promise<T>;
+  children: (data: T) => void;
+  fallback?: SlotContent;
+  error?: (err: Error) => void;
+  key?: unknown; // pass a key to force reload when dependencies change
+};
+
+export const Suspense = view(<T,>({ props, use }: any) => {
+  type Status = "loading" | "ok" | "error";
+  const status = use<Status>("loading");
+  const data = use<T | null>(null);
+  const err = use<Error | null>(null);
+
+  const run = async () => {
+    status.set("loading");
+    try {
+      const result = await props().load();
+      data.set(result);
+      status.set("ok");
+    } catch (e) {
+      err.set(e as Error);
+      status.set("error");
+    }
+  };
+
+  return {
+    onMount: run,
+    render() {
+      const p = props();
+      switch (status.get()) {
+        case "loading":
+          if (p.fallback) {
+            if (typeof p.fallback === "string") {
+              div({ class: "suspense-fallback" }, p.fallback);
+            } else {
+              p.fallback();
+            }
+          } else {
+            div({ class: "suspense-fallback" }, "Loading...");
+          }
+          return;
+        case "error":
+          if (p.error) p.error(err.get()!);
+          else div({ class: "suspense-error" }, err.get()!.message);
+          return;
+        case "ok":
+          p.children(data.get()!);
+          return;
+      }
+    },
+  };
+});
+```
+
+## Usage
+
+```ts
+const UserProfile = view<{ id: string }>(({ props }) => ({
+  render() {
+    Suspense({
+      key: props().id, // re-mount when id changes
+      load: () => fetch(`/api/users/${props().id}`).then(r => r.json()),
+      fallback: () => Spinner(),
+      error: (e) => ErrorBanner({ message: e.message }),
+      children: (user: User) => {
+        h1(_, user.name);
+        p(_, user.bio);
+      },
+    });
+  },
+}));
+```
+
+## Why this is different from React Suspense
+
+React's `<Suspense>` hooks into a special "throw a promise" protocol baked into the renderer. Creo keeps the model simpler: the async work happens in a view's lifecycle, and the status is ordinary state. You get:
+
+- No special reconciler support needed.
+- Full control over loading/error UI without wrapper gymnastics.
+- No "use this hook only under a boundary" gotchas.
+
+## Composing with `store`
+
+If many views depend on the same resource, move the loading logic into a store and subscribe:
+
+```ts
+const user = use(UsersStore);
+const loaded = user.get().byId[id];
+
+if (!loaded) {
+  Spinner();
+  loadUser(id); // idempotent — checks in-flight set
+  return;
+}
+
+UserCard({ user: loaded });
+```
+
+Then `Suspense` is only useful for one-off async work — anything reused goes into a store.
+
+## Caveats
+
+- Don't call the `load` function from `render()` — it would fire a new request every re-render. Put it in `onMount()`.
+- For cancellation, pair with `AbortController` (see [data fetching](#/how-to/data-fetching)).
+- If `load` throws synchronously, the error path still works — `await` converts synchronous throws into a rejected promise.

package/docs/index.md

@@ -0,0 +1,66 @@
+# Creo UI Framework
+
+Creo is a lightweight, imperative UI framework for building reactive interfaces in TypeScript.
+
+## What is Creo?
+
+Creo takes a different approach from JSX-based frameworks. Instead of describing UI as a tree of elements returned from render functions, Creo uses **imperative render streams** -- you call primitives as functions, and the framework builds the virtual DOM from those calls.
+
+```ts
+import { view, div, button, text } from "creo";
+
+const App = view((ctx) => {
+  return {
+    render() {
+      div({ class: "app" }, () => {
+        h1({}, () => { text("Hello, Creo"); });
+        p({}, () => { text("An imperative UI framework."); });
+      });
+    },
+  };
+});
+```
+
+## Why Creo?
+
+- **No JSX, no compiler.** Render functions are plain TypeScript. All control flow (if/else, for loops, ternaries) works naturally.
+- **Immediate state.** Calling `.set()` or `.update()` applies the value instantly. No stale closures, no batching surprises.
+- **Explicit lifecycle.** Named hooks (`mount.before`, `mount.after`, `update.before`, `update.after`) replace dependency-array guessing.
+- **Renderer-agnostic.** The same component tree can target the DOM (`HtmlRender`), a JSON structure (`JsonRender`), or an HTML string (`StringRender`). Write your own renderer by implementing the `IRender` interface.
+- **Lightweight.** No virtual DOM diffing library, no template compiler. Reconciliation is built into the engine with keyed and positional matching.
+
+## Quick taste
+
+```ts
+import { createApp, view, div, button, text, HtmlRender } from "creo";
+
+const Counter = view<{ initial: number }>(({ props, use }) => {
+  const count = use(props().initial);
+  const increment = () => count.update(n => n + 1);
+
+  return {
+    render() {
+      div({}, () => {
+        text(count.get());
+        button({ on: { click: increment } }, () => { text("+1"); });
+      });
+    },
+  };
+});
+
+createApp(
+  () => Counter({ initial: 0 }),
+  new HtmlRender(document.getElementById("app")!),
+).mount();
+```
+
+## Documentation
+
+- [Getting Started](./getting-started.md) -- installation, first app
+- [view()](./view.md) -- defining components
+- [State](./state.md) -- reactive state management
+- [Events](./events.md) -- handling user interactions
+- [Primitives](./primitives.md) -- built-in HTML elements and custom primitives
+- [Store](./store.md) -- global/shared state (context pattern)
+- [Renderers](./renderers.md) -- HtmlRender, JsonRender, StringRender, custom renderers
+- [Lifecycle](./lifecycle.md) -- mount, update, and disposal hooks