345 lines
32 KiB
Plaintext
345 lines
32 KiB
Plaintext
page wrnexuscsr {
|
|
seo {
|
|
title = "@wrnexus/csr"
|
|
description = "Reactive, navigation, and realtime browser runtimes."
|
|
}
|
|
|
|
view {
|
|
<div class="docs-shell">
|
|
<a href="#main" class="skip-link">Skip to content</a>
|
|
<header class="topbar">
|
|
<a class="brand" href="/"><span>W</span> WRNexusJS</a>
|
|
<nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
|
|
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.8.8</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
|
|
</header>
|
|
<div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
|
|
<main id="main" class="portal-main docs-layout docs-layout--navigation"><aside class="docs-section-menu" aria-label="Documentation sections"><nav>
|
|
<section><strong>Get started</strong><a href="/getting-started">Quick start</a><a href="/tutorial">Tutorial</a><a href="/guides/full-stack-auth-demo">Auth dashboard demo</a><a href="/guides/configuration-and-profiles">Configuration</a></section>
|
|
<section><strong>Build</strong><a href="/guides/pages-and-components">Pages and components</a><a href="/guides/routing">Routing</a><a href="/guides/server-data">Server data</a><a href="/guides/forms-and-validation">Forms and validation</a><a href="/guides/database">Database</a></section>
|
|
<section><strong>Auth and security</strong><a href="/guides/authentication">Authentication</a><a href="/guides/authorization">Authorization</a><a href="/guides/security">Application security</a><a href="/security">Security policy</a></section>
|
|
<section><strong>Reference</strong><a href="/packages">Packages overview</a><a href="/packages/cli">CLI</a><a href="/language">.wrn language</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/examples">Examples</a></section>
|
|
<section class="package-menu"><strong>Packages</strong><a href="/packages/ai">@wrnexus/ai</a><a href="/packages/auth">@wrnexus/auth</a><a href="/packages/authz">@wrnexus/authz</a><a href="/packages/benchmark">@wrnexus/benchmark</a><a href="/packages/cache">@wrnexus/cache</a><a href="/packages/captcha">@wrnexus/captcha</a><a href="/packages/cli">@wrnexus/cli</a><a href="/packages/compiler">@wrnexus/compiler</a><a href="/packages/content">@wrnexus/content</a><a href="/packages/core">@wrnexus/core</a><a href="/packages/csr">@wrnexus/csr</a><a href="/packages/db">@wrnexus/db</a><a href="/packages/dev-server">@wrnexus/dev-server</a><a href="/packages/dev-toolbar">@wrnexus/dev-toolbar</a><a href="/packages/encryption">@wrnexus/encryption</a><a href="/packages/graphql">@wrnexus/graphql</a><a href="/packages/helpers">@wrnexus/helpers</a><a href="/packages/i18n">@wrnexus/i18n</a><a href="/packages/identity">@wrnexus/identity</a><a href="/packages/image">@wrnexus/image</a><a href="/packages/jwt">@wrnexus/jwt</a><a href="/packages/language-server">@wrnexus/language-server</a><a href="/packages/mcp">@wrnexus/mcp</a><a href="/packages/mobile">@wrnexus/mobile</a><a href="/packages/native">@wrnexus/native</a><a href="/packages/oauth">@wrnexus/oauth</a><a href="/packages/observability">@wrnexus/observability</a><a href="/packages/playground">@wrnexus/playground</a><a href="/packages/plugin">@wrnexus/plugin</a><a href="/packages/pubsub">@wrnexus/pubsub</a><a href="/packages/pwa">@wrnexus/pwa</a><a href="/packages/queue">@wrnexus/queue</a><a href="/packages/reactive">@wrnexus/reactive</a><a href="/packages/realtime">@wrnexus/realtime</a><a href="/packages/router">@wrnexus/router</a><a href="/packages/security">@wrnexus/security</a><a href="/packages/ssr">@wrnexus/ssr</a><a href="/packages/store">@wrnexus/store</a><a href="/packages/styles">@wrnexus/styles</a><a href="/packages/syntax">@wrnexus/syntax</a><a href="/packages/test">@wrnexus/test</a><a href="/packages/tracking">@wrnexus/tracking</a><a href="/packages/typecheck">@wrnexus/typecheck</a><a href="/packages/ui">@wrnexus/ui</a><a href="/packages/uploader">@wrnexus/uploader</a><a href="/packages/validation">@wrnexus/validation</a></section>
|
|
</nav></aside><div class="docs-reading-column">
|
|
<article class="documentation prose standalone package-document"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/packages">Packages</a><span>/</span><span aria-current="page">@wrnexus/csr</span></nav><section class="doc-intro"><span class="eyebrow">Frontend · Package reference</span><h1>@wrnexus/csr</h1><p>Reactive, navigation, and realtime browser runtimes.</p><div class="doc-meta"><span>v0.8.8</span><span>Private registry</span><span>Frontend</span></div><section id="access" class="access-callout"><h2>Install the package</h2><p>After WorkRoot approves private registry access, install the release-aligned package:</p><pre><code>bun add @wrnexus/csr@0.8.8</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide"><h3 id="navigation-state-preservation">Navigation state preservation</h3>
|
|
<p>Pages can opt into restoration across client navigation:</p>
|
|
<pre data-language="wrn"><code>page Users {
|
|
navigation {
|
|
preserve = ["filters", "pagination", "scroll", "tabs", "expanded"]
|
|
}
|
|
}</code></pre>
|
|
<p>Form-like categories restore named inputs, selects, and textareas. Password, file, hidden, CSRF/token/secret/credential fields, and elements marked <code>data-no-preserve</code> are never saved. For tab, expanded, or component UI state, mark stable elements with <code>data-wrn-preserve="key"</code>; their value and ARIA selected/expanded state are restored. State is scoped to pathname plus query.</p>
|
|
<h3 id="typed-server-actions">Typed server actions</h3>
|
|
<p><code>createActionClient<Input, Output>(route, name)</code> supports programmatic calls. Schema-backed WRN actions also export <code>__wrnexusActionClients</code>, whose input and output are inferred automatically. Enhanced forms expose <code>data-wrn-action-state="pending|success|error"</code> and dispatch bubbling <code>wrnexus:action:optimistic</code>, <code>:pending</code>, <code>:success</code>, and <code>:error</code> events. Success details contain returned data and invalidated cache tags; error details contain field errors. Without JavaScript, the same form posts to its page and receives a 303 redirect or accessible validation response.</p>
|
|
<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>
|
|
<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 while preserving interactive state</td></tr></tbody></table></div>
|
|
<p>Compiled conditional rendering and dynamic component cases omit inactive elements from the live DOM. <code>data-show</code> is a visibility directive for stateful controls and keeps its element mounted. Neither mechanism is authorization: never place secrets in client-rendered branches. Authorize on the server and return only data the current request may access.</p>
|
|
<div class="table-wrap"><table>
|
|
<tbody><tr><td><code>data-for="item in list"</code> (opt. index and <code>key item.id</code>)</td><td>Per-item rendering; stable keys preserve DOM identity during reorder</td></tr><tr><td><code>data-key="item.id"</code></td><td>Alternative key declaration for <code>data-for</code> templates</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, showPassword: false">
|
|
<button data-on-click="count++">+1</button>
|
|
<span data-text="count"></span>
|
|
<p>Total: {{count}}</p>
|
|
<input type="{showPassword ? 'text' : 'password'}" />
|
|
<button
|
|
data-on-click="showPassword = !showPassword"
|
|
aria-label="{showPassword ? 'Hide password' : 'Show password'}"
|
|
>
|
|
Toggle password
|
|
</button>
|
|
</div>
|
|
<script src="/__wrnexus/reactive.js"></script></code></pre>
|
|
<p>State interpolation in ordinary attributes is reactive. The compiler keeps the initial SSR value and emits an internal binding so attributes such as <code>type</code>, <code>aria-label</code>, <code>aria-pressed</code>, <code>class</code>, and <code>href</code> update after state changes.</p>
|
|
<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="api"><h2>Complete TypeScript API</h2><p>Generated from the exact installed package declarations.</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-wrn-loop-locals="base64-json" preserves SSR {#each} item/index values
|
|
* 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.
|
|
*
|
|
* Before replacing the current page, component lifecycle behaviors are
|
|
* explicitly disposed. This ensures `unmount` hooks and watcher cleanups run
|
|
* before the old DOM is removed.
|
|
*
|
|
* 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;
|
|
|
|
declare const ACTION_RUNTIME: string;
|
|
|
|
type OutputHandler<T = unknown> = (payload: T) => void | Promise<void>;
|
|
interface OutputHost extends HTMLElement {
|
|
__wrnexusOutputHandlers?: Map<string, Set<OutputHandler>>;
|
|
}
|
|
declare function registerOutputHandler<T>(host: OutputHost, name: string, handler: OutputHandler<T>): () => void;
|
|
declare function invokeOutput<T>(host: OutputHost, name: string, payload?: T): Promise<void>;
|
|
declare function createOutputProxy<T extends Record<string, (...args: any[]) => void>>(host: OutputHost): T;
|
|
|
|
interface ServerCallOptions {
|
|
endpoint?: string;
|
|
signal?: AbortSignal;
|
|
headers?: HeadersInit;
|
|
csrfToken?: string;
|
|
}
|
|
declare class WrnServerCallError extends Error {
|
|
readonly code: string;
|
|
readonly status: number;
|
|
readonly details?: unknown | undefined;
|
|
constructor(message: string, code: string, status: number, details?: unknown | undefined);
|
|
}
|
|
declare function callServerFunction<TInput extends unknown[], TOutput>(component: string, functionName: string, args: TInput, options?: ServerCallOptions): Promise<TOutput>;
|
|
declare function createServerProxy<T extends Record<string, (...args: any[]) => Promise<any>>>(component: string, options?: ServerCallOptions): T;
|
|
|
|
declare function collectRefs(root: ParentNode): Record<string, Element>;
|
|
|
|
interface ClientModuleScope {
|
|
output: Record<string, (payload?: unknown) => void>;
|
|
server: Record<string, (...args: unknown[]) => Promise<unknown>>;
|
|
props: Readonly<Record<string, unknown>>;
|
|
refs: Record<string, Element>;
|
|
}
|
|
declare function loadClientFunctions(url: string, scope: ClientModuleScope): Promise<Record<string, (...args: unknown[]) => unknown>>;
|
|
declare function invalidateClientModule(url: string): void;
|
|
|
|
interface ActionClientOptions<I> {
|
|
signal?: AbortSignal;
|
|
csrfToken?: string;
|
|
headers?: HeadersInit;
|
|
serialize?: (input: I) => BodyInit;
|
|
}
|
|
interface ActionResult<O> {
|
|
data: O;
|
|
invalidated: string[];
|
|
}
|
|
declare class ActionClientError extends Error {
|
|
readonly status: number;
|
|
readonly errors?: Record<string, string> | undefined;
|
|
constructor(status: number, errors?: Record<string, string> | undefined);
|
|
}
|
|
declare function createActionClient<I, O>(route: string, name: string): (input: I, options?: ActionClientOptions<I>) => Promise<ActionResult<O>>;
|
|
|
|
interface HydrationScopeApi {
|
|
get(name: string): unknown;
|
|
set(name: string, value: unknown): void;
|
|
call(name: string, ...args: unknown[]): unknown;
|
|
snapshot(): Readonly<Record<string, unknown>>;
|
|
dispose(): void;
|
|
}
|
|
interface WrnexusBrowserGlobals {
|
|
__wrnexusHydrateScopes?(root?: ParentNode): void;
|
|
__wrnexusDisposeBehaviors?(root?: ParentNode): void;
|
|
}
|
|
|
|
/**
|
|
* @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(development?: boolean): string;
|
|
/** Component-specific controllers, loaded only when their marker is present. */
|
|
declare function getComponentControllerRuntime(development?: boolean): 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;
|
|
declare function getActionRuntime(): string;
|
|
|
|
export { ACTION_RUNTIME, ActionClientError, type ActionClientOptions, type ActionResult, type ClientModuleScope, type HydrationScopeApi, NAV_RUNTIME, type OutputHandler, type OutputHost, REACTIVE_RUNTIME, REALTIME_RUNTIME, type ServerCallOptions, WrnServerCallError, type WrnexusBrowserGlobals, callServerFunction, collectRefs, createActionClient, createOutputProxy, createServerProxy, getActionRuntime, getComponentControllerRuntime, getNavRuntime, getReactiveRuntime, getRealtimeRuntime, invalidateClientModule, invokeOutput, loadClientFunctions, registerOutputHandler };
|
|
</code></pre></section><section id="examples" class="examples"><h2>Examples</h2><p>Copy-ready examples from the installed package documentation.</p><div class="example-grid"><article class="example-card"><h3>Server side — serve the runtime strings from your router (example with Bun.serve)</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><article class="example-card"><h3>Browser side — server-rendered HTML that the reactive runtime hydrates</h3><pre data-language="html"><code><div data-scope="count: 0, showPassword: false">
|
|
<button data-on-click="count++">+1</button>
|
|
<span data-text="count"></span>
|
|
<p>Total: {{count}}</p>
|
|
<input type="{showPassword ? 'text' : 'password'}" />
|
|
<button
|
|
data-on-click="showPassword = !showPassword"
|
|
aria-label="{showPassword ? 'Hide password' : 'Show password'}"
|
|
>
|
|
Toggle password
|
|
</button>
|
|
</div>
|
|
<script src="/__wrnexus/reactive.js"></script></code></pre></article><article class="example-card"><h3>A realtime chat, fully declarative</h3><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></article><article class="example-card"><h3>Or drive a room from code</h3><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></article></div></section></article></div>
|
|
<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="#navigation-state-preservation">Navigation state preservation</a><a class="toc-level-3" href="#typed-server-actions">Typed server actions</a><a class="toc-level-3" href="#overview">Overview</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><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.8.8</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
|
|
</div>
|
|
}
|
|
}
|