@timber-js/app 0.1.0 → 0.1.2

package/src/server/metadata.ts

@@ -0,0 +1,263 @@
+/**
+ * Metadata resolution for timber.js.
+ *
+ * Resolves metadata from a segment chain (layouts + page), applies title
+ * templates, shallow-merges entries, and produces head element descriptors.
+ *
+ * Resolution happens inside the render pass — React.cache is active,
+ * metadata is outside Suspense, and the flush point guarantees completeness.
+ *
+ * Rendering (Metadata → HeadElement[]) is in metadata-render.ts.
+ *
+ * See design/16-metadata.md
+ */
+
+import type { Metadata } from './types.js';
+
+// Re-export renderMetadataToElements from the rendering module so existing
+// consumers (route-element-builder, tests) can keep importing from here.
+export { renderMetadataToElements } from './metadata-render.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+/** A single metadata entry from a layout or page module. */
+export interface SegmentMetadataEntry {
+  /** The resolved metadata object (from static or async `metadata` export). */
+  metadata: Metadata;
+  /** Whether this entry is from the page (leaf) module. */
+  isPage: boolean;
+}
+
+/** Options for resolveMetadata. */
+export interface ResolveMetadataOptions {
+  /**
+   * When true, the page's metadata is discarded (simulating a render error)
+   * and `<meta name="robots" content="noindex">` is injected.
+   */
+  errorState?: boolean;
+}
+
+/** A rendered head element descriptor. */
+export interface HeadElement {
+  tag: 'title' | 'meta' | 'link';
+  content?: string;
+  attrs?: Record<string, string>;
+}
+
+// ─── Title Resolution ────────────────────────────────────────────────────────
+
+/**
+ * Resolve a title value with an optional template.
+ *
+ * - string → apply template if present
+ * - { absolute: '...' } → use as-is, skip template
+ * - { default: '...' } → use as fallback (no template applied)
+ * - undefined → undefined
+ */
+export function resolveTitle(
+  title: Metadata['title'],
+  template: string | undefined
+): string | undefined {
+  if (title === undefined || title === null) {
+    return undefined;
+  }
+
+  if (typeof title === 'string') {
+    return template ? template.replace('%s', title) : title;
+  }
+
+  // Object form
+  if (title.absolute !== undefined) {
+    return title.absolute;
+  }
+
+  if (title.default !== undefined) {
+    return title.default;
+  }
+
+  return undefined;
+}
+
+// ─── Metadata Resolution ─────────────────────────────────────────────────────
+
+/**
+ * Resolve metadata from a segment chain.
+ *
+ * Processes entries from root layout to page (in segment order).
+ * The merge algorithm:
+ *   1. Shallow-merge all keys except title (later wins)
+ *   2. Track the most recent title template
+ *   3. Resolve the final title using the template
+ *
+ * In error state, the page entry is dropped and noindex is injected.
+ *
+ * See design/16-metadata.md §"Merge Algorithm"
+ */
+export function resolveMetadata(
+  entries: SegmentMetadataEntry[],
+  options: ResolveMetadataOptions = {}
+): Metadata {
+  const { errorState = false } = options;
+
+  const merged: Metadata = {};
+  let titleTemplate: string | undefined;
+  let lastDefault: string | undefined;
+  let rawTitle: Metadata['title'];
+
+  for (const { metadata, isPage } of entries) {
+    // In error state, skip the page's metadata entirely
+    if (errorState && isPage) {
+      continue;
+    }
+
+    // Track title template
+    if (metadata.title !== undefined && typeof metadata.title === 'object') {
+      if (metadata.title.template !== undefined) {
+        titleTemplate = metadata.title.template;
+      }
+      if (metadata.title.default !== undefined) {
+        lastDefault = metadata.title.default;
+      }
+    }
+
+    // Shallow-merge all keys except title
+    for (const key of Object.keys(metadata) as Array<keyof Metadata>) {
+      if (key === 'title') continue;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (merged as any)[key] = metadata[key];
+    }
+
+    // Track raw title (will be resolved after the loop)
+    if (metadata.title !== undefined) {
+      rawTitle = metadata.title;
+    }
+  }
+
+  // In error state, we lost page title — use the most recent default
+  if (errorState) {
+    rawTitle = lastDefault !== undefined ? { default: lastDefault } : rawTitle;
+    // Don't apply template in error state
+    titleTemplate = undefined;
+  }
+
+  // Resolve the final title
+  const resolvedTitle = resolveTitle(rawTitle, titleTemplate);
+  if (resolvedTitle !== undefined) {
+    merged.title = resolvedTitle;
+  }
+
+  // Error state: inject noindex, overriding any user robots
+  if (errorState) {
+    merged.robots = 'noindex';
+  }
+
+  return merged;
+}
+
+// ─── URL Resolution ──────────────────────────────────────────────────────────
+
+/**
+ * Check if a string is an absolute URL.
+ */
+function isAbsoluteUrl(url: string): boolean {
+  return url.startsWith('http://') || url.startsWith('https://') || url.startsWith('//');
+}
+
+/**
+ * Resolve a relative URL against a base URL.
+ */
+function resolveUrl(url: string, base: URL): string {
+  if (isAbsoluteUrl(url)) return url;
+  return new URL(url, base).toString();
+}
+
+/**
+ * Resolve relative URLs in metadata fields against metadataBase.
+ *
+ * Returns a new metadata object with URLs resolved. Absolute URLs are not modified.
+ * If metadataBase is not set, returns the metadata unchanged.
+ */
+export function resolveMetadataUrls(metadata: Metadata): Metadata {
+  const base = metadata.metadataBase;
+  if (!base) return metadata;
+
+  const result = { ...metadata };
+
+  // Resolve openGraph images
+  if (result.openGraph) {
+    result.openGraph = { ...result.openGraph };
+    if (typeof result.openGraph.images === 'string') {
+      result.openGraph.images = resolveUrl(result.openGraph.images, base);
+    } else if (Array.isArray(result.openGraph.images)) {
+      result.openGraph.images = result.openGraph.images.map((img) => ({
+        ...img,
+        url: resolveUrl(img.url, base),
+      }));
+    } else if (result.openGraph.images) {
+      // Single object: { url, width?, height?, alt? }
+      result.openGraph.images = {
+        ...result.openGraph.images,
+        url: resolveUrl(result.openGraph.images.url, base),
+      };
+    }
+    if (result.openGraph.url && !isAbsoluteUrl(result.openGraph.url)) {
+      result.openGraph.url = resolveUrl(result.openGraph.url, base);
+    }
+  }
+
+  // Resolve twitter images
+  if (result.twitter) {
+    result.twitter = { ...result.twitter };
+    if (typeof result.twitter.images === 'string') {
+      result.twitter.images = resolveUrl(result.twitter.images, base);
+    } else if (Array.isArray(result.twitter.images)) {
+      // Resolve each image URL, preserving the union type structure
+      const resolved = result.twitter.images.map((img) =>
+        typeof img === 'string' ? resolveUrl(img, base) : { ...img, url: resolveUrl(img.url, base) }
+      );
+      // If all entries are strings, assign as string[]; otherwise as object[]
+      const allStrings = resolved.every((r) => typeof r === 'string');
+      result.twitter.images = allStrings
+        ? (resolved as string[])
+        : (resolved as Array<{ url: string; alt?: string; width?: number; height?: number }>);
+    } else if (result.twitter.images) {
+      // Single object: { url, alt?, width?, height? }
+      result.twitter.images = {
+        ...result.twitter.images,
+        url: resolveUrl(result.twitter.images.url, base),
+      };
+    }
+  }
+
+  // Resolve alternates
+  if (result.alternates) {
+    result.alternates = { ...result.alternates };
+    if (result.alternates.canonical && !isAbsoluteUrl(result.alternates.canonical)) {
+      result.alternates.canonical = resolveUrl(result.alternates.canonical, base);
+    }
+    if (result.alternates.languages) {
+      const langs: Record<string, string> = {};
+      for (const [lang, url] of Object.entries(result.alternates.languages)) {
+        langs[lang] = isAbsoluteUrl(url) ? url : resolveUrl(url, base);
+      }
+      result.alternates.languages = langs;
+    }
+  }
+
+  // Resolve icon URLs
+  if (result.icons) {
+    result.icons = { ...result.icons };
+    if (typeof result.icons.icon === 'string') {
+      result.icons.icon = resolveUrl(result.icons.icon, base);
+    } else if (Array.isArray(result.icons.icon)) {
+      result.icons.icon = result.icons.icon.map((i) => ({ ...i, url: resolveUrl(i.url, base) }));
+    }
+    if (typeof result.icons.apple === 'string') {
+      result.icons.apple = resolveUrl(result.icons.apple, base);
+    } else if (Array.isArray(result.icons.apple)) {
+      result.icons.apple = result.icons.apple.map((i) => ({ ...i, url: resolveUrl(i.url, base) }));
+    }
+  }
+
+  return result;
+}

package/src/server/middleware-runner.ts

@@ -0,0 +1,32 @@
+/**
+ * Middleware runner — executes a route's middleware.ts before rendering.
+ *
+ * Only the leaf route's middleware runs. There is no middleware chain.
+ * Middleware does NOT have next() — it either short-circuits with a Response
+ * or returns void to continue to access checks + render.
+ *
+ * See design/07-routing.md §"middleware.ts"
+ */
+
+import type { MiddlewareContext } from './types.js';
+
+/** Signature of a middleware.ts default export. */
+export type MiddlewareFn = (ctx: MiddlewareContext) => Response | void | Promise<Response | void>;
+
+/**
+ * Run a route's middleware function.
+ *
+ * @param middlewareFn - The default export from the route's middleware.ts
+ * @param ctx - The middleware context (req, params, headers, requestHeaders, searchParams)
+ * @returns A Response if middleware short-circuited, or undefined to continue
+ */
+export async function runMiddleware(
+  middlewareFn: MiddlewareFn,
+  ctx: MiddlewareContext
+): Promise<Response | undefined> {
+  const result = await middlewareFn(ctx);
+  if (result instanceof Response) {
+    return result;
+  }
+  return undefined;
+}

package/src/server/nuqs-ssr-provider.tsx

@@ -0,0 +1,63 @@
+/**
+ * Server-side nuqs adapter provider for SSR rendering.
+ *
+ * During SSR, `'use client'` components that call nuqs hooks (useQueryStates,
+ * useQueryState) need the nuqs adapter context. The client adapter
+ * (TimberNuqsAdapter) relies on `window` and React hooks that are
+ * client-only. This provider supplies a static, SSR-safe adapter
+ * that feeds the current request's search params into the nuqs context.
+ *
+ * The returned component wraps the React tree so that nuqs hooks render
+ * the correct initial values during server-side rendering. On the client,
+ * TimberNuqsAdapter (injected by browser-entry.ts) takes over.
+ *
+ * Design doc: design/23-search-params.md §"Custom Adapter"
+ */
+
+import { createElement, type ReactNode } from 'react';
+import {
+  unstable_createAdapterProvider as createAdapterProvider,
+  type unstable_AdapterInterface as AdapterInterface,
+} from 'nuqs/adapters/custom';
+
+// ─── SSR Adapter ──────────────────────────────────────────────────
+
+/**
+ * Create a nuqs adapter provider for SSR that serves a static snapshot
+ * of search params. The `updateUrl` is a no-op because URL updates
+ * cannot happen on the server.
+ */
+function makeNuqsSsrAdapter(searchParams: URLSearchParams) {
+  function useNuqsSsrAdapter(_watchKeys: string[]): AdapterInterface {
+    return {
+      searchParams,
+      updateUrl: () => {},
+      getSearchParamsSnapshot: () => searchParams,
+    };
+  }
+
+  return createAdapterProvider(useNuqsSsrAdapter);
+}
+
+// ─── Provider Component ───────────────────────────────────────────
+
+/**
+ * Wrap the SSR element tree with a nuqs adapter context.
+ *
+ * Called by ssr-entry.ts before passing the element to renderSsrStream.
+ * Takes the NavContext search params and provides them to nuqs hooks
+ * running during SSR so they render with the correct initial values.
+ *
+ * @param searchParamsRecord - The request's search params as a plain record
+ * @param children - The React element tree to wrap
+ */
+export function withNuqsSsrAdapter(
+  searchParamsRecord: Record<string, string>,
+  children: ReactNode
+): ReactNode {
+  const searchParams = new URLSearchParams(searchParamsRecord);
+  const Provider = makeNuqsSsrAdapter(searchParams);
+  // AdapterProvider types require children in the props object (not as 3rd arg)
+  // eslint-disable-next-line react/no-children-prop
+  return createElement(Provider, { defaultOptions: { shallow: false, scroll: true }, children });
+}