@timber-js/app 0.2.0-alpha.11 → 0.2.0-alpha.110

package/src/client/index.ts

@@ -1,64 +1,89 @@
 // @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';
+// useSearchParams removed from public exports — lives in next/navigation shim only.
 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 { useActionState, useFormAction } 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';
+// Params — raw hook for untyped access. For typed params, use defineSegmentParams().useSegmentParams().
+export { useSegmentParams } from './use-segment-params';
 
-// Query states (URL-synced search params)
-export { useQueryStates, bindUseQueryStates } from './use-query-states';
+// Query states — useQueryStates lives on defineSearchParams().useQueryStates()
+// and is available via direct import for advanced cases.
 
-// Cookies
-export { useCookie } from './use-cookie';
+// Cookies — useCookie lives on defineCookie().useCookie().
+// Types still exported for advanced use.
 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 useSegmentParams hook with defineSegmentParams.
+import { useSegmentParams as _useSegmentParams } from './use-segment-params.js';
+import { _registerUseSegmentParams } from '../segment-params/define.js';
+_registerUseSegmentParams(_useSegmentParams);

package/src/client/internal.ts

@@ -0,0 +1,58 @@
+// #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 + raw hooks) ─────────────────────────────────
+export { setCurrentParams } from './use-segment-params.js';
+export { useSearchParams } from './use-search-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;
+  }
+}