@webjsdev/core 0.7.9 → 0.7.11

package/src/testing.js

@@ -57,6 +57,60 @@ export async function fixture(template) {
   return el;
 }
 
+/**
+ * Server-render a template THEN hydrate it in the same browser session,
+ * awaiting the element's native `updateComplete` so the post-hydration DOM
+ * is observable deterministically.
+ *
+ * This is the SSR + hydrate entry, distinct from `fixture()`. `fixture()`
+ * server-renders and parses the HTML into the container, but it only waits
+ * two macrotasks and never awaits the real update cycle. `ssrFixture()`
+ * renders the SAME SSR markup (with DSD), lets the browser upgrade the
+ * custom element, then awaits the element's `updateComplete` promise (the
+ * actual render-cycle resolution), not a timer.
+ *
+ * **What it proves.** The SSR'd markup and the post-hydration DOM agree.
+ * Because the returned element is the live, hydrated element, a hydration
+ * mismatch (the server rendered one thing, the client rendered another) is
+ * observable: compare the SSR'd inner HTML against `el.innerHTML` /
+ * `el.shadowRoot.innerHTML` after this resolves and a divergence shows up.
+ *
+ * **When to use (AI hint):** Use `ssrFixture()` when the test is about the
+ * SSR-then-hydrate round-trip (does the server paint survive hydration, does
+ * a `.prop` decode back, does a signal-backed render match). Use the plain
+ * `fixture()` for a quick mount where the SSR-vs-hydrate distinction does not
+ * matter.
+ *
+ * Requires a real DOM (the WTR Chromium session). The component class must
+ * already be registered (the test imports its module, same as `fixture()`).
+ *
+ * @param {import('./html.js').TemplateResult | string} template
+ *   Either a `html\`…\`` result or a raw HTML string.
+ * @returns {Promise<Element>} The hydrated root element.
+ */
+export async function ssrFixture(template) {
+  const container = getContainer();
+  if (typeof template === 'string') {
+    container.innerHTML = template;
+  } else if (template && typeof template === 'object' && template._$webjs === 'template') {
+    const { renderToString } = await import('./render-server.js');
+    const html = await renderToString(template, { ssr: true });
+    container.innerHTML = html;
+  } else {
+    throw new Error('ssrFixture() expects an html`…` template or an HTML string');
+  }
+
+  const el = container.firstElementChild;
+  if (!el) throw new Error('ssrFixture() produced no element');
+
+  // Drive the real update cycle. The browser upgrades the SSR'd custom
+  // element on innerHTML assignment; its connectedCallback queues the first
+  // render. Awaiting the native updateComplete promise (not a timer) is the
+  // whole point: the test observes the post-hydration DOM deterministically.
+  await flushUpdate(el);
+  return el;
+}
+
 /**
  * Wait for a component's next render cycle to complete.
  *
@@ -65,17 +119,105 @@ export async function fixture(template) {
  * subscribes to, any change that triggers a re-render. The re-render
  * is async (microtask-batched), so you need to await before asserting.
  *
+ * Awaits the element's native `updateComplete` promise when present (the
+ * real render-cycle resolution), falling back to a microtask flush for a
+ * plain element that has no `updateComplete` (back-compatible).
+ *
  * @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 flushUpdate(el);
+}
+
+/**
+ * Await the real update cycle of an element. For a WebComponent this awaits
+ * the native `updateComplete` promise; for anything else it yields two
+ * macrotasks (the legacy behaviour) so cascading updates settle.
+ *
+ * @param {Element} el
+ * @returns {Promise<void>}
+ */
+async function flushUpdate(el) {
+  const uc = el && /** @type {any} */ (el).updateComplete;
+  if (uc && typeof uc.then === 'function') {
+    await uc;
+    // A microtask yield lets any cascading child update flush too.
+    await Promise.resolve();
+    return;
+  }
   await new Promise((r) => setTimeout(r, 0));
   await new Promise((r) => setTimeout(r, 0));
 }
 
+/**
+ * Assert an element's subtree has no accessibility violations, using the
+ * axe-core engine in the real browser. OPT-IN: nothing calls this for you,
+ * it is never a forced gate.
+ *
+ * axe-core is a TEST-ONLY peer: it is imported dynamically here, so it is
+ * NOT a hard dependency of `@webjsdev/core`. An app that does not do a11y
+ * testing never needs it. Install it where you run the test:
+ * `npm install -D axe-core`.
+ *
+ * On a violation it throws an Error whose message lists each violation's id,
+ * impact, a short help string, and the failing nodes' selectors, so the test
+ * failure is actionable. On zero violations it resolves.
+ *
+ * ```js
+ * import { ssrFixture, assertNoA11yViolations } from '@webjsdev/core/testing';
+ * const el = await ssrFixture(html`<my-form></my-form>`);
+ * await assertNoA11yViolations(el);
+ * // tune rules: await assertNoA11yViolations(el, { rules: { 'color-contrast': { enabled: false } } });
+ * ```
+ *
+ * @param {Element} el  The element (subtree root) to scan.
+ * @param {object} [opts]  Options passed through to `axe.run` (e.g. `rules`).
+ * @returns {Promise<void>}
+ */
+export async function assertNoA11yViolations(el, opts) {
+  if (!el || typeof el !== 'object') {
+    throw new Error('assertNoA11yViolations() expects a DOM element');
+  }
+  let axe;
+  try {
+    const mod = await import('axe-core');
+    // axe-core ships a UMD bundle. Depending on how the test runner / bundler
+    // wraps it, the engine may sit on the namespace, on `.default`, on a
+    // nested `.default.default`, or only as the `window.axe` side-effect the
+    // UMD installs. Probe in that order for a `run` function.
+    const candidates = [mod, mod && mod.default, mod && mod.default && mod.default.default,
+      typeof globalThis !== 'undefined' ? globalThis.axe : undefined];
+    axe = candidates.find((c) => c && typeof c.run === 'function');
+  } catch {
+    throw new Error(
+      'assertNoA11yViolations needs axe-core. Install it: npm install -D axe-core'
+    );
+  }
+  if (!axe || typeof axe.run !== 'function') {
+    throw new Error(
+      'assertNoA11yViolations needs axe-core. Install it: npm install -D axe-core'
+    );
+  }
+
+  const results = await axe.run(el, opts || {});
+  const violations = results.violations || [];
+  if (violations.length === 0) return;
+
+  const lines = violations.map((v) => {
+    const targets = (v.nodes || [])
+      .map((n) => (n.target || []).join(' '))
+      .filter(Boolean)
+      .join(', ');
+    return `  - [${v.id}] (${v.impact || 'unknown'}) ${v.help}${targets ? ` -> ${targets}` : ''}`;
+  });
+  const err = new Error(
+    `a11y: ${violations.length} accessibility violation(s) found:\n${lines.join('\n')}`
+  );
+  err.name = 'AssertionError';
+  throw err;
+}
+
 /**
  * Simulate a click event on an element.
  *

package/src/webjs-frame.js

@@ -35,26 +35,174 @@
  * frame appears in the response, the router falls through to the
  * normal layout-marker mechanism (and then to full body swap).
  *
+ * External targeting (Turbo's `data-turbo-frame`): a trigger (an `<a>`
+ * or a `<form>`) that is NOT nested inside the frame can still drive it
+ * by carrying `data-webjs-frame="<id>"`. The router resolves the id via
+ * `getElementById` in the current document, so an external nav/sidebar
+ * link or a filter form drives a content frame it does not enclose. An
+ * id that does not resolve to a live `<webjs-frame>` warns once and falls
+ * back to a normal navigation (fail-safe, never a wrong-region swap). The
+ * reserved token `data-webjs-frame="_top"` on a trigger INSIDE a frame
+ * breaks OUT to a full-page navigation instead of swapping the frame.
+ *
+ * Busy state: while a frame's navigation is in flight the router sets the
+ * native `aria-busy="true"` on the frame element and clears it (to
+ * `"false"`) on completion, success, failure, or abort, so assistive tech
+ * announces the loading state and CSS can style `webjs-frame[aria-busy="true"]`.
+ * It also dispatches a bubbling `webjs:frame-busy` event on the frame at
+ * both edges (detail `{ frameId, busy: true }` then `{ frameId, busy: false }`),
+ * so app code can hook the start and finish.
+ *
  * 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.
  *
+ * With JS disabled a `data-webjs-frame` link is an inert attribute on a
+ * plain `<a href>`, so the click is a normal full-page navigation, the
+ * correct progressive-enhancement fallback.
+ *
+ * Self-loading (`src` + `loading`): a frame MAY fetch its own content. With
+ * a `src` attribute the frame self-fetches that URL as a frame nav and applies
+ * the matching `<webjs-frame id>` subtree from the response into itself, through
+ * the SAME router frame-swap path a click-driven frame nav uses (so the busy
+ * lifecycle, the navigation-error recovery, and the frame-missing fallback all
+ * apply). The `loading` attribute picks WHEN:
+ *
+ *   - `loading="eager"` (or absent, the default): fetch on `connectedCallback`.
+ *   - `loading="lazy"`: fetch when the frame first scrolls into view, reusing
+ *     the same IntersectionObserver budget (`rootMargin: '200px'`) as a
+ *     `static lazy = true` component.
+ *
+ * A `src` change after connect re-loads. Eager-connect, the lazy observer, and
+ * a `src` mutation never double-fire: a per-element loaded/loading guard keyed
+ * on the resolved URL coalesces them.
+ *
+ * PROGRESSIVE ENHANCEMENT CAVEAT: a `src`-driven frame is JS-DEPENDENT. The
+ * browser does NOT natively fetch `<webjs-frame src>` (unlike `<iframe>`), so
+ * with JS off the frame shows only whatever children were server-rendered into
+ * it. Use `src`/`loading` for DEFERRED content (comments, a recommendations
+ * rail, an expensive card) where a JS-off empty/placeholder state is acceptable.
+ * For content that MUST exist without JS, render it server-side into the frame
+ * instead of using `src` (the self-load then replaces those fallback children).
+ *
  * @element webjs-frame
  * @attr {string} id: Required. The frame's identifier, used by
- *   `closest()` on the client and `querySelector` on the response.
+ *   `closest()` on the client, `getElementById` for external
+ *   `data-webjs-frame` targeting, and `querySelector` on the response.
+ * @attr {string} src: Optional. A same-origin URL the frame self-fetches as a
+ *   frame nav, applying the matching `<webjs-frame id>` subtree into itself.
+ * @attr {string} loading: Optional. `eager` (default) fetches `src` on connect;
+ *   `lazy` fetches when the frame scrolls into view.
+ * @fires webjs:frame-busy: Bubbling. Dispatched on the frame when its
+ *   navigation starts (`detail.busy === true`) and finishes
+ *   (`detail.busy === false`); `detail.frameId` names the frame.
  */
 // 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.
+// is always rendered as `<webjs-frame id=... src=... loading=...>` 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.
+    constructor() {
+      super();
+      /**
+       * The `src` value most recently loaded (or loading). Guards against a
+       * double-load when eager connect, the lazy observer, and a `src`
+       * mutation all want to fire: a load only starts when the resolved URL
+       * differs from this. `null` means "nothing loaded yet".
+       * @type {string | null}
+       */
+      this._webjsLoadedSrc = null;
+      /**
+       * Teardown for the lazy IntersectionObserver subscription, so a
+       * disconnect or a `src` change stops observing.
+       * @type {(() => void) | null}
+       */
+      this._webjsLazyTeardown = null;
+    }
+
+    static get observedAttributes() { return ['src']; }
+
+    connectedCallback() {
+      this._webjsScheduleLoad();
+    }
+
+    disconnectedCallback() {
+      if (this._webjsLazyTeardown) { this._webjsLazyTeardown(); this._webjsLazyTeardown = null; }
+    }
+
+    /**
+     * @param {string} name
+     * @param {string | null} _old
+     * @param {string | null} _next
+     */
+    attributeChangedCallback(name, _old, _next) {
+      // Only react to a `src` change AFTER the element is connected (the
+      // initial attribute parse fires this before connectedCallback; the
+      // connect path handles the first load). A live `src` swap re-loads.
+      if (name === 'src' && this.isConnected) this._webjsScheduleLoad();
+    }
+
+    /**
+     * Decide whether and when to self-load based on `src` + `loading`,
+     * coalescing the three triggers (eager connect, lazy viewport, `src`
+     * mutation) so the frame never double-fetches the same URL.
+     */
+    _webjsScheduleLoad() {
+      const src = this.getAttribute('src');
+      // No src: nothing to self-load (a normal swap-anchor frame). Drop any
+      // pending lazy observation left over from a previous src.
+      if (!src) {
+        if (this._webjsLazyTeardown) { this._webjsLazyTeardown(); this._webjsLazyTeardown = null; }
+        this._webjsLoadedSrc = null;
+        return;
+      }
+      // Resolve so the dedupe key matches what loadFrame requests, and so a
+      // relative `src` compares stably.
+      let resolved = src;
+      try { resolved = new URL(src, location.href).href; } catch { /* keep raw */ }
+      // Already loaded (or loading) this exact URL: no double-load.
+      if (resolved === this._webjsLoadedSrc) return;
+
+      // A new src supersedes any in-flight lazy observation.
+      if (this._webjsLazyTeardown) { this._webjsLazyTeardown(); this._webjsLazyTeardown = null; }
+
+      const lazy = (this.getAttribute('loading') || 'eager').toLowerCase() === 'lazy';
+      if (lazy) {
+        // Defer the fetch until the frame enters the viewport, reusing the
+        // shared per-element IntersectionObserver. Mark the URL as claimed
+        // NOW so a redundant schedule (e.g. attributeChanged firing again
+        // with the same src) does not re-observe.
+        this._webjsLoadedSrc = resolved;
+        import('./lazy-loader.js').then(({ observeViewportOnce }) => {
+          // Bail if the src changed again while the import was in flight.
+          if (this._webjsLoadedSrc !== resolved || !this.isConnected) return;
+          this._webjsLazyTeardown = observeViewportOnce(this, () => {
+            this._webjsLazyTeardown = null;
+            this._webjsLoad(resolved);
+          });
+        });
+      } else {
+        this._webjsLoadedSrc = resolved;
+        this._webjsLoad(resolved);
+      }
+    }
+
+    /**
+     * Run the actual frame self-load through the router's frame-swap path.
+     * @param {string} resolved  The already-resolved absolute URL.
+     */
+    _webjsLoad(resolved) {
+      import('./router-client.js').then(({ loadFrame }) => {
+        // The src may have changed again (or the frame disconnected) between
+        // scheduling and the import resolving; only load if we still own it.
+        if (this._webjsLoadedSrc !== resolved || !this.isConnected) return;
+        loadFrame(this, resolved);
+      });
+    }
   }
   : /** @type {any} */ (null);
 

package/src/webjs-stream.js

@@ -0,0 +1,170 @@
+/**
+ * `<webjs-stream action="..." target="...">`: a self-applying surgical
+ * DOM-update element (Turbo Streams parity, webjs-shaped).
+ *
+ * The router's primary mechanism swaps a whole layout-marker region (or a
+ * `<webjs-frame>`). That is coarse: a comment-append, an optimistic row
+ * removal, or a toast insertion has to redraw a whole region or hand-write
+ * DOM JS. `<webjs-stream>` is the element-level grammar for those surgical
+ * updates. The payload is plain HTML the browser already parses: a
+ * `<webjs-stream>` wrapping a single `<template>`, carrying an `action` and a
+ * `target` (an element id) or `targets` (a CSS selector). There is no protocol
+ * parser; the element clones its `<template>` content and applies it with
+ * native DOM methods, then removes itself.
+ *
+ *   <webjs-stream action="append" target="comments">
+ *     <template><li>Nice post!</li></template>
+ *   </webjs-stream>
+ *
+ * Actions (mirroring Turbo's set):
+ *
+ *   - `append`  / `prepend`: add the template content as the last / first
+ *     children of the target.
+ *   - `before`  / `after`: insert the template content as siblings before /
+ *     after the target.
+ *   - `replace`: replace the target element itself with the template content.
+ *   - `update`: replace the target's children with the template content.
+ *   - `remove`: remove the target element (no template needed).
+ *
+ * Two delivery paths share this ONE applier:
+ *
+ *   - **HTTP (content-negotiated form response).** A `<form>` submission rides
+ *     the client router, which sends `Accept: text/vnd.webjs-stream.html`. When
+ *     the server answers with that content type, the router applies the
+ *     `<webjs-stream>` elements in the body surgically (no region swap). With
+ *     JS OFF the browser sends no such Accept, so the server returns a normal
+ *     render/redirect and the form degrades to a full-page round-trip. The
+ *     grammar is therefore additive and progressive-enhancement-safe.
+ *   - **Live channel (`broadcast()` / `connectWS`).** A server message that is
+ *     a `<webjs-stream>` HTML string is applied by `renderStream(message)` from
+ *     a `connectWS` handler, so chat / notifications / presence reuse the same
+ *     applier instead of bespoke per-app DOM code.
+ *
+ * The element is inert server-side: `renderToString` emits it as plain
+ * `<webjs-stream action=... target=...>` HTML and never touches the class
+ * (it is defined only when `HTMLElement` exists). A `<webjs-stream>` that is
+ * server-rendered into a page (rather than streamed in) self-applies on
+ * hydration exactly as a streamed one does, so there is no separate code path.
+ *
+ * @element webjs-stream
+ * @attr {string} action: Required. One of append / prepend / before / after /
+ *   replace / update / remove.
+ * @attr {string} target: An element id to apply the action to.
+ * @attr {string} targets: A CSS selector matching one or more targets (applied
+ *   to each). `target` and `targets` are mutually exclusive; `target` wins.
+ */
+
+/** The actions that operate by inserting the template content. */
+const INSERT_ACTIONS = new Set(['append', 'prepend', 'before', 'after', 'replace', 'update']);
+
+/**
+ * Apply one resolved action against one target element.
+ * @param {string} action
+ * @param {Element} target
+ * @param {DocumentFragment | null} frag  Cloned template content (null for remove).
+ */
+function applyTo(action, target, frag) {
+  switch (action) {
+    case 'append': if (frag) target.append(frag); break;
+    case 'prepend': if (frag) target.prepend(frag); break;
+    case 'before': if (frag) target.before(frag); break;
+    case 'after': if (frag) target.after(frag); break;
+    case 'replace': if (frag) target.replaceWith(frag); break;
+    case 'update': if (frag) target.replaceChildren(frag); break;
+    case 'remove': target.remove(); break;
+    default: break; // unknown action: no-op
+  }
+}
+
+const WebjsStream = (typeof HTMLElement !== 'undefined')
+  ? class WebjsStream extends HTMLElement {
+    connectedCallback() {
+      // Apply once. A streamed-in element runs this on insertion; a
+      // server-rendered one runs it on upgrade. Either way it self-removes.
+      if (this._webjsApplied) return;
+      this._webjsApplied = true;
+      this._webjsApply();
+    }
+
+    _webjsApply() {
+      const action = (this.getAttribute('action') || '').toLowerCase();
+      const doc = this.ownerDocument || document;
+      // Resolve targets: an id via `target`, or a selector via `targets`.
+      /** @type {Element[]} */
+      let targets = [];
+      const id = this.getAttribute('target');
+      if (id) {
+        const el = doc.getElementById(id);
+        if (el) targets = [el];
+      } else {
+        const sel = this.getAttribute('targets');
+        if (sel) {
+          try { targets = Array.from(doc.querySelectorAll(sel)); } catch { targets = []; }
+        }
+      }
+      // The single child <template> carries the content for an insert action.
+      const tpl = INSERT_ACTIONS.has(action)
+        ? /** @type {HTMLTemplateElement | null} */ (this.querySelector('template'))
+        : null;
+      try {
+        for (const target of targets) {
+          // Clone per target so multiple `targets` each get their own nodes.
+          const frag = tpl ? /** @type {DocumentFragment} */ (tpl.content.cloneNode(true)) : null;
+          applyTo(action, target, frag);
+        }
+      } finally {
+        // The stream element itself never stays in the live DOM.
+        this.remove();
+      }
+    }
+  }
+  : /** @type {any} */ (null);
+
+if (typeof customElements !== 'undefined' && WebjsStream && !customElements.get('webjs-stream')) {
+  customElements.define('webjs-stream', WebjsStream);
+}
+
+/**
+ * Apply a server-sent stream payload to the live DOM. The payload is HTML
+ * containing one or more `<webjs-stream>` elements (each wrapping a
+ * `<template>`); appending them to the document upgrades each one, which
+ * self-applies its action and self-removes. Use this from a `connectWS` /
+ * `broadcast` message handler so a live channel reuses the same applier as the
+ * HTTP path.
+ *
+ *   connectWS('/feed', { onMessage: (m) => renderStream(m) });
+ *
+ * @param {string | DocumentFragment | Node} input  The stream HTML (or parsed nodes).
+ * @param {Document} [doc]  The document to apply into (defaults to `document`).
+ */
+function renderStream(input, doc) {
+  const d = doc || (typeof document !== 'undefined' ? document : null);
+  if (!d) return;
+  /** @type {DocumentFragment | Node | null} */
+  let frag = null;
+  if (typeof input === 'string') {
+    const tpl = d.createElement('template');
+    tpl.innerHTML = input;
+    frag = tpl.content;
+  } else if (input && /** @type any */ (input).nodeType) {
+    frag = input; // a DocumentFragment or a single Node
+  } else {
+    return;
+  }
+  // Append ONLY the <webjs-stream> elements (each self-applies + self-removes on
+  // connect). Skipping the intervening whitespace text nodes a multi-action
+  // payload carries (the parts are joined by newlines) avoids accreting stray
+  // text nodes in <body> on a long-lived live channel.
+  const found = /** @type any */ (frag).querySelectorAll
+    ? Array.from(/** @type any */ (frag).querySelectorAll('webjs-stream'))
+    : [];
+  if (found.length) {
+    for (const s of found) d.body.append(s);
+  } else {
+    // No nested <webjs-stream> found (e.g. a single element passed directly):
+    // append the input verbatim so the caller's node still reaches the DOM.
+    d.body.append(frag);
+  }
+}
+
+export { WebjsStream, renderStream };