@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.90

package/src/client/index.ts

@@ -1,64 +1,91 @@
 // @timber-js/app/client — Client-side primitives
 // These are the primary imports for client components.
+//
+// Framework-internal bootstrap, SSR bridge, and segment plumbing is in
+// #client-internal (Node package import).
+// Design doc: design/triage/api-naming-spike.md §8.5
 
-export type { JsonSerializable, RenderErrorDigest } from './types';
+// JsonSerializable moved to @timber-js/app/codec as the single canonical path.
+// Re-export removed per TIM-721.
+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';
-export { createRouter } from './router';
-export type {
-  RouterInstance,
-  NavigationOptions,
-  RouterDeps,
-  RscDecoder,
-  RootRenderer,
-} from './router';
-export { useNavigationPending } from './use-navigation-pending';
+export { mergePreservedSearchParams } from '../shared/merge-search-params.js';
+export type { LinkProps, LinkPropsWithHref, LinkPropsWithParams, LinkBaseProps } from './link';
+export type { LinkSegmentParams, OnNavigateHandler, OnNavigateEvent } from './link';
+
+// ─── LinkFunction (originally declared here for module augmentation) ───
+//
+// The codegen emits TWO augmentations of this interface:
+//
+//   1. Per-route call signatures — `href: '/products/[id]'` with direct
+//      `segmentParams`/`searchParams` types.
+//   2. Catch-all call signatures — `ExternalHref` + computed `string`
+//      variable hrefs.
+//
+// Both live in the codegen output (NOT here). Overload ORDER matters
+// for error UX, and TypeScript's declaration-merging rule "later overload
+// sets ordered first" means that whichever augmentation block is
+// declared LATER in the codegen file ends up FIRST in the merged call-
+// signature list — and therefore the EARLIER block ends up LAST, which
+// is the overload whose error message TypeScript reports when no
+// overload matches.
+//
+// We want the PER-ROUTE overloads to be the error-reporting ones when
+// a user passes a known literal `href` with a mistyped segmentParam.
+// So the codegen emits them FIRST and the catch-all SECOND. That way
+// a call like:
+//
+//   <Link href="/products/[id]" segmentParams={{ id: maybeUndef }} />
+//
+// reports the actual mismatch (`'string | undefined' is not assignable
+// to 'string | number'` on `id`) instead of the notorious "Type 'string'
+// is not assignable to type 'never'" cascade that the old fixed
+// catch-all produced (TIM-832, sibling of TIM-830 / TIM-624).
+//
+// The interface is kept as an empty placeholder here so:
+// - module augmentation has a base interface to merge into
+// - `link.tsx` can `import type { LinkFunction }` and use it as the
+//   cast target for the `Link` const (an empty interface accepts any
+//   non-nullable value, so the cast is valid even without codegen run)
+// - NO call signatures live here — in a fresh checkout where codegen
+//   hasn't run yet, invoking `<Link>` is deliberately a type error,
+//   which surfaces "codegen hasn't run" rather than a misleading
+//   structural type mismatch.
+//
+// See TIM-624 (original typed Link), TIM-830 (flat searchParams), and
+// TIM-832 (this restructure for overload error UX).
+export interface LinkFunction {
+  // intentionally empty — call signatures are provided via codegen
+  // augmentation in `.timber/timber-routes.d.ts`.
+}
+export { usePendingNavigation } from './use-pending-navigation';
 export { useLinkStatus, LinkStatusContext } from './use-link-status';
 export type { LinkStatus } from './use-link-status';
-export { getRouter, setGlobalRouter } 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';
-
-// Navigation context (framework-internal, used by browser-entry for atomic updates)
-export { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context';
-export type { NavigationState } from './navigation-context';
+export { useSegmentParams } from './use-params';
 
 // Query states (URL-synced search params)
-export { useQueryStates, bindUseQueryStates } from './use-query-states';
+export { useQueryStates } 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';
+// Register the client cookie module with defineCookie's lazy reference.
+// This runs at module load time in the client/SSR environment, wiring up
+// the useCookie hook without a top-level import in define-cookie.ts.
+import * as _useCookieMod from './use-cookie.js';
+import { _registerUseCookieModule } from '../cookies/define-cookie.js';
+_registerUseCookieModule(_useCookieMod);

package/src/client/internal.ts

@@ -0,0 +1,57 @@
+// #client-internal — Framework-internal client exports
+//
+// This module is a Node package import (#client-internal in package.json
+// "imports" field). It is only resolvable from within @timber-js/app —
+// external consumers cannot import it.
+//
+// These exports are consumed by browser-entry, ssr-entry, and build plugins.
+// They are NOT part of the user-facing API and should not appear in
+// documentation or autocomplete for application developers.
+//
+// Design doc: design/triage/api-naming-spike.md §8.5
+
+// ── Bootstrap ────────────────────────────────────────────────────────────
+export { createRouter } from './router.js';
+export type {
+  RouterInstance,
+  NavigationOptions,
+  RouterDeps,
+  RouterPhase,
+  RscDecoder,
+  RootRenderer,
+} from './router.js';
+export { getRouter, getRouterOrNull, setGlobalRouter } from './router-ref.js';
+
+// ── SSR bridge ───────────────────────────────────────────────────────────
+export { setSsrData, clearSsrData, getSsrData } from './ssr-data.js';
+export type { SsrData } from './ssr-data.js';
+
+// ── Segment context ──────────────────────────────────────────────────────
+export { SegmentProvider, useSegmentContext } from './segment-context.js';
+export type { SegmentContextValue } from './segment-context.js';
+
+// ── Segment cache ────────────────────────────────────────────────────────
+export { SegmentCache, PrefetchCache } from './segment-cache.js';
+export type { SegmentNode, StateTree } from './segment-cache.js';
+
+// ── History ──────────────────────────────────────────────────────────────
+export { HistoryStack } from './history.js';
+export type { HistoryEntry } from './history.js';
+
+// ── Params (internal setter) ─────────────────────────────────────────────
+export { setCurrentParams } from './use-params.js';
+
+// ── Navigation context ───────────────────────────────────────────────────
+export {
+  NavigationProvider,
+  getNavigationState,
+  setNavigationState,
+} from './navigation-context.js';
+export type { NavigationState } from './navigation-context.js';
+
+// ── Query states (internal binder) ───────────────────────────────────────
+export { bindUseQueryStates } from './use-query-states.js';
+
+// ── Error boundary ───────────────────────────────────────────────────────
+export { TimberErrorBoundary } from './error-boundary.js';
+export type { TimberErrorBoundaryProps } from './error-boundary.js';

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

@@ -0,0 +1,111 @@
+/**
+ * Link Pending Store — per-link optimistic pending state.
+ *
+ * Tracks which link instance is currently navigating so that only the
+ * clicked link shows pending. Uses `useOptimistic` from React 19 —
+ * the optimistic value (isPending=true) is set inside NavigationRoot's
+ * async startTransition so it persists for the duration of the RSC
+ * fetch, then auto-reverts to idle when the transition settles.
+ *
+ * Flow:
+ * 1. Link click → setLinkForCurrentNavigation(instance) stores the ref
+ * 2. NavigationRoot startTransition → activateLinkPending() calls
+ *    instance.setIsPending(LINK_PENDING) inside the async transition
+ * 3. Transition settles → useOptimistic auto-reverts to LINK_IDLE
+ *
+ * SINGLETON GUARANTEE: Uses `globalThis` via `Symbol.for` keys because
+ * the RSC client bundler can duplicate this module across chunks.
+ *
+ * See design/19-client-navigation.md §"Per-Link Pending State"
+ */
+
+import type { LinkStatus } from './use-link-status.js';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+export interface LinkPendingInstance {
+  setIsPending: (status: LinkStatus) => void;
+}
+
+// ─── Constants ───────────────────────────────────────────────────
+
+const LINK_PENDING_KEY = Symbol.for('__timber_link_pending');
+
+/** Status object: link navigation in flight */
+export const LINK_PENDING: LinkStatus = { isPending: true };
+
+/** Status object: link idle */
+export const LINK_IDLE: LinkStatus = { isPending: false };
+
+// ─── Singleton Storage ───────────────────────────────────────────
+
+function getStore(): { current: LinkPendingInstance | null } {
+  const g = globalThis as Record<symbol, unknown>;
+  if (!g[LINK_PENDING_KEY]) {
+    g[LINK_PENDING_KEY] = { current: null };
+  }
+  return g[LINK_PENDING_KEY] as { current: LinkPendingInstance | null };
+}
+
+// ─── Public API ──────────────────────────────────────────────────
+
+/**
+ * Register the link instance that initiated the current navigation.
+ * Called from Link's click handler. Does NOT call setIsPending —
+ * that happens inside NavigationRoot's startTransition via
+ * activateLinkPending().
+ *
+ * Resets the previous link to idle immediately (the old link's
+ * useOptimistic reverts since its transition already settled).
+ */
+export function setLinkForCurrentNavigation(link: LinkPendingInstance | null): void {
+  const store = getStore();
+  store.current = link;
+}
+
+/**
+ * Activate pending state on the current link instance.
+ * MUST be called inside NavigationRoot's async startTransition —
+ * this is what makes useOptimistic persist for the navigation duration.
+ */
+export function activateLinkPending(): void {
+  const store = getStore();
+  store.current?.setIsPending(LINK_PENDING);
+}
+
+/**
+ * Reset the current link's pending state. With useOptimistic this is
+ * handled automatically when the transition settles. Kept for callers
+ * that explicitly need to clear on error paths.
+ */
+export function resetLinkPending(): void {
+  const store = getStore();
+  if (store.current) {
+    store.current.setIsPending(LINK_IDLE);
+    store.current = null;
+  }
+}
+
+/**
+ * @deprecated No longer needed with useOptimistic. Kept for callers.
+ */
+export function getCurrentNavId(): number {
+  return 0;
+}
+
+/**
+ * Clean up the link pending store entirely.
+ */
+export function clearLinkPendingSetter(): void {
+  getStore().current = null;
+}
+
+/**
+ * Unmount a link instance from navigation tracking.
+ */
+export function unmountLinkForCurrentNavigation(link: LinkPendingInstance): void {
+  const store = getStore();
+  if (store.current === link) {
+    store.current = null;
+  }
+}