@fuzdev/fuz_ui 0.199.0 → 0.201.0

package/dist/Dialog.svelte

@@ -1,167 +1,177 @@
 <script lang="ts">
 	import type {Snippet} from 'svelte';
-	import {is_editable, swallow} from '@fuzdev/fuz_util/dom.js';
-	import {wait} from '@fuzdev/fuz_util/async.js';
-
-	import Teleport from './Teleport.svelte';
-	import type {DialogLayout} from './dialog.js';
-
-	// TODO use `<dialog>` here instead of `Teleport`
-	// https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
-
-	/*
-
-	This component is a singleton that mounts to a #dialog container element added to the body,
-	using a `Teleport` component to avoid ancestor-caused style issues like overflow and z-index.
-	It adds `.dialog` to the body when mounted to fix scrolling behavior,
-	and adds padding to the body to adjust for any scrollbars.
-	It uses a CSS custom property for this to avoid the high complexity of trying to
-	correctly revert any preexisting values for overflow and padding on the body.
-	We don't want to add restrictions to what users can do to the body on their own!
-
-	*/
+	import type {SvelteHTMLElements} from 'svelte/elements';
+	import {SvelteSet} from 'svelte/reactivity';
+	import {swallow} from '@fuzdev/fuz_util/dom.js';
+
+	import {dialog_context, type DialogContext, type DialogAlign} from './dialog.js';
+
+	/**
+	 * This component renders a native `<dialog>` opened with `showModal()`, which
+	 * puts it in the top layer. The top layer escapes ancestor stacking/overflow
+	 * contexts (so no `Teleport` is needed), traps focus, makes the rest of the page
+	 * inert, closes on Escape, and restores focus to the previously focused element
+	 * on close -- all natively. The dim background is the native `::backdrop`.
+	 *
+	 * We render a full-viewport overlay inside the dialog rather than a content-sized
+	 * box, to preserve the scrolling and `align="top"` behaviors. The content
+	 * surface itself is the consumer's -- pair this with `DialogContent` for the
+	 * default `.pane` card and gutter, or render your own surface in `children`.
+	 *
+	 * @module
+	 */
 
 	const {
-		container,
-		layout = 'centered',
-		index = 0,
-		active = true,
+		show = true,
+		align = 'center',
+		dismissable = true,
 		content_selector = '.pane',
+		onbeforeclose,
 		onclose,
 		children,
-	}: {
-		// TODO maybe change this API away from an element to a selector? or remove the API completely?
-		container?: HTMLElement;
+		...rest
+	}: Omit<SvelteHTMLElements['dialog'], 'children' | 'onclose'> & {
 		/**
-		 * @default 'centered'
+		 * Whether the dialog is shown. When the `<dialog>` mounts it opens via
+		 * `showModal()`; when it unmounts it closes.
+		 * Defaults to `true` so the `{#if opened}<Dialog>...</Dialog>{/if}` pattern
+		 * works without passing `show` -- mounting the component opens the dialog.
+		 * Pass `show={opened}` to skip the outer `{#if}` and let the component manage
+		 * its own conditional rendering.
+		 * @default true
 		 */
-		layout?: DialogLayout;
+		show?: boolean;
 		/**
-		 * index 0 is under 1 is under 2 etc -- the topmost dialog is the last in the array
-		 * @default 0
+		 * How the content is aligned in the viewport. `center` vertically centers it;
+		 * `top` aligns it to the top and grows downward, which avoids jank when the
+		 * content's height changes.
+		 * @default 'center'
 		 */
-		index?: number;
+		align?: DialogAlign;
 		/**
+		 * Whether clicking outside the content (see `content_selector`) closes the
+		 * dialog. `Escape` closes it regardless of this.
 		 * @default true
 		 */
-		active?: boolean;
+		dismissable?: boolean;
 		/**
-		 * If provided, prevents clicks that would close the dialog
-		 * from bubbling past any elements matching this selector.
+		 * Fallback selector for a content surface you render in `children` yourself
+		 * (rather than via `DialogContent`, which self-registers).
+		 * When `dismissable`, a press that isn't inside a registered surface (e.g.
+		 * `DialogContent`, which self-registers) and doesn't match this selector
+		 * closes the dialog. Defaults to the fuz_css `.pane` card; set it to match
+		 * your surface's outermost element -- with no registered surface and no
+		 * match, presses anywhere close the dialog.
 		 * @default '.pane'
 		 */
-		content_selector?: string | null;
+		content_selector?: string;
+		/**
+		 * Called before a user-initiated close (`Escape`, click-outside, or `close`).
+		 * Return `false` to veto and keep the dialog open -- e.g. to confirm
+		 * discarding unsaved changes. Programmatic close via `show={false}` bypasses
+		 * this.
+		 */
+		onbeforeclose?: () => boolean | void;
+		/**
+		 * Called when the dialog closes -- via `Escape`, click-outside, or `close`.
+		 * Use it to sync your own open state, e.g. `onclose={() => (opened = false)}`.
+		 * Like `onbeforeclose`, programmatic close via `show={false}` bypasses this.
+		 */
 		onclose?: () => void;
-		children: Snippet<[close: (e?: Event) => void]>;
+		/**
+		 * Rendered inside the dialog overlay. Receives the `DialogContext` (e.g.
+		 * `{close}`); pair with `DialogContent` or render your own surface.
+		 */
+		children: Snippet<[dialog: DialogContext]>;
 	} = $props();
 
-	const ROOT_SELECTOR = 'body'; // TODO make configurable
-	const CONTAINER_ID = 'fuz_dialog';
-
-	let container_el: HTMLElement | undefined = $state.raw();
-	$effect(() => {
-		update_container_el(container);
-	});
-
-	const update_container_el = (container: HTMLElement | undefined): void => {
-		if (container) {
-			container_el = container;
-		} else {
-			const found = document.getElementById(CONTAINER_ID);
-			if (found) {
-				container_el = found;
-			} else {
-				const root_el = document.querySelector(ROOT_SELECTOR);
-				if (!root_el) {
-					throw Error(`Cannot find dialog root element with selector '${ROOT_SELECTOR}'`);
-				}
-				container_el = document.createElement('div');
-				container_el.id = CONTAINER_ID;
-				container_el.style.display = 'contents';
-				root_el.appendChild(container_el);
-			}
-		}
+	let dialog_el: HTMLDialogElement | undefined;
+
+	// Guards against a single dismissal firing `onclose` twice. Reset on mount.
+	let closing = false;
+
+	// Closes the native dialog (which restores focus to the trigger) and notifies
+	// the consumer to unmount us. Closing here, while still mounted and connected,
+	// is what makes focus restoration work -- closing on unmount would run on a
+	// detached node, which doesn't restore focus.
+	const request_close = () => {
+		if (closing) return;
+		// let the consumer veto a user-initiated dismissal (e.g. confirm unsaved changes)
+		if (onbeforeclose?.() === false) return;
+		closing = true;
+		dialog_el?.close();
+		onclose?.();
 	};
 
-	let dialog_el: HTMLElement | undefined = $state.raw();
-	let content_el: HTMLElement | undefined = $state.raw();
-
+	// The `close` passed to children also swallows the triggering event.
 	const close = (e?: Event) => {
 		if (e) swallow(e);
-		onclose?.();
+		request_close();
 	};
 
-	// TODO hook into a ui input system
-	const on_window_keydown = (e: KeyboardEvent) => {
-		if (e.key === 'Escape' && !is_editable(e.target)) {
-			// apply hotkey only for the top-most dialog
-			const parent_el = dialog_el?.parentElement;
-			const parents = parent_el?.parentElement?.children;
-			const index = Array.prototype.indexOf.call(parents, parent_el);
-			if (!parents || index === parents.length - 1 || index === -1) {
-				close(e);
-			}
-		}
+	// Content surfaces (e.g. `DialogContent`) register here so a press inside one
+	// isn't an outside-dismiss. Identity-based, so it works regardless of classes;
+	// `content_selector` stays the fallback for surfaces rendered in `children`.
+	const surfaces = new SvelteSet<Element>();
+	const register_surface = (element: Element): (() => void) => {
+		surfaces.add(element);
+		return () => {
+			surfaces.delete(element);
+		};
 	};
 
-	// The dialog isn't "ready" until the teleport moves it.
-	// Rendering the the dialog's children only once it's ready fixes things like `autofocus`.
-	let ready = $state.raw(false);
+	// The context is both passed to `children` and set for descendants (e.g.
+	// `DialogContent`), so either path can close the dialog.
+	const context: DialogContext = {close, register_surface};
+	dialog_context.set(context);
+
+	const setup_dialog = (el: HTMLDialogElement) => {
+		dialog_el = el;
+		closing = false;
+		// Esc (and any platform close request) fires `cancel`. We swallow it and
+		// close the dialog ourselves (above, while connected) so focus is restored,
+		// and so the consumer's state stays in sync and we unmount.
+		const oncancel = (e: Event) => {
+			swallow(e);
+			request_close();
+		};
+		el.addEventListener('cancel', oncancel);
+		if (!el.open) el.showModal();
+		return () => {
+			el.removeEventListener('cancel', oncancel);
+			dialog_el = undefined;
+			// fallback for programmatic unmount (e.g. `show` set false directly)
+			if (el.open) el.close();
+		};
+	};
 </script>
 
-<svelte:window onkeydown={active ? on_window_keydown : undefined} />
-
-<!--
-	The `tabindex` and `el.focus()` fix scrolling with the keyboard,
-	needed because SvelteKit puts `tabindex` on the body,
-	but there's more that needs to be done for accessibility, like focus capture.
-	For more see: https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal
-	and https://developer.mozilla.org/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets
--->
-<Teleport
-	to={container_el}
-	onmove={async () => {
-		await wait(); // TODO this is a hack to get animations working, `Teleport` now mounts synchronously?!
-		ready = true;
-		dialog_el?.focus(); // TODO make this more declarative? probably want to focus only after moving though, not on mount, which makes an action trickier
-	}}
->
-	<div
-		class="dialog"
-		class:ready
-		class:layout-page={layout === 'page'}
-		role="dialog"
-		aria-modal="true"
-		bind:this={dialog_el}
-		tabindex="-1"
-		style:z-index={100 + index}
+{#if show}
+	<dialog
+		{...rest}
+		class="dialog {rest.class}"
+		class:align-top={align === 'top'}
+		{@attach setup_dialog}
 	>
-		<div class="dialog-layout">
-			<div
-				class="dialog-wrapper"
-				role="none"
-				onmousedown={(e) => {
-					// Close if clicking outside `content_el` but inside the wrapper
-					const target = e.target as Element;
-					if (
-						content_el &&
-						(content_el === target ||
-							!content_el.contains(target) ||
-							(content_selector && !target.closest(content_selector)))
-					) {
-						close(e);
-					}
-				}}
-			>
-				<div class="dialog-bg" aria-hidden="true"></div>
-				<div class="dialog-content" bind:this={content_el}>
-					<!-- mount the content only after teleporting to avoid issues -->
-					{#if ready}{@render children(close)}{/if}
-				</div>
-			</div>
+		<div
+			class="dialog-wrapper"
+			role="none"
+			onmousedown={(e) => {
+				if (!dismissable) return;
+				const target = e.target as Element;
+				// inside a registered surface (e.g. DialogContent) -> not an outside dismiss
+				for (const surface of surfaces) {
+					if (surface.contains(target)) return;
+				}
+				// fallback for surfaces rendered in `children`: match `content_selector`
+				if (content_selector && target.closest(content_selector)) return;
+				close(e);
+			}}
+		>
+			{@render children(context)}
 		</div>
-	</div>
-</Teleport>
+	</dialog>
+{/if}
 
 <style>
 	.dialog {
@@ -171,51 +181,50 @@
 				var(--shadow_color, var(--shadow_color_umbra)) var(--shadow_alpha_70),
 				transparent
 			);
+		/* reset the user-agent dialog styles; we render a full-viewport overlay */
+		max-width: none;
+		max-height: none;
+		/* width/height are needed despite `inset: 0` to make the dialog element fill the viewport */
+		width: 100%;
+		height: 100%;
+		margin: 0;
+		padding: 0;
+		border: none;
+		background: transparent;
+		color: inherit;
 		position: fixed;
 		inset: 0;
 		overflow: auto;
-		/* this simplifies the code a lot but doesn't prevent scrolling
-		the underlying content when the dialog doesn't overflow, even when `overflow: scroll`
-		TODO check if this behaves as desired after switching to use the `dialog` element */
 		overscroll-behavior: contain;
 	}
+	/* the native backdrop is the dim background; fade it in on open */
+	.dialog::backdrop {
+		background-color: var(--dialog_bg, var(--darken_60));
+		transition: background-color var(--duration_2) ease;
+	}
+	@starting-style {
+		.dialog::backdrop {
+			background-color: transparent;
+		}
+	}
 
+	/* Lock background scroll while a modal dialog is open. `scrollbar-gutter`
+	reserves the scrollbar space so toggling the lock doesn't shift the layout. */
+	:global(html:has(dialog.dialog[open])) {
+		overflow: hidden;
+		scrollbar-gutter: stable;
+	}
+
+	/* `min-height: 100%` (not `height`) makes tall content overflow downward only: the
+	wrapper grows to its content, so the centered top stays reachable in the dialog's
+	scroll. A fixed-height centering box would strand the top above the scroll origin. */
 	.dialog-wrapper {
-		position: relative; /* for the surface */
 		min-height: 100%;
 		display: flex;
 		align-items: center;
 		justify-content: center;
 	}
-	.layout-page .dialog-wrapper {
+	.align-top .dialog-wrapper {
 		align-items: start;
 	}
-
-	.dialog-bg {
-		position: absolute;
-		inset: 0;
-		z-index: 0;
-		opacity: 0;
-		transition: opacity var(--duration_3) ease;
-		background-color: var(--dialog_bg, var(--darken_60));
-	}
-	.ready .dialog-bg {
-		opacity: 1;
-	}
-
-	.dialog-layout {
-		height: 100%;
-		/* makes the content overflow downwards instead of upwards+downwards because it's centered */
-		max-height: 100%;
-	}
-
-	.dialog-content {
-		width: 100%;
-		transform: scale(0.99);
-		transition: transform var(--duration_1) ease;
-		padding: 40px;
-	}
-	.ready .dialog-content {
-		transform: scale(1);
-	}
 </style>

package/dist/Dialog.svelte.d.ts

@@ -1,28 +1,59 @@
 import type { Snippet } from 'svelte';
-import type { DialogLayout } from './dialog.js';
-type $$ComponentProps = {
-    container?: HTMLElement;
+import type { SvelteHTMLElements } from 'svelte/elements';
+import { type DialogContext, type DialogAlign } from './dialog.js';
+type $$ComponentProps = Omit<SvelteHTMLElements['dialog'], 'children' | 'onclose'> & {
     /**
-     * @default 'centered'
+     * Whether the dialog is shown. When the `<dialog>` mounts it opens via
+     * `showModal()`; when it unmounts it closes.
+     * Defaults to `true` so the `{#if opened}<Dialog>...</Dialog>{/if}` pattern
+     * works without passing `show` -- mounting the component opens the dialog.
+     * Pass `show={opened}` to skip the outer `{#if}` and let the component manage
+     * its own conditional rendering.
+     * @default true
      */
-    layout?: DialogLayout;
+    show?: boolean;
     /**
-     * index 0 is under 1 is under 2 etc -- the topmost dialog is the last in the array
-     * @default 0
+     * How the content is aligned in the viewport. `center` vertically centers it;
+     * `top` aligns it to the top and grows downward, which avoids jank when the
+     * content's height changes.
+     * @default 'center'
      */
-    index?: number;
+    align?: DialogAlign;
     /**
+     * Whether clicking outside the content (see `content_selector`) closes the
+     * dialog. `Escape` closes it regardless of this.
      * @default true
      */
-    active?: boolean;
+    dismissable?: boolean;
     /**
-     * If provided, prevents clicks that would close the dialog
-     * from bubbling past any elements matching this selector.
+     * Fallback selector for a content surface you render in `children` yourself
+     * (rather than via `DialogContent`, which self-registers).
+     * When `dismissable`, a press that isn't inside a registered surface (e.g.
+     * `DialogContent`, which self-registers) and doesn't match this selector
+     * closes the dialog. Defaults to the fuz_css `.pane` card; set it to match
+     * your surface's outermost element -- with no registered surface and no
+     * match, presses anywhere close the dialog.
      * @default '.pane'
      */
-    content_selector?: string | null;
+    content_selector?: string;
+    /**
+     * Called before a user-initiated close (`Escape`, click-outside, or `close`).
+     * Return `false` to veto and keep the dialog open -- e.g. to confirm
+     * discarding unsaved changes. Programmatic close via `show={false}` bypasses
+     * this.
+     */
+    onbeforeclose?: () => boolean | void;
+    /**
+     * Called when the dialog closes -- via `Escape`, click-outside, or `close`.
+     * Use it to sync your own open state, e.g. `onclose={() => (opened = false)}`.
+     * Like `onbeforeclose`, programmatic close via `show={false}` bypasses this.
+     */
     onclose?: () => void;
-    children: Snippet<[close: (e?: Event) => void]>;
+    /**
+     * Rendered inside the dialog overlay. Receives the `DialogContext` (e.g.
+     * `{close}`); pair with `DialogContent` or render your own surface.
+     */
+    children: Snippet<[dialog: DialogContext]>;
 };
 declare const Dialog: import("svelte").Component<$$ComponentProps, {}, "">;
 type Dialog = ReturnType<typeof Dialog>;

package/dist/Dialog.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Dialog.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/Dialog.svelte"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,QAAQ,CAAC;AAKpC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AAE7C,KAAK,gBAAgB,GAAI;IAExB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC;CAChD,CAAC;AA4HH,QAAA,MAAM,MAAM,sDAAwC,CAAC;AACrD,KAAK,MAAM,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC;AACxC,eAAe,MAAM,CAAC"}
+{"version":3,"file":"Dialog.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/Dialog.svelte"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,QAAQ,CAAC;AACpC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAIxD,OAAO,EAAiB,KAAK,aAAa,EAAE,KAAK,WAAW,EAAC,MAAM,aAAa,CAAC;AAEhF,KAAK,gBAAgB,GAAI,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,GAAG;IACrF;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;CAC3C,CAAC;AAsHH,QAAA,MAAM,MAAM,sDAAwC,CAAC;AACrD,KAAK,MAAM,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC;AACxC,eAAe,MAAM,CAAC"}

package/dist/DialogContent.svelte

@@ -0,0 +1,140 @@
+<script lang="ts">
+	import type {Snippet} from 'svelte';
+	import type {HTMLAttributes, SvelteHTMLElements} from 'svelte/elements';
+
+	import {dialog_context, type DialogContext, type DialogCloseButtonAttrs} from './dialog.js';
+
+	/**
+	 * The default content surface for `Dialog`: a fuz_css `.pane` card with a
+	 * `gutter` margin (the dismiss zone), centered in the viewport by `Dialog`'s
+	 * own layout. It reads `close` from `dialog_context` (set by `Dialog`) and
+	 * passes it to `children`, so content can close the dialog without the consumer
+	 * threading `close` down from `Dialog`'s own `children` snippet.
+	 *
+	 * Must be rendered inside a `Dialog`, with which it registers its surface, so
+	 * click-outside-to-close treats presses inside the card as inside regardless of
+	 * classes -- `pane={false}` works without further setup.
+	 *
+	 * By default it renders a `close_button` floating just outside the surface's
+	 * top-right corner. The surface is a containing block (`position: relative`) for
+	 * that button and any absolutely-positioned content in `children`.
+	 *
+	 * The surface has no layout of its own -- it's a plain block, so children flow
+	 * top-to-bottom in normal document order. Pass `class` through (e.g. `box` for a
+	 * centered column, `column` for an uncentered one) to add one.
+	 *
+	 * @module
+	 */
+
+	const {
+		padding = 'var(--space_xl)',
+		pane = true,
+		gutter = 'var(--space_xl3)',
+		max_width = 'var(--distance_md)',
+		close_button = true,
+		children,
+		...rest
+	}: Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+		/**
+		 * The content surface's padding, set as an inline style. Defaults to
+		 * `var(--space_xl)` for a comfortable gutter between the card edge and its
+		 * content. Set to `''` or `'0'` for no padding (e.g. a flush image or a
+		 * surface that manages its own spacing).
+		 * @default 'var(--space_xl)'
+		 */
+		padding?: string;
+		/**
+		 * Whether to apply the fuz_css `.pane` card class to the content surface --
+		 * its opaque background, shadow, and rounded corners. `true` (the default) is
+		 * the standard dialog card; `false` gives a chromeless surface. Either way the
+		 * surface registers with `Dialog`, so click-outside-to-close keeps working.
+		 * @default true
+		 */
+		pane?: boolean;
+		/**
+		 * The gutter around the `.pane` card -- its outer margin, and so the area
+		 * outside the card where a press dismisses the dialog. Set to `''` or `'0'` to remove.
+		 * @default 'var(--space_xl3)'
+		 */
+		gutter?: string;
+		/**
+		 * The card's max width. The card shrinks to its content and is capped here,
+		 * so narrow content stays narrow while wide content doesn't sprawl. Set to
+		 * `''` for no cap (pure shrink-to-content).
+		 * @default 'var(--distance_md)'
+		 */
+		max_width?: string;
+		/**
+		 * The close button floating just outside the content surface's top-right
+		 * corner. `true` (the default) renders an absolutely-positioned `.sm.plain.icon_button`
+		 * that closes the dialog; `false` removes it. It renders after
+		 * `children`, so a content control (or an `autofocus` element) takes initial
+		 * focus on open rather than the close button.
+		 *
+		 * Pass a `Snippet` to render your own. It receives `attrs`
+		 * (`DialogCloseButtonAttrs`) carrying the default's placement, styling, a11y,
+		 * and `onclick` (closes the dialog), plus the `DialogContext` (e.g. `{close}`).
+		 * Spread `attrs` onto a `<button>` to inherit the corner anchoring and override
+		 * only what differs (e.g. the glyph), or drop it to place the button freely. The
+		 * surface is a containing block (`position: relative`), so an absolutely-positioned
+		 * custom button anchors to it.
+		 * @default true
+		 */
+		close_button?: boolean | Snippet<[attrs: DialogCloseButtonAttrs, dialog: DialogContext]>;
+		/**
+		 * Rendered inside the content surface. Receives the `DialogContext` (e.g.
+		 * `{close}`) so content can close the dialog without reaching into `Dialog`'s
+		 * `children` snippet.
+		 *
+		 * The default `close_button` renders as the surface's last child (so a content
+		 * control or `autofocus` element wins initial focus over it). Because it's a
+		 * real child, it throws off universal child-spacing selectors: your content's
+		 * last element is no longer `:last-child` (so `> :not(:last-child)` matches it
+		 * and `> :last-child` skips it), and `> * + *` matches the button itself. Either
+		 * scope spacing to your own elements or a class, or wrap your content in a single
+		 * element so its child selectors no longer see the button.
+		 */
+		children: Snippet<[dialog: DialogContext]>;
+	} = $props();
+
+	const dialog = dialog_context.get('DialogContent must be rendered inside a Dialog');
+
+	// the default close button's attributes; `onclick` closes the dialog and the rest
+	// is handed to a custom `close_button` snippet so it can inherit the corner-anchored
+	// button by spreading them. positioning is inline (not a scoped class) so it travels
+	// into the consumer's snippet, which carries its own style scope
+	const close_button_attrs: DialogCloseButtonAttrs = {
+		type: 'button',
+		class: 'sm plain icon_button',
+		style: 'position: absolute; top: 0; right: 0;',
+		onclick: dialog.close,
+		title: 'close',
+		'aria-label': 'close',
+	} satisfies SvelteHTMLElements['button'];
+</script>
+
+<!-- The surface is centered by `Dialog`'s `.dialog-wrapper` flex (no wrapper of its own
+needed) and is a containing block (`position: relative`) for the close button and any
+absolutely-positioned content in `children`. `gutter` is the surface's margin -- the
+dismiss zone outside the card, where a press lands on the wrapper and closes the dialog.
+`min-width: 0` lets this flex-item surface shrink below its content's intrinsic width, so
+content with its own overflow (e.g. `Code`) scrolls instead of forcing the card wider. -->
+<div
+	{...rest}
+	class:pane
+	style:padding
+	style:margin={gutter}
+	style:max-width={max_width}
+	style:min-width="0"
+	style:position="relative"
+	{@attach dialog.register_surface}
+>
+	{@render children(dialog)}
+	<!-- rendered after `children` so a content control (or an `autofocus` element)
+	takes initial focus on open, not the close button -->
+	{#if close_button === true}
+		<button {...close_button_attrs}>✕</button>
+	{:else if close_button}
+		{@render close_button(close_button_attrs, dialog)}
+	{/if}
+</div>