docs: update portal for WRNexusJS 0.8.0
This commit is contained in:
@@ -10,11 +10,21 @@ page wrnexuscsr {
|
||||
<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.7.0</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
|
||||
<div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.8.0</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 class="portal-main docs-layout">
|
||||
<article id="main" 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.7.0</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.7.0</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"><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>
|
||||
<article id="main" 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.0</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.0</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>
|
||||
@@ -42,7 +52,10 @@ getRealtimeRuntime(): string // → REALTIME_RUNTIME</code></pre>
|
||||
<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. 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>
|
||||
<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>
|
||||
@@ -189,6 +202,8 @@ declare const NAV_RUNTIME: string;
|
||||
*/
|
||||
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>>;
|
||||
@@ -223,6 +238,23 @@ interface ClientModuleScope {
|
||||
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;
|
||||
@@ -250,8 +282,9 @@ declare function getReactiveRuntime(): string;
|
||||
declare function getNavRuntime(): string;
|
||||
/** The realtime client runtime served at `/__wrnexus/realtime.js`. */
|
||||
declare function getRealtimeRuntime(): string;
|
||||
declare function getActionRuntime(): string;
|
||||
|
||||
export { type ClientModuleScope, type HydrationScopeApi, NAV_RUNTIME, type OutputHandler, type OutputHost, REACTIVE_RUNTIME, REALTIME_RUNTIME, type ServerCallOptions, WrnServerCallError, type WrnexusBrowserGlobals, callServerFunction, collectRefs, createOutputProxy, createServerProxy, getNavRuntime, getReactiveRuntime, getRealtimeRuntime, invalidateClientModule, invokeOutput, loadClientFunctions, registerOutputHandler };
|
||||
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, 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> = {
|
||||
@@ -295,9 +328,9 @@ Bun.serve({
|
||||
<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>
|
||||
<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="#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>
|
||||
<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.7.0</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>
|
||||
<footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.8.0</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>
|
||||
<BackToTop />
|
||||
</div>
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user