@weftui/core 0.26.0 → 0.26.2

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                      |