path-router-red 0.4.0

package/src/PathRouter/NavLink/NavLink.tsx

@@ -0,0 +1,146 @@
+import React, {
+  forwardRef,
+  type AnchorHTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+  type Ref,
+} from "react";
+import type { NavigateOptions } from "react-router-dom";
+
+import { usePath } from "../Provider/usePath";
+import { clearSlash } from "../utils/clearSlash";
+import type {
+  ModalNamesOf,
+  PathNamesOf,
+  RouterConfig,
+} from "../types";
+
+/** Internal — must match the splitter used by `PathProvider`. */
+const modalSplitter = "/modal/";
+
+export interface NavLinkProps<
+  C extends RouterConfig<any, any> = RouterConfig<any, any>,
+> extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  /**
+   * Target page path. If omitted, the current page is preserved
+   * (useful when you only want to open a modal).
+   */
+  to?: PathNamesOf<C>;
+  /** Modal to open on click. */
+  modal?: ModalNamesOf<C>;
+  /** Extra path segments appended after the modal name. */
+  modalBreadCrumbs?: string[];
+  /** Replace history entry instead of pushing a new one. */
+  replace?: boolean;
+  /** Extra options forwarded to the underlying `navigate`. */
+  navigateOptions?: NavigateOptions;
+  /** Class applied when this link matches the current location. */
+  activeClassName?: string;
+  children?: ReactNode;
+}
+
+const isModifiedEvent = (e: MouseEvent<HTMLAnchorElement>) =>
+  e.metaKey || e.ctrlKey || e.shiftKey || e.altKey;
+
+const NavLinkInner = forwardRef<HTMLAnchorElement, NavLinkProps>(
+  (
+    {
+      to,
+      modal,
+      modalBreadCrumbs,
+      replace,
+      navigateOptions,
+      className,
+      activeClassName,
+      onClick,
+      target,
+      children,
+      ...rest
+    },
+    ref,
+  ) => {
+    const { page, modal: modalCtx } = usePath();
+
+    /* ── Resolve the canonical href (always a real, shareable URL) ── */
+    const targetPagePath = to ? clearSlash(to as string) : page.path;
+    const tail = (modalBreadCrumbs || []).filter(Boolean).join("/");
+    const href = clearSlash(
+      modal
+        ? `${targetPagePath}${modalSplitter}${modal}${tail ? `/${tail}` : ""}`
+        : targetPagePath,
+    );
+
+    /* ── Active state ── */
+    const isPageActive = !to || page.path === targetPagePath;
+    const isModalActive = modal
+      ? modalCtx.isOpen && modalCtx.name === modal
+      : !modalCtx.isOpen || !to;
+    const isActive =
+      (!!to || !!modal) && isPageActive && (modal ? isModalActive : true);
+
+    /* ── Click handler: keep native behaviour for "open in new tab" ── */
+    const handleClick = (e: MouseEvent<HTMLAnchorElement>) => {
+      if (onClick) onClick(e);
+      if (e.defaultPrevented) return;
+
+      // Let the browser do its thing for non-primary buttons, modifier keys,
+      // or links explicitly targeted to another window/frame.
+      if (
+        e.button !== 0 ||
+        isModifiedEvent(e) ||
+        (target && target !== "_self")
+      ) {
+        return;
+      }
+
+      // Nothing to navigate to — behave as a regular anchor.
+      if (!to && !modal) return;
+
+      e.preventDefault();
+
+      const opts: NavigateOptions = { replace, ...navigateOptions };
+      // Single `navigate` call covers both "go to page" and
+      // "go to page + open modal" cases — the provider derives
+      // the modal state from the resulting pathname.
+      page.navigate(href as PathNamesOf<any>, opts);
+    };
+
+    return (
+      <a
+        {...rest}
+        ref={ref}
+        href={href}
+        target={target}
+        onClick={handleClick}
+        aria-current={isActive ? "page" : undefined}
+        data-active={isActive || undefined}
+        className={`${className || ''} ${(isActive && activeClassName) || ''}`}
+        >
+        {children}
+      </a>
+    );
+  },
+);
+
+NavLinkInner.displayName = "NavLink";
+
+/**
+ * Router-aware anchor.
+ *
+ * Renders a real `<a href>` (so right-click / "open in new tab" / SSR work)
+ * and intercepts the primary-button click to call `page.navigate` /
+ * open a modal through the `PathRouter` context.
+ *
+ * ```tsx
+ * <NavLink<typeof config> to="add">Add item</NavLink>
+ * <NavLink<typeof config> modal="confirm">Open confirm</NavLink>
+ * <NavLink<typeof config> to="users" modal="confirm" modalBreadCrumbs={["step-2"]}>
+ *   Go to users + open confirm at step 2
+ * </NavLink>
+ * ```
+ */
+export const NavLink = NavLinkInner as <
+  C extends RouterConfig<any, any> = RouterConfig<any, any>,
+>(
+  props: NavLinkProps<C> & { ref?: Ref<HTMLAnchorElement> },
+) => React.ReactElement | null;

package/src/PathRouter/NavLink/index.ts

@@ -0,0 +1,2 @@
+export { NavLink } from "./NavLink";
+export type { NavLinkProps } from "./NavLink";

package/src/PathRouter/Provider/PathProvider.tsx

@@ -0,0 +1,220 @@
+import React, { type FC, type ReactNode, useCallback, useMemo } from "react";
+import {
+  BrowserRouter,
+  type Location,
+  type NavigateOptions,
+  type To,
+  useLocation,
+  useNavigate,
+} from "react-router-dom";
+
+import {
+  type ModalState,
+  type PathContextType,
+  type SearchParams,
+  type SearchParamsState,
+} from "../types";
+import { clearSlash } from "../utils/clearSlash";
+import { parseSearchParams } from "../utils/parseSearch";
+import { PathContext } from "./context";
+
+export interface PathProviderProps {
+  children?: ReactNode;
+}
+
+const modalSplitter = "/modal/";
+
+const InnerProvider: FC<PathProviderProps> = ({ children }) => {
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  /** Derive page path & modal state from location.pathname (no extra render cycle). */
+  const { pagePath, modalState } = useMemo<{
+    pagePath: string;
+    modalState: ModalState;
+  }>(() => {
+    const [rawPagePath, modalPath] = location.pathname.split(modalSplitter) as [
+      string?,
+      string?,
+    ];
+
+    const segments = (modalPath || "").split("/").filter(Boolean);
+    const name = segments[0];
+    const breadCrumbs = segments.slice(1);
+
+    return {
+      pagePath: clearSlash(rawPagePath || "/"),
+      modalState: {
+        name,
+        breadCrumbs,
+        path: segments.join("/"),
+        isOpen: !!name,
+      },
+    };
+  }, [location.pathname]);
+
+  /** Derive search params from location.search. */
+  const searchParams = useMemo<SearchParams>(() => {
+    const usp = new URLSearchParams(location.search);
+    const out: SearchParams = {};
+    for (const [key, value] of usp.entries()) {
+      const arr = out[key];
+      if (!arr) out[key] = [value];
+      else arr.push(value);
+    }
+    return out;
+  }, [location.search]);
+
+  const setModal = useCallback(
+    (name: string, breadCrumbs?: string[]) => {
+      const tail = (breadCrumbs || []).filter(Boolean).join("/");
+      const next = clearSlash(
+        `${pagePath}${modalSplitter}${name}${tail ? `/${tail}` : ""}`,
+      );
+      navigate(next);
+    },
+    [navigate, pagePath],
+  );
+
+  const closeModal = useCallback(() => {
+    navigate(clearSlash(pagePath));
+  }, [navigate, pagePath]);
+
+  const setPath = useCallback(
+    (to: To, options?: NavigateOptions) => {
+      if (typeof to === "string") {
+        const next = clearSlash(to);
+        if (next === location.pathname) return;
+        navigate(next, options);
+      } else {
+        if (
+          to.pathname &&
+          to.pathname === location.pathname &&
+          (to.search ?? "") === location.search &&
+          (to.hash ?? "") === location.hash
+        ) {
+          return;
+        }
+        navigate(
+          {
+            ...to,
+            pathname: to.pathname ? clearSlash(to.pathname) : to.pathname,
+          },
+          options,
+        );
+      }
+    },
+    [navigate, location.pathname, location.search, location.hash],
+  );
+
+  const pageNavigate = useCallback(
+    (path: string, options?: NavigateOptions) => {
+      setPath(path as To, options);
+    },
+    [setPath],
+  );
+
+  /** Merge: string -> set, array -> append. Preserves hash. */
+  const changeSearchParams = useCallback(
+    (next: SearchParamsState) => {
+      navigate({
+        pathname: location.pathname,
+        search: parseSearchParams(next, location as Location).toString(),
+        hash: location.hash,
+      });
+    },
+    [navigate, location],
+  );
+
+  /** Replace fully: each provided key is overwritten with given value(s). */
+  const setSearchParams = useCallback(
+    (next: SearchParamsState) => {
+      const params = new URLSearchParams(location.search);
+      Object.entries(next).forEach(([key, value]) => {
+        params.delete(key);
+        if (typeof value === "string") {
+          params.append(key, value);
+        } else {
+          value.forEach((v) => params.append(key, v));
+        }
+      });
+      navigate({
+        pathname: location.pathname,
+        search: params.toString(),
+        hash: location.hash,
+      });
+    },
+    [navigate, location],
+  );
+
+  const deleteSearchParams = useCallback(
+    (key: string) => {
+      const params = new URLSearchParams(location.search);
+      params.delete(key);
+      navigate({
+        pathname: location.pathname,
+        search: params.toString(),
+        hash: location.hash,
+      });
+    },
+    [navigate, location],
+  );
+
+  const clearSearchParams = useCallback(() => {
+    navigate({
+      pathname: location.pathname,
+      search: "",
+      hash: location.hash,
+    });
+  }, [navigate, location]);
+
+  const value = useMemo<PathContextType>(
+    () => ({
+      page: {
+        path: pagePath,
+        navigate: pageNavigate,
+        isHavePrevHistory: location.key !== "default",
+      },
+      modal: {
+        ...modalState,
+        open: setModal,
+        close: closeModal,
+      },
+      searchParams: {
+        params: searchParams,
+        change: changeSearchParams,
+        set: setSearchParams,
+        delete: deleteSearchParams,
+        clear: clearSearchParams,
+      },
+      defaultLocation: location as Location,
+    }),
+    [
+      pagePath,
+      pageNavigate,
+      location,
+      modalState,
+      setModal,
+      closeModal,
+      searchParams,
+      changeSearchParams,
+      setSearchParams,
+      deleteSearchParams,
+      clearSearchParams,
+    ],
+  );
+
+  return <PathContext.Provider value={value}>{children}</PathContext.Provider>;
+};
+
+/**
+ * Wraps the application with `BrowserRouter` and the `PathContext`.
+ * Place this near the root of your component tree.
+ */
+export const PathProvider: FC<PathProviderProps> = ({ children }) => {
+  return (
+    <BrowserRouter>
+      <InnerProvider>{children}</InnerProvider>
+    </BrowserRouter>
+  );
+};

package/src/PathRouter/Provider/context.ts

@@ -0,0 +1,33 @@
+import { createContext } from "react";
+import { type PathContextType } from "../types";
+
+const defaultValues: PathContextType = {
+  page: {
+    path: "",
+    navigate: () => {},
+    isHavePrevHistory: false,
+  },
+  modal: {
+    open: () => {},
+    close: () => {},
+    path: "",
+    breadCrumbs: [],
+    isOpen: false,
+  },
+  searchParams: {
+    params: {},
+    change: () => {},
+    set: () => {},
+    clear: () => {},
+    delete: () => {},
+  },
+  defaultLocation: {
+    hash: "",
+    key: "",
+    pathname: "",
+    search: "",
+    state: {},
+  },
+};
+
+export const PathContext = createContext<PathContextType>(defaultValues);

package/src/PathRouter/Provider/index.ts

@@ -0,0 +1,2 @@
+export * from "./PathProvider";
+export * from "./usePath";

package/src/PathRouter/Provider/usePath.ts

@@ -0,0 +1,21 @@
+import { useContext } from "react";
+import { PathContext } from "./context";
+import type { PathContextType, RouterConfig } from "../types";
+
+/**
+ * Access the router context.
+ *
+ * Pass `typeof yourConfig` as the generic to get fully typed
+ * `page.navigate(...)` and `modal.open(...)` arguments:
+ *
+ * ```ts
+ * const { page, modal } = usePath<typeof config>();
+ * page.navigate("add");      // typed
+ * modal.open("test");        // typed
+ * ```
+ */
+export const usePath = <
+  C extends RouterConfig<any, any> = RouterConfig<any, any>,
+>(): PathContextType<C> => {
+  return useContext(PathContext) as unknown as PathContextType<C>;
+};

package/src/PathRouter/createPathRouter.tsx

@@ -0,0 +1,104 @@
+import React, { type ReactNode, type Ref, useContext } from "react";
+
+import { PathContext } from "./Provider/context";
+import { PathProvider as BasePathProvider } from "./Provider/PathProvider";
+import { PathRouterContainer as BasePathRouterContainer } from "./Container/RouterContainer";
+import { NavLink as BaseNavLink, type NavLinkProps } from "./NavLink";
+import type {
+  ModalNamesOf,
+  ModalWrapperComponent,
+  PathContextType,
+  PathNamesOf,
+  RouterConfig,
+} from "./types";
+
+/**
+ * Bound `PathRouterContainer` props — `config` is captured by the factory,
+ * so the consumer only needs to pass presentation-related options.
+ */
+export interface BoundPathRouterContainerProps {
+  ModalWrapper?: ModalWrapperComponent;
+  fallback?: ReactNode;
+}
+
+export interface BoundNavLinkProps<
+  C extends RouterConfig<any, any>,
+> extends NavLinkProps<C> {}
+
+/**
+ * Build a router instance bound to a concrete config.
+ *
+ * All returned helpers are pre-typed against the supplied config — no need
+ * to thread `typeof config` through every call site.
+ *
+ * ```ts
+ * import { setPage, setModal, createPathRouter } from "@/modules/PathRouter";
+ *
+ * const config = {
+ *   pages:  { home: setPage({ component: Home }) },
+ *   modals: { test: setModal({ component: TestModal }) },
+ * } as const;
+ *
+ * export const {
+ *   PathProvider,
+ *   PathRouterContainer,
+ *   usePath,
+ *   NavLink,
+ *   getPath,
+ *   getModal,
+ * } = createPathRouter(config);
+ * ```
+ */
+export const createPathRouter = <const C extends RouterConfig<any, any>>(
+  config: C,
+) => {
+  /** Typed `usePath` — `page.navigate` / `modal.open` know your routes. */
+  const usePath = (): PathContextType<C> =>
+    useContext(PathContext) as unknown as PathContextType<C>;
+
+  /** Container with `config` already injected. */
+  const PathRouterContainer: React.FC<BoundPathRouterContainerProps> = (
+    props,
+  ) => <BasePathRouterContainer config={config} {...props} />;
+
+  /** Typed `NavLink` — `to` / `modal` are autocompleted from your config. */
+  const NavLink = BaseNavLink as unknown as (
+    props: BoundNavLinkProps<C> & { ref?: Ref<HTMLAnchorElement> },
+  ) => React.ReactElement | null;
+
+  /**
+   * Identity helper that constrains its argument to a valid page path
+   * for this config. Use it where you need a typed path literal:
+   *
+   * ```ts
+   * page.navigate(getPath("home"));
+   * ```
+   */
+  const getPath = <P extends PathNamesOf<C>>(path: P): P => path;
+
+  /**
+   * Identity helper that constrains its argument to a valid modal name
+   * for this config.
+   *
+   * ```ts
+   * modal.open(getModal("test"));
+   * ```
+   */
+  const getModal = <M extends ModalNamesOf<C>>(name: M): M => name;
+
+  return {
+    /** `BrowserRouter` + context provider — does not depend on the config. */
+    PathProvider: BasePathProvider,
+    PathRouterContainer,
+    usePath,
+    NavLink,
+    getPath,
+    getModal,
+    /** The original config, re-exported for convenience. */
+    config,
+  };
+};
+
+export type PathRouter<C extends RouterConfig<any, any>> = ReturnType<
+  typeof createPathRouter<C>
+>;

package/src/PathRouter/index.ts

@@ -0,0 +1,79 @@
+/**
+ * PathRouter — public API.
+ *
+ * Everything that depends on a concrete config is produced by
+ * `createPathRouter(config)`. The package itself only exposes:
+ *
+ *   - `setPage` / `setModal`   — config builders;
+ *   - `createPathRouter`       — the factory;
+ *   - `clearSlash`             — path normalizer;
+ *   - generic helper types     — must be parametrised with `typeof config`;
+ *   - plugin / data types      — for `ModalWrapper` authors and modal
+ *                                components (`ModalProps`, etc.).
+ *
+ * `PathProvider`, `PathRouterContainer`, `usePath`, `NavLink`, `getPath`,
+ * `getModal` are intentionally **not** re-exported — obtain them from
+ * `createPathRouter(config)`.
+ *
+ * ```ts
+ * import { setPage, setModal, createPathRouter } from "@/modules/PathRouter";
+ *
+ * const config = {
+ *   pages:  { home: setPage({ component: Home }) },
+ *   modals: { test: setModal({ component: TestModal }) },
+ * } as const;
+ *
+ * export const {
+ *   PathProvider,
+ *   PathRouterContainer,
+ *   usePath,
+ *   NavLink,
+ *   getPath,
+ *   getModal,
+ * } = createPathRouter(config);
+ * ```
+ */
+
+/* Config builders */
+export { setPage, setModal } from "./utils/setters";
+
+/* The factory — the only way to get config-bound router pieces */
+export { createPathRouter } from "./createPathRouter";
+export type {
+  BoundPathRouterContainerProps,
+  BoundNavLinkProps,
+  PathRouter,
+} from "./createPathRouter";
+
+/* Path normalizer */
+export { clearSlash } from "./utils/clearSlash";
+
+/*
+ * Public types.
+ *
+ * Note on config-dependent generics: `PathNamesOf<C>` and `ModalNamesOf<C>`
+ * REQUIRE the config generic — there is no default. Use them as
+ * `PathNamesOf<typeof config>` etc.
+ *
+ * `PathContextType` is intentionally not re-exported — get a typed context
+ * shape via the `usePath` returned by `createPathRouter(config)`.
+ */
+export type {
+  /* Config shape */
+  RouterConfig,
+  PageData,
+  ModalData,
+  /* Props passed to a modal component */
+  ModalProps,
+  /* Config-dependent helpers (require <typeof config>) */
+  PathNamesOf,
+  ModalNamesOf,
+  /* Context sub-shapes */
+  ModalState,
+  SearchParams,
+  SearchParamsState,
+  /* `ModalWrapper` plugin contract */
+  ModalWrapperComponent,
+  ModalWrapperProps,
+  ModalWrapperRef,
+} from "./types";