@inglorious/web 6.4.2 → 6.5.1

package/README.md

@@ -1045,6 +1045,10 @@ api.notify("navigate", "/users/456")
 // Or navigate back in history
 api.notify("navigate", -1)
 
+// Go back, or to "/users" when the app was opened on this page and has
+// nothing of its own to go back to (a deep link, a fresh tab)
+api.notify("back", "/users")
+
 // With options
 api.notify("navigate", {
   to: "/users/456",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "6.4.2",
+  "version": "6.5.1",
   "description": "A new web framework that leverages the power of the Inglorious Store combined with the performance and simplicity of lit-html.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "contributors": [

package/src/form/handlers.js

@@ -1,4 +1,4 @@
-import { clone, get, set } from "@inglorious/utils/objects"
+import { clone, get, set } from "@inglorious/utils/object.js"
 
 /**
  * @typedef {import('../../types/form.js').FormEntity} FormEntity

package/src/form/helpers.js

@@ -1,4 +1,4 @@
-import { get } from "@inglorious/utils/objects"
+import { get } from "@inglorious/utils/object.js"
 
 /**
  * Retrieves the validation error for a specific form field.

package/src/router/handlers.js

@@ -8,6 +8,8 @@ import { toCamelCase } from "@inglorious/utils/data-structures/string.js"
 
 const SKIP_FULL_MATCH_GROUP = 1 // .match() result at index 0 is the full string
 const REMOVE_COLON_PREFIX = 1
+const FIRST_HISTORY_INDEX = 0 // The entry an app starts on, and the fallback for an entry that carries no index.
+const PUSH_HISTORY_STEP = 1 // How far a push advances the index. A replacement leaves it where it is.
 
 export function createHandlers(routeConfig) {
   /**
@@ -25,6 +27,18 @@ export function createHandlers(routeConfig) {
      * @param {Api} api - The application API.
      */
     init(entity, payload, api) {
+      /* Stamp the entry the app starts on, so that reloading keeps the app in
+         its place in the session history instead of restarting the count.
+         `withTransitions` reads this index back to tell a push from a traversal
+         and in which direction, so it has to be set before anything navigates. */
+      if (window.history.state?.idx == null) {
+        window.history.replaceState(
+          { ...window.history.state, idx: FIRST_HISTORY_INDEX },
+          "",
+        )
+      }
+      entity.idx = window.history.state?.idx ?? FIRST_HISTORY_INDEX
+
       // Handle initial route
       const { pathname, search } = window.location
       const initialPath = pathname + search
@@ -107,6 +121,9 @@ export function createHandlers(routeConfig) {
         }
 
         updateRouter(entity, route)
+        // Adopt the index of the entry just traversed, so the next push counts
+        // from where the history actually is rather than from where it was.
+        entity.idx = window.history.state?.idx ?? FIRST_HISTORY_INDEX
 
         api.notify("routeChange", {
           route: entity.route,
@@ -184,6 +201,10 @@ export function createHandlers(routeConfig) {
       // Prepare history state
       const historyState = {
         ...state,
+        /* Written before the notification that triggers the render, so that
+           anything reading the history entry during that render sees the new
+           index. `withTransitions` depends on this ordering. */
+        idx: replace ? entity.idx : entity.idx + PUSH_HISTORY_STEP,
         route: entity.route,
         params: entity.params,
         query: entity.query,
@@ -193,10 +214,34 @@ export function createHandlers(routeConfig) {
       // Navigate
       const method = replace ? "replaceState" : "pushState"
       history[method](historyState, "", path)
+      // Advance the counter as well as stamping the entry, or the next push
+      // writes the same index and reads as a replacement.
+      entity.idx = historyState.idx
 
       api.notify("routeChange", historyState)
     },
 
+    /**
+     * Goes back one entry when the app has an entry of its own to go back to,
+     * and otherwise navigates to the fallback in place. An app opened on a deep
+     * link starts at the first index, where `history.back()` would leave the
+     * app or do nothing at all.
+     * @param {RouterEntity} entity - The router entity.
+     * @param {string|{to: string, params?: object, state?: object}} [fallback] - Where to go when there is nothing to go back to.
+     * @param {Api} api - The application API.
+     */
+    back(entity, fallback, api) {
+      if (entity.idx > FIRST_HISTORY_INDEX) {
+        history.back()
+        return
+      }
+
+      if (fallback == null) return
+
+      const options = typeof fallback === "string" ? { to: fallback } : fallback
+      api.notify(`#${entity.id}:navigate`, { ...options, replace: true })
+    },
+
     /**
      * Handles successful loading of a lazily-loaded route module.
      * Registers the loaded type in the runtime type registry via `api.setType`

package/types/router.d.ts

@@ -38,6 +38,8 @@ export interface RouterEntity {
   query?: QueryParams
   /** The hash from the current URL. */
   hash?: string
+  /** The position of the current entry in the session history, counted from the entry the app started on. */
+  idx?: number
   /** Whether a route is currently loading asynchronously. */
   isLoading?: boolean
   /** An error that occurred during route loading. */
@@ -104,6 +106,19 @@ export interface RouterType {
     api: Api,
   ): void | Promise<void>
 
+  /**
+   * Goes back one history entry when the app pushed one, and otherwise
+   * navigates to the fallback, replacing the current entry.
+   * @param {RouterEntity} entity - The router entity.
+   * @param {string|Omit<NavigatePayload, "replace">} [fallback] - Where to go when there is nothing to go back to.
+   * @param {StoreApi} api - The store API.
+   */
+  back(
+    entity: RouterEntity,
+    fallback: string | Omit<NavigatePayload, "replace"> | undefined,
+    api: Api,
+  ): void
+
   /**
    * Synchronizes the router entity's state with data from a routing event,
    * typically triggered by a `popstate` event (browser back/forward).