@weftui/router 0.26.1 → 0.26.3

package/docs/how-to/split-routes-lazily.md

@@ -0,0 +1,62 @@
+---
+title: Split Routes Lazily
+order: 6
+section: how-to
+description: Code-split a route's component into its own chunk with Router.lazy, keeping the descriptor eager so matching, href, and SSR stay unchanged.
+---
+
+# Split Routes Lazily
+
+**Goal:** keep a heavy page's render code (and its dependencies) out of the initial bundle, loading it only when its route is actually rendered.
+
+Wrap the route's `component` in [`Router.lazy`](https://weftui.dev/docs/reference/router#routerlazy). The route **descriptor** (its segment and param schemas) stays eager so the matcher, `href`, and the server's dispatch API still see it statically — only the component body is split into its own chunk.
+
+```typescript
+import { Router } from "@weftui/router";
+import { Schema } from "effect";
+
+Router.route("docs/:category/:slug", {
+  path: { category: Schema.String, slug: Schema.String },
+  component: Router.lazy(() => import("./doc-page").then((m) => m.DocPage)),
+});
+```
+
+The chunk loads on the server during render and on the client on navigation; only the **matched branch's** chunks are ever fetched. `E`/`R` are preserved — a lazy route has the exact same channels as the same component declared eagerly, so an unmet service requirement is still a compile error at `Router.router(...)`.
+
+## Make the split real
+
+`Router.lazy` only splits if the dynamic `import()` is the **only eager path** to the heavy module. Keep the `Router.route(…)` descriptor in an eagerly-imported file, and move the component implementation (and its heavy deps) into a separate module referenced _only_ through `Router.lazy(() => import("./impl"))`:
+
+```typescript
+// routes.ts — eager, tiny: just the descriptor
+export const docsRoute = Router.route("docs/:category/:slug", {
+  path: { category: Schema.String, slug: Schema.String },
+  component: Router.lazy(() => import("./doc-page-impl").then((m) => m.DocsPage)),
+});
+
+// doc-page-impl.ts — heavy: pulled into its own chunk, never in the initial graph
+export const DocsPage = Component.gen(function* () {
+  /* renderHast, code highlighting, … */
+});
+```
+
+A descriptor file that still `import`s the impl statically gains nothing — the bundler keeps it in the initial graph.
+
+## What you get for free
+
+- **Flash-free hydration.** On a directly-loaded lazy route, the client re-invokes the same slot, awaits the chunk, and adopts the server DOM in place — the first production matches, so nothing is mutated.
+- **Blank-free navigation.** Client navigation is **deferred-commit**: the router resolves the target branch's chunk **and the matched leaf's own component effect** _before_ committing the URL, so the previous page stays mounted through both the fetch and any data the leaf awaits, and the swap is a single tick. See [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) for the `Router.navigating` signal this exposes.
+- **Synchronous revisits.** `Router.lazy` memoizes its load per slot, so a second visit to a loaded route commits immediately.
+
+## Edge cases
+
+- **Lazy layouts.** A `Router.layout({ component: Router.lazy(...) })` splits too — each lazy node in the matched branch is awaited; nodes outside it never load.
+- **Chunk-load failure is a defect.** If the `import()` rejects (offline, or a stale client requesting a chunk a new deploy removed), it dies as a defect and surfaces through normal defect handling — it never hangs or silently 404s. The rejection is memoized, so the route keeps failing until a reload (the deploy-skew case).
+- **Not a lazy _subtree_.** Only the component is lazy; you cannot defer a whole `RouteNode` behind an `import()`, because the matcher needs every leaf's segment and param schema before anything loads.
+
+## See also
+
+- [`Router.lazy` API reference](https://weftui.dev/docs/reference/router#routerlazy)
+- [Show Navigation Progress](https://weftui.dev/docs/how-to/show-navigation-progress) — the deferred-commit `Router.navigating` signal
+- [Add Routing](https://weftui.dev/docs/how-to/add-routing) — authoring the route tree `Router.lazy` plugs into
+- [examples/router-ssr](https://github.com/stefvw93/weft/tree/main/examples/router-ssr) — includes a `Router.lazy` page (`lazy-page.ts`) with a browser test

package/docs/how-to/style-reactively.md

@@ -0,0 +1,63 @@
+---
+title: Style Reactively
+order: 10
+section: how-to
+description: Drive inline styles from streams — a single property, or a whole style object — so the DOM updates in place with CSS transitions.
+---
+
+# Style Reactively
+
+**Goal:** animate or react to state in an element's inline style without re-rendering — a single CSS property, or a whole style object, driven by a stream.
+
+The `style` prop accepts the [`Source`](https://weftui.dev/docs/explanation/reactive-primitives) vocabulary at any level: a property value can be a stream, and you can spread a stream of style objects. CSS `transition` composes naturally, because the renderer mutates the existing node in place.
+
+```typescript
+import { h } from "@weftui/core";
+import { Schedule, Stream } from "effect";
+
+const AnimatedHue = () => {
+  const hue = Stream.iterate(0, (h) => (h + 2) % 360).pipe(
+    Stream.schedule(Schedule.spaced("50 millis")),
+  );
+
+  return h.div(
+    {
+      class: "demo-box",
+      style: {
+        // one property is reactive; the rest are static
+        backgroundColor: Stream.map(hue, (h) => `hsl(${h}, 70%, 60%)`),
+        transition: "background-color 0.05s",
+      },
+    },
+    "Hue",
+  );
+};
+```
+
+## Three modes
+
+1. **A single property as a stream** — as above: one key's value is a `Stream`, the others are static strings. Each stream property is subscribed independently.
+2. **A static object** — an ordinary `style: { backgroundColor: "#667eea" }` with no streams; nothing updates.
+3. **A whole style object as a stream** — spread a stream that emits complete style objects, merged with static props:
+
+```typescript
+const pulse = Stream.make(1, 0.5).pipe(
+  Stream.schedule(Schedule.spaced("800 millis")),
+  Stream.forever,
+);
+
+h.div({ style: { ...pulse, transition: "opacity 0.4s ease-in-out" } }, "Pulse");
+```
+
+Each emitted object is merged with the static properties on the element.
+
+## Notes
+
+- **Property names are camelCase** (`backgroundColor`, `boxShadow`) — the same keys as the DOM `style` object.
+- **CSS transitions just work.** Because a stream emission patches the DOM node directly (no re-render), the browser applies the `transition` as it would for any style mutation.
+- **Pace with `Schedule`.** `Stream.iterate`/`Stream.make` paced by `Stream.schedule(Schedule.spaced(…))` and looped with `Stream.forever` is the idiom for time-based style animation; combine with any Effect timing you like.
+
+## See also
+
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — reactive style props and the `Source` vocabulary
+- [examples/reactive-styles](https://github.com/stefvw93/weft/tree/main/examples/reactive-styles) — per-property and whole-object stream styles with CSS transitions

package/docs/how-to/use-element-refs.md

@@ -0,0 +1,63 @@
+---
+title: Use Element Refs
+order: 11
+section: how-to
+description: Capture a DOM element with the ref prop into a SubscriptionRef<Option<HTMLElement>>, then react to its mount with a scoped observer or read it imperatively.
+---
+
+# Use Element Refs
+
+**Goal:** get a handle to a real DOM element — to focus it, measure it, or call an imperative browser API on it.
+
+Declare a `SubscriptionRef<Option<HTMLElement>>`, attach it with the `ref` prop, and either **react** to the element appearing (a scoped observer on `.changes`) or **read** it later inside a handler.
+
+```typescript
+import { h } from "@weftui/core";
+import { Effect, Option, pipe, Stream, SubscriptionRef } from "effect";
+
+const AutoFocusInput = () =>
+  Effect.gen(function* () {
+    const inputRef = yield* SubscriptionRef.make<Option.Option<HTMLInputElement>>(Option.none());
+
+    // Observe the element becoming available, once, and focus it.
+    yield* pipe(
+      inputRef.changes,
+      Stream.filter(Option.isSome),
+      Stream.take(1),
+      Stream.runForEach((el) => Effect.sync(() => el.value.focus())),
+      Effect.forkScoped, // ← ties the observer to the component's instance scope
+    );
+
+    return yield* h.input({ ref: inputRef, type: "text", placeholder: "I'm focused!" });
+  });
+```
+
+## How it works
+
+- **The `ref` prop** takes a `SubscriptionRef<Option<T>>`. The renderer sets it to `Option.some(element)` **once**, when the element is created — so the ref is an `Option`: `None` until mount, `Some(el)` after.
+- **React to mount** by observing `ref.changes`: `Stream.filter(Option.isSome)` waits for the element, `Stream.take(1)` takes just the first appearance, and `Stream.runForEach` does the imperative work. This is the equivalent of a mount effect.
+- **Use `Effect.forkScoped`, not `Effect.fork`.** `forkScoped` ties the observer fiber to the component's **instance scope** (the ambient `Scope` the renderer provides), so it lives as long as the component is mounted. A bare `Effect.fork` binds to the transient component-body fiber and is interrupted the instant the generator returns — the observer would never fire.
+
+## Read a ref imperatively
+
+When you only need the element later (e.g. in a click handler), skip the observer and read the ref on demand:
+
+```typescript
+const scroll = () =>
+  Effect.gen(function* () {
+    const el = yield* SubscriptionRef.get(targetRef);
+    if (Option.isSome(el)) el.value.scrollIntoView({ behavior: "smooth" });
+  });
+```
+
+## Notes
+
+- A plain `Ref` suffices if you **only** read the element imperatively; use `SubscriptionRef` when you need to **react** to it becoming available.
+- Refs are set once at element creation and are not cleared on unmount.
+- Coming from React: `SubscriptionRef.make<Option<T>>(Option.none())` ↔ `useRef<T>(null)`; the `Stream.filter(Option.isSome)` observer ↔ a `useEffect` mount guard.
+
+## See also
+
+- [Reactive Primitives](https://weftui.dev/docs/explanation/reactive-primitives) — `SubscriptionRef` and `.changes`
+- [Author Components](https://weftui.dev/docs/how-to/author-components) — instance scope and `Effect.forkScoped`
+- [examples/element-ref](https://github.com/stefvw93/weft/tree/main/examples/element-ref) — auto-focus, element measurement, and imperative scroll via refs

package/docs/index.md

@@ -0,0 +1,59 @@
+# Weft Documentation
+
+**Reactive UI, woven from Effect.**
+
+Weft is an Effect-native reactive DOM library — in the browser and on the server. `Node<E, R>` is `Effect.Effect<ElementDescriptor, E, R>`: every element is an Effect, so error and requirement channels accumulate through the tree, all Effect combinators apply to nodes directly, and services flow from mount through the whole app. Streams drive every update — there is no virtual DOM — and the same tree renders to HTML on the server and `hydrate()`s in place on the client, flash-free. No JSX.
+
+The docs follow the [Diátaxis](https://diataxis.fr) model. Pick your entry point by what you are trying to do:
+
+## Start here
+
+**[→ Tutorial](https://weftui.dev/docs/tutorial/01-your-first-app)** — a four-step guided path from a static component to a server-rendered, error-handled app. Start here if you are new to Weft:
+
+1. [Your First App](https://weftui.dev/docs/tutorial/01-your-first-app) — `h` and `mount`
+2. [Reactivity](https://weftui.dev/docs/tutorial/02-reactivity) — `SubscriptionRef` and streams
+3. [Services and Async](https://weftui.dev/docs/tutorial/03-services-and-async) — handlers, services, async loading
+4. [Errors and Server Rendering](https://weftui.dev/docs/tutorial/04-errors-and-server) — boundaries and SSR
+
+## The four quadrants
+
+|                                                   |                                                                                                                                                                                     |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **[Tutorial](https://weftui.dev/docs/tutorial/01-your-first-app)**     | Learning-oriented. One guided path, start to finish.                                                                                                                                |
+| **[How-to guides](https://weftui.dev/docs/how-to/author-components)**  | Task-oriented. Author components, render on the server, load data with rpc, add routing — plus recipes for forms, async data, keyed lists, reactive styles, refs, and lazy routing. |
+| **[Explanation](https://weftui.dev/docs/explanation/rendering-model)** | Understanding-oriented. The rendering model, the combinator API, reactive primitives, boundaries, and services & context.                                                           |
+| **[Reference](https://weftui.dev/docs/reference/core)**                | Information-oriented. Full API: [`@weftui/core`](https://weftui.dev/docs/reference/core), [`@weftui/dom`](https://weftui.dev/docs/reference/dom), [`@weftui/router`](https://weftui.dev/docs/reference/router).                                    |
+
+New to the model itself? Read [The Rendering Model](https://weftui.dev/docs/explanation/rendering-model) — why there is no virtual DOM, and what "streams are the weft" means.
+
+## Packages
+
+Three published packages make up Weft's public API, plus one build-time plugin:
+
+- **`@weftui/core`** — element builders (`h`), components, sources/streams, and boundaries. Start here.
+- **`@weftui/dom`** — the renderer: `./client` (`mount`/`hydrate`) and `./server` (`renderToString*`).
+- **`@weftui/router`** — universal nested routing, `Router.lazy`, and the rpc seam.
+- **`@weftui/vite`** — a build-time Vite plugin (tooling, not a runtime API).
+
+`@weftui/base` is an internal, currently-empty stub — it has no public primitives; ignore it.
+
+## Examples
+
+The [`examples/`](https://github.com/stefvw93/weft/tree/main/examples) directory contains standalone runnable apps. Each covers a specific pattern and ships with a browser test:
+
+| Example                      | What it shows                                                                        |
+| ---------------------------- | ------------------------------------------------------------------------------------ |
+| `async-data-loading`         | Loading states, retry, error boundaries with Stream and Effect                       |
+| `declarative-event-handlers` | Plain, Effect-returning, service-aware, and reactive handlers                        |
+| `element-ref`                | DOM refs with `SubscriptionRef<Option<HTMLElement>>`                                 |
+| `error-boundary`             | All six failure-catch `Boundary.*` variants                                          |
+| `form-handling`              | Reactive inputs, Schema validation, Effect submit handlers                           |
+| `keyed-list`                 | Keyed list rendering with `List.each`                                                |
+| `list-rendering`             | Static and stream-based lists, fragments, nested iterables                           |
+| `reactive-styles`            | Per-property and whole-object stream styles, CSS transitions                         |
+| `router-ssr`                 | Universal nested routing with SSR, hydration, layouts, `Boundary.rpc`, `Router.lazy` |
+| `server-boundary`            | `Boundary.rpc` client-first mount + refetch, router-less                             |
+| `ssr-hydration`              | SSR + hydration without server data loading                                          |
+| `subscription-ref`           | Local state, derived streams, coordinating multiple refs                             |
+| `suspense`                   | Suspense boundaries for streaming SSR and client coordination                        |
+| `type-augmentation`          | Typed custom elements on `h` via the `CustomElements` interface                      |