creo 0.0.4-dev → 0.2.0

package/README.md

@@ -1 +1,276 @@
-Work in progress, stay tuned
+# Creo
+
+> _"There is a point of no return"_
+
+- A "streaming" UI framework.
+- No JSX, no templates, no compiler — views are function calls that flow top-down, rendered as they execute.
+- Simplicity over tons of features
+
+## Philosophy
+
+### Streaming the UI
+
+Most frameworks build a tree and diff it. Creo streams it. When `render()` runs, each `div()`, `text()`, `span()` call immediately registers a child in sequence — there is no intermediate representation between your code and the virtual DOM. The render function IS the tree, read top to bottom. What you call is what you get, in the order you call it.
+
+```ts
+render() {
+  h1({}, () => text("Title"));     // first child
+  p({}, () => text("Paragraph"));  // second child
+  ul({}, () => {                   // third child, with its own children streamed inside
+    li({}, () => text("One"));
+    li({}, () => text("Two"));
+  });
+}
+```
+
+### Native control flow
+
+No `v-if`, no `{condition && <X/>}`, no `.map()` wrappers. Creo renders imperatively — use `if`, `for`, `while`, `switch`, or any JavaScript you want. The language IS the template language.
+
+```ts
+render() {
+  if (loading.get()) {
+    Spinner();
+  } else if (error.get()) {
+    ErrorBanner({ message: error.get() });
+  } else {
+    for (const item of items.get()) {
+      ListItem({ key: item.id, data: item });
+    }
+  }
+}
+```
+
+Say _NO_ to:
+
+- special syntax to learn.
+- framework-specific iteration helpers.
+- ternary gymnastics.
+
+### Minimal model
+
+The entire reactivity model is three concepts:
+
+- **`use(value)`** — local state. Call `.get()`, `.set()`, `.update()`. That's it.
+- **`store.new(value)`** — global state. Same interface. Any view can subscribe with `use(store)`.
+- **`props()`** — read-only, passed by parent. A function call, not a magic object.
+
+No:
+
+- Computed properties
+- Watchers
+- Dependency arrays
+- Selectors
+
+State is explicit: you set it, you read it, you control when things update via `shouldUpdate`.
+
+One of major ideas under the framework "if user can do it with same efficiency, let it outside framework zone"
+
+### Pluggable renderers
+
+Creo allows any renderer overrides.
+
+- **`HtmlRender`** — DOM output for browsers
+- **`JsonRender`** — JSON AST for testing and serialization
+- **`StringRender`** — HTML strings for SSR
+
+```ts
+// Browser
+createApp(() => App(), new HtmlRender(document.getElementById("app")!)).mount();
+
+// Server
+const renderer = new StringRender();
+const engine = new Engine(renderer);
+engine.createRoot(() => App(), {});
+engine.render();
+return renderer.renderToString();
+```
+
+## Quick Start
+
+```ts
+import { createApp, view, div, text, button } from "creo";
+import { HtmlRender } from "creo";
+
+const Counter = view<{ initial: number }>(({ props, use }) => {
+  const count = use(props().initial);
+  const increment = () => count.update((n) => n + 1);
+
+  return {
+    render() {
+      button({ onClick: increment }, () => {
+        text(count.get());
+      });
+    },
+  };
+});
+
+createApp(
+  () => Counter({ initial: 0 }),
+  new HtmlRender(document.getElementById("app")!),
+).mount();
+```
+
+## Core Concepts
+
+### Views
+
+Views are components. Define them with `view<Props>()`, which takes a setup function called once per lifecycle. The setup returns a `ViewBody` with a `render()` function called on every update.
+
+```ts
+const Greeting = view<{ name: string }>(({ props }) => ({
+  render() {
+    div({ class: "greeting" }, () => {
+      text(`Hello, ${props().name}!`);
+    });
+  },
+}));
+
+// Usage in another view's render:
+Greeting({ name: "world" });
+```
+
+### State
+
+Local reactive state via `use()`. Called once in the setup function, read via `.get()` in render.
+
+```ts
+const Toggle = view(({ use }) => {
+  const on = use(false);
+  const toggle = () => on.update((v) => !v);
+
+  return {
+    render() {
+      button({ onClick: toggle }, () => {
+        text(on.get() ? "ON" : "OFF");
+      });
+    },
+  };
+});
+```
+
+### Store
+
+Global shared state. Create outside views, subscribe inside with `use(store)`.
+
+```ts
+import { store } from "creo";
+
+const ThemeStore = store.new<"light" | "dark">("light");
+
+// Any view can subscribe:
+const ThemeDisplay = view(({ use }) => {
+  const theme = use(ThemeStore);
+  return {
+    render() {
+      text(`Theme: ${theme.get()}`);
+    },
+  };
+});
+
+// Update from anywhere:
+ThemeStore.set("dark");
+```
+
+### Slots (Children)
+
+Pass children via a slot callback — the second argument to any view or primitive.
+
+```ts
+const Card = view<{ title: string }>(({ props, slot }) => ({
+  render() {
+    div({ class: "card" }, () => {
+      h1({}, () => text(props().title));
+      div({ class: "card-body" }, slot);
+    });
+  },
+}));
+
+// Usage:
+Card({ title: "Hello" }, () => {
+  p({}, () => text("Card content here."));
+});
+```
+
+### Lifecycle Hooks
+
+```ts
+const MyView = view<{ value: number }>(({ props }) => ({
+  onMount() {
+    /* after first render */
+  },
+  onUpdateBefore() {
+    /* before re-render */
+  },
+  onUpdateAfter() {
+    /* after re-render */
+  },
+  shouldUpdate(nextProps) {
+    return nextProps.value !== props().value;
+  },
+  render() {
+    text(props().value);
+  },
+}));
+```
+
+### Keyed Lists
+
+Use `key` in props for efficient list reconciliation:
+
+```ts
+for (const item of items.get()) {
+  TodoItem({ key: item.id, text: item.text, done: item.done });
+}
+```
+
+### Conditional Rendering
+
+Standard JavaScript control flow — no special syntax:
+
+```ts
+render() {
+  if (editing.get()) {
+    Editor({ key: id, value });
+  } else {
+    Display({ key: id, value });
+  }
+}
+```
+
+## Router
+
+Hash-based router available as `creo-router` (separate package):
+
+```ts
+import { createRouter } from "creo-router";
+
+const { routeStore, navigate, RouterView, Link } = createRouter({
+  routes: [
+    { path: "/", view: () => HomePage() },
+    { path: "/users/:id", view: () => UserPage() },
+  ],
+  fallback: () => NotFoundPage(),
+});
+
+// Navigation:
+Link({ href: "/users/42" }, () => text("User 42"));
+navigate("/users/42"); // programmatic
+
+// Read params:
+const route = use(routeStore);
+route.get().params.id; // "42"
+```
+
+## Development
+
+```bash
+bun install
+bun test src/          # Run tests
+bun tsc      # Type-check
+bun run build          # Build to dist/
+
+# Run examples:
+cd examples/todo && bun install && bun run dev
+cd examples/router && bun install && bun run dev
+```

package/dist/functional/assert.d.ts

@@ -0,0 +1 @@
+export declare function assertNever(x: never): never;

package/dist/functional/key.d.ts

@@ -0,0 +1,2 @@
+export type Key = number | string;
+export declare function generateNextKey(): string;

package/dist/functional/lis.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Longest Increasing Subsequence — O(n log n).
+ *
+ * Given an array of numbers, returns the Set of *indices* into that array
+ * whose elements form the longest strictly increasing subsequence.
+ * Entries equal to -1 are skipped (treated as "not present").
+ *
+ * Used by the keyed reconciler to identify the maximal set of children
+ * that are already in correct relative order and don't need DOM moves.
+ */
+export declare function lis(arr: number[]): Set<number>;

package/dist/functional/maybe.d.ts

@@ -0,0 +1,8 @@
+export type None = null | undefined;
+export type Just<T> = T;
+export type Maybe<T> = Just<T> | None;
+export declare function just<T>(maybe: Maybe<T>, errorMessage?: string): asserts maybe is Just<T>;
+export declare function isJust<T>(maybe: Maybe<T>): maybe is Just<T>;
+export declare function isNone<T>(maybe: Maybe<T>): maybe is None;
+export declare function withDefault<T, K>(v: Maybe<T>, alternative: K): K | NonNullable<T>;
+export declare const _: undefined;

package/dist/functional/maybe_promise.d.ts

@@ -0,0 +1 @@
+export type MaybePromise<T> = T | Promise<T>;

package/dist/functional/shallow_equal.d.ts

@@ -0,0 +1,2 @@
+import type { Wildcard } from "../internal/wildcard";
+export declare function shallowEqual(a: Wildcard, b: Wildcard): boolean;

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { createApp } from "./public/app";
+export { view } from "./public/view";
+export type { ViewBody, ViewFn, Slot, PublicView } from "./public/view";
+export type { Reactive, Use } from "./public/state";
+export { State } from "./public/state";
+export { Store, store, isStore } from "./public/store";
+export { $primitive } from "./public/primitive";
+export type { PrimitiveProps, EventHandlerProps } from "./public/primitive";
+export { html, text, div, span, section, article, aside, nav, header, footer, main, address, hgroup, search, p, h1, h2, h3, h4, h5, h6, pre, code, em, strong, small, br, hr, a, blockquote, label, abbr, b, bdi, bdo, cite, data, dfn, i, kbd, mark, q, rp, rt, ruby, s, samp, sub, sup, time, u, varEl, wbr, del, ins, ul, ol, li, dl, dt, dd, table, thead, tbody, tfoot, tr, th, td, caption, colgroup, col, form, button, input, textarea, select, option, fieldset, legend, datalist, optgroup, output, progress, meter, img, video, audio, canvas, source, track, map, area, picture, iframe, embed, object, portal, svg, details, summary, dialog, menu, figure, figcaption, script, noscript, template, slot, } from "./public/primitives/primitives";
+export type { BaseEventData, PointerEventData, KeyEventData, InputEventData, FocusEventData, ContainerEvents, FormEvents, HtmlAttrs, } from "./public/primitives/primitives";
+export type { IRender } from "./render/render_interface";
+export { HtmlRender } from "./render/html_render";
+export { JsonRender } from "./render/json_render";
+export type { JsonNode } from "./render/json_render";
+export { HtmlStringRender, StringRender } from "./render/string_render";
+export { Engine, type Scheduler } from "./internal/engine";
+export { type Maybe, type None, type Just, just, withDefault, _ } from "./functional/maybe";
+export type { Key } from "./functional/key";
+export { shallowEqual } from "./functional/shallow_equal";
+export { assertNever } from "./functional/assert";