@webjsdev/core 0.7.1

package/src/suspense.js

@@ -0,0 +1,46 @@
+/**
+ * `Suspense({ fallback, children })`: deferred boundary for streaming SSR.
+ *
+ * ```js
+ * import { html, Suspense } from '@webjsdev/core';
+ *
+ * export default function Page() {
+ *   return html`
+ *     <h1>Catalogue</h1>
+ *     ${Suspense({ fallback: html`<p>Loading…</p>`, children: fetchExpensive() })}
+ *   `;
+ * }
+ *
+ * async function fetchExpensive() {
+ *   const items = await db.item.findMany();
+ *   return html`<ul>${items.map(i => html`<li>${i.name}</li>`)}</ul>`;
+ * }
+ * ```
+ *
+ * The server emits the fallback immediately, closes no tags, and keeps the
+ * response stream open. When the children promise resolves, the resolved
+ * HTML streams as a `<template data-webjs-resolve="ID">…</template>` plus
+ * a tiny inline script that swaps the fallback for the real content. No
+ * hydration runtime required: just a `replaceWith` call.
+ *
+ * Nested Suspense works: a resolved template can itself contain Suspense,
+ * whose fallback is emitted inside the template until its own promise lands.
+ */
+const SUSPENSE = Symbol.for('webjs.suspense');
+
+/**
+ * @typedef {{ _$webjsSuspense: true, fallback: unknown, children: unknown }} SuspenseBoundary
+ *
+ * @param {{ fallback: unknown, children: unknown | Promise<unknown> }} props
+ * @returns {SuspenseBoundary}
+ */
+export function Suspense(props) {
+  return { _$webjsSuspense: true, fallback: props.fallback, children: props.children };
+}
+
+/** @param {unknown} x */
+export function isSuspense(x) {
+  return !!x && typeof x === 'object' && /** @type any */ (x)._$webjsSuspense === true;
+}
+
+export { SUSPENSE };

package/src/task.js

@@ -0,0 +1,386 @@
+/**
+ * Task: a ReactiveController for managing async data fetching inside
+ * web components.
+ *
+ * ## When to use
+ *
+ * Use Task when a component needs to fetch data and render
+ * loading / error / success states. Task handles `AbortController`
+ * automatically: navigating away or re-running cancels the previous
+ * in-flight request, preventing race conditions and wasted work.
+ *
+ * Good fits:
+ * - Search-as-you-type / autocomplete
+ * - Lazy-loaded data panels that fetch when a tab becomes active
+ * - Infinite scroll / pagination within a component
+ * - Any component-scoped async operation (geocoding, AI completions, etc.)
+ *
+ * ## When NOT to use
+ *
+ * - For **page-level** data loading, use async page functions or server
+ *   actions instead: they run on the server, stream via Suspense, and
+ *   produce real HTML for crawlers.
+ * - For one-shot fire-and-forget mutations (form submit, delete), a plain
+ *   `async` method on the component is usually simpler.
+ *
+ * ## Quick example
+ *
+ * ```js
+ * import { WebComponent, html } from '@webjsdev/core';
+ * import { Task } from '@webjsdev/core/task';
+ *
+ * class UserSearch extends WebComponent {
+ *   static properties = { query: { type: String } };
+ *
+ *   _search = new Task(this, {
+ *     task: async (query, { signal }) => {
+ *       const res = await fetch(`/api/users?q=${query}`, { signal });
+ *       if (!res.ok) throw new Error('Search failed');
+ *       return res.json();
+ *     },
+ *     args: () => [this.query],
+ *   });
+ *
+ *   render() {
+ *     return html`
+ *       <input .value=${this.query}
+ *              @input=${e => this.query = e.target.value}>
+ *       ${this._search.render({
+ *         initial:  ()     => html`<p>Type to search</p>`,
+ *         pending:  ()     => html`<p>Searching…</p>`,
+ *         complete: (users)=> html`<ul>${users.map(u => html`<li>${u.name}</li>`)}</ul>`,
+ *         error:    (err)  => html`<p class="error">${err.message}</p>`,
+ *       })}
+ *     `;
+ *   }
+ * }
+ * UserSearch.register('user-search');
+ * ```
+ *
+ * ### Manual control
+ *
+ * Set `autoRun: false` to disable automatic re-runs on arg changes and
+ * call `task.run()` explicitly (e.g. on button click):
+ *
+ * ```js
+ * this._export = new Task(this, {
+ *   task: async (format, { signal }) => { … },
+ *   args: () => [this.format],
+ *   autoRun: false,
+ * });
+ *
+ * // In render:
+ * html`<button @click=${() => this._export.run()}>Export</button>`
+ * ```
+ *
+ * @module
+ */
+
+// ---------------------------------------------------------------------------
+// TaskStatus enum
+// ---------------------------------------------------------------------------
+
+/**
+ * Possible states of a Task.
+ *
+ * | Value | Name      | Meaning                              |
+ * | ----- | --------- | ------------------------------------ |
+ * | 0     | INITIAL   | Task has never run.                  |
+ * | 1     | PENDING   | Task is in-flight (awaiting).        |
+ * | 2     | COMPLETE  | Task resolved successfully.          |
+ * | 3     | ERROR     | Task rejected or threw.              |
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const TaskStatus = /** @type {const} */ ({
+  INITIAL: 0,
+  PENDING: 1,
+  COMPLETE: 2,
+  ERROR: 3,
+});
+
+// ---------------------------------------------------------------------------
+// Task controller
+// ---------------------------------------------------------------------------
+
+/**
+ * A ReactiveController that runs an async function, tracks its lifecycle
+ * (initial → pending → complete | error), and triggers host re-renders
+ * on state transitions.
+ *
+ * ## AI guidance
+ *
+ * - **`task.render()`** provides declarative async UI. Pass an object
+ *   with `initial`, `pending`, `complete`, and `error` callbacks and
+ *   Task returns the right template for the current status:
+ *   ```js
+ *   task.render({
+ *     pending:  ()     => html`Loading…`,
+ *     complete: (data) => html`${data.name}`,
+ *     error:    (err)  => html`Error: ${err.message}`,
+ *   })
+ *   ```
+ *   Omitted callbacks return `undefined` (renders nothing).
+ *
+ * - **AbortController** is managed automatically. Each call to `run()`
+ *   aborts the previous in-flight request. The `{ signal }` object
+ *   passed as the last argument to your task function is wired to the
+ *   internal AbortController: pass it to `fetch()`, `ReadableStream`,
+ *   or any other signal-aware API.
+ *
+ * - **`args`** is a function that returns an array. It is re-evaluated
+ *   on every `hostUpdate()`. When `autoRun` is true (the default) and
+ *   the args have changed (shallow identity comparison per element),
+ *   the task automatically re-runs. This is how search-as-you-type and
+ *   reactive data loading work.
+ *
+ * - When the host disconnects (e.g. the component is removed from the
+ *   DOM), any in-flight task is aborted automatically: no cleanup
+ *   needed.
+ *
+ * @template T
+ */
+export class Task {
+  /**
+   * @param {import('./component.js').WebComponent} host
+   *   The host component that owns this task.
+   * @param {{
+   *   task: (...args: [...unknown[], { signal: AbortSignal }]) => Promise<T>,
+   *   args?: () => unknown[],
+   *   autoRun?: boolean
+   * }} options
+   *   - `task`: The async function to execute. Receives the spread args
+   *     from `args()` followed by an options object with `{ signal }`.
+   *   - `args`: A function returning an array of arguments. Re-evaluated
+   *     on every host update cycle. Defaults to `() => []`.
+   *   - `autoRun`: When true (default), the task re-runs automatically
+   *     whenever `args()` returns values that differ from the previous
+   *     run. Set to false for manual-only triggering via `run()`.
+   */
+  constructor(host, { task, args, autoRun = true }) {
+    /** @type {import('./component.js').WebComponent} */
+    this._host = host;
+    /** @type {(...args: any[]) => Promise<T>} */
+    this._taskFn = task;
+    /** @type {() => unknown[]} */
+    this._argsFn = args || (() => []);
+    /** @type {boolean} */
+    this._autoRun = autoRun;
+
+    /** @type {number}: current TaskStatus */
+    this._status = TaskStatus.INITIAL;
+    /** @type {T | undefined} */
+    this._value = undefined;
+    /** @type {unknown} */
+    this._error = undefined;
+
+    /** @type {AbortController | null} */
+    this._abortController = null;
+
+    /**
+     * Snapshot of args from the last run, used for shallow comparison.
+     * @type {unknown[] | null}
+     */
+    this._prevArgs = null;
+
+    if (typeof host.addController === 'function') {
+      host.addController(this);
+    }
+  }
+
+  // ---- Read-only public properties ----------------------------------------
+
+  /**
+   * Current status of the task.
+   * @returns {number} One of the `TaskStatus` enum values.
+   */
+  get status() {
+    return this._status;
+  }
+
+  /**
+   * The resolved value when status is `COMPLETE`, otherwise `undefined`.
+   * @returns {T | undefined}
+   */
+  get value() {
+    return this._value;
+  }
+
+  /**
+   * The rejection reason when status is `ERROR`, otherwise `undefined`.
+   * @returns {unknown}
+   */
+  get error() {
+    return this._error;
+  }
+
+  // ---- Public methods -----------------------------------------------------
+
+  /**
+   * Manually trigger (or re-trigger) the task.
+   *
+   * Any in-flight invocation is aborted before the new one starts. The
+   * `args()` function is called to produce the current arguments.
+   *
+   * @returns {Promise<void>} Resolves when the task finishes (or is
+   *   superseded). Does not reject: errors are captured in `this.error`.
+   */
+  async run() {
+    // Abort previous.
+    this.abort();
+
+    const ac = new AbortController();
+    this._abortController = ac;
+
+    const args = this._argsFn();
+    this._prevArgs = args;
+
+    this._status = TaskStatus.PENDING;
+    this._error = undefined;
+    this._requestHostUpdate();
+
+    try {
+      const result = await this._taskFn(...args, { signal: ac.signal });
+
+      // Guard: if this invocation was superseded while awaiting, discard.
+      if (ac.signal.aborted) return;
+
+      this._value = result;
+      this._status = TaskStatus.COMPLETE;
+      this._error = undefined;
+    } catch (err) {
+      if (ac.signal.aborted) return;
+
+      this._error = err;
+      this._status = TaskStatus.ERROR;
+      this._value = undefined;
+    } finally {
+      if (this._abortController === ac) {
+        this._abortController = null;
+      }
+    }
+
+    this._requestHostUpdate();
+  }
+
+  /**
+   * Abort the current in-flight task (if any).
+   *
+   * The AbortController's signal is set to aborted, which cancels any
+   * `fetch()` or other signal-aware work inside the task function. The
+   * task's status is **not** changed: it remains at whatever state it
+   * was before the abort. A subsequent `run()` will transition to
+   * PENDING.
+   */
+  abort() {
+    if (this._abortController) {
+      this._abortController.abort();
+      this._abortController = null;
+    }
+  }
+
+  /**
+   * Declarative async UI helper.
+   *
+   * Returns the result of calling the callback matching the current
+   * status. Omitted callbacks return `undefined`.
+   *
+   * ```js
+   * task.render({
+   *   initial:  ()      => html`<p>Ready</p>`,
+   *   pending:  ()      => html`<p>Loading…</p>`,
+   *   complete: (data)  => html`<p>${data}</p>`,
+   *   error:    (err)   => html`<p>Error: ${err.message}</p>`,
+   * })
+   * ```
+   *
+   * @param {{
+   *   initial?:  () => unknown,
+   *   pending?:  () => unknown,
+   *   complete?: (value: T) => unknown,
+   *   error?:    (error: unknown) => unknown,
+   * }} handlers
+   * @returns {unknown} The template result for the current status.
+   */
+  render(handlers = {}) {
+    switch (this._status) {
+      case TaskStatus.INITIAL:
+        return handlers.initial?.();
+      case TaskStatus.PENDING:
+        return handlers.pending?.();
+      case TaskStatus.COMPLETE:
+        return handlers.complete?.(/** @type {T} */ (this._value));
+      case TaskStatus.ERROR:
+        return handlers.error?.(this._error);
+      default:
+        return undefined;
+    }
+  }
+
+  // ---- ReactiveController lifecycle ---------------------------------------
+
+  /**
+   * Called before the host renders. When `autoRun` is enabled, checks
+   * whether `args()` have changed and re-runs the task if so.
+   */
+  hostUpdate() {
+    if (!this._autoRun) return;
+
+    const nextArgs = this._argsFn();
+
+    if (!this._argsEqual(this._prevArgs, nextArgs)) {
+      // Don't await: the run will trigger another host update when it
+      // transitions status.
+      this.run();
+    }
+  }
+
+  /**
+   * Called after the host has rendered. Currently a no-op; required by
+   * the ReactiveController interface.
+   */
+  hostUpdated() {}
+
+  /**
+   * Called when the host connects to the DOM. Currently a no-op -
+   * initial run (if autoRun) happens on the first `hostUpdate()`.
+   */
+  hostConnected() {}
+
+  /**
+   * Called when the host disconnects from the DOM. Aborts any in-flight
+   * task to prevent updates to an unmounted component.
+   */
+  hostDisconnected() {
+    this.abort();
+  }
+
+  // ---- Internal -----------------------------------------------------------
+
+  /** @private */
+  _requestHostUpdate() {
+    if (typeof this._host.requestUpdate === 'function') {
+      this._host.requestUpdate();
+    }
+  }
+
+  /**
+   * Shallow comparison of two args arrays by identity (`===`).
+   * Returns true if both are non-null, same length, and every element
+   * is strictly equal.
+   *
+   * @param {unknown[] | null} a
+   * @param {unknown[]} b
+   * @returns {boolean}
+   * @private
+   */
+  _argsEqual(a, b) {
+    if (a === null) return false;
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (a[i] !== b[i]) return false;
+    }
+    return true;
+  }
+}

package/src/testing.js

@@ -0,0 +1,157 @@
+/**
+ * Testing utilities for webjs components.
+ *
+ * **When to use (AI hint):** Import from `'@webjsdev/core/testing'` in test files
+ * to create, render, and interact with web components in a Node.js test
+ * environment using linkedom (a lightweight DOM implementation).
+ *
+ * ```js
+ * import { fixture, waitForUpdate } from '@webjsdev/core/testing';
+ * import { html } from '@webjsdev/core';
+ *
+ * const el = await fixture(html`<my-counter count="5"></my-counter>`);
+ * assert.equal(el.shadowRoot.textContent.trim(), '5');
+ *
+ * el.setAttribute('count', '10');
+ * await waitForUpdate(el);
+ * assert.equal(el.shadowRoot.textContent.trim(), '10');
+ * ```
+ *
+ * @module testing
+ */
+
+/**
+ * Create a component from a TemplateResult, connect it to a DOM,
+ * and wait for its first render to complete.
+ *
+ * Uses linkedom (if available) to create a minimal DOM environment
+ * in Node.js. Falls back to the global `document` in a browser.
+ *
+ * **When to use (AI hint):** Use `fixture()` in unit tests to quickly
+ * mount a component and assert against its rendered shadow DOM.
+ * This is the primary test helper: start every component test with it.
+ *
+ * @param {import('./html.js').TemplateResult | string} template
+ *   Either a `html\`…\`` result or a raw HTML string.
+ * @returns {Promise<Element>} The first child element of the rendered container.
+ */
+export async function fixture(template) {
+  const container = getContainer();
+  if (typeof template === 'string') {
+    container.innerHTML = template;
+  } else if (template && typeof template === 'object' && template._$webjs === 'template') {
+    // Render using the server renderer to produce HTML with DSD,
+    // then parse it into the container.
+    const { renderToString } = await import('./render-server.js');
+    const html = await renderToString(template, { ssr: true });
+    container.innerHTML = html;
+  } else {
+    throw new Error('fixture() expects an html`…` template or an HTML string');
+  }
+
+  // Wait a microtask for component connectedCallback + first render
+  await new Promise((r) => setTimeout(r, 0));
+
+  const el = container.firstElementChild;
+  if (!el) throw new Error('fixture() produced no element');
+  return el;
+}
+
+/**
+ * Wait for a component's next render cycle to complete.
+ *
+ * **When to use (AI hint):** Call after `setAttribute()`, a property
+ * assignment, `requestUpdate()`, or a signal `set()` the component
+ * subscribes to, any change that triggers a re-render. The re-render
+ * is async (microtask-batched), so you need to await before asserting.
+ *
+ * @param {Element} el  The component element.
+ * @returns {Promise<void>}
+ */
+export async function waitForUpdate(el) {
+  // WebComponent batches via queueMicrotask, so two microtask yields
+  // is sufficient: one for the scheduling microtask, one for any
+  // cascading updates.
+  await new Promise((r) => setTimeout(r, 0));
+  await new Promise((r) => setTimeout(r, 0));
+}
+
+/**
+ * Simulate a click event on an element.
+ *
+ * **When to use (AI hint):** Use to test click handlers in components
+ * without a real browser. Works with elements inside shadow DOM.
+ *
+ * @param {Element} el  The element to click.
+ */
+export function click(el) {
+  el.dispatchEvent(new Event('click', { bubbles: true, composed: true }));
+}
+
+/**
+ * Query an element inside a component's shadow root.
+ *
+ * **When to use (AI hint):** Shorthand for `el.shadowRoot.querySelector(sel)`.
+ * Returns null if no shadow root or no match.
+ *
+ * @param {Element} el  The component host element.
+ * @param {string} selector  CSS selector.
+ * @returns {Element | null}
+ */
+export function shadowQuery(el, selector) {
+  return el.shadowRoot?.querySelector(selector) ?? null;
+}
+
+/**
+ * Get all matching elements inside a component's shadow root.
+ *
+ * @param {Element} el  The component host element.
+ * @param {string} selector  CSS selector.
+ * @returns {NodeList}
+ */
+export function shadowQueryAll(el, selector) {
+  return el.shadowRoot?.querySelectorAll(selector) ?? [];
+}
+
+/* ------------------------------------------------------------------ */
+/* Internal: DOM container management                                  */
+/* ------------------------------------------------------------------ */
+
+let _doc = null;
+let _container = null;
+
+function getContainer() {
+  if (_container) {
+    _container.innerHTML = '';
+    return _container;
+  }
+
+  // Browser environment
+  if (typeof document !== 'undefined' && typeof document.createElement === 'function') {
+    _container = document.createElement('div');
+    document.body?.appendChild(_container);
+    return _container;
+  }
+
+  // Node.js environment: use linkedom
+  try {
+    const { parseHTML } = /** @type {any} */ (
+      // Dynamic import syntax can't be used in a sync function,
+      // but linkedom is a CJS package that works with createRequire.
+      (() => {
+        const { createRequire } = /** @type {any} */ (globalThis).__webjs_require ||
+          (() => { throw new Error('no require'); })();
+        return createRequire(import.meta.url)('linkedom');
+      })()
+    );
+    const { document: doc } = parseHTML('<!DOCTYPE html><html><body></body></html>');
+    _doc = doc;
+    _container = doc.createElement('div');
+    doc.body.appendChild(_container);
+    return _container;
+  } catch {
+    throw new Error(
+      'fixture() requires a DOM environment. In Node.js, install linkedom: npm i -D linkedom'
+    );
+  }
+}

package/src/webjs-frame.js

@@ -0,0 +1,65 @@
+/**
+ * `<webjs-frame id="...">`: escape-hatch partial-swap region.
+ *
+ * The framework's primary partial-nav mechanism auto-derives swap
+ * boundaries from the folder structure (each `layout.{js,ts}`'s
+ * children-slot is wrapped in a `<!--wj:children:<segment>-->` marker
+ * pair). For 99% of apps that's all you need.
+ *
+ * `<webjs-frame>` is the escape hatch for the 1%: partial-swap
+ * regions that are NOT tied to a folder layout. Typical use cases:
+ *
+ *   - A widget on a marketing page that updates on a navigation
+ *     without changing the URL hierarchy.
+ *   - A tabbed UI where each tab navigates to a sub-route but the
+ *     surrounding tab strip should not re-render.
+ *   - Lazy-loaded cards on a dashboard where a click swaps just the
+ *     card's content.
+ *
+ * Usage:
+ *
+ *   html`
+ *     <section>
+ *       <h2>Activity</h2>
+ *       <webjs-frame id="activity">
+ *         <!-- contents that should be swapped on internal nav -->
+ *         <p>Showing today's activity.</p>
+ *       </webjs-frame>
+ *     </section>
+ *   `
+ *
+ * On a link click, the router checks `closest('webjs-frame')` from
+ * the click target. If a frame is found AND the incoming response
+ * contains a `<webjs-frame id="<matching-id>">`, the swap is scoped
+ * to that frame's children: outer DOM is untouched. If no matching
+ * frame appears in the response, the router falls through to the
+ * normal layout-marker mechanism (and then to full body swap).
+ *
+ * The element is **light DOM**: no shadow root, no slot mechanics.
+ * Children are normal light-DOM children that the router replaces
+ * via the same keyed reconciler used for layout marker swaps. This
+ * means scroll position, input values, and `<details>` open state
+ * are preserved for any matched elements inside the frame.
+ *
+ * @element webjs-frame
+ * @attr {string} id: Required. The frame's identifier, used by
+ *   `closest()` on the client and `querySelector` on the response.
+ */
+// Defined lazily inside an IIFE so that importing this module on the
+// server (Node) doesn't trip a `HTMLElement is not defined` reference
+// error. Server-side renderers never touch the class: the element
+// is always rendered as `<webjs-frame id=...>` plain HTML by the
+// renderToString pipeline.
+const WebjsFrame = (typeof HTMLElement !== 'undefined')
+  ? class WebjsFrame extends HTMLElement {
+    // No shadow root and no render(). The element exists purely as a
+    // swap anchor with an addressable `id`. Children are normal
+    // light-DOM children. The router does all the work.
+  }
+  : /** @type {any} */ (null);
+
+if (typeof customElements !== 'undefined' && WebjsFrame && !customElements.get('webjs-frame')) {
+  customElements.define('webjs-frame', WebjsFrame);
+}
+
+export { WebjsFrame };