@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.81

package/src/client/link.tsx

@@ -18,10 +18,45 @@
 // - params and fully-resolved string href are mutually exclusive
 // - searchParams and inline query string are mutually exclusive
 
-import type { AnchorHTMLAttributes, ReactNode, MouseEvent as ReactMouseEvent } from 'react';
-import type { SearchParamsDefinition } from '#/search-params/create.js';
-import { LinkStatusProvider } from './link-status-provider.js';
+import {
+  useOptimistic,
+  useEffect,
+  useRef,
+  type AnchorHTMLAttributes,
+  type JSX,
+  type ReactNode,
+  type MouseEvent as ReactMouseEvent,
+} from 'react';
+import type { SearchParamsDefinition } from '../search-params/define.js';
+import { classifyUrlSegment, type UrlSegment } from '../routing/segment-classify.js';
+import { LinkStatusContext } from './use-link-status.js';
 import { getRouterOrNull } from './router-ref.js';
+import { getSsrData } from './ssr-data.js';
+import { mergePreservedSearchParams } from '../shared/merge-search-params.js';
+import {
+  setLinkForCurrentNavigation,
+  unmountLinkForCurrentNavigation,
+  LINK_IDLE,
+  type LinkPendingInstance,
+} from './link-pending-store.js';
+import { setNavLinkMetadata } from './nav-link-store.js';
+import { hasNavigationApi } from './navigation-api.js';
+
+// ─── Current Search Params ────────────────────────────────────────
+
+/**
+ * Read the current URL's search string without requiring a React hook.
+ * On the client, reads window.location.search. During SSR, reads from
+ * the request context (getSsrData). Returns empty string if unavailable.
+ */
+function getCurrentSearch(): string {
+  if (typeof window !== 'undefined') return window.location.search;
+  const data = getSsrData();
+  if (!data) return '';
+  const sp = new URLSearchParams(data.searchParams);
+  const str = sp.toString();
+  return str ? `?${str}` : '';
+}
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -42,6 +77,20 @@ interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'h
    * Set to false for tabbed interfaces where content changes within a fixed layout.
    */
   scroll?: boolean;
+  /**
+   * Preserve search params from the current URL across navigation.
+   *
+   * - `true` — preserve ALL current search params (target params take precedence)
+   * - `string[]` — preserve only the named params (e.g. `['private', 'token']`)
+   *
+   * Useful for route-group gating where a search param (e.g. `?private=access`)
+   * must persist across internal navigations. The target href's own search params
+   * always take precedence over preserved ones.
+   *
+   * During SSR, reads search params from the request context. On the client,
+   * reads from the current URL and updates reactively when the URL changes.
+   */
+  preserveSearchParams?: true | string[];
   /**
    * Called before client-side navigation commits. Call `e.preventDefault()`
    * to cancel the default navigation — the caller is then responsible for
@@ -54,48 +103,107 @@ interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'h
   children?: ReactNode;
 }
 
+// ─── Typed Link Props ────────────────────────────────────────────
+
+/**
+ * Widen server-side string params to string | number for Link convenience.
+ * Exported for use by codegen-generated overloads.
+ */
+export type LinkSegmentParams<T> = {
+  [K in keyof T]: [string] extends [T[K]] ? string | number : T[K];
+};
+
+// ─── External Href Types ─────────────────────────────────────────
+
+/**
+ * Href types accepted by the catch-all (non-route) call signature.
+ *
+ * - External protocols: https://, http://, mailto:, tel:, ftp://
+ * - Hash-only and query-only links: #section, ?param=value
+ * - Computed `string` variables (non-literal)
+ *
+ * Internal path literals like "/typo-route" do NOT match — they must
+ * be a known route (from codegen) or stored in a `string` variable.
+ * This catches wrong hrefs at the type level. See TIM-624.
+ */
+type ExternalHref =
+  | `http://${string}`
+  | `https://${string}`
+  | `mailto:${string}`
+  | `tel:${string}`
+  | `ftp://${string}`
+  | `//${string}`
+  | `#${string}`
+  | `?${string}`;
+
+/**
+ * Callable interface for the Link component.
+ *
+ * Two kinds of call signatures:
+ * 1. Per-route (added by codegen via interface merging): DIRECT types
+ *    for segmentParams — preserves TypeScript excess property checking.
+ * 2. Catch-all (below): accepts external hrefs and computed `string`
+ *    variables. Does NOT accept internal path literals — those must
+ *    match a known route from the codegen.
+ *
+ * See TIM-624.
+ */
+export interface LinkFunction {
+  // External links (literal protocol hrefs)
+  (
+    props: LinkBaseProps & {
+      href: ExternalHref;
+      segmentParams?: never;
+      searchParams?: {
+        definition: SearchParamsDefinition<Record<string, unknown>>;
+        values: Record<string, unknown>;
+      };
+    }
+  ): JSX.Element;
+  // Computed/variable href (non-literal string) — e.g. href={myVar}
+  // `string extends H` is true only when H is the wide `string` type,
+  // not a specific literal. Template literal hrefs like `/blog/${slug}`
+  // are handled by resolved-pattern signatures in the codegen.
+  <H extends string>(
+    props: string extends H
+      ? LinkBaseProps & {
+          href: H;
+          segmentParams?: Record<string, string | number | string[]>;
+          searchParams?: {
+            definition: SearchParamsDefinition<Record<string, unknown>>;
+            values: Record<string, unknown>;
+          };
+        }
+      : never
+  ): JSX.Element;
+}
+
 /**
- * Link with a fully-resolved string href.
- * When using a string href with params already interpolated,
- * the params prop is not available.
+ * Runtime-only loose props used internally by the Link implementation.
+ * Not exposed to callers — the public API uses LinkFunction.
  */
-export interface LinkPropsWithHref extends LinkBaseProps {
+interface LinkRuntimeProps extends LinkBaseProps {
   href: string;
-  params?: never;
-  /**
-   * Typed search params — serialized via the route's SearchParamsDefinition.
-   * Mutually exclusive with an inline query string in href.
-   */
+  segmentParams?: Record<string, string | number | string[]>;
   searchParams?: {
     definition: SearchParamsDefinition<Record<string, unknown>>;
     values: Record<string, unknown>;
   };
 }
 
-/**
- * Link with a route pattern + params for interpolation.
- * e.g. <Link href="/products/[id]" params={{ id: "123" }}>
- *      <Link href="/products/[id]" params={{ id: 123 }}>
- */
-export interface LinkPropsWithParams extends LinkBaseProps {
-  /** Route pattern with dynamic segments (e.g. "/products/[id]") */
+// Legacy exports for backward compat (used by buildLinkProps, tests, etc.)
+export type LinkPropsWithHref = LinkBaseProps & {
   href: string;
-  /**
-   * Dynamic segment values to interpolate into the href.
-   * Single dynamic segments accept string | number (numbers are stringified).
-   * Catch-all segments accept string[].
-   */
-  params: Record<string, string | number | string[]>;
-  /**
-   * Typed search params — serialized via the route's SearchParamsDefinition.
-   */
+  segmentParams?: never;
   searchParams?: {
     definition: SearchParamsDefinition<Record<string, unknown>>;
     values: Record<string, unknown>;
   };
-}
-
-export type LinkProps = LinkPropsWithHref | LinkPropsWithParams;
+};
+export type LinkPropsWithParams = LinkRuntimeProps & {
+  segmentParams: Record<string, string | number | string[]>;
+};
+export type LinkProps = LinkRuntimeProps;
 
 // ─── Dangerous URL Scheme Detection ──────────────────────────────
 
@@ -141,57 +249,91 @@ export function isInternalHref(href: string): boolean {
  * - [...param]       → catch-all (joined with /)
  * - [[...param]]     → optional catch-all (omitted if undefined/empty)
  */
+/**
+ * Parse a route pattern's path portion into classified segments.
+ * Exported for testing. Uses the shared character-based classifier.
+ */
+export function parseSegments(pattern: string): UrlSegment[] {
+  return pattern.split('/').filter(Boolean).map(classifyUrlSegment);
+}
+
+/**
+ * Resolve a single classified segment into its string representation.
+ * Returns null for optional catch-all with no value (filtered out before join).
+ */
+function resolveSegment(
+  seg: UrlSegment,
+  params: Record<string, string | number | string[]>,
+  pattern: string
+): string | null {
+  switch (seg.kind) {
+    case 'static':
+      return seg.value;
+
+    case 'optional-catch-all': {
+      const value = params[seg.name];
+      if (value === undefined || (Array.isArray(value) && value.length === 0)) {
+        return null;
+      }
+      const segments = Array.isArray(value) ? value : [value];
+      return segments.map(encodeURIComponent).join('/');
+    }
+
+    case 'catch-all': {
+      const value = params[seg.name];
+      if (value === undefined) {
+        throw new Error(
+          `<Link> missing required catch-all param "${seg.name}" for pattern "${pattern}".`
+        );
+      }
+      const segments = Array.isArray(value) ? value : [value];
+      if (segments.length === 0) {
+        throw new Error(
+          `<Link> catch-all param "${seg.name}" must have at least one segment for pattern "${pattern}".`
+        );
+      }
+      return segments.map(encodeURIComponent).join('/');
+    }
+
+    case 'dynamic': {
+      const value = params[seg.name];
+      if (value === undefined) {
+        throw new Error(`<Link> missing required param "${seg.name}" for pattern "${pattern}".`);
+      }
+      if (Array.isArray(value)) {
+        throw new Error(
+          `<Link> param "${seg.name}" expected a string but received an array for pattern "${pattern}".`
+        );
+      }
+      return encodeURIComponent(String(value));
+    }
+  }
+}
+
+/**
+ * Split a URL pattern into the path portion and any trailing ?query/#hash suffix.
+ * Uses URL parsing for correctness rather than manual index arithmetic.
+ */
+function splitPatternSuffix(pattern: string): [path: string, suffix: string] {
+  if (!pattern.includes('?') && !pattern.includes('#')) {
+    return [pattern, ''];
+  }
+  const url = new URL(pattern, 'http://x');
+  const suffix = url.search + url.hash;
+  const path = pattern.slice(0, pattern.length - suffix.length);
+  return [path, suffix];
+}
+
 export function interpolateParams(
   pattern: string,
   params: Record<string, string | number | string[]>
 ): string {
-  return (
-    pattern
-      .replace(
-        /\[\[\.\.\.(\w+)\]\]|\[\.\.\.(\w+)\]|\[(\w+)\]/g,
-        (_match, optionalCatchAll, catchAll, single) => {
-          if (optionalCatchAll) {
-            const value = params[optionalCatchAll];
-            if (value === undefined || (Array.isArray(value) && value.length === 0)) {
-              return '';
-            }
-            const segments = Array.isArray(value) ? value : [value];
-            return segments.map(encodeURIComponent).join('/');
-          }
+  const [pathPart, suffix] = splitPatternSuffix(pattern);
 
-          if (catchAll) {
-            const value = params[catchAll];
-            if (value === undefined) {
-              throw new Error(
-                `<Link> missing required catch-all param "${catchAll}" for pattern "${pattern}".`
-              );
-            }
-            const segments = Array.isArray(value) ? value : [value];
-            if (segments.length === 0) {
-              throw new Error(
-                `<Link> catch-all param "${catchAll}" must have at least one segment for pattern "${pattern}".`
-              );
-            }
-            return segments.map(encodeURIComponent).join('/');
-          }
-
-          // single dynamic segment
-          const value = params[single];
-          if (value === undefined) {
-            throw new Error(`<Link> missing required param "${single}" for pattern "${pattern}".`);
-          }
-          if (Array.isArray(value)) {
-            throw new Error(
-              `<Link> param "${single}" expected a string but received an array for pattern "${pattern}".`
-            );
-          }
-          // Accept numbers — coerce to string for URL interpolation
-          return encodeURIComponent(String(value));
-        }
-      )
-      // Clean up trailing slash from empty optional catch-all
-      .replace(/\/+$/, '') || '/'
-  );
+  const resolved = parseSegments(pathPart)
+    .map((seg) => resolveSegment(seg, params, pattern))
+    .filter((s): s is string => s !== null);
+  return ('/' + resolved.join('/') || '/') + suffix;
 }
 
 // ─── Resolve Href ───────────────────────────────────────────────
@@ -302,23 +444,76 @@ function shouldInterceptClick(
  * navigation via the router. No global event delegation — each Link owns
  * its own click handling.
  *
- * Supports typed routes via codegen overloads. At runtime:
- * - `params` prop interpolates dynamic segments in the href pattern
+ * Supports typed routes via the Routes interface (populated by codegen).
+ * At runtime:
+ * - `segmentParams` prop interpolates dynamic segments in the href pattern
  * - `searchParams` prop serializes query parameters via a SearchParamsDefinition
+ *
+ * Typed via the LinkFunction callable interface. The base call signature
+ * forbids segmentParams; per-route signatures are added by codegen via
+ * interface merging. See TIM-624.
  */
-export function Link({
-  href,
-  prefetch,
-  scroll,
-  params,
-  searchParams,
-  onNavigate,
-  onClick: userOnClick,
-  onMouseEnter: userOnMouseEnter,
-  children,
-  ...rest
-}: LinkProps) {
-  const { href: resolvedHref } = buildLinkProps({ href, params, searchParams });
+// Cast to LinkFunction — the callable interface provides the public type,
+// but the implementation destructures LinkRuntimeProps internally.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const Link: LinkFunction = function LinkImpl(props: any) {
+  const {
+    href,
+    prefetch,
+    scroll,
+    segmentParams,
+    searchParams,
+    preserveSearchParams,
+    onNavigate,
+    onClick: userOnClick,
+    onMouseEnter: userOnMouseEnter,
+    children,
+    ...rest
+  } = props as LinkRuntimeProps;
+  const { href: baseHref } = buildLinkProps({ href, params: segmentParams, searchParams });
+
+  // ─── Per-link pending state (useOptimistic) ────────────────────────
+  // Each Link has its own pending state. Only the clicked link's
+  // setter is invoked during navigation — zero other links re-render.
+  //
+  // Link click stores the instance; NavigationRoot activates inside startTransition.
+  // useOptimistic auto-reverts to LINK_IDLE when the navigation
+  // startTransition — batched with the new tree commit.
+  //
+  // See design/19-client-navigation.md §"Per-Link Pending State"
+  const [linkStatus, setIsPending] = useOptimistic(LINK_IDLE);
+
+  // Build the link instance ref for the pending store.
+  // The ref is stable across renders — we update the setter on each
+  // render to keep it current.
+  const linkInstanceRef = useRef<LinkPendingInstance | null>(null);
+  if (!linkInstanceRef.current) {
+    linkInstanceRef.current = { setIsPending };
+  } else {
+    linkInstanceRef.current.setIsPending = setIsPending;
+  }
+
+  // Clean up if this link unmounts while it's the current navigation link.
+  // Prevents calling setOptimistic on an unmounted component.
+  useEffect(() => {
+    const instance = linkInstanceRef.current;
+    return () => {
+      if (instance) {
+        unmountLinkForCurrentNavigation(instance);
+      }
+    };
+  }, []);
+
+  // Preserve search params from the current URL when requested.
+  // useSearchParams() works during both SSR (reads from request context)
+  // and on the client (reads from window.location, reactive to URL changes).
+  // We read current search params directly to avoid unconditional hook calls.
+  // On the client, window.location.search is always current; during SSR,
+  // getSsrData() provides the request's search params.
+  const resolvedHref = preserveSearchParams
+    ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+    : baseHref;
+
   const internal = isInternalHref(resolvedHref);
 
   // ─── Click handler ───────────────────────────────────────────
@@ -349,9 +544,42 @@ export function Link({
         const router = getRouterOrNull();
         if (!router) return; // SSR or pre-hydration — fall through to browser nav
 
-        event.preventDefault();
         const shouldScroll = scroll !== false;
-        void router.navigate(resolvedHref, { scroll: shouldScroll });
+
+        // Register this link in the pending store. The actual
+        // setIsPending(LINK_PENDING) call happens inside NavigationRoot's
+        // async startTransition via activateLinkPending().
+
+        setLinkForCurrentNavigation(linkInstanceRef.current);
+
+        // When Navigation API is active, let the <a> click propagate
+        // naturally — do NOT call preventDefault(). The navigate event
+        // handler intercepts it and runs the RSC pipeline. This is a
+        // user-initiated navigation, so Chrome shows the native loading
+        // indicator (tab spinner). Metadata (scroll, link instance) is
+        // passed via nav-link-store so the handler can configure the nav.
+        //
+        // Without Navigation API (fallback), preventDefault and drive
+        // navigation through the router as before.
+        if (hasNavigationApi()) {
+          setNavLinkMetadata({
+            scroll: shouldScroll,
+            linkInstance: linkInstanceRef.current,
+          });
+          // Don't preventDefault — let the <a> click fire the navigate event
+          return;
+        }
+
+        // History API fallback — prevent default and navigate via router
+        event.preventDefault();
+
+        // Re-merge preserved search params at click time to pick up any
+        // URL changes since render (e.g. from other navigations or pushState).
+        const navHref = preserveSearchParams
+          ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+          : resolvedHref;
+
+        void router.navigate(navHref, { scroll: shouldScroll });
       }
     : userOnClick; // External links — just pass through user's onClick
 
@@ -362,14 +590,18 @@ export function Link({
           userOnMouseEnter?.(event);
           const router = getRouterOrNull();
           if (router) {
-            router.prefetch(resolvedHref);
+            // Re-merge preserved search params at hover time for fresh prefetch URL
+            const prefetchHref = preserveSearchParams
+              ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+              : resolvedHref;
+            router.prefetch(prefetchHref);
           }
         }
       : userOnMouseEnter;
 
   return (
     <a {...rest} href={resolvedHref} onClick={handleClick} onMouseEnter={handleMouseEnter}>
-      <LinkStatusProvider href={resolvedHref}>{children}</LinkStatusProvider>
+      <LinkStatusContext.Provider value={linkStatus}>{children}</LinkStatusContext.Provider>
     </a>
   );
-}
+};

package/src/client/nav-link-store.ts

@@ -0,0 +1,47 @@
+/**
+ * Navigation Link Store — passes per-link metadata from Link's onClick
+ * to the Navigation API's navigate event handler.
+ *
+ * When the Navigation API is active, Link does NOT call event.preventDefault()
+ * or router.navigate(). Instead it stores metadata (scroll option, link
+ * pending instance) here, and lets the <a> click propagate naturally.
+ * The navigate event handler reads this metadata to configure the RSC
+ * navigation with the correct options.
+ *
+ * This store is consumed once per navigation — after reading, the metadata
+ * is cleared. If no metadata is present (e.g., a plain <a> tag without
+ * our Link component), the navigate handler uses default options.
+ *
+ * See design/19-client-navigation.md §"Navigation API Integration"
+ */
+
+import type { LinkPendingInstance } from './link-pending-store.js';
+
+export interface NavLinkMetadata {
+  /** Whether to scroll to top after navigation. Default: true. */
+  scroll: boolean;
+  /** The Link's pending state instance for per-link status tracking. */
+  linkInstance: LinkPendingInstance | null;
+}
+
+let pendingMetadata: NavLinkMetadata | null = null;
+
+/**
+ * Store metadata from Link's onClick for the next navigate event.
+ * Called synchronously in the click handler — the navigate event
+ * fires synchronously after onClick returns.
+ */
+export function setNavLinkMetadata(metadata: NavLinkMetadata): void {
+  pendingMetadata = metadata;
+}
+
+/**
+ * Consume the stored metadata. Returns null if no Link onClick
+ * preceded this navigation (e.g., plain <a> tag, programmatic nav).
+ * Clears the store after reading.
+ */
+export function consumeNavLinkMetadata(): NavLinkMetadata | null {
+  const metadata = pendingMetadata;
+  pendingMetadata = null;
+  return metadata;
+}

package/src/client/navigation-api-types.ts

@@ -0,0 +1,112 @@
+/**
+ * Ambient type declarations for the Navigation API.
+ *
+ * The Navigation API is not yet in TypeScript's standard lib. These types
+ * are used internally via type assertions — we never import Navigation API
+ * types unconditionally. Progressive enhancement only: the API is feature-
+ * detected at runtime.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API
+ */
+
+// ─── Navigation Entry ────────────────────────────────────────────
+
+export interface NavigationHistoryEntry {
+  readonly key: string;
+  readonly id: string;
+  readonly url: string | null;
+  readonly index: number;
+  readonly sameDocument: boolean;
+  getState(): unknown;
+  addEventListener(type: string, listener: EventListener): void;
+  removeEventListener(type: string, listener: EventListener): void;
+}
+
+// ─── Navigation Destination ──────────────────────────────────────
+
+export interface NavigationDestination {
+  readonly url: string;
+  readonly key: string | null;
+  readonly id: string | null;
+  readonly index: number;
+  readonly sameDocument: boolean;
+  getState(): unknown;
+}
+
+// ─── Navigate Event ──────────────────────────────────────────────
+
+export interface NavigateEvent extends Event {
+  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
+  readonly destination: NavigationDestination;
+  readonly canIntercept: boolean;
+  readonly userInitiated: boolean;
+  readonly hashChange: boolean;
+  readonly signal: AbortSignal;
+  readonly formData: FormData | null;
+  readonly downloadRequest: string | null;
+  readonly info: unknown;
+  intercept(options?: NavigateInterceptOptions): void;
+  scroll(): void;
+}
+
+export interface NavigateInterceptOptions {
+  handler?: () => Promise<void>;
+  focusReset?: 'after-transition' | 'manual';
+  scroll?: 'after-transition' | 'manual';
+}
+
+// ─── Navigation Transition ───────────────────────────────────────
+
+export interface NavigationTransition {
+  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
+  readonly from: NavigationHistoryEntry;
+  readonly finished: Promise<void>;
+}
+
+// ─── Navigation Result ───────────────────────────────────────────
+
+export interface NavigationResult {
+  committed: Promise<NavigationHistoryEntry>;
+  finished: Promise<NavigationHistoryEntry>;
+}
+
+// ─── Navigation Interface ────────────────────────────────────────
+
+export interface NavigationApi {
+  readonly currentEntry: NavigationHistoryEntry | null;
+  readonly transition: NavigationTransition | null;
+  readonly canGoBack: boolean;
+  readonly canGoForward: boolean;
+  entries(): NavigationHistoryEntry[];
+  navigate(url: string, options?: NavigationNavigateOptions): NavigationResult;
+  reload(options?: NavigationReloadOptions): NavigationResult;
+  traverseTo(key: string, options?: NavigationOptions): NavigationResult;
+  back(options?: NavigationOptions): NavigationResult;
+  forward(options?: NavigationOptions): NavigationResult;
+  updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void;
+  addEventListener(type: 'navigate', listener: (event: NavigateEvent) => void): void;
+  addEventListener(type: 'navigatesuccess', listener: (event: Event) => void): void;
+  addEventListener(type: 'navigateerror', listener: (event: Event) => void): void;
+  addEventListener(type: 'currententrychange', listener: (event: Event) => void): void;
+  addEventListener(type: string, listener: EventListener): void;
+  removeEventListener(type: string, listener: EventListener): void;
+}
+
+export interface NavigationNavigateOptions {
+  state?: unknown;
+  history?: 'auto' | 'push' | 'replace';
+  info?: unknown;
+}
+
+export interface NavigationReloadOptions {
+  state?: unknown;
+  info?: unknown;
+}
+
+export interface NavigationOptions {
+  info?: unknown;
+}
+
+export interface NavigationUpdateCurrentEntryOptions {
+  state: unknown;
+}