@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.161

package/src/client/form.tsx

@@ -12,8 +12,8 @@
  */
 
 import { useActionState as reactUseActionState, useTransition } from 'react';
-import type { ActionResult, ValidationErrors } from '#/server/action-client';
-import type { FormFlashData } from '#/server/form-flash';
+import type { ActionFn, ActionResult, InputHint, ValidationErrors } from '../server/action-client';
+import type { FormFlashData } from '../server/form-flash';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -27,13 +27,15 @@ export type UseActionStateFn<TData> = (
 ) => Promise<ActionResult<TData>>;
 
 /**
- * Return type of useActionState — matches React 19's useActionState return.
- * [result, formAction, isPending]
+ * Return type of useActionState.
+ * [result, formAction, isPending, errors]
+ * The 4th element is auto-derived from result via useFormErrors logic.
  */
 export type UseActionStateReturn<TData> = [
   result: ActionResult<TData> | null,
   formAction: (formData: FormData) => void,
   isPending: boolean,
+  errors: FormErrorsResult,
 ];
 
 // ─── useActionState ──────────────────────────────────────────────────────
@@ -73,7 +75,13 @@ export function useActionState<TData>(
 ): UseActionStateReturn<TData> {
   // FormFlashData is structurally compatible with ActionResult at runtime —
   // the cast satisfies React's generic inference which would otherwise widen TData.
-  return reactUseActionState(action, initialState as ActionResult<TData> | null, permalink);
+  const [result, formAction, isPending] = reactUseActionState(
+    action,
+    initialState as ActionResult<TData> | null,
+    permalink
+  );
+  const errors = deriveFormErrors(result);
+  return [result, formAction, isPending, errors];
 }
 
 // ─── useFormAction ───────────────────────────────────────────────────────
@@ -90,15 +98,22 @@ export function useActionState<TData>(
  * </button>
  * ```
  */
-export function useFormAction<TData>(
-  action: (input: unknown) => Promise<ActionResult<TData>>
-): [(input?: unknown) => Promise<ActionResult<TData>>, boolean] {
+export function useFormAction<TData = unknown, TInput = unknown>(
+  action: ActionFn<TData, TInput> | ((input: TInput) => Promise<ActionResult<TData>>)
+): [
+  (
+    ...args: undefined extends TInput ? [input?: InputHint<TInput>] : [input: InputHint<TInput>]
+  ) => Promise<ActionResult<TData>>,
+  boolean,
+] {
   const [isPending, startTransition] = useTransition();
 
-  const execute = (input?: unknown): Promise<ActionResult<TData>> => {
+  const execute = (input?: InputHint<TInput>): Promise<ActionResult<TData>> => {
     return new Promise((resolve) => {
       startTransition(async () => {
-        const result = await action(input);
+        const result = await (action as (input: InputHint<TInput>) => Promise<ActionResult<TData>>)(
+          input as InputHint<TInput>
+        );
         resolve(result);
       });
     });
@@ -107,9 +122,9 @@ export function useFormAction<TData>(
   return [execute, isPending];
 }
 
-// ─── useFormErrors ──────────────────────────────────────────────────────
+// ─── Form error extraction ────────────────────────────────────────────────
 
-/** Return type of useFormErrors(). */
+/** Return type of the errors element in useActionState. */
 export interface FormErrorsResult {
   /** Per-field validation errors keyed by field name. */
   fieldErrors: Record<string, string[]>;
@@ -124,27 +139,11 @@ export interface FormErrorsResult {
 }
 
 /**
- * Extract per-field and form-level errors from an ActionResult.
- *
- * Pure function (no internal hooks) — follows React naming convention
- * since it's used in render. Accepts the result from `useActionState`
- * or flash data from `getFormFlash()`.
- *
- * @example
- * ```tsx
- * const [result, action, isPending] = useActionState(createTodo, null)
- * const errors = useFormErrors(result)
- *
- * return (
- *   <form action={action}>
- *     <input name="title" />
- *     {errors.getFieldError('title') && <p>{errors.getFieldError('title')}</p>}
- *     {errors.formErrors.map(e => <p key={e}>{e}</p>)}
- *   </form>
- * )
- * ```
+ * Derive FormErrorsResult from an action result.
+ * Used internally by useActionState 4th tuple element.
+ * @internal — exported for test access only.
  */
-export function useFormErrors<TData>(
+export function deriveFormErrors<TData>(
   result:
     | ActionResult<TData>
     | {

package/src/client/history.ts

@@ -1,16 +1,17 @@
 // History Stack — stores RSC payloads by URL for instant back/forward navigation
 // See design/19-client-navigation.md § History Stack
 
-import type { HeadElement } from './head';
-
 // ─── Types ───────────────────────────────────────────────────────
 
 export interface HistoryEntry {
   /** The complete segment tree payload at the time of navigation */
   payload: unknown;
-  /** Resolved head elements for this page (title, meta tags). Null for SSR'd initial page. */
-  headElements?: HeadElement[] | null;
-  /** Route params for this page (for useParams). Null for SSR'd initial page. */
+  /**
+   * Route params for this page (for useSegmentParams). Every entry that can
+   * be replayed must carry them — the initial SSR entry gets them from the
+   * server-embedded __timber_params, navigation entries from X-Timber-Params,
+   * and revalidation overwrites preserve the current state (TIM-1037).
+   */
   params?: Record<string, string | string[]> | null;
 }
 
@@ -23,8 +24,11 @@ export interface HistoryEntry {
  * On forward navigation, the new page's payload is pushed onto the stack.
  * On popstate, the cached payload is replayed instantly.
  *
- * Scroll positions are stored in history.state (browser History API),
- * not in this stack — see design/19-client-navigation.md §Scroll Restoration.
+ * Entries are keyed by pathname + search. Used with the History API
+ * fallback and the Navigation API.
+ *
+ * Scroll positions are stored in history.state or Navigation API entry
+ * state, not in this stack — see design/19-client-navigation.md §Scroll Restoration.
  *
  * Entries persist for the session duration (no expiry) and are cleared
  * when the tab is closed — matching browser back-button behavior.

package/src/client/index.ts

@@ -1,64 +1,86 @@
 // @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).
+// eslint-disable-next-line typescript/no-empty-interface -- augmented by codegen
+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 { replaceUrl } from './shallow-url';
+// 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';
+// Params — raw hook for untyped access. For typed params, use defineSegmentParams().useSegmentParams().
+export { useSegmentParams } from './use-segment-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';
+// Query states — useQueryStates lives on defineSearchParams().useQueryStates()
+// and is available via direct import for advanced cases.
 
-// Query states (URL-synced search params)
-export { useQueryStates, bindUseQueryStates } from './use-query-states';
-
-// 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';

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';