@bractjs/bractjs 0.1.27 → 0.1.28

package/types/index.d.ts

@@ -4,8 +4,11 @@ import type { ReactNode, Context, CSSProperties } from "react";
 export type {
   LoaderArgs, ActionArgs, MetaDescriptor, MetaArgs,
   LoaderFunction, ActionFunction, MetaFunction, RouteModule,
-  RouteFile, Segment,
+  RouteFile, Segment, RouterLocation,
+  ShouldRevalidateArgs, ShouldRevalidateFunction,
+  LoaderData, ActionData,
 } from "./route.d.ts";
+import type { RouterLocation, LoaderData, ActionData, ActionArgs } from "./route.d.ts";
 
 // ── Config + Server ───────────────────────────────────────────────────────
 export type { BractJSConfig, ServerManifest, BuildConfig } from "./config.d.ts";
@@ -18,9 +21,15 @@ export interface RenderOptions {
   actionData: unknown;
   params: Record<string, string>;
   pathname: string;
+  /** Validated search params — hydrates `useSearch()` on the client. */
+  search?: Record<string, unknown>;
   manifest: ServerManifest;
   meta: MetaDescriptor[];
   status?: number;
+  routeFile?: string;
+  nonce?: string;
+  /** Set when the document did not SSR the route component (selective SSR / SPA shell). */
+  ssrMode?: "client-only" | "data-only" | "spa";
 }
 
 export type OnErrorHook = (err: unknown, request?: Request) => Promise<void> | void;
@@ -64,6 +73,10 @@ export interface BractJSContextValue {
   params: Record<string, string>;
   pathname: string;
   manifest: RouteManifest;
+  /** The request's location, so `useLocation()` works during SSR (hash is always ""). */
+  location?: RouterLocation;
+  /** Validated search params, so `useSearch()` works during SSR. */
+  search?: Record<string, unknown>;
 }
 export declare const BractJSContext: Context<BractJSContextValue>;
 export declare function BractJSProvider(props: { value: BractJSContextValue; children: ReactNode }): ReactNode;
@@ -129,6 +142,38 @@ export declare function validate<T>(
   input: FormData | Record<string, unknown>,
 ): Promise<T>;
 
+export type SafeValidateResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; fieldErrors: FieldErrors; firstError: string };
+/** Non-throwing validate(): returns a result instead of throwing a 400. */
+export declare function safeValidate<T>(
+  schema: { safeParse?(i: unknown): unknown } | { parse(i: unknown): T },
+  input: FormData | Record<string, unknown>,
+): Promise<SafeValidateResult<T>>;
+/** True for the 400 Response thrown by validate()/searchSchema validation. */
+export declare function isValidationResponse(value: unknown): value is Response;
+/** Parse the `{ errors }` body of a validation 400 into field errors + first message. */
+export declare function readValidationError(
+  res: Response,
+): Promise<{ fieldErrors: FieldErrors; firstError: string }>;
+
+// ── FormData helpers ──────────────────────────────────────────────────────
+/** String field from FormData; "" when missing or a File. */
+export declare function formText(formData: FormData, key: string): string;
+/** Collect string fields from FormData (all, or a named subset). */
+export declare function formValues(formData: FormData, keys?: string[]): Record<string, string>;
+
+// ── Search-param validation ───────────────────────────────────────────────
+/** URLSearchParams → plain object; repeated keys collapse into arrays. */
+export declare function searchParamsToObject(sp: URLSearchParams): Record<string, string | string[]>;
+/**
+ * Validate a URL's search params against a route's `searchSchema`. No schema →
+ * the raw string record; failure → throws a 400 Response with field errors.
+ */
+export declare function validateSearch(schema: unknown, url: URL): Promise<Record<string, unknown>>;
+/** Serialize a search object back into a query string (leading `?`, or ""). */
+export declare function serializeSearch(search: Record<string, unknown>): string;
+
 // ── Typed-routing registration seam ───────────────────────────────────────
 // Mirror of src/client/registry.ts. Augment `Register` (done by `bractjs codegen`
 // in app/route-types.gen.ts) to make <Link>/useNavigate/useParams/useSearchParams
@@ -151,10 +196,21 @@ export type RegisteredParamsMap =
   Register extends { routes: { params: infer P } } ? P : Record<string, Record<string, string>>;
 export type RegisteredSearchMap =
   Register extends { routes: { search: infer S } } ? S : Record<string, Record<string, string>>;
+export type RegisteredSearchOutputMap =
+  Register extends { routes: { searchOutput: infer S } } ? S : Record<string, Record<string, unknown>>;
 export type ParamsFor<TTo> =
   TTo extends keyof RegisteredParamsMap ? RegisteredParamsMap[TTo] : Record<string, string>;
 export type SearchFor<TTo> =
   TTo extends keyof RegisteredSearchMap ? RegisteredSearchMap[TTo] : Record<string, string>;
+/** Validated (schema-output) search object for a specific route literal. */
+export type SearchOutputFor<TTo> =
+  TTo extends keyof RegisteredSearchOutputMap ? RegisteredSearchOutputMap[TTo] : Record<string, unknown>;
+/** Infer the output type of a Zod/Valibot-compatible schema (duck-typed z.infer). */
+export type InferSchemaOutput<S> =
+  S extends { parse(input: unknown): infer T } ? T :
+  S extends { safeParse(input: unknown): infer R }
+    ? (Awaited<R> extends { data?: infer T } ? NonNullable<T> : Record<string, unknown>)
+    : Record<string, unknown>;
 export declare function buildPath(pattern: string, params: Record<string, string | number>): string;
 
 // ── Client components ─────────────────────────────────────────────────────
@@ -165,18 +221,37 @@ export declare function Outlet(): ReactNode;
 export type LinkProps<TTo extends RegisteredRoutes = RegisteredRoutes> = {
   to: TTo | (string & {});
   params?: ParamsFor<TTo>;
-  prefetch?: "hover" | "none";
+  /** Search params for the target, typed by its `searchSchema` (replaces any query in `to`). */
+  search?: Partial<SearchOutputFor<TTo>>;
+  /** When to prefetch the target's chunk + loader data. Default "none". */
+  prefetch?: "none" | "intent" | "hover" | "viewport" | "render";
   viewTransition?: boolean;
+  /** Replace the current history entry instead of pushing. */
+  replace?: boolean;
   children?: ReactNode;
   className?: string;
   [key: string]: unknown;
 };
 export declare function Link<TTo extends RegisteredRoutes = RegisteredRoutes>(props: LinkProps<TTo>): ReactNode;
 
-export interface FormProps { method?: "post" | "put" | "delete"; action?: string; children?: ReactNode; [key: string]: unknown; }
+export interface ScrollRestorationProps {
+  /** Derive the storage key for a location. Default: `location.key`. */
+  getKey?: (location: RouterLocation) => string;
+  storageKey?: string;
+}
+/** Restores scroll on back/forward, scrolls to top (or `#hash`) on new navigations. Render once in root.tsx. */
+export declare function ScrollRestoration(props?: ScrollRestorationProps): null;
+
+export interface FormProps { method?: "post" | "put" | "delete"; action?: string; /** Renders a hidden `intent` input (pairs with defineActions()). */ intent?: string; children?: ReactNode; [key: string]: unknown; }
 export declare function Form(props: FormProps): ReactNode;
 
-export interface AwaitProps<T> { resolve: Promise<T>; fallback: ReactNode; children: (data: T) => ReactNode; }
+// ── defineActions (intent dispatch) ───────────────────────────────────────
+/** Compose a route action from per-intent handlers, dispatching on the form's `intent` field. */
+export declare function defineActions<M extends Record<string, (args: ActionArgs) => unknown>>(
+  handlers: M,
+): (args: ActionArgs) => Promise<Awaited<ReturnType<M[keyof M]>> | Response>;
+
+export interface AwaitProps<T> { resolve: Promise<T> | Deferred<T>; fallback: ReactNode; children: (data: T) => ReactNode; }
 export declare function Await<T>(props: AwaitProps<T>): ReactNode;
 
 export type ImageFormat = "webp" | "avif" | "jpeg" | "png";
@@ -197,30 +272,90 @@ export interface ImageProps {
 export declare function Image(props: ImageProps): ReactNode;
 
 // ── Client hooks ──────────────────────────────────────────────────────────
-export declare function useLoaderData<T = unknown>(): T;
-export declare function useActionData<T = unknown>(): T | null;
+// Pass the loader/action function type to infer the data — useLoaderData<typeof loader>().
+export declare function useLoaderData<T = unknown>(): LoaderData<T>;
+export declare function useActionData<T = unknown>(): ActionData<T> | null;
+/** The current location — reactive on the client, request-derived during SSR. */
+export declare function useLocation(): RouterLocation;
 export declare function useParams<TTo extends string>(): ParamsFor<TTo>;
 export declare function useParams<T extends Record<string, string> = Record<string, string>>(): T;
 export type NavigationState = "idle" | "loading" | "submitting";
 export declare function useNavigation(): { state: NavigationState };
 
-export interface NavigateOptions<TTo extends RegisteredRoutes = RegisteredRoutes> { params?: ParamsFor<TTo>; }
+export interface NavigateOptions<TTo extends RegisteredRoutes = RegisteredRoutes> {
+  params?: ParamsFor<TTo>;
+  /** Search params for the target, typed by its `searchSchema` (replaces any query in `to`). */
+  search?: Partial<SearchOutputFor<TTo>>;
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+  /** Arbitrary history state, readable via `useLocation().state` after navigating. */
+  state?: unknown;
+}
 export interface NavigateFn {
   <TTo extends RegisteredRoutes>(to: TTo | (string & {}), options?: NavigateOptions<TTo>): Promise<void>;
 }
 export declare function useNavigate(): NavigateFn;
+
+// ── Fetchers ──────────────────────────────────────────────────────────────
+export type FetcherState = "idle" | "loading" | "submitting";
+export interface FetcherEntry {
+  key: string;
+  state: FetcherState;
+  data: unknown;
+  /** The submitted form data while a submission is in flight — the optimistic-UI source. */
+  formData?: FormData;
+  formMethod?: string;
+}
+export interface FetcherFormProps {
+  method?: "post" | "put" | "delete";
+  action?: string;
+  /** Renders a hidden `intent` input (pairs with defineActions()). */
+  intent?: string;
+  children?: ReactNode;
+  [key: string]: unknown;
+}
 export interface FetcherResult {
   data: unknown;
-  state: NavigationState;
+  state: FetcherState;
+  formData?: FormData;
+  formMethod?: string;
+  key: string;
   load(path: string): Promise<void>;
   submit(path: string, opts: { method: string; body: FormData | Record<string, string> }): Promise<void>;
+  /** A form that submits through this fetcher (no navigation, no history). */
+  Form: (props: FetcherFormProps) => ReactNode;
 }
 export interface StreamFetcherResult<T = unknown> {
+  /** @deprecated Never emitted — call `connect(actionId)` instead. Removed in 0.2. */
   events: AsyncGenerator<T>;
   connect(actionId: string): AsyncGenerator<T>;
 }
-export declare function useFetcher(): FetcherResult;
+export interface UseFetcherOptions { key?: string; stream?: boolean }
+export declare function useFetcher(opts?: { key?: string }): FetcherResult;
 export declare function useFetcher<T>(opts: { stream: true }): StreamFetcherResult<T>;
+/** Every active fetcher — the cross-component view for optimistic UI. */
+export declare function useFetchers(): FetcherEntry[];
+
+// ── Revalidation ──────────────────────────────────────────────────────────
+export interface Revalidator {
+  revalidate(): Promise<void>;
+  state: "idle" | "loading";
+}
+/** Manually re-run the active route's loaders (respects `shouldRevalidate`). */
+export declare function useRevalidator(): Revalidator;
+
+// ── Typed search ──────────────────────────────────────────────────────────
+/** The current route's VALIDATED search params (its `searchSchema` output). */
+export declare function useSearch<TTo extends string>(): SearchOutputFor<TTo>;
+export declare function useSearch<T extends Record<string, unknown>>(): T;
+export interface SetSearchOptions { replace?: boolean }
+export type SetSearchFn<T extends Record<string, unknown>> = (
+  updater: Partial<T> | ((prev: T) => Partial<T>),
+  options?: SetSearchOptions,
+) => Promise<void>;
+/** Merge a patch into the current search params and soft-navigate (loaders re-run). */
+export declare function useSetSearch<TTo extends string>(): SetSearchFn<SearchOutputFor<TTo>>;
+export declare function useSetSearch<T extends Record<string, unknown>>(): SetSearchFn<T>;
 
 export interface SearchParamsResult<T extends Record<string, string> = Record<string, string>> {
   searchParams: URLSearchParams;
@@ -316,3 +451,24 @@ export interface DevServer {
 export declare function createDevServer(options?: DevServerOptions): Promise<DevServer>;
 
 export declare function loadUserConfig(): Promise<Partial<BractJSConfig>>;
+
+/** Identity helper for bractjs.config.ts — wrap your default export for autocomplete + type-checking. */
+export declare function defineConfig(config: Partial<BractJSConfig>): Partial<BractJSConfig>;
+
+// ── Prerendering / SPA shell ──────────────────────────────────────────────
+export interface PrerenderOptions {
+  prerender: string[] | (() => string[] | Promise<string[]>);
+  appDir?: string;
+  publicDir?: string;
+  buildDir?: string;
+  manifest?: ServerManifest;
+}
+export interface PrerenderResult { written: string[] }
+/** Build-time prerendering (SSG): write HTML + /_data payloads under `<buildDir>/client/_prerender/`. */
+export declare function runPrerender(options: PrerenderOptions): Promise<PrerenderResult>;
+/** Render the SPA-mode document shell (config `ssr: false`). */
+export declare function renderSpaShell(
+  appDir: string,
+  manifest: ServerManifest,
+  registry?: ModuleRegistry,
+): Promise<string>;

package/types/route.d.ts

@@ -1,15 +1,47 @@
 import type { ComponentType } from "react";
 
-export interface LoaderArgs {
+/** A parsed navigation location (see `useLocation`). `hash` is always "" during SSR. */
+export interface RouterLocation {
+  pathname: string;
+  /** Raw query string including the leading `?`, or `""`. */
+  search: string;
+  /** Fragment including the leading `#`, or `""`. */
+  hash: string;
+  state: unknown;
+  key: string;
+}
+
+export interface LoaderArgs<TSearch extends Record<string, unknown> = Record<string, unknown>> {
   request: Request;
   params: Record<string, string>;
   context: Record<string, unknown>;
+  /**
+   * The request's search params, validated/coerced by the route's
+   * `searchSchema` export when present; otherwise the raw string record
+   * (repeated keys become arrays). Parameterize to skip the cast:
+   * `loader({ search }: LoaderArgs<BoardSearch>)`.
+   */
+  search: TSearch;
 }
 
-export interface ActionArgs extends LoaderArgs {
+export interface ActionArgs<TSearch extends Record<string, unknown> = Record<string, unknown>>
+  extends LoaderArgs<TSearch> {
   formData: FormData;
 }
 
+/**
+ * The data a route's loader resolves to, for typing `useLoaderData`. Pass the
+ * loader function type to infer it (`useLoaderData<typeof loader>()` →
+ * awaited return, `Response` excluded, `Deferred` fields preserved). A plain
+ * object type is returned as-is (back-compat).
+ */
+export type LoaderData<T> = T extends (...args: never[]) => unknown
+  ? Exclude<Awaited<ReturnType<T>>, Response>
+  : T;
+
+/** The data a route's action resolves to, for typing `useActionData`. See {@link LoaderData}. */
+export type ActionData<T> = LoaderData<T>;
+
 export type MetaDescriptor =
   | { title: string }
   | { name: string; content: string }
@@ -35,17 +67,45 @@ export interface BeforeLoadArgs {
   params: Record<string, string>;
   context: Record<string, unknown>;
   location: { pathname: string; search: string };
+  /** Validated search params (server-side only; absent in the client-side guard). */
+  search?: Record<string, unknown>;
 }
 
 export type BeforeLoadFunction = (
   args: BeforeLoadArgs,
 ) => void | Response | Promise<void | Response>;
 
+/**
+ * Decide whether loader data should be refetched (SWR background refetch and
+ * post-mutation revalidation). Return `args.defaultShouldRevalidate` (true)
+ * for the default behavior.
+ */
+export interface ShouldRevalidateArgs {
+  currentUrl: URL;
+  nextUrl: URL;
+  formMethod?: string;
+  actionStatus?: number;
+  defaultShouldRevalidate: boolean;
+}
+
+export type ShouldRevalidateFunction = (args: ShouldRevalidateArgs) => boolean;
+
 export interface RouteModule<TLoader = unknown, TAction = unknown> {
   loader?: LoaderFunction<TLoader>;
   action?: ActionFunction<TAction>;
   meta?: MetaFunction<TLoader>;
   beforeLoad?: BeforeLoadFunction;
+  shouldRevalidate?: ShouldRevalidateFunction;
+  /** Zod/Valibot-compatible schema validating search params before loaders run (400 on failure). */
+  searchSchema?: unknown;
+  /**
+   * Selective SSR: `true` (default) full SSR; `"data-only"` loaders run on the
+   * server but the component renders client-only; `false` neither the route
+   * loader nor the component runs during document SSR (beforeLoad still does).
+   */
+  ssr?: boolean | "data-only";
+  /** SSR'd in the component's place for `ssr: false` / `"data-only"` routes. */
+  Fallback?: ComponentType;
   handle?: Record<string, unknown>;
   ErrorBoundary?: ComponentType<{ error: unknown }>;
   default?: ComponentType;