@inglorious/ui 7.1.5 → 7.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ui",
-  "version": "7.1.5",
+  "version": "7.2.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",
@@ -286,7 +286,12 @@
       "types": "./types/navigation/tabs.d.ts",
       "import": "./src/navigation/tabs/index.js"
     },
-    "./tabs.css": "./src/navigation/tabs/style.css"
+    "./tabs.css": "./src/navigation/tabs/style.css",
+    "./view-transitions": {
+      "types": "./types/navigation/view-transitions.d.ts",
+      "import": "./src/navigation/view-transitions/index.js"
+    },
+    "./view-transitions.css": "./src/navigation/view-transitions/style.css"
   },
   "files": [
     "src",
@@ -300,10 +305,10 @@
     "**/*.css"
   ],
   "peerDependencies": {
-    "@inglorious/charts": "10.0.2",
+    "@inglorious/charts": "10.0.3",
     "@inglorious/store": "11.0.2",
     "@inglorious/utils": "4.0.0",
-    "@inglorious/web": "6.4.2"
+    "@inglorious/web": "6.5.0"
   },
   "devDependencies": {
     "@fontsource/material-symbols-outlined": "^5.3.5",
@@ -312,7 +317,7 @@
     "@inglorious/store": "11.0.2",
     "@inglorious/vite-plugin-jsx": "2.0.2",
     "@inglorious/vite-plugin-vue": "1.0.3",
-    "@inglorious/web": "6.4.2",
+    "@inglorious/web": "6.5.0",
     "@storybook/addon-docs": "^10.6.0",
     "@storybook/web-components-vite": "^10.6.0",
     "happy-dom": "^20.14.0",

package/src/controls/combobox/template.js

@@ -21,24 +21,61 @@ import {
 
 const NO_FOCUSED_INDEX = -1
 
-const outsideClickListeners = new Map()
+/**
+ * Registered outside-pointer listeners, keyed by the dropdown element they
+ * belong to. Used only to deduplicate: the ref callback is handed a fresh arrow
+ * on every re-render, so without this each pass would stack another listener on
+ * the document.
+ * @type {WeakMap<Element, { props: ComboboxProps, listener: (event: Event) => void }>}
+ */
+const outsideListeners = new WeakMap()
 
+/**
+ * Listen on the document for presses outside the dropdown, closing it when one
+ * happens.
+ *
+ * This listens for `pointerdown` rather than `click` on purpose. Mobile browsers
+ * synthesise `click` asynchronously after `touchend`, and drop it entirely when
+ * the touch drifts into a scroll gesture or the target is replaced meanwhile.
+ * A suppressed click would leave the listener armed, and it would then close the
+ * *next* dropdown on the tap that opened it, leaving the combobox looking stuck.
+ * `pointerdown` is dispatched synchronously for mouse, touch and pen.
+ *
+ * No id is needed: the element keys the listener, and it retires itself once its
+ * dropdown has left the DOM.
+ * @param {ComboboxProps} props
+ * @param {Element|null|undefined} el dropdown element, or undefined on unmount
+ */
 function trackOutsideClick(props, el) {
-  const previous = outsideClickListeners.get(props.id)
-  if (previous) {
-    document.removeEventListener("click", previous)
-    outsideClickListeners.delete(props.id)
+  if (!el) return
+
+  const existing = outsideListeners.get(el)
+  if (existing) {
+    // A re-render of the same dropdown: keep the one listener, but point it at
+    // the current props so onClose is not captured from the first render.
+    existing.props = props
+    return
   }
 
-  if (!el) return
+  const entry = { props }
+  entry.listener = (event) => {
+    // The dropdown left the DOM: this press is the last one to hear from it.
+    // Retiring here is what keeps a torn-down dropdown from closing whatever
+    // opens next.
+    if (!el.isConnected) {
+      document.removeEventListener("pointerdown", entry.listener)
+      return
+    }
 
-  const root = el.closest(".iw-combobox")
-  const listener = (event) => {
-    if (!event.composedPath().includes(root)) props.onClose?.()
+    // The root, not the dropdown: the control is a sibling of the dropdown, and a
+    // press on it has to count as inside. Resolved per event rather than at mount
+    // because the dropdown is not connected yet when the ref first runs.
+    const root = el.closest(".iw-combobox") ?? el
+    if (!event.composedPath().includes(root)) entry.props.onClose?.()
   }
 
-  outsideClickListeners.set(props.id, listener)
-  document.addEventListener("click", listener)
+  outsideListeners.set(el, entry)
+  document.addEventListener("pointerdown", entry.listener)
 }
 
 export const Combobox = {

package/src/index.js

@@ -43,6 +43,7 @@ export { Pagination } from "./navigation/pagination/index.js"
 export { SpeedDial } from "./navigation/speed-dial/index.js"
 export { Stepper } from "./navigation/stepper/index.js"
 export { Tabs } from "./navigation/tabs/index.js"
+export { withTransitions } from "./navigation/view-transitions/index.js"
 export { Accordion } from "./surfaces/accordion/index.js"
 export { AppBar } from "./surfaces/app-bar/index.js"
 export { Card } from "./surfaces/card/index.js"

package/src/navigation/navigation.css

@@ -7,3 +7,4 @@
 @import "./speed-dial/style.css";
 @import "./stepper/style.css";
 @import "./tabs/style.css";
+@import "./view-transitions/style.css";

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

@@ -0,0 +1,141 @@
+/**
+ * @typedef {import("../../../types/navigation/view-transitions").TransitionsStore} Store
+ * @typedef {import("../../../types/navigation/view-transitions").ViewTransitionType} ViewTransitionType
+ */
+
+/** 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
+ * `style.css` from this package, which turns those tags into a slide.
+ *
+ * The store is returned unchanged apart from its `subscribe`, which fans out to
+ * every listener instead of subscribing to the store once per listener.
+ *
+ * Requires the `Router` type from `@inglorious/web`: direction is read from the
+ * index the Router stamps into each history entry, and without it every
+ * navigation looks like a replacement and slides the wrong way.
+ *
+ * @example
+ * import { withTransitions } from "@inglorious/ui/view-transitions"
+ * import "@inglorious/ui/view-transitions.css"
+ *
+ * mount(withTransitions(store), renderApp, document.getElementById("root"))
+ *
+ * @param {Store} store - The store to wrap.
+ * @returns {Store} The same store, with a wrapped `subscribe`.
+ * @throws {Error} If the store has no `Router` type.
+ */
+export function withTransitions(store) {
+  if (!store.getType("Router")) {
+    throw new Error(
+      '[withTransitions] Requires the "Router" type from @inglorious/web. The ' +
+        "direction of a transition is read from the index the Router stamps " +
+        "into each history entry.",
+    )
+  }
+
+  const subscribe = store.subscribe
+  const listeners = new Set()
+
+  let currentPath = ""
+  let currentIndex = 0
+  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))
+  }
+
+  function onStateChange() {
+    const path = getPath()
+    const index = getIndex()
+    /* 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
+
+    currentPath = path
+    currentIndex = index
+
+    if (!hasNavigated || !supportsViewTransitions()) return notify()
+
+    const types = [getTransitionType(index, previousIndex)]
+
+    if (supportsTransitionTypes()) {
+      document.startViewTransition({ update: notify, types })
+    } else {
+      // Without `types` the browser falls back to its own cross-fade, which is
+      // a reasonable way to change page when the slide is unavailable.
+      document.startViewTransition(notify)
+    }
+  }
+
+  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)
+    }
+
+    listeners.add(listener)
+
+    return () => {
+      listeners.delete(listener)
+
+      if (!listeners.size) {
+        unsubscribeStore?.()
+        unsubscribeStore = null
+      }
+    }
+  }
+
+  return store
+}

package/src/navigation/view-transitions/style.css

@@ -0,0 +1,124 @@
+/* Directional page transitions for the whole document, driven by the types that
+   `withTransitions` tags each transition with. Pair the two: without the
+   JavaScript nothing sets a type and the browser runs its own cross-fade,
+   without this file the tags are inert and the browser does the same.
+
+   The transition pseudo-elements have to be written as one compound selector
+   glued straight onto the document element. The nested form that reads so much
+   better — `:root:active-view-transition-type(forward) { ::view-transition-old(root)
+   { … } }` — compiles to a descendant combinator, which does not reach a
+   pseudo-element that hangs off the root, and silently leaves the browser's own
+   cross-fade in place. */
+
+@media (prefers-reduced-motion: no-preference) {
+  :is(
+      :root:active-view-transition-type(forward),
+      :root:active-view-transition-type(back),
+      :root:active-view-transition-type(replace)
+    )
+    ::view-transition-group(root) {
+    animation-duration: var(--iw-duration-page);
+  }
+
+  /* The user agent isolates the image pair and blends the old snapshot onto the
+     new one with `plus-lighter`, so that two opaque snapshots cross-fading never
+     let the page show through. That is right for a fade and wrong for a slide:
+     the two snapshots do not overlap while they travel, so adding their pixels
+     only shifts their brightness. Undo both. */
+  :is(
+      :root:active-view-transition-type(forward),
+      :root:active-view-transition-type(back),
+      :root:active-view-transition-type(replace)
+    )
+    ::view-transition-image-pair(root) {
+    isolation: auto;
+  }
+
+  :is(
+      :root:active-view-transition-type(forward),
+      :root:active-view-transition-type(back),
+      :root:active-view-transition-type(replace)
+    )
+    ::view-transition-old(root) {
+    animation: none;
+    mix-blend-mode: normal;
+  }
+
+  :is(
+      :root:active-view-transition-type(forward),
+      :root:active-view-transition-type(back),
+      :root:active-view-transition-type(replace)
+    )
+    ::view-transition-new(root) {
+    animation: none;
+    mix-blend-mode: normal;
+  }
+
+  :root:active-view-transition-type(forward)::view-transition-old(root) {
+    animation: iw-view-transition-out-left var(--iw-duration-page)
+      var(--iw-easing-accelerate) both;
+  }
+
+  :root:active-view-transition-type(forward)::view-transition-new(root) {
+    animation: iw-view-transition-in-right var(--iw-duration-page)
+      var(--iw-easing-decelerate) both;
+  }
+
+  :root:active-view-transition-type(back)::view-transition-old(root) {
+    animation: iw-view-transition-out-right var(--iw-duration-page)
+      var(--iw-easing-accelerate) both;
+  }
+
+  :root:active-view-transition-type(back)::view-transition-new(root) {
+    animation: iw-view-transition-in-left var(--iw-duration-page)
+      var(--iw-easing-decelerate) both;
+  }
+
+  /* A replacement navigates in place rather than arriving from a side, so it
+     cross-fades instead of sliding. */
+  :root:active-view-transition-type(replace)::view-transition-old(root) {
+    animation: iw-view-transition-fade-out var(--iw-duration-page)
+      var(--iw-easing-standard) both;
+  }
+
+  :root:active-view-transition-type(replace)::view-transition-new(root) {
+    animation: iw-view-transition-fade-in var(--iw-duration-page)
+      var(--iw-easing-standard) both;
+  }
+}
+
+@keyframes iw-view-transition-out-left {
+  to {
+    transform: translateX(-100%);
+  }
+}
+
+@keyframes iw-view-transition-in-right {
+  from {
+    transform: translateX(100%);
+  }
+}
+
+@keyframes iw-view-transition-out-right {
+  to {
+    transform: translateX(100%);
+  }
+}
+
+@keyframes iw-view-transition-in-left {
+  from {
+    transform: translateX(-100%);
+  }
+}
+
+@keyframes iw-view-transition-fade-out {
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes iw-view-transition-fade-in {
+  from {
+    opacity: 0;
+  }
+}

package/src/styles/tokens.css

@@ -126,9 +126,26 @@
   /* ========================================
      TRANSITIONS
      ======================================== */
-  --iw-transition-fast: 150ms ease;
-  --iw-transition-normal: 200ms ease;
-  --iw-transition-slow: 300ms ease;
+  /* A duration and an easing, so that motion can pick one of each. Anything
+     that has to vary them separately — a page arriving is not eased the way a
+     page leaving is — composes them rather than reaching for the shorthands. */
+  --iw-duration-fast: 150ms;
+  --iw-duration-normal: 200ms;
+  --iw-duration-page: 250ms;
+  --iw-duration-slow: 300ms;
+  --iw-easing-standard: cubic-bezier(0.4, 0, 0.2, 1);
+  --iw-easing-accelerate: cubic-bezier(0.4, 0, 1, 1);
+  --iw-easing-decelerate: cubic-bezier(0, 0, 0.2, 1);
+
+  /* Shorthands for a plain `ease` at one of the durations above. These keep
+     working as they always have; reach for the tokens above instead when the
+     easing has to be anything other than `ease`. The page transitions in
+     `view-transitions` compose the two on purpose — a page arriving decelerates
+     and a page leaving accelerates — so they are not a shorthand case. */
+  --iw-transition-fast: var(--iw-duration-fast) ease;
+  --iw-transition-normal: var(--iw-duration-normal) ease;
+  --iw-transition-page: var(--iw-duration-page) ease;
+  --iw-transition-slow: var(--iw-duration-slow) ease;
 
   /* ========================================
      Z-INDEX SCALE

package/types/data-display/material-icon.d.ts

@@ -5,6 +5,7 @@ export interface MaterialIconProps {
   name?: string
   size?: "sm" | "md" | "lg"
   isFilled?: boolean
+  onClick?: () => void
   [key: string]: unknown
 }
 

package/types/index.d.ts

@@ -44,6 +44,11 @@ export type {
 } from "./navigation/speed-dial"
 export type { StepperProps, StepperType, Step } from "./navigation/stepper"
 export type { TabsProps, TabsType, TabItem } from "./navigation/tabs"
+export type {
+  ViewTransitionType,
+  TransitionsStore,
+  WithTransitions,
+} from "./navigation/view-transitions"
 export type {
   AccordionProps,
   AccordionType,

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

@@ -0,0 +1,17 @@
+/** The direction a view transition is tagged with, and how the stylesheet in
+ * this package reacts to it. `forward` and `back` slide, `replace` cross-fades. */
+export type ViewTransitionType = "forward" | "back" | "replace"
+
+/** The part of a store this module needs. Declared structurally rather than
+ * imported, so any store-shaped object works. */
+export interface TransitionsStore<S = unknown> {
+  subscribe(listener: (state: S) => void): () => void
+  getState(): S
+  getType(name: string): unknown
+}
+
+export interface WithTransitions {
+  <S>(store: TransitionsStore<S>): TransitionsStore<S>
+}
+
+export declare const withTransitions: WithTransitions