@timber-js/app 0.1.0 → 0.1.2

package/src/client/error-boundary.tsx

@@ -0,0 +1,209 @@
+'use client';
+
+/**
+ * Framework-injected React error boundary.
+ *
+ * Catches errors thrown by children and renders a fallback component
+ * with the appropriate props based on error type:
+ *   - DenySignal (4xx) → { status, dangerouslyPassData }
+ *   - RenderError (5xx) → { error, digest, reset }
+ *   - Unhandled error → { error, digest: null, reset }
+ *
+ * The `status` prop controls which errors this boundary catches:
+ *   - Specific code (e.g. 403) → only that status
+ *   - Category (400) → any 4xx
+ *   - Category (500) → any 5xx
+ *   - Omitted → catches everything (error.tsx behavior)
+ *
+ * See design/10-error-handling.md §"Status-Code Files"
+ */
+
+import { Component, createElement, type ReactNode } from 'react';
+
+// ─── Page Unload Detection ───────────────────────────────────────────────────
+// Track whether the page is being unloaded (user refreshed or navigated away).
+// When this is true, error boundaries suppress activation — the error is from
+// the aborted connection, not an application error.
+let _isUnloading = false;
+if (typeof window !== 'undefined') {
+  window.addEventListener('beforeunload', () => {
+    _isUnloading = true;
+  });
+  window.addEventListener('pagehide', () => {
+    _isUnloading = true;
+  });
+}
+
+// ─── Digest Types ────────────────────────────────────────────────────────────
+
+/** Structured digest returned by RSC onError for DenySignal. */
+interface DenyDigest {
+  type: 'deny';
+  status: number;
+  data: unknown;
+}
+
+/** Structured digest returned by RSC onError for RenderError. */
+interface RenderErrorDigest {
+  type: 'render-error';
+  code: string;
+  data: unknown;
+  status: number;
+}
+
+/** Structured digest returned by RSC onError for RedirectSignal. */
+interface RedirectDigest {
+  type: 'redirect';
+  location: string;
+  status: number;
+}
+
+type ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;
+
+// ─── Props & State ───────────────────────────────────────────────────────────
+
+export interface TimberErrorBoundaryProps {
+  /** The component to render when an error is caught. */
+  fallbackComponent: (...args: unknown[]) => ReactNode;
+  /**
+   * Status code filter. If set, only catches errors matching this status.
+   * 400 = any 4xx, 500 = any 5xx, specific number = exact match.
+   */
+  status?: number;
+  children: ReactNode;
+}
+
+interface TimberErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+// ─── Component ───────────────────────────────────────────────────────────────
+
+export class TimberErrorBoundary extends Component<
+  TimberErrorBoundaryProps,
+  TimberErrorBoundaryState
+> {
+  constructor(props: TimberErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): TimberErrorBoundaryState {
+    // Suppress error boundaries during page unload (refresh/navigate away).
+    // The aborted connection causes React's streaming hydration to error,
+    // but the page is about to be replaced — showing an error boundary
+    // would be a jarring flash for the user.
+    if (_isUnloading) {
+      return { hasError: false, error: null };
+    }
+    return { hasError: true, error };
+  }
+
+  componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {
+    // Reset error state when children change (e.g. client-side navigation).
+    // Without this, navigating from one error page to another keeps the
+    // stale error — getDerivedStateFromError doesn't re-fire for new children.
+    if (this.state.hasError && prevProps.children !== this.props.children) {
+      this.setState({ hasError: false, error: null });
+    }
+  }
+
+  /** Reset the error state so children re-render. */
+  private reset = () => {
+    this.setState({ hasError: false, error: null });
+  };
+
+  render(): ReactNode {
+    if (!this.state.hasError || !this.state.error) {
+      return this.props.children;
+    }
+
+    const error = this.state.error;
+    const parsed = parseDigest(error);
+
+    // RedirectSignal errors must propagate through all error boundaries
+    // so the SSR shell fails and the pipeline catch block can produce a
+    // proper HTTP redirect response. See design/04-authorization.md.
+    if (parsed?.type === 'redirect') {
+      throw error;
+    }
+
+    // If this boundary has a status filter, check whether the error matches.
+    // Non-matching errors re-throw so an outer boundary can catch them.
+    if (this.props.status != null) {
+      const errorStatus = getErrorStatus(parsed, error);
+      if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) {
+        // Re-throw: this boundary doesn't handle this error.
+        throw error;
+      }
+    }
+
+    // Render the fallback component with the right props shape.
+    if (parsed?.type === 'deny') {
+      return createElement(this.props.fallbackComponent as never, {
+        status: parsed.status,
+        dangerouslyPassData: parsed.data,
+      });
+    }
+
+    // 5xx / RenderError / unhandled error
+    const digest =
+      parsed?.type === 'render-error' ? { code: parsed.code, data: parsed.data } : null;
+
+    return createElement(this.props.fallbackComponent as never, {
+      error,
+      digest,
+      reset: this.reset,
+    });
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Parse the structured digest from the error.
+ * React sets `error.digest` from the string returned by RSC's onError.
+ */
+function parseDigest(error: Error): ParsedDigest | null {
+  const raw = (error as { digest?: string }).digest;
+  if (typeof raw !== 'string') return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {
+      return parsed as ParsedDigest;
+    }
+  } catch {
+    // Not JSON — legacy or unknown digest format
+  }
+  return null;
+}
+
+/**
+ * Extract the HTTP status code from a parsed digest or error message.
+ * Falls back to message pattern matching for errors without a digest.
+ */
+function getErrorStatus(parsed: ParsedDigest | null, error: Error): number | null {
+  if (parsed?.type === 'deny') return parsed.status;
+  if (parsed?.type === 'render-error') return parsed.status;
+  if (parsed?.type === 'redirect') return parsed.status;
+
+  // Fallback: parse DenySignal message pattern for errors that lost their digest
+  const match = error.message.match(/^Access denied with status (\d+)$/);
+  if (match) return parseInt(match[1], 10);
+
+  // Unhandled errors are implicitly 500
+  return 500;
+}
+
+/**
+ * Check whether an error's status matches the boundary's status filter.
+ * Category markers (400, 500) match any status in that range.
+ */
+function statusMatches(boundaryStatus: number, errorStatus: number): boolean {
+  // Category catch-all: 400 matches any 4xx, 500 matches any 5xx
+  if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;
+  if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;
+  // Exact match
+  return boundaryStatus === errorStatus;
+}

package/src/client/form.tsx

@@ -0,0 +1,200 @@
+/**
+ * Client-side form utilities for server actions.
+ *
+ * Exports a typed `useActionState` that understands the action builder's result shape.
+ * Result is typed to:
+ *   { data: T } | { validationErrors: Record<string, string[]> } | { serverError: { code, data? } } | null
+ *
+ * The action builder emits a function that satisfies both the direct call signature
+ * and React's `(prevState, formData) => Promise<State>` contract.
+ *
+ * See design/08-forms-and-actions.md §"Client-Side Form Mechanics"
+ */
+
+import { useActionState as reactUseActionState, useTransition } from 'react';
+import type { ActionResult, ValidationErrors } from '#/server/action-client';
+import type { FormFlashData } from '#/server/form-flash';
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+/**
+ * The action function type accepted by useActionState.
+ * Must satisfy React's (prevState, formData) => Promise<State> contract.
+ */
+export type UseActionStateFn<TData> = (
+  prevState: ActionResult<TData> | null,
+  formData: FormData
+) => Promise<ActionResult<TData>>;
+
+/**
+ * Return type of useActionState — matches React 19's useActionState return.
+ * [result, formAction, isPending]
+ */
+export type UseActionStateReturn<TData> = [
+  result: ActionResult<TData> | null,
+  formAction: (formData: FormData) => void,
+  isPending: boolean,
+];
+
+// ─── useActionState ──────────────────────────────────────────────────────
+
+/**
+ * Typed wrapper around React 19's `useActionState` that understands
+ * the timber action builder's result shape.
+ *
+ * @param action - A server action created with createActionClient or a raw 'use server' function.
+ * @param initialState - Initial state, typically `null`. Pass `getFormFlash()` for no-JS
+ *   progressive enhancement — the flash seeds the initial state so the form has a
+ *   single source of truth for both with-JS and no-JS paths.
+ * @param permalink - Optional permalink for progressive enhancement (no-JS fallback URL).
+ *
+ * @example
+ * ```tsx
+ * 'use client'
+ * import { useActionState } from '@timber/app/client'
+ * import { createTodo } from './actions'
+ *
+ * export function NewTodoForm({ flash }) {
+ *   const [result, action, isPending] = useActionState(createTodo, flash)
+ *   return (
+ *     <form action={action}>
+ *       <input name="title" />
+ *       {result?.validationErrors?.title && <p>{result.validationErrors.title}</p>}
+ *       <button disabled={isPending}>Add</button>
+ *     </form>
+ *   )
+ * }
+ * ```
+ */
+export function useActionState<TData>(
+  action: UseActionStateFn<TData>,
+  initialState: ActionResult<TData> | FormFlashData | null,
+  permalink?: string
+): UseActionStateReturn<TData> {
+  // FormFlashData is structurally compatible with ActionResult at runtime —
+  // the cast satisfies React's generic inference which would otherwise widen TData.
+  return reactUseActionState(action, initialState as ActionResult<TData> | null, permalink);
+}
+
+// ─── useFormAction ───────────────────────────────────────────────────────
+
+/**
+ * Hook for calling a server action imperatively (not via a form).
+ * Returns [execute, isPending] where execute accepts the input directly.
+ *
+ * @example
+ * ```tsx
+ * const [deleteTodo, isPending] = useFormAction(deleteTodoAction)
+ * <button onClick={() => deleteTodo({ id: todo.id })} disabled={isPending}>
+ *   Delete
+ * </button>
+ * ```
+ */
+export function useFormAction<TData>(
+  action: (input: unknown) => Promise<ActionResult<TData>>
+): [(input?: unknown) => Promise<ActionResult<TData>>, boolean] {
+  const [isPending, startTransition] = useTransition();
+
+  const execute = (input?: unknown): Promise<ActionResult<TData>> => {
+    return new Promise((resolve) => {
+      startTransition(async () => {
+        const result = await action(input);
+        resolve(result);
+      });
+    });
+  };
+
+  return [execute, isPending];
+}
+
+// ─── useFormErrors ──────────────────────────────────────────────────────
+
+/** Return type of useFormErrors(). */
+export interface FormErrorsResult {
+  /** Per-field validation errors keyed by field name. */
+  fieldErrors: Record<string, string[]>;
+  /** Form-level errors (from `_root` key). */
+  formErrors: string[];
+  /** Server error if the action threw an ActionError. */
+  serverError: { code: string; data?: Record<string, unknown> } | null;
+  /** Whether any errors are present. */
+  hasErrors: boolean;
+  /** Get the first error message for a field, or null. */
+  getFieldError: (field: string) => string | null;
+}
+
+/**
+ * Extract per-field and form-level errors from an ActionResult.
+ *
+ * Pure function (no internal hooks) — follows React naming convention
+ * since it's used in render. Accepts the result from `useActionState`
+ * or flash data from `getFormFlash()`.
+ *
+ * @example
+ * ```tsx
+ * const [result, action, isPending] = useActionState(createTodo, null)
+ * const errors = useFormErrors(result)
+ *
+ * return (
+ *   <form action={action}>
+ *     <input name="title" />
+ *     {errors.getFieldError('title') && <p>{errors.getFieldError('title')}</p>}
+ *     {errors.formErrors.map(e => <p key={e}>{e}</p>)}
+ *   </form>
+ * )
+ * ```
+ */
+export function useFormErrors<TData>(
+  result:
+    | ActionResult<TData>
+    | {
+        validationErrors?: ValidationErrors;
+        serverError?: { code: string; data?: Record<string, unknown> };
+      }
+    | null
+): FormErrorsResult {
+  const empty: FormErrorsResult = {
+    fieldErrors: {},
+    formErrors: [],
+    serverError: null,
+    hasErrors: false,
+    getFieldError: () => null,
+  };
+
+  if (!result) return empty;
+
+  const validationErrors = result.validationErrors as ValidationErrors | undefined;
+  const serverError = result.serverError as
+    | { code: string; data?: Record<string, unknown> }
+    | undefined;
+
+  if (!validationErrors && !serverError) return empty;
+
+  // Separate _root (form-level) errors from field errors
+  const fieldErrors: Record<string, string[]> = {};
+  const formErrors: string[] = [];
+
+  if (validationErrors) {
+    for (const [key, messages] of Object.entries(validationErrors)) {
+      if (key === '_root') {
+        formErrors.push(...messages);
+      } else {
+        fieldErrors[key] = messages;
+      }
+    }
+  }
+
+  const hasErrors =
+    Object.keys(fieldErrors).length > 0 || formErrors.length > 0 || serverError != null;
+
+  return {
+    fieldErrors,
+    formErrors,
+    serverError: serverError ?? null,
+    hasErrors,
+    getFieldError(field: string): string | null {
+      const errs = fieldErrors[field];
+      return errs && errs.length > 0 ? errs[0] : null;
+    },
+  };
+}

package/src/client/head.ts

@@ -0,0 +1,61 @@
+// Client-side head element updates for SPA navigation.
+//
+// On RSC payload responses, the server sends resolved HeadElement[] via the
+// X-Timber-Head response header. This module applies those elements to the
+// DOM so document.title and <meta> tags stay current after navigation.
+//
+// See design/16-metadata.md
+
+// ─── Types ───────────────────────────────────────────────────────
+
+/** Marker attribute for timber-managed head elements (cleanup on next navigation). */
+const TIMBER_ATTR = 'data-timber-head';
+
+/** A rendered head element descriptor (matches server-side HeadElement from metadata.ts). */
+export interface HeadElement {
+  tag: 'title' | 'meta' | 'link';
+  content?: string;
+  attrs?: Record<string, string>;
+}
+
+// ─── Apply Head Elements ─────────────────────────────────────────
+
+/**
+ * Apply resolved head elements to the DOM.
+ *
+ * - Sets document.title for <title> elements
+ * - Creates <meta> and <link> tags with a data-timber-head marker
+ * - Removes previous timber-managed tags to prevent accumulation
+ * - Replaces existing SSR-rendered tags with the same name/property
+ */
+export function applyHeadElements(elements: HeadElement[]): void {
+  // Remove previous timber-managed meta/link tags
+  document.head.querySelectorAll(`[${TIMBER_ATTR}]`).forEach((el) => el.remove());
+
+  for (const el of elements) {
+    if (el.tag === 'title' && el.content !== undefined) {
+      document.title = el.content;
+      continue;
+    }
+
+    if (!el.attrs) continue;
+
+    // For meta: remove existing tag with same name/property to avoid duplicates from SSR
+    if (el.tag === 'meta') {
+      const key = el.attrs.name || el.attrs.property;
+      if (key) {
+        const existing = document.head.querySelector(
+          `meta[name="${key}"], meta[property="${key}"]`
+        );
+        if (existing) existing.remove();
+      }
+    }
+
+    const node = document.createElement(el.tag);
+    node.setAttribute(TIMBER_ATTR, '');
+    for (const [k, v] of Object.entries(el.attrs)) {
+      node.setAttribute(k, v);
+    }
+    document.head.appendChild(node);
+  }
+}

package/src/client/history.ts

@@ -0,0 +1,46 @@
+// History Stack — stores RSC payloads by URL for instant back/forward navigation
+// See design/19-client-navigation.md § History Stack
+
+import type { HeadElement } from './head';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+export interface HistoryEntry {
+  /** The complete segment tree payload at the time of navigation */
+  payload: unknown;
+  /** Resolved head elements for this page (title, meta tags). Null for SSR'd initial page. */
+  headElements?: HeadElement[] | null;
+  /** Route params for this page (for useParams). Null for SSR'd initial page. */
+  params?: Record<string, string | string[]> | null;
+}
+
+// ─── History Stack ───────────────────────────────────────────────
+
+/**
+ * Session-lived history stack keyed by URL. Enables instant back/forward
+ * navigation without a server roundtrip.
+ *
+ * On forward navigation, the new page's payload is pushed onto the stack.
+ * On popstate, the cached payload is replayed instantly.
+ *
+ * Scroll positions are stored in history.state (browser History API),
+ * not in this stack — see design/19-client-navigation.md §Scroll Restoration.
+ *
+ * Entries persist for the session duration (no expiry) and are cleared
+ * when the tab is closed — matching browser back-button behavior.
+ */
+export class HistoryStack {
+  private entries = new Map<string, HistoryEntry>();
+
+  push(url: string, entry: HistoryEntry): void {
+    this.entries.set(url, entry);
+  }
+
+  get(url: string): HistoryEntry | undefined {
+    return this.entries.get(url);
+  }
+
+  has(url: string): boolean {
+    return this.entries.has(url);
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,60 @@
+// @timber/app/client — Client-side primitives
+// These are the primary imports for client components.
+
+export type { RenderErrorDigest } from './types';
+
+// Navigation
+export { Link, interpolateParams, resolveHref, validateLinkHref, buildLinkProps } from './link';
+export type { LinkProps, LinkPropsWithHref, LinkPropsWithParams } from './link';
+export type { OnNavigateHandler, OnNavigateEvent } from './link-navigate-interceptor';
+export { createRouter } from './router';
+export type {
+  RouterInstance,
+  NavigationOptions,
+  RouterDeps,
+  RscDecoder,
+  RootRenderer,
+} from './router';
+export { useNavigationPending } from './use-navigation-pending';
+export { useLinkStatus, LinkStatusContext } from './use-link-status';
+export type { LinkStatus } from './use-link-status';
+export { getRouter } from './router-ref';
+export { useRouter } from './use-router';
+export type { AppRouterInstance } from './use-router';
+export { usePathname } from './use-pathname';
+export { useSearchParams } from './use-search-params';
+export { useSelectedLayoutSegment, useSelectedLayoutSegments } from './use-selected-layout-segment';
+
+// Segment context (internal, used by rsc-entry to inject layout position)
+export { SegmentProvider, useSegmentContext } from './segment-context';
+export type { SegmentContextValue } from './segment-context';
+
+// Segment cache (internal, but exported for advanced use)
+export { SegmentCache, PrefetchCache } from './segment-cache';
+export type { SegmentNode, StateTree } from './segment-cache';
+
+// History (internal, but exported for advanced use)
+export { HistoryStack } from './history';
+export type { HistoryEntry } from './history';
+
+// Forms
+export { useActionState, useFormAction, useFormErrors } from './form';
+export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
+
+// Params
+export { useParams, setCurrentParams } from './use-params';
+
+// Query states (URL-synced search params)
+export { useQueryStates, bindUseQueryStates } from './use-query-states';
+
+// Cookies
+export { useCookie } from './use-cookie';
+export type { ClientCookieOptions, CookieSetter } from './use-cookie';
+
+// SSR data (framework-internal, used by ssr-entry to provide request data to hooks)
+export { setSsrData, clearSsrData, getSsrData } from './ssr-data';
+export type { SsrData } from './ssr-data';
+
+// Error boundary (framework-internal, used by tree-builder and rsc-entry)
+export { TimberErrorBoundary } from './error-boundary';
+export type { TimberErrorBoundaryProps } from './error-boundary';

package/src/client/link-navigate-interceptor.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+// LinkNavigateInterceptor — client component that stores an onNavigate callback
+// on the parent <a> element so the delegated click handler in browser-entry.ts
+// can invoke it before triggering SPA navigation.
+//
+// See design/19-client-navigation.md, TIM-167
+
+import { useRef, useEffect, type ReactNode } from 'react';
+
+/** Symbol used to store the onNavigate callback on anchor elements. */
+export const ON_NAVIGATE_KEY = '__timberOnNavigate' as const;
+
+export type OnNavigateEvent = {
+  preventDefault: () => void;
+};
+
+export type OnNavigateHandler = (e: OnNavigateEvent) => void;
+
+/**
+ * Augment HTMLAnchorElement with the optional onNavigate property.
+ * Used by browser-entry.ts handleLinkClick to check for the callback.
+ */
+declare global {
+  interface HTMLAnchorElement {
+    [ON_NAVIGATE_KEY]?: OnNavigateHandler;
+  }
+}
+
+/**
+ * Client component rendered inside <Link> that attaches the onNavigate
+ * callback to the closest <a> ancestor via a DOM property. The callback
+ * is cleaned up on unmount.
+ *
+ * Renders no extra DOM — just a transparent wrapper.
+ */
+export function LinkNavigateInterceptor({
+  onNavigate,
+  children,
+}: {
+  onNavigate: OnNavigateHandler;
+  children: ReactNode;
+}) {
+  const ref = useRef<HTMLSpanElement>(null);
+
+  useEffect(() => {
+    const anchor = ref.current?.closest('a');
+    if (!anchor) return;
+    anchor[ON_NAVIGATE_KEY] = onNavigate;
+    return () => {
+      delete anchor[ON_NAVIGATE_KEY];
+    };
+  }, [onNavigate]);
+
+  // Use a <span> with display:contents to avoid affecting layout.
+  // The ref lets us walk up to the parent <a> in the effect.
+  return (
+    <span ref={ref} style={{ display: 'contents' }}>
+      {children}
+    </span>
+  );
+}

package/src/client/link-status-provider.tsx

@@ -0,0 +1,40 @@
+'use client';
+
+// LinkStatusProvider — client component that provides per-link pending status
+// via React context. Used inside <Link> to power useLinkStatus().
+
+import { useSyncExternalStore, type ReactNode } from 'react';
+import { LinkStatusContext, type LinkStatus } from './use-link-status.js';
+import { getRouter } from './router-ref.js';
+
+const NOT_PENDING: LinkStatus = { pending: false };
+const IS_PENDING: LinkStatus = { pending: true };
+
+/**
+ * Client component that subscribes to the router's pending URL and provides
+ * a scoped LinkStatusContext to children. Renders no extra DOM — just a
+ * context provider around children.
+ */
+export function LinkStatusProvider({ href, children }: { href: string; children: ReactNode }) {
+  const status = useSyncExternalStore(
+    (callback) => {
+      try {
+        return getRouter().onPendingChange(callback);
+      } catch {
+        return () => {};
+      }
+    },
+    () => {
+      try {
+        const pendingUrl = getRouter().getPendingUrl();
+        if (pendingUrl === href) return IS_PENDING;
+        return NOT_PENDING;
+      } catch {
+        return NOT_PENDING;
+      }
+    },
+    () => NOT_PENDING
+  );
+
+  return <LinkStatusContext.Provider value={status}>{children}</LinkStatusContext.Provider>;
+}