@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/dialog/engine.ts

@@ -1,432 +1,449 @@
-import { gsap, EASE, registerMotion } from '../../core/gsap';
-import { reduced } from '../../core/reduced';
-import { createScope } from '../../core/scope';
-import { TIMING } from '../../core/timing';
-import { inert, warnOnce, type Cleanup, type Instance } from '../../core/types';
-import { MORPH_STYLES, clearStyles } from '../../core/styles';
-import { anchorSurface, clearAnchor } from '../../motion/anchor';
-import { attachDragDismiss } from '../../motion/drag-dismiss';
-import {
-  attachFloating,
-  dockWindow,
-  floatingAvailable,
-  forgetFloat,
-  liftWindow,
-  savedFloat,
-  unplaceWindow,
-} from '../../motion/floating';
-import { isMorphing, morphCloseWithGhost, morphOpen, releaseShared, showOrigin, stopMorph } from '../../motion/morph';
-import { pushUnderlay, releaseUnderlay, sheetClose, sheetOpen } from '../../motion/sheet';
-import { closeModal, fadeBackdrop, openModal } from '../../motion/surface';
-
-/*
- * Dialog on a native <dialog> (focus trap, Escape, top layer): the
- * control that opened it turns into it and it folds back into that control
- * (morph or liquid) over a backdrop tinted on the signature curve. It eases to
- * new heights (auto-resize), can be dragged away (> 100 px) and, on desktop,
- * lifted into a floating window by its handle. Parts: [data-mk-part] header,
- * title, description, body, footer, close, handle.
- */
-
-export type DialogVariant = 'morph' | 'liquid' | 'sheet';
-export type DialogPlacement = 'center' | 'anchor' | 'side';
-
-export interface DialogLabels {
-  close?: string;
-  float?: string;
-  dock?: string;
-}
-
-export interface DialogOptions {
-  /** morph (default), liquid, or sheet: rises from the bottom and pushes [data-mk-underlay] back. */
-  variant?: DialogVariant;
-  placement?: DialogPlacement;
-  /** Tinted backdrop; false leaves it transparent (menus). */
-  backdrop?: boolean;
-  closeOnBackdrop?: boolean;
-  /** Drag (or wheel) down to dismiss. */
-  drag?: boolean;
-  /** A key turns on the floating window (desktop) and remembers its place. */
-  float?: string | false;
-  autoResize?: boolean;
-  /** `[data-mk-open="<id>"]` buttons open it: true uses the dialog's id; a string names another id; false: none. */
-  triggers?: boolean | string;
-  /** Modal (default) or a non-modal dialog. */
-  modal?: boolean;
-  labels?: DialogLabels;
-  /** Grow the content with the surface (default). Menus turn it off and cascade their items instead. */
-  animateContent?: boolean;
-  onOpen?: () => void;
-  /** After it closed, whatever closed it. */
-  onClose?: () => void;
-}
-
-export interface DialogInstance extends Instance {
-  /** `origin`: the control it grows from; omitted, the focused control; null, none (scale-in). */
-  open(origin?: HTMLElement | null): void;
-  close(): void;
-  toggle(origin?: HTMLElement | null): void;
-  float(): void;
-  dock(): void;
-  readonly isOpen: boolean;
-  readonly isFloating: boolean;
-  readonly element: HTMLElement;
-}
-
-const DEFAULT_LABELS: Required<DialogLabels> = { close: 'Cerrar', float: 'Ventana flotante', dock: 'Volver a su sitio' };
-const FIELDS = '[autofocus], input:not([type="hidden"]):not(:disabled), textarea:not(:disabled), select:not(:disabled)';
-const CORNERS = ['tl', 'tr', 'bl', 'br'] as const;
-let uid = 0;
-
-const part = (dialog: HTMLElement, name: string) => dialog.querySelector<HTMLElement>(`[data-mk-part="${name}"]`);
-
-export function createDialog(dialog: HTMLElement | null, options: DialogOptions = {}): DialogInstance {
-  if (!dialog) {
-    warnOnce('dialog: missing <dialog> element');
-    return inert({ open() {}, close() {}, toggle() {}, float() {}, dock() {}, isOpen: false, isFloating: false, element: null as unknown as HTMLElement });
-  }
-  registerMotion();
-  const {
-    variant = 'morph',
-    placement = 'center',
-    backdrop = true,
-    closeOnBackdrop = true,
-    drag = true,
-    float: floatKey = false,
-    autoResize = true,
-    triggers = true,
-    modal = true,
-  } = options;
-  const labels = { ...DEFAULT_LABELS, ...options.labels };
-  const liquid = variant === 'liquid';
-  const sheet = variant === 'sheet';
-  const scope = createScope();
-  /** Effects that live while it is open. */
-  let session: Cleanup[] = [];
-  let opener: HTMLElement | null = null;
-  let isOpen = false;
-  let closing = false;
-  let floating = false;
-  /**
-   * Lifting and docking swap modal ↔ popover: the native `close` events they cause
-   * (queued, so they arrive later) are not the person closing it.
-   */
-  let ownCloses = 0;
-  const closeNatively = () => {
-    if (!dialog.hasAttribute('open')) return;
-    ownCloses += 1;
-    closeModal(dialog as HTMLDialogElement);
-  };
-  let destroyed = false;
-  /** destroy() is under way: the page behind comes back at once. */
-  let tearingDown = false;
-
-  if (placement !== 'center') scope.attr(dialog, 'data-mk-placement', placement);
-  if (!backdrop) scope.attr(dialog, 'data-mk-backdrop', 'none');
-  scope.attr(dialog, 'data-mk-variant', variant);
-  const title = part(dialog, 'title');
-  if (title && !dialog.hasAttribute('aria-label') && !dialog.hasAttribute('aria-labelledby')) {
-    if (!title.id) scope.attr(title, 'id', `mk-dialog-title-${++uid}`);
-    scope.attr(dialog, 'aria-labelledby', title.id);
-  }
-  const description = part(dialog, 'description');
-  if (description && !dialog.hasAttribute('aria-describedby')) {
-    if (!description.id) scope.attr(description, 'id', `mk-dialog-description-${++uid}`);
-    scope.attr(dialog, 'aria-describedby', description.id);
-  }
-  const closeButton = part(dialog, 'close');
-  if (closeButton && !closeButton.hasAttribute('aria-label') && !closeButton.textContent?.trim()) {
-    scope.attr(closeButton, 'aria-label', labels.close);
-  }
-  const handle = floatKey ? part(dialog, 'handle') : null;
-  if (handle) {
-    scope.attr(handle, 'data-mk-no-drag', '');
-    scope.attr(handle, 'aria-pressed', 'false');
-    scope.attr(handle, 'aria-label', labels.float);
-  }
-  const corners: HTMLElement[] = [];
-  if (floatKey) {
-    for (const corner of CORNERS) {
-      const element = document.createElement('span');
-      element.className = 'mk-float-corner';
-      element.dataset.mkFloatCorner = corner;
-      element.dataset.mkNoDrag = '';
-      element.setAttribute('aria-hidden', 'true');
-      dialog.append(element);
-      corners.push(element);
-    }
-    scope.add(() => corners.forEach((corner) => corner.remove()));
-  }
-
-  const emit = (type: string, cancelable = false, detail: Record<string, unknown> = {}) =>
-    dialog.dispatchEvent(new CustomEvent(type, { bubbles: true, cancelable, detail: { dialog, ...detail } }));
-
-  const endSession = () => {
-    for (const cleanup of session.splice(0).reverse()) cleanup();
-  };
-
-  const settleFloating = () => {
-    if (!floating) return;
-    floating = false;
-    if (typeof dialog.hidePopover === 'function' && dialog.hasAttribute('popover')) {
-      try {
-        dialog.hidePopover();
-      } catch {
-        // Already hidden.
-      }
-    }
-    dialog.removeAttribute('popover');
-    unplaceWindow(dialog);
-    if (handle) {
-      handle.setAttribute('aria-pressed', 'false');
-      handle.setAttribute('aria-label', labels.float);
-    }
-  };
-
-  /** Closed without our animation (owner, form[method=dialog], destroy). */
-  const closedQuietly = () => {
-    stopMorph(dialog);
-    endSession();
-    isOpen = false;
-    closing = false;
-    showOrigin(opener);
-    releaseShared(opener);
-    emit('mk:closed');
-    options.onClose?.();
-  };
-
-  const lift = () => {
-    if (!floatKey || floating || !isOpen || !floatingAvailable()) return;
-    const box = dialog.getBoundingClientRect();
-    const rect = savedFloat(floatKey) ?? { top: box.top, left: box.left, width: box.width, height: box.height };
-    const focused = document.activeElement;
-    // Its backdrop leaves as the window lifts off the page.
-    const backdropStyle = getComputedStyle(dialog, '::backdrop');
-    const veil = document.createElement('div');
-    veil.setAttribute('aria-hidden', 'true');
-    Object.assign(veil.style, {
-      position: 'fixed',
-      inset: '0',
-      background: backdropStyle.background || backdropStyle.backgroundColor,
-      backdropFilter: backdropStyle.backdropFilter,
-      pointerEvents: 'none',
-    });
-    closeNatively();
-    document.body.append(veil);
-    dialog.setAttribute('popover', 'manual');
-    if (typeof dialog.showPopover === 'function') dialog.showPopover();
-    else openModal(dialog, false);
-    liftWindow(dialog, rect);
-    gsap.to(veil, { opacity: 0, duration: reduced() ? 0 : TIMING.float.shadow, ease: EASE.signature, onComplete: () => veil.remove() });
-    floating = true;
-    if (handle) {
-      handle.setAttribute('aria-pressed', 'true');
-      handle.setAttribute('aria-label', labels.dock);
-    }
-    showOrigin(opener, { fade: true });
-    if (focused instanceof HTMLElement && dialog.contains(focused)) focused.focus();
-  };
-
-  const dock = () => {
-    if (!floatKey || !floating) return;
-    const box = dialog.getBoundingClientRect();
-    const focused = document.activeElement;
-    floating = false;
-    if (typeof dialog.hidePopover === 'function') dialog.hidePopover();
-    dialog.removeAttribute('popover');
-    closeNatively();
-    openModal(dialog, modal);
-    dockWindow(dialog, { top: box.top, left: box.left, width: box.width, height: box.height });
-    if (backdrop) void fadeBackdrop(dialog, 'in');
-    forgetFloat(floatKey);
-    if (handle) {
-      handle.setAttribute('aria-pressed', 'false');
-      handle.setAttribute('aria-label', labels.float);
-    }
-    if (focused instanceof HTMLElement && dialog.contains(focused)) focused.focus();
-  };
-
-  const startSession = () => {
-    if (sheet) {
-      const behind = [...document.querySelectorAll<HTMLElement>('[data-mk-underlay]')];
-      pushUnderlay(behind);
-      const root = document.documentElement;
-      const overflow = root.style.overflow;
-      root.style.overflow = 'hidden';
-      session.push(() => {
-        root.style.overflow = overflow;
-        if (root.getAttribute('style') === '') root.removeAttribute('style');
-        releaseUnderlay(behind, !tearingDown);
-      });
-    }
-    if (autoResize && typeof ResizeObserver === 'function') {
-      let last = dialog.offsetHeight;
-      let resizing: gsap.core.Tween | null = null;
-      const observer = new ResizeObserver(() => {
-        if (resizing?.isActive()) return;
-        const next = dialog.offsetHeight;
-        const previous = last;
-        last = next;
-        // A floating window's size is the person's, not its content's.
-        if (floating || Math.abs(next - previous) < 2 || !previous || isMorphing(dialog) || reduced()) return;
-        resizing = gsap.fromTo(
-          dialog,
-          { height: previous },
-          {
-            height: next,
-            duration: TIMING.dialog.autoResize,
-            ease: EASE.signature,
-            clearProps: 'height',
-            onComplete: () => {
-              last = dialog.offsetHeight;
-            },
-          },
-        );
-      });
-      observer.observe(dialog);
-      session.push(() => {
-        observer.disconnect();
-        resizing?.kill();
-        clearStyles([dialog], ['height']);
-      });
-    }
-    if (drag) {
-      session.push(
-        attachDragDismiss(dialog, {
-          canDrag: () => !isMorphing(dialog) && !floating && !closing && isOpen,
-          onDismiss: () => close(true),
-        }),
-      );
-    }
-    if (placement === 'anchor') {
-      const onResize = () => {
-        if (isOpen && !floating) anchorSurface(dialog, opener?.isConnected ? opener.getBoundingClientRect() : null);
-      };
-      addEventListener('resize', onResize);
-      session.push(() => {
-        removeEventListener('resize', onResize);
-        clearAnchor(dialog);
-      });
-    }
-    if (floatKey && handle) {
-      session.push(attachFloating(dialog, { key: floatKey, handle, corners, isFloating: () => floating, float: lift, dock }));
-      const onResize = () => {
-        if (floating && !floatingAvailable()) dock();
-      };
-      addEventListener('resize', onResize);
-      session.push(() => removeEventListener('resize', onResize));
-    }
-  };
-
-  const open = (origin?: HTMLElement | null) => {
-    if (destroyed || isOpen) return;
-    const active = document.activeElement;
-    // undefined: the focused control (usually the one clicked); null: no opener at all.
-    opener = origin !== undefined ? origin : active instanceof HTMLElement && active !== document.body && !dialog.contains(active) ? active : null;
-    closing = false;
-    isOpen = true;
-    openModal(dialog, modal);
-    if (placement === 'anchor') anchorSurface(dialog, opener?.getBoundingClientRect());
-    if (backdrop && modal) void fadeBackdrop(dialog, 'in');
-    if (sheet) sheetOpen(dialog);
-    else morphOpen(dialog, opener, { hideOrigin: true, liquid, content: options.animateContent === false ? ':scope > :not(*)' : undefined });
-    startSession();
-    // Forms start at their first field (after showModal: a closed dialog cannot take focus).
-    dialog.querySelector<HTMLElement>(FIELDS)?.focus({ preventScroll: true });
-    emit('mk:open', false, { origin: opener });
-    options.onOpen?.();
-  };
-
-  /** Animated close: the dialog closes at once while an inert copy folds into the opener. */
-  const close = (inPlace = false) => {
-    if (destroyed || !isOpen || closing) return;
-    if (!emit('mk:close', true, { inPlace })) return;
-    closing = true;
-    // The copy is measured first: the session cleanup clears an anchored place.
-    if (sheet) sheetClose(dialog, { inPlace });
-    else morphCloseWithGhost(dialog, opener, { inPlace, liquid });
-    endSession();
-    if (floating) settleFloating();
-    if (dialog.hasAttribute('open')) closeModal(dialog as HTMLDialogElement);
-    isOpen = false;
-    closing = false;
-    if (opener?.isConnected) opener.focus();
-    emit('mk:closed');
-    options.onClose?.();
-  };
-
-  scope.on(dialog, 'cancel', (event) => {
-    event.preventDefault();
-    close();
-  });
-  scope.on(dialog, 'close', () => {
-    if (ownCloses > 0) {
-      ownCloses -= 1;
-      return;
-    }
-    // A native close we did not start (form method="dialog", dialog.close()).
-    if (!isOpen || closing) return;
-    closedQuietly();
-  });
-  scope.on(dialog, 'keydown', (event) => {
-    // A floating (non-modal) window still closes with Escape.
-    if ((event as KeyboardEvent).key === 'Escape' && floating) {
-      event.preventDefault();
-      close();
-    }
-  });
-  scope.on(dialog, 'click', (event) => {
-    const target = event.target as Element | null;
-    if (target?.closest('[data-mk-part="close"], [data-mk-close]') && dialog.contains(target)) {
-      close();
-      return;
-    }
-    if (target !== dialog || !closeOnBackdrop || floating) return;
-    const mouse = event as MouseEvent;
-    const box = dialog.getBoundingClientRect();
-    if (mouse.clientX < box.left || mouse.clientX > box.right || mouse.clientY < box.top || mouse.clientY > box.bottom) close();
-  });
-  const triggerId = triggers === true ? dialog.id : triggers || '';
-  if (triggerId) {
-    const selector = `[data-mk-open="${typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(triggerId) : triggerId}"]`;
-    scope.on(document, 'click', (event) => {
-      const trigger = (event.target as Element | null)?.closest<HTMLElement>(selector);
-      if (!trigger || dialog.contains(trigger)) return;
-      event.preventDefault();
-      if (isOpen) close();
-      else open(trigger);
-    });
-  }
-  dialog.dataset.mkReady = '';
-
-  return {
-    open,
-    close: () => close(),
-    toggle: (origin?: HTMLElement | null) => (isOpen ? close() : open(origin)),
-    float: lift,
-    dock,
-    get isOpen() {
-      return isOpen;
-    },
-    get isFloating() {
-      return floating;
-    },
-    element: dialog,
-    destroy() {
-      if (destroyed) return;
-      tearingDown = true;
-      if (isOpen) {
-        settleFloating();
-        closing = true;
-        if (dialog.hasAttribute('open')) closeModal(dialog as HTMLDialogElement);
-        closedQuietly();
-      }
-      destroyed = true;
-      endSession();
-      gsap.killTweensOf(dialog);
-      clearStyles([dialog], [...MORPH_STYLES, 'height']);
-      scope.dispose();
-      delete dialog.dataset.mkReady;
-    },
-  };
-}
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Cleanup, type Instance } from '../../core/types';
+import { MORPH_STYLES, clearStyles } from '../../core/styles';
+import { anchorSurface, clearAnchor } from '../../motion/anchor';
+import { attachDragDismiss } from '../../motion/drag-dismiss';
+import {
+  attachFloating,
+  dockWindow,
+  floatingAvailable,
+  forgetFloat,
+  liftWindow,
+  savedFloat,
+  unplaceWindow,
+} from '../../motion/floating';
+import { isMorphing, morphCloseWithGhost, morphOpen, releaseShared, showOrigin, stopMorph } from '../../motion/morph';
+import { pushUnderlay, releaseUnderlay, sheetClose, sheetOpen, slideClose, slideOpen } from '../../motion/sheet';
+import { closeModal, fadeBackdrop, openModal } from '../../motion/surface';
+
+/*
+ * Dialog on a native <dialog> (focus trap, Escape, top layer): the
+ * control that opened it turns into it and it folds back into that control
+ * (morph or liquid) over a backdrop tinted on the signature curve. It eases to
+ * new heights (auto-resize), can be dragged away (> 100 px) and, on desktop,
+ * lifted into a floating window by its handle. Parts: [data-mk-part] header,
+ * title, description, body, footer, close, handle.
+ */
+
+/** drawer: slides in from its side (data-mk-drawer="left|right", see createDrawer). */
+export type DialogVariant = 'morph' | 'liquid' | 'sheet' | 'drawer';
+export type DialogPlacement = 'center' | 'anchor' | 'side';
+
+export interface DialogLabels {
+  close?: string;
+  float?: string;
+  dock?: string;
+}
+
+export interface DialogOptions {
+  /** morph (default), liquid, or sheet: rises from the bottom and pushes [data-mk-underlay] back. */
+  variant?: DialogVariant;
+  placement?: DialogPlacement;
+  /** placement 'anchor': the box to place it against, read on open and resize (default: the opener's). */
+  anchor?: () => DOMRect | null | undefined;
+  /** Tinted backdrop; false leaves it transparent (menus). */
+  backdrop?: boolean;
+  closeOnBackdrop?: boolean;
+  /** Drag (or wheel) down to dismiss. */
+  drag?: boolean;
+  /** A key turns on the floating window (desktop) and remembers its place. */
+  float?: string | false;
+  autoResize?: boolean;
+  /** `[data-mk-open="<id>"]` buttons open it: true uses the dialog's id; a string names another id; false: none. */
+  triggers?: boolean | string;
+  /** Modal (default) or a non-modal dialog. */
+  modal?: boolean;
+  labels?: DialogLabels;
+  /** Grow the content with the surface (default). Menus turn it off and cascade their items instead. */
+  animateContent?: boolean;
+  onOpen?: () => void;
+  /** After it closed, whatever closed it. */
+  onClose?: () => void;
+}
+
+export interface DialogInstance extends Instance {
+  /** `origin`: the control it grows from; omitted, the focused control; null, none (scale-in). */
+  open(origin?: HTMLElement | null): void;
+  close(): void;
+  toggle(origin?: HTMLElement | null): void;
+  float(): void;
+  dock(): void;
+  readonly isOpen: boolean;
+  readonly isFloating: boolean;
+  readonly element: HTMLElement;
+}
+
+const DEFAULT_LABELS: Required<DialogLabels> = { close: 'Cerrar', float: 'Ventana flotante', dock: 'Volver a su sitio' };
+const FIELDS = '[autofocus], input:not([type="hidden"]):not(:disabled), textarea:not(:disabled), select:not(:disabled)';
+const CORNERS = ['tl', 'tr', 'bl', 'br'] as const;
+let uid = 0;
+
+const part = (dialog: HTMLElement, name: string) => dialog.querySelector<HTMLElement>(`[data-mk-part="${name}"]`);
+
+export function createDialog(dialog: HTMLElement | null, options: DialogOptions = {}): DialogInstance {
+  if (!dialog) {
+    warnOnce('dialog: missing <dialog> element');
+    return inert({ open() {}, close() {}, toggle() {}, float() {}, dock() {}, isOpen: false, isFloating: false, element: null as unknown as HTMLElement });
+  }
+  registerMotion();
+  const {
+    variant = 'morph',
+    placement = 'center',
+    backdrop = true,
+    closeOnBackdrop = true,
+    drag = true,
+    float: floatKey = false,
+    autoResize = true,
+    triggers = true,
+    modal = true,
+  } = options;
+  const labels = { ...DEFAULT_LABELS, ...options.labels };
+  const liquid = variant === 'liquid';
+  const sheet = variant === 'sheet';
+  const drawer = variant === 'drawer';
+  const scope = createScope();
+  /** Effects that live while it is open. */
+  let session: Cleanup[] = [];
+  let opener: HTMLElement | null = null;
+  let isOpen = false;
+  let closing = false;
+  let floating = false;
+  /**
+   * Lifting and docking swap modal ↔ popover: the native `close` events they cause
+   * (queued, so they arrive later) are not the person closing it.
+   */
+  let ownCloses = 0;
+  const closeNatively = () => {
+    if (!dialog.hasAttribute('open')) return;
+    ownCloses += 1;
+    closeModal(dialog as HTMLDialogElement);
+  };
+  let destroyed = false;
+  /** destroy() is under way: the page behind comes back at once. */
+  let tearingDown = false;
+
+  if (placement !== 'center') scope.attr(dialog, 'data-mk-placement', placement);
+  if (!backdrop) scope.attr(dialog, 'data-mk-backdrop', 'none');
+  scope.attr(dialog, 'data-mk-variant', variant);
+  const title = part(dialog, 'title');
+  if (title && !dialog.hasAttribute('aria-label') && !dialog.hasAttribute('aria-labelledby')) {
+    if (!title.id) scope.attr(title, 'id', `mk-dialog-title-${++uid}`);
+    scope.attr(dialog, 'aria-labelledby', title.id);
+  }
+  const description = part(dialog, 'description');
+  if (description && !dialog.hasAttribute('aria-describedby')) {
+    if (!description.id) scope.attr(description, 'id', `mk-dialog-description-${++uid}`);
+    scope.attr(dialog, 'aria-describedby', description.id);
+  }
+  const closeButton = part(dialog, 'close');
+  if (closeButton && !closeButton.hasAttribute('aria-label') && !closeButton.textContent?.trim()) {
+    scope.attr(closeButton, 'aria-label', labels.close);
+  }
+  const handle = floatKey ? part(dialog, 'handle') : null;
+  if (handle) {
+    scope.attr(handle, 'data-mk-no-drag', '');
+    scope.attr(handle, 'aria-pressed', 'false');
+    scope.attr(handle, 'aria-label', labels.float);
+  }
+  const corners: HTMLElement[] = [];
+  if (floatKey) {
+    for (const corner of CORNERS) {
+      const element = document.createElement('span');
+      element.className = 'mk-float-corner';
+      element.dataset.mkFloatCorner = corner;
+      element.dataset.mkNoDrag = '';
+      element.setAttribute('aria-hidden', 'true');
+      dialog.append(element);
+      corners.push(element);
+    }
+    scope.add(() => corners.forEach((corner) => corner.remove()));
+  }
+
+  const emit = (type: string, cancelable = false, detail: Record<string, unknown> = {}) =>
+    dialog.dispatchEvent(new CustomEvent(type, { bubbles: true, cancelable, detail: { dialog, ...detail } }));
+
+  const endSession = () => {
+    for (const cleanup of session.splice(0).reverse()) cleanup();
+  };
+
+  const settleFloating = () => {
+    if (!floating) return;
+    floating = false;
+    if (typeof dialog.hidePopover === 'function' && dialog.hasAttribute('popover')) {
+      try {
+        dialog.hidePopover();
+      } catch {
+        // Already hidden.
+      }
+    }
+    dialog.removeAttribute('popover');
+    unplaceWindow(dialog);
+    if (handle) {
+      handle.setAttribute('aria-pressed', 'false');
+      handle.setAttribute('aria-label', labels.float);
+    }
+  };
+
+  /** Closed without our animation (owner, form[method=dialog], destroy). */
+  const closedQuietly = () => {
+    stopMorph(dialog);
+    endSession();
+    isOpen = false;
+    closing = false;
+    showOrigin(opener);
+    releaseShared(opener);
+    emit('mk:closed');
+    options.onClose?.();
+  };
+
+  const lift = () => {
+    if (!floatKey || floating || !isOpen || !floatingAvailable()) return;
+    const box = dialog.getBoundingClientRect();
+    const rect = savedFloat(floatKey) ?? { top: box.top, left: box.left, width: box.width, height: box.height };
+    const focused = document.activeElement;
+    // Its backdrop leaves as the window lifts off the page.
+    const backdropStyle = getComputedStyle(dialog, '::backdrop');
+    const veil = document.createElement('div');
+    veil.setAttribute('aria-hidden', 'true');
+    Object.assign(veil.style, {
+      position: 'fixed',
+      inset: '0',
+      background: backdropStyle.background || backdropStyle.backgroundColor,
+      backdropFilter: backdropStyle.backdropFilter,
+      pointerEvents: 'none',
+    });
+    closeNatively();
+    document.body.append(veil);
+    dialog.setAttribute('popover', 'manual');
+    if (typeof dialog.showPopover === 'function') dialog.showPopover();
+    else openModal(dialog, false);
+    liftWindow(dialog, rect);
+    gsap.to(veil, { opacity: 0, duration: reduced() ? 0 : TIMING.float.shadow, ease: EASE.signature, onComplete: () => veil.remove() });
+    floating = true;
+    if (handle) {
+      handle.setAttribute('aria-pressed', 'true');
+      handle.setAttribute('aria-label', labels.dock);
+    }
+    showOrigin(opener, { fade: true });
+    if (focused instanceof HTMLElement && dialog.contains(focused)) focused.focus();
+  };
+
+  const dock = () => {
+    if (!floatKey || !floating) return;
+    const box = dialog.getBoundingClientRect();
+    const focused = document.activeElement;
+    floating = false;
+    if (typeof dialog.hidePopover === 'function') dialog.hidePopover();
+    dialog.removeAttribute('popover');
+    closeNatively();
+    openModal(dialog, modal);
+    dockWindow(dialog, { top: box.top, left: box.left, width: box.width, height: box.height });
+    if (backdrop) void fadeBackdrop(dialog, 'in');
+    forgetFloat(floatKey);
+    if (handle) {
+      handle.setAttribute('aria-pressed', 'false');
+      handle.setAttribute('aria-label', labels.float);
+    }
+    if (focused instanceof HTMLElement && dialog.contains(focused)) focused.focus();
+  };
+
+  const anchorBox = () => (options.anchor ? options.anchor() : opener?.isConnected ? opener.getBoundingClientRect() : null);
+
+  const startSession = () => {
+    if (drawer && modal) {
+      const root = document.documentElement;
+      const overflow = root.style.overflow;
+      root.style.overflow = 'hidden';
+      session.push(() => {
+        root.style.overflow = overflow;
+        if (root.getAttribute('style') === '') root.removeAttribute('style');
+      });
+    }
+    if (sheet) {
+      const behind = [...document.querySelectorAll<HTMLElement>('[data-mk-underlay]')];
+      pushUnderlay(behind);
+      const root = document.documentElement;
+      const overflow = root.style.overflow;
+      root.style.overflow = 'hidden';
+      session.push(() => {
+        root.style.overflow = overflow;
+        if (root.getAttribute('style') === '') root.removeAttribute('style');
+        releaseUnderlay(behind, !tearingDown);
+      });
+    }
+    if (autoResize && typeof ResizeObserver === 'function') {
+      let last = dialog.offsetHeight;
+      let resizing: gsap.core.Tween | null = null;
+      const observer = new ResizeObserver(() => {
+        if (resizing?.isActive()) return;
+        const next = dialog.offsetHeight;
+        const previous = last;
+        last = next;
+        // A floating window's size is the person's, not its content's.
+        if (floating || Math.abs(next - previous) < 2 || !previous || isMorphing(dialog) || reduced()) return;
+        resizing = gsap.fromTo(
+          dialog,
+          { height: previous },
+          {
+            height: next,
+            duration: TIMING.dialog.autoResize,
+            ease: EASE.signature,
+            clearProps: 'height',
+            onComplete: () => {
+              last = dialog.offsetHeight;
+            },
+          },
+        );
+      });
+      observer.observe(dialog);
+      session.push(() => {
+        observer.disconnect();
+        resizing?.kill();
+        clearStyles([dialog], ['height']);
+      });
+    }
+    if (drag) {
+      session.push(
+        attachDragDismiss(dialog, {
+          canDrag: () => !isMorphing(dialog) && !floating && !closing && isOpen,
+          onDismiss: () => close(true),
+        }),
+      );
+    }
+    if (placement === 'anchor') {
+      const onResize = () => {
+        if (isOpen && !floating) anchorSurface(dialog, anchorBox());
+      };
+      addEventListener('resize', onResize);
+      session.push(() => {
+        removeEventListener('resize', onResize);
+        clearAnchor(dialog);
+      });
+    }
+    if (floatKey && handle) {
+      session.push(attachFloating(dialog, { key: floatKey, handle, corners, isFloating: () => floating, float: lift, dock }));
+      const onResize = () => {
+        if (floating && !floatingAvailable()) dock();
+      };
+      addEventListener('resize', onResize);
+      session.push(() => removeEventListener('resize', onResize));
+    }
+  };
+
+  const open = (origin?: HTMLElement | null) => {
+    if (destroyed || isOpen) return;
+    const active = document.activeElement;
+    // undefined: the focused control (usually the one clicked); null: no opener at all.
+    opener = origin !== undefined ? origin : active instanceof HTMLElement && active !== document.body && !dialog.contains(active) ? active : null;
+    closing = false;
+    isOpen = true;
+    openModal(dialog, modal);
+    if (placement === 'anchor') anchorSurface(dialog, anchorBox());
+    if (backdrop && modal) void fadeBackdrop(dialog, 'in');
+    if (sheet) sheetOpen(dialog);
+    else if (drawer) slideOpen(dialog);
+    else morphOpen(dialog, opener, { hideOrigin: true, liquid, content: options.animateContent === false ? ':scope > :not(*)' : undefined });
+    startSession();
+    // Forms start at their first field (after showModal: a closed dialog cannot take focus).
+    dialog.querySelector<HTMLElement>(FIELDS)?.focus({ preventScroll: true });
+    emit('mk:open', false, { origin: opener });
+    options.onOpen?.();
+  };
+
+  /** Animated close: the dialog closes at once while an inert copy folds into the opener. */
+  const close = (inPlace = false) => {
+    if (destroyed || !isOpen || closing) return;
+    if (!emit('mk:close', true, { inPlace })) return;
+    closing = true;
+    // The copy is measured first: the session cleanup clears an anchored place.
+    if (sheet) sheetClose(dialog, { inPlace });
+    else if (drawer) slideClose(dialog);
+    else morphCloseWithGhost(dialog, opener, { inPlace, liquid });
+    endSession();
+    if (floating) settleFloating();
+    if (dialog.hasAttribute('open')) closeModal(dialog as HTMLDialogElement);
+    isOpen = false;
+    closing = false;
+    if (opener?.isConnected) opener.focus();
+    emit('mk:closed');
+    options.onClose?.();
+  };
+
+  scope.on(dialog, 'cancel', (event) => {
+    event.preventDefault();
+    close();
+  });
+  scope.on(dialog, 'close', () => {
+    if (ownCloses > 0) {
+      ownCloses -= 1;
+      return;
+    }
+    // A native close we did not start (form method="dialog", dialog.close()).
+    if (!isOpen || closing) return;
+    closedQuietly();
+  });
+  scope.on(dialog, 'keydown', (event) => {
+    // A floating (non-modal) window still closes with Escape.
+    if ((event as KeyboardEvent).key === 'Escape' && floating) {
+      event.preventDefault();
+      close();
+    }
+  });
+  scope.on(dialog, 'click', (event) => {
+    const target = event.target as Element | null;
+    if (target?.closest('[data-mk-part="close"], [data-mk-close]') && dialog.contains(target)) {
+      close();
+      return;
+    }
+    if (target !== dialog || !closeOnBackdrop || floating) return;
+    const mouse = event as MouseEvent;
+    const box = dialog.getBoundingClientRect();
+    if (mouse.clientX < box.left || mouse.clientX > box.right || mouse.clientY < box.top || mouse.clientY > box.bottom) close();
+  });
+  const triggerId = triggers === true ? dialog.id : triggers || '';
+  if (triggerId) {
+    const selector = `[data-mk-open="${typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(triggerId) : triggerId}"]`;
+    scope.on(document, 'click', (event) => {
+      const trigger = (event.target as Element | null)?.closest<HTMLElement>(selector);
+      if (!trigger || dialog.contains(trigger)) return;
+      event.preventDefault();
+      if (isOpen) close();
+      else open(trigger);
+    });
+  }
+  dialog.dataset.mkReady = '';
+
+  return {
+    open,
+    close: () => close(),
+    toggle: (origin?: HTMLElement | null) => (isOpen ? close() : open(origin)),
+    float: lift,
+    dock,
+    get isOpen() {
+      return isOpen;
+    },
+    get isFloating() {
+      return floating;
+    },
+    element: dialog,
+    destroy() {
+      if (destroyed) return;
+      tearingDown = true;
+      if (isOpen) {
+        settleFloating();
+        closing = true;
+        if (dialog.hasAttribute('open')) closeModal(dialog as HTMLDialogElement);
+        closedQuietly();
+      }
+      destroyed = true;
+      endSession();
+      gsap.killTweensOf(dialog);
+      clearStyles([dialog], [...MORPH_STYLES, 'height']);
+      scope.dispose();
+      delete dialog.dataset.mkReady;
+    },
+  };
+}