@webjsdev/core 0.8.0 → 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

@@ -140,9 +140,14 @@ export function retargetParts(plan, bound) {
     if (!p.el) continue;
     const live = plan.map.get(p.el);
     if (!live) continue;
-    if (p.kind === 'event') {
-      p.el.removeEventListener(p.name, p.dispatcher);
-      live.addEventListener(p.name, p.dispatcher);
+    // 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') {