creo 0.2.5 → 0.2.7

package/docs/store.md

@@ -0,0 +1,135 @@
+# Store
+
+Creo's store system provides globally visible reactive data. A store is created outside views and can be read/written from any view via `use()`.
+
+## Creating a store
+
+Use `store.new(initial)` at module scope:
+
+```ts
+import { store } from "creo";
+
+const ThemeStore = store.new<"light" | "dark">("light");
+const UserStore = store.new<{ name: string; role: string } | null>(null);
+```
+
+Store instances are typically defined at module scope and imported where needed.
+
+## Reading from a view
+
+Use `use(store)` inside a view function to subscribe and get a reactive accessor:
+
+```ts
+import { view, div, text } from "creo";
+
+const ThemedButton = view(({ use }) => {
+  const theme = use(ThemeStore); // re-renders when ThemeStore changes
+
+  return {
+    render() {
+      button({ class: theme.get() === "dark" ? "btn-dark" : "btn-light" }, () => {
+        text("Click me");
+      });
+    },
+  };
+});
+```
+
+`use(store)` subscribes the view to changes. When the store value is updated via `.set()` or `.update()`, all subscribed views are scheduled for re-render. Subscriptions are automatically cleaned up when the view is disposed.
+
+## Setting values
+
+Call `.set()` or `.update()` on the store directly -- from anywhere, including outside views:
+
+```ts
+// From a handler
+const toggle = () => {
+  const current = ThemeStore.get();
+  ThemeStore.set(current === "light" ? "dark" : "light");
+};
+
+// From outside any view
+ThemeStore.set("dark");
+
+// Using update
+ThemeStore.update(current => current === "light" ? "dark" : "light");
+```
+
+## Complete example
+
+```ts
+import { createApp, store, view, div, button, span, text, HtmlRender } from "creo";
+
+// 1. Create the store
+const CounterStore = store.new(0);
+
+// 2. Writer component
+const IncrementButton = view(({ use }) => {
+  const counter = use(CounterStore);
+  const increment = () => counter.update(n => n + 1);
+
+  return {
+    render() {
+      button({ on: { click: increment } }, () => { text("+1"); });
+    },
+  };
+});
+
+// 3. Reader component
+const DisplayCount = view(({ use }) => {
+  const counter = use(CounterStore);
+
+  return {
+    render() {
+      span({}, () => {
+        text(`Count: ${counter.get()}`);
+      });
+    },
+  };
+});
+
+// 4. App
+const App = view(() => ({
+  render() {
+    div({}, () => {
+      IncrementButton();
+      DisplayCount();
+    });
+  },
+}));
+
+// 5. Mount
+createApp(() => App(), new HtmlRender(document.getElementById("app")!)).mount();
+```
+
+## Store vs State
+
+Both store and local state use the same `use()` function and return the same `Reactive<T>` interface (`get`, `set`, `update`). The difference:
+
+| | Store | State |
+|---|---|---|
+| Created with | `store.new(initial)` | `use(initial)` inside a view |
+| Scope | Global -- shared across views | Local -- private to the view |
+| Setting from outside | `MyStore.set(value)` | Not possible |
+| Subscribes view | Yes -- `use(store)` re-renders on change | Yes -- `use(value)` re-renders on change |
+
+## Store type
+
+The `Store<T>` class is exported for type annotations:
+
+```ts
+import type { Store } from "creo";
+
+function resetStore<T>(s: Store<T>, value: T): void {
+  s.set(value);
+}
+```
+
+### Full API
+
+| Method | Description |
+|--------|-------------|
+| `.get(): T` | Read the current value |
+| `.set(value: T): void` | Set a new value, re-render all subscribers |
+| `.update(fn: (current: T) => T): void` | Apply a sync transform, re-render subscribers |
+| `.update(fn: (current: T) => Promise<T>): void` | Apply an async transform, re-render on resolve |

package/docs/view.md

@@ -0,0 +1,205 @@
+# view()
+
+`view()` is the core API for defining components in Creo.
+
+## Signature
+
+```ts
+function view<Props = void, Api = void>(
+  viewFn: ViewFn<Props, Api>
+): (props: Props & { key?: Key }, slot?: Slot) => void;
+```
+
+When `Props` is `void` (no props), the returned function can be called with no arguments:
+
+```ts
+const App = view((ctx) => ({
+  render() { /* ... */ },
+}));
+
+App(); // no args needed
+```
+
+## ViewFn and context
+
+The function passed to `view()` receives a **context object** (`ctx`) with three fields:
+
+```ts
+const MyComponent = view<{ title: string }>((ctx) => {
+  // ctx.props    -- function that returns the current props object
+  // ctx.use      -- factory to create reactive state or subscribe to stores
+  // ctx.children -- pre-collected PendingView[] from the parent slot
+
+  return {
+    render() { /* ... */ },
+  };
+});
+```
+
+### ctx.props
+
+A function that returns the current props passed by the parent. Call `ctx.props()` to read:
+
+```ts
+const Label = view<{ text: string }>((ctx) => ({
+  render() {
+    span({}, () => { text(ctx.props().text); });
+  },
+}));
+```
+
+Because `props` is a function, calling it always returns the latest values -- whether inside `render()`, lifecycle hooks, or event handlers:
+
+```ts
+const Good = view<{ title: string }>((ctx) => ({
+  render() { text(ctx.props().title); }, // always current
+}));
+```
+
+### ctx.use
+
+A factory function to create reactive state or subscribe to stores. See [State](./state.md) and [Store](./store.md).
+
+```ts
+const count = ctx.use(0);            // Reactive<number> — local state
+const items = ctx.use<string[]>([]); // Reactive<string[]> — local state
+const theme = ctx.use(ThemeStore);   // Reactive<string> — store subscription
+```
+
+### ctx.children
+
+An array of `PendingView` objects representing the children passed by the caller's slot. Pass `ctx.children` directly to a primitive's second argument to render them:
+
+```ts
+const Wrapper = view((ctx) => ({
+  render() {
+    div({ class: "wrapper" }, ctx.children);
+  },
+}));
+```
+
+If the caller provided no slot, `ctx.children` is an empty array.
+
+## ViewBody
+
+The viewFn must return a `ViewBody` object. The only required field is `render`:
+
+```ts
+type ViewBody<Props, Api> = {
+  render: () => void;
+  mount?: {
+    before?: () => void;
+    after?: () => void;
+  };
+  update?: {
+    should?: (nextProps: Props) => boolean;
+    before?: () => void;
+    after?: () => void;
+  };
+};
+```
+
+When `Api` is provided (not `void`), ViewBody also includes an `api` field. See [Exposing an API](#exposing-an-api) below.
+
+### render()
+
+Called on every render cycle. Inside `render()`, call primitives and child components imperatively. The order of calls defines the virtual DOM structure:
+
+```ts
+render() {
+  div({ class: "header" }, () => {
+    h1({}, () => { text("Title"); });
+  });
+  div({ class: "body" }, () => {
+    text("Content");
+  });
+}
+```
+
+All standard JavaScript control flow works inside render:
+
+```ts
+render() {
+  if (isEditing.get()) {
+    input({ value: draft.get(), on: { input: handleInput } });
+  } else {
+    span({}, () => { text(value.get()); });
+  }
+
+  for (const item of items.get()) {
+    ListItem({ key: item.id, data: item });
+  }
+}
+```
+
+### Lifecycle hooks
+
+See [Lifecycle](./lifecycle.md) for details on `mount` and `update`.
+
+## Calling components
+
+Components are called as functions. The first argument is props, the second is an optional slot:
+
+```ts
+// No props, no children
+MyComponent();
+
+// With props
+Counter({ initial: 5 });
+
+// With children (slot)
+Card({}, () => {
+  text("Inside the card");
+});
+
+// With props and children
+Section({ title: "Info" }, () => {
+  Paragraph({ text: "Details here" });
+});
+```
+
+### Keys
+
+Pass `key` in the props object to help reconciliation identify items across re-renders:
+
+```ts
+for (const user of users.get()) {
+  UserCard({ key: user.id, name: user.name });
+}
+```
+
+## Exposing an API via `ref`
+
+Both primitives and composite views accept a `ref` prop on the call site, and
+both fill it through the same `Ref<T>` machinery. The difference is on the
+provider side: the renderer pushes the DOM `Element` into a primitive's ref;
+inside a composite, you push an API object yourself by calling `ctx.ref(...)`.
+
+```ts
+import { view, type RefObject } from "creo";
+
+const TextInput = view<{ placeholder: string }, { focus: () => void }>(
+  ({ props, ref }) => {
+    const inputRef: RefObject<HTMLInputElement> = { current: null };
+    ref({
+      focus: () => inputRef.current?.focus(),
+    });
+    return {
+      render() {
+        input({ placeholder: props().placeholder, ref: inputRef });
+      },
+    };
+  },
+);
+
+// Consumer:
+const myInput: RefObject<{ focus: () => void }> = { current: null };
+TextInput({ placeholder: "Email", ref: myInput });
+// After mount:
+myInput.current?.focus();
+```
+
+`ref` works the same on primitives — `div({ ref })` populates `.current` (or
+fires the callback) with the underlying `Element` after mount, and `null` on
+unmount. The provider verb is `ctx.ref(...)` on a composite; the consumer
+noun is `ref` in props on either side.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "creo",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -12,7 +12,10 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "docs"
   ],
   "scripts": {
     "build": "bun run build.ts",

package/dist/public/event_handle.d.ts

@@ -1,32 +0,0 @@
-import type { Wildcard } from "../internal/wildcard";
-type EventCallback = (...args: Wildcard[]) => void;
-/**
- * Delegate that the renderer provides to wire event subscriptions
- * to the actual output (DOM addEventListener, etc.).
- * Set on the EventHandle after the view's output is created.
- */
-export type EventDelegate = {
-    bind(event: string, callback: EventCallback, once?: boolean): void;
-    unbind(event: string, callback: EventCallback): void;
-};
-/**
- * Handle returned when calling a primitive in the render stream.
- * Provides on/once/off for event subscription.
- *
- * When a delegate is set (by the renderer after mount), calls are
- * proxied to the renderer — only events the user subscribes to
- * get bound. Before the delegate exists, listeners are stored and
- * flushed once the delegate arrives.
- */
-export declare class EventHandle<Events> {
-    #private;
-    on<K extends keyof Events>(event: K, callback: Events[K]): void;
-    once<K extends keyof Events>(event: K, callback: Events[K]): void;
-    off<K extends keyof Events>(event: K, callback: Events[K]): void;
-    /**
-     * Called by the renderer after the view's output is created.
-     * Flushes any listeners that were added before the delegate existed.
-     */
-    setDelegate(delegate: EventDelegate): void;
-}
-export {};

package/dist/render/canvas_render.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/render/stream_render.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/structures/indexed_list.d.ts

@@ -1,46 +0,0 @@
-/**
- * IndexedList — linked list with O(1) identity-based lookup.
- *
- * Combines a doubly-linked list (O(1) insert/delete given a node)
- * with a Map<T, INode<T>> for O(1) lookup by value identity.
- *
- * All mutating operations are O(1):
- *   push, delete, has, first, last, clear
- */
-import { type INode } from "./list";
-import type { Maybe } from "../functional/maybe";
-export declare class IndexedList<T> {
-    #private;
-    /** Append item to the end. No-op if already present. Returns the node. */
-    push(item: T): INode<T>;
-    /** Insert item at the front. No-op if already present. */
-    unshift(item: T): void;
-    /** Insert item after ref. No-op if item already present. */
-    insertAfter(ref: T, item: T): void;
-    /** Remove item. O(1). */
-    delete(item: T): void;
-    /** Check membership. O(1). */
-    has(item: T): boolean;
-    /** Number of items. */
-    get length(): number;
-    /** Get the first item (head). O(1). */
-    first(): Maybe<T>;
-    /** Get the last item (tail). O(1). */
-    last(): Maybe<T>;
-    /** Get the linked-list node for an item. O(1). */
-    getNode(item: T): Maybe<INode<T>>;
-    /** Positional access. O(n) — prefer getNode + getNext for traversal. */
-    at(index: number): Maybe<T>;
-    /**
-     * Replace item at `pos`, or insert if nothing is there.
-     * If `pos >= length`, appends to the end.
-     * Returns the node.
-     */
-    upsert(pos: number, item: T): INode<T>;
-    /** Swap two items in the list. O(1). No-op if either item is missing. */
-    swap(a: T, b: T): void;
-    /** Reset to empty. O(1). */
-    clear(): void;
-    /** Iterate values in insertion order. */
-    [Symbol.iterator](): IterableIterator<T>;
-}

package/dist/structures/list.d.ts

@@ -1,68 +0,0 @@
-/**
- * Linked list implementation
- */
-import type { Maybe } from "../functional/maybe";
-declare const $next: unique symbol;
-declare const $prev: unique symbol;
-declare const $owner: unique symbol;
-export interface INode<T> {
-    insertNext(value: T): INode<T>;
-    insertPrev(value: T): INode<T>;
-    v: T;
-    delete(): void;
-    getNext(): Maybe<INode<T>>;
-    getPrev(): Maybe<INode<T>>;
-    isFirst(): boolean;
-    isLast(): boolean;
-}
-export declare class ListNode<T> implements INode<T> {
-    [$owner]: Maybe<IBaseContainer<T>>;
-    [$next]: Maybe<ListNode<T>>;
-    [$prev]: Maybe<ListNode<T>>;
-    v: T;
-    constructor(node: T, prev: Maybe<ListNode<T>>, next: Maybe<ListNode<T>>, list: IBaseContainer<T>);
-    isFirst(): boolean;
-    isLast(): boolean;
-    delete(): void;
-    clearFields(): void;
-    insertNext(value: T): INode<T>;
-    insertPrev(value: T): INode<T>;
-    getNext(): Maybe<ListNode<T>>;
-    getPrev(): Maybe<ListNode<T>>;
-    getList(): Maybe<IBaseContainer<T>>;
-}
-interface IBaseContainer<T> {
-    delete(node: INode<T>): void;
-    insertNext(ref: INode<T>, value: T): INode<T>;
-    insertPrev(ref: INode<T>, value: T): INode<T>;
-}
-export interface IList<T> extends Iterable<INode<T>>, IBaseContainer<T> {
-    insertStart(value: T): INode<T>;
-    insertEnd(value: T): INode<T>;
-    at(n: number): Maybe<INode<T>>;
-    first(): Maybe<INode<T>>;
-    last(): Maybe<INode<T>>;
-    readonly size: number;
-    [Symbol.iterator](): IterableIterator<INode<T>>;
-}
-export declare class InternalList<T> implements IList<T> {
-    #private;
-    insertStart(value: T): ListNode<T>;
-    delete(node: INode<T>): void;
-    at(n: number): Maybe<ListNode<T>>;
-    get size(): number;
-    /** Reset the list to empty. O(1). */
-    clear(): void;
-    /** O(1) head access. */
-    first(): Maybe<ListNode<T>>;
-    /** O(1) tail access. */
-    last(): Maybe<ListNode<T>>;
-    insertEnd(value: T): ListNode<T>;
-    insertNext(ref: INode<T>, value: T): ListNode<T>;
-    insertPrev(ref: INode<T>, value: T): ListNode<T>;
-    [Symbol.iterator](): Generator<ListNode<T>, void, unknown>;
-}
-export declare class List<T> extends InternalList<T> implements IList<T> {
-    static from<T>(arrayLike: Iterable<T>): List<T>;
-}
-export {};