@fruit-ui/router 1.0.0 → 1.0.1

package/README.md

@@ -1,11 +1,43 @@
-## FRUIT Router
+# FRUIT Router
 
-This is a basic router component for [FRUIT](https://www.npmjs.com/package/@fruit-ui/core). It uses search params for routes, which minimizes server-side requirements. Its basic principles can be extended to RegExp-matched routes and could be applied to create a path-based router.
+This is a basic router component for [FRUIT](https://www.npmjs.com/package/@fruit-ui/core). It uses search params for routes, which minimizes server-side requirements.
 
-This router provides four components:
-- the Router component. This takes in `routes`, an object mapping from paths (strings) to Routes, objects with a `route` method to generate the appropriate Template, Component etc. It also allows one 'wildcard' (*) route, whose function can take in the name of the route as a parameter. The Route can also have a `title`, which will set the window's title for that route.
-- the `navigate` function, which takes in a path and navigates to that path. Navigation is done with `history.pushState` so it is compatible with the browser forward/back methods.
-- the `pagechange` event. Elements with `data-receive-page-changes` enabled will receive the `pagechange` event which can be listened for like any other event. This event is broadcast when the `navigate` function is called or forward/back methods are used in the browser. (It is *not*, however, broadcast on page load.) Within the listener, the new route can be accessed using `event.detail.page`.
-- the `getPage` function, which returns the current path.
+This router provides four significant pieces:
+
+## The Router component
+
+This is a component producer which takes in three props. 
+- `routes` is an object mapping from paths (strings) to `Route`s. `Route`s are objects with a `route` method (which generates the template/component for that route, and is allowed to be asynchronous.) You can also have a 'wildcard' (*) route whose `route` method can take in the name of the current route as a prop. Each `Route` can also have an attribute `title` which will set the window's title for that path.
+- `scrollOptions` is an optional prop. It is an object describing how scrolling should be handled when the Router component rerenders. It has two attributes: `hashed` and `unhashed`. These respectively describe how scrolling should be handled given hashed (`?page=about#contact`) and unhashed (`?page=about`) paths. In each of these, you may select any options from the [scrollIntoView](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) method, as well as an option `to: {x: number, y: number}`, which can take coordinates (in which case `scrollTo` will be used rather than `scrollIntoView`). Either can also be `false` in which case no scrolling will occur. The default value is `{hashed: {}, unhashed: {to: {x: 0, y: 0}}}`.
+- `asyncLoader` is an optional prop describing what should be displayed while an asynchronous route is loading. This is only used on the first route visited in a session; in subsequent routes, the router displays the old route until the new async route has fully loaded. The default value is `{}` (an empty `div`).
+
+Here is an example router:
+
+```js
+import * as router from "@fruit-ui/router";
+
+const router = router.Router({
+    '': () => HomePage,
+    'about': () => AboutPage,
+    'contact': () => ContactPage,
+    '*': (page) => ({children: [{tag: 'h2', children: '404'}, {tag: 'p', children: `The page "${page}" does not exist.`}]})
+}, {
+    hashed: {behavior: 'smooth'}, 
+    unhashed: {behavior: 'smooth', to: {x: 0, y: 0}}
+})
+```
+
+## The `navigate` function
+
+The `navigate` function takes in a path and navigates to that path. Navigation is done with `history.pushState` so it is compatible with the browser forward/back methods. You can navigate to hashed paths (i.e., `navigate('/about#contact')`) to automatically scroll to a certain element ID, depending on scroll settings.
+
+## The `pagechange` event
+
+Elements with `data-receive-page-changes` enabled will receive the `pagechange` event which can be listened for like any other event. This event is broadcast when the `navigate` function is called or forward/back methods are used in the browser. (It is *not*, however, broadcast on page load.) Within the listener, the new route can be accessed using `event.detail.page`.
+
+This attribute can be given using `dataset: {receivePageChanges: true}`.
+
+## The `getPage` function
+This returns the current path. Note that hashes and opening slashes are automatically removed, so after `navigate('/about#contact')`, a `getPage()` call will return `'about'`.
 
 More thorough documentation for FRUIT Router will be available shortly [here](https://asantagata.github.io/fruit-ui/?page=router-index).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruit-ui/router",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A basic router component for FRUIT",
   "main": "src/router.js",
   "homepage": "https://asantagata.github.io/fruit-ui/?page=router-index",

package/src/router.js

@@ -1,5 +1,3 @@
-import { replaceWith } from "https://cdn.jsdelivr.net/npm/@fruit-ui/core@latest/src/index.js";
-
 const PARAM_NAME = 'page';
 
 /**
@@ -25,28 +23,63 @@ function getRoute(routes, page) {
     return {};
 }
 
+/**
+ * Custom addon to scrollIntoView with coords handling.
+ * @param {HTMLElement} target 
+ * @param {object} scrollOptions 
+ */
+function scrollIntoView(target, scrollOptions) {
+    if (scrollOptions.to) {
+        target.scrollTo({...scrollOptions, top: scrollOptions.to.y, left: scrollOptions.to.x});
+    } else {
+        target.scrollIntoView(scrollOptions);
+    }
+}
+
+/**
+ * Handles scrolling.
+ * @param {HTMLElement} element - Router element
+ * @param {object | false} scrollOptions - Scroll options
+ */
+function handleScrolling(element, scrollOptions) {
+    if (window.location.hash && document.getElementById(window.location.hash.slice(1))) {
+        if (scrollOptions.hashed)
+            scrollIntoView(document.getElementById(window.location.hash.slice(1)), scrollOptions.hashed);
+    } else {
+        if (scrollOptions.unhashed)
+            scrollIntoView(element, scrollOptions.unhashed);
+    }
+}
+
 /**
  * A basic router component.
  * @param {Object.<string, {route: () => object, title?: string}>} routes - the collection of routes.
+ * @param {object | false} [scrollOptions] - scrolling options.
+ * @param {object} [asyncLoader] - loader to use while processing initial async resources
  * @returns {object} a component.
  */
-function Router(routes) {
+function Router(routes, scrollOptions = {hashed: {}, unhashed: {to: {x: 0, y: 0}}}, asyncLoader = {}) {
     return {
-        render() {
+        state() {
             const page = getPage();
             const route = getRoute(routes, page);
-            let element = (() => {
-                if (Object.getPrototypeOf(route.route).constructor.name === "AsyncFunction") {
-                    route.route(page).then(v => {
-                        replaceWith(this.element.firstChild, v);
-                    });
-                    return {};
-                } else {
-                    return route.route(page);
-                }
-            })();
             return {
-                children: typeof element === 'object' ? {...element, key: page} : element,
+                element: (() => {
+                    if (Object.getPrototypeOf(route.route).constructor.name === "AsyncFunction") {
+                        route.route(page).then(v => {
+                            document.getElementById('router').dispatchEvent(new CustomEvent('initrouterload', {detail: {element: v}}));
+                        });
+                        return asyncLoader;
+                    } else {
+                        return route.route(page);
+                    }
+                })()
+            }
+        },
+        render() {
+            return {
+                children: typeof this.state.element === 'object' ? 
+                    {...this.state.element, key: `route-${getPage()}`} : this.state.element,
                 id: 'router',
                 dataset: { receivePageChanges: true },
                 on: {
@@ -55,18 +88,28 @@ function Router(routes) {
                         const route = getRoute(routes, page);
                         if (Object.getPrototypeOf(route.route).constructor.name === "AsyncFunction") {
                             route.route(page).then(v => {
-                                this.element.scrollTo(0, 0);
-                                replaceWith(this.element.firstChild, v);
+                                this.state.element = v;
+                                this.rerender();
+                                handleScrolling(this.element, scrollOptions);
                             });
                         } else {
-                            this.element.scrollTo(0, 0);
+                            this.state.element = route.route(page);
                             this.rerender();
+                            handleScrolling(this.element, scrollOptions);
                         }
                         document.title = getRoute(routes, getPage()).title ?? document.title;
                     },
                     mount() {
                         window.onpopstate = () => broadcastPageChange(getPage());
-                        document.title = route.title ?? document.title;
+                        const page = getPage();
+                        const route = getRoute(routes, page);
+                        if (Object.getPrototypeOf(route.route).constructor.name !== "AsyncFunction")
+                            handleScrolling(this.element, scrollOptions);
+                    },
+                    initrouterload(e) {
+                        this.state.element = e.detail.element;
+                        this.rerender();
+                        handleScrolling(this.element, scrollOptions);
                     }
                 }
             }
@@ -81,9 +124,15 @@ function Router(routes) {
  */
 function navigate(page) {
     if (page.startsWith('/')) page = page.slice(1);
+    let hash = '';
+    if (page.includes('#')) {
+        hash = page.slice(page.indexOf('#'));
+        page = page.slice(0, page.indexOf('#'));
+    }
     if (page === getPage()) return;
     const url = new URL(window.location.href);
     url.searchParams.set(PARAM_NAME, page);
+    url.hash = hash;
     window.history.pushState({}, '', url);
     broadcastPageChange(page);
 }
@@ -99,4 +148,4 @@ function broadcastPageChange(page) {
     });
 }
 
-export { navigate, Router, getPage }
+export { navigate, Router, getPage };