@webjsdev/core 0.7.50 → 0.7.53

package/src/router-client/dom-parse.js

@@ -0,0 +1,150 @@
+/**
+ * Client router: dom-parse.
+ *
+ * Moved verbatim out of the pre-split `router-client.js`; that barrel holds
+ * the router's full contract and the public entry points.
+ *
+ * @module
+ */
+
+/**
+ * Parse a navigation response into a Document, PRESERVING COMMENTS.
+ *
+ * Comments are load-bearing here, not incidental: the partial swap pairs on
+ * `<!--wj:children:<path>-->` markers and hydration keys off `<!--webjs-hydrate-->`.
+ * `Document.parseHTMLUnsafe` would be the natural choice (it is the only
+ * single-pass API that also processes Declarative Shadow DOM) but it STRIPS
+ * EVERY COMMENT in Chromium 150 (#1007), which deletes both. So it is used only
+ * when a one-time probe proves it lossless on this engine, and otherwise we parse
+ * with DOMParser (comments preserved; DSD is left unprocessed, see
+ * `parseDocumentPreservingComments` for why that gap beats both ways of closing it).
+ *
+ * A partial-nav response (#936) is an INNER fragment that BEGINS with the
+ * `<!--wj:children:<segment>:<route-key>-->` boundary open and carries no
+ * `<!doctype>`/`<html>`. Parsing such a fragment as a DOCUMENT hoists that
+ * leading comment OUT of `<body>` (the HTML parser's "before html" insertion
+ * mode makes a leading comment a child of the document, before `<html>`), so
+ * `collectBoundaries(doc.body)` never sees the opening boundary, finds no
+ * shared segment, and `applySwap` degrades to a full load. So a fragment is
+ * parsed in BODY (fragment) context instead, keeping the boundary with its
+ * content.
+ * `body.setHTMLUnsafe` also processes Declarative Shadow DOM, so a shadow
+ * component inside the swapped content still re-attaches its root; the
+ * `<template>` path is the fallback for browsers without it (markers preserved,
+ * DSD not, which matches the pre-`setHTMLUnsafe` baseline).
+ *
+ * @param {string} html
+ * @returns {Document | null}
+ */
+export function parseHTML(html) {
+  const isFragment = !/^\s*(?:<!doctype|<html)/i.test(html);
+  if (isFragment && typeof document !== 'undefined' && document.implementation) {
+    try {
+      const doc = document.implementation.createHTMLDocument();
+      if (typeof doc.body.setHTMLUnsafe === 'function') {
+        doc.body.setHTMLUnsafe(html);
+      } else {
+        const t = doc.createElement('template');
+        t.innerHTML = html;
+        doc.body.appendChild(t.content);
+      }
+      return doc;
+    } catch {
+      // Fall through to a document parse (still functional, just the #936 path).
+    }
+  }
+  if (
+    typeof Document !== 'undefined' &&
+    typeof Document.parseHTMLUnsafe === 'function' &&
+    parseHTMLUnsafePreservesComments()
+  ) {
+    return Document.parseHTMLUnsafe(html);
+  }
+  return parseDocumentPreservingComments(html);
+}
+
+/**
+ * Is `Document.parseHTMLUnsafe` lossless for comments?
+ *
+ * Chromium 150 strips EVERY comment from `Document.parseHTMLUnsafe` output
+ * (#1007). No other parse API does: `DOMParser`, `setHTMLUnsafe`,
+ * `template.innerHTML`, and plain `innerHTML` all preserve them, and the
+ * document's own navigation parser preserves them (which is why a hard refresh
+ * always looked fine and only soft nav broke). MDN documents parseHTMLUnsafe as
+ * the parse-WITHOUT-sanitization entry point, so this reads as a browser defect
+ * rather than intent, but the whole router rides on comments (`wj:children`
+ * layout markers) and so does hydration (`webjs-hydrate`), so we cannot take
+ * the risk either way.
+ *
+ * Probed once, lazily, rather than version-sniffed: when the browser is fixed
+ * we silently return to the fast single-pass native path, and a future browser
+ * that regresses the same way is caught with no code change.
+ *
+ * @returns {boolean}
+ */
+let _parseUnsafeLossless = null;
+
+function parseHTMLUnsafePreservesComments() {
+  if (_parseUnsafeLossless !== null) return _parseUnsafeLossless;
+  try {
+    const probe = Document.parseHTMLUnsafe('<!doctype html><body><!--c--><i></i>');
+    _parseUnsafeLossless = probe?.body?.firstChild?.nodeType === 8;
+  } catch {
+    _parseUnsafeLossless = false;
+  }
+  return _parseUnsafeLossless;
+}
+
+/**
+ * Clear the memoized losslessness probe. Test-only: a browser cannot change
+ * mid-session, so nothing in the runtime needs this. Tests SIMULATE a stripping
+ * parser (rather than depending on the runner's browser actually being an
+ * affected version, which the Chromium web-test-runner currently resolves is not) and reset the
+ * memo around that stub.
+ */
+export function resetParseProbe() {
+  _parseUnsafeLossless = null;
+}
+
+/**
+ * Parse a FULL document while preserving comments.
+ *
+ * `DOMParser` keeps comments but does NOT process Declarative Shadow DOM, so a
+ * `<template shadowrootmode>` stays an inert template here. That is a DELIBERATE
+ * limitation on this path, and both obvious ways to "fix" it are worse than the
+ * gap (measured on Chromium 150, not reasoned about):
+ *
+ *   - `body.setHTMLUnsafe(body.innerHTML)` re-serializes, and that round-trip is
+ *     not idempotent: Chromium omits the spec's LF-compensation rule (append
+ *     U+000A when a `pre` / `textarea` / `listing` element's first Text child
+ *     starts with one), so `<textarea>\n\nfoo</textarea>` parses to `"\nfoo"`
+ *     natively but `"foo"` after a round-trip. In a `<textarea>` that is silent
+ *     form-data corruption: a soft nav would submit different bytes than a hard
+ *     refresh.
+ *   - Attaching each root by hand (`host.attachShadow()` + move the template's
+ *     nodes) is USELESS on the common path and HARMFUL on the other. Useless
+ *     because the marker swap imports with `document.importNode(n, true)`, which
+ *     drops a shadow root unless it is `clonable`, and SSR emits a bare
+ *     `<template shadowrootmode="open">`, so the root never survives the import
+ *     and `component.js` re-attaches from scratch exactly as it always did.
+ *     Harmful because the full-body-swap path ADOPTS instead, so a script-created
+ *     root does survive, and a script-created root is not `declarative`: the spec
+ *     only permits a second `attachShadow()` over an existing root when that root
+ *     is declarative, so any element whose constructor unconditionally calls
+ *     `attachShadow()` then throws `NotSupportedError` on upgrade, where the
+ *     native parse it replaced worked fine.
+ *
+ * The gap this leaves is narrow and strictly better than the bug it replaces: on
+ * a comment-stripping browser only, an element that depends on DSD content and
+ * ships NO JavaScript loses that content on a full-body-swap navigation. Every
+ * WebJs `static shadow = true` component is unaffected, because it attaches and
+ * renders its own root on upgrade (`component.js`, guarded by `if
+ * (!this.shadowRoot)`), and a soft nav runs JS by definition. Tracked separately.
+ *
+ * @param {string} html
+ * @returns {Document | null}
+ */
+function parseDocumentPreservingComments(html) {
+  if (typeof DOMParser === 'undefined') return null;
+  return new DOMParser().parseFromString(html, 'text/html');
+}

package/src/router-client/events.js

@@ -0,0 +1,182 @@
+/**
+ * Client router: events.
+ *
+ * Moved verbatim out of the pre-split `router-client.js`; that barrel holds
+ * the router's full contract and the public entry points.
+ *
+ * @module
+ */
+import { findAnchorInPath } from './anchors.js';
+import { NON_HTML_EXTENSIONS } from './constants.js';
+import { enabled, markFragmentNav } from './state.js';
+import { warnIfActionSubmissionCannotDeliver } from './diagnostics.js';
+import { buildSubmitFormData, encodeSubmitBody, getSubmitAction, getSubmitEnctype, getSubmitMethod } from './form-encoder.js';
+import { resolveTargetFrameId } from './frames.js';
+import { resolvePreserveScroll } from './scroll.js';
+import { absorbFragmentClickPopState, performNavigation, performSubmission } from './navigator.js';
+
+/** @param {MouseEvent} e */
+export function onClick(e) {
+  if (!enabled) return;
+  if (e.defaultPrevented || e.button !== 0) return;
+  if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+
+  const anchor = findAnchorInPath(e);
+  if (!anchor) return;
+  if (anchor.hasAttribute('download')) return;
+  if (anchor.target && anchor.target !== '_self') return;
+
+  const href = anchor.href;
+  if (!href) return;
+
+  const url = new URL(href);
+  if (url.origin !== location.origin) return;
+  // `href.includes('#')` rather than `url.hash`, because the URL serializer
+  // reports BOTH a null fragment and an empty one as `''`, and only the second
+  // is a fragment navigation. `href="#"` keeps its `#` in `href` and per the
+  // spec navigates to the document element (the back-to-top idiom), while
+  // `href=""` resolves to the current url with the fragment REMOVED, which the
+  // spec reloads rather than jumping, so it must stay a router navigation. A
+  // `#` cannot appear anywhere else in a serialized url: the parser encodes it
+  // in the path and starts the fragment at it in the query (#1437).
+  if (url.pathname === location.pathname && url.search === location.search && url.href.includes('#')) {
+    // Leave a mark for the popstate this jump is about to fire. A REPEAT click
+    // replaces its history entry rather than pushing, so that popstate arrives
+    // with an unchanged url and is indistinguishable by comparison from a real
+    // Back between two entries that share one. Provenance is the only thing
+    // that separates them, and this is where the router has it (#1437).
+    markFragmentNav(url.href);
+    return;
+  }
+  // Checked AFTER the fragment bow-out on purpose. `data-no-router` opts out of
+  // ROUTING, and the bow-out above routes nothing either way, but the browser
+  // still performs the native jump and still fires the popstate that has to be
+  // recognised. Returning here first would leave EVERY click of a
+  // `data-no-router` in-page anchor unmarked, first and repeat alike, since the
+  // mark is the only thing that absorbs one, so each would be re-navigated
+  // destructively (#1437).
+  if (anchor.hasAttribute('data-no-router')) return;
+  if (NON_HTML_EXTENSIONS.test(url.pathname)) return;
+
+  e.preventDefault();
+  // Resolve the target frame. An explicit `data-webjs-frame` on (or above)
+  // the anchor drives a frame by id from anywhere in the document (an
+  // external sidebar/nav link), `_top` breaks out to a full-page nav, and
+  // absence falls back to the closest enclosing frame (today's default).
+  const frameId = resolveTargetFrameId(anchor);
+  // #1436: `data-preserve-scroll` on the anchor or an ancestor keeps the reader
+  // where they are instead of scrolling to top. Read here, beside the other
+  // per-link opt-outs, and carried on the navigation's opts bag. Inert on a
+  // frame-targeted link, which already writes no scroll (#1427).
+  performNavigation(href, false, frameId, { preserveScroll: resolvePreserveScroll(anchor) });
+}
+
+/** @param {PopStateEvent} _e */
+export function onPopState(_e) {
+  // The popstate an in-page fragment CLICK produces is not a navigation: the
+  // browser has already done the jump, so re-fetching and re-swapping would
+  // destroy live DOM identity and undo it (#1437). Absorbed only when the
+  // router MARKED that click on its way out (the bow-out above); a popstate
+  // with no mark behind it is a traversal and stays on the normal path,
+  // whatever its url. The callee's docstring has the full reasoning, including
+  // why no url comparison can stand in for the mark.
+  if (absorbFragmentClickPopState(location.href)) return;
+  // popstate has no DOM anchor, so no frame context: restore via cache or
+  // refetch the whole document.
+  performNavigation(location.href, true, null);
+}
+
+/**
+ * Intercept form submissions. BUBBLE phase (see enableClientRouter) so we run
+ * AFTER a component's per-element `@submit` handler, which is bound at-target.
+ * That ordering is what makes the `if (e.defaultPrevented) return` guard below
+ * work: a component that calls `e.preventDefault()` (the chat / comments forms,
+ * or any JS-handled form) has already run, so we see the prevented default and
+ * leave the form alone. A capture listener would fire us first, before the
+ * component, defeating the guard and wrongly navigating the page out from under
+ * a JS-handled form.
+ *
+ * Filtering mirrors Turbo's `form_submit_observer.js`:
+ *   - `data-no-router` on form or submitter → full browser submit.
+ *   - `formmethod="dialog"` → native <dialog> dismissal, never routed.
+ *   - `target` / `formtarget` that isn't `_self` → iframe / popup target.
+ *   - Cross-origin or non-HTML-extension action → let the browser handle.
+ *
+ * Submitter attributes (`formmethod`, `formaction`, `formenctype`) take
+ * precedence over the form's own: HTML5 form-submission algorithm.
+ *
+ * @param {SubmitEvent} e
+ */
+export function onSubmit(e) {
+  if (!enabled) return;
+  if (e.defaultPrevented) return;
+
+  const form = /** @type {HTMLFormElement | null} */ (e.target);
+  // Duck-type check rather than `instanceof HTMLFormElement`: linkedom
+  // and other non-browser DOMs don't always mark form elements as
+  // instances of the window's HTMLFormElement class.
+  if (!form || form.nodeType !== 1 || form.tagName !== 'FORM') return;
+  if (form.hasAttribute('data-no-router')) return;
+
+  const submitter = /** @type {HTMLElement | null} */ (e.submitter ?? null);
+  if (submitter && submitter.hasAttribute('data-no-router')) return;
+
+  // Presence, not truthiness, exactly as `getSubmitAction` resolves the action
+  // (#1322). The form-submission algorithm asks whether the submitter HAS a
+  // `formtarget`, so a present-but-empty one overrides the form and then means
+  // the current browsing context, per the rules for choosing a navigable.
+  const target = (submitter && submitter.hasAttribute('formtarget'))
+    ? (submitter.getAttribute('formtarget') || '')
+    : (form.getAttribute('target') || '');
+  if (target && target !== '_self') return;
+
+  const method = getSubmitMethod(form, submitter);
+  if (method === 'dialog') return;
+
+  const enctype = getSubmitEnctype(form, submitter);
+  const isSafeMethod = method === 'get' || method === 'head';
+
+  const action = getSubmitAction(form, submitter);
+  /** @type {URL} */ let url;
+  try { url = new URL(action, location.href); }
+  catch { return; }
+  if (url.origin !== location.origin) return;
+  if (NON_HTML_EXTENSIONS.test(url.pathname)) return;
+
+  // Built once, after the cheap bails (a submission the router ignores should
+  // not pay for a FormData) and BEFORE the text/plain bail below. That order
+  // matters for the dev report: `text/plain` is precisely the case where the
+  // router declines the submission, so reporting after the bail would be dead
+  // code for the one shape that most needs it, since both paths are then
+  // answered with a 405 and the author gets no other signal.
+  const rawBody = buildSubmitFormData(form, submitter);
+  // Observational, and silent in production. Runs before `preventDefault`.
+  warnIfActionSubmissionCannotDeliver(form, submitter, method, rawBody);
+
+  // #1307: `text/plain` is a legal native encoding the server cannot parse
+  // (`looksLikeFormSubmission` accepts multipart and urlencoded only), and
+  // there is no honest way to send it over `fetch` and have the response mean
+  // anything. Bail to the browser so BOTH paths do the same thing, rather than
+  // silently sending multipart, which is what made the same form behave one
+  // way with JS and another way without it. Turbo enumerates this encoding and
+  // then sends FormData anyway, which is the divergence being avoided here. A
+  // safe method ignores the enctype entirely, per the submission algorithm.
+  if (!isSafeMethod && enctype === 'text/plain') return;
+
+  const body = encodeSubmitBody(rawBody, enctype);
+
+  e.preventDefault();
+  // Resolve the target frame for the submit, same precedence as a link:
+  // an explicit `data-webjs-frame` on (or above) the form or its submitter
+  // wins, `_top` breaks out, absence falls back to the enclosing frame.
+  const frameId = resolveTargetFrameId(submitter || form);
+  // Same trigger precedence as the frame line above. The form is passed as a
+  // FALLBACK rather than relied on through the submitter's ancestors, because a
+  // submitter is form-associated by `form="id"` and may sit outside the form
+  // entirely, where `closest()` would never reach it. The trigger still wins
+  // when it resolves a carrier, so `data-preserve-scroll="false"` on a button
+  // inside a marked form still opts that button out.
+  const preserveScroll = resolvePreserveScroll(submitter || form, form);
+  performSubmission(url.href, method, body, frameId, form, { preserveScroll });
+}
+