235 lines
20 KiB
Plaintext
235 lines
20 KiB
Plaintext
page wrnexuscsr {
|
|
seo {
|
|
title = "@wrnexus/csr"
|
|
description = "Reactive, navigation, and realtime browser runtimes."
|
|
}
|
|
|
|
view {
|
|
<div class="docs-shell">
|
|
<header class="topbar">
|
|
<a class="brand" href="/"><span>W</span> WRNexusJS</a>
|
|
<nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
|
<button data-wire-theme-toggle class="theme-button" aria-label="Toggle theme">Theme</button>
|
|
</header>
|
|
<main class="page package-page">
|
|
<aside class="sidebar"><a href="/packages">← All packages</a><span class="category">Frontend</span><h1>@wrnexus/csr</h1><p>Reactive, navigation, and realtime browser runtimes.</p><code>bun add @wrnexus/csr@0.2.14</code><nav><a href="#guide">Guide</a><a href="#api">Complete API</a></nav></aside>
|
|
<article class="documentation"><section class="doc-intro"><span class="eyebrow">Frontend</span><h1>@wrnexus/csr</h1><p>Reactive, navigation, and realtime browser runtimes.</p><pre><code>bun add @wrnexus/csr@0.2.14</code></pre></section><section id="guide" class="prose"><blockquote>The browser-side client runtime for WRNexusJS — generic, self-contained JS that hydrates server-rendered pages with reactivity, client-side navigation, and realtime rooms.</blockquote>
|
|
<p>Part of the <strong>WRNexusJS</strong> framework — an SSR-first, Bun-native full-stack web framework.</p>
|
|
<h3 id="overview">Overview</h3>
|
|
<p><code>@wrnexus/csr</code> holds the three client runtimes that WRNexusJS serves to the browser. Components are authored as <code>.wrn</code> files and rendered on the <strong>server</strong>; this package provides the single, generic runtime that <strong>hydrates</strong> that HTML in the browser — there are no per-component browser bundles. Each runtime is exported as a plain-JS string (no build step, no imports) intended to be served verbatim from a well-known URL:</p>
|
|
<ul>
|
|
<li><strong>reactive</strong> at <code>/__wrnexus/reactive.js</code> — reactive directives (<code>data-scope</code>, <code>data-text</code>, <code>data-for</code>, …)</li>
|
|
<li><strong>nav</strong> at <code>/__wrnexus/nav.js</code> — SPA-style client navigation with graceful fallback</li>
|
|
<li><strong>realtime</strong> at <code>/__wrnexus/realtime.js</code> — WebSocket "rooms", declarative or programmatic</li>
|
|
</ul>
|
|
<p>The package itself runs on the server (it just returns strings); the strings it returns run in the browser. A dev/prod server (see <code>@wrnexus/core</code>) is responsible for actually serving them.</p>
|
|
<h3 id="installation">Installation</h3>
|
|
<pre data-language="bash"><code>bun add @wrnexus/csr</code></pre>
|
|
<blockquote>Private package — the machine must be authenticated to the <code>wrnexus</code> npm org</blockquote>
|
|
<blockquote>(a read token in <code>~/.npmrc</code>). Requires <strong>Bun</strong> (Node is not supported).</blockquote>
|
|
<h3 id="api">API</h3>
|
|
<p>All exports come from the package root (<code>@wrnexus/csr</code>). The runtime source is delivered as strings, so the "API" on the server side is small; the real surface is the browser directives/globals each string installs.</p>
|
|
<h4 id="runtime-strings">Runtime strings</h4>
|
|
<div class="table-wrap"><table>
|
|
<thead><tr><th>Export</th><th>Type</th><th>Served at</th><th>Contents</th></tr></thead>
|
|
<tbody><tr><td><code>REACTIVE_RUNTIME</code></td><td><code>string</code></td><td><code>/__wrnexus/reactive.js</code></td><td>Reactive directive runtime</td></tr><tr><td><code>NAV_RUNTIME</code></td><td><code>string</code></td><td><code>/__wrnexus/nav.js</code></td><td>Client-side navigation runtime</td></tr><tr><td><code>REALTIME_RUNTIME</code></td><td><code>string</code></td><td><code>/__wrnexus/realtime.js</code></td><td>Realtime rooms runtime</td></tr></tbody></table></div>
|
|
<h4 id="accessor-functions">Accessor functions</h4>
|
|
<p>Convenience getters that return the same strings.</p>
|
|
<pre data-language="ts"><code>getReactiveRuntime(): string // → REACTIVE_RUNTIME
|
|
getNavRuntime(): string // → NAV_RUNTIME
|
|
getRealtimeRuntime(): string // → REALTIME_RUNTIME</code></pre>
|
|
<h4 id="browser-reactive-directives">Browser: reactive directives</h4>
|
|
<p>Applied to any subtree containing <code>data-scope</code>. Expressions are parsed by a tiny eval-free evaluator, so a strict CSP with no <code>unsafe-eval</code> works.</p>
|
|
<div class="table-wrap"><table>
|
|
<thead><tr><th>Directive</th><th>Purpose</th></tr></thead>
|
|
<tbody><tr><td><code>data-scope="count: 0, name: 'x'"</code></td><td>Declare reactive state on a subtree</td></tr><tr><td><code>data-on-<event>="count++"</code></td><td>Run a statement in scope on a DOM event</td></tr><tr><td><code>data-text="expr"</code></td><td>Bind an element's <code>textContent</code> to an expression</td></tr><tr><td><code>data-show="expr"</code></td><td>Toggle visibility (<code>display</code>) on truthiness</td></tr><tr><td><code>data-for="item in list"</code> (opt. <code>item, i in list</code>)</td><td>Per-item list rendering template</td></tr><tr><td><code>{{expr}}</code> or <code>{expr}</code></td><td>Interpolation inside text nodes and attribute values</td></tr><tr><td><code>data-wrnexus-csr="id"</code></td><td>Target for a generated CSR fetch binding (fetches <code>/__wrnexus/csr?...</code>)</td></tr></tbody></table></div>
|
|
<p>Supported expression features: literals, identifiers, member access (<code>a.b</code>, <code>a[b]</code>), function/method calls, arrays, objects, arithmetic, comparison, equality, logical (<code>&& ||</code>), unary (<code>! - +</code>), and ternary. Statements support <code>++</code>/<code>--</code>, assignment operators (<code>= += -= *= /= %=</code>), and bare expression/method calls. Rendering is dependency-tracked: a signal change only re-runs the renderers that actually read it.</p>
|
|
<p>Browser globals installed: <code>window.__wrnexusHydrateScopes(root)</code> and <code>window.__wrnexusHydrateCsrFetches(root)</code> — both idempotent, so re-running after a DOM swap or HMR morph is safe. Both run automatically on <code>DOMContentLoaded</code>.</p>
|
|
<h4 id="browser-navigation">Browser: navigation</h4>
|
|
<p>Intercepts same-origin <code><a></code> clicks, fetches the target page, and swaps the <code>#app</code> container in place (via <code>importNode</code> — not <code>innerHTML</code> — so it works under a Trusted-Types CSP), updating history, title, and scroll, then re-hydrates. Cross-origin links, modified clicks, <code>download</code>/<code>data-no-nav</code>/<code>rel="external"</code>/<code>target</code> links, non-HTML responses, or a missing <code>#app</code> fall back to a full browser navigation.</p>
|
|
<ul>
|
|
<li>Programmatic navigation: <code>window.__wrnexusNavigate(url)</code></li>
|
|
<li>Emits a <code>wrnexus:navigated</code> <code>CustomEvent</code> (<code>detail.url</code>) after each swap</li>
|
|
<li>Sends <code>x-wrnexus-nav: 1</code> on fetches so the server can return the page fragment</li>
|
|
<li>Appends any <code>/__wrnexus/*</code> runtime scripts the incoming page needs but the current document lacks</li>
|
|
</ul>
|
|
<h4 id="browser-realtime-rooms">Browser: realtime rooms</h4>
|
|
<p>Connects to <code>/realtime/<name></code> over WebSocket (<code>ws</code>/<code>wss</code> chosen from <code>location.protocol</code>). Two usage modes.</p>
|
|
<p>Programmatic API via <code>window.wire</code>:</p>
|
|
<pre data-language="ts"><code>wire.room(name): Room // open (or reuse) a room connection
|
|
wire.bindRooms(root?) // (re)bind declarative [data-room] containers
|
|
|
|
interface Room {
|
|
name: string;
|
|
send(obj: object | string): Room; // JSON-stringifies objects; queues until open
|
|
on(type: string, cb): Room; // filter by msg.type; "*" or a fn = all messages
|
|
on(cb): Room;
|
|
close(): Room;
|
|
}</code></pre>
|
|
<p>Internal lifecycle messages are emitted to listeners as <code>{ type }</code>: <code>__open</code>, <code>__close</code>, <code>__error</code>, and <code>__raw</code> (non-JSON frames, with <code>data</code>). Reconnect uses exponential backoff capped at 5s; queued sends flush on reconnect.</p>
|
|
<p>Declarative binding (zero JS) on a <code>data-room="<name>"</code> container:</p>
|
|
<div class="table-wrap"><table>
|
|
<thead><tr><th>Attribute</th><th>On</th><th>Purpose</th></tr></thead>
|
|
<tbody><tr><td><code>data-room="<name>"</code></td><td>container</td><td>Connect to room <code><name></code></td></tr><tr><td><code>data-room-user="<id>"</code></td><td>container</td><td>Identify the connection (<code>?user=<id></code>)</td></tr><tr><td><code>data-room-log</code></td><td>element</td><td>Where incoming messages are appended</td></tr><tr><td><code><template data-room-item="<type>"></code></td><td>template</td><td>Row template for messages of that <code>type</code> (empty = fallback)</td></tr><tr><td><code>%field%</code></td><td>inside template</td><td>Placeholder filled from the message field (text/attr only, HTML-escaped)</td></tr><tr><td><code>data-room-status</code></td><td>element</td><td>Reflects connection state text (<code>connected</code>/<code>disconnected</code>/<code>error</code>)</td></tr><tr><td><code>data-room-status-class</code></td><td>status element</td><td>Base class; a state variant (<code>is-connected</code>, …) is appended</td></tr><tr><td><code><form data-room-send></code></td><td>form</td><td>Submits named fields as a JSON message</td></tr><tr><td><code>data-room-reset</code></td><td>form field</td><td>Clears that field after send</td></tr></tbody></table></div>
|
|
<p>Rebinds on <code>wrnexus:navigated</code> and closes rooms whose container has left the page.</p>
|
|
<h3 id="usage">Usage</h3>
|
|
<p>Server side — serve the runtime strings from your router (example with <code>Bun.serve</code>):</p>
|
|
<pre data-language="ts"><code>import { getReactiveRuntime, getNavRuntime, getRealtimeRuntime } from "@wrnexus/csr";
|
|
|
|
const routes: Record<string, string> = {
|
|
"/__wrnexus/reactive.js": getReactiveRuntime(),
|
|
"/__wrnexus/nav.js": getNavRuntime(),
|
|
"/__wrnexus/realtime.js": getRealtimeRuntime(),
|
|
};
|
|
|
|
Bun.serve({
|
|
fetch(req) {
|
|
const body = routes[new URL(req.url).pathname];
|
|
if (body) {
|
|
return new Response(body, {
|
|
headers: { "content-type": "text/javascript; charset=utf-8" },
|
|
});
|
|
}
|
|
return new Response("Not found", { status: 404 });
|
|
},
|
|
});</code></pre>
|
|
<p>Browser side — server-rendered HTML that the reactive runtime hydrates:</p>
|
|
<pre data-language="html"><code><div data-scope="count: 0">
|
|
<button data-on-click="count++">+1</button>
|
|
<span data-text="count"></span>
|
|
<p>Total: {{count}}</p>
|
|
</div>
|
|
<script src="/__wrnexus/reactive.js"></script></code></pre>
|
|
<p>A realtime chat, fully declarative:</p>
|
|
<pre data-language="html"><code><div data-room="lobby" data-room-user="ada">
|
|
<div data-room-status></div>
|
|
<ul data-room-log></ul>
|
|
<template data-room-item="chat"><li>%user%: %text%</li></template>
|
|
<form data-room-send>
|
|
<input name="text" data-room-reset />
|
|
<input type="hidden" name="type" value="chat" />
|
|
<button>Send</button>
|
|
</form>
|
|
</div>
|
|
<script src="/__wrnexus/realtime.js"></script></code></pre>
|
|
<p>Or drive a room from code:</p>
|
|
<pre data-language="ts"><code>const room = wire.room("lobby");
|
|
room.on("chat", (msg) => console.log(msg.user, msg.text));
|
|
room.send({ type: "chat", user: "ada", text: "hi" });</code></pre>
|
|
<h3 id="requirements-notes">Requirements / Notes</h3>
|
|
<ul>
|
|
<li><strong>Bun-only</strong> on the server (the package integrates with Bun-based WRNexusJS servers); the emitted strings are plain browser JS with no dependencies.</li>
|
|
<li>Browser runtimes are <strong>self-contained</strong> (no imports, no build step) and <strong>idempotent</strong>, so re-hydration after navigation or HMR is safe.</li>
|
|
<li>Designed for a <strong>strict CSP</strong>: the reactive expression evaluator avoids <code>eval</code>/<code>new Function</code> (no <code>unsafe-eval</code>), and DOM swaps use <code>importNode</code>/attribute writes rather than <code>innerHTML</code> (Trusted-Types friendly).</li>
|
|
<li>Peer packages: rendered <code>.wrn</code> components and the serving layer come from <code>@wrnexus/core</code> (the sole dependency); pages are rendered by the WRNexusJS dev/prod server.</li>
|
|
</ul></section><section id="api" class="prose api"><h2>Complete TypeScript API</h2><p>This declaration is generated from the exact published package and lists its exported functions, classes, interfaces, and types.</p><pre data-language="typescript"><code>/**
|
|
* Browser reactive runtime (Point 2: reactive directives).
|
|
*
|
|
* Served verbatim at `/__wrnexus/reactive.js` for any page that contains a
|
|
* `data-scope`. It is plain browser JS (no build step) and self-contained: it
|
|
* inlines a tiny `signal()` so it has no imports to resolve.
|
|
*
|
|
* Supported directives (this is exactly what the `.wrn` compiler emits):
|
|
* data-scope="count: 0, name: 'x'" declare reactive state on a subtree
|
|
* data-on-<event>="count++" run a statement in scope on an event
|
|
* data-text="expr" element textContent follows an expression
|
|
* data-wrnexus-csr="id" target for generated CSR fetch bindings
|
|
* {{expr}} or {expr} interpolation inside text nodes
|
|
*
|
|
* Expressions are evaluated by a tiny parser instead of `eval`/`new Function`,
|
|
* so production can use a strong CSP without `unsafe-eval`.
|
|
*/
|
|
declare const REACTIVE_RUNTIME: string;
|
|
|
|
/**
|
|
* Client-side navigation runtime, served at `/__wrnexus/nav.js`.
|
|
*
|
|
* Progressive enhancement over normal links: intercepts same-origin `<a>`
|
|
* clicks, fetches the target page's HTML, swaps the `#app` container in place,
|
|
* updates history/title/scroll, ensures any framework runtimes the new page
|
|
* needs are present, and re-hydrates. Anything unexpected (cross-origin,
|
|
* modified click, non-HTML response, missing `#app`) falls back to a full
|
|
* browser navigation, so behaviour degrades safely.
|
|
*
|
|
* Data "loaders": pages load their data on the server (SSR `api` bindings), so
|
|
* the fetched HTML already contains fresh data — no separate client loader is
|
|
* needed. Client-side (`csr`) bindings and reactive scopes re-hydrate after the
|
|
* swap. Programmatic navigation is exposed as `window.__wrnexusNavigate(url)`.
|
|
*/
|
|
declare const NAV_RUNTIME: string;
|
|
|
|
/**
|
|
* Client realtime runtime, served at `/__wrnexus/realtime.js`.
|
|
*
|
|
* Two ways to use it — no hand-written WebSocket code either way:
|
|
*
|
|
* 1. Declarative (zero JS). Put `data-room="<name>"` on a container; the runtime
|
|
* connects, appends incoming messages to `[data-room-log]` using a
|
|
* `<template data-room-item="<type>">` (fields via `%field%`, HTML-escaped),
|
|
* reflects connection state on `[data-room-status]`, and sends a
|
|
* `<form data-room-send>`'s named fields as JSON on submit (fields marked
|
|
* `data-room-reset` clear after send). Optional `data-room-user` identifies
|
|
* the connection.
|
|
*
|
|
* 2. Programmatic: `const room = wire.room("chat"); room.on("chat", fn);
|
|
* room.send({ type: "chat", text })`. Handles connect, JSON, reconnect.
|
|
*
|
|
* Rebinds on `wrnexus:navigated` (client-side nav) and closes rooms whose
|
|
* container has left the page.
|
|
*/
|
|
declare const REALTIME_RUNTIME: string;
|
|
|
|
/**
|
|
* @wrnexus/csr — the browser reactive runtime.
|
|
*
|
|
* Components are `.wrn` files rendered on the SERVER (see @wrnexus/dev-server)
|
|
* and hydrated in the browser by this single, generic runtime — served once at
|
|
* `/__wrnexus/reactive.js` for any page that contains a `data-scope`. There are
|
|
* no per-component browser bundles: SSR stays cleanly separated from CSR.
|
|
*/
|
|
|
|
/** The reactive runtime served at `/__wrnexus/reactive.js` (plain browser JS). */
|
|
declare function getReactiveRuntime(): string;
|
|
/** The client-side navigation runtime served at `/__wrnexus/nav.js`. */
|
|
declare function getNavRuntime(): string;
|
|
/** The realtime client runtime served at `/__wrnexus/realtime.js`. */
|
|
declare function getRealtimeRuntime(): string;
|
|
|
|
export { NAV_RUNTIME, REACTIVE_RUNTIME, REALTIME_RUNTIME, getNavRuntime, getReactiveRuntime, getRealtimeRuntime };
|
|
</code></pre></section><section id="examples" class="prose examples"><h2>Examples</h2><p>Copy-ready examples taken from this package's published documentation.</p><div class="example-grid"><article class="example-card"><h3>Example 1</h3><pre data-language="bash"><code>bun add @wrnexus/csr</code></pre></article><article class="example-card"><h3>Example 2</h3><pre data-language="ts"><code>getReactiveRuntime(): string // → REACTIVE_RUNTIME
|
|
getNavRuntime(): string // → NAV_RUNTIME
|
|
getRealtimeRuntime(): string // → REALTIME_RUNTIME</code></pre></article><article class="example-card"><h3>Example 3</h3><pre data-language="ts"><code>wire.room(name): Room // open (or reuse) a room connection
|
|
wire.bindRooms(root?) // (re)bind declarative [data-room] containers
|
|
|
|
interface Room {
|
|
name: string;
|
|
send(obj: object | string): Room; // JSON-stringifies objects; queues until open
|
|
on(type: string, cb): Room; // filter by msg.type; "*" or a fn = all messages
|
|
on(cb): Room;
|
|
close(): Room;
|
|
}</code></pre></article><article class="example-card"><h3>Example 4</h3><pre data-language="ts"><code>import { getReactiveRuntime, getNavRuntime, getRealtimeRuntime } from "@wrnexus/csr";
|
|
|
|
const routes: Record<string, string> = {
|
|
"/__wrnexus/reactive.js": getReactiveRuntime(),
|
|
"/__wrnexus/nav.js": getNavRuntime(),
|
|
"/__wrnexus/realtime.js": getRealtimeRuntime(),
|
|
};
|
|
|
|
Bun.serve({
|
|
fetch(req) {
|
|
const body = routes[new URL(req.url).pathname];
|
|
if (body) {
|
|
return new Response(body, {
|
|
headers: { "content-type": "text/javascript; charset=utf-8" },
|
|
});
|
|
}
|
|
return new Response("Not found", { status: 404 });
|
|
},
|
|
});</code></pre></article></div></section></article>
|
|
<aside class="on-this-page"><h2>On this page</h2><nav><a class="toc-level-2" href="#guide">Guide</a><a class="toc-level-3" href="#overview">Overview</a><a class="toc-level-3" href="#installation">Installation</a><a class="toc-level-3" href="#api">API</a><a class="toc-level-4" href="#runtime-strings">Runtime strings</a><a class="toc-level-4" href="#accessor-functions">Accessor functions</a><a class="toc-level-4" href="#browser-reactive-directives">Browser: reactive directives</a><a class="toc-level-4" href="#browser-navigation">Browser: navigation</a><a class="toc-level-4" href="#browser-realtime-rooms">Browser: realtime rooms</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-3" href="#requirements-notes">Requirements / Notes</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
|
|
</main>
|
|
<footer>WRNexusJS 0.2.14 · SSR-first · Bun-native · Documentation generated from published package APIs.</footer>
|
|
</div>
|
|
}
|
|
}
|