@inglorious/ui 7.4.0 → 7.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ui",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "description": "A design system for Inglorious Web with render-function components and customizable themes",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",

package/src/navigation/view-transitions/index.js

@@ -1,44 +1,9 @@
 /**
  * @typedef {import("../../../types/navigation/view-transitions").TransitionsStore} Store
  * @typedef {import("../../../types/navigation/view-transitions").ViewTransitionType} ViewTransitionType
+ * @typedef {import("../../../types/navigation/view-transitions").TransitionsOptions} TransitionsOptions
  */
 
-/** The path the router matches against. Hashes are deliberately excluded: they
- * change the fragment, not the page, so they must not animate one. */
-function getPath() {
-  return window.location.pathname + window.location.search
-}
-
-/** The position of the current entry in the session history, stamped by the
- * Router as it navigates. Comparing it to the previous one is what tells a push
- * from a traversal, and in which direction. */
-function getIndex() {
-  return window.history.state?.idx ?? 0
-}
-
-function supportsViewTransitions() {
-  return typeof document.startViewTransition === "function"
-}
-
-/** `types` landed after `startViewTransition` itself, so an engine can have the
- * method and still throw when handed the object form of the argument. */
-function supportsTransitionTypes() {
-  return (
-    typeof ViewTransition !== "undefined" && "types" in ViewTransition.prototype
-  )
-}
-
-/**
- * @param {number} index - The index of the entry now current.
- * @param {number} previousIndex - The index of the entry before this render.
- * @returns {ViewTransitionType}
- */
-function getTransitionType(index, previousIndex) {
-  if (index < previousIndex) return "back"
-  if (index > previousIndex) return "forward"
-  return "replace"
-}
-
 /**
  * Wraps a store so that the renders which follow a navigation are run inside a
  * view transition, tagged with the direction they navigated in. Pair it with
@@ -57,11 +22,28 @@ function getTransitionType(index, previousIndex) {
  *
  * mount(withTransitions(store), renderApp, document.getElementById("root"))
  *
+ * Pass `routes` to choose which navigations animate; the rest change page
+ * without a transition. A list of route names animates every navigation into
+ * or out of one of them. A function receives `{ type, from, to }`, where `type`
+ * is the direction read from the history and `from` / `to` carry the `path`,
+ * `index` and `route` of each side, and returns whether to animate.
+ *
+ * @example
+ * // Slide into and out of detail pages; switch tabs instantly.
+ * withTransitions(store, { routes: ["eventDetail", "userDetail"] })
+ *
+ * @example
+ * // Slide only when going deeper or coming back up, never sideways.
+ * withTransitions(store, {
+ *   routes: ({ from, to }) => from.path.startsWith(to.path) || to.path.startsWith(from.path),
+ * })
+ *
  * @param {Store} store - The store to wrap.
+ * @param {TransitionsOptions} [options]
  * @returns {Store} The same store, with a wrapped `subscribe`.
  * @throws {Error} If the store has no `Router` type.
  */
-export function withTransitions(store) {
+export function withTransitions(store, { routes } = {}) {
   if (!store.getType("Router")) {
     throw new Error(
       '[withTransitions] Requires the "Router" type from @inglorious/web. The ' +
@@ -71,38 +53,60 @@ export function withTransitions(store) {
   }
 
   const subscribe = store.subscribe
+  const shouldTransition = toPredicate(routes)
   const listeners = new Set()
 
   let currentPath = ""
   let currentIndex = 0
+  let currentRoute
   let unsubscribeStore = null
 
-  /* The update callback of a view transition does not run synchronously: the
-   * browser captures the old state first and calls it on a later task. Reading
-   * the state here rather than in the subscription keeps a listener from
-   * replaying whatever the store held when the transition started. */
-  function notify() {
-    const state = store.getState()
-    // Copied, so that a listener subscribing during this pass waits for the
-    // next one instead of being notified by the pass that added it.
-    ;[...listeners].forEach((listener) => listener(state))
+  store.subscribe = (listener) => {
+    /* Taken here rather than when the store is wrapped, so that anything that
+       navigated in between — an initial redirect, a renderer mounting late — is
+       part of the baseline instead of a navigation in its own right. It also
+       keeps `window` untouched until something subscribes, so wrapping a store
+       during a server render is harmless. */
+    if (!unsubscribeStore) {
+      currentPath = getPath()
+      currentIndex = getIndex()
+      currentRoute = getRoute(store.getState())
+      unsubscribeStore = subscribe.call(store, onStateChange)
+    }
+
+    listeners.add(listener)
+
+    return () => {
+      listeners.delete(listener)
+
+      if (!listeners.size) {
+        unsubscribeStore?.()
+        unsubscribeStore = null
+      }
+    }
   }
 
   function onStateChange() {
     const path = getPath()
     const index = getIndex()
+    const route = getRoute(store.getState())
     /* Both are compared against the baseline before it moves forward,
      * otherwise the comparison would always be against itself and every
      * navigation would read as a replacement. */
     const hasNavigated = path !== currentPath
-    const previousIndex = currentIndex
+    const from = { path: currentPath, index: currentIndex, route: currentRoute }
+    const to = { path, index, route }
 
     currentPath = path
     currentIndex = index
+    currentRoute = route
 
     if (!hasNavigated || !supportsViewTransitions()) return notify()
 
-    const types = [getTransitionType(index, previousIndex)]
+    const type = getTransitionType(to.index, from.index)
+    if (!shouldTransition({ type, from, to })) return notify()
+
+    const types = [type]
 
     if (supportsTransitionTypes()) {
       document.startViewTransition({ update: notify, types })
@@ -113,29 +117,67 @@ export function withTransitions(store) {
     }
   }
 
-  store.subscribe = (listener) => {
-    /* Taken here rather than when the store is wrapped, so that anything that
-       navigated in between — an initial redirect, a renderer mounting late — is
-       part of the baseline instead of a navigation in its own right. It also
-       keeps `window` untouched until something subscribes, so wrapping a store
-       during a server render is harmless. */
-    if (!unsubscribeStore) {
-      currentPath = getPath()
-      currentIndex = getIndex()
-      unsubscribeStore = subscribe.call(store, onStateChange)
-    }
+  /* The update callback of a view transition does not run synchronously: the
+   * browser captures the old state first and calls it on a later task. Reading
+   * the state here rather than in the subscription keeps a listener from
+   * replaying whatever the store held when the transition started. */
+  function notify() {
+    const state = store.getState()
+    // Copied, so that a listener subscribing during this pass waits for the
+    // next one instead of being notified by the pass that added it.
+    ;[...listeners].forEach((listener) => listener(state))
+  }
 
-    listeners.add(listener)
+  return store
+}
 
-    return () => {
-      listeners.delete(listener)
+/** `routes` as a predicate over a navigation. Without it every navigation
+ * animates. */
+function toPredicate(routes) {
+  if (!routes) return () => true
+  if (typeof routes === "function") return routes
 
-      if (!listeners.size) {
-        unsubscribeStore?.()
-        unsubscribeStore = null
-      }
-    }
-  }
+  const names = new Set(routes)
+  return ({ from, to }) => names.has(from.route) || names.has(to.route)
+}
 
-  return store
+/** The path the router matches against. Hashes are deliberately excluded: they
+ * change the fragment, not the page, so they must not animate one. */
+function getPath() {
+  return window.location.pathname + window.location.search
+}
+
+/** The position of the current entry in the session history, stamped by the
+ * Router as it navigates. Comparing it to the previous one is what tells a push
+ * from a traversal, and in which direction. */
+function getIndex() {
+  return window.history.state?.idx ?? 0
+}
+
+/** The route the Router entity resolved, whatever the entity is called. */
+function getRoute(state) {
+  return Object.values(state).find((entity) => entity?.type === "Router")?.route
+}
+
+function supportsViewTransitions() {
+  return typeof document.startViewTransition === "function"
+}
+
+/**
+ * @param {number} index - The index of the entry now current.
+ * @param {number} previousIndex - The index of the entry before this render.
+ * @returns {ViewTransitionType}
+ */
+function getTransitionType(index, previousIndex) {
+  if (index < previousIndex) return "back"
+  if (index > previousIndex) return "forward"
+  return "replace"
+}
+
+/** `types` landed after `startViewTransition` itself, so an engine can have the
+ * method and still throw when handed the object form of the argument. */
+function supportsTransitionTypes() {
+  return (
+    typeof ViewTransition !== "undefined" && "types" in ViewTransition.prototype
+  )
 }

package/types/navigation/view-transitions.d.ts

@@ -10,8 +10,33 @@ export interface TransitionsStore<S = unknown> {
   getType(name: string): unknown
 }
 
+/** One side of a navigation. */
+export interface NavigationSide {
+  path: string
+  /** The history index the Router stamped on the entry. */
+  index: number
+  /** The route the Router resolved, if any. */
+  route?: string
+}
+
+export interface Navigation {
+  /** The direction read from the history. */
+  type: ViewTransitionType
+  from: NavigationSide
+  to: NavigationSide
+}
+
+export interface TransitionsOptions {
+  /** Which navigations animate: those into or out of the named routes, or
+   * those the function accepts. Omit it to animate every navigation. */
+  routes?: string[] | ((navigation: Navigation) => boolean)
+}
+
 export interface WithTransitions {
-  <S>(store: TransitionsStore<S>): TransitionsStore<S>
+  <S>(
+    store: TransitionsStore<S>,
+    options?: TransitionsOptions,
+  ): TransitionsStore<S>
 }
 
 export declare const withTransitions: WithTransitions