@webjsdev/core 0.9.0 → 0.9.1

package/index.d.ts

@@ -147,6 +147,37 @@ export interface OptimisticState<State, Action> {
 }
 
 // Declarative Signature with custom update reducer
+/**
+ * Show a mutation's result before the server confirms it. The declarative form
+ * keeps a queue of pending payloads on a component; `.value` is `source()` with
+ * each folded in by `update` (keep it pure: it runs on every render), and an
+ * entry drops when the promise passed to `.add()` settles. Use it in a
+ * degrade-first form: bound to the action, so it posts with JavaScript off.
+ *
+ * @example
+ * class TodoList extends WebComponent {
+ *   static properties = { todos: { type: Array } };
+ *   declare todos: Todo[];                          // seeded by the page: .todos=${todos}
+ *   pending = optimistic(this, {
+ *     source: () => this.todos,
+ *     update: (rows: Todo[], add: { id: string; title: string }) => [...rows, { ...add, done: false }],
+ *   });
+ *   async add(e: SubmitEvent) {
+ *     e.preventDefault();
+ *     const form = e.target as HTMLFormElement;
+ *     const title = String(new FormData(form).get('title'));
+ *     form.reset();
+ *     const promise = createTodo({ title });        // a 'use server' action, by RPC
+ *     this.pending.add({ id: crypto.randomUUID(), title }, promise);
+ *     const result = await promise;
+ *     if (result.success && result.data) this.todos = [...this.todos, result.data];
+ *   }
+ *   render() {
+ *     return html`<form action=${createTodo} @submit=${(e: SubmitEvent) => this.add(e)}>...</form>
+ *       <ul>${this.pending.value.map((t) => html`<li>${t.title}</li>`)}</ul>`;
+ *   }
+ * }
+ */
 export function optimistic<State, Action>(
   host: { requestUpdate?(): void },
   options: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "type": "module",
   "description": "The runtime for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Ships the html and css template tags, the WebComponent base class, signals, directives, and the isomorphic renderers.",
   "types": "./index.d.ts",

package/src/asset-url.d.ts

@@ -1,3 +1,21 @@
 /** Content-hashed `public/` asset urls (#1194). Server-side resolver; the browser bundle drops setAssetUrlProvider and `asset` returns its argument. */
 export function setAssetUrlProvider(fn: (path: string) => string): void;
+/**
+ * The url of a `public/` file with a content hash added in production
+ * (`/app.css?v=<hash>`, served `immutable` for a year), so a deploy can never
+ * leave a stale copy cached. Unchanged in dev and in the browser.
+ *
+ * @example
+ * ```ts
+ * // app/(marketing)/layout.ts: a stylesheet link that leads a layout is moved into <head>
+ * import { html, asset } from '@webjsdev/core';
+ * import type { LayoutProps } from '@webjsdev/core';
+ *
+ * export default function MarketingLayout({ children }: LayoutProps) {
+ *   return html`<link rel="stylesheet" href=${asset('/marketing.css')}>${children}`;
+ * }
+ * // Call it inside the render function of a page, layout or metadata route, not at
+ * // module scope or in a component (hydration would swap the hashed url for the bare path).
+ * ```
+ */
 export function asset(path: string): string;

package/src/csp-nonce.d.ts

@@ -1,3 +1,21 @@
 /** Per-request CSP nonce provider (#259). Server-side; the browser bundle drops setCspNonceProvider. */
 export function setCspNonceProvider(fn: () => string): void;
+/**
+ * The current request's CSP nonce while rendering on the server, `''` when CSP
+ * is off and always `''` in the browser. Turn CSP on with `"webjs": { "csp": true }`
+ * in package.json; the framework already stamps its own scripts.
+ *
+ * @example
+ * ```ts
+ * // app/layout.ts (the root layout): stamp it on an inline script you write yourself
+ * import { html, cspNonce } from '@webjsdev/core';
+ * import type { LayoutProps } from '@webjsdev/core';
+ *
+ * export default function RootLayout({ children }: LayoutProps) {
+ *   return html`<!doctype html><html><head>
+ *     <script nonce=${cspNonce()}>document.documentElement.dataset.js = 'on'</script>
+ *   </head><body>${children}</body></html>`;
+ * }
+ * ```
+ */
 export function cspNonce(): string;

package/src/testing.d.ts

@@ -1,6 +1,48 @@
 import type { TemplateResult } from './html.js';
 
+/**
+ * Server-render a template (or an HTML string) into a container in the test
+ * page, wait two macrotasks for the element to upgrade, and resolve its first
+ * element. A quick mount; use `ssrFixture` when the hydration round trip matters.
+ *
+ * @example
+ * ```js
+ * // modules/todos/components/browser/todo-item.test.js, run with `webjs test --browser`
+ * import { html } from '@webjsdev/core';
+ * import { fixture } from '@webjsdev/core/testing';
+ * import '../todo-item.ts';
+ *
+ * suite('<todo-item>', () => {   // the runner's UI is tdd (suite / test), and a test throws to fail
+ *   test('renders its title', async () => {
+ *     const el = await fixture(html`<todo-item title="Buy milk"></todo-item>`);
+ *     if (!el.textContent?.includes('Buy milk')) throw new Error('the title is missing');
+ *   });
+ * });
+ * ```
+ */
 export function fixture(template: TemplateResult | string): Promise<Element>;
+/**
+ * Server-render a template, hydrate it in the real browser, and resolve once
+ * the element's `updateComplete` settles, so the post-hydration DOM is what the
+ * test reads. The component module must be imported first.
+ *
+ * @example
+ * ```js
+ * // modules/counter/components/browser/counter-card.test.js, run with `webjs test --browser`
+ * import { html } from '@webjsdev/core';
+ * import { ssrFixture, waitForUpdate } from '@webjsdev/core/testing';
+ * import '../counter-card.ts';
+ *
+ * suite('<counter-card>', () => {
+ *   test('counts a click after hydration', async () => {
+ *     const el = await ssrFixture(html`<counter-card></counter-card>`);
+ *     el.querySelector('button')?.click();
+ *     await waitForUpdate(el);
+ *     if (!el.textContent?.includes('1')) throw new Error('the count did not advance');
+ *   });
+ * });
+ * ```
+ */
 export function ssrFixture(template: TemplateResult | string): Promise<Element>;
 export function waitForUpdate(el: Element): Promise<void>;
 export function assertNoA11yViolations(el: Element, opts?: Record<string, unknown>): Promise<void>;

package/src/websocket-client.d.ts

@@ -19,4 +19,28 @@ export interface WSConnection {
   readonly readyState: 0 | 1 | 2 | 3;
 }
 
+/**
+ * Open a managed WebSocket: a relative path is promoted to ws:// or wss://, it
+ * reconnects with backoff unless `reconnect: false`, a string message that is
+ * JSON arrives parsed, `send()` JSON-encodes an object and queues while
+ * disconnected, and `close()` stops for good.
+ *
+ * @example
+ * ```ts
+ * // modules/chat/components/chat-feed.ts, fed by app/api/chat/route.ts (its WS export)
+ * import { WebComponent, html, signal, connectWS, type WSConnection } from '@webjsdev/core';
+ *
+ * export class ChatFeed extends WebComponent {
+ *   readonly #lines = signal<string[]>([]);
+ *   #conn: WSConnection | null = null;
+ *   connectedCallback() {   // browser only, so no socket opens during SSR
+ *     super.connectedCallback();
+ *     this.#conn = connectWS('/api/chat', { onMessage: (msg) => this.#lines.set([...this.#lines.get(), String(msg)]) });
+ *   }
+ *   disconnectedCallback() { super.disconnectedCallback(); this.#conn?.close(); }
+ *   render() { return html`<ul>${this.#lines.get().map((line) => html`<li>${line}</li>`)}</ul>`; }
+ * }
+ * ChatFeed.register('chat-feed');
+ * ```
+ */
 export function connectWS(url: string, opts?: ConnectOptions): WSConnection;