@botiverse/raft-ui 0.83.0 → 0.85.0

package/dist/components/lightbox/lightbox.d.mts

@@ -1,20 +1,68 @@
 import { StyledProps } from "../../lib/styled-props.mjs";
 import { ButtonProps } from "../button/button.mjs";
+import { ScrollAreaProps } from "../scroll-area/types.mjs";
 import { Dialog } from "@base-ui/react/dialog";
 import { ReactNode } from "react";
 import { useRender } from "@base-ui/react/use-render";
 //#region src/components/lightbox/lightbox.d.ts
-export type LightboxProps<Payload = unknown> = Omit<Dialog.Root.Props<Payload>, "actionsRef" | "children" | "handle"> & {
+export type LightboxProps<Payload = unknown> = Omit<Dialog.Root.Props<Payload>, "actionsRef" | "children" | "handle" | "modal"> & {
   children?: ReactNode;
+  /**
+   * Whether Cmd+W (Ctrl+W) closes the lightbox instead of the browser tab.
+   * @default true
+   */
   closeOnModW?: boolean;
+  /**
+   * How the lightbox holds the page while it is open.
+   * - `true`: focus is trapped in it and the page's scroll is locked. For an
+   *   image or a preview that fits the window.
+   * - `"trap-focus"`: document mode, for a file read top to bottom (a PDF, a
+   *   document, a diagram). Focus is still trapped, but the page's scroll is
+   *   not locked: the document's own body scrolls, and Base UI's lock would
+   *   only rewrite the page's `<html>` and `<body>` styles under it, again on
+   *   every resize. The scrim still covers the page.
+   * - `false`: nothing is held; focus can leave the lightbox.
+   *
+   * In every mode the content is neither `inert` nor hidden, so the browser's
+   * find in page reaches it.
+   * @default true
+   */
+  modal?: boolean | "trap-focus";
 };
+/**
+ * A full-screen viewer over the scrim for images and attachment previews,
+ * with previous and next, thumbnails and one button to close. Pass
+ * `modal="trap-focus"` for a file read top to bottom (document mode).
+ */
 export declare function Lightbox<Payload = unknown>({ closeOnModW, defaultOpen, modal, onOpenChange, open, children, ...props }: LightboxProps<Payload>): import("react").JSX.Element;
 export type LightboxTriggerProps = Dialog.Trigger.Props;
 export declare function LightboxTrigger(props: LightboxTriggerProps): import("react").JSX.Element;
-export type LightboxPortalProps = Dialog.Portal.Props;
-export declare function LightboxPortal(props: LightboxPortalProps): import("react").JSX.Element;
+export type LightboxPortalProps = StyledProps<Dialog.Portal.Props>;
+/**
+ * The lightbox's own stacking context, at `z-lightbox` (70) above the page's dialogs
+ * and popups: the scrim, the content, and every Base UI popup opened from
+ * inside, which Base UI portals into this element by default, in DOM order.
+ * A popup's own `z-popup` then counts inside the lightbox, so it is drawn above
+ * the content instead of under the scrim, and a press on it is a press inside
+ * the lightbox.
+ */
+export declare function LightboxPortal({ className, ...props }: LightboxPortalProps): import("react").JSX.Element;
 export type LightboxContentProps = StyledProps<Dialog.Popup.Props>;
-export declare function LightboxContent({ className, initialFocus, finalFocus, ...props }: LightboxContentProps): import("react").JSX.Element;
+/**
+ * The full-screen layer, with the scrim behind it. Popups opened inside it
+ * are drawn above it (`LightboxPortal`). `initialFocus` and `finalFocus` are
+ * `false` by default, so focus doesn't move when it opens or closes, except
+ * in document mode (`modal="trap-focus"`): focus moves into the lightbox when
+ * it opens and back to `LightboxTrigger` when it closes. It lands on
+ * `LightboxBody`, so the keys that scroll scroll the document at once; on the
+ * first control when there is no body; and on the lightbox itself after a
+ * tap, so a phone shows no ring and opens no keyboard. A key that would
+ * scroll the page under the scrim scrolls the body instead.
+ *
+ * A lightbox opened from state passes `finalFocus={openerRef}` so focus goes
+ * back to what opened it.
+ */
+export declare function LightboxContent({ className, initialFocus, finalFocus, onKeyDown, ref, ...props }: LightboxContentProps): import("react").JSX.Element;
 export type LightboxHeaderProps = useRender.ComponentProps<"div">;
 export declare function LightboxHeader({ render, className, ...props }: LightboxHeaderProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export type LightboxToolbarProps = useRender.ComponentProps<"div">;
@@ -27,6 +75,24 @@ export type LightboxTitleProps = useRender.ComponentProps<"div">;
 export declare function LightboxTitle({ render, className, ...props }: LightboxTitleProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export type LightboxActionsProps = useRender.ComponentProps<"div">;
 export declare function LightboxActions({ render, className, ...props }: LightboxActionsProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export type LightboxBodyProps = Omit<ScrollAreaProps, "overscroll">;
+/**
+ * The scrolling body of a document-mode lightbox (`modal="trap-focus"`),
+ * under `LightboxToolbar`: a ScrollArea that fills the rest of the content
+ * (`min-h-0 flex-1`) on `layer-canvas`, the toolbar's surface. Pass a
+ * `className` for another surface (`bg-layer-sidebar`). It takes the pointer
+ * back from `LightboxContent`, which lets it through to the scrim, and never
+ * passes a scroll on to the page under the scrim (`overscroll-contain`, also
+ * while it has nothing to scroll; `overscroll-none` in `className` also stops
+ * the bounce). Every other ScrollArea prop, `render` included, is the area's.
+ *
+ * It is a tab stop even when it has nothing to scroll (`tabIndex={0}`), as it
+ * takes focus when the lightbox opens, and draws its focus ring inside its
+ * edge, which is the window's. Its content keeps clear of a phone's safe
+ * areas at the bottom and the sides, around the caller's own content box
+ * (`contentClassName`), so the scrollbar stays at the edge.
+ */
+export declare function LightboxBody({ children, className, contentClassName, contentStyle, ...props }: LightboxBodyProps): import("react").JSX.Element;
 export type LightboxStageProps = useRender.ComponentProps<"div">;
 export declare function LightboxStage({ render, className, ...props }: LightboxStageProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export type LightboxMediaProps = useRender.ComponentProps<"div">;

package/dist/components/lightbox/lightbox.mjs

@@ -2,96 +2,115 @@ import { cn } from "../../cn.mjs";
 import { headEdgePull } from "../../lib/head-edges.mjs";
 import { tv } from "../../lib/tv.mjs";
 import { useThemeScopeProps } from "../../lib/theme/theme-scope.mjs";
+import { OverlayLayerProvider, useParentOverlayKind } from "../../lib/overlay-depth.mjs";
 import { Button } from "../button/button.mjs";
+import { useMergedRef } from "../../lib/use-merged-ref.mjs";
+import { ScrollArea } from "../scroll-area/scroll-area.mjs";
 import { Dialog } from "@base-ui/react/dialog";
-import { useCallback, useRef, useState } from "react";
+import { createContext, useCallback, useContext, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { mergeProps } from "@base-ui/react/merge-props";
 import { useRender } from "@base-ui/react/use-render";
 import { useHotkey } from "@tanstack/react-hotkeys";
 //#region src/components/lightbox/lightbox.tsx
-const lightbox = tv({ slots: {
-	backdrop: ["fixed inset-0 z-70 bg-layer-backdrop data-closed:hidden"],
-	content: [
-		"pointer-events-none fixed inset-0 z-71 flex flex-col data-closed:hidden",
-		"*:data-lightbox-close:pointer-events-auto *:data-lightbox-close:absolute *:data-lightbox-close:z-20",
-		"*:data-lightbox-close:top-[calc(16px+env(safe-area-inset-top,0px))] *:data-lightbox-close:right-[calc(16px+env(safe-area-inset-right,0px))]"
-	],
-	header: [
-		"pointer-events-auto shrink-0",
-		"flex items-center gap-3 pb-3",
-		"pt-[calc(env(safe-area-inset-top,0px)+--spacing(3))]",
-		"pl-[calc(env(safe-area-inset-left,0px)+--spacing(4))]",
-		"pr-[calc(env(safe-area-inset-right,0px)+--spacing(4))]",
-		"bg-transparent shadow-none",
-		headEdgePull
-	],
-	toolbar: [
-		"pointer-events-auto shrink-0 flex items-center gap-3",
-		"h-[calc(var(--header-height)+env(safe-area-inset-top,0px))] pt-[env(safe-area-inset-top,0px)]",
-		"pl-[calc(16px+env(safe-area-inset-left,0px))] pr-[calc(16px+env(safe-area-inset-right,0px))]",
-		"**:data-lightbox-close:static **:data-lightbox-close:inset-auto",
-		"**:data-lightbox-close:top-auto **:data-lightbox-close:right-auto",
-		"border-b border-line-seam bg-layer-canvas shadow-none",
-		headEdgePull
-	],
-	headerMeta: ["flex min-w-0 flex-1 items-center gap-1.5"],
-	headerLabel: [
-		"inline-flex shrink-0 items-center px-1.5",
-		"h-[22px] rounded-chip bg-fill-muted py-0",
-		"font-sans text-caption font-semibold normal-case tracking-normal text-foreground-muted"
-	],
-	title: ["min-w-0 flex-1 truncate", "py-0 font-sans text-headline font-bold text-foreground"],
-	actions: [
-		"flex shrink-0 items-center",
-		"gap-1",
-		"[&>[data-icon-inset]:nth-last-child(1_of_:not([data-base-ui-focus-guard],[aria-owns]))]:-mr-icon-inset"
-	],
-	stage: ["pointer-events-none relative flex min-h-0 flex-1 items-center justify-center overflow-hidden"],
-	media: ["pointer-events-auto max-h-[80vh] max-w-[86vw] border-0 bg-transparent shadow-none"],
-	navigationButton: [
-		"pointer-events-auto absolute z-10 inline-flex items-center justify-center",
-		"transition-[background-color,color,opacity,box-shadow,transform] duration-150",
-		"outline-[1px] outline-offset-2 outline-transparent",
-		"data-[disabled=true]:cursor-default",
-		"[&_svg]:pointer-events-none [&_svg]:shrink-0",
-		"size-11 rounded-control border-[1.5px] border-line-strong bg-layer-card text-foreground shadow-none",
-		"hover:overlay-medium active:overlay-medium",
-		"focus-visible:outline-transparent focus-visible:shadow-focus",
-		"[&_svg]:size-5.5"
-	],
-	infoDock: ["pointer-events-none absolute right-6 bottom-20 left-6 z-10 flex justify-center"],
-	infoBar: [
-		"pointer-events-auto flex items-center",
-		"w-[clamp(144px,20vw,224px)] max-w-[calc(100vw-48px)] min-w-36",
-		"gap-2 rounded-container py-1 pr-1 pl-2.5",
-		"bg-layer-popover text-foreground shadow-float ring-1 ring-line-seam"
-	],
-	infoTitle: ["min-w-0 flex-1 truncate", "font-sans text-footnote font-semibold text-foreground"],
-	infoActions: [
-		"flex shrink-0 items-center",
-		"gap-1",
-		"*:data-[slot=button]:h-7 *:data-[slot=button]:w-auto *:data-[slot=button]:min-w-7",
-		"*:data-[slot=button]:rounded-chip",
-		"*:data-[slot=button]:after:inset-x-[-3px] *:data-[slot=button]:first:after:left-[-9.5px] *:data-[slot=button]:last:after:right-[-9.5px]",
-		"pointer-coarse:*:data-[slot=button]:after:inset-y-[-9.5px]"
-	],
-	thumbnailStrip: ["pointer-events-none absolute right-0 bottom-4 left-0 z-10", "flex items-center justify-center gap-1.5"],
-	thumbnail: [
-		"group/lightbox-thumb pointer-events-auto relative size-12 overflow-hidden",
-		"transition-[border-color,opacity,box-shadow] duration-150",
-		"[&_img]:pointer-events-none [&_img]:size-full [&_img]:object-cover",
-		"rounded-control border-[1.5px] opacity-100 shadow-none",
-		"border-sticker-paper/40 hover:border-sticker-paper/80",
-		"data-active:border-sticker-paper"
-	],
-	thumbnailOverlay: [
-		"pointer-events-none absolute inset-0 block transition-colors duration-150",
-		"bg-layer-backdrop-nested group-hover/lightbox-thumb:bg-layer-backdrop-nested/70",
-		"group-data-active/lightbox-thumb:bg-transparent"
-	],
-	close: ["pointer-events-auto"]
-} });
+const lightbox = tv({
+	slots: {
+		portal: ["relative isolate z-lightbox"],
+		backdrop: ["fixed inset-0 bg-layer-backdrop data-closed:hidden"],
+		content: [
+			"pointer-events-none fixed inset-0 flex flex-col data-closed:hidden",
+			"*:data-lightbox-close:pointer-events-auto *:data-lightbox-close:absolute *:data-lightbox-close:z-raised",
+			"*:data-lightbox-close:top-[calc(16px+env(safe-area-inset-top,0px))] *:data-lightbox-close:right-[calc(16px+env(safe-area-inset-right,0px))]"
+		],
+		header: [
+			"pointer-events-auto shrink-0",
+			"flex items-center gap-3 pb-3",
+			"pt-[calc(env(safe-area-inset-top,0px)+--spacing(3))]",
+			"pl-[calc(env(safe-area-inset-left,0px)+--spacing(4))]",
+			"pr-[calc(env(safe-area-inset-right,0px)+--spacing(4))]",
+			"bg-transparent shadow-none",
+			headEdgePull
+		],
+		toolbar: [
+			"pointer-events-auto shrink-0 flex items-center gap-3",
+			"h-[calc(var(--header-height)+env(safe-area-inset-top,0px))] pt-[env(safe-area-inset-top,0px)]",
+			"pl-[calc(16px+env(safe-area-inset-left,0px))] pr-[calc(16px+env(safe-area-inset-right,0px))]",
+			"**:data-lightbox-close:static **:data-lightbox-close:inset-auto",
+			"**:data-lightbox-close:top-auto **:data-lightbox-close:right-auto",
+			"border-b border-line-seam bg-layer-canvas shadow-none",
+			headEdgePull
+		],
+		headerMeta: ["flex min-w-0 flex-1 items-center gap-1.5"],
+		headerLabel: [
+			"inline-flex shrink-0 items-center px-1.5",
+			"h-[22px] rounded-chip bg-fill-muted py-0",
+			"font-sans text-caption font-semibold normal-case tracking-normal text-foreground-muted"
+		],
+		title: ["min-w-0 flex-1 truncate", "py-0 font-sans text-headline font-bold text-foreground"],
+		actions: [
+			"flex shrink-0 items-center",
+			"gap-1",
+			"[&>[data-icon-inset]:nth-last-child(1_of_:not([data-base-ui-focus-guard],[aria-owns]))]:-mr-icon-inset"
+		],
+		body: [
+			"pointer-events-auto min-h-0 flex-1 overscroll-contain",
+			"bg-layer-canvas",
+			"focus-visible:shadow-none focus-visible:keyboard:outline-2 focus-visible:keyboard:-outline-offset-2 focus-visible:keyboard:outline-foreground"
+		],
+		bodyContent: ["pr-[env(safe-area-inset-right,0px)] pb-[env(safe-area-inset-bottom,0px)] pl-[env(safe-area-inset-left,0px)]"],
+		stage: ["pointer-events-none relative flex min-h-0 flex-1 items-center justify-center overflow-hidden"],
+		media: ["pointer-events-auto max-h-[80vh] max-w-[86vw] border-0 bg-transparent shadow-none"],
+		navigationButton: [
+			"pointer-events-auto absolute z-raised inline-flex items-center justify-center",
+			"transition-[background-color,color,opacity,box-shadow,transform] duration-150",
+			"outline-[1px] outline-offset-2 outline-transparent",
+			"data-[disabled=true]:cursor-default",
+			"[&_svg]:pointer-events-none [&_svg]:shrink-0",
+			"size-11 rounded-control border-[1.5px] border-line-strong bg-layer-card text-foreground shadow-none",
+			"hover:overlay-medium active:overlay-medium",
+			"focus-visible:outline-transparent focus-visible:shadow-focus",
+			"[&_svg]:size-5.5"
+		],
+		infoDock: ["pointer-events-none absolute right-6 bottom-20 left-6 z-raised flex justify-center"],
+		infoBar: [
+			"pointer-events-auto flex items-center",
+			"w-[clamp(144px,20vw,224px)] max-w-[calc(100vw-48px)] min-w-36",
+			"gap-2 rounded-container py-1 pr-1 pl-2.5",
+			"bg-layer-popover text-foreground shadow-float ring-1 ring-line-seam"
+		],
+		infoTitle: ["min-w-0 flex-1 truncate", "font-sans text-footnote font-semibold text-foreground"],
+		infoActions: [
+			"flex shrink-0 items-center",
+			"gap-1",
+			"*:data-[slot=button]:h-7 *:data-[slot=button]:w-auto *:data-[slot=button]:min-w-7",
+			"*:data-[slot=button]:rounded-chip",
+			"*:data-[slot=button]:after:inset-x-[-3px] *:data-[slot=button]:first:after:left-[-9.5px] *:data-[slot=button]:last:after:right-[-9.5px]",
+			"pointer-coarse:*:data-[slot=button]:after:inset-y-[-9.5px]"
+		],
+		thumbnailStrip: ["pointer-events-none absolute right-0 bottom-4 left-0 z-raised", "flex items-center justify-center gap-1.5"],
+		thumbnail: [
+			"group/lightbox-thumb pointer-events-auto relative size-12 overflow-hidden",
+			"transition-[border-color,opacity,box-shadow] duration-150",
+			"[&_img]:pointer-events-none [&_img]:size-full [&_img]:object-cover",
+			"rounded-control border-[1.5px] opacity-100 shadow-none",
+			"border-sticker-paper/40 hover:border-sticker-paper/80",
+			"data-active:border-sticker-paper"
+		],
+		thumbnailOverlay: [
+			"pointer-events-none absolute inset-0 block transition-colors duration-150",
+			"bg-layer-backdrop-nested group-hover/lightbox-thumb:bg-layer-backdrop-nested/70",
+			"group-data-active/lightbox-thumb:bg-transparent"
+		],
+		close: ["pointer-events-auto"]
+	},
+	variants: { nested: { true: { backdrop: ["bg-layer-backdrop-nested"] } } }
+});
+const LightboxModalContext = createContext(true);
+/**
+* A full-screen viewer over the scrim for images and attachment previews,
+* with previous and next, thumbnails and one button to close. Pass
+* `modal="trap-focus"` for a file read top to bottom (document mode).
+*/
 function Lightbox({ closeOnModW = true, defaultOpen = false, modal = true, onOpenChange, open, children, ...props }) {
 	const dialogRef = useRef(null);
 	const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
@@ -108,7 +127,14 @@ function Lightbox({ closeOnModW = true, defaultOpen = false, modal = true, onOpe
 		onOpenChange: handleOpenChange,
 		open,
 		...props,
-		children: [modWClose, children]
+		children: [modWClose, /* @__PURE__ */ jsx(OverlayLayerProvider, {
+			kind: "dialog",
+			modal: true,
+			children: /* @__PURE__ */ jsx(LightboxModalContext.Provider, {
+				value: modal,
+				children
+			})
+		})]
 	});
 }
 function LightboxModWClose({ dialogRef }) {
@@ -128,22 +154,158 @@ function LightboxTrigger(props) {
 		...props
 	});
 }
-function LightboxPortal(props) {
+/**
+* The lightbox's own stacking context, at `z-lightbox` (70) above the page's dialogs
+* and popups: the scrim, the content, and every Base UI popup opened from
+* inside, which Base UI portals into this element by default, in DOM order.
+* A popup's own `z-popup` then counts inside the lightbox, so it is drawn above
+* the content instead of under the scrim, and a press on it is a press inside
+* the lightbox.
+*/
+function LightboxPortal({ className, ...props }) {
+	const { portal } = lightbox();
 	return /* @__PURE__ */ jsx(Dialog.Portal, {
 		"data-slot": "lightbox-portal",
-		...useThemeScopeProps(props)
+		...useThemeScopeProps({
+			...props,
+			className: portal({ className })
+		})
 	});
 }
-function LightboxContent({ className, initialFocus = false, finalFocus = false, ...props }) {
-	const { backdrop, content } = lightbox();
+const BODY_SELECTOR = "[data-slot=\"lightbox-body\"]";
+/** The browser's own steps: an arrow key's line, and the share of the view a page keeps. */
+const LINE_STEP = 40;
+const PAGE_FRACTION = .875;
+/**
+* Where a key the browser scrolls with takes the body, or `null` for a key
+* that doesn't scroll (or is the browser's own shortcut, such as Ctrl+Page Down).
+*/
+function scrollKeyTarget(event, body) {
+	const { altKey, ctrlKey, key, metaKey, shiftKey } = event;
+	if (altKey) return null;
+	const page = body.clientHeight * PAGE_FRACTION;
+	const { scrollLeft: left, scrollTop: top } = body;
+	const start = {
+		left,
+		top: 0
+	};
+	const end = {
+		left,
+		top: body.scrollHeight
+	};
+	if (ctrlKey || metaKey) {
+		if (key === "ArrowUp" || key === "Home") return start;
+		if (key === "ArrowDown" || key === "End") return end;
+		return null;
+	}
+	switch (key) {
+		case "ArrowUp": return {
+			left,
+			top: top - LINE_STEP
+		};
+		case "ArrowDown": return {
+			left,
+			top: top + LINE_STEP
+		};
+		case "ArrowLeft": return {
+			left: left - LINE_STEP,
+			top
+		};
+		case "ArrowRight": return {
+			left: left + LINE_STEP,
+			top
+		};
+		case "PageUp": return {
+			left,
+			top: top - page
+		};
+		case "PageDown": return {
+			left,
+			top: top + page
+		};
+		case " ": return {
+			left,
+			top: shiftKey ? top - page : top + page
+		};
+		case "Home": return start;
+		case "End": return end;
+		default: return null;
+	}
+}
+/** Whether `element` takes the key itself: a text field edits with it, a button presses with Space. */
+function takesKey(element, key) {
+	if (element instanceof HTMLElement && element.isContentEditable) return true;
+	if (element.closest("input, textarea, select")) return true;
+	return key === " " && element.closest("button, summary, [role=\"button\"]") !== null;
+}
+/** Whether `element`, or a parent of it inside `popup`, scrolls: the browser scrolls that one. */
+function inScroller(element, popup) {
+	for (let node = element; node && node !== popup; node = node.parentElement) {
+		const { overflowX, overflowY } = getComputedStyle(node);
+		if (/auto|scroll/.test(overflowY) && node.scrollHeight > node.clientHeight) return true;
+		if (/auto|scroll/.test(overflowX) && node.scrollWidth > node.clientWidth) return true;
+	}
+	return false;
+}
+/**
+* Document mode doesn't lock the page, so a key that would scroll it from
+* outside the body (focus on a toolbar button, or on the content after a tap)
+* scrolls `LightboxBody` instead, and never the page under the scrim. A key
+* from inside a scroller is that scroller's; a key a control uses, or one a
+* handler already took (a menu's arrows), is left alone. A popup opened
+* inside is portaled beside the content, so its keys never come here.
+*/
+function routeScrollKey(event) {
+	const popup = event.currentTarget;
+	const target = event.target;
+	if (event.defaultPrevented || !popup.contains(target)) return;
+	if (takesKey(target, event.key) || inScroller(target, popup)) return;
+	const body = popup.querySelector(BODY_SELECTOR);
+	const to = scrollKeyTarget(event, body ?? popup);
+	if (to === null) return;
+	event.preventDefault();
+	body?.scrollTo(to);
+}
+/**
+* The full-screen layer, with the scrim behind it. Popups opened inside it
+* are drawn above it (`LightboxPortal`). `initialFocus` and `finalFocus` are
+* `false` by default, so focus doesn't move when it opens or closes, except
+* in document mode (`modal="trap-focus"`): focus moves into the lightbox when
+* it opens and back to `LightboxTrigger` when it closes. It lands on
+* `LightboxBody`, so the keys that scroll scroll the document at once; on the
+* first control when there is no body; and on the lightbox itself after a
+* tap, so a phone shows no ring and opens no keyboard. A key that would
+* scroll the page under the scrim scrolls the body instead.
+*
+* A lightbox opened from state passes `finalFocus={openerRef}` so focus goes
+* back to what opened it.
+*/
+function LightboxContent({ className, initialFocus, finalFocus, onKeyDown, ref, ...props }) {
+	const documentMode = useContext(LightboxModalContext) === "trap-focus";
+	const nested = useParentOverlayKind() != null;
+	const { backdrop, content } = lightbox({ nested });
+	const [setRef, getRef] = useMergedRef(ref);
+	const documentInitialFocus = useCallback((openType) => {
+		const popup = getRef();
+		if (openType === "touch") return popup;
+		return popup?.querySelector(BODY_SELECTOR) ?? true;
+	}, [getRef]);
+	const handleKeyDown = useCallback((event) => {
+		onKeyDown?.(event);
+		if (documentMode) routeScrollKey(event);
+	}, [documentMode, onKeyDown]);
 	return /* @__PURE__ */ jsxs(LightboxPortal, { children: [/* @__PURE__ */ jsx(Dialog.Backdrop, {
 		"data-slot": "lightbox-backdrop",
+		"data-nested": nested ? "" : void 0,
+		forceRender: true,
 		className: backdrop()
 	}), /* @__PURE__ */ jsx(Dialog.Popup, {
 		"data-slot": "lightbox-content",
-		initialFocus,
-		finalFocus,
+		ref: setRef,
+		initialFocus: initialFocus ?? (documentMode ? documentInitialFocus : false),
+		finalFocus: finalFocus ?? documentMode,
 		className: content({ className }),
+		onKeyDown: handleKeyDown,
 		...props
 	})] });
 }
@@ -207,6 +369,38 @@ function LightboxActions({ render, className, ...props }) {
 		state: { slot: "lightbox-actions" }
 	});
 }
+/**
+* The scrolling body of a document-mode lightbox (`modal="trap-focus"`),
+* under `LightboxToolbar`: a ScrollArea that fills the rest of the content
+* (`min-h-0 flex-1`) on `layer-canvas`, the toolbar's surface. Pass a
+* `className` for another surface (`bg-layer-sidebar`). It takes the pointer
+* back from `LightboxContent`, which lets it through to the scrim, and never
+* passes a scroll on to the page under the scrim (`overscroll-contain`, also
+* while it has nothing to scroll; `overscroll-none` in `className` also stops
+* the bounce). Every other ScrollArea prop, `render` included, is the area's.
+*
+* It is a tab stop even when it has nothing to scroll (`tabIndex={0}`), as it
+* takes focus when the lightbox opens, and draws its focus ring inside its
+* edge, which is the window's. Its content keeps clear of a phone's safe
+* areas at the bottom and the sides, around the caller's own content box
+* (`contentClassName`), so the scrollbar stays at the edge.
+*/
+function LightboxBody({ children, className, contentClassName, contentStyle, ...props }) {
+	const { body, bodyContent } = lightbox();
+	return /* @__PURE__ */ jsx(ScrollArea, {
+		"data-slot": "lightbox-body",
+		tabIndex: 0,
+		...props,
+		className: body({ className }),
+		contentClassName: bodyContent(),
+		children: contentClassName !== void 0 || contentStyle !== void 0 ? /* @__PURE__ */ jsx("div", {
+			"data-slot": "lightbox-body-content",
+			className: contentClassName,
+			style: contentStyle,
+			children
+		}) : children
+	});
+}
 function LightboxStage({ render, className, ...props }) {
 	const { stage } = lightbox();
 	const defaultProps = { className: stage({ className }) };
@@ -333,4 +527,4 @@ function LightboxClose({ className, render, ...props }) {
 	});
 }
 //#endregion
-export { Lightbox, LightboxActions, LightboxClose, LightboxContent, LightboxHeader, LightboxHeaderLabel, LightboxHeaderMeta, LightboxInfoActions, LightboxInfoBar, LightboxInfoDock, LightboxInfoTitle, LightboxMedia, LightboxNavigationButton, LightboxPortal, LightboxStage, LightboxThumbnail, LightboxThumbnailStrip, LightboxTitle, LightboxToolbar, LightboxTrigger };
+export { Lightbox, LightboxActions, LightboxBody, LightboxClose, LightboxContent, LightboxHeader, LightboxHeaderLabel, LightboxHeaderMeta, LightboxInfoActions, LightboxInfoBar, LightboxInfoDock, LightboxInfoTitle, LightboxMedia, LightboxNavigationButton, LightboxPortal, LightboxStage, LightboxThumbnail, LightboxThumbnailStrip, LightboxTitle, LightboxToolbar, LightboxTrigger };

package/dist/components/list-row/list-row.d.mts

@@ -24,6 +24,19 @@ export type ListRowProps = useRender.ComponentProps<"button"> & Pick<VariantProp
    *  `flex flex-col gap-0.5 py-2` column. A settings card keeps the default
    *  look, with its lines. */
   cell?: boolean;
+  /** The row belongs to the setting in the row above it, in the same
+   *  `ListRowGroup`: quiet hours' start and end times under Quiet hours, a
+   *  server's channel overrides under its notification level. It draws no
+   *  hairline above it (a hairline says "another setting"), and a `plain`
+   *  row has no top padding, so it follows the row it belongs to. The row
+   *  above keeps its own height and its switch, centred on its own title
+   *  and description, doesn't move. The row after it draws its hairline as
+   *  usual. An interactive one keeps the control height as its least, so
+   *  it stays a 44px target on a phone and a touch screen. Carries
+   *  `data-attached`. Tie it to its setting for assistive technology: a
+   *  display-only one takes `role="group"` and `aria-labelledby` the
+   *  setting's title id; an interactive one, `aria-describedby` that id. */
+  attached?: boolean;
 };
 /**
  * One row of a list. It renders a `button` by default; pass `render={<a />}`
@@ -31,7 +44,7 @@ export type ListRowProps = useRender.ComponentProps<"button"> & Pick<VariantProp
  * block (an avatar, a channel or icon tile, `ListRowIcon`), `ListRowBody`, and
  * anything trailing (a value, a badge, a switch, `ListRowChevron`).
  */
-export declare function ListRow({ variant, tone, selected, interactive, cell, className, render, ...props }: ListRowProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export declare function ListRow({ variant, tone, selected, interactive, cell, attached, className, render, ...props }: ListRowProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export type ListRowIconProps = useRender.ComponentProps<"span">;
 /** A 20px leading icon in ink-3: entry rows and settings. */
 export declare function ListRowIcon({ className, render, ...props }: ListRowIconProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/components/list-row/list-row.mjs

@@ -23,17 +23,19 @@ function ListRowGroup({ className, render, ...props }) {
 * block (an avatar, a channel or icon tile, `ListRowIcon`), `ListRowBody`, and
 * anything trailing (a value, a badge, a switch, `ListRowChevron`).
 */
-function ListRow({ variant = "default", tone = "default", selected = false, interactive = true, cell = false, className, render, ...props }) {
+function ListRow({ variant = "default", tone = "default", selected = false, interactive = true, cell = false, attached = false, className, render, ...props }) {
 	const { root } = listRow({
 		variant,
 		interactive,
-		cell
+		cell,
+		attached
 	});
 	const defaultProps = {
 		"data-slot": "list-row",
 		"data-variant": variant,
 		"data-tone": tone === "default" ? void 0 : tone,
 		"data-selected": selected ? "" : void 0,
+		"data-attached": attached ? "" : void 0,
 		className: root({ className }),
 		...interactive && !render ? { type: "button" } : {}
 	};

package/dist/components/list-row/list-row.recipe.d.mts

@@ -15,6 +15,10 @@ export declare const listRow: import("tailwind-variants/lite").TVReturnType<{
     true: {};
     false: {};
   };
+  attached: {
+    true: {};
+    false: {};
+  };
   cell: {
     false: {
       root: string[];
@@ -57,6 +61,10 @@ export declare const listRow: import("tailwind-variants/lite").TVReturnType<{
     true: {};
     false: {};
   };
+  attached: {
+    true: {};
+    false: {};
+  };
   cell: {
     false: {
       root: string[];
@@ -99,6 +107,10 @@ export declare const listRow: import("tailwind-variants/lite").TVReturnType<{
     true: {};
     false: {};
   };
+  attached: {
+    true: {};
+    false: {};
+  };
   cell: {
     false: {
       root: string[];