@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.100

package/src/handles/breadcrumbs.ts

@@ -0,0 +1,66 @@
+/**
+ * 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` (last item for each href wins).
+ *
+ * @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
+ * (last item for each href wins).
+ */
+function collectBreadcrumbs(segments: BreadcrumbItem[][]): BreadcrumbItem[] {
+  const all = segments.flat();
+  const seen = new Map<string, number>();
+
+  for (let i = 0; i < all.length; i++) {
+    seen.set(all[i].href, i);
+  }
+
+  // Return items in order, keeping only the last occurrence per href
+  return all.filter((item, index) => seen.get(item.href) === index);
+}
+
+/**
+ * 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/index.ts

@@ -4,3 +4,4 @@
 
 export { Meta } from "./meta.ts";
 export { MetaTags } from "./MetaTags.tsx";
+export { Breadcrumbs, type BreadcrumbItem } from "./breadcrumbs.ts";

package/src/handles/meta.ts

@@ -39,7 +39,7 @@ import type {
  * Type guard for unset descriptor
  */
 function isUnsetDescriptor(
-  descriptor: MetaDescriptor
+  descriptor: MetaDescriptor,
 ): descriptor is UnsetDescriptor {
   return (
     typeof descriptor === "object" &&
@@ -53,7 +53,7 @@ function isUnsetDescriptor(
  * Type guard for title descriptor (any form)
  */
 function isTitleDescriptor(
-  descriptor: MetaDescriptor
+  descriptor: MetaDescriptor,
 ): descriptor is { title: TitleDescriptor } {
   return (
     typeof descriptor === "object" &&
@@ -66,7 +66,7 @@ function isTitleDescriptor(
  * Type guard for title template descriptor
  */
 function isTitleTemplate(
-  title: TitleDescriptor
+  title: TitleDescriptor,
 ): title is { template: string; default: string } {
   return (
     typeof title === "object" &&
@@ -79,7 +79,9 @@ 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;
 }
 
@@ -141,7 +143,7 @@ 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;
@@ -158,7 +160,7 @@ function addOrReplace(
  */
 function updateIndicesAfterRemoval(
   keyToIndex: Map<string, number>,
-  removedIndex: number
+  removedIndex: number,
 ): void {
   for (const [key, index] of keyToIndex) {
     if (index > removedIndex) {
@@ -208,13 +210,23 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
           // 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;
         }
 
@@ -222,7 +234,12 @@ function collectMeta(segments: MetaDescriptor[][]): MetaDescriptor[] {
         const finalTitle = titleTemplate
           ? titleTemplate.replace("%s", titleValue as string)
           : titleValue;
-        addOrReplace(result, keyToIndex, { title: finalTitle as string }, "title");
+        addOrReplace(
+          result,
+          keyToIndex,
+          { title: finalTitle as string },
+          "title",
+        );
         continue;
       }
 
@@ -241,7 +258,7 @@ 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.
  */
-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__");

package/src/host/cookie-handler.ts

@@ -4,30 +4,36 @@
  * Manages cookie-based host override for development environments.
  */
 
-import type { HostOverrideConfig } from './types.js';
-import { matchPattern, parseRequest } from './pattern-matcher.js';
+import type { HostOverrideConfig } from "./types.js";
+import type { RouterRequestInput } from "../router/router-interfaces.js";
+import { matchPattern, parseRequest } from "./pattern-matcher.js";
 import {
   HostOverrideNotAllowedError,
   InvalidHostnameError,
   HostValidationError,
-} from './errors.js';
+} from "./errors.js";
 
 /**
  * Parse cookies from request
  */
 export function parseCookies(request: Request): Record<string, string> {
-  const cookieHeader = request.headers.get('cookie');
+  const cookieHeader = request.headers.get("cookie");
   if (!cookieHeader) {
     return {};
   }
 
   const cookies: Record<string, string> = {};
-  const pairs = cookieHeader.split(';');
+  const pairs = cookieHeader.split(";");
 
   for (const pair of pairs) {
-    const [key, value] = pair.trim().split('=');
-    if (key && value) {
-      cookies[key] = decodeURIComponent(value);
+    const [name, ...rest] = pair.trim().split("=");
+    if (name && rest.length > 0) {
+      const value = rest.join("=");
+      try {
+        cookies[name] = decodeURIComponent(value);
+      } catch {
+        cookies[name] = value;
+      }
     }
   }
 
@@ -54,7 +60,7 @@ export function createDeleteCookieHeader(name: string): string {
  */
 export function createCookieErrorResponse(
   cookieName: string,
-  message: string
+  message: string,
 ): Response {
   return new Response(
     JSON.stringify({
@@ -64,10 +70,10 @@ export function createCookieErrorResponse(
     {
       status: 400,
       headers: {
-        'Content-Type': 'application/json',
-        'Set-Cookie': createDeleteCookieHeader(cookieName),
+        "Content-Type": "application/json",
+        "Set-Cookie": createDeleteCookieHeader(cookieName),
       },
-    }
+    },
   );
 }
 
@@ -76,7 +82,7 @@ export function createCookieErrorResponse(
  */
 export function isHostAllowed(
   request: Request,
-  allowedHosts: string[]
+  allowedHosts: string[],
 ): boolean {
   const { hostname, pathname, parts } = parseRequest(request);
 
@@ -98,7 +104,7 @@ export function isHostAllowed(
 export function handleCookieOverride(
   request: Request,
   config: HostOverrideConfig | undefined,
-  context: any
+  input: RouterRequestInput<any>,
 ): string {
   if (!config) {
     const { hostname } = parseRequest(request);
@@ -127,7 +133,7 @@ export function handleCookieOverride(
   // If allowed and has custom validation, run it
   if (validate) {
     try {
-      const validatedHostname = validate(request, cookieValue, context);
+      const validatedHostname = validate(request, cookieValue, input);
       return validatedHostname;
     } catch (error) {
       // Wrap in HostValidationError

package/src/host/errors.ts

@@ -22,7 +22,7 @@ export class HostRouterError extends Error {
     if (options?.cause) {
       this.cause = options.cause;
     }
-    this.name = 'HostRouterError';
+    this.name = "HostRouterError";
     Object.setPrototypeOf(this, HostRouterError.prototype);
   }
 }
@@ -33,7 +33,7 @@ export class HostRouterError extends Error {
 export class InvalidPatternError extends HostRouterError {
   constructor(pattern: string, reason: string, options?: ErrorOptions) {
     super(`Invalid pattern "${pattern}": ${reason}`, options);
-    this.name = 'InvalidPatternError';
+    this.name = "InvalidPatternError";
     Object.setPrototypeOf(this, InvalidPatternError.prototype);
   }
 }
@@ -45,9 +45,9 @@ export class HostOverrideNotAllowedError extends HostRouterError {
   constructor(currentHost: string, cookieName: string, options?: ErrorOptions) {
     super(
       `Host override not allowed on "${currentHost}" (cookie: ${cookieName})`,
-      options
+      options,
     );
-    this.name = 'HostOverrideNotAllowedError';
+    this.name = "HostOverrideNotAllowedError";
     Object.setPrototypeOf(this, HostOverrideNotAllowedError.prototype);
   }
 }
@@ -58,7 +58,7 @@ export class HostOverrideNotAllowedError extends HostRouterError {
 export class InvalidHostnameError extends HostRouterError {
   constructor(hostname: string, options?: ErrorOptions) {
     super(`Invalid hostname format: "${hostname}"`, options);
-    this.name = 'InvalidHostnameError';
+    this.name = "InvalidHostnameError";
     Object.setPrototypeOf(this, InvalidHostnameError.prototype);
   }
 }
@@ -69,7 +69,7 @@ export class InvalidHostnameError extends HostRouterError {
 export class HostValidationError extends HostRouterError {
   constructor(message: string, cause?: unknown) {
     super(message, { cause });
-    this.name = 'HostValidationError';
+    this.name = "HostValidationError";
     Object.setPrototypeOf(this, HostValidationError.prototype);
   }
 }
@@ -80,7 +80,7 @@ export class HostValidationError extends HostRouterError {
 export class NoRouteMatchError extends HostRouterError {
   constructor(hostname: string, pathname: string, options?: ErrorOptions) {
     super(`No route matched for ${hostname}${pathname}`, options);
-    this.name = 'NoRouteMatchError';
+    this.name = "NoRouteMatchError";
     Object.setPrototypeOf(this, NoRouteMatchError.prototype);
   }
 }
@@ -91,7 +91,7 @@ export class NoRouteMatchError extends HostRouterError {
 export class InvalidHandlerError extends HostRouterError {
   constructor(handler: unknown, options?: ErrorOptions) {
     super(`Invalid handler type: ${typeof handler}`, options);
-    this.name = 'InvalidHandlerError';
+    this.name = "InvalidHandlerError";
     Object.setPrototypeOf(this, InvalidHandlerError.prototype);
   }
 }

package/src/host/index.ts

@@ -23,13 +23,10 @@
  */
 
 // Core router
-export { createHostRouter } from './router.js';
-
-// Host router registry for build-time discovery
-export { HostRouterRegistry, type HostRouterRegistryEntry } from './router.js';
+export { createHostRouter } from "./router.js";
 
 // Utilities
-export { defineHosts } from './utils.js';
+export { defineHosts } from "./utils.js";
 
 // Errors
 export {
@@ -40,7 +37,7 @@ export {
   HostValidationError,
   NoRouteMatchError,
   InvalidHandlerError,
-} from './errors.js';
+} from "./errors.js";
 
 // Types
 export type {
@@ -53,4 +50,4 @@ export type {
   HostPattern,
   HostMatchResult,
   HostOverrideConfig,
-} from './types.js';
+} from "./types.js";

package/src/host/pattern-matcher.ts

@@ -14,17 +14,17 @@
  * - `example.com/admin` - specific domain with path prefix
  */
 
-import { InvalidPatternError } from './errors.js';
+import { InvalidPatternError } from "./errors.js";
 
 /**
  * Normalize a pattern by removing trailing slashes from paths
  */
 export function normalizePattern(pattern: string): string {
   // If pattern has a path component, remove trailing slash
-  const slashIndex = pattern.indexOf('/');
+  const slashIndex = pattern.indexOf("/");
   if (slashIndex !== -1) {
     const domain = pattern.slice(0, slashIndex);
-    const path = pattern.slice(slashIndex).replace(/\/$/, '');
+    const path = pattern.slice(slashIndex).replace(/\/$/, "");
     return domain + path;
   }
   return pattern;
@@ -41,7 +41,7 @@ export function parseRequest(request: Request): {
   const url = new URL(request.url);
   const hostname = url.hostname;
   const pathname = url.pathname;
-  const parts = hostname.split('.');
+  const parts = hostname.split(".");
 
   return { hostname, pathname, parts };
 }
@@ -70,12 +70,12 @@ export function matchPattern(
   pattern: string,
   hostname: string,
   pathname: string,
-  parts: string[]
+  parts: string[],
 ): boolean {
   const normalized = normalizePattern(pattern);
 
   // Check if pattern has path component
-  const slashIndex = normalized.indexOf('/');
+  const slashIndex = normalized.indexOf("/");
   const hasPath = slashIndex !== -1;
   const domainPattern = hasPath ? normalized.slice(0, slashIndex) : normalized;
   const pathPattern = hasPath ? normalized.slice(slashIndex) : null;
@@ -88,7 +88,7 @@ export function matchPattern(
 
   // Then match path (prefix match)
   if (pathPattern) {
-    return pathname === pathPattern || pathname.startsWith(pathPattern + '/');
+    return pathname === pathPattern || pathname.startsWith(pathPattern + "/");
   }
 
   return true;
@@ -100,7 +100,7 @@ export function matchPattern(
 function matchDomainPattern(
   pattern: string,
   hostname: string,
-  parts: string[]
+  parts: string[],
 ): boolean {
   // Exact match
   if (pattern === hostname) {
@@ -108,48 +108,48 @@ function matchDomainPattern(
   }
 
   // `.` or `*` - any apex domain
-  if (pattern === '.' || pattern === '*') {
+  if (pattern === "." || pattern === "*") {
     return isApexDomain(parts);
   }
 
   // `**` - any domain (apex + all subdomains)
-  if (pattern === '**') {
+  if (pattern === "**") {
     return true;
   }
 
   // `*.` - any single-level subdomain
-  if (pattern === '*.') {
+  if (pattern === "*.") {
     return getSubdomainLevel(parts) === 1;
   }
 
   // `**.` - any multi-level subdomain (2+ levels)
-  if (pattern === '**.') {
+  if (pattern === "**.") {
     return getSubdomainLevel(parts) >= 2;
   }
 
   // `*.tld` - any apex domain with specific TLD (e.g., *.com)
-  if (pattern.startsWith('*.') && !pattern.includes('.', 2)) {
+  if (pattern.startsWith("*.") && !pattern.includes(".", 2)) {
     const tld = pattern.slice(2);
-    return isApexDomain(parts) && hostname.endsWith('.' + tld);
+    return isApexDomain(parts) && hostname.endsWith("." + tld);
   }
 
   // `*.example.com` - single subdomain of specific domain
-  if (pattern.startsWith('*.')) {
+  if (pattern.startsWith("*.")) {
     const baseDomain = pattern.slice(2);
-    if (hostname.endsWith('.' + baseDomain)) {
+    if (hostname.endsWith("." + baseDomain)) {
       // Count parts: if pattern is *.example.com (3 parts),
       // hostname should have exactly 4 parts (www.example.com)
-      const patternParts = baseDomain.split('.');
+      const patternParts = baseDomain.split(".");
       return parts.length === patternParts.length + 1;
     }
     return false;
   }
 
   // `**.example.com` - any depth subdomain of specific domain
-  if (pattern.startsWith('**.')) {
+  if (pattern.startsWith("**.")) {
     const baseDomain = pattern.slice(3);
-    if (hostname.endsWith('.' + baseDomain)) {
-      const patternParts = baseDomain.split('.');
+    if (hostname.endsWith("." + baseDomain)) {
+      const patternParts = baseDomain.split(".");
       // Must have more parts than the base domain (i.e., has subdomains)
       return parts.length > patternParts.length;
     }
@@ -158,7 +158,7 @@ function matchDomainPattern(
 
   // `subdomain.*` - specific subdomain of any apex domain
   // e.g., admin.* matches admin.example.com, admin.google.com
-  if (pattern.endsWith('.*')) {
+  if (pattern.endsWith(".*")) {
     const subdomain = pattern.slice(0, -2);
     // Must be single-level subdomain (3 parts total)
     if (parts.length === 3 && parts[0] === subdomain) {
@@ -169,7 +169,7 @@ function matchDomainPattern(
 
   // `subdomain.**` - specific subdomain of any domain (including multi-level)
   // e.g., admin.** matches admin.example.com, admin.sub.example.com
-  if (pattern.endsWith('.**')) {
+  if (pattern.endsWith(".**")) {
     const subdomain = pattern.slice(0, -3);
     if (parts.length >= 3 && parts[0] === subdomain) {
       return true;
@@ -179,7 +179,7 @@ function matchDomainPattern(
 
   // `subdomain.` - specific subdomain of any apex domain (no wildcard)
   // e.g., admin. matches admin.example.com, admin.google.com
-  if (pattern.endsWith('.') && !pattern.includes('*')) {
+  if (pattern.endsWith(".") && !pattern.includes("*")) {
     const subdomain = pattern.slice(0, -1);
     // Must be exactly 3 parts (subdomain.domain.tld)
     if (parts.length === 3 && parts[0] === subdomain) {
@@ -195,17 +195,17 @@ function matchDomainPattern(
  * Validate pattern format
  */
 export function validatePattern(pattern: string): void {
-  if (!pattern || typeof pattern !== 'string') {
+  if (!pattern || typeof pattern !== "string") {
     throw new InvalidPatternError(
       pattern,
-      'Pattern must be a non-empty string',
-      { cause: { type: typeof pattern, value: pattern } }
+      "Pattern must be a non-empty string",
+      { cause: { type: typeof pattern, value: pattern } },
     );
   }
 
   // Check for invalid characters (spaces, etc.)
   if (/\s/.test(pattern)) {
-    throw new InvalidPatternError(pattern, 'contains whitespace', {
+    throw new InvalidPatternError(pattern, "contains whitespace", {
       cause: { pattern },
     });
   }