sheer-ui 0.0.0

package/src/lib/components/date-range-field/types.ts

@@ -0,0 +1,171 @@
+import type { DateValue } from '@internationalized/date';
+import type { OnChangeFn, WithChild, Without } from '../../internal/types.js';
+import type { BitsPrimitiveDivAttributes, BitsPrimitiveSpanAttributes } from '../../internal/attribute-types.js';
+import type { DateOnInvalid, DateRange, DateRangeValidator, EditableSegmentPart, SegmentPart } from '../../internal/index.js';
+import type { DateFieldSegmentProps, DateFieldSegmentPropsWithoutHTML } from '../date-field/types.js';
+import type { Granularity } from '../../internal/date-time/types.js';
+
+export type DateRangeFieldRootPropsWithoutHTML = WithChild<{
+	/**
+	 * The value of the date range field.
+	 *
+	 * @bindable
+	 */
+	value?: DateRange;
+
+	/**
+	 * A callback that is called when the value of the date range field changes.
+	 */
+	onValueChange?: OnChangeFn<DateRange | undefined>;
+
+	/**
+	 * The placeholder value of the date field. This determines the format
+	 * and what date the field starts at when it is empty.
+	 *
+	 * @bindable
+	 */
+	placeholder?: DateValue;
+
+	/**
+	 * A callback that is called when the date field's placeholder value changes.
+	 */
+	onPlaceholderChange?: OnChangeFn<DateValue | undefined>;
+
+	/**
+	 * A function that returns a string or array of strings as validation errors if the date is
+	 * invalid, or nothing if the date is valid
+	 */
+	validate?: DateRangeValidator;
+
+	/**
+	 * A callback fired when the date field's value is invalid. Use this to display an error
+	 * message to the user.
+	 */
+	onInvalid?: DateOnInvalid;
+
+	/**
+	 * The minimum acceptable date. When provided, the date field
+	 * will be marked as invalid if the user enters a date before this date.
+	 */
+	minValue?: DateValue;
+
+	/**
+	 * The maximum acceptable date. When provided, the date field
+	 * will be marked as invalid if the user enters a date after this date.
+	 */
+	maxValue?: DateValue;
+
+	/**
+	 * If true, the date field will be disabled and users will not be able
+	 * to interact with it. This also disables the hidden input element if
+	 * the date field is used in a form.
+	 *
+	 * @defaultValue false
+	 */
+	disabled?: boolean;
+
+	/**
+	 * If true, the date field will be readonly, and users will not be able to
+	 * edit the values of any of the individual segments.
+	 *
+	 * @defaultValue false
+	 */
+	readonly?: boolean;
+
+	/**
+	 * If true, the date field will be required, which is useful when used within
+	 * a form. If the date field is empty when the form is submitted, the form
+	 * will not be valid.
+	 *
+	 * @defaultValue false
+	 */
+	required?: boolean;
+
+	/**
+	 * An array of segment names that should be readonly. If provided, only the
+	 * segments not in this array will be editable.
+	 */
+	readonlySegments?: EditableSegmentPart[];
+
+	/**
+	 * The format to use for displaying the time in the input.
+	 * If using a 12 hour clock, ensure you also include the `dayPeriod`
+	 * segment in your input to ensure the user can select AM/PM.
+	 *
+	 * @defaultValue the locale's default time format
+	 */
+	hourCycle?: 12 | 24;
+
+	/**
+	 * The locale to use for formatting the date field.
+	 *
+	 * @defaultValue 'en'
+	 */
+	locale?: string;
+
+	/**
+	 * The granularity of the date field. This determines which
+	 * segments will be includes in the segments array used to
+	 * build the date field.
+	 *
+	 * By default, when a `CalendarDate` value is used, the granularity
+	 * will default to `'day'`, and when a `CalendarDateTime` or `ZonedDateTime`
+	 * value is used, the granularity will default to `'minute'`.
+	 *
+	 * Granularity is only used for visual purposes, and does not impact
+	 * the value of the date field. You can have the same value synced
+	 * between multiple date fields with different granularities and they
+	 * will all contain the same value.
+	 *
+	 * @defaultValue 'day'
+	 */
+	granularity?: Granularity;
+
+	/**
+	 * Whether or not to hide the timeZoneName segment from the date field.
+	 *
+	 * @defaultValue false;
+	 */
+	hideTimeZone?: boolean;
+
+	/**
+	 * The `id` of the element which contains the error messages for the date field when the
+	 * date is invalid.
+	 */
+	errorMessageId?: string;
+}>;
+
+export type DateRangeFieldRootProps = DateRangeFieldRootPropsWithoutHTML &
+	Without<BitsPrimitiveDivAttributes, DateRangeFieldRootPropsWithoutHTML>;
+
+export type DateRangeFieldLabelPropsWithoutHTML = WithChild;
+
+export type DateRangeFieldLabelProps = DateRangeFieldLabelPropsWithoutHTML &
+	Without<BitsPrimitiveSpanAttributes, DateRangeFieldLabelPropsWithoutHTML>;
+
+export type DateRangeFieldInputSnippetProps = {
+	segments: Array<{ part: SegmentPart; value: string }>;
+};
+
+export type DateRangeFieldInputPropsWithoutHTML = WithChild<
+	{
+		/**
+		 * The name to use for the hidden input element associated with this input
+		 * used for form submission.
+		 */
+		name?: string;
+
+		/**
+		 * Whether this input represents the start or end of the date range.
+		 */
+		type: 'start' | 'end';
+	},
+	DateRangeFieldInputSnippetProps
+>;
+
+export type DateRangeFieldInputProps = DateRangeFieldInputPropsWithoutHTML &
+	Without<BitsPrimitiveDivAttributes, DateRangeFieldInputPropsWithoutHTML>;
+
+export type DateRangeFieldSegmentPropsWithoutHTML = DateFieldSegmentPropsWithoutHTML;
+
+export type DateRangeFieldSegmentProps = DateFieldSegmentProps;

package/src/lib/components/dialog/components/dialog-close.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+	import { boxWith } from '../../../internal/tools/index.js';
+	import { mergeProps } from '../../../internal/merge-props.js';
+	import { DialogCloseState } from '../dialog.svelte.js';
+	import type { DialogCloseProps } from '../types.js';
+	import { createId } from '../../../internal/create-id.js';
+
+	const uid = $props.id();
+
+	let { children, child, id = createId(uid), ref = $bindable(null), disabled = false, ...restProps }: DialogCloseProps = $props();
+
+	const closeState = DialogCloseState.create({
+		variant: boxWith(() => 'close'),
+		id: boxWith(() => id),
+		ref: boxWith(
+			() => ref,
+			(v) => (ref = v),
+		),
+		disabled: boxWith(() => Boolean(disabled)),
+	});
+
+	const mergedProps = $derived(mergeProps({ 'data-slot': 'dialog-close' }, restProps, closeState.props));
+</script>
+
+{#if child}
+	{@render child({ props: mergedProps })}
+{:else}
+	<button {...mergedProps}>
+		{@render children?.()}
+	</button>
+{/if}

package/src/lib/components/dialog/components/dialog-content-headless.svelte

@@ -0,0 +1,104 @@
+<script lang="ts">
+	import { boxWith } from '../../../internal/tools/index.js';
+	import { mergeProps } from '../../../internal/merge-props.js';
+	import { DialogContentState } from '../dialog.svelte.js';
+	import type { DialogContentProps } from '../types.js';
+	import { interactOutsideAttachment } from '../../../internal/dismissible-layer/use-dismissable-layer.svelte.js';
+	import { escapeKeydownAttachment } from '../../../internal/escape-layer/use-escape-layer.svelte.js';
+	import { createFocusScopeProps } from '../../../internal/focus-scope/focus-scope.svelte.js';
+	import { createId } from '../../../internal/create-id.js';
+	import { scrollLockAttachment } from '../../../internal/body-scroll-lock.svelte.js';
+
+	/**
+	 * Headless JS-overlay dialog content — an always-mounted <div> (visibility:hidden while closed;
+	 * the drawer's exit keyframes hold it visible) with the FocusScope / EscapeLayer /
+	 * DismissibleLayer / ScrollLock stack and the CSS text-selection guard. The public Dialog.Content is now the native <dialog>
+	 * (dialog-content.svelte); this variant survives ONLY for the Drawer, whose vaul drag physics need a
+	 * draggable in-flow <div> and cannot live in the top layer. Keep in sync with the shared Dialog state
+	 * cell — it is the same DialogContentState, just rendered as a div instead of a modal <dialog>.
+	 */
+	const uid = $props.id();
+
+	let {
+		id = createId(uid),
+		children,
+		child,
+		ref = $bindable(null),
+		onCloseAutoFocus = () => {},
+		onOpenAutoFocus = () => {},
+		onEscapeKeydown = () => {},
+		onInteractOutside = () => {},
+		trapFocus = true,
+		preventScroll = true,
+		restoreScrollDelay = null,
+		...restProps
+	}: DialogContentProps = $props();
+
+	const contentState = DialogContentState.create({
+		id: boxWith(() => id),
+		ref: boxWith(
+			() => ref,
+			(v) => (ref = v),
+		),
+	});
+
+	// Closed state, on this element only (DialogContentState.props is shared with the native
+	// modal surface). The scroll lock's body styles land a tick after opening, after vaul's
+	// open effect has snapshotted them, as they did when the mount gate flipped a flush later.
+	const mergedProps = $derived(mergeProps(restProps, contentState.props, { style: contentState.root.cell.open ? {} : { visibility: 'hidden' } }));
+
+	const escapeAttachment = escapeKeydownAttachment({
+		escapeKeydownBehavior: () => restProps.escapeKeydownBehavior ?? 'close',
+		onEscapeKeydown: () => (e) => {
+			onEscapeKeydown(e);
+			if (e.defaultPrevented) return;
+			contentState.root.handleClose();
+		},
+		enabled: () => contentState.root.cell.open,
+	});
+
+	// Dialog content historically dropped the dismissible focus-capture props (its default-slot
+	// usage never threaded them), so only `dismissible.attachment` is merged below.
+	const dismissible = interactOutsideAttachment({
+		id: () => id,
+		interactOutsideBehavior: () => restProps.interactOutsideBehavior ?? 'close',
+		onInteractOutside: () => (e) => {
+			onInteractOutside(e);
+			if (e.defaultPrevented) return;
+			contentState.root.handleClose();
+		},
+		onFocusOutside: () => restProps.onFocusOutside,
+		enabled: () => contentState.root.cell.open,
+	});
+
+	// Flags the open surface for the CSS text-selection guard in ui.css.
+	const textSelectionGuard = $derived(
+		contentState.root.cell.open && (restProps.preventOverflowTextSelection ?? true) ? { 'data-text-selection-guard': '' } : {},
+	);
+
+	// Spans `present` (open through the settled exit), the window element lifecycle used to
+	// give it — restoreScrollDelay covers the scrollbar restore.
+	const scrollLock = scrollLockAttachment({
+		enabled: () => preventScroll && contentState.root.present,
+		restoreScrollDelay: () => restoreScrollDelay,
+	});
+
+	const focusScope = createFocusScopeProps({
+		enabled: () => contentState.root.cell.open,
+		trap: () => trapFocus,
+		loop: () => true,
+		onCloseAutoFocus: () => onCloseAutoFocus,
+		onOpenAutoFocus: () => onOpenAutoFocus,
+	});
+</script>
+
+{#if child}
+	{@render child({
+		props: mergeProps(mergedProps, focusScope.props, escapeAttachment, dismissible.attachment, textSelectionGuard, scrollLock),
+		...contentState.snippetProps,
+	})}
+{:else}
+	<div {...mergeProps(mergedProps, focusScope.props, escapeAttachment, dismissible.attachment, textSelectionGuard, scrollLock)}>
+		{@render children?.()}
+	</div>
+{/if}

package/src/lib/components/dialog/components/dialog-content.svelte

@@ -0,0 +1,69 @@
+<script lang="ts">
+	import { join } from 'overrule';
+	import ModalSurface from './modal-surface.svelte';
+	import type { DialogContentProps, DialogPortalProps } from '../types.js';
+	import type { WithoutChildrenOrChild } from '../../../internal/utils.js';
+
+	/**
+	 * Modal dialog adapter over the shared native modal surface (modal-surface.svelte),
+	 * which owns the skeleton: parity props, content state, controller, scroll lock, and
+	 * the `<dialog>` render. This file owns only Dialog's visual policy.
+	 *
+	 * The visual surface (centered box, bg, border, radius, shadow, padding, sm:max-w-lg) is baked
+	 * here — the shadcn convention — so a bare `<Dialog.Content>` is a styled modal; consumer
+	 * `class` still merges to override (e.g. `max-w-md!`). Two Tailwind gotchas: no `display`
+	 * utility on the <dialog> (grid lives on the inner wrapper); explicit centering via
+	 * `fixed inset-0 m-auto h-fit` (preflight resets the UA `margin:auto` that would otherwise
+	 * center it).
+	 */
+	let {
+		children,
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: DialogContentProps & {
+		portalProps?: WithoutChildrenOrChild<DialogPortalProps>;
+	} = $props();
+</script>
+
+<ModalSurface
+	bind:ref
+	data-slot="dialog-content"
+	class={join(
+		'dialog-content bg-background fixed inset-0 z-50 m-auto h-fit max-h-[calc(100dvh-2rem)] w-full max-w-[calc(100%-2rem)] overflow-y-auto rounded-lg border p-6 shadow-lg sm:max-w-lg',
+		className,
+	)}
+	{...restProps}>
+	<div class="grid gap-4">
+		{@render children?.()}
+	</div>
+</ModalSurface>
+
+<style>
+	/* Pop is a keyframe animation, not an @starting-style / display / overlay transition: WebKit
+	   doesn't start those on top-layer changes (bug 275184; `overlay` is Chromium-only), so
+	   transitions snapped both directions on iOS. Exit plays REVERSED on [data-state=closed] while
+	   the dialog is still open — the controller defers close() until animations settle. The
+	   closed-state display reset and the ::backdrop fade live in ui.css under [data-modal-surface]. */
+	/* Distinct in/out names on purpose: with a single name, the state flip only UPDATES the
+	   already-finished entry animation (animation-name unchanged → no restart per spec), so the
+	   exit would never play and the deferred close would fire instantly. */
+	@keyframes dialog-pop-in {
+		from {
+			scale: 0.95;
+			opacity: 0;
+		}
+	}
+	@keyframes dialog-pop-out {
+		to {
+			scale: 0.95;
+			opacity: 0;
+		}
+	}
+	:global(.dialog-content[open][data-state='open']) {
+		animation: dialog-pop-in 200ms cubic-bezier(0.4, 0, 0.2, 1);
+	}
+	:global(.dialog-content[open][data-state='closed']) {
+		animation: dialog-pop-out 200ms cubic-bezier(0.4, 0, 0.2, 1) forwards;
+	}
+</style>

package/src/lib/components/dialog/components/dialog-description.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+	import { boxWith } from '../../../internal/tools/index.js';
+	import { mergeProps } from '../../../internal/merge-props.js';
+	import { DialogDescriptionState } from '../dialog.svelte.js';
+	import type { DialogDescriptionProps } from '../types.js';
+	import { createId } from '../../../internal/create-id.js';
+
+	const uid = $props.id();
+
+	let { id = createId(uid), children, child, ref = $bindable(null), ...restProps }: DialogDescriptionProps = $props();
+
+	const descriptionState = DialogDescriptionState.create({
+		id: boxWith(() => id),
+		ref: boxWith(
+			() => ref,
+			(v) => (ref = v),
+		),
+	});
+
+	const mergedProps = $derived(mergeProps(restProps, descriptionState.props));
+</script>
+
+{#if child}
+	{@render child({ props: mergedProps })}
+{:else}
+	<div {...mergedProps}>
+		{@render children?.()}
+	</div>
+{/if}

package/src/lib/components/dialog/components/dialog-overlay.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+	import { boxWith } from '../../../internal/tools/index.js';
+	import { mergeProps } from '../../../internal/merge-props.js';
+	import { DialogOverlayState } from '../dialog.svelte.js';
+	import type { DialogOverlayProps } from '../types.js';
+	import { createId } from '../../../internal/create-id.js';
+
+	const uid = $props.id();
+
+	let { id = createId(uid), child, children, ref = $bindable(null), ...restProps }: DialogOverlayProps = $props();
+
+	const overlayState = DialogOverlayState.create({
+		id: boxWith(() => id),
+		ref: boxWith(
+			() => ref,
+			(v) => (ref = v),
+		),
+	});
+
+	// Always mounted; closed is visibility:hidden here, and the adapter's exit (the drawer's fadeOut
+	// keyframe, the sheet's overlay-surface transition) holds it visible while it plays.
+	const mergedProps = $derived(mergeProps(restProps, overlayState.props, { style: overlayState.root.cell.open ? {} : { visibility: 'hidden' } }));
+</script>
+
+{#if child}
+	{@render child({ props: mergedProps, ...overlayState.snippetProps })}
+{:else}
+	<div {...mergedProps}>
+		{@render children?.(overlayState.snippetProps)}
+	</div>
+{/if}

package/src/lib/components/dialog/components/dialog-title.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+	import { boxWith } from '../../../internal/tools/index.js';
+	import { mergeProps } from '../../../internal/merge-props.js';
+	import { DialogTitleState } from '../dialog.svelte.js';
+	import type { DialogTitleProps } from '../types.js';
+	import { createId } from '../../../internal/create-id.js';
+
+	const uid = $props.id();
+
+	let { id = createId(uid), ref = $bindable(null), child, children, level = 2, ...restProps }: DialogTitleProps = $props();
+
+	const titleState = DialogTitleState.create({
+		id: boxWith(() => id),
+		level: boxWith(() => level),
+		ref: boxWith(
+			() => ref,
+			(v) => (ref = v),
+		),
+	});
+
+	const mergedProps = $derived(mergeProps(restProps, titleState.props));
+</script>
+
+{#if child}
+	{@render child({ props: mergedProps })}
+{:else}
+	<div {...mergedProps}>
+		{@render children?.()}
+	</div>
+{/if}

package/src/lib/components/dialog/components/dialog-trigger.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+	import { boxWith } from '../../../internal/tools/index.js';
+	import { mergeProps } from '../../../internal/merge-props.js';
+	import { DialogTriggerState } from '../dialog.svelte.js';
+	import type { DialogTriggerProps } from '../types.js';
+	import { createId } from '../../../internal/create-id.js';
+
+	const uid = $props.id();
+
+	let { id = createId(uid), ref = $bindable(null), children, child, disabled = false, ...restProps }: DialogTriggerProps = $props();
+
+	const triggerState = DialogTriggerState.create({
+		id: boxWith(() => id),
+		ref: boxWith(
+			() => ref,
+			(v) => (ref = v),
+		),
+		disabled: boxWith(() => Boolean(disabled)),
+	});
+
+	const mergedProps = $derived(mergeProps(restProps, triggerState.props));
+</script>
+
+{#if child}
+	{@render child({ props: mergedProps })}
+{:else}
+	<button {...mergedProps}>
+		{@render children?.()}
+	</button>
+{/if}

package/src/lib/components/dialog/components/dialog.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+	import { boxWith } from '../../../internal/tools/index.js';
+	import { DialogRootState, DialogState } from '../dialog.svelte.js';
+	import type { DialogRootProps } from '../types.js';
+
+	let { open = false, onOpenChangeComplete = () => {}, state, children }: DialogRootProps = $props();
+
+	// Root owns both the machinery and the cell; `open` (the prop) is the cell's
+	// derivation source, and the children snippet is the only way the cell leaves.
+	// A caller-built `state` cell (with its own source/writer) takes over both roles.
+	// The cell's identity is fixed at mount — swapping `state` later is not supported.
+	// svelte-ignore state_referenced_locally
+	const dialog = state ?? new DialogState(() => open);
+	DialogRootState.create({
+		variant: boxWith(() => 'dialog'),
+		cell: dialog,
+		onOpenChangeComplete: boxWith(() => onOpenChangeComplete),
+	});
+</script>
+
+{@render children?.(dialog)}

package/src/lib/components/dialog/components/modal-surface.svelte

@@ -0,0 +1,131 @@
+<script lang="ts">
+	import type { HTMLDialogAttributes } from 'svelte/elements';
+	import { boxWith } from '../../../internal/tools/index.js';
+	import { mergeProps } from '../../../internal/merge-props.js';
+	import { DialogContentState } from '../dialog.svelte.js';
+	import type { DialogContentProps, DialogPortalProps } from '../types.js';
+	import { createId } from '../../../internal/create-id.js';
+	import type { WithoutChildrenOrChild } from '../../../internal/utils.js';
+	import { scrollLockAttachment } from '../../../internal/body-scroll-lock.svelte.js';
+	import { nativeDialogControllerAttachment } from '../../../internal/native-dialog-controller.svelte.js';
+
+	/**
+	 * The native modal surface: the one skeleton behind every modal `<dialog>` adapter
+	 * (Dialog.Content, Sheet.Content). Owns what the adapters used to copy — the parity
+	 * prop block, the content state, the controller attachment, the scroll lock, and the
+	 * `<dialog>` render + attribute cast. Adapters supply only their visual policy:
+	 * `class`, an `outsideEvent` override, and their inner markup.
+	 *
+	 * What native + CSS absorb, replacing the old JS overlay stack
+	 * (FocusScope / EscapeLayer / DismissibleLayer / presence gate / portal + overlay <div>):
+	 *   focus trap / restore / initial focus  → showModal() (drops FocusScope + the focus-memory stack)
+	 *   focus CONTAINMENT (can't tab out)      → native, via inert on everything outside the dialog
+	 *   focus trap LOOP (tab wraps ends)       → NOT native: inert stops escape but sequential nav lands
+	 *                                            on <body> for one step instead of wrapping. The
+	 *                                            controller's keydown handler closes that gap (via
+	 *                                            `trapFocus`, wired here for every adapter).
+	 *   Esc to close                           → native `cancel` (drops EscapeLayer + its global stack)
+	 *   inert background (clicks/focus/AT)     → native modal, stronger than the JS Tab-trap
+	 *   backdrop dim                           → ::backdrop (drops the rendered overlay <div>; the fade
+	 *                                            lives in ui.css under `[data-modal-surface]`)
+	 *   mount/unmount + enter/exit timing      → @starting-style + display/overlay allow-discrete
+	 *                                            (drops the {#if shouldRender} presence gate)
+	 *   click-outside to close                 → backdrop click; checked on `pointerdown` by default so
+	 *                                            a text-selection drag that overshoots the edge isn't
+	 *                                            misread as a backdrop click
+	 * Surviving JS: the controller attachment (open↔showModal + dismissal sync + tab-wrap) and
+	 * <ScrollLock> (native showModal makes the page inert but still scrollable; the ref-counted body
+	 * lock stays, and `overflow:hidden` leaks touch-scroll on iOS Safari).
+	 *
+	 * Adapter gotcha (Tailwind): no `display` utility on the `<dialog>` itself — a grid/flex class
+	 * overrides the UA `dialog:not([open]){display:none}`, leaving a closed dialog rendered and
+	 * intercepting events (ui.css re-asserts the reset, but layout utilities belong on an inner
+	 * wrapper). Each adapter's transition-property re-home stays in its own <style> — which
+	 * properties animate (scale vs translate) is visual policy.
+	 */
+	const uid = $props.id();
+
+	let {
+		id = createId(uid),
+		children,
+		child,
+		ref = $bindable(null),
+		// how the controller detects a backdrop dismissal; Dialog and Sheet both use the default.
+		outsideEvent = 'pointerdown',
+		// --- Accepted for API parity; the native <dialog> absorbs or no-ops these ---
+		// no-op: the <dialog> is always rendered; showModal()/close() toggles visibility.
+		forceMount = false,
+		// no-op: native modal restores focus to the opener on close.
+		onCloseAutoFocus = () => {},
+		// no-op: showModal() autofocuses ([autofocus] or the first focusable).
+		onOpenAutoFocus = () => {},
+		// wired below via the native `cancel` event.
+		onEscapeKeydown = () => {},
+		// wired below via backdrop click.
+		onInteractOutside = () => {},
+		// no-op: a native modal makes the background inert (no focus-outside to report).
+		onFocusOutside = () => {},
+		// honored — enables the controller's sequential-focus wrap.
+		trapFocus = true,
+		// still honored — passed to the scrollLockAttachment below.
+		preventScroll = true,
+		restoreScrollDelay = null,
+		// honored in the `cancel` / backdrop-click handlers below.
+		escapeKeydownBehavior = 'close',
+		interactOutsideBehavior = 'close',
+		// no-op: not applicable to a native modal surface.
+		preventOverflowTextSelection = true,
+		// no-op: no portal — a modal <dialog> renders in place and is promoted to the top layer.
+		portalProps,
+		...restProps
+	}: DialogContentProps & {
+		outsideEvent?: 'pointerdown' | 'click';
+		portalProps?: WithoutChildrenOrChild<DialogPortalProps>;
+	} = $props();
+
+	const contentState = DialogContentState.create({
+		id: boxWith(() => id),
+		ref: boxWith(
+			() => ref,
+			(v) => (ref = v),
+		),
+	});
+
+	// Bridge the shared root `open` to the native top-layer API and mirror native dismissal back
+	// into the root state, in one attachment. The root stays the source of truth, so Trigger /
+	// Close / handleClose stay authoritative.
+	//
+	// NOTE: onOpenChangeComplete is intentionally NOT re-homed here. The Dialog root watches
+	// `contentNode` (set by DialogContentState) and fires it once the <dialog>'s animations
+	// settle (useOpenChangeComplete) — a listener here would double-fire it.
+	const controllerAttachment = nativeDialogControllerAttachment({
+		open: () => contentState.root.cell.open,
+		onClose: () => contentState.root.handleClose(),
+		// the controller takes this as a plain, non-reactive value — fixed per adapter at mount
+		// svelte-ignore state_referenced_locally
+		outsideEvent,
+		onInteractOutside: () => onInteractOutside,
+		interactOutsideBehavior: () => interactOutsideBehavior,
+		onEscapeKeydown: () => onEscapeKeydown,
+		escapeKeydownBehavior: () => escapeKeydownBehavior,
+		trapFocus: () => trapFocus,
+	});
+
+	// The <dialog> persists across open/close, so the lock gates on the cell's open, not element lifecycle.
+	const scrollLock = scrollLockAttachment({
+		enabled: () => contentState.root.cell.open && preventScroll,
+		restoreScrollDelay: () => restoreScrollDelay,
+	});
+
+	const mergedProps = $derived(mergeProps({ 'data-modal-surface': '' }, restProps, contentState.props, scrollLock));
+</script>
+
+{#if child}
+	{@render child({ props: mergeProps(mergedProps, controllerAttachment), ...contentState.snippetProps })}
+{:else}
+	<!-- DialogContentState.props / DialogContentProps are authored for a <div>; their generic event
+	     handlers are typed to HTMLDivElement, so assert the merged set as dialog attributes. -->
+	<dialog {...controllerAttachment} {...mergedProps as unknown as HTMLDialogAttributes}>
+		{@render children?.()}
+	</dialog>
+{/if}