creo 0.2.6 → 0.2.7

package/dist/public/view.d.ts

@@ -1,36 +1,55 @@
 import type { Key } from "../functional/key";
+import type { Maybe } from "../functional/maybe";
 import type { Use } from "./state";
 import type { $primitive } from "./primitive";
-type ViewBodyBase<Props> = {
+export type RefCallback<T> = (value: T | null) => void;
+export type RefObject<T> = {
+    current: T | null;
+};
+export type Ref<T> = RefCallback<T> | RefObject<T>;
+/** Apply a value (or null) to either ref shape. Engine + renderer share this. */
+export declare function applyRef<T>(ref: Maybe<Ref<T>>, value: T | null): void;
+export type ViewBody<Props> = {
     render: () => void;
     onMount?: () => void;
     shouldUpdate?: (nextProps: Props) => boolean;
     onUpdateBefore?: () => void;
     onUpdateAfter?: () => void;
-};
-export type ViewBody<Props, Api> = Api extends void ? ViewBodyBase<Props> : ViewBodyBase<Props> & {
-    api: Api;
+    dispose?: () => void;
 };
 /** Slot callback — passed by the caller at the call site. */
 export type Slot = () => void;
 /** What callers may pass as a slot: a callback or a plain string (rendered as text). */
 export type SlotContent = Slot | string;
+/**
+ * Setter handed to the viewFn for publishing an api into the consumer's `ref`.
+ * Typically called once during the body. Subsequent calls overwrite.
+ */
+export type RefSetter<Api> = (value: Api) => void;
 export type ViewFn<Props, Api> = {
     (ctx: {
         props: () => Props;
         use: Use;
         slot: Slot;
-    }): ViewBody<Props, Api>;
+        ref: RefSetter<Api>;
+    }): ViewBody<Props>;
     [$primitive]?: string;
 };
-/** Resolves to the caller-facing props type. Allows `void` when Props is void or all-optional. */
-type ViewProps<Props> = Props extends void ? {
+/**
+ * Caller-facing props type. Allows `void` when Props is void or all-optional.
+ * `ref` is added alongside `key`; its element type is whatever the view
+ * publishes via `ctx.ref(...)`.
+ */
+type ViewProps<Props, Api> = Props extends void ? {
     key?: Key;
+    ref?: Ref<Api>;
 } | void : {} extends Props ? (Props & {
     key?: Key;
+    ref?: Ref<Api>;
 }) | void : Props & {
     key?: Key;
+    ref?: Ref<Api>;
 };
-export declare function view<Props = void, Api = void>(body: ViewFn<Props, Api>): (props: ViewProps<Props>, slot?: SlotContent) => void;
+export declare function view<Props = void, Api = void>(body: ViewFn<Props, Api>): (props: ViewProps<Props, Api>, slot?: SlotContent) => void;
 export type PublicView<Props, Api> = ReturnType<typeof view<Props, Api>>;
 export {};

package/dist/render/html_render.d.ts

@@ -19,6 +19,7 @@ export declare class HtmlRender implements IRender<HTMLElement | Text> {
     private findInsertionPoint;
     private setAttributes;
     private diffAttributes;
+    private diffEvents;
     private bindEvent;
     private unbindEvent;
     private setAttribute;

package/docs/create-app.md

@@ -0,0 +1,110 @@
+# Create App
+
+`creo-create-app` is a CLI that scaffolds a ready-to-run Creo project with Vite and, optionally, a [Hono](https://hono.dev) backend. Use it when you want a new project without wiring up the tooling yourself.
+
+## Quick start
+
+<div class="pkg-tabs" data-pkg-tabs>
+  <div class="pkg-tabs-bar" role="tablist">
+    <button class="pkg-tab active" data-pkg="bun" role="tab">bun</button>
+    <button class="pkg-tab" data-pkg="npm" role="tab">npm</button>
+    <button class="pkg-tab" data-pkg="pnpm" role="tab">pnpm</button>
+    <button class="pkg-tab" data-pkg="yarn" role="tab">yarn</button>
+  </div>
+  <pre class="pkg-panel active" data-pkg="bun"><code>bunx creo-create-app my-app</code></pre>
+  <pre class="pkg-panel" data-pkg="npm"><code>npx creo-create-app my-app</code></pre>
+  <pre class="pkg-panel" data-pkg="pnpm"><code>pnpm dlx creo-create-app my-app</code></pre>
+  <pre class="pkg-panel" data-pkg="yarn"><code>yarn dlx creo-create-app my-app</code></pre>
+</div>
+
+Omit the project name to be prompted for it:
+
+```bash
+bunx creo-create-app
+```
+
+## Interactive prompts
+
+The CLI asks two questions:
+
+1. **Project name** — becomes the directory name and `package.json` name. Skipped if you passed the name as an argument.
+2. **Include a server (Hono)?** — adds a Hono backend that serves the built static files and exposes a sample `/api/health` endpoint.
+
+## Generated layout
+
+### Client-only (default)
+
+```
+my-app/
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+├── index.html
+├── .gitignore
+└── src/
+    ├── main.ts        # Mounts the creo app
+    └── app.ts         # Starter counter component
+```
+
+Scripts:
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| `dev` | `vite` | Start dev server with HMR |
+| `build` | `vite build` | Production build to `dist/` |
+| `preview` | `vite preview` | Preview production build |
+
+### With server (Hono)
+
+Everything above, plus:
+
+```
+my-app/
+└── src/
+    └── server.ts      # Hono server with static file serving
+```
+
+Additional scripts:
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| `dev:server` | `bun run --watch src/server.ts` | Start Hono server with watch mode |
+| `start` | `bun run src/server.ts` | Run Hono server in production |
+
+During development you run both terminals. Vite proxies `/api/*` requests to the Hono server on `localhost:3000`:
+
+```bash
+# Terminal 1 — backend
+bun run dev:server
+
+# Terminal 2 — frontend
+bun run dev
+```
+
+For production:
+
+```bash
+bun run build
+bun run start
+```
+
+## Adding API routes
+
+The generated `src/server.ts` is a normal Hono app. Add routes directly:
+
+```ts
+app.get("/api/users", (c) => c.json([{ id: 1, name: "Alice" }]));
+
+app.use("/*", async (c, next) => {
+  console.log(`${c.req.method} ${c.req.url}`);
+  await next();
+});
+```
+
+The server uses Bun's native HTTP via `export default { port, fetch }`, so nothing else is required to run it.
+
+## Next steps
+
+- Start editing `src/app.ts` — the starter counter is a normal Creo view.
+- Read [Getting Started](#/getting-started) for the core API.
+- Want to ship it? See [Host on Vercel](#/how-to/deploy-vercel).

package/docs/events.md

@@ -0,0 +1,236 @@
+# Events
+
+Creo collects event handlers under a single `on` prop on primitives.
+
+## Declaring handlers
+
+Define event handler functions in the view function body, before returning the ViewBody. Reference them in render:
+
+```ts
+import { view, button, input, text } from "creo";
+import type { PointerEventData, InputEventData } from "creo";
+
+const MyForm = view((ctx) => {
+  const value = ctx.use("");
+
+  const handleClick = (e: PointerEventData) => {
+    console.log("Clicked at", e.x, e.y);
+  };
+
+  const handleInput = (e: InputEventData) => {
+    value.set(e.value);
+  };
+
+  return {
+    render() {
+      input({
+        value: value.get(),
+        placeholder: "Type here...",
+        on: { input: handleInput },
+      });
+      button({ on: { click: handleClick } }, () => { text("Submit"); });
+    },
+  };
+});
+```
+
+Declaring handlers before `return` keeps them as stable references across re-renders and keeps the render function clean. Better still: if you keep the entire `on: { … }` object stable (declared once outside `render`), the renderer skips the per-event diff with a single reference check.
+
+## The `on` prop
+
+Event handlers live under a single `on` key. Event names are the camelCase form of the DOM event (no `on` prefix). This keeps the renderer free of per-prop event detection: it special-cases one key (`on`) instead of scanning every prop for an `on*` pattern.
+
+| Event key | Fires on | Event data type |
+|---|---|---|
+| `click` | Click / tap | `PointerEventData` |
+| `dblclick` | Double click | `PointerEventData` |
+| `pointerDown` | Pointer button pressed | `PointerEventData` |
+| `pointerUp` | Pointer button released | `PointerEventData` |
+| `pointerMove` | Pointer moved | `PointerEventData` |
+| `keyDown` | Key pressed | `KeyEventData` |
+| `keyUp` | Key released | `KeyEventData` |
+| `focus` | Element focused | `FocusEventData` |
+| `blur` | Element blurred | `FocusEventData` |
+| `input` | Input value changed | `InputEventData` |
+| `change` | Input value committed | `InputEventData` |
+
+## Event data types
+
+All event data types extend `BaseEventData`:
+
+```ts
+type BaseEventData = {
+  stopPropagation: () => void;
+  preventDefault: () => void;
+};
+```
+
+### PointerEventData
+
+```ts
+type PointerEventData = BaseEventData & {
+  x: number;  // clientX
+  y: number;  // clientY
+};
+```
+
+Used by `click`, `dblclick`, `pointerDown`, `pointerUp`, `pointerMove`.
+
+### KeyEventData
+
+```ts
+type KeyEventData = BaseEventData & {
+  key: string;   // e.g. "Enter", "a", "Escape"
+  code: string;  // e.g. "KeyA", "Enter", "Space"
+};
+```
+
+Used by `keyDown`, `keyUp`.
+
+### InputEventData
+
+```ts
+type InputEventData = BaseEventData & {
+  value: string;  // current input value
+};
+```
+
+Used by `input`, `change`.
+
+### FocusEventData
+
+```ts
+type FocusEventData = BaseEventData;
+```
+
+Used by `focus`, `blur`. Contains only the base methods.
+
+## Event type maps
+
+Creo defines two event maps that determine which events a primitive supports:
+
+### ContainerEvents
+
+Applies to most HTML elements (`div`, `span`, `button`, `li`, etc.):
+
+```ts
+type ContainerEvents = {
+  click: (e: PointerEventData) => void;
+  dblclick: (e: PointerEventData) => void;
+  pointerDown: (e: PointerEventData) => void;
+  pointerUp: (e: PointerEventData) => void;
+  pointerMove: (e: PointerEventData) => void;
+  keyDown: (e: KeyEventData) => void;
+  keyUp: (e: KeyEventData) => void;
+  focus: (e: FocusEventData) => void;
+  blur: (e: FocusEventData) => void;
+};
+```
+
+### FormEvents
+
+Extends `ContainerEvents` with input-specific events. Applies to `input`, `textarea`, `select`:
+
+```ts
+type FormEvents = ContainerEvents & {
+  input: (e: InputEventData) => void;
+  change: (e: InputEventData) => void;
+};
+```
+
+## Examples
+
+### Keyboard navigation
+
+```ts
+const KeyNav = view((ctx) => {
+  const selected = ctx.use(0);
+
+  const handleKeyDown = (e: KeyEventData) => {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      selected.update(n => n + 1);
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      selected.update(n => Math.max(0, n - 1));
+    }
+  };
+
+  return {
+    render() {
+      div({ tabindex: 0, on: { keyDown: handleKeyDown } }, () => {
+        text(`Selected: ${selected.get()}`);
+      });
+    },
+  };
+});
+```
+
+### Controlled input
+
+```ts
+const SearchBox = view((ctx) => {
+  const query = ctx.use("");
+
+  const handleInput = (e: InputEventData) => query.set(e.value);
+
+  return {
+    render() {
+      input({
+        value: query.get(),
+        placeholder: "Search...",
+        on: { input: handleInput },
+      });
+    },
+  };
+});
+```
+
+### Preventing default behavior
+
+```ts
+const NoContextMenu = view((ctx) => ({
+  render() {
+    div(
+      {
+        on: {
+          click: (e: PointerEventData) => {
+            e.preventDefault();
+            e.stopPropagation();
+          },
+        },
+      },
+      () => {
+        text("Right-click has no effect here");
+      },
+    );
+  },
+}));
+```
+
+## Stable `on` objects (optional optimization)
+
+The renderer short-circuits the per-event diff when `prev.on === next.on`. Two patterns work:
+
+```ts
+// Pattern A — declare the events object once, reuse it across renders.
+const Counter = view(() => {
+  const inc = () => count.update(n => n + 1);
+  const events = { click: inc };
+
+  return {
+    render() {
+      button({ class: "btn", on: events }, "+1");
+    },
+  };
+});
+
+// Pattern B — inline; the renderer diffs sub-keys, which is still cheap.
+return {
+  render() {
+    button({ class: "btn", on: { click: inc } }, "+1");
+  },
+};
+```
+
+Both are correct. Pattern A skips the sub-diff entirely.

package/docs/getting-started.md

@@ -0,0 +1,201 @@
+# Getting Started
+
+## Installation
+
+<div class="pkg-tabs" data-pkg-tabs>
+  <div class="pkg-tabs-bar" role="tablist">
+    <button class="pkg-tab active" data-pkg="bun" role="tab">bun</button>
+    <button class="pkg-tab" data-pkg="npm" role="tab">npm</button>
+    <button class="pkg-tab" data-pkg="pnpm" role="tab">pnpm</button>
+    <button class="pkg-tab" data-pkg="yarn" role="tab">yarn</button>
+  </div>
+  <pre class="pkg-panel active" data-pkg="bun"><code>bun add creo</code></pre>
+  <pre class="pkg-panel" data-pkg="npm"><code>npm install creo</code></pre>
+  <pre class="pkg-panel" data-pkg="pnpm"><code>pnpm add creo</code></pre>
+  <pre class="pkg-panel" data-pkg="yarn"><code>yarn add creo</code></pre>
+</div>
+
+Creo is a pure JavaScript/TypeScript package with no runtime dependencies. It ships typed for TypeScript 5+, but works just as well from plain JavaScript.
+
+## Your first component
+
+Components are created with `view()`. The function receives a **context object** (here named `ctx`) and returns a `ViewBody` — an object containing at minimum a `render()` function and, optionally, lifecycle hooks (`onMount`, `onUpdateAfter`, etc.).
+
+The context is how your component reads inputs and creates state. It has three members:
+
+- **`ctx.props()`** — a function that returns the current props. Always call it (don't destructure) so you read the latest values on every render.
+- **`ctx.use(initial)`** — creates reactive local state, or subscribes to a global `store`. Must be called in the view body, not inside `render()`.
+- **`ctx.slot`** — the children the parent passed in. Call it (`ctx.slot?.()`) to render them.
+
+Most code destructures what it needs: `({ props, use, slot }) => ...`.
+
+Create `src/app.ts` with a greeting component:
+
+```ts
+// src/app.ts
+import { view, div } from "creo";
+
+export const Greeting = view<{ name: string }>(({ props }) => {
+  return {
+    render() {
+      div({ class: "greeting" }, `Hello, ${props().name}!`);
+    },
+  };
+});
+```
+
+When a primitive has a single string child, pass it as the slot directly — the engine wraps it as a text node automatically. No `text()` wrapper, no `() => {}` callback. Use a function slot only when you have multiple children or need structure.
+
+This is a leaf component. Any component can compose others — the one you mount is called the **root**. Let's wrap `Greeting` in a root `App`:
+
+```ts
+// src/app.ts (continued)
+export const App = view(() => {
+  return {
+    render() {
+      Greeting({ name: "World" });
+    },
+  };
+});
+```
+
+## Mounting the app
+
+Now we have an `App` component — time to put it on the page. Every Creo app starts with `createApp`:
+
+```ts
+// src/main.ts
+import { createApp, HtmlRender } from "creo";
+import { App } from "./app";
+
+const el = document.getElementById("app")!;  // <div id="app"></div> in index.html
+createApp(() => App(), new HtmlRender(el)).mount();
+```
+
+`createApp` takes three arguments:
+
+1. **A slot callback** (`() => void`) — you call your root component inside it, the same way you'd call a child component in any other render function.
+2. **A renderer** — `HtmlRender` draws to the DOM. Other renderers produce JSON or HTML strings; see [Renderers](#/renderers).
+3. **An optional options object** — for advanced settings like a custom scheduler (below).
+
+Calling `.mount()` performs the first render. From then on, Creo re-renders automatically whenever reactive state used by the view changes.
+
+> **Tip.** If you don't want to wire this up by hand, [`creo-create-app`](#/create-app) scaffolds exactly this file layout with Vite already configured.
+
+### Custom scheduler
+
+By default, Creo schedules re-renders via `queueMicrotask`. You can provide a custom scheduler. For example, `requestAnimationFrame` for visual updates:
+
+```ts
+createApp(
+  () => App(),
+  new HtmlRender(document.getElementById("app")!),
+  { scheduler: requestAnimationFrame },
+).mount();
+```
+
+The scheduler receives a `() => void` callback and is responsible for calling it when the next render should happen.
+
+## Adding state
+
+Use `ctx.use` to create reactive values. Here's a counter that displays the current value and a button to increment it:
+
+```ts
+import { view, div, button, _ } from "creo";
+
+const Counter = view(({ use }) => {
+  const count = use(0);
+  const increment = () => count.update(n => n + 1);
+
+  return {
+    render() {
+      div(_, () => {
+        div(_, String(count.get()));
+        button({ on: { click: increment } }, "+1");
+      });
+    },
+  };
+});
+```
+
+Notice the two slot forms in play:
+
+- The **outer `div`** has two children (the value and the button). Multiple children means a **function slot** — `() => { ... }` — where each primitive call adds a child to the parent.
+- The **inner `div`** and the **`button`** each have just one string child, so they use the **string slot** form: `div(_, "...")`, `button({ on: { click } }, "+1")`. No `text()` call, no function wrapper.
+
+As a rule: reach for a function slot when you need to render more than one thing or use control flow (`if`, `for`); use a string slot whenever a single piece of text is enough.
+
+`use()` calls must appear in the body of the view function (before `return`), never inside `render()`. Call order must be stable across re-renders (same rule as React hooks).
+
+## Composing components
+
+Components accept an optional slot (children) as a second argument. The caller passes a string or `() => void`, and inside the view you receive it as `ctx.slot`:
+
+```ts
+import { view, div, p, text, _ } from "creo";
+
+const Card = view(({ slot }) => {
+  return {
+    render() {
+      div({ class: "card" }, slot);
+    },
+  };
+});
+
+// Usage in a parent render:
+Card(_, () => {
+  p(_, "Card content");
+});
+```
+
+When a component does not need children, omit the second argument:
+
+```ts
+Counter({ initial: 0 });
+```
+
+## Full example
+
+```ts
+import { createApp, view, div, h1, ul, li, input, button, HtmlRender, _ } from "creo";
+import type { InputEventData } from "creo";
+
+const TodoApp = view(({ use }) => {
+  const items = use<string[]>([]);
+  const draft = use("");
+
+  const handleInput = (e: InputEventData) => draft.set(e.value);
+  const addItem = () => {
+    if (draft.get().trim()) {
+      items.update(list => [...list, draft.get().trim()]);
+      draft.set("");
+    }
+  };
+
+  return {
+    render() {
+      div({ class: "todo-app" }, () => {
+        h1(_, "Todo");
+        div(_, () => {
+          input({
+            value: draft.get(),
+            placeholder: "New item...",
+            on: { input: handleInput },
+          });
+          button({ on: { click: addItem } }, "Add");
+        });
+        ul(_, () => {
+          for (const item of items.get()) {
+            li({ key: item }, item);
+          }
+        });
+      });
+    },
+  };
+});
+
+createApp(
+  () => TodoApp(),
+  new HtmlRender(document.getElementById("app")!),
+).mount();
+```