@webjsdev/core 0.7.10 → 0.7.11

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 };