@mxweb/router 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-12-27
+
+### Added
+
+- Initial release
+- `Router` component with basename support for adhoc features
+- `Route` component with index and path-based routing
+- `Link` component with `asChild` pattern support
+- `useRouter` hook for accessing router state and navigation
+- Built-in browser History API navigation
+- Next.js App Router adapter support (`next/navigation`)
+- React Router v5 adapter support (`useHistory`)
+- React Router v6 adapter support (`useNavigate`)
+- TypeScript support with full type definitions
+- JSDoc documentation for all public APIs
+
+[1.0.0]: https://github.com/mxwebio/mxweb-router/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MXWeb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @mxweb/router
+
+A lightweight router for Next.js App Router adhoc features. Supports both built-in browser navigation and Next.js navigation for seamless routing within embedded applications.
+
+## Installation
+
+```bash
+npm install @mxweb/router
+# or
+yarn add @mxweb/router
+# or
+pnpm add @mxweb/router
+```
+
+## Quick Start
+
+```tsx
+import { Router, Route, Link, useRouter } from '@mxweb/router';
+import { useRouter as useNextRouter } from 'next/navigation';
+
+function MyAdhocFeature() {
+  const nextRouter = useNextRouter();
+
+  return (
+    <Router basename="/my-feature" adapter={nextRouter}>
+      <nav>
+        <Link href="/">Home</Link>
+        <Link href="/settings">Settings</Link>
+      </nav>
+      
+      <Route index element={HomePage} />
+      <Route path="settings" element={SettingsPage} />
+    </Router>
+  );
+}
+
+function HomePage({ navigation }) {
+  return <button onClick={() => navigation.push('/settings')}>Go to Settings</button>;
+}
+
+function SettingsPage({ navigation }) {
+  return <button onClick={() => navigation.pop()}>Go Back</button>;
+}
+```
+
+## Documentation
+
+For full documentation, visit **[docs.mxweb.io/router](https://docs.mxweb.io/router)**
+
+## License
+
+MIT © MxWeb

package/dist/index.d.ts

@@ -0,0 +1,371 @@
+/**
+ * @fileoverview MxWeb Router - A lightweight router for Next.js App Router adhoc features
+ *
+ * This package provides routing support for embedding features (adhoc apps) into Next.js App Router
+ * with a specific basename. It supports both built-in browser navigation and Next.js navigation
+ * for seamless routing within the adhoc application.
+ *
+ * @example
+ * // Using with Next.js App Router
+ * import { Router, Route, Link } from '@mxweb/router';
+ * import { useRouter } from 'next/navigation';
+ *
+ * function MyAdhocApp() {
+ *   const nextRouter = useRouter();
+ *
+ *   return (
+ *     <Router basename="/my-feature" adapter={nextRouter}>
+ *       <Route index element={HomePage} />
+ *       <Route path="settings" element={SettingsPage} />
+ *       <Link href="/settings">Go to Settings</Link>
+ *     </Router>
+ *   );
+ * }
+ *
+ * @example
+ * // Using with built-in navigation (no adapter)
+ * function StandaloneApp() {
+ *   return (
+ *     <Router basename="/app">
+ *       <Route index element={HomePage} />
+ *       <Route path="about" element={AboutPage} />
+ *     </Router>
+ *   );
+ * }
+ *
+ * @packageDocumentation
+ * @module @mxweb/router
+ */
+import React, { AnchorHTMLAttributes, ComponentType, MouseEventHandler, PropsWithChildren, ReactElement, ReactNode, Ref } from "react";
+import { LiteralObject } from "@mxweb/utils";
+/**
+ * Navigation interface for routing operations within the adhoc app.
+ * Provides methods to navigate between routes programmatically.
+ */
+export interface RouteNavigation {
+    /**
+     * Navigate to a new path by pushing it onto the history stack.
+     * @param path - The target path relative to the basename
+     * @param state - Optional state object to pass to the new route
+     */
+    push(path: string, state?: unknown): void;
+    /**
+     * Replace the current path in the history stack without creating a new entry.
+     * @param path - The target path relative to the basename
+     * @param state - Optional state object to pass to the new route
+     */
+    replace(path: string, state?: unknown): void;
+    /**
+     * Navigate backward or forward in the history stack.
+     * @param delta - Number of steps to go back (negative) or forward (positive). Defaults to -1.
+     */
+    pop(delta?: number): void;
+}
+/**
+ * Utility type that adds navigation prop to component props.
+ * Use this type for route element components that need access to navigation.
+ *
+ * @typeParam Props - The base props type for the component
+ *
+ * @example
+ * ```tsx
+ * function MyPage({ navigation }: PropsWithNavigation) {
+ *   return <button onClick={() => navigation.push('/home')}>Go Home</button>;
+ * }
+ * ```
+ */
+export type PropsWithNavigation<Props = {}> = Props & {
+    navigation: RouteNavigation;
+};
+interface RouteIndex {
+    index: true;
+    path?: never;
+    element: ComponentType<PropsWithNavigation>;
+}
+interface RoutePath<Pathname extends string = string> {
+    index?: never;
+    path: Pathname;
+    element: ComponentType<PropsWithNavigation>;
+}
+/**
+ * Props for the Route component. Can be either an index route or a path-based route.
+ *
+ * @typeParam Pathname - The type of the path string for type-safe routing
+ *
+ * @example
+ * ```tsx
+ * // Index route (matches the basename exactly)
+ * <Route index element={HomePage} />
+ *
+ * // Path-based route
+ * <Route path="settings" element={SettingsPage} />
+ * ```
+ */
+export type RouteProps<Pathname extends string = string> = RouteIndex | RoutePath<Pathname>;
+/**
+ * Options for Next.js router navigation methods.
+ * @internal
+ */
+type NextRouteOptions = {
+    scroll?: boolean;
+};
+/**
+ * Adapter interface for Next.js App Router navigation.
+ * Compatible with the `useRouter()` hook from `next/navigation`.
+ *
+ * @example
+ * ```tsx
+ * import { useRouter } from 'next/navigation';
+ *
+ * function App() {
+ *   const nextRouter = useRouter();
+ *   return <Router adapter={nextRouter}>...</Router>;
+ * }
+ * ```
+ */
+export interface NextRouteAdapter {
+    push(href: string, options?: NextRouteOptions): void;
+    replace(href: string, options?: NextRouteOptions): void;
+    back(): void;
+    forward?(): void;
+}
+/**
+ * Adapter interface for React Router v5 history object.
+ * Compatible with the `useHistory()` hook from `react-router-dom` v5.
+ *
+ * @example
+ * ```tsx
+ * import { useHistory } from 'react-router-dom';
+ *
+ * function App() {
+ *   const history = useHistory();
+ *   return <Router adapter={history}>...</Router>;
+ * }
+ * ```
+ */
+export interface ReactRouterV5Adapter {
+    push(path: string, state?: unknown): void;
+    replace(path: string, state?: unknown): void;
+    go(n: number): void;
+    goBack?(): void;
+    goForward?(): void;
+}
+/**
+ * Adapter interface for React Router v6 navigate function.
+ * Compatible with the `useNavigate()` hook from `react-router-dom` v6.
+ *
+ * @example
+ * ```tsx
+ * import { useNavigate } from 'react-router-dom';
+ *
+ * function App() {
+ *   const navigate = useNavigate();
+ *   return <Router adapter={navigate}>...</Router>;
+ * }
+ * ```
+ */
+export interface ReactRouterAdapter {
+    (to: string | number, options?: {
+        replace?: boolean;
+        state?: unknown;
+    }): void;
+}
+/**
+ * Union type for all supported router adapters.
+ * The router automatically detects which adapter type is provided and uses the appropriate navigation methods.
+ *
+ * Supported adapters:
+ * - **NextRouteAdapter**: Next.js App Router (`useRouter` from `next/navigation`)
+ * - **ReactRouterV5Adapter**: React Router v5 (`useHistory` from `react-router-dom`)
+ * - **ReactRouterAdapter**: React Router v6 (`useNavigate` from `react-router-dom`)
+ *
+ * If no adapter is provided, the router uses the built-in browser History API.
+ */
+export type RouteAdapter = NextRouteAdapter | ReactRouterV5Adapter | ReactRouterAdapter;
+/**
+ * State object representing the current router state.
+ *
+ * @typeParam Basename - The type of the basename string for type-safe routing
+ */
+export interface RouterState<Basename extends string = string> {
+    /** The base path prefix for all routes in this router instance */
+    basename: Basename;
+    /** The current path relative to the basename */
+    pathname: string;
+    /** The complete URL path including the basename */
+    fullpath: string;
+}
+/**
+ * Hook to access the router state and navigation methods.
+ * Must be used within a `<Router>` component.
+ *
+ * @returns An object containing:
+ * - `state` - The current router state (basename, pathname, fullpath)
+ * - `navigation` - The navigation object with push, replace, pop methods
+ * - `push` - Shorthand for navigation.push
+ * - `replace` - Shorthand for navigation.replace
+ * - `pop` - Shorthand for navigation.pop
+ * - `isIndexPath` - Function to check if current path is the index route
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { state, push, isIndexPath } = useRouter();
+ *
+ *   return (
+ *     <div>
+ *       <p>Current path: {state.pathname}</p>
+ *       <button onClick={() => push('/settings')}>Go to Settings</button>
+ *       {isIndexPath() && <p>You are on the home page</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useRouter(): {
+    state: RouterState<string>;
+    navigation: RouteNavigation;
+    push: <S extends LiteralObject = {}>(path: string, pushState?: S) => void;
+    replace: <S extends LiteralObject = {}>(path: string, replaceState?: S) => void;
+    pop: (delta?: number) => void;
+    isIndexPath: () => boolean;
+};
+/**
+ * Props for the Router component.
+ *
+ * @typeParam Basename - The type of the basename string for type-safe routing
+ */
+export interface RouterProps<Basename extends string = string> {
+    /**
+     * The base path for all routes in this router.
+     * All route paths will be relative to this basename.
+     * @default "/"
+     */
+    basename?: Basename;
+    /**
+     * An optional navigation adapter for integrating with external routers.
+     * Supports Next.js App Router, React Router v5, and React Router v6.
+     * If not provided, uses the built-in browser History API.
+     */
+    adapter?: RouteAdapter;
+}
+/**
+ * The main Router provider component.
+ * Wraps your adhoc application and provides routing context to child components.
+ *
+ * @typeParam Basename - The type of the basename string for type-safe routing
+ *
+ * @example
+ * ```tsx
+ * // With Next.js App Router
+ * import { useRouter } from 'next/navigation';
+ *
+ * function MyAdhocFeature() {
+ *   const nextRouter = useRouter();
+ *
+ *   return (
+ *     <Router basename="/my-feature" adapter={nextRouter}>
+ *       <Route index element={HomePage} />
+ *       <Route path="settings" element={SettingsPage} />
+ *     </Router>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With built-in navigation (standalone mode)
+ * function StandaloneApp() {
+ *   return (
+ *     <Router basename="/app">
+ *       <Route index element={HomePage} />
+ *       <Route path="about" element={AboutPage} />
+ *     </Router>
+ *   );
+ * }
+ * ```
+ */
+export declare function Router<Basename extends string = string>(props: PropsWithChildren<RouterProps<Basename>>): React.JSX.Element;
+/**
+ * A route component that renders its element when the current path matches.
+ *
+ * @typeParam Pathname - The type of the path string for type-safe routing
+ *
+ * @example
+ * ```tsx
+ * // Index route - matches when pathname is empty or "/"
+ * <Route index element={HomePage} />
+ *
+ * // Path route - matches when pathname starts with "settings"
+ * <Route path="settings" element={SettingsPage} />
+ *
+ * // Nested route example
+ * <Route path="users" element={UsersPage} />
+ * <Route path="users/profile" element={UserProfilePage} />
+ * ```
+ */
+export declare function Route<Pathname extends string = string>(props: RouteProps<Pathname>): React.JSX.Element | null;
+/**
+ * Base props shared by all Link variants.
+ * @internal
+ */
+interface LinkPropsBase {
+    /** The target path to navigate to */
+    href: string;
+    /** If true, replaces the current history entry instead of pushing a new one */
+    replace?: boolean;
+    /** Optional state object to pass to the target route */
+    state?: LiteralObject;
+}
+/**
+ * Props for Link when used with asChild pattern.
+ * @internal
+ */
+interface LinkPropsAsChild extends LinkPropsBase {
+    asChild: true;
+    children: ReactElement<{
+        href?: string;
+        onClick?: MouseEventHandler;
+        ref?: Ref<HTMLAnchorElement>;
+    }>;
+}
+/**
+ * Props for Link when rendering as a standard anchor element.
+ * @internal
+ */
+interface LinkPropsDefault extends LinkPropsBase, Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+    asChild?: false;
+    children?: ReactNode;
+}
+/**
+ * Props for the Link component.
+ * Supports two modes:
+ * - Default mode: Renders as an `<a>` element
+ * - asChild mode: Passes props to a child element (similar to Radix UI pattern)
+ */
+export type LinkProps = LinkPropsAsChild | LinkPropsDefault;
+/**
+ * A navigation link component that handles client-side routing.
+ * Intercepts clicks and uses the router's navigation methods instead of full page reloads.
+ *
+ * Supports modifier keys (Ctrl, Cmd, Shift, Alt) for opening in new tabs/windows.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Link href="/settings">Go to Settings</Link>
+ *
+ * // With replace (no new history entry)
+ * <Link href="/settings" replace>Go to Settings</Link>
+ *
+ * // With state
+ * <Link href="/details" state={{ id: 123 }}>View Details</Link>
+ *
+ * // asChild pattern - pass navigation to a custom component
+ * <Link href="/home" asChild>
+ *   <MyCustomButton>Go Home</MyCustomButton>
+ * </Link>
+ * ```
+ */
+export declare const Link: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLAnchorElement>>;
+export {};

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var t=require("react"),e=require("@mxweb/store"),a=require("@mxweb/react-hooks"),s=require("@mxweb/utils");function r(t){return t&&t.__esModule?t:{default:t}}var i=r(t);class n{constructor(t,e=null){this.routerState=t,this.adapter=e}getFullPath(t){return[this.routerState.basename,t].join("/").replace(/\/\/+/g,"/")}isNextAdapter(t){return s.hasOwnProperty(t,"back")&&"function"==typeof t.back}isV5Adapter(t){return s.hasOwnProperty(t,"go")&&"function"==typeof t.go}isV6Adapter(t){return"function"==typeof t}push(t,e={}){if(this.adapter)if(this.isV6Adapter(this.adapter))this.adapter(this.getFullPath(t),{state:e});else{if(this.isNextAdapter(this.adapter)){const a=s.hasOwnProperty(e,"scroll")?{scroll:e.scroll}:void 0;return void this.adapter.push(this.getFullPath(t),a)}this.isV5Adapter(this.adapter)&&this.adapter.push(this.getFullPath(t),e)}else s.isBrowser()&&(window.history.pushState(e,"",this.getFullPath(t)),window.dispatchEvent(new PopStateEvent("popstate")))}replace(t,e={}){if(this.adapter)if(this.isV6Adapter(this.adapter))this.adapter(this.getFullPath(t),{replace:!0,state:e});else{if(this.isNextAdapter(this.adapter)){const a=s.hasOwnProperty(e,"scroll")?{scroll:e.scroll}:void 0;return void this.adapter.replace(this.getFullPath(t),a)}this.isV5Adapter(this.adapter)&&this.adapter.replace(this.getFullPath(t),e)}else s.isBrowser()&&(window.history.replaceState(e,"",this.getFullPath(t)),window.dispatchEvent(new PopStateEvent("popstate")))}pop(t=-1){this.adapter?this.isV6Adapter(this.adapter)?this.adapter(t):this.isNextAdapter(this.adapter)?-1===t?this.adapter.back():1===t&&this.adapter.forward?this.adapter.forward():s.isBrowser()&&window.history.go(t):this.isV5Adapter(this.adapter)&&this.adapter.go(t):s.isBrowser()&&window.history.go(t)}setAdapter(t){return this.adapter=t,this}setState(t){return this.routerState=t,this}}class o extends e.StoreBase{constructor(){super({basename:"",pathname:"",fullpath:""}),this.navigation=new n(this.getState())}setState(t){return super.setState(t),this.navigation.setState(this.getState()),this}setAdapter(t){return this.navigation.setAdapter(t),this}getNavigation(){return{push:this.navigation.push.bind(this.navigation),replace:this.navigation.replace.bind(this.navigation),pop:this.navigation.pop.bind(this.navigation)}}isIndex(t){return s.isNullish(t)||""===t||"/"===t}isIndexPath(){const{basename:t,pathname:e}=this.getState();return!!this.isIndex(e)||(e===t||e===`${t}/`)}isIndexRoute(t){return s.hasOwnProperty(t,"index")&&!0===t.index}isPathRoute(t){return s.hasOwnProperty(t,"path")}isMatch(t,e){return`${e}/`.startsWith(`${t.replace(/^\//,"")}/`)}snapshot(t=""){if(!s.isBrowser())return{basename:t,fullpath:"",pathname:""};const e=window.location.pathname;let a=e;const r=t.startsWith("/")?t:`/${t}`;return r&&"/"!==r&&e.startsWith(r)?a=e.slice(r.length).replace(/^\//,""):e.startsWith("/")&&(a=e.slice(1)),{basename:r,fullpath:e,pathname:a}}}const h=new o,p=t.createContext(null);function l(){const e=t.useContext(p),a=e??h.getState(),s=h.getNavigation();return{state:a,navigation:s,push:(t,e)=>s.push(t,e),replace:(t,e)=>s.replace(t,e),pop:t=>s.pop(t),isIndexPath:()=>h.isIndexPath()}}const u=t.forwardRef((e,s)=>{const{href:r,replace:n=!1,state:o,asChild:h=!1}=e,{push:p,replace:u}=l(),d=t=>{t.metaKey||t.ctrlKey||t.shiftKey||t.altKey||0!==t.button||(t.preventDefault(),n?u(r,o):p(r,o))};if(h){const i=t.Children.only(e.children);if(!t.isValidElement(i))return null;const n=i.props;return t.cloneElement(i,{href:r,ref:a.combineRefs(s,n.ref),onClick:a.combineEvents(n.onClick,d)})}const{onClick:c,children:f,...g}=e;return i.default.createElement("a",{...g,ref:s,href:r,onClick:t=>{c?.(t),d(t)}},f)});u.displayName="Link",exports.Link=u,exports.Route=function(t){const{element:e}=t,{state:{pathname:a},navigation:s,isIndexPath:r}=l();return h.isIndexRoute(t)?r()?i.default.createElement(e,{navigation:s}):null:h.isPathRoute(t)&&h.isMatch(t.path,a)?i.default.createElement(e,{navigation:s}):null},exports.Router=function(e){const{basename:a="/",adapter:r=null,children:n}=e,[o,l]=t.useState(()=>(r&&h.setAdapter(r),h.setState(h.snapshot(a)).getState()));return t.useEffect(()=>{const t=h.onStateChange(()=>{l(t=>{const e=h.getState();return s.isEqualPrimitive(t,e)?t:e})});return h.setState(h.snapshot(a)),t},[a]),t.useEffect(()=>{r&&h.setAdapter(r)},[r]),i.default.createElement(p.Provider,{value:o},n)},exports.useRouter=l;

package/dist/index.mjs

@@ -0,0 +1 @@
+import t,{createContext as e,forwardRef as a,Children as s,isValidElement as i,cloneElement as r,useContext as n,useState as h,useEffect as o}from"react";import{StoreBase as p}from"@mxweb/store";import{combineEvents as l,combineRefs as d}from"@mxweb/react-hooks";import{isNullish as u,hasOwnProperty as c,isBrowser as g,isEqualPrimitive as f}from"@mxweb/utils";class m{constructor(t,e=null){this.routerState=t,this.adapter=e}getFullPath(t){return[this.routerState.basename,t].join("/").replace(/\/\/+/g,"/")}isNextAdapter(t){return c(t,"back")&&"function"==typeof t.back}isV5Adapter(t){return c(t,"go")&&"function"==typeof t.go}isV6Adapter(t){return"function"==typeof t}push(t,e={}){if(this.adapter)if(this.isV6Adapter(this.adapter))this.adapter(this.getFullPath(t),{state:e});else{if(this.isNextAdapter(this.adapter)){const a=c(e,"scroll")?{scroll:e.scroll}:void 0;return void this.adapter.push(this.getFullPath(t),a)}this.isV5Adapter(this.adapter)&&this.adapter.push(this.getFullPath(t),e)}else g()&&(window.history.pushState(e,"",this.getFullPath(t)),window.dispatchEvent(new PopStateEvent("popstate")))}replace(t,e={}){if(this.adapter)if(this.isV6Adapter(this.adapter))this.adapter(this.getFullPath(t),{replace:!0,state:e});else{if(this.isNextAdapter(this.adapter)){const a=c(e,"scroll")?{scroll:e.scroll}:void 0;return void this.adapter.replace(this.getFullPath(t),a)}this.isV5Adapter(this.adapter)&&this.adapter.replace(this.getFullPath(t),e)}else g()&&(window.history.replaceState(e,"",this.getFullPath(t)),window.dispatchEvent(new PopStateEvent("popstate")))}pop(t=-1){this.adapter?this.isV6Adapter(this.adapter)?this.adapter(t):this.isNextAdapter(this.adapter)?-1===t?this.adapter.back():1===t&&this.adapter.forward?this.adapter.forward():g()&&window.history.go(t):this.isV5Adapter(this.adapter)&&this.adapter.go(t):g()&&window.history.go(t)}setAdapter(t){return this.adapter=t,this}setState(t){return this.routerState=t,this}}const v=new class extends p{constructor(){super({basename:"",pathname:"",fullpath:""}),this.navigation=new m(this.getState())}setState(t){return super.setState(t),this.navigation.setState(this.getState()),this}setAdapter(t){return this.navigation.setAdapter(t),this}getNavigation(){return{push:this.navigation.push.bind(this.navigation),replace:this.navigation.replace.bind(this.navigation),pop:this.navigation.pop.bind(this.navigation)}}isIndex(t){return u(t)||""===t||"/"===t}isIndexPath(){const{basename:t,pathname:e}=this.getState();return!!this.isIndex(e)||(e===t||e===`${t}/`)}isIndexRoute(t){return c(t,"index")&&!0===t.index}isPathRoute(t){return c(t,"path")}isMatch(t,e){return`${e}/`.startsWith(`${t.replace(/^\//,"")}/`)}snapshot(t=""){if(!g())return{basename:t,fullpath:"",pathname:""};const e=window.location.pathname;let a=e;const s=t.startsWith("/")?t:`/${t}`;return s&&"/"!==s&&e.startsWith(s)?a=e.slice(s.length).replace(/^\//,""):e.startsWith("/")&&(a=e.slice(1)),{basename:s,fullpath:e,pathname:a}}},w=e(null);function S(){const t=n(w),e=t??v.getState(),a=v.getNavigation();return{state:e,navigation:a,push:(t,e)=>a.push(t,e),replace:(t,e)=>a.replace(t,e),pop:t=>a.pop(t),isIndexPath:()=>v.isIndexPath()}}function x(e){const{basename:a="/",adapter:s=null,children:i}=e,[r,n]=h(()=>(s&&v.setAdapter(s),v.setState(v.snapshot(a)).getState()));return o(()=>{const t=v.onStateChange(()=>{n(t=>{const e=v.getState();return f(t,e)?t:e})});return v.setState(v.snapshot(a)),t},[a]),o(()=>{s&&v.setAdapter(s)},[s]),t.createElement(w.Provider,{value:r},i)}function P(e){const{element:a}=e,{state:{pathname:s},navigation:i,isIndexPath:r}=S();return v.isIndexRoute(e)?r()?t.createElement(a,{navigation:i}):null:v.isPathRoute(e)&&v.isMatch(e.path,s)?t.createElement(a,{navigation:i}):null}const A=a((e,a)=>{const{href:n,replace:h=!1,state:o,asChild:p=!1}=e,{push:u,replace:c}=S(),g=t=>{t.metaKey||t.ctrlKey||t.shiftKey||t.altKey||0!==t.button||(t.preventDefault(),h?c(n,o):u(n,o))};if(p){const t=s.only(e.children);if(!i(t))return null;const h=t.props;return r(t,{href:n,ref:d(a,h.ref),onClick:l(h.onClick,g)})}const{onClick:f,children:m,...v}=e;return t.createElement("a",{...v,ref:a,href:n,onClick:t=>{f?.(t),g(t)}},m)});A.displayName="Link";export{A as Link,P as Route,x as Router,S as useRouter};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@mxweb/router",
+  "version": "1.0.0",
+  "description": "A lightweight router for Next.js App Router adhoc features with built-in and adapter-based navigation support",
+  "keywords": [
+    "react",
+    "router",
+    "nextjs",
+    "app-router",
+    "navigation",
+    "adhoc",
+    "embedded",
+    "mxweb",
+    "client-side-routing",
+    "spa"
+  ],
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "author": "MxWeb Team <mxwebio@gmail.com>",
+  "homepage": "https://docs.mxweb.io/router",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "yarn clean && yarn lint && rollup -c",
+    "build:watch": "rollup -c -w",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx,json,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,json,md}\"",
+    "prepublishOnly": "yarn build"
+  },
+  "devDependencies": {
+    "@mxweb/react-hooks": "^0.0.3",
+    "@mxweb/store": "^1.1.0",
+    "@mxweb/utils": "^0.0.5",
+    "@rollup/plugin-babel": "^6.1.0",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@typescript-eslint/eslint-plugin": "^8.50.1",
+    "@typescript-eslint/parser": "^8.50.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "glob": "^13.0.0",
+    "prettier": "^3.7.4",
+    "react": "19.2.3",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.54.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5"
+  },
+  "peerDependencies": {
+    "@mxweb/react-hooks": "^0.0.3",
+    "@mxweb/store": "^1.1.0",
+    "@mxweb/utils": "^0.0.5",
+    "react": "^19.2.3"
+  }
+}