next-modal-router 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import * as react from 'react';
+import { AnchorHTMLAttributes, ReactNode } from 'react';
+import { LinkProps } from 'next/link';
+import { ReadonlyURLSearchParams } from 'next/navigation';
+
+type OverlayLinkProps = LinkProps & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, keyof LinkProps> & {
+    fallback?: string;
+};
+declare const OverlayLink: react.ForwardRefExoticComponent<LinkProps<any> & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, keyof LinkProps<any>> & {
+    fallback?: string;
+} & react.RefAttributes<HTMLAnchorElement>>;
+
+type SearchParamValue = string | number | boolean | null | undefined;
+type SearchParamUpdates = Readonly<Record<string, SearchParamValue | readonly SearchParamValue[]>>;
+declare function updateSearchParams(current: URLSearchParams | string, updates: SearchParamUpdates): URLSearchParams;
+declare function withSearchParams(pathname: string, current: URLSearchParams | string, updates: SearchParamUpdates): string;
+
+interface OverlayNavigationOptions {
+    fallback?: string;
+    scroll?: boolean;
+}
+interface OverlayState {
+    isOpen: boolean;
+    isOverlayNavigation: boolean;
+    pathname: string;
+    previousPathname?: string;
+    depth: number;
+    fallback?: string;
+    canGoBackSafely: boolean;
+}
+interface OverlayRouter extends OverlayState {
+    searchParams: ReadonlyURLSearchParams;
+    open(href: string, options?: OverlayNavigationOptions): void;
+    replace(href: string, options?: OverlayNavigationOptions): void;
+    close(fallback?: string): void;
+    back(): void;
+    forward(): void;
+    refresh(): void;
+    setSearchParams(updates: SearchParamUpdates, options?: {
+        scroll?: boolean;
+    }): void;
+}
+
+interface OverlayRouterProviderProps {
+    children: ReactNode;
+    defaultFallback?: string;
+    restoreFocus?: boolean;
+}
+declare function OverlayRouterProvider({ children, defaultFallback, restoreFocus }: OverlayRouterProviderProps): react.JSX.Element;
+
+declare function useOverlayRouter(): OverlayRouter;
+
+declare function useOverlayState(): OverlayState;
+
+declare const OVERLAY_TYPES: readonly ["modal", "drawer", "sheet", "panel", "custom"];
+type OverlayType = (typeof OVERLAY_TYPES)[number];
+interface OverlayDefinition {
+    route: string;
+    source: string;
+    type: OverlayType;
+    slot?: string;
+    closeFallback: string;
+}
+interface OverlayConfig<T extends Record<string, OverlayDefinition> = Record<string, OverlayDefinition>> {
+    defaultSlot?: string;
+    overlays: T;
+}
+
+type RouteSegmentKind = "static" | "dynamic" | "catch-all" | "optional-catch-all" | "group" | "slot";
+interface RouteSegment {
+    raw: string;
+    kind: RouteSegmentKind;
+    name: string;
+    contributesToUrl: boolean;
+}
+
+type IssueSeverity = "error" | "warning" | "info";
+interface ValidationIssue {
+    code: string;
+    severity: IssueSeverity;
+    message: string;
+    path?: string;
+    overlay?: string;
+    suggestion?: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    issues: ValidationIssue[];
+}
+
+export { type OverlayConfig, type OverlayDefinition, OverlayLink, type OverlayLinkProps, type OverlayNavigationOptions, type OverlayRouter, OverlayRouterProvider, type OverlayRouterProviderProps, type OverlayState, type OverlayType, type RouteSegment, type RouteSegmentKind, type SearchParamUpdates, type SearchParamValue, type ValidationIssue, type ValidationResult, updateSearchParams, useOverlayRouter, useOverlayState, withSearchParams };

package/dist/index.js

@@ -0,0 +1,166 @@
+"use client";
+
+// src/runtime/overlay-link.tsx
+import Link from "next/link";
+import { forwardRef } from "react";
+
+// src/runtime/context.tsx
+import { createContext, useCallback, useContext, useMemo, useRef, useState } from "react";
+import { usePathname } from "next/navigation";
+import { jsx } from "react/jsx-runtime";
+var OverlayContext = createContext(null);
+function pathnameOf(href) {
+  try {
+    return new URL(href, "http://nmr.local").pathname;
+  } catch {
+    return href.split("?")[0] ?? href;
+  }
+}
+function activeEntries(entries, pathname) {
+  let index = -1;
+  for (let cursor = entries.length - 1; cursor >= 0; cursor -= 1) {
+    if (entries[cursor]?.pathname === pathname) {
+      index = cursor;
+      break;
+    }
+  }
+  return index < 0 ? [] : entries.slice(0, index + 1);
+}
+function OverlayRouterProvider({ children, defaultFallback, restoreFocus = true }) {
+  const pathname = usePathname();
+  const [entries, setEntries] = useState([]);
+  const previous = useRef(void 0);
+  const lastPath = useRef(pathname);
+  if (lastPath.current !== pathname) {
+    previous.current = lastPath.current;
+    lastPath.current = pathname;
+  }
+  const mark = useCallback((href, fallback) => {
+    const active2 = typeof document === "undefined" ? void 0 : document.activeElement instanceof HTMLElement ? document.activeElement : void 0;
+    const resolvedFallback = fallback ?? defaultFallback;
+    setEntries((current) => [...activeEntries(current, pathname), { href, pathname: pathnameOf(href), ...resolvedFallback ? { fallback: resolvedFallback } : {}, ...active2 ? { trigger: active2 } : {} }]);
+  }, [defaultFallback, pathname]);
+  const replaceMark = useCallback((href, fallback) => {
+    setEntries((current) => {
+      const active2 = activeEntries(current, pathname);
+      const resolvedFallback = fallback ?? active2.at(-1)?.fallback ?? defaultFallback;
+      return [...active2.slice(0, -1), { href, pathname: pathnameOf(href), ...resolvedFallback ? { fallback: resolvedFallback } : {} }];
+    });
+  }, [defaultFallback, pathname]);
+  const pop = useCallback(() => {
+    const removed = activeEntries(entries, pathname).at(-1);
+    if (restoreFocus) queueMicrotask(() => removed?.trigger?.isConnected && removed.trigger.focus());
+    return removed;
+  }, [entries, pathname, restoreFocus]);
+  const active = activeEntries(entries, pathname);
+  const top = active.at(-1);
+  const value = useMemo(() => ({
+    isOpen: active.length > 0,
+    isOverlayNavigation: active.length > 0,
+    pathname,
+    ...previous.current ? { previousPathname: previous.current } : {},
+    depth: active.length,
+    ...top?.fallback ? { fallback: top.fallback } : {},
+    canGoBackSafely: Boolean(top && top.pathname === pathname),
+    mark,
+    replaceMark,
+    pop
+  }), [active.length, mark, pathname, pop, replaceMark, top]);
+  return /* @__PURE__ */ jsx(OverlayContext.Provider, { value, children });
+}
+function useOverlayContext() {
+  const context = useContext(OverlayContext);
+  if (!context) throw new Error("next-modal-router hooks and OverlayLink must be rendered inside OverlayRouterProvider.");
+  return context;
+}
+
+// src/runtime/overlay-link.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+function hrefString(href) {
+  if (typeof href === "string") return href;
+  const query = href.query ? new URLSearchParams(Object.entries(href.query).flatMap(([key, value]) => Array.isArray(value) ? value.map((item) => [key, String(item)]) : value == null ? [] : [[key, String(value)]])).toString() : "";
+  return `${href.pathname ?? ""}${query ? `?${query}` : ""}${href.hash ?? ""}`;
+}
+var OverlayLink = forwardRef(function OverlayLink2({ fallback, onClick, scroll = false, ...props }, ref) {
+  const context = useOverlayContext();
+  const handleClick = (event) => {
+    onClick?.(event);
+    if (!event.defaultPrevented && event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey) context.mark(hrefString(props.href), fallback);
+  };
+  return /* @__PURE__ */ jsx2(Link, { ...props, ref, scroll, onClick: handleClick });
+});
+
+// src/runtime/use-overlay-router.ts
+import { useCallback as useCallback2, useMemo as useMemo2 } from "react";
+import { useRouter, useSearchParams } from "next/navigation";
+
+// src/runtime/history.ts
+function decideSafeClose(input) {
+  if (input.depth > 0 && input.entryPathname === input.currentPathname) return { action: "back" };
+  if (input.fallback) return { action: "replace", href: input.fallback };
+  return { action: "replace", href: "/" };
+}
+
+// src/runtime/search-params.ts
+function updateSearchParams(current, updates) {
+  const result = new URLSearchParams(current);
+  for (const [key, raw] of Object.entries(updates)) {
+    result.delete(key);
+    const values = Array.isArray(raw) ? raw : [raw];
+    for (const value of values) if (value !== null && value !== void 0) result.append(key, String(value));
+  }
+  result.sort();
+  return result;
+}
+function withSearchParams(pathname, current, updates) {
+  const query = updateSearchParams(current, updates).toString();
+  return query ? `${pathname}?${query}` : pathname;
+}
+
+// src/runtime/use-overlay-router.ts
+function useOverlayRouter() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const context = useOverlayContext();
+  const open = useCallback2((href, options) => {
+    context.mark(href, options?.fallback);
+    router.push(href, { scroll: options?.scroll ?? false });
+  }, [context, router]);
+  const replace = useCallback2((href, options) => {
+    context.replaceMark(href, options?.fallback);
+    router.replace(href, { scroll: options?.scroll ?? false });
+  }, [context, router]);
+  const close = useCallback2((fallback) => {
+    const resolvedFallback = fallback ?? context.fallback;
+    const decision = decideSafeClose({ depth: context.depth, currentPathname: context.pathname, ...context.canGoBackSafely ? { entryPathname: context.pathname } : {}, ...resolvedFallback ? { fallback: resolvedFallback } : {} });
+    context.pop();
+    if (decision.action === "back") router.back();
+    else router.replace(decision.href, { scroll: false });
+  }, [context, router]);
+  const setSearchParams = useCallback2((updates, options) => {
+    router.replace(withSearchParams(context.pathname, searchParams.toString(), updates), { scroll: options?.scroll ?? false });
+  }, [context.pathname, router, searchParams]);
+  return useMemo2(() => ({ ...context, searchParams, open, replace, close, back: router.back, forward: router.forward, refresh: router.refresh, setSearchParams }), [close, context, open, replace, router.back, router.forward, router.refresh, searchParams, setSearchParams]);
+}
+
+// src/runtime/use-overlay-state.ts
+function useOverlayState() {
+  const context = useOverlayContext();
+  return {
+    isOpen: context.isOpen,
+    isOverlayNavigation: context.isOverlayNavigation,
+    pathname: context.pathname,
+    ...context.previousPathname ? { previousPathname: context.previousPathname } : {},
+    depth: context.depth,
+    ...context.fallback ? { fallback: context.fallback } : {},
+    canGoBackSafely: context.canGoBackSafely
+  };
+}
+export {
+  OverlayLink,
+  OverlayRouterProvider,
+  updateSearchParams,
+  useOverlayRouter,
+  useOverlayState,
+  withSearchParams
+};

package/docs/cli.md

@@ -0,0 +1,16 @@
+# CLI reference
+
+The `next-modal-router` binary has five commands: `init`, `add`, `check`, `doctor`, and `list`. Run `next-modal-router help` for compact syntax.
+
+Generation commands support `--dry-run` and refuse meaningful overwrites unless the requested operation uses `--force`. Analysis commands support `--format json`; JSON contains no ANSI formatting. `--cwd` targets an application inside a monorepo.
+
+Exit codes are `0` for success, `1` for route validation errors, and `2` for invalid invocation, unreadable configuration, or protected-file conflicts.
+
+## Automation
+
+```bash
+next-modal-router add product --route /products/[id] --source /products --type modal --slot modal --fallback /products --ci
+next-modal-router check --format json --ci
+```
+
+Quote dynamic routes in shells that expand brackets. See the README for every command, flag, and example output.

package/docs/concepts.md

@@ -0,0 +1,17 @@
+# Concepts
+
+`next-modal-router` separates three responsibilities. Next.js owns URL matching, server rendering, soft navigation, and browser history. The CLI owns filesystem generation and static validation. The runtime records only overlay navigation initiated through its public API.
+
+## Parallel slots
+
+A directory named `@modal` becomes a named layout prop. Its `default.tsx` must return `null` when no intercepted child is active. The slot does not add a URL segment.
+
+## Interception
+
+`(.)products/[id]` targets a sibling route segment from the layout that owns the slot. `(..)` climbs one route segment, repeated forms climb multiple segments, and `(...)` targets from the app root. Route groups and parallel slots do not count as URL segments.
+
+## Navigation modes
+
+Soft navigation can preserve the current page and render the target through a slot. A refresh or direct request renders the ordinary target page. Both modes intentionally share the same URL.
+
+The library never attempts to turn a hard navigation into a client-only modal.

package/docs/configuration.md

@@ -0,0 +1,24 @@
+# Configuration
+
+The generated `next-modal-router.config.ts` uses `defineConfig` for literal inference. `.mts`, `.js`, and `.mjs` are also discovered.
+
+```ts
+import { defineConfig } from "next-modal-router/config"
+
+export default defineConfig({
+  defaultSlot: "modal",
+  overlays: {
+    product: {
+      route: "/products/[id]",
+      source: "/products",
+      type: "modal",
+      slot: "modal",
+      closeFallback: "/products",
+    },
+  },
+})
+```
+
+`route`, `source`, and `closeFallback` are absolute application routes. `slot` omits the leading `@`. `type` is one of `modal`, `drawer`, `sheet`, `panel`, or `custom` and has no visual runtime behavior. `defaultSlot` applies when a definition omits `slot`.
+
+Config files execute in the local development process, like Next.js config. The loader does not evaluate strings or accept remote configuration. Keep configuration deterministic for CI.

package/docs/limitations.md

@@ -0,0 +1,9 @@
+# Limitations
+
+`next-modal-router` orchestrates documented App Router behavior; it cannot alter when Next.js chooses an intercepted route.
+
+Browser APIs do not disclose arbitrary history destinations. Safe close therefore trusts only entries recorded by the current provider and otherwise replaces with a fallback. Navigations made through raw custom router calls are invisible to this marker.
+
+The generator targets root-owned parallel slots. The analyzer can discover nested existing slots, but unusual route trees may be maintained manually. Config-driven `add` serializes configuration to a stable static form and does not preserve comments or computed expressions.
+
+There is no focus trap, portal, animation engine, dialog markup, CSS, or server-side overlay state. Use an accessible UI library for those concerns.

package/docs/nested-overlays.md

@@ -0,0 +1,13 @@
+# Nested overlays
+
+Nested navigation remains URL-first:
+
+```text
+/products
+/products/42
+/products/42/reviews
+```
+
+Open each level through `OverlayLink` or `overlay.open`. The provider then reports depth `0`, `1`, and `2`, and safe close uses one native back operation per recorded current level.
+
+Visual stacking depends on the route tree. A second parallel slot can preserve two independent surfaces. When one slot replaces its own active page, render the parent modal shell in the deeper intercepted page if the design needs both surfaces visible. Do not build a detached local array of modal components: it will diverge from refresh, sharing, and browser history.

package/docs/troubleshooting.md

@@ -0,0 +1,29 @@
+# Troubleshooting
+
+## Modal remains visible after navigation
+
+The slot may be retaining its previous active segment. Add `@slot/default.tsx` returning `null`, and ensure the close action navigates rather than only toggling component state.
+
+## Missing `default.tsx`
+
+Every parallel slot needs a fallback for routes that do not match it. Run `next-modal-router check`; `NMR001` identifies the slot path.
+
+## Incorrect intercept depth
+
+Matchers count route segments. They do not count route groups such as `(shop)` or parallel slots such as `@modal`. Run `check --verbose` to compare found and expected paths.
+
+## Overlay appears on refresh
+
+The modal may live in an ordinary page or shared layout. Intercepted UI belongs under `@slot/(.)target`; the normal target page belongs outside the slot.
+
+## Overlay does not appear during soft navigation
+
+Confirm the slot is rendered by its owner layout and use `OverlayLink`, Next.js `Link`, or App Router navigation. A plain anchor can cause a hard request.
+
+## Back button leaves the website
+
+Replace unconditional `router.back()` with `overlay.close()` and provide a route fallback. Direct requests have no safe in-app previous entry the browser will disclose.
+
+## Parallel slot produces 404
+
+Pass the named slot prop through its layout, add a default route, and verify that the intercepted page filename is one of Next.js's supported page extensions.

package/docs/ui-libraries.md

@@ -0,0 +1,7 @@
+# UI-library integrations
+
+Routing controls whether the intercepted page exists. A UI library controls portal placement, focus trapping, escape handling, outside-click handling, animation, and visuals.
+
+For Radix or shadcn/ui, render the dialog in controlled mode with `open` and call `overlay.close()` when `onOpenChange` receives `false`. For Headless UI, pass `open` and `onClose={overlay.close}`. For sheet packages, use the equivalent controlled-open callback.
+
+Avoid a second persistent boolean as the source of truth. Navigation unmounts the intercepted route after close. If the UI library restores focus, set `restoreFocus={false}` on `OverlayRouterProvider` so only one system owns that behavior.

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "next-modal-router",
+  "version": "0.1.0",
+  "description": "URL-native modals, drawers and overlays for Next.js App Router — without the routing headache.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ali Ranjbar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RanjbarAli/next-modal-router.git"
+  },
+  "homepage": "https://github.com/RanjbarAli/next-modal-router#readme",
+  "bugs": {
+    "url": "https://github.com/RanjbarAli/next-modal-router/issues"
+  },
+  "keywords": [
+    "nextjs",
+    "next",
+    "react",
+    "modal",
+    "router",
+    "app-router",
+    "parallel-routes",
+    "intercepting-routes",
+    "drawer",
+    "sheet",
+    "overlay",
+    "routing"
+  ],
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "assets",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "package.json"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "next-modal-router": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "packageManager": "pnpm@10.15.0",
+  "peerDependencies": {
+    "next": ">=14.2 <17",
+    "react": ">=18.2 <20",
+    "react-dom": ">=18.2 <20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit && pnpm build && pnpm --dir examples/basic typecheck",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "example:build": "pnpm --dir examples/basic build",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm example:build",
+    "prepublishOnly": "pnpm check"
+  },
+  "dependencies": {
+    "jiti": "^2.5.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.35.0",
+    "@playwright/test": "^1.55.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.18.0",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.35.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "globals": "^16.3.0",
+    "next": "16.3.3",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.42.0",
+    "vitest": "^3.2.4"
+  }
+}