@aminnairi/react-router 1.0.1 → 2.0.0

package/README.md

@@ -60,7 +60,7 @@ export const Fallback = () => {
   const navigateToHomePage = useNavigateToPage(home);
 
   return (
-    <button onClick={navigateToHomePage}>
+    <button onClick={() => navigateToHomePage({})}>
       Go back home
     </button>
   );
@@ -82,7 +82,7 @@ export const Issue = () => {
   return (
     <Fragment>
       <h1>An issue occurred</h1>
-      <button onClick={home.navigate}>
+      <button onClick={() => navigateToHomePage({})}>
         Go back home
       </button>
     </Fragment>
@@ -94,11 +94,11 @@ export const Issue = () => {
 touch src/router/index.ts
 ```
 
-```tsx
+```ts
 import { createRouter } from "@aminnairi/react-router";
-import { Fallback } from "./router/fallback";
-import { Issue } from "./router/issue";
-import { home } from "./router/pages/home";
+import { Fallback } from "./fallback";
+import { Issue } from "./issue";
+import { home } from "./pages/home";
 
 export const router = createRouter({
   fallback: Fallback,
@@ -259,7 +259,7 @@ const about = createPage({
         <h1>
           About Us
         </h1>
-        <button onClick={navigateToLoginPage}>
+        <button onClick={() => navigateToLoginPage({})}>
           Login
         </button>
       </Fragment>
@@ -277,7 +277,7 @@ createPage({
         <h1>
           Home
         </h1>
-        <button onClick={navigateToAboutPage}>
+        <button onClick={() => navigateToAboutPage({})}>
           About Us
         </button>
       </Fragment>
@@ -385,12 +385,14 @@ root.render(
 
 You can also activate the View Transition Web API if you want before each page renders. This is nice because by default, the browser already has some styling that allows for a smooth and simple transition between pages.
 
-All you have to do is to set the `withViewTransition` property to `true` in the arguments of the `createRouter` function. By default, its value is set to `false` if not provided in the arguments of the `createRouter` function.
+All you have to do is to provide a `transition` function in the arguments of the `createRouter` function. This function receives the navigation direction (`"pushstate"` or `"popstate"`) and a `next` callback to render the next page.
+
+This library also exports a `slideFadeTransition` that you can use out-of-the-box.
 
 ```tsx
 import { Fragment, StrictMode } from "react";
 import { createRoot } from "react-dom/client";
-import { createRouter, createPage } from "@aminnairi/react-router";
+import { createRouter, createPage, slideFadeTransition } from "@aminnairi/react-router";
 
 const home = createPage({
   path: "/",
@@ -402,7 +404,7 @@ const home = createPage({
 });
 
 const router = createRouter({
-  transition: true,
+  transition: slideFadeTransition,
   fallback: () => (
     <h1>Not found</h1>
   ),
@@ -464,18 +466,15 @@ const home = createPage({
 });
 
 const router = createRouter({
-  transition: true,
   fallback: () => (
     <h1>Not found</h1>
   ),
   issue: ({ error, reset }) => (
-    return (
-      <Fragment>
-        <h1>Error</h1>
-        <p>{error.message}</p>
-        <button onClick={reset}>Reset</button>
-      </Fragment>
-    );
+    <Fragment>
+      <h1>Error</h1>
+      <p>{error.message}</p>
+      <button onClick={reset}>Reset</button>
+    </Fragment>
   ),
   pages: [
     home
@@ -538,17 +537,14 @@ const Fallback = () => {
 }
 
 const Issue = createIssue(({ error, reset }) => (
-  return (
-    <Fragment>
-      <h1>Error</h1>
-      <p>{error.message}</p>
-      <button onClick={reset}>Reset</button>
-    </Fragment>
-  );
+  <Fragment>
+    <h1>Error</h1>
+    <p>{error.message}</p>
+    <button onClick={reset}>Reset</button>
+  </Fragment>
 ));
 
 const router = createRouter({
-  transition: true,
   fallback: Fallback,
   issue: Issue,
   pages: [
@@ -582,7 +578,9 @@ const App = () => {
 
 root.render(
   <StrictMode>
-    <App />
+    <router.Provider>
+      <App />
+    </router.Provider>
   </StrictMode>
 );
 ```
@@ -611,7 +609,7 @@ const Fallback = () => {
   return (
     <Fragment>
       <h1>Not found</h1>
-      <button onClick={navigateToHomePage}>
+      <button onClick={() => navigateToHomePage({})}>
         Go Back Home
       </button>
     </Fragment>
@@ -619,18 +617,15 @@ const Fallback = () => {
 }
 
 const Issue = createIssue(({ error, reset }) => (
-  return (
-    <Fragment>
-      <h1>Error</h1>
-      <p>{error.message}</p>
-      <button onClick={reset}>Reset</button>
-    </Fragment>
-  );
+  <Fragment>
+    <h1>Error</h1>
+    <p>{error.message}</p>
+    <button onClick={reset}>Reset</button>
+  </Fragment>
 ));
 
 const router = createRouter({
   prefix: "/portfolio",
-  transition: true,
   fallback: Fallback,
   issue: Issue,
   pages: [
@@ -664,7 +659,9 @@ const App = () => {
 
 root.render(
   <StrictMode>
-    <App />
+    <router.Provider>
+      <App />
+    </router.Provider>
   </StrictMode>
 );
 ```
@@ -679,7 +676,7 @@ It accepts a page that has been created using `createPage`.
 import { Fragment } from "react";
 import { createPage, useNavigateToPage } from "@aminnairi/react-router";
 
-const home = createPath({
+const home = createPage({
   path: "/",
   element: function Home() {
     return (
@@ -696,7 +693,7 @@ createPage({
     return (
       <Fragment>
         <h1>About</h1>
-        <button onClick={navigateToHomePage}>Home</button>
+        <button onClick={() => navigateToHomePage({})}>Home</button>
       </Fragment>
     );
   }
@@ -711,7 +708,7 @@ The parameters should always be provided as string, as they are the only data ty
 import { Fragment } from "react";
 import { createPage, useNavigateToPage } from "@aminnairi/react-router";
 
-const user = createPath({
+const user = createPage({
   path: "/users/:user",
   element: function User({ parameters: { user }}) {
     return (
@@ -735,6 +732,40 @@ createPage({
 });
 ```
 
+### useLink
+
+Allow you to navigate to another page using a JSX component instead of a callback as for the `useNavigateToPage` hook.
+
+The created component is simply a `<a href="...">{children}</a>` under the hood which prevents the default behavior of the navigator which is to create a new HTTP request and to reload the page. The `href` attribute is computed from the page path and its parameters.
+
+```tsx
+import { Fragment } from "react";
+import { createPage, useLink } from "@aminnairi/react-router";
+
+const user = createPage({
+  path: "/users/:user",
+  element: function User({ parameters: { user }}) {
+    return (
+      <h1>User#{user}</h1>
+    );
+  }
+});
+
+createPage({
+  path: "/about",
+  element: function About() {
+    const Link = useLink(user);
+
+    return (
+      <Fragment>
+        <h1>About</h1>
+        <Link parameters={{ user: "123" }}>User#123</Link>
+      </Fragment>
+    );
+  }
+});
+```
+
 ### useSearch
 
 Allow you to get one or more search query from the URL.
@@ -748,7 +779,7 @@ import { createPage, useSearch } from "@aminnairi/react-router";
 createPage({
   path: "/users",
   element: function Home() {
-    const [search] = useSearch();
+    const search = useSearch();
     const sortedByDate = useMemo(() => search.get("sort-by") === "date", [search]);
 
     return (
@@ -791,13 +822,13 @@ This function is mainly used in the internals of the `createRouter` and in most
 ```typescript
 import { doesRouteMatchPath } from "@aminnairi/react-router";
 
-doesRoutePatchPath("/", "/"); // true
+doesRouteMatchPath("/", "/"); // true
 
-doesRoutePatchPath("/", "/about"); // false
+doesRouteMatchPath("/", "/about"); // false
 
-doesRoutePatchPath("/users/:user", "/users/123"); // true
+doesRouteMatchPath("/users/:user", "/users/123"); // true
 
-doesRoutePatchPath("/users/:user", "/users/123/articles"); // false
+doesRouteMatchPath("/users/:user", "/users/123/articles"); // false
 ```
 
 You can also optionally provide a prefix.
@@ -805,13 +836,13 @@ You can also optionally provide a prefix.
 ```typescript
 import { doesRouteMatchPath } from "@aminnairi/react-router";
 
-doesRoutePatchPath("/", "/github", "/github"); // true
+doesRouteMatchPath("/", "/github", "/github"); // true
 
-doesRoutePatchPath("/", "/github/about", "/github"); // false
+doesRouteMatchPath("/", "/github/about", "/github"); // false
 
-doesRoutePatchPath("/users/:user", "/github/users/123", "/github"); // true
+doesRouteMatchPath("/users/:user", "/github/users/123", "/github"); // true
 
-doesRoutePatchPath("/users/:user", "/github/users/123/articles", "/github"); // false
+doesRouteMatchPath("/users/:user", "/github/users/123/articles", "/github"); // false
 ```
 
 ### getParameters
@@ -823,13 +854,13 @@ This function is mainly used in the internals of the `createRouter` and in most
 ```typescript
 import { getParameters } from "@aminnairi/react-router";
 
-getParameters("/", "/"); // object
+getParameters("/", "/"); // {}
 
-getParameters("/", "/about"); // object
+getParameters("/", "/about"); // {}
 
 getParameters("/users/:user", "/users/123"); // { user: "123" }
 
-getParameters("/users/:user", "/users/123/articles"); // { user: "123" }
+getParameters("/users/:user", "/users/123/articles"); // {}
 ```
 
 You can also provide an optional prefix.
@@ -837,91 +868,13 @@ You can also provide an optional prefix.
 ```typescript
 import { getParameters } from "@aminnairi/react-router";
 
-getParameters("/", "/github", "/github"); // object
+getParameters("/", "/github", "/github"); // {}
 
-getParameters("/", "/github/about", "/github"); // object
+getParameters("/", "/github/about", "/github"); // {}
 
 getParameters("/users/:user", "/github/users/123", "/github"); // { user: "123" }
 
-getParameters("/users/:user", "/github/users/123/articles", "/github"); // { user: "123" }
-```
-
-### findPage
-
-Return a page that matches the `window.location.pathname` property containing the current URI of the page from an array of pages.
-
-If it does not match any pages, it returns `undefined` instead.
-
-This function is mainly used in the internals of the `createRouter` and in most case should not be necessary.
-
-```tsx
-import { findPage, createPage } from "@aminnairi/react-router";
-
-const home = createPage({
-  path: "/",
-  element: () => <h1>Home</h1>
-});
-
-const about = createPage({
-  path: "/about",
-  element: () => <h1>About</h1>
-});
-
-const login = createPage({
-  path: "/login",
-  element: () => <h1>Login</h1>
-});
-
-const pages = [
-  home.page,
-  about.page,
-  login.page
-];
-
-const foundPage = findPage(pages, "/login");
-
-if (foundPage) {
-  console.log("Found a page matching the current location");
-  console.log(foundPage.path);
-} else {
-  console.log("No page matching the current location.");
-}
-```
-
-You can also provide an optional prefix.
-
-```tsx
-import { findPage, createPage } from "@aminnairi/react-router";
-
-const home = createPage({
-  path: "/",
-  element: () => <h1>Home</h1>
-});
-
-const about = createPage({
-  path: "/about",
-  element: () => <h1>About</h1>
-});
-
-const login = createPage({
-  path: "/login",
-  element: () => <h1>Login</h1>
-});
-
-const pages = [
-  home.page,
-  about.page,
-  login.page
-];
-
-const foundPage = findPage(pages, "/github/login", "/github");
-
-if (foundPage) {
-  console.log("Found a page matching the current location");
-  console.log(foundPage.path);
-} else {
-  console.log("No page matching the current location.");
-}
+getParameters("/users/:user", "/github/users/123/articles", "/github"); // {}
 ```
 
 ### sanitizePath
@@ -960,9 +913,7 @@ This means that you can use this library with other popular solutions for handli
 
 ### Transition
 
-Support for the View Transition API is built-in and allows for painless and smooth view transition out-of-the-box without having to do anything.
-
-This can also easily be disabled if needed.
+Support for the View Transition API is built-in and allows for painless and smooth view transition out-of-the-box. You can create your own transition animation, and the library also exports a `slideFadeTransition` ready to be used.
 
 ### Error handling
 
@@ -976,11 +927,42 @@ See [`LICENSE`](./LICENSE).
 
 ### Versions
 
+- [`2.0.0`](#200)
+- [`1.1.0`](#110)
 - [`1.0.1`](#101)
 - [`1.0.0`](#100)
 - [`0.1.1`](#011)
 - [`0.1.0`](#010)
 
+### 2.0.0
+
+#### Major changes
+
+- The `transition` property in `createRouter` is now a function instead of a boolean, which allows for more control over the animation. This is a breaking change.
+- A `slideFadeTransition` is now exported and can be used directly.
+
+#### Minor changes
+
+None.
+
+#### Bug & security fixes
+
+None.
+
+### 1.1.0
+
+#### Major changes
+
+None.
+
+#### Minor changes
+
+- Added a new `useLink` hook to create components that allow for navigating to another page
+
+#### Bug & security fixes
+
+None.
+
 ### 1.0.1
 
 #### Major changes
@@ -1039,4 +1021,4 @@ None.
 
 #### Bug & security fixes
 
-None.
+None.

package/index.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState, FunctionComponent, useMemo, Component, PropsWithChildren, createContext, SetStateAction, Dispatch, ReactNode, useContext, useCallback } from "react";
+import { useEffect, useState, FunctionComponent, useMemo, Component, PropsWithChildren, createContext, SetStateAction, Dispatch, ReactNode, useContext, useCallback, memo, MouseEvent } from "react";
 
 export type AbsolutePath<Path extends string> =
   Path extends `${infer Start}:${string}/${infer Rest}`
@@ -25,8 +25,10 @@ export interface Page<Path extends string> {
   element: FunctionComponent<PageComponentProps<Path>>
 }
 
+export type Transition = (direction: NavigationDirection, next: () => void) => void;
+
 export interface CreateRouterOptions<Path extends string> {
-  transition?: boolean,
+  transition?: Transition,
   prefix?: string,
   pages: Array<Page<Path>>
   fallback: FunctionComponent
@@ -99,7 +101,7 @@ export interface IssueProps {
 
 export interface ErrorBoundaryProps {
   fallback: FunctionComponent<IssueProps>,
-  transition: boolean
+  transition?: Transition
 }
 
 export interface ErrorBoundaryState {
@@ -177,6 +179,11 @@ const Context = createContext<ContextInterface>({
   setHash: () => { }
 });
 
+enum NavigationDirection {
+  Forward = "pushstate",
+  Backward = "popstate"
+}
+
 export const useNavigateToPage = <Path extends string>(page: Page<Path>) => {
   const { prefix } = useContext(Context);
 
@@ -187,18 +194,22 @@ export const useNavigateToPage = <Path extends string>(page: Page<Path>) => {
       return path.replace(`:${parameterName}`, parameterValue);
     }, initialPath);
 
-    console.log({ initialPath, pathWithParameters });
-
     if (replace) {
       window.history.replaceState(null, pathWithParameters, pathWithParameters);
     } else {
       window.history.pushState(null, pathWithParameters, pathWithParameters);
     }
 
-    window.dispatchEvent(new CustomEvent("popstate"));
+    window.dispatchEvent(new CustomEvent(NavigationDirection.Forward));
   }, [page]);
 };
 
+export const useNavigateBack = () => {
+  return useCallback(() => {
+    window.dispatchEvent(new CustomEvent(NavigationDirection.Backward));
+  }, []);
+}
+
 export const useIsActivePage = (page: Page<string>) => {
   const { pathname, prefix } = useContext(Context);
 
@@ -216,12 +227,74 @@ export const useHash = () => {
   return hash;
 };
 
-export const createRouter = <Path extends string>({ pages, fallback, transition: withViewTransition, issue, prefix }: CreateRouterOptions<Path>) => {
+export const useLink = <Path extends string>(page: Page<Path>) => {
+  const Link = memo(({ children, parameters }: { children: ReactNode, parameters: Parameters<Path> }) => {
+    const { prefix } = useContext(Context);
+    const navigateToPage = useNavigateToPage(page);
+
+    const pathWithParameters = useMemo(() => {
+      return Object.entries(parameters).reduce((previousPath, [parameterName, parameterValue]) => {
+        return previousPath.replace(`:${parameterName}`, parameterValue);
+      }, sanitizePath(`${prefix ?? ""}/${page.path}`));
+    }, []);
+
+    const navigate = useCallback((event: MouseEvent) => {
+      event.preventDefault();
+      navigateToPage(parameters);
+    }, []);
+
+    return (
+      <a
+        href={pathWithParameters}
+        onClick={navigate}>
+        {children}
+      </a>
+    );
+
+  });
+
+  return Link;
+};
+
+export const slideFadeTransition: Transition = async (direction: NavigationDirection, next) => {
+  const transition = document.startViewTransition(() => {
+    next();
+  });
+
+  await transition.ready;
+
+  document.documentElement.animate(
+    [
+      { transform: 'translateX(0)', opacity: 1 },
+      { transform: `translateX(${direction === NavigationDirection.Forward ? '100%' : '-100%'})`, opacity: 0 }
+    ],
+    {
+      duration: 250,
+      easing: "ease-in-out",
+      fill: "both",
+      pseudoElement: "::view-transition-old(root)",
+    }
+  );
+
+  document.documentElement.animate(
+    [
+      { transform: `translateX(${direction === NavigationDirection.Forward ? '-100%' : '100%'})`, opacity: 0 },
+      { transform: 'translateX(0)', opacity: 1 }
+    ],
+    {
+      duration: 250,
+      easing: "ease-in-out",
+      fill: "both",
+      pseudoElement: "::view-transition-new(root)",
+    }
+  );
+}
+
+export const createRouter = <Path extends string>({ pages, fallback, transition, issue, prefix }: CreateRouterOptions<Path>) => {
   const Provider = ({ children }: ProviderProps) => {
     const [pathname, setPathname] = useState(sanitizePath(window.location.pathname));
     const [search, setSearch] = useState(new URLSearchParams(sanitizePath(window.location.search)));
     const [hash, setHash] = useState(window.location.hash);
-    const shouldTransitionBetweenPages = useMemo(() => typeof document.startViewTransition === "function" && withViewTransition ? true : false, [withViewTransition]);
 
     const value = useMemo(() => {
       return {
@@ -236,9 +309,9 @@ export const createRouter = <Path extends string>({ pages, fallback, transition:
     }, [prefix, pathname, search, hash]);
 
     useEffect(() => {
-      const onWindowPopstate = () => {
-        if (shouldTransitionBetweenPages) {
-          document.startViewTransition(() => {
+      const onNavigation = async (direction: NavigationDirection) => {
+        if (transition) {
+          transition(direction, () => {
             setPathname(sanitizePath(window.location.pathname));
           });
 
@@ -246,18 +319,28 @@ export const createRouter = <Path extends string>({ pages, fallback, transition:
         }
 
         setPathname(sanitizePath(window.location.pathname));
+      }
+
+      const onNavigationForward = () => {
+        onNavigation(NavigationDirection.Forward);
+      };
+
+      const onNavigationBackward = () => {
+        onNavigation(NavigationDirection.Backward);
       };
 
-      window.addEventListener("popstate", onWindowPopstate);
+      window.addEventListener(NavigationDirection.Forward, onNavigationForward);
+      window.addEventListener(NavigationDirection.Backward, onNavigationBackward);
 
       return () => {
-        window.removeEventListener("popstate", onWindowPopstate);
+        window.removeEventListener(NavigationDirection.Forward, onNavigationForward);
+        window.removeEventListener(NavigationDirection.Backward, onNavigationBackward);
       }
     }, []);
 
     return (
       <Context.Provider value={value}>
-        <ErrorBoundary fallback={issue} transition={shouldTransitionBetweenPages}>
+        <ErrorBoundary fallback={issue}>
           {children}
         </ErrorBoundary>
       </Context.Provider>
@@ -279,7 +362,9 @@ export const createRouter = <Path extends string>({ pages, fallback, transition:
 
     if (page) {
       return (
-        <page.element parameters={parameters} />
+        <div >
+          <page.element parameters={parameters} />
+        </div>
       );
     }
 
@@ -292,4 +377,4 @@ export const createRouter = <Path extends string>({ pages, fallback, transition:
     View,
     Provider,
   };
-}
+}

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@aminnairi/react-router",
   "description": "Type-safe router for the React library",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "homepage": "https://github.com/aminnairi/react-router#readme",
   "license": "MIT",
   "bugs": {
@@ -27,4 +27,4 @@
   "peerDependencies": {
     "react": ">=18.0.0"
   }
-}
+}