@mpen/rerouter 0.1.9 → 0.3.1

package/dist/index.d.ts

@@ -0,0 +1,278 @@
+import { ClassValue } from "@mpen/classcat";
+import * as _$react from "react";
+import { ComponentType, ReactNode } from "react";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import { OverrideProps } from "@mpen/ts-types/react";
+import { Override } from "@mpen/ts-types";
+
+//#region src/components/Link.d.ts
+/**
+ * Values accepted by [`Link`]{@link Link} for building query strings.
+ *
+ * @example
+ * ```tsx
+ * <Link to="/matches" search={{ page: 2, sort: 'desc' }}>
+ *     Matches
+ * </Link>
+ * ```
+ */
+type SearchParamsInit = string | string[][] | Record<string, string | number | boolean | undefined | null> | URLSearchParams;
+/**
+ * Props for [`Link`]{@link Link}.
+ */
+type LinkProps = OverrideProps<'a', {
+  /**
+   * Classes to apply to the rendered anchor.
+   */
+  className?: ClassValue;
+  /**
+   * Destination URL passed to the rendered anchor's `href` attribute.
+   */
+  to: string;
+  /**
+   * Query parameters to merge into [`LinkProps.to`]{@link LinkProps#to}.
+   */
+  search?: SearchParamsInit;
+  /**
+   * Whether navigation should replace the current history entry instead of pushing a new one.
+   */
+  replace?: boolean;
+  href: never;
+  onClick: never;
+}>;
+/**
+ * Renders an anchor that navigates with rerouter history updates on ordinary clicks.
+ *
+ * @example
+ * ```tsx
+ * <Link to="/matches/42" search={{ tab: 'details' }}>
+ *     View match
+ * </Link>
+ * ```
+ *
+ * @param props - Anchor props plus rerouter navigation options.
+ * @returns An anchor element that pushes or replaces the browser URL.
+ */
+declare function Link({
+  to,
+  search,
+  children,
+  className,
+  replace,
+  ...rest
+}: LinkProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/components/NavLink.d.ts
+type NavLinkMatch = 'exact' | 'prefix';
+/**
+ * Props for [`NavLink`]{@link NavLink}.
+ */
+type NavLinkProps = Override<LinkProps, {
+  /**
+   * Classes to apply when the link target matches the current path.
+   */
+  activeClass?: ClassValue;
+  /**
+   * Classes to apply when the link target does not match the current path.
+   */
+  inactiveClass?: ClassValue;
+  /**
+   * How to compare the link target to the current path.
+   *
+   * @defaultValue `'exact'`
+   */
+  match?: NavLinkMatch;
+}>;
+/**
+ * Renders a [`Link`]{@link Link} with classes selected from the current route.
+ *
+ * @example
+ * ```tsx
+ * <NavLink
+ *     activeClass={['pill', 'active']}
+ *     inactiveClass={['pill', { muted: true }]}
+ *     to="/settings"
+ * >
+ *     Settings
+ * </NavLink>
+ * ```
+ *
+ * @param props - Link props plus active and inactive class values.
+ * @returns An anchor element that navigates through rerouter.
+ */
+declare function NavLink({
+  activeClass,
+  className,
+  inactiveClass,
+  match,
+  to,
+  ...props
+}: NavLinkProps): _$react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/lib/routes.d.ts
+/**
+ * Route params captured from the current URL pathname.
+ */
+type RouteParams = Record<string, string | undefined>;
+/**
+ * A React component that receives URL params captured for its route.
+ *
+ * @example
+ * ```tsx
+ * const UserPage: RouteComponent<{ id: string }> = ({ id }) => <div>{id}</div>
+ * ```
+ */
+type RouteComponent<TParams extends RouteParams = RouteParams> = ComponentType<TParams>;
+/**
+ * A dynamically imported route component module.
+ *
+ * @example
+ * ```tsx
+ * export default function UserPage({ id }: { id: string }) {
+ *     return <div>{id}</div>
+ * }
+ * ```
+ */
+type RouteComponentModule<TParams extends RouteParams = RouteParams> = {
+  default: RouteComponent<TParams>;
+};
+/**
+ * Loads a route component on demand.
+ *
+ * @example
+ * ```tsx
+ * const loadUserPage: RouteComponentLoader<{ id: string }> = () => import('./pages/UserPage')
+ * ```
+ */
+type RouteComponentLoader<TParams extends RouteParams = RouteParams> = () => Promise<RouteComponentModule<TParams>>;
+/**
+ * Object route definition consumed by [`Router`]{@link Router}.
+ *
+ * @example
+ * ```tsx
+ * const route: RouteObject = {
+ *     name: 'userProfile',
+ *     pattern: '/users/:id',
+ *     component: () => import('./pages/UserProfile'),
+ * }
+ * ```
+ */
+type RouteObject = {
+  /**
+   * Optional route name used by the CLI to generate a URL helper.
+   *
+   * Routes without a name still participate in runtime matching, but are skipped by the
+   * helper generator.
+   */
+  name?: string;
+  pattern: string | URLPattern;
+  component: RouteComponentLoader<any>;
+};
+type Routes = RouteObject[];
+/**
+ * Route definition consumed by [`Router`]{@link Router}.
+ *
+ * @example
+ * ```tsx
+ * const routes: readonly Route[] = [
+ *     { name: 'home', pattern: '/', component: () => import('./pages/Home') },
+ *     { pattern: '/users/:id', component: () => import('./pages/UserLayout') },
+ * ]
+ * ```
+ */
+type Route = RouteObject;
+/**
+ * Route definition normalized into a single object shape with a pathname matcher.
+ */
+type NormalizedRoute = {
+  name?: string;
+  pattern: string | URLPattern;
+  component: RouteComponentLoader<any>;
+  matches(pathname: string): RouteParams | null;
+};
+/**
+ * Converts legacy `path-to-regexp` syntax that is ignored by URL generation into syntax accepted
+ * by the current parser.
+ *
+ * @param pattern - The route pattern to normalize.
+ * @returns The pattern with custom regexp constraints stripped and optional group suffixes removed.
+ *
+ * @example
+ * ```ts
+ * normalizeLegacyPathToRegexpSyntax('/blog/:id(\\d+){-:title}?')
+ * // '/blog/:id{-:title}'
+ * ```
+ *
+ * @internal
+ */
+declare function normalizeLegacyPathToRegexpSyntax(pattern: string): string;
+/**
+ * Normalizes routes into objects with a shared matcher implementation.
+ *
+ * @param routes - The route definitions to normalize.
+ * @returns Routes with stable `name`, `pattern`, `component`, and `matches` fields.
+ *
+ * @example
+ * ```tsx
+ * const normalized = normalizeRoutes(routes)
+ * const match = normalized[0]?.matches('/users/123')
+ * ```
+ */
+declare function normalizeRoutes(routes: readonly Route[]): NormalizedRoute[];
+//#endregion
+//#region src/components/Router.d.ts
+/**
+ * Props for [`Router`]{@link Router}.
+ *
+ * @example
+ * ```tsx
+ * <Router routes={routes} loading={<div>Loading...</div>} />
+ * ```
+ */
+interface RouterProps {
+  /**
+   * Route definitions to match against the current URL pathname.
+   */
+  routes: readonly Route[];
+  /**
+   * Optional fallback rendered while a matched route component module is loading.
+   */
+  loading?: ReactNode;
+  /**
+   * Delay before rendering [`RouterProps.loading`]{@link RouterProps#loading} for a suspended
+   * route, in milliseconds.
+   *
+   * @defaultValue `400`
+   */
+  loadingDelayMs?: number;
+}
+/**
+ * Renders the first route that matches the current URL pathname.
+ *
+ * @param props - The router props.
+ * @returns The matched lazy route component, the loading fallback, or `null`.
+ *
+ * @example
+ * ```tsx
+ * import routes from './routes'
+ *
+ * function App() {
+ *     return <Router routes={routes} loading={<div>Loading...</div>} loadingDelayMs={400} />
+ * }
+ * ```
+ */
+declare function Router({
+  routes,
+  loading,
+  loadingDelayMs
+}: RouterProps): string | number | bigint | boolean | _$react_jsx_runtime0.JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | _$react.ReactPortal | _$react.ReactElement<unknown, string | _$react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
+//#endregion
+//#region src/lib/url.d.ts
+declare function pushUrl(next: string, state?: unknown): void;
+declare function replaceUrl(next: string, state?: unknown): void;
+//#endregion
+//#region src/hooks/useUrl.d.ts
+declare function useUrlPath(): string;
+declare function useUrlSearchParams(): URLSearchParams;
+//#endregion
+export { Link, LinkProps, NavLink, NavLinkMatch, NavLinkProps, NormalizedRoute, Route, RouteComponent, RouteComponentLoader, RouteComponentModule, RouteObject, RouteParams, Router, RouterProps, Routes, SearchParamsInit, normalizeLegacyPathToRegexpSyntax, normalizeRoutes, pushUrl, replaceUrl, useUrlPath, useUrlSearchParams };

package/dist/index.js

@@ -0,0 +1,247 @@
+import { n as normalizeRoutes, t as normalizeLegacyPathToRegexpSyntax } from "./routes-PW-bNm8e.js";
+import { cc } from "@mpen/classcat";
+import { Suspense, startTransition, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/lib/url.ts
+function pushUrl(next, state) {
+	window.history.pushState(state, "", next);
+	window.dispatchEvent(new PopStateEvent("popstate"));
+}
+function replaceUrl(next, state) {
+	window.history.replaceState(state, "", next);
+	window.dispatchEvent(new PopStateEvent("popstate"));
+}
+//#endregion
+//#region src/lib/mergeSearch.ts
+function mergeSearch(to, search) {
+	const hashIndex = to.indexOf("#");
+	const hash = hashIndex !== -1 ? to.slice(hashIndex) : "";
+	const pathAndQuery = hashIndex !== -1 ? to.slice(0, hashIndex) : to;
+	const queryIndex = pathAndQuery.indexOf("?");
+	const path = queryIndex !== -1 ? pathAndQuery.slice(0, queryIndex) : pathAndQuery;
+	const existingQuery = queryIndex !== -1 ? pathAndQuery.slice(queryIndex + 1) : "";
+	const params = new URLSearchParams(existingQuery);
+	const newParams = new URLSearchParams(search);
+	for (const [key, value] of newParams) params.set(key, value);
+	const queryString = params.toString();
+	return `${path}${queryString ? "?" + queryString : ""}${hash}`;
+}
+//#endregion
+//#region src/components/Link.tsx
+/**
+* Renders an anchor that navigates with rerouter history updates on ordinary clicks.
+*
+* @example
+* ```tsx
+* <Link to="/matches/42" search={{ tab: 'details' }}>
+*     View match
+* </Link>
+* ```
+*
+* @param props - Anchor props plus rerouter navigation options.
+* @returns An anchor element that pushes or replaces the browser URL.
+*/
+function Link({ to, search, children, className, replace, ...rest }) {
+	const href = search ? mergeSearch(to, search) : to;
+	const linkClassName = cc(className);
+	const onClick = (ev) => {
+		if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return;
+		if (ev.button !== 0) return;
+		ev.preventDefault();
+		startTransition(() => {
+			if (replace) replaceUrl(href);
+			else pushUrl(href);
+		});
+	};
+	return /* @__PURE__ */ jsx("a", {
+		...rest,
+		className: linkClassName || void 0,
+		href,
+		onClick,
+		children
+	});
+}
+//#endregion
+//#region src/hooks/useUrl.ts
+const getPathname = () => window.location.pathname;
+const getSearch = () => window.location.search;
+function subscribe(cb) {
+	const handler = () => cb();
+	window.addEventListener("popstate", handler);
+	return () => {
+		window.removeEventListener("popstate", handler);
+	};
+}
+function useUrlPath() {
+	return useSyncExternalStore(subscribe, getPathname, getPathname);
+}
+function useUrlSearchParams() {
+	const search = useSyncExternalStore(subscribe, getSearch, getSearch);
+	return useMemo(() => new URLSearchParams(search), [search]);
+}
+//#endregion
+//#region src/components/NavLink.tsx
+function isActivePath(pathname, targetPathname, match) {
+	if (pathname === targetPathname) return true;
+	if (match === "exact") return false;
+	if (targetPathname === "/") return false;
+	return pathname.startsWith(`${targetPathname}/`);
+}
+/**
+* Renders a [`Link`]{@link Link} with classes selected from the current route.
+*
+* @example
+* ```tsx
+* <NavLink
+*     activeClass={['pill', 'active']}
+*     inactiveClass={['pill', { muted: true }]}
+*     to="/settings"
+* >
+*     Settings
+* </NavLink>
+* ```
+*
+* @param props - Link props plus active and inactive class values.
+* @returns An anchor element that navigates through rerouter.
+*/
+function NavLink({ activeClass, className, inactiveClass, match = "exact", to, ...props }) {
+	const linkClassName = cc(className, isActivePath(useUrlPath(), new URL(to, window.location.href).pathname, match) ? activeClass : inactiveClass);
+	return /* @__PURE__ */ jsx(Link, {
+		...props,
+		className: linkClassName || void 0,
+		to
+	});
+}
+//#endregion
+//#region src/components/Router.tsx
+const DEFAULT_LOADING_DELAY_MS = 400;
+const loadedRouteComponents = /* @__PURE__ */ new WeakMap();
+const loadingRouteComponents = /* @__PURE__ */ new WeakMap();
+function loadRouteComponent(component) {
+	const loaded = loadedRouteComponents.get(component);
+	if (loaded) return Promise.resolve(loaded);
+	let loading = loadingRouteComponents.get(component);
+	if (!loading) {
+		loading = component().then((module) => {
+			loadedRouteComponents.set(component, module.default);
+			loadingRouteComponents.delete(component);
+			return module.default;
+		});
+		loadingRouteComponents.set(component, loading);
+	}
+	return loading;
+}
+function findRouteMatch(routes, pathname) {
+	for (const route of routes) {
+		const params = route.matches(pathname);
+		if (!params) continue;
+		return {
+			route,
+			params,
+			pathname
+		};
+	}
+	return null;
+}
+function getLoadedRoute(match) {
+	if (!match) return null;
+	const Component = loadedRouteComponents.get(match.route.component);
+	if (!Component) return null;
+	return {
+		...match,
+		Component
+	};
+}
+function scheduleTransition(cb) {
+	queueMicrotask(() => {
+		startTransition(cb);
+	});
+}
+function useRenderedRoute(match, loadingDelayMs) {
+	const [renderedRoute, setRenderedRoute] = useState(() => getLoadedRoute(match));
+	const [showLoading, setShowLoading] = useState(false);
+	const [loadError, setLoadError] = useState(null);
+	useEffect(() => {
+		if (!match) {
+			scheduleTransition(() => {
+				setRenderedRoute(null);
+				setShowLoading(false);
+				setLoadError(null);
+			});
+			return;
+		}
+		const loaded = getLoadedRoute(match);
+		if (loaded) {
+			scheduleTransition(() => {
+				setRenderedRoute(loaded);
+				setShowLoading(false);
+				setLoadError(null);
+			});
+			return;
+		}
+		let active = true;
+		let timeout;
+		scheduleTransition(() => {
+			setShowLoading(false);
+		});
+		if (loadingDelayMs <= 0) timeout = setTimeout(() => {
+			if (active) setShowLoading(true);
+		}, 0);
+		else timeout = setTimeout(() => {
+			if (active) setShowLoading(true);
+		}, loadingDelayMs);
+		loadRouteComponent(match.route.component).then((Component) => {
+			if (!active) return;
+			if (timeout) clearTimeout(timeout);
+			startTransition(() => {
+				setRenderedRoute({
+					...match,
+					Component
+				});
+				setShowLoading(false);
+				setLoadError(null);
+			});
+		}).catch((error) => {
+			if (!active) return;
+			setLoadError(error);
+		});
+		return () => {
+			active = false;
+			if (timeout) clearTimeout(timeout);
+		};
+	}, [loadingDelayMs, match]);
+	if (loadError) throw loadError;
+	return {
+		renderedRoute,
+		showLoading
+	};
+}
+/**
+* Renders the first route that matches the current URL pathname.
+*
+* @param props - The router props.
+* @returns The matched lazy route component, the loading fallback, or `null`.
+*
+* @example
+* ```tsx
+* import routes from './routes'
+*
+* function App() {
+*     return <Router routes={routes} loading={<div>Loading...</div>} loadingDelayMs={400} />
+* }
+* ```
+*/
+function Router({ routes, loading = null, loadingDelayMs = DEFAULT_LOADING_DELAY_MS }) {
+	const pathname = useUrlPath();
+	const normalizedRoutes = useMemo(() => normalizeRoutes(routes), [routes]);
+	const { renderedRoute, showLoading } = useRenderedRoute(useMemo(() => findRouteMatch(normalizedRoutes, pathname), [normalizedRoutes, pathname]), loadingDelayMs);
+	if (showLoading) return loading;
+	if (!renderedRoute) return null;
+	const { Component, params } = renderedRoute;
+	return /* @__PURE__ */ jsx(Suspense, {
+		fallback: loading,
+		children: /* @__PURE__ */ jsx(Component, { ...params })
+	});
+}
+//#endregion
+export { Link, NavLink, Router, normalizeLegacyPathToRegexpSyntax, normalizeRoutes, pushUrl, replaceUrl, useUrlPath, useUrlSearchParams };