@paramour-js/next 0.3.0 → 0.4.0

package/README.md

@@ -0,0 +1,48 @@
+# @paramour-js/next
+
+The Next.js integration for [paramour](https://paramour.dev):
+`withTypedRoutes` (build-time registry generation and drift checking),
+typed client hooks for both routers, and the `paramour` CLI
+(`generate` / `check` / `init` / `list` / `doctor`).
+
+```sh
+pnpm add paramour @paramour-js/next
+```
+
+Wrap your Next config so the route registry regenerates on dev and is
+enforced on build:
+
+```ts
+// next.config.ts
+import { withTypedRoutes } from "@paramour-js/next";
+
+export default withTypedRoutes({}, { strict: true });
+```
+
+Client components read the URL through hooks that take the same route
+object as everything else:
+
+```tsx
+"use client";
+
+import { useSearch } from "@paramour-js/next/app";
+
+import { productRoute } from "./route.def";
+
+export function FilterSummary() {
+  const search = useSearch(productRoute);
+  if (search.status === "error") return <p role="alert">Bad filters</p>;
+  return <p>query: {search.data.q ?? "none"}</p>;
+}
+```
+
+## Docs
+
+- [Getting started](https://paramour.dev/docs/getting-started)
+- [Next API reference](https://paramour.dev/docs/reference/next)
+- [CLI reference](https://paramour.dev/docs/reference/next/cli)
+- [Hooks guide](https://paramour.dev/docs/guides/hooks)
+
+## License
+
+MIT © Jason Paff

package/dist/app.js

@@ -1,13 +1,16 @@
 "use client";
 import { useParams, usePathname, useRouter, useSearchParams, } from "next/navigation";
 import { decodeParams, decodeSearch, ParamsDecodeError, safeDecodeParams, safeDecodeSearch, SearchDecodeError, } from "paramour";
+import { useContext } from "react";
 import { searchWireSnapshot } from "./devtools-seam.js";
+import { AppNavigationContext, } from "./navigation-adapter.js";
 import { makeAppNavigate, useDevtoolsEmitter, } from "./observe.js";
 import { paramsFingerprint, searchParamsFingerprint, useSelectedResult, useSelectedValue, useStableResult, } from "./select.js";
 export function useRouteParams(route, options) {
-    const params = useParams() ?? {};
-    const router = useRouter();
-    const pathname = usePathname();
+    const nav = useAppNavigation();
+    const params = nav.useParams() ?? {};
+    const router = nav.useRouter();
+    const pathname = nav.usePathname();
     const emitter = useDevtoolsEmitter();
     const spec = process.env.NODE_ENV === "production"
         ? undefined
@@ -33,9 +36,10 @@ export function useRouteParams(route, options) {
     return useSelectedResult(result, options);
 }
 export function useRouteParamsOrThrow(route, options) {
-    const params = useParams() ?? {};
-    const router = useRouter();
-    const pathname = usePathname();
+    const nav = useAppNavigation();
+    const params = nav.useParams() ?? {};
+    const router = nav.useRouter();
+    const pathname = nav.usePathname();
     const emitter = useDevtoolsEmitter();
     const spec = process.env.NODE_ENV === "production"
         ? undefined
@@ -77,9 +81,10 @@ export function useRouteParamsOrThrow(route, options) {
     return useSelectedValue(value, options);
 }
 export function useSearch(route, options) {
-    const searchParams = useSearchParams();
-    const router = useRouter();
-    const pathname = usePathname();
+    const nav = useAppNavigation();
+    const searchParams = nav.useSearchParams();
+    const router = nav.useRouter();
+    const pathname = nav.usePathname();
     const emitter = useDevtoolsEmitter();
     const spec = process.env.NODE_ENV === "production"
         ? undefined
@@ -105,9 +110,10 @@ export function useSearch(route, options) {
     return useSelectedResult(result, options);
 }
 export function useSearchOrThrow(route, options) {
-    const searchParams = useSearchParams();
-    const router = useRouter();
-    const pathname = usePathname();
+    const nav = useAppNavigation();
+    const searchParams = nav.useSearchParams();
+    const router = nav.useRouter();
+    const pathname = nav.usePathname();
     const emitter = useDevtoolsEmitter();
     const spec = process.env.NODE_ENV === "production"
         ? undefined
@@ -156,3 +162,25 @@ export function useSearchOrThrow(route, options) {
     }
     return useSelectedValue(value, options);
 }
+/**
+ * Real-Next fallback for the adapter seam (design-16 TA3): the /testing
+ * provider overrides these reads through {@link AppNavigationContext}; with
+ * no provider mounted the context's `null` default resolves here, so
+ * production behavior (and this module's `next/navigation`-only bundle
+ * graph, per dist.test.ts) is unchanged.
+ */
+const realAppAdapter = {
+    useParams,
+    usePathname,
+    useRouter,
+    useSearchParams,
+};
+/**
+ * Every hook resolves the adapter ONCE at its top and calls the adapter's
+ * reads unconditionally, exactly where the direct Next calls previously sat
+ * — hook call order is identical across renders and across provider
+ * presence (TA4).
+ */
+function useAppNavigation() {
+    return useContext(AppNavigationContext) ?? realAppAdapter;
+}

package/dist/navigation-adapter.d.ts

@@ -0,0 +1,60 @@
+import type { ParamsSource } from "paramour";
+/**
+ * Adapter seam for the client hooks' framework reads (design-16 TA1): each
+ * flavor's hooks resolve Next through a React context so the /testing entry
+ * can override the reads without runner-specific module mocking.
+ * Deliberately NO `"use client"` directive — app.ts (which carries one) and
+ * pages.ts (which must not, PR2) both import from here, like
+ * observe.ts/select.ts; the directive belongs on the entry modules, not a
+ * shared leaf.
+ *
+ * This module is Next-free on purpose (TA3): the contexts default to `null`
+ * and each flavor ENTRY supplies its own real-Next fallback
+ * (`useContext(ctx) ?? realAdapter`), so neither this module nor the
+ * /testing entry ever drags a `next/*` specifier into its graph. The
+ * dist.test.ts bundle-hygiene invariants (/app reaches only
+ * `next/navigation`, /pages only `next/router.js`, /testing neither) depend
+ * on exactly this split — a context whose DEFAULT VALUE were the real
+ * adapter would break all three.
+ */
+/**
+ * App-flavor adapter: EXACTLY the ambient view of `next/navigation` declared
+ * in `src/types/next-navigation.d.ts` — that ambient is the contract of
+ * record, and this interface must stay in lockstep with it (TA2; the
+ * `examples/next-compat` pins guard the real-Next side). `useParams()`'s
+ * `null` arm is the outside-App-Router-tree state (Next #48058 family) the
+ * hooks deliberately tolerate; `useRouter().replace`/`usePathname` are the
+ * devtools `navigate` capability's write path and resolution base (DT8).
+ */
+export interface AppNavigationAdapter {
+    useParams(): null | ParamsSource;
+    usePathname(): string;
+    useRouter(): {
+        replace(href: string): void;
+    };
+    useSearchParams(): URLSearchParams;
+}
+/**
+ * Pages-flavor adapter: EXACTLY the ambient view of `next/router.js`
+ * declared in `src/types/next-router.d.ts` — that ambient is the contract of
+ * record, and this interface must stay in lockstep with it (TA2). The
+ * ambient's throw-on-unmounted behavior under `app/` (PR5) is part of the
+ * contract: adapter implementations reproduce it by THROWING from
+ * `useRouter()`, which pages.ts translates.
+ */
+export interface PagesNavigationAdapter {
+    useRouter(): {
+        asPath: string;
+        isReady: boolean;
+        query: ParamsSource;
+        replace(url: string): Promise<boolean>;
+    };
+}
+/**
+ * The `null` default is load-bearing (TA3): with no provider mounted,
+ * app.ts falls back to its real `next/navigation` adapter — zero markup and
+ * zero behavior change in production (TA4).
+ */
+export declare const AppNavigationContext: import("react").Context<AppNavigationAdapter | null>;
+/** The pages twin; `null` default load-bearing for the same TA3 reasons. */
+export declare const PagesNavigationContext: import("react").Context<PagesNavigationAdapter | null>;

package/dist/navigation-adapter.js

@@ -0,0 +1,9 @@
+import { createContext } from "react";
+/**
+ * The `null` default is load-bearing (TA3): with no provider mounted,
+ * app.ts falls back to its real `next/navigation` adapter — zero markup and
+ * zero behavior change in production (TA4).
+ */
+export const AppNavigationContext = createContext(null);
+/** The pages twin; `null` default load-bearing for the same TA3 reasons. */
+export const PagesNavigationContext = createContext(null);

package/dist/pages.js

@@ -6,7 +6,9 @@
 // every bundler. Guarded by the examples/next-compat build-app.
 import { useRouter } from "next/router.js";
 import { ParamourError, safeDecodeParams, safeDecodeSearch, } from "paramour";
+import { useContext } from "react";
 import { recordWireSnapshot } from "./devtools-seam.js";
+import { PagesNavigationContext, } from "./navigation-adapter.js";
 import { makePagesNavigate, useDevtoolsEmitter, } from "./observe.js";
 import { paramsFingerprint, PENDING_FINGERPRINT, queryFingerprint, useSelectedResult, useStableResult, } from "./select.js";
 /** Referentially stable across every pending render. */
@@ -99,17 +101,31 @@ function omitPathParams(query, route) {
     }
     return Object.fromEntries(Object.entries(query).filter(([key]) => !names.has(key)));
 }
+/**
+ * Real-Next fallback for the adapter seam (design-16 TA3): the /testing
+ * provider overrides the read through {@link PagesNavigationContext}; with
+ * no provider mounted the context's `null` default resolves here, so
+ * production behavior (and this module's `next/router.js`-only bundle
+ * graph, per dist.test.ts) is unchanged. The adapter is resolved via an
+ * unconditional `useContext` BEFORE the try below, exactly where the direct
+ * call previously sat, keeping hook call order identical across renders and
+ * across provider presence (TA4).
+ */
+const realPagesAdapter = { useRouter };
 /**
  * `useRouter` with the one failure the brand cannot catch translated (PR5):
  * in a hybrid project a component rendered under `app/` can legally hold a
  * pages-branded route, but `next/router` has no mount there and throws
  * "NextRouter was not mounted" — a message pointing at the wrong fix
  * (component placement is invisible to the type system). Rethrow a
- * `ParamourError` naming the actual mistake; everything else propagates.
+ * `ParamourError` naming the actual mistake; everything else propagates —
+ * and the adapter's `useRouter()` stays INSIDE the try so a testing
+ * adapter's unmounted reproduction gets the same translation.
  */
 function usePagesRouter() {
+    const nav = useContext(PagesNavigationContext) ?? realPagesAdapter;
     try {
-        return useRouter();
+        return nav.useRouter();
     }
     catch (error) {
         if (error instanceof Error &&

package/dist/testing.d.ts

@@ -0,0 +1,72 @@
+import type { ParamsSource } from "paramour";
+import type { ReactElement, ReactNode } from "react";
+/**
+ * `@paramour-js/next/testing` (design-16): a provider that overrides the
+ * hooks' framework reads through the adapter seam (TA1), so client
+ * components calling `useSearch`/`useRouteParams` (either flavor) can be
+ * unit-tested without runner-specific `next/*` module mocking. One provider
+ * feeds BOTH flavor contexts (TA5) — hybrid apps and pages components need
+ * no second import. Server code needs none of this: `parse`/`safeParse` and
+ * server components are pure functions over props (TA8).
+ *
+ * This module imports ONLY react and the (Next-free) adapter-seam module —
+ * no `next/*` specifier and no `@testing-library/*` (TA5; dist.test.ts pins
+ * the bundle graph, and the hermeticity check there is why these docs never
+ * spell out the two Next specifiers). It carries `"use client"` like
+ * app.ts.
+ *
+ * Stability contract (TA4): the provider holds ONE adapter pair for its
+ * lifetime, created once and closing over a latest-props ref that is
+ * reassigned every render — prop changes mutate what the stable adapters
+ * RETURN, they never mint new adapters, so the hooks' context reads stay
+ * identity-stable and mid-test URL changes are driven by ordinary rerenders
+ * with new props.
+ */
+/**
+ * Input shape mirrors what Next hands the hooks (TA6) — no `url`
+ * reverse-matching in v1 (deferred: needs a core matcher). `params: null`
+ * and `mounted: false` are first-class because they are the two states
+ * nobody hand-rolling a mock models.
+ */
+export interface ParamourTestingOptions {
+    /**
+     * Pages flavor only: `false` is the pre-hydration state of a
+     * statically-optimized page (`query` not yet populated — the PR5
+     * `pending` arm). Defaults to `true`. design-16 listed this as deferred,
+     * but TA7 migrates the whole pages suite — which pins the pending arm —
+     * to this provider, so it was promoted from the deferred list.
+     */
+    isReady?: boolean;
+    /**
+     * Pages flavor only: `false` reproduces the pages router's
+     * throw-on-unmounted state under `app/` (PR5) — pages.ts translates it to
+     * a `ParamourError` naming the actual mistake.
+     */
+    mounted?: boolean;
+    /** Captures `replace(href)` from either flavor's router. */
+    onReplace?: (href: string) => void;
+    /**
+     * `null` is the hybrid-app `useParams()` state outside an App-Router tree
+     * (Next #48058 family) and passes through as `null`; omitted means `{}`.
+     */
+    params?: null | ParamsSource;
+    /** Defaults to `"/"`. */
+    pathname?: string;
+    /** `"?page=2"` and `"page=2"` are both accepted. */
+    search?: string | URLSearchParams;
+}
+/**
+ * Renders BOTH flavor contexts' providers around `children` (TA5). Exported
+ * for people composing their own wrappers (Storybook decorators, custom
+ * render helpers); testing-library users want {@link withParamourTesting}.
+ */
+export declare function ParamourTestingProvider(props: ParamourTestingOptions & {
+    children?: ReactNode;
+}): ReactElement;
+/**
+ * Wrapper-component form for testing-library's `wrapper` option (TA5,
+ * mirroring `withNuqsTestingAdapter`).
+ */
+export declare function withParamourTesting(options?: ParamourTestingOptions): (props: {
+    children?: ReactNode;
+}) => ReactElement;

package/dist/testing.js

@@ -0,0 +1,113 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef, useState } from "react";
+import { AppNavigationContext, PagesNavigationContext, } from "./navigation-adapter.js";
+/**
+ * Renders BOTH flavor contexts' providers around `children` (TA5). Exported
+ * for people composing their own wrappers (Storybook decorators, custom
+ * render helpers); testing-library users want {@link withParamourTesting}.
+ */
+export function ParamourTestingProvider(props) {
+    // Latest-ref pattern (TA4): reassigned every render so the stable
+    // adapters below always read the CURRENT render's props.
+    const latest = useRef(props);
+    latest.current = props;
+    const [adapters] = useState(() => createAdapters(latest));
+    return (_jsx(AppNavigationContext.Provider, { value: adapters.app, children: _jsx(PagesNavigationContext.Provider, { value: adapters.pages, children: props.children }) }));
+}
+/**
+ * Wrapper-component form for testing-library's `wrapper` option (TA5,
+ * mirroring `withNuqsTestingAdapter`).
+ */
+export function withParamourTesting(options = {}) {
+    return function ParamourTestingWrapper({ children, }) {
+        return (_jsx(ParamourTestingProvider, { ...options, children: children }));
+    };
+}
+/**
+ * The one adapter pair a provider instance ever holds (TA4). Every read
+ * defers to `latest.current`, so the adapters are stable while their
+ * answers track prop updates. Fresh `URLSearchParams` per call is fine —
+ * the hooks fingerprint the declared slice (SEL4), not the instance.
+ */
+function createAdapters(latest) {
+    const app = {
+        useParams() {
+            const { params } = latest.current;
+            // `null` must pass through as-is — it is the hybrid-app state the
+            // app hooks deliberately tolerate; only OMITTED means `{}`.
+            return params === undefined ? {} : params;
+        },
+        usePathname() {
+            return latest.current.pathname ?? "/";
+        },
+        useRouter() {
+            return {
+                replace(href) {
+                    latest.current.onReplace?.(href);
+                },
+            };
+        },
+        useSearchParams() {
+            return new URLSearchParams(normalizeSearch(latest.current.search));
+        },
+    };
+    const pages = {
+        useRouter() {
+            const options = latest.current;
+            if (options.mounted === false) {
+                // Verbatim prefix of next/router's real unmounted error — pages.ts
+                // matches on the message to translate it (PR5).
+                throw new Error("NextRouter was not mounted. https://nextjs.org/docs/messages/next-router-not-mounted");
+            }
+            const search = normalizeSearch(options.search);
+            return {
+                // asPath derives from pathname + normalized search (TA6) —
+                // basePath-relative, what the devtools navigate capability resolves
+                // against (DT8).
+                asPath: (options.pathname ?? "/") + (search === "" ? "" : `?${search}`),
+                isReady: options.isReady ?? true,
+                query: mergedQuery(options),
+                replace(url) {
+                    latest.current.onReplace?.(url);
+                    // Real next/router resolves `true` on a completed replace (TA6).
+                    return Promise.resolve(true);
+                },
+            };
+        },
+    };
+    return { app, pages };
+}
+/**
+ * The merged `query` bag real Next hands the pages router: search entries
+ * first (single value → scalar, repeats → `string[]`), then `params`
+ * entries override — path params win, mirroring real Next's merge.
+ * Entries → fromEntries for define-semantics, so a hostile `"__proto__"`
+ * key stays an ordinary own property (omitPathParams's ethos in pages.ts).
+ */
+function mergedQuery(options) {
+    const entries = [];
+    const searchParams = new URLSearchParams(normalizeSearch(options.search));
+    for (const key of new Set(searchParams.keys())) {
+        const values = searchParams.getAll(key);
+        const first = values[0];
+        // Unreachable for a key yielded by keys(); satisfies
+        // noUncheckedIndexedAccess without a cast.
+        if (first === undefined)
+            continue;
+        entries.push([key, values.length === 1 ? first : values]);
+    }
+    for (const entry of Object.entries(options.params ?? {})) {
+        entries.push(entry);
+    }
+    return Object.fromEntries(entries);
+}
+/** `undefined` → `""`; `URLSearchParams` → its string; strip one leading `?`. */
+function normalizeSearch(search) {
+    if (search === undefined)
+        return "";
+    if (typeof search === "string") {
+        return search.startsWith("?") ? search.slice(1) : search;
+    }
+    return search.toString();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paramour-js/next",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": {
@@ -17,6 +17,10 @@
     "./pages": {
       "types": "./dist/pages.d.ts",
       "default": "./dist/pages.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "sideEffects": false,
@@ -30,7 +34,7 @@
     "jiti": "^2.7.0",
     "magicast": "^0.3.5",
     "tinyglobby": "^0.2.15",
-    "paramour": "0.5.0"
+    "paramour": "0.5.1"
   },
   "peerDependencies": {
     "next": ">=15",
@@ -50,13 +54,23 @@
   },
   "description": "Next.js integration for paramour: withTypedRoutes, App and Pages Router hooks, PageProps glue, and the codegen CLI.",
   "author": "Jason Paff <jasonpaff@gmail.com>",
+  "keywords": [
+    "nextjs",
+    "app-router",
+    "typescript",
+    "routing",
+    "type-safe",
+    "typed-routes",
+    "cli",
+    "codegen"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/JasonPaff/paramour.git",
     "directory": "packages/next"
   },
-  "homepage": "https://github.com/JasonPaff/paramour#readme",
+  "homepage": "https://paramour.dev/docs/reference/next",
   "bugs": {
     "url": "https://github.com/JasonPaff/paramour/issues"
   },