shelving 1.292.0 → 1.292.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.292.0",
+	"version": "1.292.2",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/ui/router/Navigation.d.ts

@@ -14,6 +14,8 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {
  * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls.
  * - Listens for `popstate` to sync the store with browser back/forward.
  * - Publishes the live URL into the `Meta` context via `mergeMeta()`, so descendant `<Router>`s re-render on navigation and merge invariants hold (e.g. `root` defaults to the live URL's origin when unset).
+ * - Publishes each URL change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition.
+ * - Skips the transition when the browser already animated the change (`PopStateEvent.hasUAVisualTransition`, e.g. a swipe-back gesture).
  *
  * Exactly one `<Navigation>` per app — nested routers share this single store.
  *

package/ui/router/Navigation.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect } from "react";
+import { startTransition, useEffect, useState } from "react";
 import { useInstance } from "../../react/useInstance.js";
-import { useStore } from "../../react/useStore.js";
 import { MetaContext, requireMeta } from "../misc/MetaContext.js";
+import { setTransitionType } from "../transition/util.js";
 import { mergeMeta } from "../util/index.js";
 import { NavigationContext } from "./NavigationContext.js";
 import { NavigationStore } from "./NavigationStore.js";
@@ -12,6 +12,8 @@ import { NavigationStore } from "./NavigationStore.js";
  * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls.
  * - Listens for `popstate` to sync the store with browser back/forward.
  * - Publishes the live URL into the `Meta` context via `mergeMeta()`, so descendant `<Router>`s re-render on navigation and merge invariants hold (e.g. `root` defaults to the live URL's origin when unset).
+ * - Publishes each URL change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition.
+ * - Skips the transition when the browser already animated the change (`PopStateEvent.hasUAVisualTransition`, e.g. a swipe-back gesture).
  *
  * Exactly one `<Navigation>` per app — nested routers share this single store.
  *
@@ -23,10 +25,26 @@ import { NavigationStore } from "./NavigationStore.js";
 export function Navigation({ children, ...meta }) {
     const current = requireMeta(meta);
     const nav = useInstance(NavigationStore, current.url, current.root);
-    useStore(nav);
+    // React runs a `<ViewTransition>` only for a transition update, and `useSyncExternalStore()` always renders a sync update.
+    // So keep the published URL in state and copy each store change into it inside `startTransition()`.
+    const [url, setURL] = useState(nav.value);
     useEffect(() => {
         if (typeof document === "undefined" || typeof window === "undefined")
             return;
+        // Type of the next transition: `"back"` for a `popstate`, else `"forward"` (link click, `forward()`, `redirect()`).
+        // `null` means no transition, because the browser already animated the change (e.g. a swipe-back gesture).
+        let type = "forward";
+        const stop = nav.subscribe(value => {
+            const t = type;
+            type = "forward";
+            if (!t)
+                return setURL(value);
+            // React renders a transition that starts inside a `popstate` event as a sync update with no view transition, so leave the event first.
+            setTimeout(() => startTransition(() => {
+                setTransitionType(t);
+                setURL(value);
+            }));
+        });
         const onClick = (e) => {
             if (e.target instanceof Element) {
                 const anchor = e.target.closest("a") ||
@@ -38,15 +56,19 @@ export function Navigation({ children, ...meta }) {
                 }
             }
         };
-        const onPopState = () => {
-            nav.value = window.location.href;
+        const onPopState = (e) => {
+            const href = window.location.href;
+            if (href !== nav.value.href)
+                type = e.hasUAVisualTransition ? null : "back";
+            nav.value = href;
         };
         document.addEventListener("click", onClick);
         window.addEventListener("popstate", onPopState);
         return () => {
             document.removeEventListener("click", onClick);
             window.removeEventListener("popstate", onPopState);
+            stop();
         };
     }, [nav]);
-    return (_jsx(NavigationContext, { value: nav, children: _jsx(MetaContext, { value: mergeMeta(current, { url: nav.value }, Navigation), children: children }) }));
+    return (_jsx(NavigationContext, { value: nav, children: _jsx(MetaContext, { value: mergeMeta(current, { url }, Navigation), children: children }) }));
 }

package/ui/router/Navigation.md

@@ -6,6 +6,9 @@ The top-level navigation provider for a client-side app. It owns a single `Navig
 
 - Same-origin anchor clicks are intercepted automatically and turned into `forward()` calls. Add a `download` attribute to an anchor to opt out.
 - It listens for `popstate` so the store stays in sync with browser back/forward.
+- It publishes each page change inside `startTransition()`, so a `<Transition>` around the routes animates it. A link click, `NavigationStore.forward()` or `NavigationStore.redirect()` sets the `"forward"` transition type. The browser back or forward button sets `"back"` (`popstate` does not say which way it went).
+- When the browser already animated the change, for example a swipe-back gesture on a phone, there is no view transition, so the page does not slide twice. The browser says so with `hasUAVisualTransition` on the `popstate` event. Other browsers still slide.
+- The `popstate` update waits for the next task (`setTimeout()`). React renders a transition that starts inside `popstate` as a sync update with no view transition.
 - It initialises the store from the surrounding `<Meta>` url/base, so set those on an ancestor `<App>` / `<HTML>` / `<Page>`. In the browser the store falls back to `window.location.href` when no url is set.
 - The meta it publishes always has a `root` — when none is set anywhere, `root` defaults to the live URL's origin. Setting `root` explicitly on `<App>` / `<HTML>` is still strongly recommended, especially for apps served under a sub-path.
 - `<Router>` works with no `<Navigation>` at all (SSR, static rendering, tests) — `<Navigation>` is only what makes the URL *live* on the client.
@@ -22,6 +25,19 @@ import { HTML, Navigation, Router } from "shelving/ui";
 </HTML>
 ```
 
+### Page transitions
+
+```tsx
+import { HorizontalTransition, Navigation, Router } from "shelving/ui";
+
+// Links slide right, the browser back button slides left.
+<Navigation>
+  <HorizontalTransition>
+    <Router routes={ROUTES}/>
+  </HorizontalTransition>
+</Navigation>
+```
+
 ### Imperative navigation
 
 Read the navigation store from anywhere in the tree with `requireNavigation()` for imperative URL changes:

package/ui/router/Navigation.tsx

@@ -1,7 +1,7 @@
-import { type ReactElement, useEffect } from "react";
+import { type ReactElement, startTransition, useEffect, useState } from "react";
 import { useInstance } from "../../react/useInstance.js";
-import { useStore } from "../../react/useStore.js";
 import { MetaContext, requireMeta } from "../misc/MetaContext.js";
+import { setTransitionType, type TransitionType } from "../transition/util.js";
 import { mergeMeta, type PossibleMeta } from "../util/index.js";
 import type { OptionalChildProps } from "../util/props.js";
 import { NavigationContext } from "./NavigationContext.js";
@@ -20,6 +20,8 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {}
  * - Intercepts same-origin anchor clicks (excluding `download` anchors) and turns them into `forward()` calls.
  * - Listens for `popstate` to sync the store with browser back/forward.
  * - Publishes the live URL into the `Meta` context via `mergeMeta()`, so descendant `<Router>`s re-render on navigation and merge invariants hold (e.g. `root` defaults to the live URL's origin when unset).
+ * - Publishes each URL change inside `startTransition()` with a `"forward"` or `"back"` transition type, so a `<Transition>` around the routes runs a view transition.
+ * - Skips the transition when the browser already animated the change (`PopStateEvent.hasUAVisualTransition`, e.g. a swipe-back gesture).
  *
  * Exactly one `<Navigation>` per app — nested routers share this single store.
  *
@@ -31,11 +33,30 @@ export interface NavigationProps extends PossibleMeta, OptionalChildProps {}
 export function Navigation({ children, ...meta }: NavigationProps): ReactElement {
 	const current = requireMeta(meta);
 	const nav = useInstance(NavigationStore, current.url, current.root);
-	useStore(nav);
+
+	// React runs a `<ViewTransition>` only for a transition update, and `useSyncExternalStore()` always renders a sync update.
+	// So keep the published URL in state and copy each store change into it inside `startTransition()`.
+	const [url, setURL] = useState(nav.value);
 
 	useEffect(() => {
 		if (typeof document === "undefined" || typeof window === "undefined") return;
 
+		// Type of the next transition: `"back"` for a `popstate`, else `"forward"` (link click, `forward()`, `redirect()`).
+		// `null` means no transition, because the browser already animated the change (e.g. a swipe-back gesture).
+		let type: TransitionType | null = "forward";
+		const stop = nav.subscribe(value => {
+			const t = type;
+			type = "forward";
+			if (!t) return setURL(value);
+			// React renders a transition that starts inside a `popstate` event as a sync update with no view transition, so leave the event first.
+			setTimeout(() =>
+				startTransition(() => {
+					setTransitionType(t);
+					setURL(value);
+				}),
+			);
+		});
+
 		const onClick = (e: MouseEvent) => {
 			if (e.target instanceof Element) {
 				const anchor =
@@ -48,8 +69,10 @@ export function Navigation({ children, ...meta }: NavigationProps): ReactElement
 				}
 			}
 		};
-		const onPopState = () => {
-			nav.value = window.location.href;
+		const onPopState = (e: PopStateEvent) => {
+			const href = window.location.href;
+			if (href !== nav.value.href) type = e.hasUAVisualTransition ? null : "back";
+			nav.value = href;
 		};
 
 		document.addEventListener("click", onClick);
@@ -58,12 +81,13 @@ export function Navigation({ children, ...meta }: NavigationProps): ReactElement
 		return () => {
 			document.removeEventListener("click", onClick);
 			window.removeEventListener("popstate", onPopState);
+			stop();
 		};
 	}, [nav]);
 
 	return (
 		<NavigationContext value={nav}>
-			<MetaContext value={mergeMeta(current, { url: nav.value }, Navigation)}>{children}</MetaContext>
+			<MetaContext value={mergeMeta(current, { url }, Navigation)}>{children}</MetaContext>
 		</NavigationContext>
 	);
 }

package/ui/transition/HorizontalTransition.css

@@ -1,6 +1,11 @@
-@layer base {
+@import url("../style/layers.css");
+@import url("../style/Duration.module.css");
+
+/* Global CSS, not a CSS module — see `Transition.css` for why. */
+@layer defaults {
 	:root {
-		--horizontal-transition-size: 25vw;
+		/* A percentage is of the snapshot's own size, so the old and new content sit edge to edge and never overlap. */
+		--horizontal-transition-size: 100%;
 		--horizontal-transition-duration: var(--duration-normal);
 	}
 }
@@ -53,6 +58,12 @@
 	}
 }
 
+/* Clip the slide to the element's own box, so it does not paint over the content around it. */
+::view-transition-group(.slide-right),
+::view-transition-group(.slide-left) {
+	overflow: clip;
+}
+
 ::view-transition-new(.slide-right) {
 	animation: slide-in-from-right var(--horizontal-transition-duration) ease-in-out both;
 }

package/ui/transition/HorizontalTransition.md

@@ -5,35 +5,39 @@ A direction-aware `<Transition>` preset that slides its children horizontally
 **Things to know:**
 
 - Slides right by default and when the type is `"forward"`; slides left when the type is `"back"`.
-- Set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback before navigating — see `<Transition>`.
+- Inside `<Navigation>` the direction is automatic: a link click, `NavigationStore.forward()` or `NavigationStore.redirect()` sets the `"forward"` type, and the browser back or forward button sets `"back"`. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
 - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
+- The old and new content slide a full width apart, so they sit edge to edge and never overlap.
+- The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
+- During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and put the slide groups below it:
+
+  ```css
+  ::view-transition-group(.slide-right),
+  ::view-transition-group(.slide-left) {
+    z-index: -1;
+  }
+  ```
+
 - Under `prefers-reduced-motion: reduce` the slide distance is forced to `0`, so the transition degrades to an opacity-only crossfade with no positional movement (large viewport-level slides are exactly what the preference exists to suppress).
 
 ## Usage
 
 ```tsx
-import { HorizontalTransition, setTransitionType, requireNavigation } from "shelving/ui";
-import { startTransition } from "react";
-
-function navigate(direction: "forward" | "back", url: string) {
-  const nav = requireNavigation();
-  startTransition(() => {
-    setTransitionType(direction);
-    nav.forward(url);
-  });
-}
-
-// In the layout:
-<HorizontalTransition>
-  <Router routes={ROUTES}/>
-</HorizontalTransition>
+import { HorizontalTransition, Navigation, Router } from "shelving/ui";
+
+// Links slide right, the browser back button slides left.
+<Navigation>
+  <HorizontalTransition>
+    <Router routes={ROUTES}/>
+  </HorizontalTransition>
+</Navigation>
 ```
 
 ## Styling
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--horizontal-transition-size` | Slide distance for the enter/leave keyframes | `25vw` |
+| `--horizontal-transition-size` | Slide distance for the enter/leave keyframes. A percentage is of the element's own width. | `100%` |
 | `--horizontal-transition-duration` | Duration of the slide keyframes | `var(--duration-normal)` |
 
 **Global tokens it reads** — `--duration-normal`.

package/ui/transition/Transition.md

@@ -6,7 +6,8 @@ The base View Transition wrapper. It wraps its children in React 19's `<ViewTran
 
 - Set `default` for the base transition; `forward` and `back` default to it and let you pick a direction-aware variant. The class names must correspond to `::view-transition-old(.className)` / `::view-transition-new(.className)` rules in your CSS.
 - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`, from `Transition.css`).
-- Direction is driven by the active view-transition type. Call `setTransitionType("forward")` (or `"back"`) inside a `startTransition()` callback before navigating; the variants read that type to choose the correct slide.
+- Direction is driven by the active view-transition type. `<Navigation>` sets it for each page change (`"forward"` for a link or `NavigationStore.forward()`, `"back"` for the browser back button). For any other change, call `setTransitionType("forward")` (or `"back"`) inside a `startTransition()` callback; the variants read that type to choose the correct slide.
+- React runs a view transition only for a transition update (`startTransition()`, `useDeferredValue()` or a Suspense reveal). A sync update, for example a `useStore()` change, swaps the content with no animation.
 - The preset variants honour `prefers-reduced-motion: reduce` — positional movement (slides, collapse) is removed while opacity-only fades are kept (see each preset's page). Custom transition classes should ship their own `@media (prefers-reduced-motion: reduce)` override; `animation: none` on the `::view-transition-*` pseudo-elements makes the swap an instant cut while the DOM update still happens.
 
 ## Usage
@@ -31,24 +32,40 @@ import { FadeTransition } from "shelving/ui";
 </FadeTransition>
 ```
 
+### Page transitions
+
+`<Navigation>` publishes each page change as a transition with a direction type:
+
+```tsx
+import { HorizontalTransition, Navigation, Router } from "shelving/ui";
+
+// Slides right on forward, left on back:
+<Navigation>
+  <HorizontalTransition>
+    <Router routes={ROUTES}/>
+  </HorizontalTransition>
+</Navigation>
+```
+
 ### Setting the direction with `setTransitionType()`
 
 ```tsx
-import { HorizontalTransition, setTransitionType, requireNavigation } from "shelving/ui";
-import { startTransition } from "react";
-
-function go(direction: "forward" | "back", url: string) {
-  const nav = requireNavigation();
-  startTransition(() => {
-    setTransitionType(direction);
-    nav.forward(url);
-  });
+import { HorizontalTransition, setTransitionType } from "shelving/ui";
+import { startTransition, useState } from "react";
+
+function Steps() {
+  const [step, setStep] = useState(0);
+  const go = (direction: "forward" | "back") =>
+    startTransition(() => {
+      setTransitionType(direction);
+      setStep(s => s + (direction === "forward" ? 1 : -1));
+    });
+  return (
+    <HorizontalTransition>
+      <Step key={step} step={step} onNext={() => go("forward")} onBack={() => go("back")}/>
+    </HorizontalTransition>
+  );
 }
-
-// In the layout — slides right on forward, left on back:
-<HorizontalTransition>
-  <Router routes={ROUTES}/>
-</HorizontalTransition>
 ```
 
 ## Styling

package/ui/transition/VerticalTransition.css

@@ -1,6 +1,11 @@
-@layer base {
+@import url("../style/layers.css");
+@import url("../style/Duration.module.css");
+
+/* Global CSS, not a CSS module — see `Transition.css` for why. */
+@layer defaults {
 	:root {
-		--vertical-transition-size: 25vh;
+		/* A percentage is of the snapshot's own size, so the old and new content sit edge to edge and never overlap. */
+		--vertical-transition-size: 100%;
 		--vertical-transition-duration: var(--duration-normal);
 	}
 }
@@ -53,6 +58,12 @@
 	}
 }
 
+/* Clip the slide to the element's own box, so it does not paint over the content around it. */
+::view-transition-group(.slide-up),
+::view-transition-group(.slide-down) {
+	overflow: clip;
+}
+
 ::view-transition-new(.slide-up) {
 	animation: slide-in-from-bottom var(--vertical-transition-duration) ease-in-out both;
 }

package/ui/transition/VerticalTransition.md

@@ -5,8 +5,19 @@ A direction-aware `<Transition>` preset that slides its children vertically —
 **Things to know:**
 
 - Slides down by default and when the type is `"forward"`; slides up when the type is `"back"`.
-- Set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback before navigating — see `<Transition>`.
+- Inside `<Navigation>` the direction is automatic: a link click, `NavigationStore.forward()` or `NavigationStore.redirect()` sets the `"forward"` type, and the browser back or forward button sets `"back"`. Outside `<Navigation>`, set the direction with `setTransitionType("forward" | "back")` inside a `startTransition()` callback — see `<Transition>`.
 - Pass `overlay` to raise the transition group above surrounding content during the animation (`z-index: 100`).
+- The old and new content slide a full height apart, so they sit edge to edge and never overlap.
+- The slide is clipped to the element's own box (`overflow: clip` on the group), so it does not paint over the content around it.
+- During the slide, the snapshots paint above fixed elements such as a bottom bar. To keep a fixed element on top, give it its own `view-transition-name` and put the slide groups below it:
+
+  ```css
+  ::view-transition-group(.slide-up),
+  ::view-transition-group(.slide-down) {
+    z-index: -1;
+  }
+  ```
+
 - Under `prefers-reduced-motion: reduce` the slide distance is forced to `0`, so the transition degrades to an opacity-only crossfade with no positional movement (large viewport-level slides are exactly what the preference exists to suppress).
 
 ## Usage
@@ -23,7 +34,7 @@ import { VerticalTransition } from "shelving/ui";
 
 | Variable | Styles | Default |
 |---|---|---|
-| `--vertical-transition-size` | Slide distance for the enter/leave keyframes | `25vh` |
+| `--vertical-transition-size` | Slide distance for the enter/leave keyframes. A percentage is of the element's own height. | `100%` |
 | `--vertical-transition-duration` | Duration of the slide keyframes | `var(--duration-normal)` |
 
 **Global tokens it reads** — `--duration-normal`.