@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/src/handles/breadcrumbs.ts

@@ -0,0 +1,93 @@
+/**
+ * Built-in Breadcrumbs handle for accumulating breadcrumb items across route segments.
+ *
+ * Each layout/route pushes breadcrumb items via `ctx.use(Breadcrumbs)`.
+ * Items are collected in parent-to-child order with automatic deduplication
+ * by `href`: each href keeps its FIRST position but takes the LAST value, so a
+ * child re-pushing a parent href refreshes the label without reordering the trail.
+ *
+ * @example
+ * ```tsx
+ * // In route handler
+ * route("/blog/:slug", (ctx) => {
+ *   const breadcrumb = ctx.use(Breadcrumbs);
+ *   breadcrumb({ label: "Blog", href: "/blog" });
+ *   breadcrumb({ label: post.title, href: `/blog/${ctx.params.slug}` });
+ * });
+ *
+ * // In client component (consume with useHandle)
+ * const crumbs = useHandle(Breadcrumbs);
+ * crumbs.map((c) => <a href={c.href}>{c.label}</a>);
+ * ```
+ */
+
+import type { ReactNode } from "react";
+import { createHandle, type Handle } from "../handle.js";
+
+/**
+ * A single breadcrumb item.
+ *
+ * @property label - Display text for the breadcrumb
+ * @property href - URL the breadcrumb links to
+ * @property content - Optional extra content (sync or async) rendered alongside the label
+ */
+export interface BreadcrumbItem {
+  label: string;
+  href: string;
+  content?: ReactNode | Promise<ReactNode>;
+}
+
+/**
+ * Collect function for Breadcrumbs handle.
+ * Flattens segments in parent-to-child order with deduplication by href: each
+ * href keeps its FIRST position but takes the LAST value (re-pushing a parent
+ * href refreshes the label in place without reordering the trail). Deferred
+ * crumbs (a pushed Promise or `ctx.use(Breadcrumbs).defer()`) are resolved
+ * BEFORE collect runs (resolve-by-default), so collect only ever sees resolved
+ * items. An item without a string `href` is passed through by identity and
+ * excluded from the href dedup.
+ */
+function collectBreadcrumbs(segments: BreadcrumbItem[][]): BreadcrumbItem[] {
+  const all = segments.flat();
+
+  const hasHref = (item: unknown): item is BreadcrumbItem =>
+    item != null &&
+    typeof item === "object" &&
+    typeof (item as { href?: unknown }).href === "string";
+
+  // Dedup crumbs by href: keep the FIRST position (preserving parent->child
+  // order) but the LAST value (a child re-pushing a parent's href can refresh
+  // its label). Items without an href pass through by identity at their original
+  // position.
+  const valueByHref = new Map<string, BreadcrumbItem>();
+  for (const item of all) {
+    if (hasHref(item)) valueByHref.set(item.href, item);
+  }
+
+  const result: BreadcrumbItem[] = [];
+  const emitted = new Set<string>();
+  for (const item of all) {
+    if (!hasHref(item)) {
+      result.push(item);
+      continue;
+    }
+    // Emit each href once, at its first occurrence, with the final value.
+    if (!emitted.has(item.href)) {
+      emitted.add(item.href);
+      result.push(valueByHref.get(item.href)!);
+    }
+  }
+  return result;
+}
+
+/**
+ * Built-in handle for accumulating breadcrumb navigation items.
+ *
+ * Use `ctx.use(Breadcrumbs)` in route handlers to push breadcrumb items.
+ * Use `useHandle(Breadcrumbs)` in client components to consume them.
+ */
+export const Breadcrumbs: Handle<BreadcrumbItem, BreadcrumbItem[]> =
+  createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+    collectBreadcrumbs,
+    "__rsc_router_breadcrumbs__",
+  );

package/src/handles/deferred-resolution.ts

@@ -0,0 +1,127 @@
+import type { HandleData, HandleStore } from "../server/handle-store.js";
+import { isThenable } from "./is-thenable.js";
+
+/**
+ * Runtime-neutral resolution of deferred (Promise) handle values. Shared by the
+ * server full-render path (resolve before the payload is finalized so SSR sees
+ * resolved values) and the client soft-nav path (NavigationProvider resolves
+ * each yield before applying it). Pure — imports only `isThenable` — so it is
+ * safe in both the RSC server environment AND the browser.
+ *
+ * Resolution is SHALLOW: only an entry that is ITSELF a thenable is awaited. A
+ * value that merely contains a promise (e.g. `{ data: somePromise }`) is a
+ * non-thenable, so the `isThenable` check skips it and it passes through verbatim
+ * — the nested promise is the consumer's responsibility. Resolution runs each
+ * entry through `Promise.all` with a per-entry `try/catch` (NOT `allSettled`), so
+ * one rejecting entry is dropped without rejecting the batch or aborting siblings.
+ */
+
+/**
+ * Handle names ($$id) whose snapshot carries a deferred (top-level Promise)
+ * value. Used by the client to decide which buckets to hold-and-resolve, and
+ * `.size > 0` answers "does this snapshot have any deferred value".
+ */
+export function deferredHandleNames(data: HandleData): Set<string> {
+  const names = new Set<string>();
+  for (const [handleName, segments] of Object.entries(data)) {
+    for (const values of Object.values(segments)) {
+      if (values.some(isThenable)) {
+        names.add(handleName);
+        break;
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Snapshot with deferred (Promise) values awaited (shallow — only top-level
+ * thenables). A rejected deferred is dropped, and a deferred that resolves to
+ * `null`/`undefined` is dropped (the `.defer({ else })` skip semantics), so a
+ * nullish deferred slot never reaches a collector. Sync (non-thenable) values —
+ * including a legitimate sync `null` push — pass through unchanged.
+ */
+export async function resolveDeferredHandleValues(
+  data: HandleData,
+): Promise<HandleData> {
+  const out: HandleData = {};
+  await Promise.all(
+    Object.entries(data).flatMap(([handleName, segments]) => {
+      out[handleName] = {};
+      return Object.entries(segments).map(async ([segmentId, values]) => {
+        out[handleName][segmentId] = await resolveValues(values);
+      });
+    }),
+  );
+  return out;
+}
+
+// Resolve each entry IN ORDER. A non-thenable passes through verbatim (including
+// a legitimate sync `null`/`undefined` push — the "await iff thenable" contract).
+// A thenable is awaited and dropped when it rejects OR resolves to null/undefined
+// (the `.defer({ else })` skip semantics: a forgotten resolver times out to
+// `else ?? undefined`), so a nullish deferred slot never reaches a collector.
+async function resolveValues(values: unknown[]): Promise<unknown[]> {
+  const resolved = await Promise.all(
+    values.map(async (v) => {
+      if (!isThenable(v)) return { keep: true, value: v };
+      try {
+        const value = await v;
+        return { keep: value != null, value };
+      } catch {
+        return { keep: false, value: undefined };
+      }
+    }),
+  );
+  return resolved.filter((r) => r.keep).map((r) => r.value);
+}
+
+/**
+ * Full-render handle stream: a one-shot async generator that yields the FINAL
+ * handle snapshot with every top-level deferred value resolved. Drop-in for
+ * `handleStore.stream()` on full / HTML renders (initial load, 404, progressive
+ * enhancement), where the consumer drains the generator to completion before
+ * rendering anyway — so the single final yield is equivalent to the streamed
+ * yields' converged state, and the SSR markup plus the first sync `useHandle`
+ * read see resolved values. `getData()` seals the store and awaits the handler
+ * barrier; `resolveDeferredHandleValues` then awaits the pushed-value promises.
+ * A hung handle promise blocks the full render like any unresolved await (no
+ * handle-specific timeout). Partial / action payloads keep streaming via
+ * `handleStore.stream()`.
+ */
+export async function* resolvedHandleStream(
+  handleStore: HandleStore,
+): AsyncGenerator<HandleData, void, unknown> {
+  // Drain stream() (NOT getData()) for the converged snapshot: stream() sets the
+  // store's `completed` flag on seal+settle, and that flag is what makes a LATE
+  // push throw LateHandlePushError — an async JSX subtree that suspended and later
+  // calls ctx.use(Handle)(...) after collection. getData() never sets `completed`,
+  // so the late push would silently land. Both wait for the same settle barrier, so
+  // the final yielded value is identical; we just keep the late-push guard.
+  let snapshot: HandleData = {};
+  for await (const data of handleStore.stream()) {
+    snapshot = data;
+  }
+  yield await resolveDeferredHandleValues(snapshot);
+}
+
+/**
+ * Resolve the deferred (Promise) values in ONE segment's handle bucket
+ * (`handleName -> entries[]`). Same shallow + drop-rejections rule as
+ * {@link resolveDeferredHandleValues}, but for the segment-keyed shape the
+ * prerender/static collection paths use (`getDataForSegment`). Prerender is a
+ * build-time cache, so the baked artifact must hold resolved values — a hit
+ * replays them into the segment system, where collect/useHandle expect resolved
+ * data.
+ */
+export async function resolveSegmentHandleValues(
+  segHandles: Record<string, unknown[]>,
+): Promise<Record<string, unknown[]>> {
+  const out: Record<string, unknown[]> = {};
+  await Promise.all(
+    Object.entries(segHandles).map(async ([handleName, values]) => {
+      out[handleName] = await resolveValues(values);
+    }),
+  );
+  return out;
+}

package/src/handles/is-thenable.ts

@@ -0,0 +1,18 @@
+/**
+ * Single thenable predicate for the resolve-by-default handle machinery
+ * (`handles/deferred-resolution.ts`, its sole owner) — it decides which top-level
+ * handle entries are deferred (`Promise`) values to await before any consumer
+ * sees them, and which pass through verbatim.
+ *
+ * Requires a CALLABLE `then` (`typeof obj.then === "function"`), not merely a
+ * `"then" in obj` membership check, so a non-promise carrying a `then` field
+ * (e.g. a serialized shape `{ then: 5 }`) is treated as a plain sync value rather
+ * than awaited. A single predicate keeps that classification consistent.
+ */
+export function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}

package/src/handles/meta.ts

@@ -31,15 +31,13 @@
 import { createHandle, type Handle } from "../handle.js";
 import type {
   MetaDescriptor,
+  MetaDescriptorBase,
   TitleDescriptor,
   UnsetDescriptor,
 } from "../router/types.js";
 
-/**
- * Type guard for unset descriptor
- */
 function isUnsetDescriptor(
-  descriptor: MetaDescriptor
+  descriptor: MetaDescriptor,
 ): descriptor is UnsetDescriptor {
   return (
     typeof descriptor === "object" &&
@@ -49,11 +47,8 @@ function isUnsetDescriptor(
   );
 }
 
-/**
- * Type guard for title descriptor (any form)
- */
 function isTitleDescriptor(
-  descriptor: MetaDescriptor
+  descriptor: MetaDescriptor,
 ): descriptor is { title: TitleDescriptor } {
   return (
     typeof descriptor === "object" &&
@@ -62,11 +57,8 @@ function isTitleDescriptor(
   );
 }
 
-/**
- * Type guard for title template descriptor
- */
 function isTitleTemplate(
-  title: TitleDescriptor
+  title: TitleDescriptor,
 ): title is { template: string; default: string } {
   return (
     typeof title === "object" &&
@@ -76,19 +68,13 @@ function isTitleTemplate(
   );
 }
 
-/**
- * Type guard for absolute title descriptor
- */
-function isAbsoluteTitle(title: TitleDescriptor): title is { absolute: string } {
+function isAbsoluteTitle(
+  title: TitleDescriptor,
+): title is { absolute: string } {
   return typeof title === "object" && title !== null && "absolute" in title;
 }
 
-/**
- * Get a unique key for a meta descriptor for deduplication.
- * Returns undefined for descriptors that shouldn't be deduplicated.
- */
 function getMetaKey(descriptor: MetaDescriptor): string | undefined {
-  // Skip unset descriptors - they are processed separately
   if (isUnsetDescriptor(descriptor)) {
     return undefined;
   }
@@ -108,13 +94,10 @@ function getMetaKey(descriptor: MetaDescriptor): string | undefined {
     return `httpEquiv:${descriptor.httpEquiv}`;
   }
   if ("script:ld+json" in descriptor) {
-    // JSON-LD scripts can have multiple, don't dedupe by default
     return undefined;
   }
   if ("tagName" in descriptor) {
-    // For link tags, dedupe by rel if present
     if (descriptor.tagName === "link" && "rel" in descriptor) {
-      // Some link rels should be unique (canonical), others not (stylesheet)
       const uniqueRels = ["canonical", "icon", "apple-touch-icon"];
       if (uniqueRels.includes(descriptor.rel as string)) {
         return `link:${descriptor.rel}`;
@@ -134,14 +117,11 @@ const defaultMetaDescriptors: MetaDescriptor[] = [
   { name: "viewport", content: "width=device-width, initial-scale=1" },
 ];
 
-/**
- * Helper to add or replace a descriptor in the result array
- */
 function addOrReplace(
   result: MetaDescriptor[],
   keyToIndex: Map<string, number>,
   descriptor: MetaDescriptor,
-  key: string | undefined
+  key: string | undefined,
 ): void {
   if (key !== undefined && keyToIndex.has(key)) {
     result[keyToIndex.get(key)!] = descriptor;
@@ -153,12 +133,9 @@ function addOrReplace(
   }
 }
 
-/**
- * Helper to update indices after removing an element
- */
 function updateIndicesAfterRemoval(
   keyToIndex: Map<string, number>,
-  removedIndex: number
+  removedIndex: number,
 ): void {
   for (const [key, index] of keyToIndex) {
     if (index > removedIndex) {
@@ -167,17 +144,11 @@ function updateIndicesAfterRemoval(
   }
 }
 
-/**
- * Collect function for Meta handle.
- * Includes default meta descriptors, then deduplicates by key with later routes overriding earlier ones.
- * Supports title templates, absolute titles, and unset descriptors.
- */
 function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
   const result: MetaDescriptor[] = [];
   const keyToIndex = new Map<string, number>();
   let titleTemplate: string | undefined;
 
-  // Add defaults first so they can be overridden
   for (const descriptor of defaultMetaDescriptors) {
     const key = getMetaKey(descriptor);
     if (key !== undefined) {
@@ -188,7 +159,9 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
 
   for (const descriptors of segments) {
     for (const descriptor of descriptors) {
-      // Handle unset descriptors
+      // Deferred (Promise) descriptors are resolved BEFORE collectMeta runs
+      // (resolve-by-default), so every descriptor here is synchronous and
+      // participates in key-based dedup + title-templating like any other.
       if (isUnsetDescriptor(descriptor)) {
         const keyToRemove = descriptor.unset;
         if (keyToIndex.has(keyToRemove)) {
@@ -200,33 +173,46 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         continue;
       }
 
-      // Handle title descriptors with template/absolute support
       if (isTitleDescriptor(descriptor)) {
         const titleValue = descriptor.title;
 
         if (isTitleTemplate(titleValue)) {
-          // Store template for subsequent title descriptors in child segments
           titleTemplate = titleValue.template;
-          // Set the default title
-          addOrReplace(result, keyToIndex, { title: titleValue.default }, "title");
+          addOrReplace(
+            result,
+            keyToIndex,
+            { title: titleValue.default },
+            "title",
+          );
           continue;
         }
 
         if (isAbsoluteTitle(titleValue)) {
-          // Absolute title bypasses any template
-          addOrReplace(result, keyToIndex, { title: titleValue.absolute }, "title");
+          addOrReplace(
+            result,
+            keyToIndex,
+            { title: titleValue.absolute },
+            "title",
+          );
           continue;
         }
 
-        // String title - apply template if one exists
+        // Insert the title literally. String.prototype.replace treats the
+        // replacement string specially ($&, $`, $', $$, $n), so a title like
+        // "Save $5" or one containing "$&" would be mangled. split/join inserts
+        // the raw value with no special-character interpretation.
         const finalTitle = titleTemplate
-          ? titleTemplate.replace("%s", titleValue as string)
+          ? titleTemplate.split("%s").join(titleValue as string)
           : titleValue;
-        addOrReplace(result, keyToIndex, { title: finalTitle as string }, "title");
+        addOrReplace(
+          result,
+          keyToIndex,
+          { title: finalTitle as string },
+          "title",
+        );
         continue;
       }
 
-      // Handle all other descriptors
       const key = getMetaKey(descriptor);
       addOrReplace(result, keyToIndex, descriptor, key);
     }
@@ -240,8 +226,13 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
  *
  * Use `ctx.use(Meta)` in route handlers to push meta descriptors.
  * Use `<MetaTags />` component to render them in the document head.
+ *
+ * Deferred (Promise) descriptors are resolved before collectMeta runs
+ * (resolve-by-default), so they participate in deduplication and `%s`
+ * title-templating identically to synchronous descriptors. A descriptor that
+ * resolves to `null`/`undefined` (or rejects) is dropped.
  */
-export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<MetaDescriptor, MetaDescriptor[]>(
-  collectMeta,
-  "__rsc_router_meta__"
-);
+export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<
+  MetaDescriptor,
+  MetaDescriptor[]
+>(collectMeta, "__rsc_router_meta__");