@timber-js/app 0.1.1 → 0.1.3

package/src/server/types.ts

@@ -0,0 +1,150 @@
+// Server-side type definitions
+
+import type { EarlyHint } from './early-hints.js';
+
+export interface MiddlewareContext {
+  req: Request;
+  requestHeaders: Headers;
+  headers: Headers;
+  params: Record<string, string | string[]>;
+  searchParams: unknown;
+  /** Declare early hints for critical resources. Appends Link headers. */
+  earlyHints: (hints: EarlyHint[]) => void;
+}
+
+export interface RouteContext {
+  req: Request;
+  params: Record<string, string | string[]>;
+  searchParams: URLSearchParams;
+  headers: Headers;
+}
+
+export interface AccessContext {
+  params: Record<string, string | string[]>;
+  searchParams: unknown;
+}
+
+export interface Metadata {
+  title?: string | { default?: string; template?: string; absolute?: string };
+  description?: string;
+  generator?: string;
+  applicationName?: string;
+  authors?: Array<{ name?: string; url?: string }> | { name?: string; url?: string };
+  creator?: string;
+  publisher?: string;
+  robots?:
+    | string
+    | {
+        index?: boolean;
+        follow?: boolean;
+        googleBot?: string | { index?: boolean; follow?: boolean; [key: string]: unknown };
+        [key: string]: unknown;
+      };
+  referrer?: string;
+  keywords?: string | string[];
+  category?: string;
+  openGraph?: {
+    title?: string;
+    description?: string;
+    url?: string;
+    siteName?: string;
+    images?:
+      | string
+      | { url: string; width?: number; height?: number; alt?: string }
+      | Array<{ url: string; width?: number; height?: number; alt?: string }>;
+    videos?: Array<{ url: string; width?: number; height?: number }>;
+    audio?: Array<{ url: string }>;
+    locale?: string;
+    type?: string;
+    publishedTime?: string;
+    modifiedTime?: string;
+    authors?: string[];
+  };
+  twitter?: {
+    card?: string;
+    site?: string;
+    siteId?: string;
+    title?: string;
+    description?: string;
+    images?:
+      | string
+      | string[]
+      | { url: string; alt?: string; width?: number; height?: number }
+      | Array<{ url: string; alt?: string; width?: number; height?: number }>;
+    creator?: string;
+    creatorId?: string;
+    /** Player card fields — embedded media player. Requires card: 'player'. */
+    players?: Array<{
+      playerUrl: string;
+      streamUrl?: string;
+      width?: number;
+      height?: number;
+    }>;
+    /** App card fields — link to a native app. Requires card: 'app'. */
+    app?: {
+      name?: string;
+      id?: { iPhone?: string; iPad?: string; googlePlay?: string };
+      url?: { iPhone?: string; iPad?: string; googlePlay?: string };
+    };
+  };
+  icons?: {
+    icon?: string | Array<{ url: string; sizes?: string; type?: string; media?: string }>;
+    shortcut?: string | string[];
+    apple?: string | Array<{ url: string; sizes?: string; type?: string }>;
+    other?: Array<{ rel: string; url: string; sizes?: string; type?: string }>;
+  };
+  manifest?: string;
+  alternates?: {
+    canonical?: string;
+    languages?: Record<string, string>;
+    media?: Record<string, string>;
+    types?: Record<string, string>;
+  };
+  verification?: {
+    google?: string;
+    yahoo?: string;
+    yandex?: string;
+    other?: Record<string, string | string[]>;
+  };
+  metadataBase?: URL | null;
+  appleWebApp?: {
+    capable?: boolean;
+    title?: string;
+    statusBarStyle?: string;
+    startupImage?: string | Array<{ url: string; media?: string }>;
+  };
+  formatDetection?: { email?: boolean; address?: boolean; telephone?: boolean };
+  /** App Links — deep linking to native apps (al:* meta property tags). */
+  appLinks?: {
+    ios?: Array<{ url: string; app_store_id?: string; app_name?: string }>;
+    android?: Array<{ url: string; package?: string; class?: string; app_name?: string }>;
+    windows?: Array<{ url: string; app_id?: string; app_name?: string }>;
+    windowsPhone?: Array<{ url: string; app_id?: string; app_name?: string }>;
+    windowsUniversal?: Array<{ url: string; app_id?: string; app_name?: string }>;
+    web?: { url?: string; shouldFallback?: boolean };
+  };
+  /** apple-itunes-app meta tag — link to an iOS app in the App Store. */
+  itunes?: { appId: string; appArgument?: string; affiliateData?: string };
+  other?: Record<string, string | string[]>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace MetadataRoute {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  export interface Sitemap extends Array<SitemapEntry> {}
+  export interface SitemapEntry {
+    url: string;
+    lastModified?: Date | string;
+    changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    priority?: number;
+  }
+  export interface Robots {
+    rules: Array<{
+      userAgent?: string | string[];
+      allow?: string | string[];
+      disallow?: string | string[];
+    }>;
+    sitemap?: string | string[];
+    host?: string;
+  }
+}

package/src/shims/font-google.ts

@@ -0,0 +1,67 @@
+/**
+ * Fallback shim for `next/font/google` → `@timber/fonts/google`.
+ *
+ * At build time, the timber-fonts plugin's transform hook replaces font
+ * function calls with static FontResult objects containing real class names
+ * and font stacks. This file serves two purposes:
+ *
+ * 1. **TypeScript resolution** — provides types for IDEs and `tsc` outside
+ *    of Vite's module graph (where the virtual module handles it).
+ * 2. **Runtime fallback** — returns empty className/fontFamily values when
+ *    the plugin hasn't processed a call (e.g. in tests or non-Vite environments).
+ *
+ * The shim resolution path (`next/font/google` → `\0@timber/fonts/google`)
+ * is unchanged — this file is NOT on that resolution path. It exists as a
+ * physical module for direct imports and type re-exports.
+ *
+ * Design doc: 24-fonts.md, "Next.js Font Compatibility"
+ */
+
+import type { GoogleFontConfig, FontResult } from '#/fonts/types.js';
+
+export type { GoogleFontConfig, FontResult };
+
+/**
+ * Create a stub FontResult with empty values.
+ *
+ * The timber-fonts plugin replaces these calls at build time with real
+ * class names and font stacks. This stub ensures code that imports
+ * font functions outside of the build pipeline (tests, type-checking)
+ * gets a valid FontResult shape without runtime errors.
+ */
+function createStubFontResult(config?: GoogleFontConfig): FontResult {
+  return {
+    className: '',
+    style: { fontFamily: '' },
+    variable: config?.variable,
+  };
+}
+
+/**
+ * Generic font loader — accepts any font name, returns a stub FontResult.
+ *
+ * Named exports like `Inter`, `Roboto`, etc. are generated dynamically
+ * by the virtual module at build time. This function provides a catch-all
+ * for non-Vite contexts.
+ */
+export function createFont(_family: string, config?: GoogleFontConfig): FontResult {
+  return createStubFontResult(config);
+}
+
+// Common Google Font exports for TypeScript autocomplete.
+// These are stubs — the virtual module and transform hook provide real values.
+export const Inter = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);
+export const Roboto = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);
+export const Open_Sans = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);
+export const Lato = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);
+export const Montserrat = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);
+export const Poppins = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);
+export const Geist = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);
+export const Geist_Mono = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);
+export const JetBrains_Mono = (config?: GoogleFontConfig): FontResult =>
+  createStubFontResult(config);
+export const Source_Code_Pro = (config?: GoogleFontConfig): FontResult =>
+  createStubFontResult(config);
+export const Playfair_Display = (config?: GoogleFontConfig): FontResult =>
+  createStubFontResult(config);
+export const Merriweather = (config?: GoogleFontConfig): FontResult => createStubFontResult(config);

package/src/shims/headers.ts

@@ -0,0 +1,11 @@
+/**
+ * Shim: next/headers → timber request context
+ *
+ * Re-exports timber's ALS-backed headers() and cookies() for libraries
+ * that import from next/headers. These are real implementations backed
+ * by AsyncLocalStorage, not stubs.
+ *
+ * See design/14-ecosystem.md §"next/headers" for the full shim audit.
+ */
+
+export { headers, cookies } from '#/server/request-context.js';

package/src/shims/image.ts

@@ -0,0 +1,48 @@
+/**
+ * Shim: next/image → stub
+ *
+ * timber.js does not implement an image optimization pipeline.
+ * This shim exports a pass-through <img> component so libraries
+ * that import next/image still render correctly.
+ */
+
+import { createElement } from 'react';
+import type { ImgHTMLAttributes } from 'react';
+
+export type ImageProps = ImgHTMLAttributes<HTMLImageElement> & {
+  /** next/image width — passed through as the HTML attribute */
+  width?: number | string;
+  /** next/image height — passed through as the HTML attribute */
+  height?: number | string;
+  /** next/image priority — ignored (no optimization pipeline) */
+  priority?: boolean;
+  /** next/image quality — ignored */
+  quality?: number;
+  /** next/image fill — ignored */
+  fill?: boolean;
+  /** next/image sizes — passed through */
+  sizes?: string;
+  /** next/image placeholder — ignored */
+  placeholder?: 'blur' | 'empty';
+  /** next/image blurDataURL — ignored */
+  blurDataURL?: string;
+};
+
+/**
+ * Pass-through image component.
+ *
+ * Renders a plain <img> tag, ignoring next/image-specific optimization
+ * props (priority, quality, fill, placeholder, blurDataURL).
+ */
+export function Image({
+  priority: _priority,
+  quality: _quality,
+  fill: _fill,
+  placeholder: _placeholder,
+  blurDataURL: _blurDataURL,
+  ...rest
+}: ImageProps) {
+  return createElement('img', rest);
+}
+
+export default Image;

package/src/shims/link.ts

@@ -0,0 +1,9 @@
+/**
+ * Shim: next/link → @timber/app/client Link
+ *
+ * Re-exports timber's Link component so libraries that import next/link
+ * get the timber equivalent without modification.
+ */
+
+export { Link as default, Link } from '#/client/link.js';
+export type { LinkProps } from '#/client/link.js';

package/src/shims/navigation-client.ts

@@ -0,0 +1,52 @@
+/**
+ * Shim: next/navigation (client environment only)
+ *
+ * Re-exports only the client-side hooks from timber's navigation shims.
+ * Server-only functions (redirect, notFound, etc.) are excluded to prevent
+ * server/primitives.ts from being pulled into the browser bundle.
+ *
+ * The full shim (navigation.ts) is still used in the RSC and SSR environments
+ * where both client hooks and server functions are needed.
+ *
+ * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
+ */
+
+// Hooks (client-side only)
+export { useParams } from '#/client/use-params.js';
+export { usePathname } from '#/client/use-pathname.js';
+export { useSearchParams } from '#/client/use-search-params.js';
+export { useRouter } from '#/client/use-router.js';
+export {
+  useSelectedLayoutSegment,
+  useSelectedLayoutSegments,
+} from '#/client/use-selected-layout-segment.js';
+
+// RedirectType enum is safe (no server code dependency) and used by some
+// client-side libraries for type checking.
+export const RedirectType = {
+  push: 'push',
+  replace: 'replace',
+} as const;
+
+// Server-only stubs — throw at runtime if called from the client.
+// These exist for type compatibility with libraries that import the types
+// but should never execute in the browser.
+export function redirect(): never {
+  throw new Error(
+    'redirect() is a server-only function and cannot be called from client components. ' +
+      'Use useRouter().push() or useRouter().replace() for client-side navigation.'
+  );
+}
+
+export function permanentRedirect(): never {
+  throw new Error(
+    'permanentRedirect() is a server-only function and cannot be called from client components. ' +
+      'Use useRouter().push() or useRouter().replace() for client-side navigation.'
+  );
+}
+
+export function notFound(): never {
+  throw new Error(
+    'notFound() is a server-only function and cannot be called from client components.'
+  );
+}

package/src/shims/navigation.ts

@@ -0,0 +1,31 @@
+/**
+ * Shim: next/navigation → timber navigation primitives
+ *
+ * Re-exports timber's navigation hooks and functions for libraries
+ * that import from next/navigation. Covers the App Router API surface
+ * used by ecosystem libraries (nuqs, next-intl, etc.).
+ *
+ * Note: nuqs imports next/navigation.js (with .js extension).
+ * The timber-shims plugin strips .js before matching.
+ *
+ * Intentional divergences from Next.js:
+ * - useRouter().replace() currently uses pushState (same as push) —
+ *   timber's router doesn't distinguish push/replace yet.
+ * - redirect() does not accept a RedirectType argument — timber
+ *   always uses replace semantics for redirects.
+ * - permanentRedirect() delegates to redirect(path, 308).
+ * See design/14-ecosystem.md for the full shim audit.
+ */
+
+// Hooks (client-side)
+export { useParams } from '#/client/use-params.js';
+export { usePathname } from '#/client/use-pathname.js';
+export { useSearchParams } from '#/client/use-search-params.js';
+export { useRouter } from '#/client/use-router.js';
+export {
+  useSelectedLayoutSegment,
+  useSelectedLayoutSegments,
+} from '#/client/use-selected-layout-segment.js';
+
+// Functions (server-side)
+export { redirect, permanentRedirect, notFound, RedirectType } from '#/server/primitives.js';

package/src/shims/server-only-noop.js

@@ -0,0 +1,5 @@
+// No-op shim for server-only/client-only packages.
+// In dev mode, Vite externalizes node_modules and loads them via Node's
+// require(). Deps like `bright` that import `server-only` would hit the
+// real CJS package which throws. This shim replaces it with a no-op
+// in server environments (RSC/SSR) where the import is always safe.