shelving 1.285.6 → 1.286.0

package/package.json

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

package/ui/block/Card.d.ts

@@ -23,7 +23,7 @@ export interface CardProps extends ClickableProps, StatusVariants, BlockVariants
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  * - Accepts a `status` colour and raw `ColorProps` — the card styles the box; lay out its contents however the use case needs.
- * - Carries a `normal` drop shadow by default — set `shadow="none"` to flatten a card, or `shadow="small"` / `shadow="large"` to adjust its elevation.
+ * - Has no drop shadow by default — set `shadow="small"`, `shadow="normal"` or `shadow="large"` to raise a card.
  *
  * @kind component
  * @see https://shelving.cc/ui/Card

package/ui/block/Card.js

@@ -11,7 +11,7 @@ import CARD_CSS from "./Card.module.css";
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  * - Accepts a `status` colour and raw `ColorProps` — the card styles the box; lay out its contents however the use case needs.
- * - Carries a `normal` drop shadow by default — set `shadow="none"` to flatten a card, or `shadow="small"` / `shadow="large"` to adjust its elevation.
+ * - Has no drop shadow by default — set `shadow="small"`, `shadow="normal"` or `shadow="large"` to raise a card.
  *
  * @kind component
  * @see https://shelving.cc/ui/Card

package/ui/block/Card.md

@@ -1,13 +1,13 @@
 # Card
 
-A boxed surface that groups a self-contained piece of content. Rendered as an `<article>`, painted from the tint ladder (surface, border, text) and styled with rounded corners and padding by default.
+A boxed surface that groups a self-contained piece of content. Rendered as an `<article>`, painted from the tint ladder (surface, text) and styled with rounded corners and padding by default.
 
 **Things to know:**
 
 - Set `href` or `onClick` to make the whole card navigable — a stretched, visually-hidden overlay `<a>` / `<button>` covers the card while the children render normally inside. Real interactive elements inside the card (inline links, buttons) stay clickable and keyboard-focusable.
-- `color=` and `status=` move the tint anchor for the card's scope, so the surface, border, text, and hover shade all re-derive together — and nested components (`<Tag>`, `<Preformatted>`, `<Button>`) inherit the same tint.
+- `color=` and `status=` move the tint anchor for the card's scope, so the surface, text, and hover shade all re-derive together — and nested components (`<Tag>`, `<Preformatted>`, `<Button>`) inherit the same tint.
 - A card styles only the box. Lay out its contents with the usual block components (`<Subheading>`, `<Paragraph>`, `<Row>`, …).
-- Cards carry a `normal` drop shadow by default — set `shadow="none"` to flatten a given card, or `shadow="small"` / `shadow="large"` to adjust its elevation.
+- Cards have no drop shadow by default — set `shadow="small"`, `shadow="normal"` or `shadow="large"` to raise a given card.
 - Composes the standard styling variants: `color`, `status`, `padding`, `space`, `width`, `shadow`, plus typography.
 
 ## Usage
@@ -49,14 +49,14 @@ import { Card, Subheading } from "shelving/ui";
 ```tsx
 import { Card, Subheading } from "shelving/ui";
 
-// Flatten one card; raise another.
-<Card shadow="none"><Subheading>Flat</Subheading></Card>
-<Card shadow="large"><Subheading>Raised</Subheading></Card>
+// Raise a card a little or a lot.
+<Card shadow="small"><Subheading>Raised</Subheading></Card>
+<Card shadow="large"><Subheading>Raised more</Subheading></Card>
 ```
 
 ## Styling
 
-`Card` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` (on the card or an ancestor scope) to recolour everything at once — surface, border, text, and hover shade re-derive together; reach for a per-property hook for a single surgical change.
+`Card` paints from the [tint ladder](/ui/TINT_CLASS); override these hooks at `:root` (or any ancestor scope) to retheme. Apply `color=` / `status=` (on the card or an ancestor scope) to recolour everything at once — surface, text, and hover shade re-derive together; reach for a per-property hook for a single surgical change.
 
 | Variable | Styles | Default |
 |---|---|---|
@@ -64,20 +64,20 @@ import { Card, Subheading } from "shelving/ui";
 | `--card-hover-background` | Surface fill when a navigable card is hovered | `var(--tint-95)` |
 | `--card-color` | Text colour | `var(--tint-00)` |
 | `--card-border` | Border shorthand | `var(--card-stroke) solid var(--tint-80)` |
-| `--card-stroke` | Border / outline thickness | `var(--stroke-normal)` (2px) |
+| `--card-stroke` | Border thickness — set it (e.g. `var(--stroke-normal)`) to show the border | `0` |
 | `--card-radius` | Corner radius | `var(--radius-normal)` (16px) |
 | `--card-padding` | Inner padding | `var(--space-normal)` (16px) |
 | `--card-space` | Outer block margin (top + bottom) | `var(--space-paragraph)` (16px) |
-| `--card-shadow` | Drop shadow | `var(--shadow-normal)` |
+| `--card-shadow` | Drop shadow | `none` |
 | `--card-transition` | Transition | `all var(--duration-fast)` (150ms) |
 | `--card-focus-border` | Focus outline | `var(--stroke-focus) solid var(--color-focus)` |
 
-**Global tokens it reads** — move these to retheme broadly rather than overriding ladder steps directly: the tint ladder `--tint-00` / `--tint-80` / `--tint-90` / `--tint-95`, plus `--space-normal`, `--space-paragraph`, `--radius-normal`, `--shadow-normal`, `--stroke-normal`, `--stroke-focus`, `--color-focus`, and `--duration-fast`.
+**Global tokens it reads** — move these to retheme broadly rather than overriding ladder steps directly: the tint ladder `--tint-00` / `--tint-80` / `--tint-90` / `--tint-95`, plus `--space-normal`, `--space-paragraph`, `--radius-normal`, `--stroke-focus`, `--color-focus`, and `--duration-fast`.
 
 ```css
-/* Theme: flat cards with tighter corners. */
+/* Theme: raised cards with tighter corners. */
 :root {
-  --card-shadow: none;
+  --card-shadow: var(--shadow-normal);
   --card-radius: var(--radius-small);
 }
 ```

package/ui/block/Card.module.css

@@ -2,7 +2,6 @@
 @import url("../style/Color.module.css");
 @import url("../style/Duration.module.css");
 @import url("../style/Radius.module.css");
-@import url("../style/Shadow.module.css");
 @import url("../style/Space.module.css");
 @import url("../style/Stroke.module.css");
 @import url("../style/Tint.module.css");
@@ -24,22 +23,22 @@
 		position: relative;
 		margin-inline: 0;
 		margin-block: var(--card-space, var(--space-paragraph));
-		border: var(--card-border, var(--card-stroke, var(--stroke-normal) solid var(--tint-80)));
+		border: var(--card-border, var(--card-stroke, 0) solid var(--tint-80));
 		padding: var(--card-padding, var(--space-normal));
 		border-radius: var(--card-radius, var(--radius-normal));
 
 		/* Style */
 		background: var(--card-background, var(--tint-90));
 		color: var(--card-color, var(--tint-00));
-		box-shadow: var(--card-shadow, var(--shadow-normal));
+		box-shadow: var(--card-shadow, none);
 		transition: var(--card-transition, all var(--duration-fast));
 		outline: var(--card-focus-border, var(--stroke-focus) solid var(--color-focus));
-		outline-offset: calc(0px - var(--card-stroke, var(--stroke-normal)));
+		outline-offset: calc(0px - var(--stroke-focus)); /* Fully inset, so it sits inside the card edge. */
 
 		/* Hover/focus affordance driven by the overlay link/button. */
 		&:has(.overlay:hover) {
 			background: var(--card-hover-background, var(--tint-95));
-			border: var(--card-hover-border, var(--card-stroke, var(--stroke-normal)) solid var(--tint-90));
+			border: var(--card-hover-border, var(--card-stroke, 0) solid var(--tint-90));
 		}
 	}
 

package/ui/block/Card.tsx

@@ -27,7 +27,7 @@ export interface CardProps extends ClickableProps, StatusVariants, BlockVariants
  * - When `href` or `onClick` is set the card becomes navigable: a stretched overlay `<a>` / `<button>` covers the entire card while the children render normally inside.
  * - Real interactive elements inside the card (e.g. inline `<a>` links) stay clickable thanks to `position: relative; z-index: 2` rules in the stylesheet.
  * - Accepts a `status` colour and raw `ColorProps` — the card styles the box; lay out its contents however the use case needs.
- * - Carries a `normal` drop shadow by default — set `shadow="none"` to flatten a card, or `shadow="small"` / `shadow="large"` to adjust its elevation.
+ * - Has no drop shadow by default — set `shadow="small"`, `shadow="normal"` or `shadow="large"` to raise a card.
  *
  * @kind component
  * @see https://shelving.cc/ui/Card

package/ui/block/Panel.md

@@ -7,8 +7,8 @@ A full-width vertical region that paints the current surface colour. Use panels
 - A panel always spans the full width of its container. To constrain the content inside, compose a `<Block>` `width="narrow"` (or `width="wide"`) within it.
 - Block margin is always zero so panels stack flush; control the vertical breathing room with the `padding` variant (`<Panel padding="large">`, `<Panel padding="none">`).
 - Inline padding ("indent") keeps content off the edges by default. Override it per-property with `--panel-indent`, or change it with the shared `indent` variant (`<Panel indent="large">`, `<Panel indent="none">`).
-- `color=` / `status=` move the tint anchor for the whole panel scope, so the surface, border, and text re-derive together and cascade into nested content.
-- The top and bottom borders are dropped on the first and last panel so the page doesn't gain stray edge lines.
+- `color=` / `status=` move the tint anchor for the whole panel scope, so the surface and text re-derive together and cascade into nested content.
+- Panels have no border by default. Set `--panel-stroke` (or `--panel-border`) to add top and bottom borders; the first and last panel drop them so the page doesn't gain stray edge lines.
 
 ## Usage
 
@@ -31,15 +31,15 @@ import { Panel, Block, Title, Paragraph } from "shelving/ui";
 
 ## Styling
 
-`Panel` paints from the [tint ladder](/ui/TINT_CLASS); apply `color=` / `status=` (on the panel or an ancestor scope) to recolour the whole scope at once — surface, border, and text re-derive together — or reach for a per-property hook for a single change.
+`Panel` paints from the [tint ladder](/ui/TINT_CLASS); apply `color=` / `status=` (on the panel or an ancestor scope) to recolour the whole scope at once — surface and text re-derive together — or reach for a per-property hook for a single change.
 
 | Variable | Styles | Default |
 |---|---|---|
 | `--panel-background` | Surface fill | `var(--tint-90)` |
 | `--panel-color` | Text colour | `var(--tint-00)` |
 | `--panel-border` | Top/bottom border shorthand | `var(--panel-stroke) solid var(--tint-80)` |
-| `--panel-stroke` | Border thickness | `var(--stroke-normal)` (2px) |
+| `--panel-stroke` | Border thickness — set it (e.g. `var(--stroke-normal)`) to show the border | `0` |
 | `--panel-padding` | Block padding (top + bottom) | `var(--space-section)` (2rem) |
 | `--panel-indent` | Inline padding (left + right) keeping content off the edges | `var(--space-normal)` (16px) |
 
-**Global tokens it reads:** the tint-ladder steps `--tint-00` / `--tint-80` / `--tint-90`, plus `--stroke-normal`, `--space-section`, and `--space-normal`. The shared `padding` variant overrides `--panel-padding`; the shared `indent` variant overrides `--panel-indent`.
+**Global tokens it reads:** the tint-ladder steps `--tint-00` / `--tint-80` / `--tint-90`, plus `--space-section`, and `--space-normal`. The shared `padding` variant overrides `--panel-padding`; the shared `indent` variant overrides `--panel-indent`.

package/ui/block/Panel.module.css

@@ -1,5 +1,4 @@
 @import url("../style/layers.css");
-@import url("../style/Stroke.module.css");
 @import url("../style/Tint.module.css");
 @import url("../style/Space.module.css");
 
@@ -18,8 +17,8 @@
 		position: relative;
 		padding-block: var(--panel-padding, var(--space-section));
 		padding-inline: var(--panel-indent, var(--space-normal));
-		border-top: var(--panel-border, var(--panel-stroke, var(--stroke-normal)) solid var(--tint-80));
-		border-bottom: var(--panel-border, var(--panel-stroke, var(--stroke-normal)) solid var(--tint-80));
+		border-top: var(--panel-border, var(--panel-stroke, 0) solid var(--tint-80));
+		border-bottom: var(--panel-border, var(--panel-stroke, 0) solid var(--tint-80));
 
 		/* Style */
 		background: var(--panel-background, var(--tint-90));

package/ui/dialog/Dialog.d.ts

@@ -2,18 +2,23 @@ import { type ReactElement } from "react";
 import type { Callback } from "../../util/function.js";
 import { type ButtonVariants } from "../button/Button.js";
 import type { ClassProps, OptionalChildProps } from "../util/props.js";
+import "../transition/FadeTransition.css";
 /**
  * Props for `<Dialog>` — optional `children` content and an `onClose` callback.
  *
  * @see https://shelving.cc/ui/DialogProps
  */
 export interface DialogProps extends OptionalChildProps {
+    /** Called when the user closes the dialog. It must unmount the `<Dialog>`, and it runs inside `startTransition()` so the dialog animates out. */
     onClose?: Callback;
 }
 /**
  * Modal `<dialog>` element that opens on mount and includes a close button.
  *
- * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, or the close button.
+ * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, the close button, or the Escape key.
+ * - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
+ * - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
+ * - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
  * - Wraps content in `<Suspense>` so lazy children can stream in.
  *
  * @kind component

package/ui/dialog/Dialog.js

@@ -1,13 +1,17 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { XMarkIcon } from "@heroicons/react/24/solid";
-import { memo, Suspense, useEffect, useRef } from "react";
+import { memo, Suspense, startTransition, useLayoutEffect, useRef, ViewTransition } from "react";
 import { getButtonClass } from "../button/Button.js";
 import { getClass, getModuleClass } from "../util/css.js";
+import "../transition/FadeTransition.css";
 import styles from "./Dialog.module.css";
 /**
  * Modal `<dialog>` element that opens on mount and includes a close button.
  *
- * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, or the close button.
+ * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, the close button, or the Escape key.
+ * - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
+ * - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
+ * - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
  * - Wraps content in `<Suspense>` so lazy children can stream in.
  *
  * @kind component
@@ -15,19 +19,33 @@ import styles from "./Dialog.module.css";
  */
 export const Dialog = memo(({ children, onClose, ...props }) => {
     const ref = useRef(null);
-    useEffect(() => {
+    // Open in a layout effect, not a passive effect. React runs layout effects inside the view transition's update, so the new snapshot shows the open dialog.
+    useLayoutEffect(() => {
         ref.current?.showModal();
     }, []);
-    return (_jsx(Suspense, { fallback: null, children: _jsxs("dialog", { ref: ref, className: getModuleClass(styles, "dialog"), onClick: _closeOnBackdropClick, onClose: onClose, ...props, children: [children, _jsx("div", { className: getModuleClass(styles, "close"), children: _jsx(DialogCloseButton, {}) })] }) }));
+    return (_jsx(Suspense, { fallback: null, children: _jsx(ViewTransition, { enter: "fade", exit: "fade", children: _jsxs("dialog", { ref: ref, className: getModuleClass(styles, "dialog"), onClick: _closeOnBackdropClick, onCancel: e => {
+                    // Keep the dialog open and let the parent unmount it in a transition. An uncancelable request closes natively and fires `onClose` from the `close` event.
+                    if (!onClose || !e.cancelable)
+                        return;
+                    e.preventDefault();
+                    startTransition(() => onClose());
+                }, onClose: onClose, ...props, children: [_jsx("div", { className: getModuleClass(styles, "content"), children: children }), _jsx("div", { className: getModuleClass(styles, "close"), children: _jsx(DialogCloseButton, {}) })] }) }) }));
 });
 /** When the user clicks anywhere on a `<dialog>` element (and the click isn't on a link etc), then close the dialog. */
 function _closeOnBackdropClick({ currentTarget, target }) {
     // Close the dialog when clicking on the dialog itself (but not its children).
     if (currentTarget === target)
-        currentTarget.close();
+        _requestClose(currentTarget);
     // Close the dialog when clicking on links or buttons in a `<nav>` element.
     if (target instanceof Element && target.closest("a:any-link, nav button:enabled"))
-        currentTarget.close();
+        _requestClose(currentTarget);
+}
+/** Ask a `<dialog>` to close. `requestClose()` fires a cancelable `cancel` event, so `<Dialog>` can run `onClose` in a transition. Older browsers close at once. */
+function _requestClose(dialog) {
+    if (typeof dialog.requestClose === "function")
+        dialog.requestClose();
+    else
+        dialog.close();
 }
 /**
  * Button that closes its wrapping `<dialog>`, showing an X icon by default.
@@ -41,5 +59,7 @@ export function DialogCloseButton({ children = _jsx(XMarkIcon, {}), plain = true
     return (_jsx("button", { type: "button", title: "Close", className: getClass(getButtonClass({ plain, ...variants }), className), onClick: _closeOnButtonClick, children: children }));
 }
 function _closeOnButtonClick({ currentTarget }) {
-    currentTarget.closest("dialog")?.close();
+    const dialog = currentTarget.closest("dialog");
+    if (dialog)
+        _requestClose(dialog);
 }

package/ui/dialog/Dialog.md

@@ -4,10 +4,16 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
 
 **Things to know:**
 
-- Closes on a backdrop click, on any link or `<nav>` button clicked inside it, or via the built-in `<DialogCloseButton>` (an X icon, top-right).
+- Closes on a backdrop click, the Escape key, any link or `<nav>` button clicked inside it, or the built-in `<DialogCloseButton>` (an X icon, top-right).
 - Children render inside a `<Suspense>` boundary, so lazy content can stream in.
-- `onClose` fires when the dialog closes — use it to clear the React state that mounts the dialog, or (when pushed via a store) to remove it from the list.
-- Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app. For a non-blocking persistent overlay, reach for `<Modal>` instead.
+- Children sit in one wrapper in normal block layout, so several children stack as they would on the page. The wrapper is `--dialog-width` wide (never wider than the screen) and centred on the screen. A centred `<Modal>` fills it. Content taller than the screen starts at the top, and the dialog scrolls.
+- While a dialog is open, the page behind it does not scroll. A scroll inside the dialog never passes on to the page.
+- `Dialog` only dims the page. Its text is white (`--tint-100`) so it reads on the dark overlay. Wrap the content in `<Modal>` to give it a panel with dark text on a light surface.
+- `onClose` fires when the user closes the dialog. It must unmount the `Dialog`: clear the React state that mounts it, or (when pushed via a store) remove it from the list. `Dialog` calls `onClose` inside `startTransition()`, and the dialog stays open until it unmounts.
+- The dialog animates with [view transitions](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API). The whole dialog fades in and out as one layer. A `<Modal>` pinned to an edge takes its own layer and slides.
+- A view transition only runs for a React transition update. `DialogsStore` and `onClose` do this for you. To animate a declarative `Dialog` as it opens, set the state that mounts it inside `startTransition()`.
+- A browser without view transitions shows and hides the dialog at once.
+- Pair with `DialogsStore`, `<DialogsContext>`, and `<Dialogs>` to open dialogs imperatively from anywhere in the app.
 
 ## Usage
 
@@ -16,19 +22,21 @@ A native `<dialog>` element opened in modal mode. It opens via `showModal()` whe
 Mount `<Dialog>` directly when its lifetime matches a React state variable.
 
 ```tsx
-import { Dialog, DialogCloseButton } from "shelving/ui";
+import { Dialog, Modal } from "shelving/ui";
 
 function ConfirmDelete({ onConfirm, onClose }: { onConfirm: () => void; onClose: () => void }) {
   return (
     <Dialog onClose={onClose}>
-      <p>Delete this item?</p>
-      <button type="button" onClick={onConfirm}>Delete</button>
-      <DialogCloseButton />
+      <Modal>
+        <p>Delete this item?</p>
+        <button type="button" onClick={onConfirm}>Delete</button>
+      </Modal>
     </Dialog>
   );
 }
 
-// In the parent:
+// In the parent. Open inside `startTransition()` so the dialog animates in.
+<button type="button" onClick={() => startTransition(() => setShowConfirm(true))}>Delete</button>
 {showConfirm && <ConfirmDelete onConfirm={handleDelete} onClose={() => setShowConfirm(false)} />}
 ```
 
@@ -37,28 +45,35 @@ function ConfirmDelete({ onConfirm, onClose }: { onConfirm: () => void; onClose:
 Set up the context once near the app root (see `<DialogsContext>` and `<Dialogs>`), then push a `<Dialog>` from anywhere with `requireDialogs()`.
 
 ```tsx
-import { requireDialogs } from "shelving/ui";
+import { Modal, requireDialogs } from "shelving/ui";
 
-function DeleteButton({ id }: { id: string }) {
+function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
   const dialogs = requireDialogs();
-  const open = () => dialogs.show(
-    <ConfirmDelete id={id} onConfirm={() => handleDelete(id)} />,
-  );
+  const open = () =>
+    dialogs.show(
+      <Modal>
+        <p>Delete this item?</p>
+        <button type="button" onClick={onConfirm}>Delete</button>
+      </Modal>,
+    );
   return <button type="button" onClick={open}>Delete</button>;
 }
 ```
 
-`dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element.
+`dialogs.show()` wraps the content in a `<Dialog>` for you, so you pass plain children rather than a `<Dialog>` element. It does not add a `<Modal>`; include one in the content if you want a panel.
 
 ## Styling
 
-`Dialog` paints the full-screen overlay; the inner panel is laid out by its children. Override these hooks at `:root` (or any ancestor scope) to retheme.
+`Dialog` paints the full-screen overlay and resets the browser's default `<dialog>` border, size limits, and `::backdrop`. The inner panel comes from its children, usually `<Modal>`. Override these hooks at `:root` (or any ancestor scope) to retheme.
 
 | Variable | Styles | Default |
 |---|---|---|
 | `--dialog-padding` | Padding around the centred content | `var(--space-normal)` (16px) |
-| `--dialog-color-overlay` | Backdrop fill behind the content | `var(--color-shadow)` |
-| `--dialog-transition` | Open / close transition (a fixed discrete `display` transition runs alongside it so the fade animates across the show / hide toggle) | `all var(--duration-fast)` (150ms) |
-| `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (8px) |
+| `--dialog-width` | Width of the centred content, and so of a centred `<Modal>` | `var(--width-narrow)` (36rem) |
+| `--dialog-background` | Overlay fill behind the content | `var(--shadow-color)` |
+| `--dialog-color` | Text colour directly on the overlay | `var(--tint-100)` (white) |
+| `--dialog-close-offset` | Inset of the close button from the top-right corner | `var(--space-small)` (12px) |
+
+The fade uses the `fade` class from `<FadeTransition>`, so `--fade-transition-duration` sets its length. It runs only as the dialog opens and closes; an open dialog stays still while other dialogs open and close.
 
-**Global tokens it reads** — move these to retheme broadly: `--space-normal`, `--space-small`, `--color-shadow`, and `--duration-fast`.
+**Global tokens it reads** — move these to retheme broadly: `--tint-100`, `--width-narrow`, `--space-normal`, `--space-small`, `--shadow-color`, and `--duration-fast` (through `<FadeTransition>`).

package/ui/dialog/Dialog.module.css

@@ -1,8 +1,9 @@
 @import url("../style/layers.css");
 @import url("../style/Color.module.css");
-@import url("../style/Duration.module.css");
 @import url("../style/Space.module.css");
 @import url("../style/Shadow.module.css");
+@import url("../style/Tint.module.css");
+@import url("../style/Width.module.css");
 
 @layer components {
 	.dialog {
@@ -12,29 +13,52 @@
 		inset: 0;
 		z-index: 1000;
 		margin: 0;
-		width: 100vw;
-		height: 100vh;
-		align-items: center;
-		justify-content: center;
+		width: auto;
+		height: auto;
+		max-width: none;
+		max-height: none;
+		overflow: auto;
+
+		/* A scroll that reaches the top or bottom of the dialog stops there, and does not pass on to the page. */
+		overscroll-behavior: contain;
 		padding: var(--dialog-padding, var(--space-normal));
+		border: none;
 
 		/* Style */
-		background: var(--dialog-color-overlay, var(--shadow-color));
-		opacity: 0;
-		transition:
-			var(--dialog-transition, all var(--duration-fast)),
-			display var(--duration-fast) allow-discrete;
+		color: var(--dialog-color, var(--tint-100));
+		background: var(--dialog-background, var(--shadow-color));
 
+		/* Flex only to centre `.content`, its one in-flow child. */
 		&[open] {
 			display: flex;
-			opacity: 1;
 		}
 
-		@starting-style {
-			opacity: 0;
+		/* `.dialog` paints the overlay itself, so the browser's own backdrop must not add a second shade. */
+		&::backdrop {
+			background: transparent;
 		}
 	}
 
+	/*
+	 * Lock the page while a dialog is open, so the page behind never scrolls, even when the dialog itself has nothing to scroll.
+	 * - No `scrollbar-gutter: stable` here: fixed elements stop at the root gutter, so the overlay would leave a bare strip at the side.
+	 */
+	:root:has(.dialog[open]) {
+		overflow: hidden;
+	}
+
+	/*
+	 * The children, in normal block layout, `--dialog-width` wide.
+	 * - `margin: auto` centres it on both axes. When it is taller than the screen, the margins drop to 0, so it starts at the top and the dialog scrolls. (`align-items: center` would push the top out of reach.)
+	 * - A pinned `<Modal>` and the close button are `position: fixed`, so this wrapper does not affect them.
+	 */
+	.content {
+		margin: auto;
+		width: var(--dialog-width, var(--width-narrow));
+		min-width: 0;
+		max-width: 100%;
+	}
+
 	.close {
 		position: fixed;
 		top: var(--dialog-close-offset, var(--space-small));

package/ui/dialog/Dialog.tsx

@@ -1,9 +1,10 @@
 import { XMarkIcon } from "@heroicons/react/24/solid";
-import { type MouseEvent, memo, type ReactElement, Suspense, useEffect, useRef } from "react";
+import { type MouseEvent, memo, type ReactElement, Suspense, startTransition, useLayoutEffect, useRef, ViewTransition } from "react";
 import type { Callback } from "../../util/function.js";
 import { type ButtonVariants, getButtonClass } from "../button/Button.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import type { ClassProps, OptionalChildProps } from "../util/props.js";
+import "../transition/FadeTransition.css";
 import styles from "./Dialog.module.css";
 
 /**
@@ -12,13 +13,17 @@ import styles from "./Dialog.module.css";
  * @see https://shelving.cc/ui/DialogProps
  */
 export interface DialogProps extends OptionalChildProps {
+	/** Called when the user closes the dialog. It must unmount the `<Dialog>`, and it runs inside `startTransition()` so the dialog animates out. */
 	onClose?: Callback;
 }
 
 /**
  * Modal `<dialog>` element that opens on mount and includes a close button.
  *
- * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, or the close button.
+ * - Opens via `showModal()` when mounted and closes on backdrop clicks, link/nav-button clicks, the close button, or the Escape key.
+ * - The whole dialog fades in and out in one view transition. A `<Modal>` pinned to an edge leaves that layer and slides in its own.
+ * - With `onClose`, a close request calls `onClose()` and the dialog stays open until it unmounts, so the view transition can capture it as it leaves.
+ * - Children sit in one wrapper in normal block layout, `--dialog-width` wide and centred on the screen. Content taller than the screen scrolls from its top.
  * - Wraps content in `<Suspense>` so lazy children can stream in.
  *
  * @kind component
@@ -27,19 +32,35 @@ export interface DialogProps extends OptionalChildProps {
 export const Dialog = memo(({ children, onClose, ...props }: DialogProps) => {
 	const ref = useRef<HTMLDialogElement>(null);
 
-	useEffect(() => {
+	// Open in a layout effect, not a passive effect. React runs layout effects inside the view transition's update, so the new snapshot shows the open dialog.
+	useLayoutEffect(() => {
 		ref.current?.showModal();
 	}, []);
 
 	return (
 		<Suspense fallback={null}>
-			{/** biome-ignore lint/a11y/useKeyWithClickEvents: Dialogs also show a close button. */}
-			<dialog ref={ref} className={getModuleClass(styles, "dialog")} onClick={_closeOnBackdropClick} onClose={onClose} {...props}>
-				{children}
-				<div className={getModuleClass(styles, "close")}>
-					<DialogCloseButton />
-				</div>
-			</dialog>
+			{/* The transition must wrap the `<dialog>`: React only animates a `<ViewTransition>` that comes before any DOM element in the inserted or deleted tree. Fade only on enter and exit, so an open dialog stays still while another dialog opens or closes. */}
+			<ViewTransition enter="fade" exit="fade">
+				{/** biome-ignore lint/a11y/useKeyWithClickEvents: Dialogs also show a close button. */}
+				<dialog
+					ref={ref}
+					className={getModuleClass(styles, "dialog")}
+					onClick={_closeOnBackdropClick}
+					onCancel={e => {
+						// Keep the dialog open and let the parent unmount it in a transition. An uncancelable request closes natively and fires `onClose` from the `close` event.
+						if (!onClose || !e.cancelable) return;
+						e.preventDefault();
+						startTransition(() => onClose());
+					}}
+					onClose={onClose}
+					{...props}
+				>
+					<div className={getModuleClass(styles, "content")}>{children}</div>
+					<div className={getModuleClass(styles, "close")}>
+						<DialogCloseButton />
+					</div>
+				</dialog>
+			</ViewTransition>
 		</Suspense>
 	);
 });
@@ -47,10 +68,16 @@ export const Dialog = memo(({ children, onClose, ...props }: DialogProps) => {
 /** When the user clicks anywhere on a `<dialog>` element (and the click isn't on a link etc), then close the dialog. */
 function _closeOnBackdropClick({ currentTarget, target }: MouseEvent<HTMLDialogElement>): void {
 	// Close the dialog when clicking on the dialog itself (but not its children).
-	if (currentTarget === target) currentTarget.close();
+	if (currentTarget === target) _requestClose(currentTarget);
 
 	// Close the dialog when clicking on links or buttons in a `<nav>` element.
-	if (target instanceof Element && target.closest("a:any-link, nav button:enabled")) currentTarget.close();
+	if (target instanceof Element && target.closest("a:any-link, nav button:enabled")) _requestClose(currentTarget);
+}
+
+/** Ask a `<dialog>` to close. `requestClose()` fires a cancelable `cancel` event, so `<Dialog>` can run `onClose` in a transition. Older browsers close at once. */
+function _requestClose(dialog: HTMLDialogElement): void {
+	if (typeof dialog.requestClose === "function") dialog.requestClose();
+	else dialog.close();
 }
 
 /**
@@ -87,5 +114,6 @@ export function DialogCloseButton({
 }
 
 function _closeOnButtonClick({ currentTarget }: MouseEvent<HTMLButtonElement>): void {
-	currentTarget.closest("dialog")?.close();
+	const dialog = currentTarget.closest("dialog");
+	if (dialog) _requestClose(dialog);
 }

package/ui/dialog/Dialogs.d.ts

@@ -4,7 +4,8 @@ import type { ChildProps } from "../util/props.js";
 /**
  * Store holding the live list of open `<Dialog>` elements.
  *
- * - `show()` opens a new dialog; closed dialogs are removed after an animation delay.
+ * - `show()` opens a new dialog. A dialog is removed from the list as soon as it closes.
+ * - `<Dialogs>` renders the list inside a transition, so dialogs animate in and out with view transitions.
  *
  * @see https://shelving.cc/ui/DialogsStore
  */
@@ -59,5 +60,5 @@ export declare function DialogsContext({ children }: DialogsContextProps): React
  * @kind component
  * @see https://shelving.cc/ui/Dialogs
  */
-export declare function Dialogs(): ReactNode | null;
+export declare function Dialogs(): ReactNode;
 export {};

package/ui/dialog/Dialogs.js

@@ -1,16 +1,15 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, use } from "react";
 import { useInstance } from "../../react/useInstance.js";
-import { useStore } from "../../react/useStore.js";
 import { ArrayStore } from "../../store/ArrayStore.js";
 import { getRandomKey } from "../../util/random.js";
+import { useTransitionValue } from "../transition/useTransitionValue.js";
 import { Dialog } from "./Dialog.js";
-/** How long before a hidden dialogs are removed from the DOM (allow time for animates to complete). */
-const REMOVE_DELAY = 500;
 /**
  * Store holding the live list of open `<Dialog>` elements.
  *
- * - `show()` opens a new dialog; closed dialogs are removed after an animation delay.
+ * - `show()` opens a new dialog. A dialog is removed from the list as soon as it closes.
+ * - `<Dialogs>` renders the list inside a transition, so dialogs animate in and out with view transitions.
  *
  * @see https://shelving.cc/ui/DialogsStore
  */
@@ -25,10 +24,8 @@ export class DialogsStore extends ArrayStore {
         const dialog = (_jsx(Dialog
         // Add a `key=""` so dialogs can be rendered directly and added/removed in any order.
         , { 
-            // When the `<dialog>` is closed, wait for the animation to finish then remove the dialog from the list.
-            onClose: () => {
-                setTimeout(() => this.delete(dialog), REMOVE_DELAY);
-            }, children: children }, getRandomKey()));
+            // When the `<dialog>` closes, remove it from the list. The view transition animates it out.
+            onClose: () => this.delete(dialog), children: children }, getRandomKey()));
         this.add(dialog);
     }
     /**
@@ -68,6 +65,5 @@ export function DialogsContext({ children }) {
  * @see https://shelving.cc/ui/Dialogs
  */
 export function Dialogs() {
-    const dialogs = useStore(requireDialogs());
-    return dialogs ? dialogs.value : null;
+    return useTransitionValue(requireDialogs());
 }