@timber-js/app 0.1.1 → 0.1.3

package/src/client/use-pathname.ts

@@ -0,0 +1,43 @@
+/**
+ * usePathname() — client-side hook for reading the current pathname.
+ *
+ * Returns the pathname portion of the current URL (e.g. '/dashboard/settings').
+ * Updates when client-side navigation changes the URL.
+ *
+ * This is a thin wrapper over window.location.pathname, provided for
+ * Next.js API compatibility (libraries like nuqs import usePathname
+ * from next/navigation).
+ *
+ * During SSR, reads the request pathname from the SSR ALS context
+ * (populated by ssr-entry.ts) instead of window.location.
+ */
+
+import { useSyncExternalStore } from 'react';
+import { getSsrData } from './ssr-data.js';
+
+function getPathname(): string {
+  if (typeof window !== 'undefined') return window.location.pathname;
+  return getSsrData()?.pathname ?? '/';
+}
+
+function getServerPathname(): string {
+  return getSsrData()?.pathname ?? '/';
+}
+
+function subscribe(callback: () => void): () => void {
+  // Listen for popstate (back/forward) and timber's custom navigation events.
+  // pushState/replaceState don't fire popstate, but timber's router calls
+  // onPendingChange listeners after navigation — components re-render
+  // naturally via React's tree update from the new RSC payload.
+  window.addEventListener('popstate', callback);
+  return () => window.removeEventListener('popstate', callback);
+}
+
+/**
+ * Read the current URL pathname.
+ *
+ * Compatible with Next.js's `usePathname()` from `next/navigation`.
+ */
+export function usePathname(): string {
+  return useSyncExternalStore(subscribe, getPathname, getServerPathname);
+}

package/src/client/use-query-states.ts

@@ -0,0 +1,133 @@
+/**
+ * useQueryStates — client-side hook for URL-synced search params.
+ *
+ * Delegates to nuqs for URL synchronization, batching, React 19 transitions,
+ * and throttled URL writes. Bridges timber's SearchParamCodec protocol to
+ * nuqs-compatible parsers.
+ *
+ * Design doc: design/23-search-params.md §"Codec Bridge"
+ */
+
+'use client';
+
+import { useQueryStates as nuqsUseQueryStates } from 'nuqs';
+import type { SingleParser } from 'nuqs';
+import type {
+  SearchParamCodec,
+  SearchParamsDefinition,
+  SetParams,
+  QueryStatesOptions,
+} from '#/search-params/create.js';
+import { getSearchParams } from '#/search-params/registry.js';
+
+// ─── Codec Bridge ─────────────────────────────────────────────────
+
+/**
+ * Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.
+ *
+ * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }
+ * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }
+ */
+function bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { defaultValue: T } {
+  return {
+    parse: (v: string) => codec.parse(v),
+    serialize: (v: T) => codec.serialize(v) ?? '',
+    defaultValue: codec.parse(undefined) as T,
+    eq: (a: T, b: T) => codec.serialize(a) === codec.serialize(b),
+  };
+}
+
+/**
+ * Bridge an entire codec map to nuqs-compatible parsers.
+ */
+function bridgeCodecs<T extends Record<string, unknown>>(codecs: {
+  [K in keyof T]: SearchParamCodec<T[K]>;
+}) {
+  const result: Record<string, SingleParser<unknown> & { defaultValue: unknown }> = {};
+  for (const key of Object.keys(codecs)) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    result[key] = bridgeCodec(codecs[key as keyof T]) as any;
+  }
+  return result as { [K in keyof T]: SingleParser<T[K]> & { defaultValue: T[K] } };
+}
+
+// ─── Hook ─────────────────────────────────────────────────────────
+
+/**
+ * Read and write typed search params from/to the URL.
+ *
+ * Delegates to nuqs internally. The timber nuqs adapter (auto-injected in
+ * browser-entry.ts) handles RSC navigation on non-shallow updates.
+ *
+ * Usage:
+ * ```ts
+ * // Via a SearchParamsDefinition
+ * const [params, setParams] = definition.useQueryStates()
+ *
+ * // Standalone with inline codecs
+ * const [params, setParams] = useQueryStates({
+ *   page: fromSchema(z.coerce.number().int().min(1).default(1)),
+ * })
+ * ```
+ */
+export function useQueryStates<T extends Record<string, unknown>>(
+  codecsOrRoute: { [K in keyof T]: SearchParamCodec<T[K]> } | string,
+  _options?: QueryStatesOptions,
+  urlKeys?: Readonly<Record<string, string>>
+): [T, SetParams<T>] {
+  // Route-string overload: resolve codecs from the registry
+  let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };
+  let resolvedUrlKeys = urlKeys;
+  if (typeof codecsOrRoute === 'string') {
+    const definition = getSearchParams(codecsOrRoute);
+    if (!definition) {
+      throw new Error(
+        `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +
+          `Either the route has no search-params.ts file, or it hasn't been loaded yet. ` +
+          `For cross-route usage, import the definition explicitly.`
+      );
+    }
+    codecs = definition.codecs as { [K in keyof T]: SearchParamCodec<T[K]> };
+    resolvedUrlKeys = definition.urlKeys;
+  } else {
+    codecs = codecsOrRoute;
+  }
+
+  const bridged = bridgeCodecs(codecs);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const nuqsOptions: any = {};
+  if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) {
+    nuqsOptions.urlKeys = resolvedUrlKeys;
+  }
+
+  const [values, setValues] = nuqsUseQueryStates(bridged, nuqsOptions);
+
+  // Wrap the nuqs setter to match timber's SetParams<T> signature.
+  // nuqs's setter accepts Partial<Nullable<Values>> | UpdaterFn | null.
+  // timber's setter accepts Partial<T> with optional SetParamsOptions.
+  const setParams: SetParams<T> = (partial, setOptions?) => {
+    const nuqsSetOptions: Record<string, unknown> = {};
+    if (setOptions?.shallow !== undefined) nuqsSetOptions.shallow = setOptions.shallow;
+    if (setOptions?.scroll !== undefined) nuqsSetOptions.scroll = setOptions.scroll;
+    if (setOptions?.history !== undefined) nuqsSetOptions.history = setOptions.history;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    void setValues(partial as any, nuqsSetOptions);
+  };
+
+  return [values as T, setParams];
+}
+
+// ─── Definition binding ───────────────────────────────────────────
+
+/**
+ * Create a useQueryStates binding for a SearchParamsDefinition.
+ * This is used internally by SearchParamsDefinition.useQueryStates().
+ */
+export function bindUseQueryStates<T extends Record<string, unknown>>(
+  definition: SearchParamsDefinition<T>
+): (options?: QueryStatesOptions) => [T, SetParams<T>] {
+  return (options?: QueryStatesOptions) => {
+    return useQueryStates<T>(definition.codecs, options, definition.urlKeys);
+  };
+}

package/src/client/use-router.ts

@@ -0,0 +1,77 @@
+/**
+ * useRouter() — client-side hook for programmatic navigation.
+ *
+ * Returns a router instance with push, replace, refresh, back, forward,
+ * and prefetch methods. Compatible with Next.js's `useRouter()` from
+ * `next/navigation` (App Router).
+ *
+ * This wraps timber's internal RouterInstance in the Next.js-compatible
+ * AppRouterInstance shape that ecosystem libraries expect.
+ */
+
+import { getRouter } from './router-ref.js';
+
+export interface AppRouterInstance {
+  /** Navigate to a URL, pushing a new history entry */
+  push(href: string, options?: { scroll?: boolean }): void;
+  /** Navigate to a URL, replacing the current history entry */
+  replace(href: string, options?: { scroll?: boolean }): void;
+  /** Refresh the current page (re-fetch RSC payload) */
+  refresh(): void;
+  /** Navigate back in history */
+  back(): void;
+  /** Navigate forward in history */
+  forward(): void;
+  /** Prefetch an RSC payload for a URL */
+  prefetch(href: string): void;
+}
+
+/** No-op router returned during SSR or before bootstrap. All methods are safe no-ops. */
+const SSR_NOOP_ROUTER: AppRouterInstance = {
+  push() {},
+  replace() {},
+  refresh() {},
+  back() {},
+  forward() {},
+  prefetch() {},
+};
+
+/**
+ * Get a router instance for programmatic navigation.
+ *
+ * Compatible with Next.js's `useRouter()` from `next/navigation`.
+ *
+ * Returns a no-op router during SSR or before the client router is bootstrapped,
+ * so components that call useRouter() at the function level (e.g. TransitionLink)
+ * do not crash during server-side rendering.
+ */
+export function useRouter(): AppRouterInstance {
+  let router;
+  try {
+    router = getRouter();
+  } catch {
+    // Router not yet bootstrapped — SSR or early client render before bootstrap().
+    return SSR_NOOP_ROUTER;
+  }
+
+  return {
+    push(href: string, options?: { scroll?: boolean }) {
+      void router.navigate(href, { scroll: options?.scroll });
+    },
+    replace(href: string, options?: { scroll?: boolean }) {
+      void router.navigate(href, { scroll: options?.scroll, replace: true });
+    },
+    refresh() {
+      void router.refresh();
+    },
+    back() {
+      window.history.back();
+    },
+    forward() {
+      window.history.forward();
+    },
+    prefetch(href: string) {
+      router.prefetch(href);
+    },
+  };
+}

package/src/client/use-search-params.ts

@@ -0,0 +1,74 @@
+/**
+ * useSearchParams() — client-side hook for reading URL search params.
+ *
+ * Returns a read-only URLSearchParams instance reflecting the current
+ * URL's query string. Updates when client-side navigation changes the URL.
+ *
+ * This is a thin wrapper over window.location.search, provided for
+ * Next.js API compatibility (libraries like nuqs import useSearchParams
+ * from next/navigation).
+ *
+ * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
+ * URLSearchParams. Mutation methods (set, delete, append) work on the
+ * local copy but do NOT affect the URL — use the router or nuqs for that.
+ *
+ * During SSR, reads the request search params from the SSR ALS context
+ * (populated by ssr-entry.ts) instead of window.location.
+ */
+
+import { useSyncExternalStore } from 'react';
+import { getSsrData } from './ssr-data.js';
+
+function getSearch(): 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}` : '';
+}
+
+function getServerSearch(): string {
+  const data = getSsrData();
+  if (!data) return '';
+  const sp = new URLSearchParams(data.searchParams);
+  const str = sp.toString();
+  return str ? `?${str}` : '';
+}
+
+function subscribe(callback: () => void): () => void {
+  window.addEventListener('popstate', callback);
+  return () => window.removeEventListener('popstate', callback);
+}
+
+// Cache the last search string and its parsed URLSearchParams to avoid
+// creating a new object on every render when the URL hasn't changed.
+let cachedSearch = '';
+let cachedParams = new URLSearchParams();
+
+function getSearchParams(): URLSearchParams {
+  const search = getSearch();
+  if (search !== cachedSearch) {
+    cachedSearch = search;
+    cachedParams = new URLSearchParams(search);
+  }
+  return cachedParams;
+}
+
+function getServerSearchParams(): URLSearchParams {
+  const data = getSsrData();
+  return data ? new URLSearchParams(data.searchParams) : new URLSearchParams();
+}
+
+/**
+ * Read the current URL search params.
+ *
+ * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
+ */
+export function useSearchParams(): URLSearchParams {
+  // useSyncExternalStore needs a primitive snapshot for comparison.
+  // We use the raw search string as the snapshot, then return the
+  // parsed URLSearchParams.
+  useSyncExternalStore(subscribe, getSearch, getServerSearch);
+  return typeof window !== 'undefined' ? getSearchParams() : getServerSearchParams();
+}

package/src/client/use-selected-layout-segment.ts

@@ -0,0 +1,110 @@
+/**
+ * useSelectedLayoutSegment / useSelectedLayoutSegments — client-side hooks
+ * for reading the active segment(s) below the current layout.
+ *
+ * These hooks are used by navigation UIs to highlight active sections.
+ * They match Next.js's API from next/navigation.
+ *
+ * How they work:
+ * 1. Each layout is wrapped with a SegmentProvider that records its depth
+ *    (the URL segments from root to that layout level).
+ * 2. The hooks read the current URL pathname via usePathname().
+ * 3. They compare the layout's segment depth against the full URL segments
+ *    to determine which child segments are "selected" below.
+ *
+ * Example: For URL "/dashboard/settings/profile"
+ * - Root layout (depth 0, segments: ['']): selected segment = "dashboard"
+ * - Dashboard layout (depth 1, segments: ['', 'dashboard']): selected = "settings"
+ * - Settings layout (depth 2, segments: ['', 'dashboard', 'settings']): selected = "profile"
+ *
+ * Design docs: design/19-client-navigation.md, design/14-ecosystem.md
+ */
+
+'use client';
+
+import { useSegmentContext } from './segment-context.js';
+import { usePathname } from './use-pathname.js';
+
+/**
+ * Split a pathname into URL segments.
+ * "/" → [""]
+ * "/dashboard" → ["", "dashboard"]
+ * "/dashboard/settings" → ["", "dashboard", "settings"]
+ */
+export function pathnameToSegments(pathname: string): string[] {
+  return pathname.split('/');
+}
+
+/**
+ * Pure function: compute the selected child segment given a layout's segment
+ * depth and the current URL pathname.
+ *
+ * @param contextSegments — segments from root to the calling layout, or null if no context
+ * @param pathname — current URL pathname
+ * @returns the active child segment one level below, or null if at the leaf
+ */
+export function getSelectedSegment(
+  contextSegments: string[] | null,
+  pathname: string
+): string | null {
+  const urlSegments = pathnameToSegments(pathname);
+
+  if (!contextSegments) {
+    return urlSegments[1] || null;
+  }
+
+  const depth = contextSegments.length;
+  return urlSegments[depth] || null;
+}
+
+/**
+ * Pure function: compute all selected segments below a layout's depth.
+ *
+ * @param contextSegments — segments from root to the calling layout, or null if no context
+ * @param pathname — current URL pathname
+ * @returns all active segments below the layout
+ */
+export function getSelectedSegments(contextSegments: string[] | null, pathname: string): string[] {
+  const urlSegments = pathnameToSegments(pathname);
+
+  if (!contextSegments) {
+    return urlSegments.slice(1).filter(Boolean);
+  }
+
+  const depth = contextSegments.length;
+  return urlSegments.slice(depth).filter(Boolean);
+}
+
+/**
+ * Returns the active child segment one level below the layout where this
+ * hook is called. Returns `null` if the layout is the leaf (no child segment).
+ *
+ * Compatible with Next.js's `useSelectedLayoutSegment()` from `next/navigation`.
+ *
+ * @param parallelRouteKey — Optional parallel route key. Currently unused
+ *   (parallel route segment tracking is not yet implemented). Accepted for
+ *   API compatibility with Next.js.
+ */
+export function useSelectedLayoutSegment(parallelRouteKey?: string): string | null {
+  void parallelRouteKey;
+  const context = useSegmentContext();
+  const pathname = usePathname();
+  return getSelectedSegment(context?.segments ?? null, pathname);
+}
+
+/**
+ * Returns all active segments below the layout where this hook is called.
+ * Returns an empty array if the layout is the leaf (no child segments).
+ *
+ * Compatible with Next.js's `useSelectedLayoutSegments()` from `next/navigation`.
+ *
+ * @param parallelRouteKey — Optional parallel route key. Currently unused
+ *   (parallel route segment tracking is not yet implemented). Accepted for
+ *   API compatibility with Next.js.
+ */
+export function useSelectedLayoutSegments(parallelRouteKey?: string): string[] {
+  void parallelRouteKey;
+  const context = useSegmentContext();
+  const pathname = usePathname();
+  return getSelectedSegments(context?.segments ?? null, pathname);
+}

package/src/content/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @timber/app/content — Public API for content collections.
+ *
+ * Re-exports from content-collections and provides timber-specific utilities.
+ * Users can import directly from 'content-collections' for generated types,
+ * or use this module for the re-exports.
+ *
+ * Design doc: 20-content-collections.md §"Querying Collections"
+ */
+
+// Re-export defineCollection and defineConfig for convenience.
+// Users can also import these directly from @content-collections/core.
+export { defineCollection, defineConfig } from '@content-collections/core';

package/src/cookies/define-cookie.ts

@@ -0,0 +1,137 @@
+/**
+ * defineCookie — typed cookie definitions.
+ *
+ * Bundles name + codec + options into a reusable CookieDefinition<T>
+ * with .get(), .set(), .delete() server methods and a .useCookie() client hook.
+ *
+ * Reuses the SearchParamCodec protocol via fromSchema() bridge.
+ * Validation on read returns the codec default (never throws).
+ *
+ * See design/29-cookies.md §"Typed Cookies with Schema Validation"
+ */
+
+import { cookies } from '#/server/request-context.js';
+import type { CookieOptions } from '#/server/request-context.js';
+import { useCookie as useRawCookie } from '#/client/use-cookie.js';
+import type { ClientCookieOptions } from '#/client/use-cookie.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/**
+ * A codec that converts between string cookie values and typed values.
+ * Intentionally identical to SearchParamCodec<T>.
+ */
+export interface CookieCodec<T> {
+  parse(value: string | string[] | undefined): T;
+  serialize(value: T): string | null;
+}
+
+/** Options for defineCookie: codec + CookieOptions merged. */
+export interface DefineCookieOptions<T> extends Omit<CookieOptions, 'signed'> {
+  /** Codec for parsing/serializing the cookie value. */
+  codec: CookieCodec<T>;
+  /** Sign the cookie with HMAC-SHA256. */
+  signed?: boolean;
+}
+
+/** A fully typed cookie definition with server and client methods. */
+export interface CookieDefinition<T> {
+  /** The cookie name. */
+  readonly name: string;
+  /** The resolved cookie options (without codec). */
+  readonly options: CookieOptions;
+  /** The codec used for parsing/serializing. */
+  readonly codec: CookieCodec<T>;
+
+  /** Server: read the typed value from the current request. */
+  get(): T;
+  /** Server: set the typed value on the response. */
+  set(value: T): void;
+  /** Server: delete the cookie. */
+  delete(): void;
+
+  /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */
+  useCookie(): [T, (value: T) => void, () => void];
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────
+
+/**
+ * Define a typed cookie.
+ *
+ * ```ts
+ * import { defineCookie } from '@timber/app/cookies';
+ * import { fromSchema } from '@timber/app/search-params';
+ * import { z } from 'zod/v4';
+ *
+ * export const themeCookie = defineCookie('theme', {
+ *   codec: fromSchema(z.enum(['light', 'dark', 'system']).default('system')),
+ *   httpOnly: false,
+ *   maxAge: 60 * 60 * 24 * 365,
+ * });
+ * ```
+ */
+export function defineCookie<T>(
+  name: string,
+  options: DefineCookieOptions<T>
+): CookieDefinition<T> {
+  const { codec, ...cookieOpts } = options;
+  const resolvedOptions: CookieOptions = { ...cookieOpts };
+
+  return {
+    name,
+    options: resolvedOptions,
+    codec,
+
+    get(): T {
+      const jar = cookies();
+      const raw = resolvedOptions.signed ? jar.getSigned(name) : jar.get(name);
+      return codec.parse(raw);
+    },
+
+    set(value: T): void {
+      const serialized = codec.serialize(value);
+      if (serialized === null) {
+        cookies().delete(name, {
+          path: resolvedOptions.path,
+          domain: resolvedOptions.domain,
+        });
+      } else {
+        cookies().set(name, serialized, resolvedOptions);
+      }
+    },
+
+    delete(): void {
+      cookies().delete(name, {
+        path: resolvedOptions.path,
+        domain: resolvedOptions.domain,
+      });
+    },
+
+    useCookie(): [T, (value: T) => void, () => void] {
+      // Extract client-safe options (no httpOnly — client cookies can't be httpOnly)
+      const clientOpts: ClientCookieOptions = {
+        path: resolvedOptions.path,
+        domain: resolvedOptions.domain,
+        maxAge: resolvedOptions.maxAge,
+        expires: resolvedOptions.expires,
+        sameSite: resolvedOptions.sameSite,
+        secure: resolvedOptions.secure,
+      };
+
+      const [raw, setRaw, deleteRaw] = useRawCookie(name, clientOpts);
+      const parsed = codec.parse(raw);
+
+      const setTyped = (value: T): void => {
+        const serialized = codec.serialize(value);
+        if (serialized === null) {
+          deleteRaw();
+        } else {
+          setRaw(serialized);
+        }
+      };
+
+      return [parsed, setTyped, deleteRaw];
+    },
+  };
+}

package/src/cookies/index.ts

@@ -0,0 +1,9 @@
+// @timber/app/cookies — Typed cookie definitions
+// See design/29-cookies.md §"Typed Cookies with Schema Validation"
+
+export { defineCookie } from './define-cookie.js';
+export type {
+  CookieDefinition,
+  CookieCodec,
+  DefineCookieOptions,
+} from './define-cookie.js';