shelving 1.268.0 → 1.268.2

package/package.json

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

package/react/createAPIContext.d.ts

@@ -1,5 +1,6 @@
 import { type ReactElement } from "react";
 import type { Endpoint } from "../api/endpoint/Endpoint.js";
+import { APICache } from "../api/index.js";
 import type { APIProvider } from "../api/provider/APIProvider.js";
 import type { EndpointStore } from "../api/store/EndpointStore.js";
 import type { ChildProps } from "../ui/index.js";
@@ -13,8 +14,10 @@ export interface APIContext<P, R> {
     /** React hook to return an `EndpointStore` for the specified endpoint/payload in the current `APIProvider` context. */
     useAPI<PP extends P, RR extends R>(this: void, endpoint: Endpoint<PP, RR>, payload: PP): EndpointStore<PP, RR>;
     useAPI<PP extends P, RR extends R>(this: void, endpoint: Nullish<Endpoint<PP, RR>>, payload: PP): EndpointStore<PP, RR> | undefined;
-    /** The `<APIContext>` wrapper to give your React components access to this API provider. */
+    /** Create a new `APICache` and provide it as context to child nodes, to allow them to use `useAPI()` */
     readonly APIContext: (props: ChildProps) => ReactElement;
+    /** Return the underlying `APICache` for `<APIContext>` */
+    requireAPICache(): APICache<P, R>;
 }
 /**
  * Create an API context.

package/react/createAPIContext.js

@@ -15,15 +15,18 @@ import { useStore } from "./useStore.js";
  */
 export function createAPIContext(provider) {
     const CacheContext = createContext(undefined);
-    function useAPI(endpoint, payload) {
+    function requireAPICache(caller = requireAPICache) {
         const cache = use(CacheContext);
         if (!cache)
-            throw new RequiredError(`useAPI() can only be used inside <APIContext>`, { caller: useAPI });
-        return useStore(endpoint ? cache.get(endpoint).get(payload) : undefined);
+            throw new RequiredError(`Must be used inside <APIContext>`, { caller });
+        return cache;
+    }
+    function useAPI(endpoint, payload) {
+        return useStore(endpoint ? requireAPICache(useAPI).get(endpoint).get(payload) : undefined);
     }
     function APIContext({ children }) {
         const cache = useInstance(APICache, provider);
         return _jsx(CacheContext, { value: cache, children: children });
     }
-    return { useAPI, APIContext };
+    return { requireAPICache, useAPI, APIContext };
 }

package/react/createDBContext.d.ts

@@ -1,4 +1,5 @@
 import { type ReactElement, type ReactNode } from "react";
+import { DBCache } from "../db/cache/DBCache.js";
 import type { Collection } from "../db/collection/Collection.js";
 import type { DBProvider } from "../db/provider/DBProvider.js";
 import type { ItemStore } from "../db/store/ItemStore.js";
@@ -23,10 +24,12 @@ export interface DBContext<I extends Identifier, T extends Data> {
     query: Nullish<Query<Item<II, TT>>>): QueryStore<II, TT> | undefined;
     useQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, //
     query: Query<Item<II, TT>>): QueryStore<II, TT>;
-    /** The `<DataContext>` wrapper to give your React components access to this data. */
+    /** Create a new `DBCache` and provide it as context to child nodes, to allow them to use `useItem()` and `useQuery()` */
     readonly DBContext: ({ children }: {
         children: ReactNode;
     }) => ReactElement;
+    /** Return the underlying `DBCache` for `<DBContext>` */
+    requireDBCache(): DBCache<I, T>;
 }
 /**
  * Create a data context

package/react/createDBContext.js

@@ -15,23 +15,23 @@ import { useStore } from "./useStore.js";
  */
 export function createDBContext(provider) {
     const CacheContext = createContext(undefined);
-    function useItem(collection, //
-    id) {
+    function requireDBCache(caller = requireDBCache) {
         const cache = use(CacheContext);
         if (!cache)
-            throw new RequiredError("useItem() can only be used inside <DBContext>", { caller: useItem });
-        return useStore(collection && id ? cache.getItem(collection, id) : undefined);
+            throw new RequiredError(`Must be used inside <DBContext>`, { caller });
+        return cache;
+    }
+    function useItem(collection, //
+    id) {
+        return useStore(collection && id ? requireDBCache(useItem).getItem(collection, id) : undefined);
     }
     function useQuery(collection, //
     query) {
-        const cache = use(CacheContext);
-        if (!cache)
-            throw new RequiredError("useQuery() can only be used inside <DBContext>", { caller: useQuery });
-        return useStore(collection && query ? cache.getQuery(collection, query) : undefined);
+        return useStore(collection && query ? requireDBCache(useQuery).getQuery(collection, query) : undefined);
     }
     function DBContext({ children }) {
         const cache = useInstance(DBCache, provider);
         return _jsx(CacheContext, { value: cache, children: children });
     }
-    return { useItem, useQuery, DBContext };
+    return { requireDBCache, useItem, useQuery, DBContext };
 }

package/ui/docs/DocumentationCard.js

@@ -3,6 +3,7 @@ import { Card } from "../block/Card.js";
 import { Paragraph } from "../block/Paragraph.js";
 import { Row } from "../block/Row.js";
 import { Subheading } from "../block/Subheading.js";
+import { CollapseTransition } from "../transition/CollapseTransition.js";
 import { DocumentationButtons } from "./DocumentationButtons.js";
 import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
 import { DocumentationSignatures } from "./DocumentationSignatures.js";
@@ -19,5 +20,5 @@ export function DocumentationCard({ path, title, name, kind, description, signat
 class: _memberOf, ...props }) {
     // `path` is the symbol's own canonical URL, stamped by `flattenTree()` — link straight to it.
     const color = kind ? getDocumentationKindColor(kind) : undefined;
-    return (_jsxs(Card, { href: path, color: color, children: [_jsx(Subheading, { space: "none", children: _jsxs(Row, { left: true, wrap: true, gap: "xsmall", children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind })] }) }), _jsx(DocumentationButtons, { ...props, space: "none" }), description && _jsx(Paragraph, { children: description }), _jsx(DocumentationSignatures, { signatures: signatures })] }));
+    return (_jsxs(Card, { href: path, color: color, children: [_jsx(Subheading, { space: "none", children: _jsxs(Row, { left: true, wrap: true, gap: "xsmall", children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind })] }) }), _jsx(CollapseTransition, { children: _jsx(DocumentationButtons, { ...props, space: "none" }) }), description && _jsx(Paragraph, { children: description }), _jsx(DocumentationSignatures, { signatures: signatures })] }));
 }

package/ui/docs/DocumentationCard.tsx

@@ -4,6 +4,7 @@ import { Card } from "../block/Card.js";
 import { Paragraph } from "../block/Paragraph.js";
 import { Row } from "../block/Row.js";
 import { Subheading } from "../block/Subheading.js";
+import { CollapseTransition } from "../transition/CollapseTransition.js";
 import { DocumentationButtons } from "./DocumentationButtons.js";
 import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
 import { DocumentationSignatures } from "./DocumentationSignatures.js";
@@ -37,7 +38,9 @@ export function DocumentationCard({
 					{kind && <DocumentationKind kind={kind} />}
 				</Row>
 			</Subheading>
-			<DocumentationButtons {...props} space="none" />
+			<CollapseTransition>
+				<DocumentationButtons {...props} space="none" />
+			</CollapseTransition>
 			{description && <Paragraph>{description}</Paragraph>}
 			<DocumentationSignatures signatures={signatures} />
 		</Card>

package/ui/form/Progress.css

@@ -0,0 +1,23 @@
+/*
+* Keyframes for the `Progress` indeterminate animation.
+*
+* This lives in a plain (non-module) CSS file, not `Progress.module.css`, because Bun's CSS-modules
+* transform renames the `@keyframes` identifier (appends the module hash) but does *not* rewrite the
+* matching `animation` reference, so a keyframes block defined in the module file animates against a
+* name that no longer exists. Keeping the declaration global here leaves the name stable, and the
+* un-rewritten `animation: progress-flow` reference in `Progress.module.css` resolves to it. This
+* mirrors how the `transition` components keep their keyframes in sibling `.css` files.
+*
+* Tracked in dhoulb/shelving#259 (revert once Bun ships the fix for oven-sh/bun#18921).
+*/
+
+/* Conveyor the block fully off the left edge, across, and fully off the right — then it loops back round unseen. `-70%`/`170%` fully clear a `40%`-wide block, and `linear` timing keeps a constant speed with no ease-out stall at the ends. */
+@keyframes progress-flow {
+	from {
+		background-position: -70% 0;
+	}
+
+	to {
+		background-position: 170% 0;
+	}
+}

package/ui/form/Progress.d.ts

@@ -2,6 +2,7 @@ import type { ReactElement } from "react";
 import { type Nullish } from "../../util/null.js";
 import { type ColorVariants } from "../style/Color.js";
 import { type StatusVariants } from "../style/Status.js";
+import "./Progress.css";
 /**
  * Props for `Progress`, a continuous horizontal progress bar.
  *

package/ui/form/Progress.js

@@ -4,6 +4,7 @@ import { notNullish } from "../../util/null.js";
 import { getColorClass } from "../style/Color.js";
 import { getStatusClass } from "../style/Status.js";
 import { getClass, getModuleClass } from "../util/css.js";
+import "./Progress.css";
 import styles from "./Progress.module.css";
 /**
  * Show progress as a single continuous horizontal bar, filled to `value` within the `min`–`max` range (matches `getPercent()` and `formatPercent()`).

package/ui/form/Progress.module.css

@@ -73,13 +73,4 @@
 	}
 }
 
-/* Conveyor the block fully off the left edge, across, and fully off the right — then it loops back round unseen. `-70%`/`170%` fully clear a `40%`-wide block, and `linear` timing keeps a constant speed with no ease-out stall at the ends. */
-@keyframes progress-flow {
-	from {
-		background-position: -70% 0;
-	}
-
-	to {
-		background-position: 170% 0;
-	}
-}
+/* The `progress-flow` keyframes referenced above live in the sibling non-module `Progress.css` — see the note there for why they can't be defined in this module file. */

package/ui/form/Progress.tsx

@@ -4,6 +4,7 @@ import { type Nullish, notNullish } from "../../util/null.js";
 import { type ColorVariants, getColorClass } from "../style/Color.js";
 import { getStatusClass, type StatusVariants } from "../style/Status.js";
 import { getClass, getModuleClass } from "../util/css.js";
+import "./Progress.css";
 import styles from "./Progress.module.css";
 
 /**

package/ui/layout/SidebarLayout.js

@@ -12,6 +12,7 @@ const LAYOUT_TOGGLE_CLASS = getModuleClass(LAYOUT_CSS, "toggle");
 const LAYOUT_OVERLAY_CLASS = getModuleClass(LAYOUT_CSS, "overlay");
 const LAYOUT_MAIN_CLASS = getModuleClass(LAYOUT_CSS, "main");
 const LAYOUT_OPEN_CLASS = getModuleClass(LAYOUT_CSS, "open");
+const LAYOUT_RIGHT_CLASS = getModuleClass(LAYOUT_CSS, "right");
 /**
  * Layout with a fixed-width side column (typically navigation) next to a scrollable main content column.
  * - The sidebar is rendered as `<nav>` — it almost always contains the page's primary navigation.
@@ -31,13 +32,7 @@ export function SidebarLayout({ sidebar, children, right = false }) {
         if (path)
             setOpen(false);
     }, [path]);
-    const sidebarEl = (_jsx("nav", { className: getClass(LAYOUT_SIDEBAR_CLASS, //
-        open && LAYOUT_OPEN_CLASS), children: sidebar }, "sidebar"));
-    // Wrap the scrolling content column in `<RouteCache>` so recently-visited pages stay mounted but hidden
-    // — keeping the scroll position of this `.content` container (and all page state) intact across
-    // back/forward navigation. The sidebar and drawer state stay outside the cache, so they are neither
-    // duplicated nor remounted as the URL changes.
-    const contentEl = (_jsx(RouteCache, { children: _jsxs("div", { className: LAYOUT_CONTENT_CLASS, children: [_jsx("div", { className: LAYOUT_TOGGLE_CLASS, children: _jsx(Button, { title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(XMarkIcon, {}) : _jsx(Bars3Icon, {}) }) }), children] }) }, "content"));
-    const overlayEl = open && (_jsx("button", { type: "button", className: LAYOUT_OVERLAY_CLASS, "aria-label": "Close menu", onClick: () => setOpen(false) }, "overlay"));
-    return _jsx("main", { className: LAYOUT_MAIN_CLASS, children: right ? [contentEl, sidebarEl, overlayEl] : [sidebarEl, contentEl, overlayEl] });
+    // DOM order is always sidebar → content → overlay; the `right` variant flips the visual column order in CSS, so the markup never reshuffles.
+    return (_jsxs("main", { className: getClass(LAYOUT_MAIN_CLASS, right && LAYOUT_RIGHT_CLASS), children: [_jsx("nav", { className: getClass(LAYOUT_SIDEBAR_CLASS, //
+                open && LAYOUT_OPEN_CLASS), children: sidebar }), _jsx(RouteCache, { children: _jsxs("div", { className: LAYOUT_CONTENT_CLASS, children: [_jsx("div", { className: LAYOUT_TOGGLE_CLASS, children: _jsx(Button, { title: open ? "Close menu" : "Show menu", onClick: () => setOpen(o => !o), children: open ? _jsx(XMarkIcon, {}) : _jsx(Bars3Icon, {}) }) }), children] }) }), _jsx("button", { type: "button", className: getClass(LAYOUT_OVERLAY_CLASS, open && LAYOUT_OPEN_CLASS), "aria-label": "Close menu", onClick: () => setOpen(false) })] }));
 }

package/ui/layout/SidebarLayout.module.css

@@ -14,8 +14,11 @@
 * document so `.main` is the only scroll container.
 *
 * On narrow viewports the sidebar becomes an off-canvas drawer that slides off the left edge of the
-* screen; the `.toggle` button opens/closes it and the `.overlay` dims the page behind the open
-* drawer (both are hidden entirely on wide viewports).
+* screen (the right edge for the `.right` variant); the `.toggle` button opens/closes it and the
+* `.overlay` dims the page behind the open drawer (both are hidden entirely on wide viewports).
+*
+* The `.right` variant keeps the DOM order static (sidebar → content) and mirrors the visual order in
+* CSS by swapping the grid columns, so the markup never reshuffles.
 */
 
 @layer components {
@@ -103,6 +106,25 @@
 		background: var(--sidebar-layout-background, var(--tint-100));
 	}
 
+	/*
+	 * Right variant — mirror the layout so the sidebar sits on the right, without touching DOM order.
+	 * The grid columns are swapped, the sidebar and content are placed into them explicitly, and the
+	 * divider border moves to the sidebar's inner (left) edge.
+	 */
+	.main.right {
+		grid-template-columns: 1fr var(--sidebar-layout-width, 17.5rem);
+	}
+
+	.main.right .sidebar {
+		grid-column: 2;
+		border-right: none;
+		border-left: var(--sidebar-layout-border, var(--stroke-normal) solid var(--tint-80));
+	}
+
+	.main.right .content {
+		grid-column: 1;
+	}
+
 	/* Wrapper for the menu toggle button — hidden on wide viewports, shown on narrow ones (see media query). */
 	.toggle {
 		display: none;
@@ -115,19 +137,10 @@
 		display: none;
 	}
 
-	@keyframes overlay-fade-in {
-		from {
-			opacity: 0;
-		}
-
-		to {
-			opacity: 1;
-		}
-	}
-
-	/* On narrow viewports the sidebar becomes an off-canvas drawer that slides in from the left. */
+	/* On narrow viewports the sidebar becomes an off-canvas drawer that slides in from the left (right for the `right` variant). */
 	@media (width <= 48rem) {
-		.main {
+		.main,
+		.main.right {
 			grid-template-columns: 1fr;
 		}
 
@@ -150,6 +163,17 @@
 			box-shadow: 0 0 1.5rem #0006;
 		}
 
+		/* Right variant: dock the drawer to the right edge and slide it in from the right instead. */
+		.main.right .sidebar {
+			left: auto;
+			right: 0;
+			transform: translateX(100%);
+		}
+
+		.main.right .sidebar.open {
+			transform: translateX(0);
+		}
+
 		/* Pin the toggle button to the top-right so it stays reachable while the content column scrolls. */
 		.toggle {
 			display: block;
@@ -159,7 +183,7 @@
 			z-index: 110;
 		}
 
-		/* Dim the page behind the open drawer; clicking the overlay closes it. */
+		/* Dim the page behind the open drawer; clicking the overlay closes it. Always mounted, so it fades both ways via the `open` class. */
 		.overlay {
 			/* Box */
 			display: block;
@@ -173,7 +197,18 @@
 			/* Style */
 			background: var(--shadow-color);
 			cursor: pointer;
-			animation: overlay-fade-in var(--duration-normal) ease-in-out;
+
+			/* Hidden and non-interactive until open. Transition `visibility` alongside `opacity` so the overlay stays in the a11y tree (and clickable) only while shown, then flips hidden at the end of the fade-out. */
+			opacity: 0;
+			visibility: hidden;
+			transition:
+				opacity var(--duration-normal) ease-in-out,
+				visibility var(--duration-normal);
+		}
+
+		.overlay.open {
+			opacity: 1;
+			visibility: visible;
 		}
 	}
 }

package/ui/layout/SidebarLayout.tsx

@@ -13,6 +13,7 @@ const LAYOUT_TOGGLE_CLASS = getModuleClass(LAYOUT_CSS, "toggle");
 const LAYOUT_OVERLAY_CLASS = getModuleClass(LAYOUT_CSS, "overlay");
 const LAYOUT_MAIN_CLASS = getModuleClass(LAYOUT_CSS, "main");
 const LAYOUT_OPEN_CLASS = getModuleClass(LAYOUT_CSS, "open");
+const LAYOUT_RIGHT_CLASS = getModuleClass(LAYOUT_CSS, "right");
 
 /**
  * Props for `<SidebarLayout>` — the `sidebar` column content, main `children`, and a `right` placement flag.
@@ -46,38 +47,35 @@ export function SidebarLayout({ sidebar, children, right = false }: SidebarLayou
 		if (path) setOpen(false);
 	}, [path]);
 
-	const sidebarEl = (
-		<nav
-			key="sidebar"
-			className={getClass(
-				LAYOUT_SIDEBAR_CLASS, //
-				open && LAYOUT_OPEN_CLASS,
-			)}
-		>
-			{sidebar}
-		</nav>
-	);
-
-	// Wrap the scrolling content column in `<RouteCache>` so recently-visited pages stay mounted but hidden
-	// — keeping the scroll position of this `.content` container (and all page state) intact across
-	// back/forward navigation. The sidebar and drawer state stay outside the cache, so they are neither
-	// duplicated nor remounted as the URL changes.
-	const contentEl = (
-		<RouteCache key="content">
-			<div className={LAYOUT_CONTENT_CLASS}>
-				<div className={LAYOUT_TOGGLE_CLASS}>
-					<Button title={open ? "Close menu" : "Show menu"} onClick={() => setOpen(o => !o)}>
-						{open ? <XMarkIcon /> : <Bars3Icon />}
-					</Button>
+	// DOM order is always sidebar → content → overlay; the `right` variant flips the visual column order in CSS, so the markup never reshuffles.
+	return (
+		<main className={getClass(LAYOUT_MAIN_CLASS, right && LAYOUT_RIGHT_CLASS)}>
+			<nav
+				className={getClass(
+					LAYOUT_SIDEBAR_CLASS, //
+					open && LAYOUT_OPEN_CLASS,
+				)}
+			>
+				{sidebar}
+			</nav>
+			{/* Wrap the scrolling content column in `<RouteCache>` so recently-visited pages stay mounted but hidden — keeping the scroll position of this `.content` container (and all page state) intact across back/forward navigation. The sidebar and drawer state stay outside the cache, so they are neither duplicated nor remounted as the URL changes. */}
+			<RouteCache>
+				<div className={LAYOUT_CONTENT_CLASS}>
+					<div className={LAYOUT_TOGGLE_CLASS}>
+						<Button title={open ? "Close menu" : "Show menu"} onClick={() => setOpen(o => !o)}>
+							{open ? <XMarkIcon /> : <Bars3Icon />}
+						</Button>
+					</div>
+					{children}
 				</div>
-				{children}
-			</div>
-		</RouteCache>
+			</RouteCache>
+			{/* Overlay is always mounted (on narrow viewports) so it can fade both in and out via the `open` class — a conditionally-mounted element can't animate on the way out. */}
+			<button
+				type="button"
+				className={getClass(LAYOUT_OVERLAY_CLASS, open && LAYOUT_OPEN_CLASS)}
+				aria-label="Close menu"
+				onClick={() => setOpen(false)}
+			/>
+		</main>
 	);
-
-	const overlayEl = open && (
-		<button key="overlay" type="button" className={LAYOUT_OVERLAY_CLASS} aria-label="Close menu" onClick={() => setOpen(false)} />
-	);
-
-	return <main className={LAYOUT_MAIN_CLASS}>{right ? [contentEl, sidebarEl, overlayEl] : [sidebarEl, contentEl, overlayEl]}</main>;
 }

package/ui/transition/CollapseTransition.d.ts

@@ -1,5 +1,4 @@
 import type { ReactElement } from "react";
-import "./CollapseTransition.css";
 import { type TransitionProps } from "./Transition.js";
 /**
  * Props for the `CollapseTransition` component — the shared transition variant props.

package/ui/transition/CollapseTransition.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import "./CollapseTransition.css";
+import { getModuleClass } from "../util/css.js";
+import COLLAPSE_CSS from "./CollapseTransition.module.css";
 import { Transition } from "./Transition.js";
+const COLLAPSE_CLASS = getModuleClass(COLLAPSE_CSS, "collapse");
 /**
  * Transition that collapses its children in and out by animating their size.
  *
@@ -8,5 +10,5 @@ import { Transition } from "./Transition.js";
  * @see https://shelving.cc/ui/CollapseTransition
  */
 export function CollapseTransition(props) {
-    return _jsx(Transition, { default: "collapse", ...props });
+    return _jsx(Transition, { default: COLLAPSE_CLASS, ...props });
 }

package/ui/transition/CollapseTransition.tsx

@@ -1,7 +1,10 @@
 import type { ReactElement } from "react";
-import "./CollapseTransition.css";
+import { getModuleClass } from "../util/css.js";
+import COLLAPSE_CSS from "./CollapseTransition.module.css";
 import { Transition, type TransitionProps } from "./Transition.js";
 
+const COLLAPSE_CLASS = getModuleClass(COLLAPSE_CSS, "collapse");
+
 /**
  * Props for the `CollapseTransition` component — the shared transition variant props.
  *
@@ -16,5 +19,5 @@ export interface CollapseTransitionProps extends TransitionProps {}
  * @see https://shelving.cc/ui/CollapseTransition
  */
 export function CollapseTransition(props: CollapseTransitionProps): ReactElement {
-	return <Transition default="collapse" {...props} />;
+	return <Transition default={COLLAPSE_CLASS} {...props} />;
 }

package/ui/transition/Transition.d.ts

@@ -1,16 +1,27 @@
 import { type ReactElement } from "react";
 import type { ChildProps } from "../util/props.js";
-import type { TransitionClasses } from "./util.js";
-import "./Transition.css";
 /**
  * Variant props shared by every transition component.
  *
- * @see https://shelving.cc/ui/TransitionProps
+ * @see https://shelving.cc/ui/TransitionVariants
  */
-export interface TransitionProps extends ChildProps {
+export interface TransitionVariants {
     /** Render this transition above other transitions (z-index: 100 on the group). */
     overlay?: boolean | undefined;
 }
+/**
+ * React props for `<Transition>` component.
+ *
+ * @see https://shelving.cc/ui/TransitionProps
+ */
+export interface TransitionProps extends ChildProps, TransitionVariants {
+    /** The default CSS class. */
+    default?: string | undefined;
+    /** The CSS class to apply when the transition is moving forward. */
+    forward?: string | undefined;
+    /** The CSS class to apply when the transition is moving backward. */
+    back?: string | undefined;
+}
 /**
  * Wrap children in a React View Transition, applying the configured transition classes.
  *
@@ -22,4 +33,4 @@ export interface TransitionProps extends ChildProps {
  * @returns A `<ViewTransition>` element wrapping the children.
  * @see https://shelving.cc/ui/Transition
  */
-export declare function Transition({ children, default: d, forward, back, ...variants }: Partial<TransitionClasses> & TransitionProps): ReactElement;
+export declare function Transition({ children, default: d, forward, back, overlay }: TransitionProps): ReactElement;

package/ui/transition/Transition.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 /// <reference types="react/canary" />
 import { ViewTransition } from "react";
-import { getClass } from "../util/css.js";
-import "./Transition.css";
+import { getClass, getModuleClass } from "../util/css.js";
+import TRANSITION_CSS from "./Transition.module.css";
+const TRANSITION_OVERLAY_CLASS = getModuleClass(TRANSITION_CSS, "overlay");
 /**
  * Wrap children in a React View Transition, applying the configured transition classes.
  *
@@ -14,11 +15,10 @@ import "./Transition.css";
  * @returns A `<ViewTransition>` element wrapping the children.
  * @see https://shelving.cc/ui/Transition
  */
-export function Transition({ children, default: d, forward = d, back = d, ...variants }) {
-    const classes = {
-        default: getClass(d, variants),
-        forward: getClass(forward, variants),
-        back: getClass(back, variants),
-    };
-    return _jsx(ViewTransition, { default: classes, children: children });
+export function Transition({ children, default: d, forward = d, back = d, overlay = false }) {
+    return (_jsx(ViewTransition, { default: {
+            default: getClass(d, overlay && TRANSITION_OVERLAY_CLASS),
+            forward: getClass(forward, overlay && TRANSITION_OVERLAY_CLASS),
+            back: getClass(back, overlay && TRANSITION_OVERLAY_CLASS),
+        }, children: children }));
 }

package/ui/transition/Transition.tsx

@@ -1,20 +1,35 @@
 /// <reference types="react/canary" />
 import { type ReactElement, ViewTransition } from "react";
-import { getClass } from "../util/css.js";
+import { getClass, getModuleClass } from "../util/css.js";
 import type { ChildProps } from "../util/props.js";
-import type { TransitionClasses } from "./util.js";
-import "./Transition.css";
+import TRANSITION_CSS from "./Transition.module.css";
+
+const TRANSITION_OVERLAY_CLASS = getModuleClass(TRANSITION_CSS, "overlay");
 
 /**
  * Variant props shared by every transition component.
  *
- * @see https://shelving.cc/ui/TransitionProps
+ * @see https://shelving.cc/ui/TransitionVariants
  */
-export interface TransitionProps extends ChildProps {
+export interface TransitionVariants {
 	/** Render this transition above other transitions (z-index: 100 on the group). */
 	overlay?: boolean | undefined;
 }
 
+/**
+ * React props for `<Transition>` component.
+ *
+ * @see https://shelving.cc/ui/TransitionProps
+ */
+export interface TransitionProps extends ChildProps, TransitionVariants {
+	/** The default CSS class. */
+	default?: string | undefined;
+	/** The CSS class to apply when the transition is moving forward. */
+	forward?: string | undefined;
+	/** The CSS class to apply when the transition is moving backward. */
+	back?: string | undefined;
+}
+
 /**
  * Wrap children in a React View Transition, applying the configured transition classes.
  *
@@ -26,17 +41,16 @@ export interface TransitionProps extends ChildProps {
  * @returns A `<ViewTransition>` element wrapping the children.
  * @see https://shelving.cc/ui/Transition
  */
-export function Transition({
-	children,
-	default: d,
-	forward = d,
-	back = d,
-	...variants
-}: Partial<TransitionClasses> & TransitionProps): ReactElement {
-	const classes: TransitionClasses = {
-		default: getClass(d, variants),
-		forward: getClass(forward, variants),
-		back: getClass(back, variants),
-	};
-	return <ViewTransition default={classes}>{children}</ViewTransition>;
+export function Transition({ children, default: d, forward = d, back = d, overlay = false }: TransitionProps): ReactElement {
+	return (
+		<ViewTransition
+			default={{
+				default: getClass(d, overlay && TRANSITION_OVERLAY_CLASS),
+				forward: getClass(forward, overlay && TRANSITION_OVERLAY_CLASS),
+				back: getClass(back, overlay && TRANSITION_OVERLAY_CLASS),
+			}}
+		>
+			{children}
+		</ViewTransition>
+	);
 }