@webjsdev/core 0.8.0 → 0.9.1

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/webjs-config.d.ts

@@ -220,7 +220,7 @@ export type WebjsDoctorSeverity = 'off' | 'warn' | 'error';
 export interface WebjsDoctorConfig {
   /**
    * Per-check severity, keyed by the stable doctor code (`NODE_VERSION`,
-   * `UNMARKED_ASSET_LINKS`, `ELISION_CARRIERS`, and so on; `webjs doctor --json`
+   * `UNMARKED_ASSET_LINKS`, `ROUTE_BROWSER_CODE`, and so on; `webjs doctor --json`
    * carries the code on every result). A code with no entry keeps its default:
    * `error` for a hard toolchain failure, `warn` otherwise. This is how CI gates
    * on a chosen subset without `--strict` making every warning fatal.
@@ -277,13 +277,6 @@ export interface WebjsCspConfig {
  * Next.js superset.
  */
 export interface WebjsConfig {
-  /**
-   * Display-only and inert-route dead-JS elision switch. Default `true`.
-   * Set to `false` to ship every module's JS app-wide. The `WEBJS_ELIDE`
-   * env override wins over this.
-   */
-  elide?: boolean;
-
   /**
    * SSR action-result seeding switch (#472). Default `true`. When on, a
    * `'use server'` action's SSR result is serialized into the page so an

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;