@fruit-ui/router 1.0.0

package/README.md

@@ -0,0 +1,11 @@
+## 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 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.
+
+More thorough documentation for FRUIT Router will be available shortly [here](https://asantagata.github.io/fruit-ui/?page=router-index).

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@fruit-ui/router",
+  "version": "1.0.0",
+  "description": "A basic router component for FRUIT",
+  "main": "src/router.js",
+  "homepage": "https://asantagata.github.io/fruit-ui/?page=router-index",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "terser .\\src\\router.js -o .\\dist\\router.js"
+  },
+  "keywords": [
+    "fruit",
+    "core",
+    "js",
+    "json",
+    "vanilla",
+    "ui",
+    "dom",
+    "react",
+    "reactive",
+    "router"
+  ],
+  "author": "asantagata",
+  "license": "ISC",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asantagata/fruit-ui.git"
+  }
+}

package/src/router.js

@@ -0,0 +1,102 @@
+import { replaceWith } from "https://cdn.jsdelivr.net/npm/@fruit-ui/core@latest/src/index.js";
+
+const PARAM_NAME = 'page';
+
+/**
+ * Get the current page.
+ * @returns {string}
+ */
+function getPage() {
+    const params = new URLSearchParams(window.location.search);
+    return params.get(PARAM_NAME) ?? '';
+}
+
+/**
+ * Get the correct route for a page.
+ * @param {Object.<string, *>} routes - the collection of routes.
+ * @param {string} page - the page name to index the routes.
+ * @returns {object} the corresponding route.
+ */
+function getRoute(routes, page) {
+    if (routes[page]) return routes[page];
+    if (routes[`/${page}`]) return routes[`/${page}`];
+    if (routes['*']) return routes['*'];
+    if (routes['/*']) return routes['/*'];
+    return {};
+}
+
+/**
+ * A basic router component.
+ * @param {Object.<string, {route: () => object, title?: string}>} routes - the collection of routes.
+ * @returns {object} a component.
+ */
+function Router(routes) {
+    return {
+        render() {
+            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,
+                id: 'router',
+                dataset: { receivePageChanges: true },
+                on: {
+                    pagechange() {
+                        const page = getPage();
+                        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);
+                            });
+                        } else {
+                            this.element.scrollTo(0, 0);
+                            this.rerender();
+                        }
+                        document.title = getRoute(routes, getPage()).title ?? document.title;
+                    },
+                    mount() {
+                        window.onpopstate = () => broadcastPageChange(getPage());
+                        document.title = route.title ?? document.title;
+                    }
+                }
+            }
+        },
+        memo: {page: getPage()}
+    }
+}
+
+/**
+ * Navigates to a page.
+ * @param {string} page - the page.
+ */
+function navigate(page) {
+    if (page.startsWith('/')) page = page.slice(1);
+    if (page === getPage()) return;
+    const url = new URL(window.location.href);
+    url.searchParams.set(PARAM_NAME, page);
+    window.history.pushState({}, '', url);
+    broadcastPageChange(page);
+}
+
+/**
+ * Broadcasts that a page updated.
+ * @param {string} page - the page. 
+ */
+function broadcastPageChange(page) {
+    const event = new CustomEvent('pagechange', {detail: {page}});
+    Array.from(document.querySelectorAll(`[data-receive-page-changes]`)).forEach(target => {
+        target.dispatchEvent(event);
+    });
+}
+
+export { navigate, Router, getPage }