@webjsdev/core 0.7.65 → 0.9.0

package/src/metadata.d.ts

@@ -11,8 +11,8 @@
  *     export const metadata: Metadata = { title: 'Home', description: '…' };
  *     export async function generateMetadata(ctx: MetadataContext): Promise<Metadata> { … }
  *
- * The shape mirrors what ssr.js actually consumes (and the skill's
- * references/routing-and-pages.md documents), NOT Next.js's full superset.
+ * The shape mirrors what ssr.js actually consumes (and
+ * https://webjs.dev/docs/metadata-routes documents), NOT Next.js's full superset.
  * Every field is optional. Zero
  * runtime cost: nothing in this file ships to the browser.
  */
@@ -209,7 +209,7 @@ export interface PreloadDescriptor {
  * optional. Where the framework accepts a string OR an object (`title`,
  * `viewport`, `robots`, `appleWebApp`, `icons`), the type is a union.
  *
- * @see the skill's references/routing-and-pages.md for the field-by-field emission reference.
+ * @see https://webjs.dev/docs/metadata-routes for the field-by-field emission reference.
  */
 export interface Metadata {
   /** -> `<title>`. Plain string or `{ template, default, absolute }`. */
@@ -337,3 +337,22 @@ export interface MetadataContext {
    */
   actionData?: unknown;
 }
+
+/**
+ * A page's or layout's `generateMetadata` export, Next.js's: called per
+ * request with the page context and a promise of the metadata the outer
+ * layouts resolved, it returns this segment's {@link Metadata}. Export a static
+ * `metadata` object instead when nothing depends on the request.
+ *
+ * @example
+ * ```ts
+ * // app/posts/[slug]/page.ts
+ * import type { Metadata, MetadataContext } from '@webjsdev/core';
+ * export async function generateMetadata({ params }: MetadataContext, parent: Promise<Metadata>): Promise<Metadata> {
+ *   const post = await getPost(params.slug);
+ *   const images = (await parent).openGraph?.images ?? [];
+ *   return { title: post?.title ?? 'Not found', openGraph: { images } };
+ * }
+ * ```
+ */
+export type GenerateMetadata = (ctx: MetadataContext, parent: Promise<Metadata>) => Metadata | Promise<Metadata>;

package/src/nav.d.ts

@@ -1,5 +1,8 @@
 export function notFound(): never;
-export function redirect(url: string, status?: number | { status?: number }): never;
+/** How the client records a redirect that reaches the browser (Next's RedirectType). */
+export type RedirectType = 'push' | 'replace';
+export function redirect(url: string, status?: number | RedirectType | { status?: number; type?: RedirectType }): never;
+export function permanentRedirect(url: string, type?: RedirectType): never;
 export function forbidden(): never;
 export function unauthorized(): never;
 export function isNotFound(e: unknown): boolean;

package/src/nav.js

@@ -59,31 +59,64 @@ export function unauthorized() {
  * each kind of redirect gets the conventional code:
  *   - thrown during a GET page/layout render (a gating redirect like an auth
  *     bounce to `/login`): 302 Found, the conventional GET-to-GET code.
- *   - thrown from a server action (a POST): 307 Temporary Redirect, which is
- *     method-preserving so the action's intent survives. (The PRG success
- *     path uses 303 separately.)
+ *   - thrown from a `route.ts` handler: 307 Temporary Redirect.
+ *   - thrown from a server action bound to a form: always 303 See Other, so
+ *     the browser follows with a GET and the action runs once (Next parity).
+ *   - thrown from a server action called over RPC: the client router
+ *     navigates to the target.
  * Pass an explicit status to override: `redirect('/x', 308)` (permanent) or the
- * options form `redirect('/x', { status: 301 })`. An explicit status wins at
- * every catching site.
+ * options form `redirect('/x', { status: 301 })`. An explicit status wins
+ * everywhere except a form-bound action, which always answers 303.
+ *
+ * The second argument may instead be `'push'` or `'replace'` (Next's
+ * `RedirectType`): how the client records the navigation when the redirect
+ * reaches the browser from an action called over RPC. `'push'` is the
+ * default there, as in a Next.js server action.
  *
  * @param {string} url
- * @param {number | { status?: number }} [status] explicit status (number) or
- *   `{ status }`; omit to let the catching site pick (302 for a GET gate, 307
- *   for an action).
+ * @param {number | RedirectType | { status?: number, type?: RedirectType }} [status]
+ *   explicit status (number), a `RedirectType`, or `{ status, type }`; omit to
+ *   let the catching site pick.
  * @returns {never}
  */
 export function redirect(url, status) {
-  const code = typeof status === 'object' && status !== null ? status.status : status;
+  /** @type {number | undefined} */
+  let code;
+  /** @type {RedirectType | undefined} */
+  let type;
+  if (status === 'push' || status === 'replace') type = status;
+  else if (typeof status === 'object' && status !== null) {
+    code = status.status;
+    if (status.type === 'push' || status.type === 'replace') type = status.type;
+  } else if (typeof status === 'number') code = status;
   const err = new Error(`webjs: redirect(${url})`);
   /** @type any */ (err).__webjs = REDIRECT;
   /** @type any */ (err).url = url;
   // Left undefined when the caller did not specify one, so the catching site
-  // can apply its convention (302 GET gate vs 307 action). A caller-supplied
-  // code is stored verbatim and overrides that convention.
+  // can apply its convention (302 GET gate, 307 route handler, 303 form action).
+  // A caller-supplied code is stored verbatim and overrides that convention,
+  // except at a form-bound action, which always answers 303.
   /** @type any */ (err).status = typeof code === 'number' ? code : undefined;
+  /** @type any */ (err).redirectType = type;
   throw err;
 }
 
+/**
+ * Throw a PERMANENT redirect sentinel, Next.js's `permanentRedirect()`: a 308
+ * Permanent Redirect everywhere except a form-bound action, which answers 303. Use it
+ * when a URL has moved for good (a renamed slug); browsers and search engines
+ * remember a 308.
+ *
+ * @param {string} url
+ * @param {RedirectType} [type] how an RPC caller's client records the navigation.
+ * @returns {never}
+ */
+export function permanentRedirect(url, type) {
+  return redirect(url, { status: 308, type });
+}
+
+/** @typedef {'push' | 'replace'} RedirectType */
+
 /** @param {unknown} e */
 export function isNotFound(e) {
   return !!e && /** @type any */ (e).__webjs === NOT_FOUND;

package/src/optimistic.js

@@ -108,8 +108,8 @@ async function runImperativeOptimistic(signal, value, action) {
  * Imperative form (signal-based rollback), for a one-shot toggle:
  *   await optimistic(signal, value, () => likePost(postId));
  *
- * Client-only: it calls `host.requestUpdate()` (client work), so a component
- * importing it is never elided as display-only.
+ * Client-only: it calls `host.requestUpdate()` (client work), so it belongs in
+ * a component, never in a server-only one.
  *
  * @template State
  * @template Action

package/src/refresh-header.js

@@ -0,0 +1,52 @@
+/**
+ * The `x-webjs-refresh` header a server action's response carries when it
+ * called `revalidatePath()`. A leaf module (no imports), so the router's
+ * fetch path and the action stub's effects can both read it without an
+ * import cycle.
+ *
+ * @module refresh-header
+ */
+
+/**
+ * Parse an `x-webjs-refresh` header: comma-separated, percent-encoded paths,
+ * each optionally suffixed `;layout` (Next's `revalidatePath(path, 'layout')`).
+ * @param {string | null | undefined} value
+ * @returns {{ path: string, layout: boolean }[]}
+ */
+export function parseRefreshHeader(value) {
+  if (!value) return [];
+  /** @type {{ path: string, layout: boolean }[]} */
+  const out = [];
+  for (const part of String(value).split(',')) {
+    const raw = part.trim();
+    if (!raw) continue;
+    const layout = raw.endsWith(';layout');
+    let path = layout ? raw.slice(0, -';layout'.length) : raw;
+    try { path = decodeURIComponent(path); } catch { /* keep as sent */ }
+    if (path.startsWith('/')) out.push({ path, layout });
+  }
+  return out;
+}
+
+/**
+ * Whether `pathname` is covered by one refreshed entry. A `[param]` segment
+ * matches any one segment, a `[...param]` segment one or more and a
+ * `[[...param]]` segment zero or more of the rest
+ * (Next lets `revalidatePath` name a route pattern); a `layout` entry also
+ * covers every path below it.
+ * @param {{ path: string, layout: boolean }} entry
+ * @param {string} pathname
+ */
+export function refreshCovers(entry, pathname) {
+  const want = entry.path.split('/').filter(Boolean);
+  const have = pathname.split('/').filter(Boolean);
+  for (let i = 0; i < want.length; i++) {
+    const w = want[i];
+    if (/^\[\[\.\.\./.test(w)) return true;
+    if (/^\[\.\.\./.test(w)) return have.length > i;
+    if (i >= have.length) return false;
+    if (/^\[[^\]]+\]$/.test(w)) continue;
+    if (w !== have[i]) return false;
+  }
+  return entry.layout || have.length === want.length;
+}

package/src/registry.js

@@ -17,6 +17,8 @@
  * @typedef {{ cls: typeof import('./component.js').WebComponent, moduleUrl: string | null, lazy: boolean, tag: string }} RegistryEntry
  */
 
+import { hotReplacer } from './hot.js';
+
 /* ------------------------------------------------------------------
  * Shared registry on globalThis.
  *
@@ -106,7 +108,11 @@ function registerInternal(tag, cls) {
 if (isBrowser) {
   const native = customElements.define.bind(customElements);
   /** @type {any} */ (customElements).define = function (tag, cls, options) {
-    if (!customElements.get(tag)) native(tag, cls, options);
+    const prev = customElements.get(tag);
+    if (!prev) native(tag, cls, options);
+    // A re-define of a known tag under the dev hot client (#1689) patches the
+    // registered class in place, so the registry keeps the class the browser uses.
+    else if (prev !== cls) { const replace = hotReplacer(); if (replace) cls = replace(tag, prev, cls); }
     registerInternal(tag, cls);
   };
 }
@@ -152,6 +158,9 @@ if (!isBrowser) {
  * @param {typeof import('./component.js').WebComponent} cls
  */
 export function register(tag, cls) {
+  // Lit's `finalize()`, so the class's metadata is ready before the first
+  // instance (a class not built on WebComponent has none).
+  if (typeof (/** @type {any} */ (cls)).finalize === 'function') /** @type {any} */ (cls).finalize();
   if (isBrowser) {
     /** @type any */ (customElements).define(tag, cls);
   } else {

package/src/render-client/adopt-slots.js

@@ -0,0 +1,250 @@
+/**
+ * Hydration slot adoption: keep a light-DOM host's SSR-projected children in
+ * the document while its first client render replaces the SSR markup (#1666).
+ *
+ * Hydration renders the template from a fresh clone and swaps it in for the
+ * SSR markup. The projected children sit inside the SSR `<slot>`, so swapping
+ * the SSR tree out took them out of the document, and the first slot apply put
+ * them back a microtask later. A removal is not free: the HTML spec navigates
+ * a re-inserted iframe again (and `loading="lazy"` defers only the FIRST
+ * insertion, so a hidden lazy frame loads), and every nested custom element
+ * disconnects and reconnects.
+ *
+ * So for each of the template's own slots whose SSR counterpart holds exactly
+ * the nodes the host's record adopted, the SSR slot and its ancestor chain up
+ * to the host are KEPT: the parts that target a fresh element on that chain
+ * are pointed at its live twin, and the fresh siblings around the chain are
+ * inserted into the live elements instead of the live tree being replaced. No
+ * kept node moves, so the projected children never leave the document. The
+ * fresh slot's cloned fallback goes to the slot's holding fragment, where the
+ * slot part would have put it.
+ *
+ * Conservative by construction: a slot is adopted only when every link of
+ * both chains matches by tag, no link is a custom element (whose SSR markup is
+ * its own rendered template) or a `<form>` (form-action reconciliation inserts
+ * children into it), the slot's name is static, and the kept nodes sit in the
+ * same relative order on both sides. Anything else, a slot inside a
+ * conditional template among them, falls back to the plain swap.
+ *
+ * @module
+ */
+import {
+  PROJECTION_ACTUAL, PROJECTION_ATTR, SLOT_FALLBACK_FRAG, SLOT_OWNER_ATTR,
+  ensureSlotState, hasSlotState, keyOfName,
+} from '../slot.js';
+
+/**
+ * Live SSR slots a hydration render adopted. The slot part's finalize reads
+ * it to leave the slot's children (the projected nodes) in place instead of
+ * harvesting them as fallback, since the holding fragment is already set.
+ * @type {WeakSet<Element>}
+ */
+export const adoptedSlots = new WeakSet();
+
+/**
+ * @typedef {{ map: Map<Node, Element>, slots: [Element, Element][], chains: [Element, Element][] }} AdoptionPlan
+ */
+
+/**
+ * Plan the adoption for a hydration render, after the parts are bound and
+ * before any is applied. Returns null when no slot qualifies.
+ *
+ * @param {Element | DocumentFragment | ShadowRoot} container
+ * @param {DocumentFragment} frag the fresh clone
+ * @param {any[]} bound the template's bound parts
+ * @returns {AdoptionPlan | null}
+ */
+export function planSlotAdoption(container, frag, bound) {
+  if (/** @type {any} */ (container).nodeType !== 1 || !hasSlotState(/** @type {Element} */ (container))) return null;
+  const state = ensureSlotState(/** @type {Element} */ (container));
+  /** @type {Set<Element>} */
+  const dynamicName = new Set();
+  for (const p of bound) {
+    if ((p.kind === 'attr' || p.kind === 'attr-mixed' || p.kind === 'bool') && p.name === 'name') dynamicName.add(p.el);
+  }
+  /** @type {Map<Node, Element>} fresh element to its live twin */
+  const map = new Map();
+  /** @type {Set<Element>} */
+  const usedLive = new Set();
+  /** @type {[Element, Element][]} */
+  const slots = [];
+  /** @type {[Element, Element][]} */
+  const chains = [];
+  for (const p of bound) {
+    if (p.kind !== 'slot') continue;
+    const slotF = /** @type {Element} */ (p.slotEl);
+    if (dynamicName.has(slotF)) continue;
+    const assigned = state.assignedByName.get(keyOfName(slotF.getAttribute('name')));
+    if (!assigned || assigned.length === 0) continue;
+    const slotL = /** @type {Element | null} */ (assigned[0].parentNode);
+    if (!slotL || slotL.nodeType !== 1 || slotL.localName !== 'slot' || usedLive.has(slotL)) continue;
+    if (slotL.getAttribute(PROJECTION_ATTR) !== PROJECTION_ACTUAL) continue;
+    if (!sameNodes(slotL.childNodes, assigned)) continue;
+    const fChain = ancestorsUpTo(slotF, frag);
+    const lChain = ancestorsUpTo(slotL, container);
+    if (!fChain || !lChain || fChain.length !== lChain.length) continue;
+    let ok = true;
+    for (let i = 0; i < fChain.length && ok; i++) {
+      const f = fChain[i];
+      const l = lChain[i];
+      const name = f.localName;
+      if (name !== l.localName || name.includes('-') || name === 'form') ok = false;
+      else {
+        const prior = map.get(f);
+        if (prior ? prior !== l : usedLive.has(l)) ok = false;
+      }
+    }
+    if (!ok) continue;
+    map.set(slotF, slotL);
+    usedLive.add(slotL);
+    slots.push([slotF, slotL]);
+    for (let i = 0; i < fChain.length; i++) {
+      if (map.has(fChain[i])) continue;
+      map.set(fChain[i], lChain[i]);
+      usedLive.add(lChain[i]);
+      chains.push([fChain[i], lChain[i]]);
+    }
+  }
+  if (slots.length === 0) return null;
+  // No kept node may have to move: under each kept parent the kept children
+  // must already sit in the order the template puts them in.
+  for (const fParent of [frag, ...chains.map(([f]) => f)]) {
+    let last = null;
+    for (const child of fParent.childNodes) {
+      const live = map.get(child);
+      if (!live) continue;
+      if (last && !(last.compareDocumentPosition(live) & Node.DOCUMENT_POSITION_FOLLOWING)) return null;
+      last = live;
+    }
+  }
+  return { map, slots, chains };
+}
+
+/**
+ * Point every bound part that targets a kept fresh element at its live twin,
+ * and give each kept element the fresh one's static attributes. Runs before
+ * the parts apply, so every dynamic value lands on the live element directly.
+ *
+ * @param {AdoptionPlan} plan
+ * @param {any[]} bound
+ */
+export function retargetParts(plan, bound) {
+  /** @type {Map<Element, Set<string>>} attributes a part owns, per live element */
+  const owned = new Map();
+  for (const p of bound) {
+    if (p.kind === 'slot') {
+      const live = plan.map.get(p.slotEl);
+      if (live) p.slotEl = live;
+      continue;
+    }
+    if (!p.el) continue;
+    const live = plan.map.get(p.el);
+    if (!live) continue;
+    // An event part registers its dispatcher in applyPart, with the handler as
+    // the options bag (capture / once / passive). This runs before the first
+    // apply, so usually nothing is registered yet; move a registration only
+    // when one exists, with the SAME options, or a capture listener would be
+    // registered twice and a `once` listener would lose its `once`.
+    if (p.kind === 'event' && p.handler) {
+      p.el.removeEventListener(p.name, p.dispatcher, p.handler);
+      live.addEventListener(p.name, p.dispatcher, p.handler);
+    }
+    p.el = live;
+    if (p.kind === 'attr' || p.kind === 'attr-mixed' || p.kind === 'bool') {
+      let names = owned.get(live);
+      if (!names) owned.set(live, names = new Set());
+      names.add(p.name);
+    }
+  }
+  for (const [fresh, live] of [...plan.chains, ...plan.slots]) {
+    const isSlot = live.localName === 'slot';
+    const names = owned.get(live);
+    for (const a of Array.from(live.attributes)) {
+      if (fresh.hasAttribute(a.name) || names?.has(a.name)) continue;
+      // The SSR projection stamps stay: the slot IS projected, and the owner
+      // carrier is what isOwnSlot reads until the owner symbol is stamped.
+      if (isSlot && (a.name === PROJECTION_ATTR || a.name === SLOT_OWNER_ATTR)) continue;
+      live.removeAttribute(a.name);
+    }
+    for (const a of Array.from(fresh.attributes)) {
+      if (live.getAttribute(a.name) !== a.value) live.setAttribute(a.name, a.value);
+    }
+  }
+}
+
+/**
+ * Commit the fresh template into the container around the kept live nodes:
+ * every live child that is not kept is removed, every fresh node is inserted
+ * in template order, and no kept node moves. The fresh slots' cloned fallback
+ * goes to each kept slot's holding fragment.
+ *
+ * @param {AdoptionPlan} plan
+ * @param {Element} container
+ * @param {Node[]} top the container's new children, bookends included
+ */
+export function commitAdoption(plan, container, top) {
+  const mapped = (/** @type {Node} */ n) => plan.map.get(n) || n;
+  const state = ensureSlotState(container);
+  for (const [fresh, live] of plan.chains) mergeChildren(live, Array.from(fresh.childNodes, mapped));
+  mergeChildren(container, top.map(mapped));
+  for (const [fresh, live] of plan.slots) {
+    const fallback = document.createDocumentFragment();
+    while (fresh.firstChild) fallback.appendChild(fresh.firstChild);
+    /** @type {any} */ (live)[SLOT_FALLBACK_FRAG] = fallback;
+    adoptedSlots.add(live);
+    // Forget the adopted snapshot so the first apply reports the initial
+    // projection (one slotchange), exactly as the plain swap did.
+    state.lastSnapshot.delete(live);
+  }
+}
+
+/**
+ * Make `parent`'s children exactly `want`, removing what is not wanted and
+ * inserting the rest, without moving a node already in place in order.
+ *
+ * @param {Node} parent
+ * @param {Node[]} want
+ */
+function mergeChildren(parent, want) {
+  const keep = new Set(want);
+  for (const c of Array.from(parent.childNodes)) {
+    if (!keep.has(c)) parent.removeChild(c);
+  }
+  let cursor = parent.firstChild;
+  for (const node of want) {
+    if (node === cursor) {
+      cursor = cursor.nextSibling;
+      continue;
+    }
+    parent.insertBefore(node, cursor);
+  }
+}
+
+/**
+ * The element ancestors of `node` below `root`, nearest first, or null when
+ * `root` is not an ancestor.
+ *
+ * @param {Node} node
+ * @param {Node} root
+ * @returns {Element[] | null}
+ */
+function ancestorsUpTo(node, root) {
+  const out = [];
+  let p = node.parentNode;
+  while (p && p !== root) {
+    if (p.nodeType !== 1) return null;
+    out.push(/** @type {Element} */ (p));
+    p = p.parentNode;
+  }
+  return p === root ? out : null;
+}
+
+/**
+ * @param {NodeListOf<ChildNode>} list
+ * @param {Node[]} nodes
+ */
+function sameNodes(list, nodes) {
+  if (list.length !== nodes.length) return false;
+  for (let i = 0; i < nodes.length; i++) if (list[i] !== nodes[i]) return false;
+  return true;
+}