creo 0.2.6 → 0.2.7

package/docs/lifecycle.md

@@ -0,0 +1,173 @@
+# Lifecycle
+
+Creo provides explicit, named lifecycle hooks on the `ViewBody` object. There are no dependency arrays — each hook has a clear purpose and timing.
+
+## Overview
+
+| Hook | When it runs |
+|------|-------------|
+| `onMount` | After the view's first render (DOM/output exists) |
+| `shouldUpdate(nextProps)` | Before a re-render, to decide whether it should proceed |
+| `onUpdateBefore` | Before each re-render (not called on first render) |
+| `onUpdateAfter` | After each re-render (not called on first render) |
+
+All hooks are optional properties on the object returned from a view function.
+
+## onMount
+
+Runs after the view's first render and after all children have been rendered. The DOM/output exists at this point. Use it for post-mount side effects like focusing an element, starting timers, or fetching data:
+
+```ts
+const ItemList = view(({ use }) => {
+  const data = use<string[]>([]);
+
+  return {
+    onMount() {
+      fetch("/api/items")
+        .then(r => r.json())
+        .then(items => data.set(items));
+    },
+    render() {
+      for (const item of data.get()) {
+        li(_, item);
+      }
+    },
+  };
+});
+```
+
+`onMount` callbacks are batched — all views that mounted in the same render loop have their `onMount` called after the entire tree is settled.
+
+## shouldUpdate
+
+A predicate that decides whether the view should re-render when it receives new props. Return `true` to allow the render, `false` to skip it. This is equivalent to `React.memo`'s comparison function:
+
+```ts
+const ExpensiveList = view<{ items: string[]; label: string }>(({ props }) => {
+  return {
+    shouldUpdate(nextProps) {
+      return nextProps.items !== props().items;
+    },
+    render() {
+      div(_, () => {
+        text(props().label);
+        for (const item of props().items) {
+          li(_, item);
+        }
+      });
+    },
+  };
+});
+```
+
+If `shouldUpdate` is not defined, Creo compares props by **shallow equality**. The view re-renders when its own props shallow-differ, when a subscribed `use()` value changes, or when the slot's structure changes — a parent re-render alone doesn't force a child re-render.
+
+## onUpdateBefore
+
+Runs synchronously before each re-render (not on the first render). Use it for pre-render calculations or logging:
+
+```ts
+const Animated = view(({ use }) => {
+  const value = use(0);
+  let prevValue = 0;
+
+  return {
+    onUpdateBefore() {
+      prevValue = value.get();
+    },
+    render() {
+      div({ class: prevValue !== value.get() ? "changed" : "" }, () => {
+        text(String(value.get()));
+      });
+    },
+  };
+});
+```
+
+## onUpdateAfter
+
+Runs synchronously after each re-render (not on the first render). The DOM/output reflects the new state:
+
+```ts
+const WordCount = view<{ text: string }>(({ props, use }) => {
+  const count = use(0);
+
+  return {
+    onUpdateAfter() {
+      // Props just changed; derive a value from them and push it somewhere.
+      count.set(props().text.trim().split(/\s+/).filter(Boolean).length);
+      console.log(`re-rendered with ${count.get()} words`);
+    },
+    render() {
+      div(_, () => {
+        p(_, props().text);
+        p({ class: "meta" }, `${count.get()} words`);
+      });
+    },
+  };
+});
+```
+
+`onUpdateAfter` is for observing the result of a render — reading measurements, pushing metrics, scheduling follow-up work. It fires after DOM mutations are applied, so any reads you do see the latest layout.
+
+## Cleanup
+
+When a view is removed from the tree (its parent no longer renders it), the view and all its descendants are disposed automatically during reconciliation. The engine calls the renderer's `unmount` to clean up output artifacts and removes the view from the dirty queue.
+
+There is no dedicated unmount hook. For cleanup of resources (timers, subscriptions, event listeners) started in `onMount`, tie them to module-scoped stores or rely on `setInterval`/`setTimeout` completing on page unload. If you need guaranteed teardown, pair the resource with a reactive `store` and clear it from a parent view when the child is conditionally removed.
+
+```ts
+const Poller = view(({ use }) => {
+  const data = use("");
+
+  return {
+    onMount() {
+      setInterval(() => {
+        fetch("/api/status")
+          .then(r => r.text())
+          .then(t => data.set(t));
+      }, 5000);
+    },
+    render() {
+      text(data.get());
+    },
+  };
+});
+```
+
+## Complete example
+
+```ts
+const Dashboard = view<{ userId: string }>(({ props, use }) => {
+  const profile = use<{ name: string } | null>(null);
+  let renderCount = 0;
+
+  return {
+    onMount() {
+      fetch(`/api/users/${props().userId}`)
+        .then(r => r.json())
+        .then(data => profile.set(data));
+    },
+    shouldUpdate(nextProps) {
+      return nextProps.userId !== props().userId;
+    },
+    onUpdateBefore() {
+      renderCount++;
+      console.log(`Re-render #${renderCount}`);
+    },
+    onUpdateAfter() {
+      console.log("Dashboard updated");
+    },
+    render() {
+      div({ class: "dashboard" }, () => {
+        const p = profile.get();
+        if (p) {
+          h1(_, p.name);
+        } else {
+          text("Loading...");
+        }
+      });
+    },
+  };
+});
+```

package/docs/primitives.md

@@ -0,0 +1,195 @@
+# Primitives
+
+Primitives are the leaf-level building blocks in Creo. They correspond to HTML elements and are called as functions inside `render()`.
+
+## Built-in HTML elements
+
+Creo exports pre-defined primitives for all standard HTML elements. Import them directly:
+
+```ts
+import { div, span, p, h1, button, input, text } from "creo";
+```
+
+### Calling primitives
+
+Primitives accept two optional arguments:
+
+1. **Props** -- an object with HTML attributes and event handlers.
+2. **Slot** -- a `() => void` callback for child content, or a `PendingView[]` for passthrough children.
+
+```ts
+// No props, no children
+br();
+hr();
+
+// Props only
+input({ type: "text", placeholder: "Enter name" });
+img({ src: "/logo.png", alt: "Logo" });
+
+// Props and children
+div({ class: "card", id: "main" }, () => {
+  h1({}, () => { text("Title"); });
+  p({}, () => { text("Content goes here."); });
+});
+
+// Children only (pass undefined or omit props)
+div({}, () => {
+  text("Hello");
+});
+```
+
+### text()
+
+`text()` renders a text node. It accepts a string or number:
+
+```ts
+text("Hello, world");
+text(42);
+text(count.get());
+```
+
+`text()` does not accept children.
+
+## Available elements
+
+### Layout / structural
+
+`div`, `span`, `section`, `article`, `aside`, `nav`, `header`, `footer`, `main`
+
+### Sectioning
+
+`address`, `hgroup`, `search`
+
+### Text / headings
+
+`p`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `pre`, `code`, `em`, `strong`, `small`, `br`, `hr`, `blockquote`
+
+### Links and labels
+
+`a` (with `href`, `target` attrs), `label` (with `for` attr)
+
+### Text semantics
+
+`abbr`, `b`, `bdi`, `bdo`, `cite`, `data`, `dfn`, `i`, `kbd`, `mark`, `q`, `rp`, `rt`, `ruby`, `s`, `samp`, `sub`, `sup`, `time`, `u`, `varEl`, `wbr`
+
+### Lists
+
+`ul`, `ol`, `li`, `dl`, `dt`, `dd`
+
+### Tables
+
+`table`, `thead`, `tbody`, `tfoot`, `tr`, `th` (with `colspan`, `rowspan`, `scope`), `td` (with `colspan`, `rowspan`), `caption`, `colgroup`, `col`
+
+### Forms
+
+`form`, `button`, `input`, `textarea`, `select`, `option`, `fieldset`, `legend`, `datalist`, `optgroup`, `output`, `progress`, `meter`
+
+Form elements like `input`, `textarea`, and `select` support `FormEvents` (includes `onInput`, `onChange`). Other elements use `ContainerEvents`.
+
+### Media
+
+`img`, `video`, `audio`, `canvas`, `source`, `track`, `map`, `area`, `picture`
+
+### Embedded
+
+`iframe`, `embed`, `object`, `portal`, `svg`
+
+### Interactive
+
+`details` (with `open`), `summary`, `dialog` (with `open`), `menu`
+
+### Figure
+
+`figure`, `figcaption`
+
+## HtmlAttrs
+
+All built-in primitives share a common attribute base:
+
+```ts
+type HtmlAttrs = {
+  class?: string;
+  id?: string;
+  style?: string;
+  title?: string;
+  tabindex?: number;
+  hidden?: boolean;
+  role?: string;
+  draggable?: boolean;
+  [attr: string]: unknown;  // open index signature for any HTML attribute
+};
+```
+
+The open index signature means you can pass any attribute -- Creo will set it via `setAttribute`.
+
+## The html() factory
+
+`html(tag)` creates a primitive for any HTML tag at runtime. All built-in primitives are created this way:
+
+```ts
+import { html } from "creo";
+
+// Create a custom element primitive
+const myWidget = html("my-widget");
+
+// Use it in render
+myWidget({ class: "fancy" }, () => {
+  text("Inside custom element");
+});
+```
+
+You can specify custom attribute and event types via generics:
+
+```ts
+const video = html<
+  HtmlAttrs & { src?: string; controls?: boolean; autoplay?: boolean },
+  ContainerEvents
+>("video");
+```
+
+`html()` caches primitives by tag name -- calling `html("div")` twice returns the same primitive.
+
+## The primitive() factory
+
+For completely custom primitives (not backed by an HTML tag), use `primitive()`:
+
+```ts
+import { primitive } from "creo";
+import type { PrimitiveComponent } from "creo";
+
+type CanvasAttrs = { width: number; height: number };
+type CanvasEvents = { click: (e: PointerEventData) => void };
+
+const myCanvas: PrimitiveComponent<CanvasAttrs, CanvasEvents> = primitive<CanvasAttrs, CanvasEvents>();
+```
+
+Custom primitives need a render handler registered on the renderer to produce output. See [Renderers](./renderers.md) for details.
+
+## Passing children
+
+Primitives accept children in two forms:
+
+### Slot callback
+
+A `() => void` function called at the call site. The engine collects child calls made inside it:
+
+```ts
+div({ class: "wrapper" }, () => {
+  p({}, () => { text("Hello"); });
+  span({}, () => { text("World"); });
+});
+```
+
+### PendingView array (passthrough)
+
+When a view receives `ctx.children` from its parent, it can pass that array directly as the second argument:
+
+```ts
+const Card = view((ctx) => ({
+  render() {
+    div({ class: "card" }, ctx.children);
+  },
+}));
+```
+
+This avoids re-collecting children and preserves the parent's pending views directly.

package/docs/renderers.md

@@ -0,0 +1,183 @@
+# Renderers
+
+Creo separates the component model from the output target. Renderers implement the `IRender` interface to translate the virtual DOM into a specific output format.
+
+## Built-in renderers
+
+### HtmlRender
+
+Renders to the browser DOM. This is the primary renderer for web applications.
+
+```ts
+import { createApp, HtmlRender } from "creo";
+
+const container = document.getElementById("app")!;
+createApp(() => App(), new HtmlRender(container)).mount();
+```
+
+`HtmlRender` handles:
+- Creating and updating DOM elements
+- Attribute diffing (only changed attributes are touched)
+- Event listener binding and cleanup
+- DOM properties (`value`, `checked`, `selected`) set directly instead of via `setAttribute`
+- Keyed reordering of child nodes
+- Boolean attribute handling (`disabled`, `hidden`, etc.)
+- `autofocus` support on mount
+
+### JsonRender
+
+Produces a JSON tree representation of the UI. Useful for testing and serialization.
+
+```ts
+import { createApp, JsonRender } from "creo";
+import type { JsonNode } from "creo";
+
+const renderer = new JsonRender();
+createApp(() => App(), renderer).mount();
+
+const tree: JsonNode | undefined = renderer.root;
+// {
+//   type: "div",
+//   props: { class: "app" },
+//   children: [ ... ],
+//   key: undefined
+// }
+```
+
+The `JsonNode` type:
+
+```ts
+type JsonNode = {
+  type: string;
+  props: Record<string, unknown>;
+  children: JsonNode[];
+  key?: string | number;
+};
+```
+
+### StringRender
+
+Produces an HTML string from the virtual DOM. Useful for server-side rendering.
+
+```ts
+import { createApp, StringRender } from "creo";
+
+const renderer = new StringRender();
+createApp(() => App(), renderer).mount();
+
+const html: string = renderer.renderToString();
+// "<div><h1>Hello</h1><p>World</p></div>"
+```
+
+`StringRender` is pull-based -- `render()` and `unmount()` are essentially no-ops. Call `renderToString()` to walk the virtual DOM and build the HTML string on demand.
+
+## The IRender interface
+
+All renderers implement `IRender<Output>`:
+
+```ts
+interface IRender<Output> {
+  /** Create output if view is new, or update if existing. */
+  render(view: BaseView): void;
+
+  /** Remove a view's output artifacts. Called on disposal. */
+  unmount(view: BaseView): void;
+
+  /** Register render handlers for custom primitive components. */
+  registerPrimitive(
+    entries: [PrimitiveComponent<any, any>, PrimitiveRenderHandler<Output>][],
+  ): void;
+}
+```
+
+The `Output` type parameter describes what each primitive produces (e.g., `HTMLElement | Text` for HtmlRender, `JsonNode` for JsonRender, `string` for StringRender).
+
+## Custom renderers
+
+To create a custom renderer, implement `IRender<YourOutput>`:
+
+```ts
+import type { IRender, PrimitiveRenderHandler } from "creo";
+import type { PrimitiveComponent } from "creo";
+import type { BaseView } from "creo"; // available via internal types
+
+class CanvasRender implements IRender<void> {
+  private ctx: CanvasRenderingContext2D;
+
+  constructor(canvas: HTMLCanvasElement) {
+    this.ctx = canvas.getContext("2d")!;
+  }
+
+  render(view: BaseView): void {
+    // Draw or update based on view.props, view.renderRef, etc.
+  }
+
+  unmount(view: BaseView): void {
+    // Clean up any resources
+    view.renderRef = undefined;
+  }
+
+  registerPrimitive(
+    entries: [PrimitiveComponent<any, any>, PrimitiveRenderHandler<void>][],
+  ): void {
+    // Store handlers for custom primitives
+  }
+}
+```
+
+## Registering custom primitives
+
+When you create a primitive with `primitive()` (not `html()`), you must register a render handler on the renderer so it knows how to produce output:
+
+```ts
+import { primitive, createApp, HtmlRender } from "creo";
+
+// Define a custom primitive
+const sparkline = primitive<{ data: number[]; width: number; height: number }>();
+
+// Create renderer and register the handler
+const renderer = new HtmlRender(document.getElementById("app")!);
+renderer.registerPrimitive([
+  [sparkline, {
+    render(view) {
+      const canvas = document.createElement("canvas");
+      canvas.width = view.props.width;
+      canvas.height = view.props.height;
+      // draw sparkline on canvas...
+      return canvas;
+    },
+  }],
+]);
+
+// Now sparkline() can be used in render functions
+createApp(() => App(), renderer).mount();
+```
+
+The `PrimitiveRenderHandler<Output>` interface:
+
+```ts
+interface PrimitiveRenderHandler<Output> {
+  render(view: BaseView): Output;
+}
+```
+
+## Scheduler integration
+
+The renderer is paired with a scheduler via `createApp` options. The scheduler controls when re-renders happen:
+
+```ts
+// Default: queueMicrotask (immediate, within same task)
+createApp(() => App(), new HtmlRender(el)).mount();
+
+// requestAnimationFrame (synced to display refresh)
+createApp(() => App(), new HtmlRender(el), {
+  scheduler: requestAnimationFrame,
+}).mount();
+
+// Custom scheduler
+createApp(() => App(), new HtmlRender(el), {
+  scheduler: (cb) => setTimeout(cb, 16),
+}).mount();
+```
+
+The `Scheduler` type is `(callback: () => void) => void`.

package/docs/state.md

@@ -0,0 +1,131 @@
+# State
+
+Creo's state system provides reactive values that trigger re-renders when changed.
+
+## Creating state
+
+Call `use(initial)` in the view function body (before `return`):
+
+```ts
+import { view, text } from "creo";
+
+const Counter = view(({ use }) => {
+  const count = use(0);
+  const name = use("untitled");
+  const items = use<string[]>([]);
+
+  return {
+    render() {
+      text(String(count.get()));
+    },
+  };
+});
+```
+
+### Rules
+
+- Call `use()` **before** returning the ViewBody, never inside `render()`.
+- Call order must be stable across re-renders (same as React hooks). Do not call `use()` inside conditionals or loops.
+- On the first render, `use(initial)` creates a new `Reactive<T>` instance. On subsequent renders, it returns the existing instance at the same position (the `initial` argument is ignored).
+
+## Reading state
+
+Use `.get()` to read the current value:
+
+```ts
+const count = use(0);
+
+return {
+  render() {
+    text(String(count.get())); // reads current value
+  },
+};
+```
+
+`.get()` always returns the latest committed value, including any changes made by `.set()` or `.update()` earlier in the same cycle.
+
+## Setting state
+
+### .set(value)
+
+Replace the current value and schedule a re-render:
+
+```ts
+const name = use("Alice");
+
+const rename = () => name.set("Bob");
+```
+
+`.set()` applies the value **immediately** -- calling `.get()` right after `.set()` returns the new value. A re-render is then scheduled through the engine's scheduler.
+
+### .update(fn)
+
+Apply a function to the current value:
+
+```ts
+const count = use(0);
+
+const increment = () => count.update(n => n + 1);
+const decrement = () => count.update(n => n - 1);
+```
+
+Like `.set()`, the update is applied immediately and a re-render is scheduled.
+
+### Async updates
+
+`.update()` also accepts async functions. The value is applied and render is scheduled when the promise resolves:
+
+```ts
+const data = use<string[]>([]);
+
+const fetchData = () => data.update(async current => {
+  const response = await fetch("/api/items");
+  const items = await response.json();
+  return items;
+});
+```
+
+## State vs plain variables
+
+Use `use()` for values that should trigger re-renders when they change. For ephemeral values that do not affect the rendered output, a plain `let` variable is sufficient:
+
+```ts
+const MyComponent = view(({ use }) => {
+  const count = use(0);        // reactive -- triggers re-render on change
+  let lastClickTime = 0;       // not reactive -- no re-render needed
+
+  const handleClick = () => {
+    lastClickTime = Date.now();
+    count.update(n => n + 1);
+  };
+
+  return {
+    render() {
+      button({ on: { click: handleClick } }, () => {
+        text(String(count.get()));
+      });
+    },
+  };
+});
+```
+
+## The Reactive interface
+
+Both `use(initial)` (local state) and `use(store)` (store binding) return `Reactive<T>`:
+
+```ts
+import type { Reactive } from "creo";
+
+function doubleReactive(r: Reactive<number>): void {
+  r.update(n => n * 2);
+}
+```
+
+### Full API
+
+| Method | Description |
+|--------|-------------|
+| `.get(): T` | Read the current value |
+| `.set(value: T): void` | Set a new value immediately, schedule re-render |
+| `.update(fn: (current: T) => T): void` | Apply a sync transform, schedule re-render |
+| `.update(fn: (current: T) => Promise<T>): void` | Apply an async transform, schedule re-render on resolve |