@inglorious/ui 7.4.0 → 7.6.0

package/README.md

@@ -46,17 +46,22 @@ The public CSS exports are:
 
 ## Safe-area utilities
 
-The base styles also expose CSS variables and utility classes for iPhone notch and home-indicator safe areas.
+The base styles also expose CSS variables and utility classes for the system bars' insets: the notch, rounded corners, the home indicator and Android's status and navigation bars. They are in `base.css`, or on their own in `@inglorious/ui/safe-area.css`.
 
 ```css
 :root {
-  --safe-area-top: env(safe-area-inset-top, 0px);
-  --safe-area-bottom: env(safe-area-inset-bottom, 0px);
-  --safe-area-left: env(safe-area-inset-left, 0px);
-  --safe-area-right: env(safe-area-inset-right, 0px);
+  --safe-area-top: …;
+  --safe-area-bottom: …;
+  --safe-area-left: …;
+  --safe-area-right: …;
 }
 ```
 
+They are `env(safe-area-inset-*)`, with two corrections:
+
+- **In a Capacitor app on Android**, they use the `--safe-area-inset-*` variables Capacitor's SystemBars plugin injects. `env()` alone doubles the status bar on WebViews that Capacitor already pads natively.
+- **In a browser tab, the top inset is 0.** The browser's chrome always sits between the page and the status bar, but browsers that embed a WebView can still report one (DuckDuckGo on Android reports 37px under its toolbar). The top inset applies in the installed PWA and in the native app, which `mount` from `@inglorious/web` marks with the `iw-native` class on `<html>`.
+
 The following utility classes are available:
 
 ```css
@@ -73,5 +78,3 @@ The following utility classes are available:
   padding-right: var(--safe-area-right);
 }
 ```
-
-These are useful for mobile layouts that need to respect notches, rounded corners, and the home indicator. They are intentionally generic utilities so apps can opt into them without having to define custom safe-area values repeatedly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ui",
-  "version": "7.4.0",
+  "version": "7.6.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",
@@ -35,6 +35,7 @@
     "./navigation.css": "./src/navigation/navigation.css",
     "./surfaces.css": "./src/surfaces/surfaces.css",
     "./tokens.css": "./src/styles/tokens.css",
+    "./safe-area.css": "./src/styles/safe-area.css",
     "./themes/inglorious.css": "./src/styles/themes/inglorious.css",
     "./themes/material.css": "./src/styles/themes/material.css",
     "./themes/bootstrap.css": "./src/styles/themes/bootstrap.css",
@@ -305,10 +306,10 @@
     "**/*.css"
   ],
   "peerDependencies": {
-    "@inglorious/charts": "10.0.5",
+    "@inglorious/charts": "10.0.6",
     "@inglorious/store": "11.0.3",
     "@inglorious/utils": "5.0.0",
-    "@inglorious/web": "6.5.2"
+    "@inglorious/web": "6.6.0"
   },
   "devDependencies": {
     "@fontsource/material-symbols-outlined": "^5.3.5",
@@ -317,7 +318,7 @@
     "@inglorious/store": "11.0.3",
     "@inglorious/vite-plugin-jsx": "2.0.3",
     "@inglorious/vite-plugin-vue": "1.0.4",
-    "@inglorious/web": "6.5.2",
+    "@inglorious/web": "6.6.0",
     "@storybook/addon-docs": "^10.6.0",
     "@storybook/web-components-vite": "^10.6.0",
     "happy-dom": "^20.14.0",

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/src/styles/safe-area.css

@@ -1,8 +1,39 @@
+/* The system bars' insets.
+
+   In a native app on Android, Capacitor's SystemBars plugin injects
+   --safe-area-inset-* with the right value in every case: 0 where it pads the
+   WebView natively (WebView < 140), the real inset where the app is
+   edge-to-edge. env() is only right on the newer WebViews, and adding it on top
+   of that native padding doubles the status bar. Everywhere else there is no
+   injected variable, and env() is the fallback.
+
+   The top inset is the exception: in a browser tab the browser's own chrome
+   always sits between the page and the status bar, so it is 0 there even when
+   the browser reports otherwise. Browsers that embed a WebView can (DuckDuckGo
+   on Android says 37px with its toolbar in the way). It only applies where the
+   page can reach the status bar: the installed PWA, and the native app, which
+   `mount` from @inglorious/web marks with `iw-native`. */
 :root {
-  --safe-area-top: env(safe-area-inset-top, 0px);
-  --safe-area-bottom: env(safe-area-inset-bottom, 0px);
-  --safe-area-left: env(safe-area-inset-left, 0px);
-  --safe-area-right: env(safe-area-inset-right, 0px);
+  --safe-area-top: var(--safe-area-inset-top, 0px);
+  --safe-area-bottom: var(
+    --safe-area-inset-bottom,
+    env(safe-area-inset-bottom, 0px)
+  );
+  --safe-area-left: var(--safe-area-inset-left, env(safe-area-inset-left, 0px));
+  --safe-area-right: var(
+    --safe-area-inset-right,
+    env(safe-area-inset-right, 0px)
+  );
+}
+
+@media (display-mode: standalone), (display-mode: fullscreen) {
+  :root {
+    --safe-area-top: env(safe-area-inset-top, 0px);
+  }
+}
+
+:root.iw-native {
+  --safe-area-top: var(--safe-area-inset-top, env(safe-area-inset-top, 0px));
 }
 
 .pt-safe {

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