entasis 0.11.0 → 0.13.0

package/dist/components/Dialog/dialog.mcp.js

@@ -21,6 +21,7 @@ The Dialog component (also known as Modal) displays content in a layer above the
 
 ### Core Props
 - **open**: boolean (bindable) - Controls dialog visibility
+- **modal**: boolean (default: true) - A modal makes the page behind \`inert\`, locks page scroll, contains Tab, dims the page with the shared backdrop and dismisses on an outside press. \`modal={false}\` leaves the page interactive: no \`inert\`, no scroll lock, no backdrop, no Tab containment, and an outside press does not dismiss it unless \`closeOnClickOutside\` is set. Escape, the close button and swipes still close it (the Android Back gesture does not: it closes modal dialogs only). It renders no \`aria-modal\` (and \`data-modal="false"\`), always scrolls inside its card, and does not push dialogs beneath it back
 - **defaultOpen**: boolean (default: false) - Initial state when open is not provided
 - **id**: string - Unique identifier for the dialog
 - **type**: 'fullScreen' | 'drawerRight' | 'drawerLeft' | 'drawerBottom' | 'drawerTop' | 'alert' | 'modal' (default: 'modal')
@@ -29,7 +30,7 @@ The Dialog component (also known as Modal) displays content in a layer above the
   - drawerLeft: Drawer sliding in from the left
   - drawerBottom: Drawer sliding in from the bottom
   - drawerTop: Drawer sliding in from the top
-  - alert: Alert-style dialog
+  - alert: Alert dialog for an interruption that needs an answer: renders \`role="alertdialog"\` and ignores outside presses unless \`closeOnClickOutside\` is set (Escape still closes it)
   - modal: Standard modal dialog
   - Supports responsive values: pass a \`Partial<Record<Breakpoint, DialogType>>\` record such as \`{ xs: 'drawerBottom', md: 'modal' }\` to vary the type per breakpoint (breakpoint is one of 'xs' | 'sm' | 'md' | 'lg' | 'xl', tracked live from the viewport; the nearest defined key at or below the active one wins)
 - **responsive**: boolean (default: true) - When the resolved type is \`modal\`, collapse it into a \`drawerBottom\` bottom sheet on mobile (viewport < 768px). The sheet inherits swipe-to-dismiss and the drag thumb. Set false to keep a centered modal on every screen size
@@ -41,27 +42,32 @@ The Dialog component (also known as Modal) displays content in a layer above the
   - large: Larger dialog size
 
 ### Event Props
-- **onOpenChange**: (open: boolean) => void - Called once for each library-requested state change
-- **onAfterOpen**: (payload: DialogState) => void - Called after the open transition finishes
-- **onAfterClose**: (payload: DialogState) => void - Called after the close transition finishes
+- **onOpenChange**: (open: boolean, details: OpenChangeDetails) => void - Called before each library-requested state change, with \`details.reason\` (\`'trigger-press'\`, \`'escape-key'\`, \`'outside-press'\`, \`'close-press'\`, \`'swipe'\`, \`'close-watcher'\` for the Android Back gesture, \`'imperative-action'\`…), \`details.event\`, \`details.trigger\`, \`details.interaction\` and \`details.cancel()\`. Cancelling keeps the dialog as it is (a cancelled swipe snaps back) and leaves the event untouched. Inside the callback \`open\` still holds the previous state. Types from \`entasis/types\`
+- **onAfterOpen**: (payload: DialogApi) => void - Called once per open after the open transition finishes; a dialog created open (\`defaultOpen\`) renders once mounted, animates in and reports it too
+- **onAfterClose**: (payload: DialogApi) => void - Called once per close after the close transition finishes
 
 ### Slot Props
-- **title**: string | Snippet<[DialogState]> - Dialog title
-- **description**: string | Snippet<[DialogState]> - Dialog description
-- **children**: Snippet<[DialogState]> - Main dialog content
+- **title**: string | Snippet - Dialog title
+- **description**: string | Snippet - Dialog description
+- **children**: Snippet<[DialogApi]> - Main dialog content
 - **header**: Snippet - Custom header content
 - **footer**: Snippet - Custom footer content
-- **trigger**: Snippet | (ButtonProps & { content?: string }) - Custom trigger button
-- **closeButton**: Snippet - Custom close button
+- **trigger**: Snippet<[DialogApi]> | (ButtonProps & { content?: string }) - Custom trigger button. The built-in button carries \`aria-haspopup="dialog"\`, \`aria-expanded\` and \`aria-controls\`; its \`onclick\` runs first, and \`event.preventDefault()\` there keeps the dialog closed. In a snippet, \`{@attach dialog.trigger}\` gives any element the same contract
+- **closeButton**: Snippet | false - Custom close button, or \`false\` to suppress the visible one. A closable dialog whose visible button is suppressed (\`false\`, or a snippet that renders nothing, as the Popover mobile sheet passes) still renders a visually hidden \`Close\` button at the end of the panel, out of the Tab order but in the accessibility tree, so screen reader users have a control that closes it. An \`alert\` never gets one: its own buttons answer it. The default close button is named \`Close\` (translated by the i18n catalog)
 
 ### Behavior Props
-- **closeOnEscape**: boolean (default: true) - Close when Escape key is pressed
-- **closeOnClickOutside**: boolean (default: true) - Close when clicking outside dialog
+- **closeOnEscape**: boolean (default: true) - Close when Escape key is pressed (and, for a modal dialog on Android, on the Back gesture)
+- **closeOnClickOutside**: boolean (default: true, false for \`type="alert"\` and for \`modal={false}\`) - Close when pressing outside dialog. A press that began before the dialog opened does not count
 - **closable**: boolean (default: true) - Whether dialog can be closed
-- **swipeToDismiss**: boolean (default: true for drawer types) - Drag the drawer toward its edge to dismiss. Direction-aware (drawerRight drags right, drawerBottom drags down, etc.) and never hijacks inner scrolling; opt elements out with \`data-no-swipe\`
+- **focusOnClose**: boolean | HTMLElement | ((details) => HTMLElement | boolean | void) (default: true) - Where focus goes when the dialog closes. \`true\` returns it to the control that opened the dialog, else to the most recent element still on the page; \`false\` leaves focus alone; an element receives it; a function gets the change details (\`reason\`, \`interaction\`…) and returns one of these, or nothing to restore as usual
+- **swipeToDismiss**: boolean (default: true for drawer types) - Drag the drawer toward its edge to dismiss. Direction-aware (drawerRight drags right, drawerBottom drags down, etc.) and never hijacks inner scrolling (including a horizontal scroller in a right-to-left layout) or a mostly sideways drag (a press that travels more across the dismiss axis than along it is spent); a quick flick dismisses even when the last move before release is nearly stationary; opt elements out with \`data-no-swipe\`. A mouse or pen drags a drawer only from its handles (thumb and header), so dragging over the body selects text; a finger drags from anywhere unless text is selected in the panel, buttons and links included (a field, a select or a media element keeps its own gesture, and a tap stays a tap). A dialog above another one keeps the one beneath moving with it: its scale and fade follow the swipe's progress
 - **thumb**: boolean (default: true) - Drag thumb bar shown on swipe-dismissable drawers (inner edge, orientation follows the drawer side, oversized hitbox); set false to hide. Themeable via the \`thumb\` theme part
 - **inset**: a spacing step or \`'none'\` — how far a drawer stands off the screen edge for this dialog. Defaults to the theme's \`designTokens.drawerInset\` (\`'layout-md'\`). At \`'none'\` the drawer is edge to edge, its edge corners square off and only the corners facing the page stay rounded
-- **swipeFrom**: 'panel' | 'handle' (default: 'panel') - Where a swipe can start: anywhere on the panel, or only the drag handles (thumb and header)
+- **swipeFrom**: 'panel' | 'handle' (default: 'panel') - Where a finger swipe can start: anywhere on the panel, or only the drag handles (thumb and header). Mouse and pen always start from a handle
+- **snapPoints**: (number | string)[] - Where a \`drawerBottom\` or \`drawerTop\` (or a modal collapsed into a mobile sheet) can rest. A number is a fraction of the available height (above 0, at most 1), a string a CSS length (\`'148px'\`, \`'20rem'\`, \`'40%'\`, \`'50vh'\`). The panel is as tall as the largest point and shows only the active one; a drag moves it between the points, a flick (0.4 px/ms or more) carries it to the next one in the direction it was thrown, and dragging below the lowest dismisses it when swipe-to-dismiss is on (otherwise the lowest is as far as it goes). The body scrolls only at the largest point; below it, a drag anywhere moves the panel. Ignored by the other types
+- **snapPoint**: number | string (bindable) - The point the drawer rests at, one of \`snapPoints\`
+- **defaultSnapPoint**: number | string - The point it opens at when \`snapPoint\` is not bound (default: the largest)
+- **onSnapPointChange**: ({ snapPoint, details }: { snapPoint; details: OpenChangeDetails }) => void - Called before the resting point changes. \`details.reason\` is \`'swipe'\` or \`'imperative-action'\` (\`dialog.setSnapPoint\`); \`details.cancel()\` keeps the current point and a cancelled drag snaps back
 
 ### Visual Props
 - **transition**: TransitionConfig - Custom transition animation
@@ -106,8 +112,113 @@ The Dialog component (also known as Modal) displays content in a layer above the
 <Dialog bind:open title="Welcome">
 	<p>This is a basic dialog.</p>
 	
+	<!-- {@attach dialog.trigger} opens the dialog on click (Enter/Space on a non-control) and
+	     keeps aria-haspopup / aria-expanded / aria-controls in sync; focus returns to it -->
 	{#snippet trigger(dialog)}
-		<Button onclick={() => dialog.open()}>Open</Button>
+		<Button {@attach dialog.trigger}>Open</Button>
+	{/snippet}
+</Dialog>
+\`\`\`
+
+### Choose where focus goes on close
+
+\`\`\`svelte
+<script lang="ts">
+	import { Dialog } from './index.ts';
+
+	let search = $state<HTMLInputElement | null>(null);
+</script>
+
+<input bind:this={search} aria-label="Search" />
+<!-- After a save, focus the search field instead of the button that opened the dialog. -->
+<Dialog
+	title="Rename"
+	trigger={{ content: 'Rename' }}
+	focusOnClose={(details) => (details?.reason === 'close-press' ? search : undefined)}
+>
+	<p>New name</p>
+</Dialog>
+\`\`\`
+
+### Cancel a close
+
+\`\`\`svelte
+<script lang="ts">
+	import { Dialog } from './index.ts';
+	import type { OpenChangeDetails } from '../../types/index.ts';
+
+	let draft = $state('');
+	// Runs before the change: with a draft, only the close button closes the dialog.
+	const keepDraft = (open: boolean, details: OpenChangeDetails) => {
+		if (!open && draft && details.reason !== 'close-press') details.cancel();
+	};
+</script>
+
+<Dialog title="New message" trigger={{ content: 'Write' }} onOpenChange={keepDraft}>
+	<textarea aria-label="Message" bind:value={draft}></textarea>
+</Dialog>
+\`\`\`
+
+### Ask before closing
+
+\`\`\`svelte
+<script lang="ts">
+	import { Dialog } from './index.ts';
+	import { confirmation } from '../Confirmation/index.ts';
+	import type { OpenChangeDetails } from '../../types/index.ts';
+
+	let open = $state(false);
+	let draft = $state('');
+
+	// Escape, an outside press, the close button, a swipe and Android Back all arrive here.
+	const askBeforeClosing = (nextOpen: boolean, details: OpenChangeDetails) => {
+		if (nextOpen || !draft) return;
+		details.cancel();
+		confirmation({
+			title: 'Discard this draft?',
+			description: 'Your changes will be lost.',
+			confirm: { text: 'Discard', color: 'danger' },
+			cancel: 'Keep editing'
+		}).then(({ confirmed }) => {
+			if (!confirmed) return;
+			draft = '';
+			open = false;
+		});
+	};
+</script>
+
+<Dialog type="drawerRight" title="New message" bind:open onOpenChange={askBeforeClosing}>
+	<textarea aria-label="Message" bind:value={draft}></textarea>
+</Dialog>
+\`\`\`
+
+### Non-modal
+
+\`\`\`svelte
+<Dialog modal={false} type="drawerRight" title="Inspector" trigger={{ content: 'Open inspector' }}>
+	<p>The page behind stays interactive.</p>
+</Dialog>
+\`\`\`
+
+### Snap points
+
+\`\`\`svelte
+<script lang="ts">
+	import { Dialog } from './index.ts';
+
+	let snapPoint = $state<number | string>(0.3);
+</script>
+
+<Dialog
+	type="drawerBottom"
+	title="Snap points"
+	snapPoints={[0.3, 0.6, 1]}
+	bind:snapPoint
+	onSnapPointChange={({ snapPoint, details }) => console.log(snapPoint, details.reason)}
+	trigger={{ content: 'Open sheet' }}
+>
+	{#snippet children(dialog)}
+		<button onclick={() => dialog.setSnapPoint(1)}>Expand</button>
 	{/snippet}
 </Dialog>
 \`\`\`
@@ -264,22 +375,84 @@ size:"small"
 
 ## State Management
 
-The Dialog component uses a \`DialogState\` instance that is passed to all slot snippets. This state object provides:
+The \`trigger\` and \`children\` snippets, \`onAfterOpen\` and \`onAfterClose\` receive a \`DialogApi\` (\`import type { DialogApi } from './index.ts'\`). It is a narrow handle: the class behind it stays internal, so its layer, focus scope and swipe machinery can change without breaking you. It provides:
+
+- **id**: string - Dialog identifier, which the open trigger's \`aria-controls\` points at
+- **isOpen**: boolean - Whether the dialog is open
+- **status**: 'closed' | 'entering' | 'open' | 'exiting' - Where the dialog is in its open/close lifecycle
+- **modal**: boolean - Whether the dialog is modal
+- **computedType**: DialogType - The type resolved for the current viewport, after the mobile sheet collapse
+- **open(details?)**, **close(details?)**, **toggle(details?)** - Request a change through \`onOpenChange\`; each accepts the DOM event or partial details (\`{ reason, event }\`), and reports \`'imperative-action'\` unless a trigger press is dispatching
+- **setOpen(open, details?)**: boolean - The same request with an explicit state; returns \`false\` when \`onOpenChange\` cancelled it
+- **setSnapPoint(point, details?)**: boolean - Moves a snap-point drawer to one of its \`snapPoints\` (or the nearest to \`point\`) through \`onSnapPointChange\`; returns \`false\` when it did not move
+- **currentSnapPoint**: number | string | undefined - The point the drawer rests at, as written in \`snapPoints\`
+- **triggerProps**: { haspopup, expanded, controls } - The trigger state in the library's semantic vocabulary, to spread on a Button; \`trigger\` and \`reference\` already write it as ARIA attributes
+- **trigger**: attachment that makes any element the dialog's trigger (\`{@attach dialog.trigger}\`): \`reference\`, plus a click that opens the dialog and, on a non-control, \`role="button"\`, \`tabindex="0"\` and Enter/Space activation. The element's own handler runs first; \`event.preventDefault()\` there stops it
+- **reference**: attachment that keeps a custom trigger's \`aria-haspopup\`, \`aria-expanded\` and \`aria-controls\` in sync and makes it the element focus returns to, leaving clicks to the element
+
+## Styling hooks
+
+The root, the panel, the trigger and the shared backdrop carry state attributes, so a theme or a \`class\` can style each phase without reading component state.
+
+Attributes are presence attributes (set while the state holds, omitted otherwise) unless they carry a value.
 
-- **id**: string - Dialog identifier
-- **type**: DialogType - Current dialog type
-- **size**: Size - Current dialog size
-- **open()**: () => void - Method to open the dialog
-- **close()**: () => void - Method to close the dialog
+**Data attributes**
+- \`data-open\`: On the root (\`role="dialog"\`), the panel and the shared backdrop: present while open.
+- \`data-closed\`: On the root, the panel and the backdrop: present while their exit transition plays (a closed dialog is not rendered).
+- \`data-entering\`: On the root and the panel: present while the enter transition plays.
+- \`data-exiting\`: On the root and the panel: present while the exit transition plays.
+- \`data-type\`: On the root and the panel: the type actually shown (\`modal\`, \`drawerBottom\`, ...), after responsive records and the mobile-sheet fallback resolve.
+- \`data-modal\`: On the root: \`true\` or \`false\`, whether the dialog is modal.
+- \`data-popup-open\`: On the trigger (the built-in button, or an element with \`dialog.trigger\` / \`dialog.reference\`): present while the dialog is open.
+- \`data-dialog-open\`: On \`<html>\`: present while at least one modal dialog is open.
+
+**CSS variables**
+- \`--dialog-depth\`: On \`<html>\`: how many modal dialogs are open (\`1\` for a single sheet), for pages that scale back behind a sheet.
+- \`--drawer-inset\`: On the root: the gap between a drawer and the screen edge, from the \`inset\` prop or the theme.
+- \`--drawer-edge-radius\`: On a drawer's panel: the radius of its screen-edge corners, \`0\` while it touches the edge.
+
+The typed maps \`dialogDataAttributes\` and \`dialogCssVariables\` (from \`entasis/dialog\`) list each name with its meaning.
+
+\`\`\`svelte
+<script>
+	import { Dialog } from './index.ts';
+</script>
+
+<!-- Fade the trigger while its dialog is open -->
+<Dialog trigger={{ content: 'Open', class: 'data-popup-open:opacity-60' }} title="Settings">…</Dialog>
+\`\`\`
 
 ## Accessibility
 
 - Initial focus goes to an \`[autofocus]\` / \`[data-autofocus]\` element inside the dialog, else the first tabbable control (the close button is skipped), else the panel itself
 - Tab and Shift+Tab are contained inside the dialog, and the rest of the page is \`inert\` while a modal is open
-- Focus is restored to the opener after the close transition finishes, just before \`onAfterClose\`
+- Focus is restored to the opener after the close transition finishes, just before \`onAfterClose\`: the trigger that opened it, else the element focused when it opened. When that element is gone or disabled (a menu item that opened the dialog), focus goes to the last element that had it inside the dialog beneath this one, else to the most recent element still on the page. A close by Escape or from the keyboard returns focus with a visible focus ring, and in Safari a focused text field is blurred before it unmounts so the page does not jump. \`focusOnClose\` overrides all of this
+- When a dialog (a Confirmation, say) closes over another dialog, the one beneath keeps focus where it was and receives it back from the closing one; it does not move focus to its first field again
+- Tab moves focus inside the dialog itself instead of leaving it to the browser, so it wraps in Safari too, where Tab skips buttons by default
+- The trigger (built-in, or a snippet element with \`{@attach dialog.trigger}\`) carries \`aria-haspopup="dialog"\`, \`aria-expanded\` and \`aria-controls\` pointing at the open dialog
+- On Android, the Back gesture closes the topmost modal dialog (not a \`modal={false}\` one) through a \`CloseWatcher\` (\`reason: 'close-watcher'\`), under the same rules as Escape
 - \`aria-labelledby\` links the \`title\` and \`aria-describedby\` links the \`description\`
+- The root is \`role="dialog"\`, or \`role="alertdialog"\` for \`type="alert"\`, always with \`aria-modal="true"\`
+- The root and the panel carry \`data-type\` with the resolved type (a responsive record or a modal collapsed into a mobile sheet reports the type actually shown), which drawer edge rounding keys on
+- A closable dialog whose visible close button is suppressed has a visually hidden \`Close\` button (\`tabindex="-1"\`) at the end of the panel for a screen reader's virtual cursor; the default close button is named \`Close\`
+- Every way out of a dialog (Escape, an outside press, the close button, a swipe, Android Back) goes through \`onOpenChange\` with its \`reason\` before anything changes, so \`details.cancel()\` can hold any of them back; a cancelled swipe snaps back with no exit animation
 - Escape closes only the topmost open layer and an outside press dismisses the layers above the one pressed; both honour \`closeOnEscape\` / \`closable\` / \`closeOnClickOutside\` through the shared layer stack
-- Body scroll is locked when dialog is open
+- Page scroll is locked while a dialog is open: \`data-entasis-scroll-lock\` on \`<html>\` (the Tailwind plugin turns it into \`overflow: hidden\`, so a lock another library holds is never overwritten) and \`--entasis-scrollbar-width\` with the hidden scrollbar's width, for \`position: fixed\` headers that must not jump. A page with \`scrollbar-gutter: stable\` gets no second gutter
+
+## Indent effect
+
+While at least one modal dialog is open, \`<html>\` carries the \`data-dialog-open\` attribute and the \`--dialog-depth\` custom property (the number of open modal dialogs, \`1\` for a single sheet). A page can scale back behind a sheet with plain CSS:
+
+\`\`\`css
+.app-shell { transition: transform 300ms ease; transform-origin: 50% 0; }
+html[data-dialog-open] .app-shell { transform: scale(calc(1 - var(--dialog-depth) * 0.04)); }
+\`\`\`
+
+Non-modal dialogs do not set them.
+
+## On-screen keyboard
+
+In a \`drawerBottom\` (or a modal collapsed into a mobile sheet), while a text field inside the panel has focus the sheet stays inside the part of the screen the keyboard leaves visible: its bottom padding grows by \`--keyboard-inset\` (the height the keyboard covers) and its top padding by \`--visual-viewport-top\` (how far iOS scrolled the page to show the field), both published on \`<html>\` by the Theme. The panel sits on the keyboard and shrinks to the room above it, and once the visual viewport has stopped moving the field is centered by scrolling the dialog's own scroll containers, never the page. On iOS the Theme also keeps Safari from zooming into a focused field (see Theme). Focus moving from one field to the next never lets the sheet drop in between. Browsers that resize the layout viewport for the keyboard (Chrome on Android only with \`interactive-widget=resizes-content\` in the viewport meta tag) report no inset and need no help; by default Chrome on Android reports the inset and the sheet uses it, like iOS.
 
 ## Notes
 

package/dist/components/Dialog/dialog.props.d.ts

@@ -1,65 +1,149 @@
 import type { SpacingStep } from '../../tailwind/spacing.js';
 import type { Snippet } from 'svelte';
-import type { WithSlot } from '../Slot/slot.js';
-import type { DialogState } from './dialog.state.svelte.js';
+import type { Slot, WithSlot } from '../Slot/slot.js';
+import type { DialogApi } from './dialog.api.js';
 import type { ResponsiveProps } from '../Theme/theme.js';
 import type { Sizes } from '../../types/theme.js';
 import type { ButtonProps } from '../Button/index.js';
 import type { FSOProps } from '../../transitions/transition.js';
 import type { DialogThemeProps } from './dialog.theme.js';
+import type { OpenChangeDetails, OpenChangeHandler } from '../../utils/openChange.js';
+import type { FocusOnClose } from '../../utils/useFocusScope.svelte.js';
 export type DialogType = 'fullScreen' | 'drawerRight' | 'drawerLeft' | 'drawerBottom' | 'drawerTop' | 'alert' | 'modal';
+/**
+ * A drawer snap point: how much of the drawer shows when it rests there. A number is a fraction
+ * of the available height (`0.5` is half of it), a string a CSS length (`'148px'`, `'20rem'`,
+ * `'40%'`, `'50vh'`).
+ */
+export type DialogSnapPoint = number | string;
 export type DialogProps = WithSlot<{
     /** Stable DOM id for the portaled dialog root; falls back to a generated id when omitted. */
     id?: string;
     /** Presentation variant (modal, alert, fullScreen, or edge drawer); supports responsive
-     *  values — pass a `{ xs: 'drawerBottom', md: 'modal' }` record for per-breakpoint control. */
+     *  values — pass a `{ xs: 'drawerBottom', md: 'modal' }` record for per-breakpoint control.
+     *  An `alert` renders `role="alertdialog"` and ignores outside presses by default. The
+     *  resolved type is exposed as `data-type` on the root and the panel. */
     type?: ResponsiveProps<DialogType>;
     /** When the resolved type is `modal`, collapse it into a bottom-sheet drawer on mobile
      *  (viewport < 768px), inheriting swipe-to-dismiss and the drag thumb. Default `true`. */
     responsive?: boolean;
+    /**
+     * Whether the dialog is modal (default `true`): it makes the page behind `inert`, locks page
+     * scroll, contains Tab, dims the page with the shared backdrop and dismisses on an outside
+     * press. `false` leaves the page interactive: no `inert`, no scroll lock, no backdrop, no
+     * focus containment, and an outside press does not dismiss it unless `closeOnClickOutside`
+     * is set. Escape, the close button and swipes still close it. It renders no `aria-modal`
+     * (an alert stays an `alertdialog`). A non-modal dialog always scrolls inside its card.
+     */
+    modal?: boolean;
     /** Controls whether the dialog is rendered; bindable for two-way control. */
     open?: boolean;
     /** Initial open state when `open` is not provided. */
     defaultOpen?: boolean;
-    /** Called once when the library requests an open-state change. */
-    onOpenChange?: (open: boolean) => void;
-    /** Called after the open transition finishes. */
-    onAfterOpen?: (payload: DialogState) => void;
-    /** Called after the close transition finishes. */
-    onAfterClose?: (payload: DialogState) => void;
+    /**
+     * Called before the dialog opens or closes, with the requested state and the change
+     * details: `reason` (`'trigger-press'`, `'escape-key'`, `'outside-press'`, `'close-press'`,
+     * `'swipe'`, `'close-watcher'` for the Android Back gesture, `'imperative-action'`…), the
+     * originating `event`, the `trigger` element, the `interaction` type and `cancel()`.
+     * Calling `details.cancel()` keeps the dialog as it is (a cancelled swipe snaps back) and
+     * leaves the event untouched. Inside the callback, `open` still holds the previous state.
+     */
+    onOpenChange?: OpenChangeHandler;
+    /** Called once per open, after the open transition finishes (right away when none plays). */
+    onAfterOpen?: (payload: DialogApi) => void;
+    /** Called once per close, after the close transition finishes. */
+    onAfterClose?: (payload: DialogApi) => void;
     /** Content max-width for modal and alert types; supports responsive values. */
     size?: ResponsiveProps<Sizes>;
     /** Where a dialog taller than the viewport scrolls: inside the card (`inner`, default) or the viewport (`outer`). */
     scroll?: ResponsiveProps<'inner' | 'outer'>;
     /** Fly/scale opacity transition overrides for open and close; supports responsive values. */
     transition?: ResponsiveProps<FSOProps>;
-    /** Snippet for main dialog body content; receives the dialog state instance. */
-    children?: Snippet<[DialogState]>;
-    /** Snippet or button props that render the control used to open the dialog. */
-    trigger?: Snippet<[DialogState]> | (ButtonProps & {
+    /**
+     * Where focus goes when the dialog closes. By default it returns to the control that
+     * opened the dialog (with a visible focus ring after Escape or another keyboard close);
+     * when that control is gone or disabled, to the most recent element that is still on the
+     * page. `false` leaves focus where it is, an element receives it, and a function is called
+     * with the change details (`reason`, `interaction`…) and returns one of these, or nothing
+     * to restore as usual.
+     * @default true
+     */
+    focusOnClose?: FocusOnClose;
+    /**
+     * Where a bottom or top drawer (or a mobile sheet) can rest, from the least to the most of
+     * it showing: fractions of the available height or CSS lengths. With snap points the
+     * drawer opens at `defaultSnapPoint` (the largest by default), a drag moves it between the
+     * points (a flick carries it to the next), and dragging below the lowest one dismisses it
+     * when swipe-to-dismiss is on. Its body scrolls only at the largest point. Ignored by the
+     * other types.
+     */
+    snapPoints?: DialogSnapPoint[];
+    /**
+     * The snap point the drawer rests at: one of `snapPoints`, bindable. Without it the drawer
+     * manages its own, starting at `defaultSnapPoint`.
+     */
+    snapPoint?: DialogSnapPoint;
+    /** The snap point the drawer opens at when `snapPoint` is not bound. Defaults to the largest. */
+    defaultSnapPoint?: DialogSnapPoint;
+    /**
+     * Called before the resting snap point changes, with `{ snapPoint, details }`: the new point
+     * and the change details (`reason` is `'swipe'` for a drag and `'imperative-action'` for
+     * `setSnapPoint`; `details.cancel()` keeps the current point and a cancelled drag snaps back).
+     */
+    onSnapPointChange?: (payload: {
+        snapPoint: DialogSnapPoint;
+        details: OpenChangeDetails;
+    }) => void;
+    /** Snippet for main dialog body content; receives the dialog (`DialogApi`). */
+    children?: Snippet<[DialogApi]>;
+    /**
+     * Snippet or button props that render the control used to open the dialog. The built-in
+     * button carries `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`, and its
+     * `onclick` runs first: calling `event.preventDefault()` there keeps the dialog closed. A
+     * snippet trigger gets the same contract with `{@attach dialog.trigger}`; focus returns to
+     * the trigger when the dialog closes.
+     */
+    trigger?: Snippet<[DialogApi]> | (ButtonProps & {
         content?: string;
     });
     /** When true, shows a close button and allows Escape to close the dialog. */
     closable?: boolean;
-    /** When true, clicking outside the dialog panel closes the topmost open dialog. */
+    /** When true, pressing outside the dialog panel closes the topmost open dialog. Defaults to
+     *  `true`, except for an `alert`, which ignores outside presses unless this is set. A press
+     *  that began before the dialog opened does not count. */
     closeOnClickOutside?: boolean;
-    /** When true, pressing Escape closes the dialog when it is closable and topmost. */
+    /** When true, pressing Escape (and, for a modal dialog on Android, the Back gesture) closes
+     *  the dialog when it is closable and topmost. */
     closeOnEscape?: boolean;
     /** Drag the panel toward its edge to dismiss (drawer types only). Defaults to true for drawers.
      *  Direction-aware, and never hijacks inner scrolling — a scrollable region that can still
-     *  scroll along the drag axis keeps the gesture. Opt elements out with `data-no-swipe`. */
+     *  scroll along the drag axis keeps the gesture (right-to-left scrollers included), and so
+     *  does a drag that travels more across the axis than along it. A flick dismisses on release
+     *  speed alone. A mouse or pen drags only from the handles (the thumb and the header), so
+     *  dragging over the body selects text; a finger drags from anywhere unless text is selected
+     *  in the panel, buttons and links included (a field, a select or a media element keeps its
+     *  own gesture). Opt elements out with `data-no-swipe`. A dialog above another keeps the one
+     *  beneath moving with its swipe. */
     swipeToDismiss?: boolean;
     /** Show the drag thumb bar on swipe-dismissable drawers; set false to hide. Default true. */
     thumb?: boolean;
-    /** Where a swipe can start: the whole panel (`panel`, default) or only the drag handles
-     *  (`handle` — the thumb and the header). */
+    /** Where a finger swipe can start: the whole panel (`panel`, default) or only the drag
+     *  handles (`handle` — the thumb and the header). A mouse or pen always starts from a handle. */
     swipeFrom?: 'panel' | 'handle';
     /** How far a drawer stands off the screen edge: a spacing step or `'none'` for edge to edge.
      *  Defaults to the theme's `designTokens.drawerInset` (`'layout-md'`). At `'none'` the edge
      *  corners square off and only the corners facing the page keep their radius. */
     inset?: SpacingStep | 'none';
+    /**
+     * Replaces the close button, or `false` to suppress the visible one. A closable dialog whose
+     * visible button is suppressed (`false`, or a snippet that renders nothing, as the Popover
+     * mobile sheet passes) still gets a visually hidden Close button at the end of the panel, so
+     * screen reader users have a control that closes it. An `alert` never gets one: its own
+     * buttons answer it.
+     */
+    closeButton?: Slot | false;
     /** Additional CSS classes merged onto the portaled dialog root element. */
     class?: string;
     /** Per-instance theme overrides for dialog layout and styling class names. */
     theme?: DialogThemeProps;
-}, 'title' | 'description' | 'footer' | 'header' | 'closeButton'>;
+}, 'title' | 'description' | 'footer' | 'header'>;

package/dist/components/Dialog/dialog.snap.d.ts

@@ -0,0 +1,40 @@
+import type { DialogSnapPoint } from './dialog.props.js';
+/** A snap point and how much of the drawer shows when it rests there, in px. */
+export type ResolvedSnapPoint = {
+    /** The point as the consumer wrote it; this is what `snapPoint` and `onSnapPointChange` carry. */
+    point: DialogSnapPoint;
+    /** Height of the drawer that shows at this point, in px. */
+    height: number;
+};
+/** What a snap point is measured against. */
+export type SnapContext = {
+    /** Height in px the drawer may use: the positioner's content box. */
+    available: number;
+    /** Height of the viewport in px, for `vh` lengths. */
+    viewport: number;
+    /** Font size of the root element in px, for `rem` and `em` lengths. */
+    rem: number;
+};
+/** Release speed in px/ms from which a drag is a flick, the same rule as dismissing a drawer. */
+export declare const FLICK_SPEED = 0.4;
+/**
+ * The visible height of a snap point in px, `NaN` when it is not valid. A number is a fraction of
+ * the available height (above 0, at most 1); a string is a CSS length: `px`, `rem`, `em`, `%` (of
+ * the available height) or `vh`.
+ */
+export declare function snapPointHeight(point: DialogSnapPoint, context: SnapContext): number;
+/**
+ * The snap points as px heights, from the lowest to the highest. Invalid points are dropped, a
+ * point taller than the available room is clamped to it, and points that land on the same pixel
+ * keep the first one written.
+ */
+export declare function resolveSnapPoints(points: readonly DialogSnapPoint[] | undefined, context: SnapContext): ResolvedSnapPoint[];
+/**
+ * Where a released drag rests. `height` is how much of the drawer shows when the pointer lifts and
+ * `velocity` its speed toward dismissal in px/ms (positive shrinks the drawer). A flick (at least
+ * `FLICK_SPEED`) carries the drawer to the next point in the direction it was thrown, past the
+ * lowest one to closed; a slower release rests at the nearest point, closed counting as a point
+ * with a height of 0. Without `allowClose`, closed is never the answer. Returns the index into
+ * `heights` (ascending), or `-1` to close. A tie keeps the drawer open and as large as possible.
+ */
+export declare function settleSnapIndex(heights: readonly number[], height: number, velocity: number, allowClose: boolean): number;

package/dist/components/Dialog/dialog.snap.js

@@ -0,0 +1,78 @@
+const LENGTH = /^\s*(\d*\.?\d+)\s*(px|rem|em|%|vh|dvh|svh|lvh)?\s*$/i;
+/** Release speed in px/ms from which a drag is a flick, the same rule as dismissing a drawer. */
+export const FLICK_SPEED = 0.4;
+/**
+ * The visible height of a snap point in px, `NaN` when it is not valid. A number is a fraction of
+ * the available height (above 0, at most 1); a string is a CSS length: `px`, `rem`, `em`, `%` (of
+ * the available height) or `vh`.
+ */
+export function snapPointHeight(point, context) {
+    if (typeof point === 'number') {
+        return point > 0 && point <= 1 ? point * context.available : Number.NaN;
+    }
+    const match = LENGTH.exec(point);
+    if (!match)
+        return Number.NaN;
+    const value = parseFloat(match[1]);
+    const unit = (match[2] ?? 'px').toLowerCase();
+    if (unit === 'px')
+        return value;
+    if (unit === 'rem' || unit === 'em')
+        return value * context.rem;
+    if (unit === '%')
+        return (value / 100) * context.available;
+    return (value / 100) * context.viewport;
+}
+/**
+ * The snap points as px heights, from the lowest to the highest. Invalid points are dropped, a
+ * point taller than the available room is clamped to it, and points that land on the same pixel
+ * keep the first one written.
+ */
+export function resolveSnapPoints(points, context) {
+    if (!points?.length || !(context.available > 0))
+        return [];
+    const resolved = [];
+    for (const point of points) {
+        const height = Math.min(snapPointHeight(point, context), context.available);
+        if (!Number.isFinite(height) || height <= 0)
+            continue;
+        if (resolved.some((other) => Math.abs(other.height - height) < 0.5))
+            continue;
+        resolved.push({ point, height });
+    }
+    return resolved.sort((a, b) => a.height - b.height);
+}
+/**
+ * Where a released drag rests. `height` is how much of the drawer shows when the pointer lifts and
+ * `velocity` its speed toward dismissal in px/ms (positive shrinks the drawer). A flick (at least
+ * `FLICK_SPEED`) carries the drawer to the next point in the direction it was thrown, past the
+ * lowest one to closed; a slower release rests at the nearest point, closed counting as a point
+ * with a height of 0. Without `allowClose`, closed is never the answer. Returns the index into
+ * `heights` (ascending), or `-1` to close. A tie keeps the drawer open and as large as possible.
+ */
+export function settleSnapIndex(heights, height, velocity, allowClose) {
+    if (Math.abs(velocity) >= FLICK_SPEED) {
+        if (velocity > 0) {
+            for (let index = heights.length - 1; index >= 0; index -= 1) {
+                if (heights[index] < height - 0.5)
+                    return index;
+            }
+            return allowClose ? -1 : 0;
+        }
+        for (let index = 0; index < heights.length; index += 1) {
+            if (heights[index] > height + 0.5)
+                return index;
+        }
+        return heights.length - 1;
+    }
+    let best = -1;
+    let bestDistance = allowClose ? Math.abs(height) : Number.POSITIVE_INFINITY;
+    for (let index = 0; index < heights.length; index += 1) {
+        const distance = Math.abs(height - heights[index]);
+        if (distance <= bestDistance) {
+            best = index;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}