@timber-js/app 0.2.0-alpha.1 → 0.2.0-alpha.100

package/src/client/browser-links.ts

@@ -1,90 +0,0 @@
-/**
- * Link click interception and hover prefetch for SPA navigation.
- *
- * Handles click events on <a data-timber-link> and mouseenter events
- * on <a data-timber-prefetch> for client-side navigation.
- *
- * Extracted from browser-entry.ts to keep files under 500 lines.
- *
- * See design/19-client-navigation.md
- */
-
-import type { RouterInstance } from '@timber-js/app/client';
-import { ON_NAVIGATE_KEY } from './link-navigate-interceptor.js';
-
-// ─── Link Click Interception ─────────────────────────────────────
-
-/**
- * Handle click events on timber links. Intercepts clicks on <a> elements
- * marked with data-timber-link and triggers SPA navigation instead of
- * a full page load.
- *
- * Passes through to default browser behavior when:
- * - Modified keys are held (Ctrl, Meta, Shift, Alt) — open in new tab
- * - The click is not the primary button
- * - The link has a target attribute (e.g., target="_blank")
- * - The link has a download attribute
- */
-export function handleLinkClick(event: MouseEvent, router: RouterInstance): void {
-  // Only intercept primary clicks without modifier keys
-  if (event.button !== 0) return;
-  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
-  if (event.defaultPrevented) return;
-
-  // Find the closest <a> ancestor with data-timber-link
-  const anchor = (event.target as Element).closest?.(
-    'a[data-timber-link]'
-  ) as HTMLAnchorElement | null;
-  if (!anchor) return;
-
-  // Don't intercept links that should open externally
-  if (anchor.target && anchor.target !== '_self') return;
-  if (anchor.hasAttribute('download')) return;
-
-  const href = anchor.getAttribute('href');
-  if (!href) return;
-
-  // Prevent default navigation
-  event.preventDefault();
-
-  // Call onNavigate if registered on this anchor (via LinkNavigateInterceptor).
-  // If the handler calls preventDefault(), skip the default SPA navigation —
-  // the caller is responsible for navigating (e.g. via router.push()).
-  const onNavigate = anchor[ON_NAVIGATE_KEY];
-  if (onNavigate) {
-    let prevented = false;
-    onNavigate({
-      preventDefault: () => {
-        prevented = true;
-      },
-    });
-    if (prevented) return;
-  }
-
-  // Check scroll preference from data attribute
-  const scroll = anchor.getAttribute('data-timber-scroll') !== 'false';
-
-  // Trigger SPA navigation
-  void router.navigate(href, { scroll });
-}
-
-// ─── Prefetch on Hover ───────────────────────────────────────────
-
-/**
- * Handle mouseenter events on prefetch-enabled links. When the user
- * hovers over <a data-timber-prefetch>, the RSC payload is fetched
- * and cached for near-instant navigation.
- *
- * See design/19-client-navigation.md §"Prefetch Cache"
- */
-export function handleLinkHover(event: MouseEvent, router: RouterInstance): void {
-  const anchor = (event.target as Element).closest?.(
-    'a[data-timber-prefetch]'
-  ) as HTMLAnchorElement | null;
-  if (!anchor) return;
-
-  const href = anchor.getAttribute('href');
-  if (!href) return;
-
-  router.prefetch(href);
-}

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

@@ -1,62 +0,0 @@
-'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

@@ -1,30 +0,0 @@
-'use client';
-
-// LinkStatusProvider — client component that provides per-link pending status
-// via React context. Used inside <Link> to power useLinkStatus().
-//
-// Reads pendingUrl from PendingNavigationContext (provided by TransitionRoot).
-// The pending URL is set as an URGENT update at navigation start (shows
-// immediately) and cleared inside startTransition when the new tree commits
-// (atomic with params/pathname). This eliminates both:
-// 1. The delay before showing the spinner (urgent update, not deferred)
-// 2. The gap between spinner disappearing and active state updating (same commit)
-
-import type { ReactNode } from 'react';
-import { LinkStatusContext, type LinkStatus } from './use-link-status.js';
-import { usePendingNavigationUrl } from './navigation-context.js';
-
-const NOT_PENDING: LinkStatus = { pending: false };
-const IS_PENDING: LinkStatus = { pending: true };
-
-/**
- * Client component that reads the pending URL from PendingNavigationContext
- * 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 pendingUrl = usePendingNavigationUrl();
-  const status = pendingUrl === href ? IS_PENDING : NOT_PENDING;
-
-  return <LinkStatusContext.Provider value={status}>{children}</LinkStatusContext.Provider>;
-}

package/src/client/transition-root.tsx

@@ -1,160 +0,0 @@
-/**
- * TransitionRoot — Wrapper component for transition-based rendering.
- *
- * Solves the "new boundary has no old content" problem for client-side
- * navigation. When React renders a completely new Suspense boundary via
- * root.render(), it shows the fallback immediately — root.render() is
- * always an urgent update regardless of startTransition.
- *
- * TransitionRoot holds the current element in React state. Navigation
- * updates call startTransition(() => setState(newElement)), which IS
- * a transition update. React keeps the old committed tree visible while
- * any new Suspense boundaries in the transition resolve.
- *
- * Also manages `pendingUrl` as React state with an urgent/transition split:
- * - Navigation START: `setPendingUrl(url)` is an urgent update — React
- *   commits it before the next paint, showing the spinner immediately.
- * - Navigation END: `setPendingUrl(null)` is inside `startTransition`
- *   alongside `setElement(newTree)` — both commit atomically, so the
- *   spinner disappears in the same frame as the new content appears.
- *
- * See design/05-streaming.md §"deferSuspenseFor"
- * See design/19-client-navigation.md §"NavigationContext"
- */
-
-import { useState, useTransition, createElement, Fragment, type ReactNode } from 'react';
-import { PendingNavigationProvider } from './navigation-context.js';
-import { TopLoader, type TopLoaderConfig } from './top-loader.js';
-
-// ─── Module-level functions ──────────────────────────────────────
-
-/**
- * Module-level reference to the state setter wrapped in startTransition.
- * Used for non-navigation renders (applyRevalidation, popstate replay).
- */
-let _transitionRender: ((element: ReactNode) => void) | null = null;
-
-/**
- * Module-level reference to the navigation transition function.
- * Wraps a full navigation (fetch + render) in a single startTransition
- * with useOptimistic for the pending URL.
- */
-let _navigateTransition:
-  | ((pendingUrl: string, perform: () => Promise<ReactNode>) => Promise<void>)
-  | null = null;
-
-// ─── Component ───────────────────────────────────────────────────
-
-/**
- * Root wrapper component that enables transition-based rendering.
- *
- * Renders PendingNavigationProvider around children for the pending URL
- * context. The DOM tree matches the server-rendered HTML during hydration
- * (the provider renders no extra DOM elements).
- *
- * Usage in browser-entry.ts:
- *   const rootEl = createElement(TransitionRoot, { initial: wrapped });
- *   reactRoot = hydrateRoot(document, rootEl);
- *
- * Subsequent navigations:
- *   navigateTransition(url, async () => { fetch; return wrappedElement; });
- *
- * Non-navigation renders:
- *   transitionRender(newWrappedElement);
- */
-export function TransitionRoot({ initial, topLoaderConfig }: { initial: ReactNode; topLoaderConfig?: TopLoaderConfig }): ReactNode {
-  const [element, setElement] = useState<ReactNode>(initial);
-  const [pendingUrl, setPendingUrl] = useState<string | null>(null);
-  const [, startTransition] = useTransition();
-
-  // Non-navigation render (revalidation, popstate cached replay).
-  _transitionRender = (newElement: ReactNode) => {
-    startTransition(() => {
-      setElement(newElement);
-    });
-  };
-
-  // Full navigation transition.
-  // setPendingUrl(url) is an URGENT update — React commits it before the next
-  // paint, so the pending spinner appears immediately when navigation starts.
-  // Inside startTransition: the async fetch + setElement + setPendingUrl(null)
-  // are deferred. When the transition commits, the new tree and pendingUrl=null
-  // both apply in the same React commit — making the pending→active transition
-  // atomic (no frame where pending is false but the old tree is still visible).
-  _navigateTransition = (url: string, perform: () => Promise<ReactNode>) => {
-    // Urgent: show pending state immediately
-    setPendingUrl(url);
-
-    return new Promise<void>((resolve, reject) => {
-      startTransition(async () => {
-        try {
-          const newElement = await perform();
-          setElement(newElement);
-          // Clear pending inside the transition — commits atomically with new tree
-          setPendingUrl(null);
-          resolve();
-        } catch (err) {
-          // Clear pending on error too
-          setPendingUrl(null);
-          reject(err);
-        }
-      });
-    });
-  };
-
-  // Inject TopLoader alongside the element tree inside PendingNavigationProvider.
-  // The TopLoader reads pendingUrl from context to show/hide the progress bar.
-  // It is rendered only when not explicitly disabled via config.
-  const showTopLoader = topLoaderConfig?.enabled !== false;
-  const children = showTopLoader
-    ? createElement(Fragment, null, createElement(TopLoader, { config: topLoaderConfig }), element)
-    : element;
-  return createElement(PendingNavigationProvider, { value: pendingUrl }, children);
-}
-
-// ─── Public API ──────────────────────────────────────────────────
-
-/**
- * Trigger a transition render for non-navigation updates.
- * React keeps the old committed tree visible while any new Suspense
- * boundaries in the update resolve.
- *
- * Used for: applyRevalidation, popstate replay with cached payload.
- */
-export function transitionRender(element: ReactNode): void {
-  if (_transitionRender) {
-    _transitionRender(element);
-  }
-}
-
-/**
- * Run a full navigation inside a React transition with optimistic pending URL.
- *
- * The `perform` callback runs inside `startTransition` — it should fetch the
- * RSC payload, update router state, and return the wrapped React element.
- * The pending URL shows immediately (useOptimistic urgent update) and reverts
- * to null when the transition commits (atomic with the new tree).
- *
- * Returns a Promise that resolves when the async work completes (note: the
- * React transition may not have committed yet, but all state updates are done).
- *
- * Used for: navigate(), refresh(), popstate with fetch.
- */
-export function navigateTransition(
-  pendingUrl: string,
-  perform: () => Promise<ReactNode>
-): Promise<void> {
-  if (_navigateTransition) {
-    return _navigateTransition(pendingUrl, perform);
-  }
-  // Fallback: no TransitionRoot mounted (shouldn't happen in production)
-  return perform().then(() => {});
-}
-
-/**
- * Check if the TransitionRoot is mounted and ready for renders.
- * Used by browser-entry.ts to guard against renders before hydration.
- */
-export function isTransitionRootReady(): boolean {
-  return _transitionRender !== null;
-}

package/src/plugins/cache-transform.ts

@@ -1,199 +0,0 @@
-import type { Plugin } from 'vite';
-import { findFunctionsWithDirective, containsDirective } from '#/utils/directive-parser.js';
-
-/**
- * Parse a cacheLife duration string to seconds.
- * Supports: '30s', '5m', '1h', '2d', '1w', or a plain number (seconds).
- */
-export function parseCacheLife(value: string | number): number {
-  if (typeof value === 'number') return value;
-
-  const match = value.match(/^(\d+)(s|m|h|d|w)$/);
-  if (!match) {
-    throw new Error(
-      `Invalid cacheLife value: "${value}". Expected format: "30s", "5m", "1h", "2d", "1w", or a number.`
-    );
-  }
-
-  const amount = parseInt(match[1], 10);
-  const unit = match[2];
-  const multipliers: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400, w: 604800 };
-  return amount * multipliers[unit];
-}
-
-// Default TTL when no cacheLife() is specified (Infinity means cache until explicit invalidation).
-const DEFAULT_TTL = Infinity;
-
-export interface CacheTransformWarning {
-  message: string;
-  functionName: string;
-}
-
-interface TransformResult {
-  code: string;
-  map?: null;
-  warnings?: CacheTransformWarning[];
-}
-
-/**
- * Match cacheLife() calls: cacheLife('1h'), cacheLife("5m"), cacheLife(300)
- */
-const CACHE_LIFE_PATTERN = /cacheLife\(\s*(?:'([^']+)'|"([^"]+)"|(\d+))\s*\)/;
-
-/**
- * Strip the 'use cache' directive and cacheLife() call from a function body.
- * Returns the cleaned body and the extracted TTL.
- */
-function extractCacheDirectives(body: string): { cleanBody: string; ttl: number } {
-  let ttl = DEFAULT_TTL;
-
-  // Remove 'use cache' / "use cache" directive (including optional semicolon and newline)
-  let cleanBody = body.replace(/\s*['"]use cache['"];?\s*\n?/, '\n');
-
-  // Extract and remove cacheLife() calls
-  const lifeMatch = cleanBody.match(CACHE_LIFE_PATTERN);
-  if (lifeMatch) {
-    const value = lifeMatch[1] || lifeMatch[2] || parseInt(lifeMatch[3], 10);
-    ttl = parseCacheLife(value);
-    cleanBody = cleanBody.replace(/\s*cacheLife\([^)]*\);?\s*\n?/, '\n');
-  }
-
-  return { cleanBody, ttl };
-}
-
-/**
- * Determine if a function name is a React component (PascalCase).
- */
-function isComponentName(name: string): boolean {
-  return /^[A-Z]/.test(name);
-}
-
-/**
- * Pattern matching page/layout file conventions in a dynamic route segment.
- * Matches paths like: app/[slug]/page.tsx, app/[id]/layout.ts, etc.
- */
-const DYNAMIC_ROUTE_PAGE_PATTERN = /\/\[[^\]]+\].*\/(page|layout)\.[jt]sx?$/;
-
-/**
- * Detect if a function declaration has Promise-typed parameters.
- *
- * Checks for common patterns:
- * - `params: Promise<...>`
- * - `{ params }: { params: Promise<...> }`
- * - `props: { params: Promise<...> }`
- */
-const PROMISE_PARAMS_PATTERN = /params\s*(?::|.*?:)\s*Promise\s*</;
-
-/**
- * Check if a 'use cache' function in a dynamic route page/layout receives
- * Promise-typed params, which are not serializable as cache keys.
- */
-export function detectPromiseParamsWarning(
-  declaration: string,
-  functionName: string,
-  fileId: string
-): CacheTransformWarning | null {
-  if (!DYNAMIC_ROUTE_PAGE_PATTERN.test(fileId)) return null;
-  if (!PROMISE_PARAMS_PATTERN.test(declaration)) return null;
-
-  return {
-    message:
-      `'use cache' on "${functionName}" in "${fileId}" receives Promise params. ` +
-      `Promise is not serializable as a cache key and will cause runtime errors. ` +
-      `Either remove 'use cache' or await the params before using them in a separate cached function.`,
-    functionName,
-  };
-}
-
-/**
- * Transform source code containing 'use cache' directives into
- * registerCachedFunction() calls.
- *
- * Returns null if no transformations were made.
- */
-export function transformUseCache(code: string, fileId: string): TransformResult | null {
-  if (!containsDirective(code, 'use cache')) return null;
-
-  const functions = findFunctionsWithDirective(code, 'use cache');
-  if (functions.length === 0) return null;
-
-  let result = code;
-  let needsImport = false;
-  const warnings: CacheTransformWarning[] = [];
-
-  // Process functions from end to start (sorted descending by start position)
-  for (const fn of functions) {
-    // Warn if function receives Promise params in a dynamic route page/layout
-    const promiseWarning = detectPromiseParamsWarning(fn.declaration, fn.name, fileId);
-    if (promiseWarning) warnings.push(promiseWarning);
-    const { cleanBody, ttl } = extractCacheDirectives(fn.bodyContent);
-    const stableId = `${fileId}#${fn.name}`;
-    const isComponent = isComponentName(fn.name);
-
-    // Build the options object
-    const optsParts = [`ttl: ${ttl === Infinity ? 'Infinity' : ttl}`];
-    optsParts.push(`id: '${stableId}'`);
-    if (isComponent) {
-      optsParts.push('isComponent: true');
-    }
-    const optsStr = `{ ${optsParts.join(', ')} }`;
-
-    // Build the replacement
-    let replacement: string;
-    if (fn.isArrow) {
-      // const Name = async (...) => { body } → const Name = registerCachedFunction(async (...) => { body }, opts)
-      const arrowSig = fn.declaration.replace(/^(?:const|let|var)\s+\w+\s*=\s*/, '');
-      replacement = `const ${fn.name} = registerCachedFunction(${arrowSig} {${cleanBody}}, ${optsStr})`;
-    } else {
-      // async function Name(...) { body } → const Name = registerCachedFunction(async function Name(...) { body }, opts)
-      const fnDecl = fn.declaration.replace(/^(?:export\s+default\s+|export\s+)?/, '');
-      const exportPrefix = fn.prefix.includes('default')
-        ? 'export default '
-        : fn.prefix.includes('export')
-          ? 'export '
-          : '';
-
-      replacement = `${exportPrefix}const ${fn.name} = registerCachedFunction(${fnDecl} {${cleanBody}}, ${optsStr})`;
-    }
-
-    result = result.slice(0, fn.start) + replacement + result.slice(fn.end);
-    needsImport = true;
-  }
-
-  if (needsImport) {
-    // Add the import at the top of the file
-    result = `import { registerCachedFunction } from '@timber-js/app/cache';\n` + result;
-  }
-
-  return { code: result, map: null, warnings: warnings.length > 0 ? warnings : undefined };
-}
-
-/**
- * Vite plugin: timber-cache
- *
- * Transforms 'use cache' directives into registerCachedFunction() calls.
- * Only runs in the RSC environment.
- */
-export function cacheTransformPlugin(): Plugin {
-  return {
-    name: 'timber-cache',
-
-    transform(code, id) {
-      // Only transform in RSC environment
-      // Skip node_modules and non-JS/TS files
-      if (id.includes('node_modules')) return null;
-      if (!/\.[jt]sx?$/.test(id)) return null;
-
-      // Quick bail-out: no 'use cache' directive in this file
-      if (!containsDirective(code, 'use cache')) return null;
-
-      const result = transformUseCache(code, id);
-      if (result?.warnings) {
-        for (const w of result.warnings) {
-          this.warn(`[timber] ${w.message}`);
-        }
-      }
-      return result;
-    },
-  };
-}