@papack/csr 0.0.2 → 1.0.0

package/readme.md

@@ -1,72 +1,45 @@
 # @papack/csr
 
-Async UI Dom runtime (experimental) .Designed for **predictability over comfort** — which, in practice, _creates_ comfort.
-No Virtual DOM. No content diffing.
-Instead: **real mutation**, **async components**, **deterministic structural updates**.
+**Experimental synchronous UI DOM runtime.**
+Designed for **simplicity, explicitness, and predictability**.
 
-Zero dependencies. Fully TypeScript.
+> **No feature is the feature.**
 
-## Features
-
-- Async components (`await` directly inside components)
-- Deterministic rendering without a Virtual DOM
-- `signal` / `effect` as minimal reactivity primitives
-- Explicit lifecycle (`mount`, `unmount`, `destroy`)
-- Keyed `For` with stable DOM identity
-- Structural conditional rendering (`Show`)
-- Mutation is allowed (by design)
-- Fully TypeScript
-
-## Core Ideas
-
-- **Async components are first-class**
+No Virtual DOM.
+No diffing.
+No scheduler.
+No hidden async.
 
-  ```ts
-  async function User() {
-    const data = await fetch("/api/user").then((r) => r.json());
-    return <div>{data.name}</div>;
-  }
-  ```
+Just **real DOM**, **real mutation**, and **deterministic structure** with zero dependencies.
 
-- **Signals are active sources**
+---
 
-  - no reference equality checks
-  - mutation is allowed
-  - every `set()` reliably triggers effects
+## Philosophy
 
-- **Lifecycle is bound to real DOM nodes**
+This library is **simple by design**, not “easy”.
 
-  - `mount` / `unmount` attach to actual elements
-  - for: reordering ≠ remounting
-  - removal = real `destroy`
+- There is **one way** to do things
+- Everything is **explicit**
 
-## Example
+It _is_ optimized for **clarity and long-term maintenance**.
 
-```ts
-import { jsx, render, signal } from "../core";
-import { For } from "../core/for";
-
-const [items, setItems] = signal([
-  { uuid: "a", name: "A" },
-  { uuid: "b", name: "B" },
-]);
+---
 
-render(<App />, { parent: document.body });
+## Features
 
-function App() {
-  return (
-    <ul>
-      <For each={items}>{(item) => <li>{item.name}</li>}</For>
-    </ul>
-  );
-}
-```
+- Fully **synchronous rendering**
+- No Virtual DOM, no reconciliation
+- Minimal reactivity via `signal` / `effect`
+- Explicit lifecycle (`mount`, `unmount`)
+- Structural primitives (`Show`, `For`)
 
 ---
 
-## `signal`
+## Core Ideas
+
+### Signals are active state
 
-Signals are **active state containers**, not passive values.
+Signals are **sources**, not values.
 
 ```ts
 const [count, setCount] = signal(0);
@@ -75,16 +48,12 @@ setCount((v) => v + 1);
 setCount(() => 42);
 ```
 
-### Properties
-
-- `set()` **always triggers**
 - no equality checks
+- no dependency tracking
 - mutation is allowed
-- async setters are allowed
-
-## `effect(readFn, callback)`
+- every write notifies every subscriber
 
-Subscribes to a signal and reacts to changes.
+### Effects are explicit reactions to signals
 
 ```ts
 effect(count, (value) => {
@@ -92,132 +61,117 @@ effect(count, (value) => {
 });
 ```
 
-### Characteristics
+Characteristics:
 
 - runs immediately with the current value
-- runs on **every** `set()`
-- no dependency tracking
-- async callbacks supported
+- runs on **every** write
+- only one singal, no dependency arrays
+- async callbacks are allowed (fire-and-forget)
 
-```ts
-effect(userId, async (id) => {
-  const user = await fetch(`/api/user/${id}`).then((r) => r.json());
-});
-```
+> Effects are **not awaited**.
+> Concurrency is explicit and intentional.
 
-````md
-## Context Injection
+### Lifecycle is bound to real DOM
 
-`render()` accepts arbitrary values on the top-level context.  
-This context is automatically available in **every component** via `props.ctx`.
+Lifecycle is structural, not conceptual.
 
 ```ts
-render(<App />, {
-  parent: document.body,
-  api,
-  events,
-  dummy: 42,
+mount((parent) => {
+  // runs once, when the root DOM element exists
 });
-```
-````
 
-```ts
-function Item(p: any) {
-  console.log(p.ctx.dummy); // 42
-  p.ctx.api.fetch();
-}
+unmount(() => {
+  // guaranteed cleanup before removal
+});
 ```
 
-- no providers
-- no hooks
-- no imports
-- no reactivity
-
-Context is for **stable infrastructure** (stores, APIs, event buses),
-not for frequently changing UI state.
+- lifecycle is attached to **actual DOM nodes**
+- children unmount before parents
+- removal means real `destroy`
 
-The context is immutable for the lifetime of the render tree and
-does not trigger re-renders.
+---
 
-## Lifecycle Primitives
+## Example
 
-Lifecycle is **explicit** and **structural**.
+```ts
+import { render, signal } from "@papack/csr";
+import { For } from "@papack/csr/for";
 
-### `mount(fn)`
+const [items, setItems] = signal([
+  { uuid: "a", name: "A" },
+  { uuid: "b", name: "B" },
+]);
 
-Registers a callback that runs **once**, when the component’s root DOM element
-is attached.
+render(<App />, { parent: document.body });
 
-```ts
-mount((parent) => {
-  // parent === root Element
-});
+function App() {
+  return (
+    <ul>
+      <For each={items}>{(item) => <li>{item.name}</li>}</For>
+    </ul>
+  );
+}
 ```
 
-- runs exactly once per component instance
-- runs after the DOM node exists
-- used for subscriptions, timers, imperative DOM work
+## Structural Rendering
 
-### `unmount(fn)`
+### `Show`
 
-Registers cleanup logic tied to the component’s root element.
+Controls **existence**, not visibility.
 
 ```ts
-unmount(() => {
-  // cleanup
-});
+<Show when={visible}>
+  <User />
+</Show>
 ```
 
-- runs exactly once
-- runs before DOM removal
-- children unmount before parents
-- guaranteed execution
+- when `false`, the subtree is destroyed
+- when `true`, it is rendered fresh
+- lifecycle runs correctly on both transitions
 
-## `For` (intentionally restricted)
+### `For` (intentionally restricted)
 
-`For` is **not** a general iterator.
-It is a **keyed structural renderer**.
+`For` is a **keyed structural renderer**, not a generic iterator.
 
-### Rules
+Rules:
 
-- `each` **must** bet an array
-- each item **must** be an object
-- each object **must** have a stable key field (e.g. `uuid`)
-- no fallbacks, no warnings
+- `each` must be an array
+- each item must be an object
+- each item must have a stable key (`uuid`)
+- no fallbacks, no heuristics
 
 ```ts
 type Item = {
-  uuid: string; // required
+  uuid: string;
   [key: string]: any;
 };
 ```
 
-### What `For` does
+What `For` does:
 
 - detects:
 
+  - additions
+  - removals
   - order changes
-  - added items
-  - removed items
 
 - performs:
 
   - DOM moves (`insertBefore`)
-  - rendering **only** for new keys
+  - rendering only for new keys
   - `destroy()` for removed keys
 
-### What `For` does **not** do
+What `For` does **not** do:
 
 - no content diffing
 - no re-rendering existing items
 - no prop patching
-- no heuristic matching
 
 > If an item’s content changes, the item itself must be reactive.
 
 ---
 
-## Mutation: allowed
+## Mutation is allowed
 
 ```ts
 setItems((prev) => {
@@ -230,16 +184,33 @@ This is **correct**.
 
 Why:
 
-- `signal` is active
-- effects are not reference-based
-- `For` evaluates only keys and order
+- signals are active
+- updates are not reference-based
+- `For` only cares about keys and order
 
-## `Show` (structural conditional rendering)
+## Routing
 
-`Show` controls **existence**, not visibility.
+Routing is **just application state**.
 
 ```ts
-<Show when={visible}>
-  <User />
+const [route, setRoute] = signal("home");
+```
+
+Structure is derived explicitly:
+
+```ts
+effect(route, (r) => {
+  setIsHome(() => r === "home");
+  setIsSettings(() => r === "settings");
+});
+```
+
+```tsx
+<Show when={isHome}>
+  <Home />
+</Show>
+
+<Show when={isSettings}>
+  <Settings />
 </Show>
 ```