@rangojs/router 0.0.0-experimental.10

package/src/handle.ts

@@ -0,0 +1,130 @@
+/**
+ * Handle definition for accumulating data across route segments.
+ *
+ * Handles allow server-side route handlers to pass accumulated data to client
+ * components. Unlike loaders (which fetch data for specific routes), handles
+ * accumulate data across all matched route segments.
+ *
+ * @example
+ * ```ts
+ * // Define a handle (name auto-generated from file + export)
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ *
+ * // Use in handler
+ * const push = ctx.use(Breadcrumbs);
+ * push({ label: "Home", href: "/" });
+ *
+ * // Consume on client
+ * const crumbs = useHandle(Breadcrumbs);
+ * ```
+ */
+export interface Handle<TData, TAccumulated = TData[]> {
+  /**
+   * Brand to distinguish handles from loaders in ctx.use()
+   */
+  readonly __brand: "handle";
+
+  /**
+   * Auto-generated unique ID for this handle (used as key in storage)
+   * Format: "filePath#ExportName" in dev, "hash#ExportName" in production
+   */
+  readonly $$id: string;
+
+}
+
+/**
+ * Default collect function that flattens segment arrays into a single array.
+ */
+function defaultCollect<T>(segments: T[][]): T[] {
+  return segments.flat();
+}
+
+// Module-level registry mapping $$id to collect functions.
+// Populated when createHandle() runs (both server and client).
+// Used by useHandle() to recover collect when handle is deserialized from RSC prop.
+const collectRegistry = new Map<string, (segments: unknown[][]) => unknown>();
+
+/**
+ * Look up a collect function from the registry by handle $$id.
+ * Returns undefined if not registered (falls back to defaultCollect in useHandle).
+ */
+export function getCollectFn(id: string): ((segments: unknown[][]) => unknown) | undefined {
+  return collectRegistry.get(id);
+}
+
+/**
+ * Create a handle definition for accumulating data across route segments.
+ *
+ * The $$id is auto-generated by the Vite exposeHandleId plugin based on
+ * file path and export name. No manual naming required.
+ *
+ * @param collect - Optional collect function (default: flatten into array)
+ * @param __injectedId - Auto-injected by Vite plugin, do not provide manually
+ *
+ * @example
+ * ```ts
+ * // Default: flatten into array
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>();
+ * // Result type: BreadcrumbItem[]
+ *
+ * // Custom: last value wins
+ * export const PageTitle = createHandle<string, string>(
+ *   (segments) => segments.flat().at(-1) ?? "Default Title"
+ * );
+ * // Result type: string
+ *
+ * // Custom: object merge
+ * export const Meta = createHandle<Partial<MetaTags>, MetaTags>(
+ *   (segments) => Object.assign({ robots: "index,follow" }, ...segments.flat())
+ * );
+ * // Result type: MetaTags
+ *
+ * // Custom: dedupe by href
+ * export const Breadcrumbs = createHandle<BreadcrumbItem>(
+ *   (segments) => {
+ *     const all = segments.flat();
+ *     return all.filter((item, i) => all.findIndex(x => x.href === item.href) === i);
+ *   }
+ * );
+ * ```
+ */
+export function createHandle<TData, TAccumulated = TData[]>(
+  collect?: (segments: TData[][]) => TAccumulated,
+  __injectedId?: string
+): Handle<TData, TAccumulated> {
+  const handleId = __injectedId ?? "";
+
+  if (!handleId && process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[rsc-router] Handle is missing $$id. " +
+        "Make sure the exposeHandleId Vite plugin is enabled and " +
+        "the handle is exported with: export const MyHandle = createHandle(...)"
+    );
+  }
+
+  const collectFn = collect ??
+    (defaultCollect as unknown as (segments: TData[][]) => TAccumulated);
+
+  // Register collect in module-level registry so useHandle() can recover it
+  // when the handle is deserialized from RSC props (toJSON strips collect).
+  if (handleId) {
+    collectRegistry.set(handleId, collectFn as (segments: unknown[][]) => unknown);
+  }
+
+  return {
+    __brand: "handle" as const,
+    $$id: handleId,
+  };
+}
+
+/**
+ * Type guard to check if a value is a Handle.
+ */
+export function isHandle(value: unknown): value is Handle<unknown, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "handle"
+  );
+}

package/src/handles/MetaTags.tsx

@@ -0,0 +1,193 @@
+"use client";
+
+/**
+ * Component to render collected meta descriptors in the document head.
+ *
+ * Supports both sync and async meta descriptors. Async descriptors
+ * (Promise<MetaDescriptorBase>) are resolved using React's use() hook.
+ *
+ * When theme is enabled in the router config, MetaTags also renders
+ * the theme initialization script to prevent FOUC (flash of unstyled content).
+ *
+ * @example
+ * ```tsx
+ * function RootLayout() {
+ *   return (
+ *     <html lang="en" suppressHydrationWarning>
+ *       <head>
+ *         <MetaTags />
+ *       </head>
+ *       <body>...</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+
+import { use } from "react";
+import { useHandle } from "../browser/react/use-handle.js";
+import { Meta } from "./meta.js";
+import type { MetaDescriptor, MetaDescriptorBase } from "../router/types.js";
+import { getSSRThemeConfig } from "../theme/theme-context.js";
+import { generateThemeScript } from "../theme/theme-script.js";
+
+// Type guards for MetaDescriptorBase variants
+function hasCharSet(d: MetaDescriptorBase): d is { charSet: "utf-8" } {
+  return "charSet" in d && d.charSet === "utf-8";
+}
+
+function hasTitle(d: MetaDescriptorBase): d is { title: string } {
+  return "title" in d && typeof (d as { title?: unknown }).title === "string";
+}
+
+function hasNameContent(d: MetaDescriptorBase): d is { name: string; content: string } {
+  return "name" in d && "content" in d &&
+    typeof (d as { name?: unknown }).name === "string" &&
+    typeof (d as { content?: unknown }).content === "string";
+}
+
+function hasPropertyContent(d: MetaDescriptorBase): d is { property: string; content: string } {
+  return "property" in d && "content" in d &&
+    typeof (d as { property?: unknown }).property === "string" &&
+    typeof (d as { content?: unknown }).content === "string";
+}
+
+function hasHttpEquivContent(d: MetaDescriptorBase): d is { httpEquiv: string; content: string } {
+  return "httpEquiv" in d && "content" in d &&
+    typeof (d as { httpEquiv?: unknown }).httpEquiv === "string" &&
+    typeof (d as { content?: unknown }).content === "string";
+}
+
+function hasScriptLdJson(d: MetaDescriptorBase): d is { "script:ld+json": object } {
+  return "script:ld+json" in d;
+}
+
+function hasTagName(d: MetaDescriptorBase): d is { tagName: "meta" | "link"; [name: string]: string } {
+  return "tagName" in d && ((d as { tagName?: unknown }).tagName === "meta" || (d as { tagName?: unknown }).tagName === "link");
+}
+
+/**
+ * Check if a value is a Promise.
+ */
+function isPromise(value: unknown): value is Promise<unknown> {
+  return value !== null && typeof value === "object" && "then" in value;
+}
+
+/**
+ * Render a single meta descriptor as a React element.
+ */
+function renderMetaDescriptor(
+  descriptor: MetaDescriptorBase,
+  index: number
+): React.ReactNode {
+  // charset
+  if (hasCharSet(descriptor)) {
+    return <meta key="charSet" charSet={descriptor.charSet} />;
+  }
+
+  // title
+  if (hasTitle(descriptor)) {
+    return <title key="title">{descriptor.title}</title>;
+  }
+
+  // name + content (description, viewport, etc.)
+  if (hasNameContent(descriptor)) {
+    return (
+      <meta
+        key={`name-${descriptor.name}`}
+        name={descriptor.name}
+        content={descriptor.content}
+      />
+    );
+  }
+
+  // property + content (Open Graph, etc.)
+  if (hasPropertyContent(descriptor)) {
+    return (
+      <meta
+        key={`property-${descriptor.property}`}
+        property={descriptor.property}
+        content={descriptor.content}
+      />
+    );
+  }
+
+  // http-equiv + content
+  if (hasHttpEquivContent(descriptor)) {
+    return (
+      <meta
+        key={`httpEquiv-${descriptor.httpEquiv}`}
+        httpEquiv={descriptor.httpEquiv}
+        content={descriptor.content}
+      />
+    );
+  }
+
+  // JSON-LD structured data
+  if (hasScriptLdJson(descriptor)) {
+    const json = JSON.stringify(descriptor["script:ld+json"]);
+    return (
+      <script
+        key={`ld-json-${index}`}
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: json }}
+      />
+    );
+  }
+
+  // Custom tagName (meta or link with arbitrary attributes)
+  if (hasTagName(descriptor)) {
+    const { tagName, ...rest } = descriptor;
+    if (tagName === "link") {
+      return <link key={`link-${index}`} {...(rest as React.LinkHTMLAttributes<HTMLLinkElement>)} />;
+    }
+    if (tagName === "meta") {
+      return <meta key={`meta-${index}`} {...(rest as React.MetaHTMLAttributes<HTMLMetaElement>)} />;
+    }
+  }
+
+  // Fallback: treat as meta attributes
+  return <meta key={`meta-fallback-${index}`} {...(descriptor as React.MetaHTMLAttributes<HTMLMetaElement>)} />;
+}
+
+/**
+ * Wrapper component to resolve a Promise<MetaDescriptorBase> using use().
+ */
+function AsyncMetaTag({ promise, index }: { promise: Promise<MetaDescriptorBase>; index: number }): React.ReactNode {
+  const resolved = use(promise);
+  return renderMetaDescriptor(resolved, index);
+}
+
+/**
+ * Renders all collected meta descriptors from route handlers.
+ *
+ * Place this component inside the `<head>` element of your document.
+ * It will automatically update when meta descriptors change during navigation.
+ *
+ * When theme is enabled in router config, also renders the theme initialization
+ * script to prevent FOUC (flash of unstyled content).
+ *
+ * Async meta descriptors (Promise<MetaDescriptorBase>) are resolved using
+ * React's use() hook. RSC streaming handles the Promise resolution.
+ */
+export function MetaTags(): React.ReactNode {
+  const descriptors = useHandle(Meta) as MetaDescriptor[];
+  const themeConfig = getSSRThemeConfig();
+
+  return (
+    <>
+      {/* Theme script must be first to prevent FOUC */}
+      {themeConfig && (
+        <script
+          dangerouslySetInnerHTML={{ __html: generateThemeScript(themeConfig) }}
+        />
+      )}
+      {descriptors.map((descriptor, index) => {
+        if (isPromise(descriptor)) {
+          return <AsyncMetaTag key={`async-${index}`} promise={descriptor} index={index} />;
+        }
+        return renderMetaDescriptor(descriptor, index);
+      })}
+    </>
+  );
+}

package/src/handles/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Built-in handles for rsc-router.
+ */
+
+export { Meta } from "./meta.ts";
+export { MetaTags } from "./MetaTags.tsx";

package/src/handles/meta.ts

@@ -0,0 +1,247 @@
+/**
+ * Built-in Meta handle for managing document metadata across route segments.
+ *
+ * Provides automatic deduplication: later routes override earlier ones
+ * for the same meta key (title, name, property, etc.)
+ *
+ * @example
+ * ```tsx
+ * // In route handler
+ * route("product/:id", (ctx) => {
+ *   const meta = ctx.use(Meta);
+ *   meta({ title: "Product Details" });
+ *   meta({ name: "description", content: "..." });
+ *   meta({ property: "og:title", content: "..." });
+ * });
+ *
+ * // In layout (renders the collected meta tags)
+ * function RootLayout() {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <MetaTags />
+ *       </head>
+ *       ...
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+
+import { createHandle, type Handle } from "../handle.js";
+import type {
+  MetaDescriptor,
+  TitleDescriptor,
+  UnsetDescriptor,
+} from "../router/types.js";
+
+/**
+ * Type guard for unset descriptor
+ */
+function isUnsetDescriptor(
+  descriptor: MetaDescriptor
+): descriptor is UnsetDescriptor {
+  return (
+    typeof descriptor === "object" &&
+    descriptor !== null &&
+    "unset" in descriptor &&
+    typeof (descriptor as UnsetDescriptor).unset === "string"
+  );
+}
+
+/**
+ * Type guard for title descriptor (any form)
+ */
+function isTitleDescriptor(
+  descriptor: MetaDescriptor
+): descriptor is { title: TitleDescriptor } {
+  return (
+    typeof descriptor === "object" &&
+    descriptor !== null &&
+    "title" in descriptor
+  );
+}
+
+/**
+ * Type guard for title template descriptor
+ */
+function isTitleTemplate(
+  title: TitleDescriptor
+): title is { template: string; default: string } {
+  return (
+    typeof title === "object" &&
+    title !== null &&
+    "template" in title &&
+    "default" in title
+  );
+}
+
+/**
+ * Type guard for absolute title descriptor
+ */
+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;
+  }
+  if ("charSet" in descriptor) {
+    return "charSet";
+  }
+  if ("title" in descriptor) {
+    return "title";
+  }
+  if ("name" in descriptor && "content" in descriptor) {
+    return `name:${descriptor.name}`;
+  }
+  if ("property" in descriptor && "content" in descriptor) {
+    return `property:${descriptor.property}`;
+  }
+  if ("httpEquiv" in descriptor && "content" in descriptor) {
+    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}`;
+      }
+    }
+    return undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Default meta descriptors included automatically.
+ * These can be overridden by route handlers.
+ */
+const defaultMetaDescriptors: MetaDescriptor[] = [
+  { charSet: "utf-8" },
+  { 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
+): void {
+  if (key !== undefined && keyToIndex.has(key)) {
+    result[keyToIndex.get(key)!] = descriptor;
+  } else {
+    if (key !== undefined) {
+      keyToIndex.set(key, result.length);
+    }
+    result.push(descriptor);
+  }
+}
+
+/**
+ * Helper to update indices after removing an element
+ */
+function updateIndicesAfterRemoval(
+  keyToIndex: Map<string, number>,
+  removedIndex: number
+): void {
+  for (const [key, index] of keyToIndex) {
+    if (index > removedIndex) {
+      keyToIndex.set(key, index - 1);
+    }
+  }
+}
+
+/**
+ * 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) {
+      keyToIndex.set(key, result.length);
+    }
+    result.push(descriptor);
+  }
+
+  for (const descriptors of segments) {
+    for (const descriptor of descriptors) {
+      // Handle unset descriptors
+      if (isUnsetDescriptor(descriptor)) {
+        const keyToRemove = descriptor.unset;
+        if (keyToIndex.has(keyToRemove)) {
+          const idx = keyToIndex.get(keyToRemove)!;
+          result.splice(idx, 1);
+          keyToIndex.delete(keyToRemove);
+          updateIndicesAfterRemoval(keyToIndex, idx);
+        }
+        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");
+          continue;
+        }
+
+        if (isAbsoluteTitle(titleValue)) {
+          // Absolute title bypasses any template
+          addOrReplace(result, keyToIndex, { title: titleValue.absolute }, "title");
+          continue;
+        }
+
+        // String title - apply template if one exists
+        const finalTitle = titleTemplate
+          ? titleTemplate.replace("%s", titleValue as string)
+          : titleValue;
+        addOrReplace(result, keyToIndex, { title: finalTitle as string }, "title");
+        continue;
+      }
+
+      // Handle all other descriptors
+      const key = getMetaKey(descriptor);
+      addOrReplace(result, keyToIndex, descriptor, key);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Built-in handle for managing document metadata.
+ *
+ * Use `ctx.use(Meta)` in route handlers to push meta descriptors.
+ * Use `<MetaTags />` component to render them in the document head.
+ */
+export const Meta: Handle<MetaDescriptor, MetaDescriptor[]> = createHandle<MetaDescriptor, MetaDescriptor[]>(
+  collectMeta,
+  "__rsc_router_meta__"
+);