@solidjs/router 0.4.3 → 0.5.1

package/README.md

@@ -28,6 +28,7 @@ It supports all of Solid's SSR methods and has Solid's transitions baked in, so
   - [useRouteData](#useroutedata)
   - [useMatch](#usematch)
   - [useRoutes](#useroutes)
+  - [useBeforeLeave](#usebeforeleave)
 
 ## Getting Started
 
@@ -98,7 +99,7 @@ export default function App() {
 
 3. Lazy-load route components
 
-This way, the `Users` and `Home` components will only be loaded if you're navigating to `/users` or `/home`, respectively.
+This way, the `Users` and `Home` components will only be loaded if you're navigating to `/users` or `/`, respectively.
 
 ```jsx
 import { lazy } from "solid-js";
@@ -120,11 +121,11 @@ export default function App() {
 
 ## Create Links to Your Routes
 
-Use the `Link` component to create an anchor tag that takes you to a route:
+Use the `A` component to create an anchor tag that takes you to a route:
 
 ```jsx
 import { lazy } from "solid-js";
-import { Routes, Route, Link } from "@solidjs/router"
+import { Routes, Route, A } from "@solidjs/router"
 const Users = lazy(() => import("./pages/Users"));
 const Home = lazy(() => import("./pages/Home"));
 
@@ -132,8 +133,8 @@ export default function App() {
   return <>
     <h1>My Site with Lots of Pages</h1>
     <nav>
-      <Link href="/about">About</Link>
-      <Link href="/">Home</Link>
+      <A href="/about">About</A>
+      <A href="/">Home</A>
     </nav>
     <Routes>
       <Route path="/users" component={Users} />
@@ -144,33 +145,21 @@ export default function App() {
 }
 ```
 
-If you use `NavLink` instead of `Link`, the anchor tag will have an `active` class if its href matches the current location, and `inactive` otherwise. **Note:** By default matching includes locations that are descendents (eg. href `/users` matches locations `/users` and `/users/123`), use the boolean `end` prop to prevent matching these. This is particularly useful for links to the root route `/` which would match everything.
+The `<A>` tag also has an `active` class if its href matches the current location, and `inactive` otherwise. **Note:** By default matching includes locations that are descendents (eg. href `/users` matches locations `/users` and `/users/123`), use the boolean `end` prop to prevent matching these. This is particularly useful for links to the root route `/` which would match everything.
 
-Both of these components have these props:
 
 | prop     | type    | description                                                                                                                                                                              |
 |----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | href     | string  | The path of the route to navigate to. This will be resolved relative to the route that the link is in, but you can preface it with `/` to refer back to the root.                                                                                                                                                    |
 | noScroll | boolean | If true, turn off the default behavior of scrolling to the top of the new page                                                                                                           |
 | replace  | boolean | If true, don't add a new entry to the browser history. (By default, the new page will be added to the browser history, so pressing the back button will take you to the previous route.) |
-| state    | unknown | [Push this value](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) to the history stack when navigating  |
-
-
-`NavLink` additionally has:
-
-| prop     | type    | description                                                                                                                                                                              |
-|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| state    | unknown | [Push this value](https://developer.mozilla.org/en-US/docs/Web/API/History/pushState) to the history stack when navigating  |                                      |
 | inactiveClass | string  | The class to show when the link is inactive (when the current location doesn't match the link) |
 | activeClass | string | The class to show when the link is active                                                                                                        |
 | end  | boolean | If `true`, only considers the link to be active when the curent location matches the `href` exactly; if `false`, check if the current location _starts with_ `href` |
 
-
-
-
-If you have a same-domain path that you want to link to _without_ going through the router, set `rel="external"` on the link component.
-
 ### The Navigate Component
-Solid Router provides a `Navigate` component that works similarly to `Link` and `NavLink`, but it will _immediately_ navigate to the provided path as soon as the component is rendered. It also uses the `href` prop, but you have the additional option of passing a function to `href` that returns a path to navigate to:
+Solid Router provides a `Navigate` component that works similarly to `A`, but it will _immediately_ navigate to the provided path as soon as the component is rendered. It also uses the `href` prop, but you have the additional option of passing a function to `href` that returns a path to navigate to:
 
 ```jsx
 function getPath ({navigate, location}) {
@@ -180,9 +169,7 @@ function getPath ({navigate, location}) {
 }
 
 //Navigating to /redirect will redirect you to the result of getPath
-<Route path="/redirect">
-  <Navigate href={getPath}/>
-</Route>
+<Route path="/redirect" element={<Navigate href={getPath}/>}/>
 ```
 
 ## Dynamic Routes
@@ -198,7 +185,7 @@ const Home = lazy(() => import("./pages/Home"));
 
 export default function App() {
   return <>
-    <h1>My Site with Lots of Pages<h1/>
+    <h1>My Site with Lots of Pages</h1>
     <Routes>
       <Route path="/users" component={Users} />
       <Route path="/users/:id" component={User} />
@@ -224,7 +211,7 @@ export default function User () {
 
   const [userData] = createResource(() => params.id, fetchUser);
 
-  return <a href={userData.twitter}>{userData.name}</a>
+  return <A href={userData.twitter}>{userData.name}</A>
 }
 ```
 
@@ -273,9 +260,9 @@ To do this, create a function that fetches and returns the data using `createRes
 ```js
 import { lazy } from "solid-js";
 import { Route } from "@solidjs/router";
-import { fetchUser } ... 
+import { fetchUser } ...
 
-const User = lazy(() => import("/pages/users/[id].js"));
+const User = lazy(() => import("./pages/users/[id].js"));
 
 //Data function
 function UserData({params, location, navigate, data}) {
@@ -361,7 +348,7 @@ function PageWrapper () {
   return <div>
     <h1> We love our users! </h1>
     <Outlet/>
-    <Link href="/">Back Home</Link>
+    <A href="/">Back Home</A>
   </div>
 }
 
@@ -401,7 +388,7 @@ You don't have to use JSX to set up your routes; you can pass an object directly
 ```jsx
 import { lazy } from "solid-js";
 import { render } from "solid-js/web";
-import { Router, useRoutes, Link } from "@solidjs/router";
+import { Router, useRoutes, A } from "@solidjs/router";
 
 const routes = [
   {
@@ -432,12 +419,12 @@ function App() {
   return (
     <>
       <h1>Awesome Site</h1>
-      <Link class="nav" href="/">
+      <A class="nav" href="/">
         Home
-      </Link>
-      <Link class="nav" href="/users">
+      </A>
+      <A class="nav" href="/users">
         Users
-      </Link>
+      </A>
       <Routes />
     </>
   );
@@ -552,3 +539,32 @@ return <div classList={{ active: Boolean(match()) }} />;
 ### useRoutes
 
 Used to define routes via a config object instead of JSX. See [Config Based Routing](#config-based-routing).
+
+### useBeforeLeave
+
+`useBeforeLeave` takes a function that will be called prior to leaving a route.  The function will be called with:
+
+- from (_Location_): current location (before change).
+- to (_string | number_}: path passed to `navigate`.
+- options (_NavigateOptions_}: options passed to `navigate`.
+- preventDefault (_void function_): call to block the route change.
+- defaultPrevented (_readonly boolean_): true if any previously called leave handlers called preventDefault().
+- retry (_void function_, _force?: boolean_ ): call to retry the same navigation, perhaps after confirming with the user. Pass `true` to skip running the leave handlers again (ie force navigate without confirming).
+
+Example usage:
+```js
+useBeforeLeave((e: BeforeLeaveEventArgs) => {
+  if (form.isDirty && !e.defaultPrevented) {
+    // preventDefault to block immediately and prompt user async
+    e.preventDefault();
+    setTimeout(() => {
+      if (window.confirm("Discard unsaved changes - are you sure?")) {
+        // user wants to proceed anyway so retry with force=true
+        e.retry(true); 
+      }
+    }, 100);
+  }
+});
+```
+
+

package/dist/components.d.ts

@@ -6,6 +6,7 @@ declare module "solid-js" {
             state?: string;
             noScroll?: boolean;
             replace?: boolean;
+            link?: boolean;
         }
     }
 }
@@ -27,7 +28,7 @@ export interface RoutesProps {
     children: JSX.Element;
 }
 export declare const Routes: (props: RoutesProps) => JSX.Element;
-export declare const useRoutes: (routes: RouteDefinition | RouteDefinition[], base?: string | undefined) => () => JSX.Element;
+export declare const useRoutes: (routes: RouteDefinition | RouteDefinition[], base?: string) => () => JSX.Element;
 export declare type RouteProps = {
     path: string | string[];
     children?: JSX.Element;
@@ -42,19 +43,17 @@ export declare type RouteProps = {
 });
 export declare const Route: (props: RouteProps) => JSX.Element;
 export declare const Outlet: () => JSX.Element;
-export interface LinkProps extends Omit<JSX.AnchorHTMLAttributes<HTMLAnchorElement>, "state"> {
+export interface AnchorProps extends Omit<JSX.AnchorHTMLAttributes<HTMLAnchorElement>, "state"> {
     href: string;
     replace?: boolean;
     noScroll?: boolean;
     state?: unknown;
-}
-export declare function Link(props: LinkProps): JSX.Element;
-export interface NavLinkProps extends LinkProps {
     inactiveClass?: string;
     activeClass?: string;
     end?: boolean;
 }
-export declare function NavLink(props: NavLinkProps): JSX.Element;
+export declare function A(props: AnchorProps): JSX.Element;
+export { A as Link, A as NavLink, AnchorProps as LinkProps, AnchorProps as NavLinkProps };
 export interface NavigateProps {
     href: ((args: {
         navigate: Navigator;

package/dist/components.jsx

@@ -3,7 +3,7 @@ import { children, createMemo, createRoot, mergeProps, on, Show, splitProps } fr
 import { isServer } from "solid-js/web";
 import { pathIntegration, staticIntegration } from "./integration";
 import { createBranches, createRouteContext, createRouterContext, getRouteMatches, RouteContextObj, RouterContextObj, useHref, useLocation, useNavigate, useResolvedPath, useRoute, useRouter } from "./routing";
-import { joinPaths } from "./utils";
+import { joinPaths, normalizePath } from "./utils";
 export const Router = (props) => {
     const { source, url, base, data, out } = props;
     const integration = source || (isServer ? staticIntegration({ value: url || "" }) : pathIntegration());
@@ -54,7 +54,7 @@ export const Routes = (props) => {
         return next;
     }));
     return (<Show when={routeStates() && root}>
-      {route => <RouteContextObj.Provider value={route}>{route.outlet()}</RouteContextObj.Provider>}
+      {((route) => (<RouteContextObj.Provider value={route}>{route.outlet()}</RouteContextObj.Provider>))}
     </Show>);
 };
 export const useRoutes = (routes, base) => {
@@ -71,36 +71,32 @@ export const Route = (props) => {
 export const Outlet = () => {
     const route = useRoute();
     return (<Show when={route.child}>
-      {child => <RouteContextObj.Provider value={child}>{child.outlet()}</RouteContextObj.Provider>}
+      {((child) => (<RouteContextObj.Provider value={child}>{child.outlet()}</RouteContextObj.Provider>))}
     </Show>);
 };
-function LinkBase(props) {
-    const [, rest] = splitProps(props, ["children", "to", "href", "state"]);
-    const href = useHref(() => props.to);
-    return (<a {...rest} href={href() || props.href} state={JSON.stringify(props.state)}>
-      {props.children}
-    </a>);
-}
-export function Link(props) {
-    const to = useResolvedPath(() => props.href);
-    return <LinkBase {...props} to={to()}/>;
-}
-export function NavLink(props) {
+export function A(props) {
     props = mergeProps({ inactiveClass: "inactive", activeClass: "active" }, props);
-    const [, rest] = splitProps(props, ["activeClass", "inactiveClass", "end"]);
-    const location = useLocation();
+    const [, rest] = splitProps(props, ["href", "state", "class", "activeClass", "inactiveClass", "end"]);
     const to = useResolvedPath(() => props.href);
+    const href = useHref(to);
+    const location = useLocation();
     const isActive = createMemo(() => {
         const to_ = to();
-        if (to_ === undefined) {
+        if (to_ === undefined)
             return false;
-        }
-        const path = to_.split(/[?#]/, 1)[0].toLowerCase();
-        const loc = location.pathname.toLowerCase();
+        const path = normalizePath(to_.split(/[?#]/, 1)[0]).toLowerCase();
+        const loc = normalizePath(location.pathname).toLowerCase();
         return props.end ? path === loc : loc.startsWith(path);
     });
-    return (<LinkBase {...rest} to={to()} classList={{ [props.inactiveClass]: !isActive(), [props.activeClass]: isActive(), ...rest.classList }} aria-current={isActive() ? "page" : undefined}/>);
+    return (<a link {...rest} href={href() || props.href} state={JSON.stringify(props.state)} classList={{
+            ...(props.class && { [props.class]: true }),
+            [props.inactiveClass]: !isActive(),
+            [props.activeClass]: isActive(),
+            ...rest.classList
+        }} aria-current={isActive() ? "page" : undefined}/>);
 }
+// deprecated alias exports
+export { A as Link, A as NavLink };
 export function Navigate(props) {
     const navigate = useNavigate();
     const location = useLocation();

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./components";
 export * from "./integration";
-export { useRouteData, useHref, useIsRouting, useLocation, useMatch, useNavigate, useParams, useResolvedPath, useSearchParams } from "./routing";
+export * from "./lifecycle";
+export { useRouteData, useHref, useIsRouting, useLocation, useMatch, useNavigate, useParams, useResolvedPath, useSearchParams, useBeforeLeave, } from "./routing";
 export { mergeSearchString as _mergeSearchString } from "./utils";
-export type { Location, LocationChange, LocationChangeSignal, NavigateOptions, Navigator, OutputMatch, Params, RouteDataFunc, RouteDataFuncArgs, RouteDefinition, RouterIntegration, RouterOutput, RouterUtils, SetParams } from "./types";
+export type { Location, LocationChange, LocationChangeSignal, NavigateOptions, Navigator, OutputMatch, Params, RouteDataFunc, RouteDataFuncArgs, RouteDefinition, RouterIntegration, RouterOutput, RouterUtils, SetParams, BeforeLeaveEventArgs } from "./types";