@hanzogui/dialog 2.0.0-rc.41-hanzoai.3

package/src/Dialog.tsx

@@ -0,0 +1,1052 @@
+import {
+  Adapt,
+  AdaptParent,
+  AdaptPortalContents,
+  ProvideAdaptContext,
+  useAdaptContext,
+  useAdaptIsActive,
+} from '@hanzogui/adapt'
+import { Animate } from '@hanzogui/animate'
+import { composeRefs, useComposedRefs } from '@hanzogui/compose-refs'
+import { isWeb, useIsomorphicLayoutEffect } from '@hanzogui/constants'
+import type { GetProps, HanzoguiElement, ViewProps } from '@hanzogui/core'
+import {
+  createStyledContext,
+  getExpandedShorthand,
+  LayoutMeasurementController,
+  styled,
+  Theme,
+  useThemeName,
+  View,
+} from '@hanzogui/core'
+import { createContext } from '@hanzogui/create-context'
+import type { DismissableProps } from '@hanzogui/dismissable'
+import { Dismissable } from '@hanzogui/dismissable'
+import type { FocusScopeProps } from '@hanzogui/focus-scope'
+import { FocusScope, FocusScopeController } from '@hanzogui/focus-scope'
+import { composeEventHandlers, withStaticProperties } from '@hanzogui/helpers'
+import {
+  needsPortalRepropagation,
+  Portal,
+  PortalItem,
+  resolveViewZIndex,
+} from '@hanzogui/portal'
+import { RemoveScroll } from '@hanzogui/remove-scroll'
+import { SheetController } from '@hanzogui/sheet/controller'
+import type { YStackProps } from '@hanzogui/stacks'
+import { ButtonNestingContext, ThemeableStack, YStack } from '@hanzogui/stacks'
+import { H2, Paragraph } from '@hanzogui/text'
+import { useControllableState } from '@hanzogui/use-controllable-state'
+import { StackZIndexContext } from '@hanzogui/z-index-stack'
+import * as React from 'react'
+
+export type DialogScopes = string
+
+type ScopedProps<P> = P & { scope?: DialogScopes }
+
+type DialogProps = ScopedProps<{
+  children?: React.ReactNode
+  open?: boolean
+  defaultOpen?: boolean
+
+  /**
+   * When true, children never un-mount, otherwise they mount on open.
+   *
+   * @default false
+   */
+  keepChildrenMounted?: boolean
+  onOpenChange?(open: boolean): void
+  modal?: boolean
+
+  /**
+   * Used to disable the remove scroll functionality when open
+   */
+  disableRemoveScroll?: boolean
+
+  /**
+   * Called when the dialog open/close animation completes.
+   */
+  onAnimationComplete?: (info: { open: boolean }) => void
+}>
+
+type NonNull<A> = Exclude<A, void | null>
+
+type DialogContextValue = {
+  forceMount?: boolean
+  keepChildrenMounted?: boolean
+  disableRemoveScroll?: boolean
+  triggerRef: React.RefObject<HanzoguiElement | null>
+  contentRef: React.RefObject<HanzoguiElement | null>
+  contentId: string
+  titleId: string
+  descriptionId: string
+  onOpenToggle(): void
+  open: NonNull<DialogProps['open']>
+  onOpenChange: NonNull<DialogProps['onOpenChange']>
+  modal: NonNull<DialogProps['modal']>
+  dialogScope: DialogScopes
+  adaptScope: string
+  onAnimationComplete?: DialogProps['onAnimationComplete']
+}
+
+export const DialogContext = createStyledContext<DialogContextValue>(
+  // since we always provide this we can avoid setting here
+  {} as DialogContextValue,
+  'Dialog__'
+)
+
+export const { useStyledContext: useDialogContext, Provider: DialogProvider } =
+  DialogContext
+
+/**
+ * Tracks whether the Sheet adapted from a Dialog has finished its slide-out
+ * animation. DialogSheetController owns the state; DialogContent reads it so
+ * it can hold adapted children mounted until the sheet is fully off-screen,
+ * instead of tearing them down the moment Dialog.open flips false.
+ *
+ * Default true so the value is "safe to unmount" if no provider is mounted
+ * (matches the historical behavior where adapted children unmount immediately
+ * on close in native).
+ */
+const DialogAdaptHiddenContext = React.createContext(true)
+
+/* -------------------------------------------------------------------------------------------------
+ * DialogTrigger
+ * -----------------------------------------------------------------------------------------------*/
+
+const DialogTriggerFrame = styled(View, {
+  name: 'DialogTrigger',
+})
+
+type DialogTriggerProps = ScopedProps<ViewProps>
+
+const DialogTrigger = DialogTriggerFrame.styleable<ScopedProps<{}>>(
+  function DialogTrigger(props, forwardedRef) {
+    const { scope, ...triggerProps } = props
+    const isInsideButton = React.useContext(ButtonNestingContext)
+    const context = useDialogContext(scope)
+    const composedTriggerRef = useComposedRefs(forwardedRef, context.triggerRef)
+    return (
+      <ButtonNestingContext.Provider value={true}>
+        <DialogTriggerFrame
+          render={isInsideButton ? 'span' : 'button'}
+          aria-haspopup="dialog"
+          aria-expanded={context.open}
+          aria-controls={context.contentId}
+          data-state={getState(context.open)}
+          {...triggerProps}
+          ref={composedTriggerRef}
+          onPress={composeEventHandlers(props.onPress as any, context.onOpenToggle)}
+        />
+      </ButtonNestingContext.Provider>
+    )
+  }
+)
+
+/* -------------------------------------------------------------------------------------------------
+ * DialogPortal
+ * -----------------------------------------------------------------------------------------------*/
+
+type DialogPortalProps = ScopedProps<
+  YStackProps & {
+    /**
+     * Used to force mounting when more control is needed. Useful when
+     * controlling animation with React animation libraries.
+     */
+    forceMount?: boolean
+  }
+>
+
+export const DialogPortalFrame = styled(YStack, {
+  pointerEvents: 'none',
+  render: 'dialog',
+
+  variants: {
+    unstyled: {
+      false: {
+        alignItems: 'center',
+        justifyContent: 'center',
+        fullscreen: true,
+
+        '$platform-web': {
+          // undo dialog styles
+          borderWidth: 0,
+          backgroundColor: 'transparent',
+          color: 'inherit',
+          maxInlineSize: 'none',
+          margin: 0,
+          width: 'auto',
+          height: 'auto',
+          // ensure always in frame and right height
+          maxHeight: '100vh',
+          position: 'fixed',
+          // ensure dialog inherits stacking context from portal wrapper
+          zIndex: 1,
+        },
+      },
+    },
+  } as const,
+
+  defaultVariants: {
+    unstyled: process.env.HANZOGUI_HEADLESS === '1',
+  },
+})
+
+const needsRepropagation = needsPortalRepropagation()
+
+const DialogPortalItem = ({
+  context,
+  children,
+}: {
+  context: DialogContextValue
+  children: React.ReactNode
+}) => {
+  const themeName = useThemeName()
+  const isAdapted = useAdaptIsActive(context.adaptScope)
+  const adaptContext = useAdaptContext(context.adaptScope)
+
+  let content = <Theme name={themeName}>{children}</Theme>
+
+  // not just adapted - both sheet and portal for modal need it
+  if (needsRepropagation) {
+    content = (
+      <ProvideAdaptContext {...adaptContext}>
+        <DialogProvider {...context}>{content}</DialogProvider>
+      </ProvideAdaptContext>
+    )
+  }
+
+  // until we can use react-native portals natively
+  // have to re-propogate context, sketch
+  // when adapted we portal to the adapt, when not we portal to root modal if needed
+  return isAdapted ? (
+    <AdaptPortalContents scope={context.adaptScope}>{content}</AdaptPortalContents>
+  ) : context.modal ? (
+    <PortalItem hostName={context.modal ? 'root' : context.adaptScope}>
+      {content}
+    </PortalItem>
+  ) : (
+    content
+  )
+}
+
+const DialogPortal = React.forwardRef<HanzoguiElement, DialogPortalProps>(
+  (props, forwardRef) => {
+    const { scope, forceMount, children, ...frameProps } = props
+    const dialogRef = React.useRef<HanzoguiElement>(null)
+    const ref = composeRefs(dialogRef, forwardRef)
+
+    const context = useDialogContext(scope)
+    const keepMounted = forceMount || context.keepChildrenMounted
+    const isAdapted = useAdaptIsActive(context.adaptScope)
+    const [isFullyHidden, setIsFullyHidden] = React.useState(!context.open)
+
+    if (context.open && isFullyHidden) {
+      setIsFullyHidden(false)
+    }
+
+    const isVisible = context.open ? true : !isFullyHidden
+
+    if (isWeb) {
+      useIsomorphicLayoutEffect(() => {
+        const node = dialogRef.current
+        if (!(node instanceof HTMLDialogElement)) return
+        // optional chaining for JSDOM compatibility (doesn't implement show/close)
+        if (isVisible) {
+          node.show?.()
+        } else {
+          node.close?.()
+        }
+      }, [isVisible])
+    }
+
+    const onAnimationCompleteRef = React.useRef(context.onAnimationComplete)
+    onAnimationCompleteRef.current = context.onAnimationComplete
+
+    const handleExitComplete = React.useCallback(() => {
+      setIsFullyHidden(true)
+      onAnimationCompleteRef.current?.({ open: false })
+    }, [])
+
+    React.useEffect(() => {
+      if (context.open && !isAdapted && onAnimationCompleteRef.current) {
+        const tm = setTimeout(() => {
+          onAnimationCompleteRef.current?.({ open: true })
+        }, 350)
+        return () => clearTimeout(tm)
+      }
+    }, [context.open, isAdapted])
+
+    const zIndex = getExpandedShorthand('zIndex', props)
+
+    const contents = (
+      <StackZIndexContext zIndex={resolveViewZIndex(zIndex)}>
+        <Animate
+          type="presence"
+          present={Boolean(context.open)}
+          keepChildrenMounted={Boolean(keepMounted)}
+          onExitComplete={handleExitComplete}
+          passThrough={isAdapted}
+        >
+          {children}
+        </Animate>
+      </StackZIndexContext>
+    )
+
+    const framedContents =
+      isFullyHidden && !keepMounted && !isAdapted ? null : (
+        <LayoutMeasurementController disable={!context.open}>
+          <DialogPortalFrame
+            ref={ref}
+            {...(isWeb &&
+              context.open && {
+                'aria-modal': true,
+              })}
+            pointerEvents={context.open ? 'auto' : 'none'}
+            {...frameProps}
+            className={`_no_backdrop ` + (frameProps.className || '')}
+          >
+            {contents}
+          </DialogPortalFrame>
+        </LayoutMeasurementController>
+      )
+
+    if (isWeb) {
+      return (
+        <Portal
+          zIndex={zIndex}
+          // set to 100000 which ensures dialogs are above most fixed UI (headers, navs)
+          // this makes sure its above typical stacking contexts
+          stackZIndex={100000}
+          passThrough={isAdapted}
+        >
+          <PassthroughTheme passThrough={isAdapted}>{framedContents}</PassthroughTheme>
+        </Portal>
+      )
+    }
+
+    return isAdapted ? (
+      framedContents
+    ) : (
+      <DialogPortalItem context={context}>{framedContents}</DialogPortalItem>
+    )
+  }
+)
+
+const PassthroughTheme = ({
+  children,
+  passThrough,
+}: {
+  passThrough?: boolean
+  children?: React.ReactNode
+}) => {
+  const themeName = useThemeName()
+
+  return (
+    <Theme passThrough={passThrough} name={themeName} forceClassName>
+      {children}
+    </Theme>
+  )
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * DialogOverlay
+ * -----------------------------------------------------------------------------------------------*/
+
+const OVERLAY_NAME = 'DialogOverlay'
+
+/**
+ * exported for internal use with extractable()
+ */
+export const DialogOverlayFrame = styled(YStack, {
+  name: OVERLAY_NAME,
+  zIndex: 1,
+
+  variants: {
+    open: {
+      true: {
+        pointerEvents: 'auto',
+      },
+      false: {
+        pointerEvents: 'none',
+      },
+    },
+
+    unstyled: {
+      false: {
+        fullscreen: true,
+        position: 'absolute',
+        backgroundColor: '$background',
+        pointerEvents: 'auto',
+      },
+    },
+  } as const,
+
+  defaultVariants: {
+    unstyled: process.env.HANZOGUI_HEADLESS === '1',
+  },
+})
+
+export type DialogOverlayExtraProps = ScopedProps<{
+  /**
+   * Used to force mounting when more control is needed. Useful when
+   * controlling animation with React animation libraries.
+   */
+  forceMount?: boolean
+}>
+
+type DialogOverlayProps = YStackProps & DialogOverlayExtraProps
+
+const DialogOverlay = DialogOverlayFrame.styleable<DialogOverlayExtraProps>(
+  function DialogOverlay({ scope, ...props }, forwardedRef) {
+    const context = useDialogContext(scope)
+    const { forceMount = context.forceMount, ...overlayProps } = props
+    const isAdapted = useAdaptIsActive(context.adaptScope)
+
+    if (!forceMount) {
+      if (!context.modal || isAdapted) {
+        return null
+      }
+    }
+
+    // Make sure `Content` is scrollable even when it doesn't live inside `RemoveScroll`
+    // ie. when `Overlay` and `Content` are siblings
+    return (
+      <DialogOverlayFrame
+        data-state={getState(context.open)}
+        // TODO: this will be apply for v2
+        // onPress={() => {
+        //   // if the overlay is pressed, close the dialog
+        //   context.onOpenChange(false)
+        // }}
+        // We re-enable pointer-events prevented by `Dialog.Content` to allow scrolling the overlay.
+        pointerEvents={context.open ? 'auto' : 'none'}
+        {...overlayProps}
+        ref={forwardedRef}
+      />
+    )
+  }
+)
+
+/* -------------------------------------------------------------------------------------------------
+ * DialogContent
+ * -----------------------------------------------------------------------------------------------*/
+
+const CONTENT_NAME = 'DialogContent'
+
+const DialogContentFrame = styled(ThemeableStack, {
+  name: CONTENT_NAME,
+  zIndex: 2,
+
+  variants: {
+    size: {
+      '...size': (val, extras) => {
+        return {}
+      },
+    },
+
+    unstyled: {
+      false: {
+        position: 'relative',
+        backgroundColor: '$background',
+        borderWidth: 1,
+        borderColor: '$borderColor',
+        padding: '$true',
+        borderRadius: '$true',
+        elevate: true,
+        // Ensure content receives pointer events (fixes React 19 + display:contents inheritance)
+        pointerEvents: 'auto',
+      },
+    },
+  } as const,
+
+  defaultVariants: {
+    size: '$true',
+    unstyled: process.env.HANZOGUI_HEADLESS === '1',
+  },
+})
+
+type DialogContentFrameProps = GetProps<typeof DialogContentFrame>
+
+type DialogContentExtraProps = ScopedProps<
+  Omit<DialogContentTypeProps, 'context' | 'onPointerDownCapture'>
+>
+
+type DialogContentProps = DialogContentFrameProps & DialogContentExtraProps
+
+const DialogContent = DialogContentFrame.styleable<DialogContentExtraProps>(
+  function DialogContent({ scope, ...props }, forwardedRef) {
+    const context = useDialogContext(scope)
+
+    const contents = (
+      <>
+        {context.modal ? (
+          <DialogContentModal context={context} {...props} ref={forwardedRef} />
+        ) : (
+          <DialogContentNonModal context={context} {...props} ref={forwardedRef} />
+        )}
+      </>
+    )
+
+    if (!isWeb || context.disableRemoveScroll) {
+      return contents
+    }
+
+    return (
+      <RemoveScroll enabled={context.open}>
+        <div data-remove-scroll-container className="_dsp_contents">
+          {contents}
+        </div>
+      </RemoveScroll>
+    )
+  }
+)
+
+/* -----------------------------------------------------------------------------------------------*/
+
+type DialogContentTypeProps = DialogContentImplProps & {
+  context: DialogContextValue
+}
+
+const DialogContentModal = React.forwardRef<HanzoguiElement, DialogContentTypeProps>(
+  ({ children, context, ...props }, forwardedRef) => {
+    const contentRef = React.useRef<HanzoguiElement>(null)
+    const composedRefs = useComposedRefs(forwardedRef, context.contentRef, contentRef)
+
+    return (
+      <DialogContentImpl
+        {...props}
+        context={context}
+        ref={composedRefs}
+        // we make sure focus isn't trapped once `DialogContent` has been closed
+        // (closed !== unmounted when animating out)
+        trapFocus={context.open}
+        disableOutsidePointerEvents
+        onCloseAutoFocus={composeEventHandlers(props.onCloseAutoFocus, (event) => {
+          event.preventDefault()
+          context.triggerRef.current?.focus()
+        })}
+        onPointerDownOutside={composeEventHandlers(
+          props.onPointerDownOutside,
+          (event) => {
+            const originalEvent = event['detail'].originalEvent
+            const ctrlLeftClick =
+              originalEvent.button === 0 && originalEvent.ctrlKey === true
+            const isRightClick = originalEvent.button === 2 || ctrlLeftClick
+            // If the event is a right-click, we shouldn't close because
+            // it is effectively as if we right-clicked the `Overlay`.
+            if (isRightClick) event.preventDefault()
+          }
+        )}
+        // When focus is trapped, a `focusout` event may still happen.
+        // We make sure we don't trigger our `onDismiss` in such case.
+        onFocusOutside={composeEventHandlers(props.onFocusOutside, (event) =>
+          event.preventDefault()
+        )}
+        {...(!props.unstyled && {
+          outlineStyle: 'none',
+        })}
+      >
+        {children}
+      </DialogContentImpl>
+    )
+  }
+)
+
+/* -----------------------------------------------------------------------------------------------*/
+
+const DialogContentNonModal = React.forwardRef<HanzoguiElement, DialogContentTypeProps>(
+  (props, forwardedRef) => {
+    const hasInteractedOutsideRef = React.useRef(false)
+
+    return (
+      <DialogContentImpl
+        {...props}
+        ref={forwardedRef}
+        trapFocus={false}
+        disableOutsidePointerEvents={false}
+        onCloseAutoFocus={(event) => {
+          props.onCloseAutoFocus?.(event)
+
+          if (!event.defaultPrevented) {
+            if (!hasInteractedOutsideRef.current) {
+              props.context.triggerRef.current?.focus()
+            }
+            // Always prevent auto focus because we either focus manually or want user agent focus
+            event.preventDefault()
+          }
+
+          hasInteractedOutsideRef.current = false
+        }}
+        onInteractOutside={(event) => {
+          props.onInteractOutside?.(event)
+
+          if (!event.defaultPrevented) hasInteractedOutsideRef.current = true
+
+          // Prevent dismissing when clicking the trigger.
+          // As the trigger is already setup to close, without doing so would
+          // cause it to close and immediately open.
+          //
+          // We use `onInteractOutside` as some browsers also
+          // focus on pointer down, creating the same issue.
+          const target = event.target as HTMLElement
+          const trigger = props.context.triggerRef.current
+          if (!(trigger instanceof HTMLElement)) return
+          const targetIsTrigger = trigger.contains(target)
+          if (targetIsTrigger) event.preventDefault()
+        }}
+      />
+    )
+  }
+)
+
+/* -----------------------------------------------------------------------------------------------*/
+
+type DialogContentImplExtraProps = Omit<DismissableProps, 'onDismiss'> & {
+  /**
+   * When `true`, focus cannot escape the `Content` via keyboard,
+   * pointer, or a programmatic focus.
+   * @defaultValue false
+   */
+  trapFocus?: FocusScopeProps['trapped']
+
+  /**
+   * Event handler called when auto-focusing on open.
+   * Can be prevented.
+   */
+  onOpenAutoFocus?: FocusScopeProps['onMountAutoFocus']
+
+  /**
+   * Event handler called when auto-focusing on close.
+   * Can be prevented.
+   */
+  onCloseAutoFocus?: FocusScopeProps['onUnmountAutoFocus']
+
+  context: DialogContextValue
+}
+
+type DialogContentImplProps = DialogContentFrameProps & DialogContentImplExtraProps
+
+const DialogContentImpl = React.forwardRef<HanzoguiElement, DialogContentImplProps>(
+  (props, forwardedRef) => {
+    const {
+      trapFocus,
+      onOpenAutoFocus,
+      onCloseAutoFocus,
+      disableOutsidePointerEvents,
+      onEscapeKeyDown,
+      onPointerDownOutside,
+      onFocusOutside,
+      onInteractOutside,
+      context,
+      ...contentProps
+    } = props
+
+    const contentRef = React.useRef<HanzoguiElement>(null)
+    const composedRefs = useComposedRefs(forwardedRef, contentRef)
+    const isAdapted = useAdaptIsActive(context.adaptScope)
+
+    // TODO this will re-parent, ideally we would not change tree structure
+
+    // when adapted, the dialog's content is portaled into the Sheet via
+    // Adapt.Contents. hold children mounted until the sheet's slide-out
+    // animation is fully complete (DialogAdaptHiddenContext is flipped by
+    // DialogSheetController via SheetController.onAnimationComplete), then
+    // unmount. opt out with `keepChildrenMounted` if you need the old
+    // permanent-mount behavior.
+    const isAdaptFullyHidden = React.useContext(DialogAdaptHiddenContext)
+    if (isAdapted) {
+      if (!context.open && !context.keepChildrenMounted && isAdaptFullyHidden) {
+        return null
+      }
+
+      return (
+        <DialogPortalItem context={context}>{contentProps.children}</DialogPortalItem>
+      )
+    }
+
+    const contents = (
+      <DialogContentFrame
+        ref={composedRefs}
+        id={context.contentId}
+        role="dialog"
+        aria-modal={context.modal}
+        aria-describedby={context.descriptionId}
+        aria-labelledby={context.titleId}
+        data-state={getState(context.open)}
+        // allow clicking through content during exit animation
+        pointerEvents={context.open ? 'auto' : 'none'}
+        {...contentProps}
+      />
+    )
+
+    if (!isWeb) {
+      return contents
+    }
+
+    return (
+      <>
+        <Dismissable
+          disableOutsidePointerEvents={context.open && disableOutsidePointerEvents}
+          forceUnmount={!context.open}
+          onEscapeKeyDown={onEscapeKeyDown}
+          onPointerDownOutside={onPointerDownOutside}
+          onFocusOutside={onFocusOutside}
+          onInteractOutside={onInteractOutside}
+          onDismiss={() => context?.onOpenChange?.(false)}
+        >
+          <FocusScope
+            loop
+            enabled={context.open}
+            trapped={trapFocus}
+            onMountAutoFocus={onOpenAutoFocus}
+            forceUnmount={!context.open}
+            onUnmountAutoFocus={onCloseAutoFocus}
+          >
+            {contents}
+          </FocusScope>
+        </Dismissable>
+
+        {process.env.NODE_ENV === 'development' && (
+          <>
+            <TitleWarning titleId={context.titleId} />
+            <DescriptionWarning
+              contentRef={contentRef as any}
+              descriptionId={context.descriptionId}
+            />
+          </>
+        )}
+      </>
+    )
+  }
+)
+
+/* -------------------------------------------------------------------------------------------------
+ * DialogTitle
+ * -----------------------------------------------------------------------------------------------*/
+
+const DialogTitleFrame = styled(H2, {
+  name: 'DialogTitle',
+})
+
+type DialogTitleExtraProps = ScopedProps<{}>
+type DialogTitleProps = DialogTitleExtraProps & GetProps<typeof DialogTitleFrame>
+
+const DialogTitle = DialogTitleFrame.styleable<DialogTitleExtraProps>(
+  function DialogTitle(props, forwardedRef) {
+    const { scope, ...titleProps } = props
+    const context = useDialogContext(scope)
+    return <DialogTitleFrame id={context.titleId} {...titleProps} ref={forwardedRef} />
+  }
+)
+
+/* -------------------------------------------------------------------------------------------------
+ * DialogDescription
+ * -----------------------------------------------------------------------------------------------*/
+
+const DialogDescriptionFrame = styled(Paragraph, {
+  name: 'DialogDescription',
+})
+
+type DialogDescriptionExtraProps = ScopedProps<{}>
+type DialogDescriptionProps = DialogDescriptionExtraProps &
+  GetProps<typeof DialogDescriptionFrame>
+
+const DialogDescription = DialogDescriptionFrame.styleable<DialogDescriptionExtraProps>(
+  function DialogDescription(props, forwardedRef) {
+    const { scope, ...descriptionProps } = props
+    const context = useDialogContext(scope)
+    return (
+      <DialogDescriptionFrame
+        id={context.descriptionId}
+        {...descriptionProps}
+        ref={forwardedRef}
+      />
+    )
+  }
+)
+
+/* -------------------------------------------------------------------------------------------------
+ * DialogClose
+ * -----------------------------------------------------------------------------------------------*/
+
+const CLOSE_NAME = 'DialogClose'
+
+const DialogCloseFrame = styled(View, {
+  name: CLOSE_NAME,
+  render: 'button',
+})
+
+export type DialogCloseExtraProps = ScopedProps<{
+  displayWhenAdapted?: boolean
+}>
+
+type DialogCloseProps = GetProps<typeof DialogCloseFrame> & DialogCloseExtraProps
+
+const DialogClose = DialogCloseFrame.styleable<DialogCloseExtraProps>(
+  (props, forwardedRef) => {
+    const { scope, displayWhenAdapted, ...closeProps } = props
+    const context = useDialogContext(scope)
+    const isAdapted = useAdaptIsActive(context.adaptScope)
+    const isInsideButton = React.useContext(ButtonNestingContext)
+
+    if (isAdapted && !displayWhenAdapted) {
+      return null
+    }
+
+    return (
+      <DialogCloseFrame
+        aria-label="Dialog Close"
+        render={isInsideButton ? 'span' : 'button'}
+        {...closeProps}
+        ref={forwardedRef}
+        onPress={composeEventHandlers(props.onPress as any, () => {
+          context.onOpenChange(false)
+        })}
+      />
+    )
+  }
+)
+
+/* -----------------------------------------------------------------------------------------------*/
+
+function getState(open: boolean) {
+  return open ? 'open' : 'closed'
+}
+
+const TITLE_WARNING_NAME = 'DialogTitleWarning'
+
+const [DialogWarningProvider, useWarningContext] = createContext(TITLE_WARNING_NAME, {
+  contentName: CONTENT_NAME,
+  titleName: 'DialogTitle',
+  docsSlug: 'dialog',
+})
+
+type TitleWarningProps = { titleId?: string }
+
+const TitleWarning: React.FC<TitleWarningProps> = ({ titleId }) => {
+  if (process.env.NODE_ENV === 'development') {
+    const titleWarningContext = useWarningContext(TITLE_WARNING_NAME)
+
+    const MESSAGE = `\`${titleWarningContext.contentName}\` wants a \`${titleWarningContext.titleName}\` to be accessible. If you want to hide the \`${titleWarningContext.titleName}\`, wrap it with <VisuallyHidden />.`
+
+    React.useEffect(() => {
+      if (!isWeb) return
+      if (titleId) {
+        const hasTitle = document.getElementById(titleId)
+        if (!hasTitle) {
+          console.warn(MESSAGE)
+        }
+      }
+    }, [MESSAGE, titleId])
+  }
+
+  return null
+}
+
+const DESCRIPTION_WARNING_NAME = 'DialogDescriptionWarning'
+
+type DescriptionWarningProps = {
+  contentRef: React.RefObject<HanzoguiElement>
+  descriptionId?: string
+}
+
+const DescriptionWarning: React.FC<DescriptionWarningProps> = ({
+  contentRef,
+  descriptionId,
+}) => {
+  if (process.env.NODE_ENV === 'development') {
+    const descriptionWarningContext = useWarningContext(DESCRIPTION_WARNING_NAME)
+    const MESSAGE = `Warning: Missing \`Description\` or \`aria-describedby={undefined}\` for {${descriptionWarningContext.contentName}}.`
+
+    React.useEffect(() => {
+      if (!isWeb) return
+      const contentNode = contentRef.current
+      if (!(contentNode instanceof HTMLElement)) {
+        return
+      }
+      const describedById = contentNode.getAttribute('aria-describedby')
+      // if we have an id and the user hasn't set aria-describedby={undefined}
+      if (descriptionId && describedById) {
+        const hasDescription = document.getElementById(descriptionId)
+        if (!hasDescription) {
+          console.warn(MESSAGE)
+        }
+      }
+    }, [MESSAGE, contentRef, descriptionId])
+  }
+
+  return null
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Dialog
+ * -----------------------------------------------------------------------------------------------*/
+
+export type DialogHandle = {
+  open: (val: boolean) => void
+}
+
+const Dialog = withStaticProperties(
+  React.forwardRef<{ open: (val: boolean) => void }, DialogProps>(
+    function Dialog(props, ref) {
+      const {
+        scope = '',
+        children,
+        open: openProp,
+        defaultOpen = false,
+        onOpenChange,
+        modal = true,
+        keepChildrenMounted,
+        disableRemoveScroll = false,
+        onAnimationComplete,
+      } = props
+
+      const baseId = React.useId()
+      const dialogId = `Dialog-${scope}-${baseId}`
+      const contentId = `${dialogId}-content`
+      const titleId = `${dialogId}-title`
+      const descriptionId = `${dialogId}-description`
+
+      const triggerRef = React.useRef<HanzoguiElement>(null)
+      const contentRef = React.useRef<HanzoguiElement>(null)
+
+      const [open, setOpen] = useControllableState({
+        prop: openProp,
+        defaultProp: defaultOpen,
+        onChange: onOpenChange,
+      })
+
+      const onOpenToggle = React.useCallback(() => {
+        setOpen((prevOpen) => !prevOpen)
+      }, [setOpen])
+
+      const adaptScope = `DialogAdapt${scope}`
+
+      const context = {
+        dialogScope: scope,
+        adaptScope,
+        triggerRef,
+        contentRef,
+        contentId,
+        titleId,
+        descriptionId,
+        open,
+        onOpenChange: setOpen,
+        onOpenToggle,
+        modal,
+        keepChildrenMounted,
+        disableRemoveScroll,
+        onAnimationComplete,
+      } satisfies DialogContextValue
+
+      React.useImperativeHandle(
+        ref,
+        () => ({
+          open: setOpen,
+        }),
+        [setOpen]
+      )
+
+      return (
+        <AdaptParent
+          scope={adaptScope}
+          portal={{
+            forwardProps: props,
+          }}
+        >
+          <DialogProvider scope={scope} {...context}>
+            <DialogSheetController onOpenChange={setOpen} scope={scope}>
+              {children}
+            </DialogSheetController>
+          </DialogProvider>
+        </AdaptParent>
+      )
+    }
+  ),
+  {
+    Trigger: DialogTrigger,
+    Portal: DialogPortal,
+    Overlay: DialogOverlay,
+    Content: DialogContent,
+    Title: DialogTitle,
+    Description: DialogDescription,
+    Close: DialogClose,
+    FocusScope: FocusScopeController,
+    Adapt,
+  }
+)
+
+const getAdaptScope = (dialogScope: string) => `DialogAdapt${dialogScope}`
+
+const DialogSheetController = (
+  props: ScopedProps<{
+    children: React.ReactNode
+    onOpenChange: React.Dispatch<React.SetStateAction<boolean>>
+  }>
+) => {
+  const context = useDialogContext(props.scope)
+  const isAdapted = useAdaptIsActive(context.adaptScope)
+
+  // tracks whether the adapted Sheet has finished its slide-out animation.
+  // starts true (= safe to unmount) when the dialog is closed; flips to
+  // false the moment the dialog opens; flips back to true when the sheet
+  // signals onAnimationComplete with open=false (i.e. slide-out finished).
+  const [isAdaptFullyHidden, setIsAdaptFullyHidden] = React.useState(!context.open)
+  // mirror context.open into the hidden flag during render — an opening
+  // dialog must immediately mark its children as not-hidden so they render
+  // for the enter animation.
+  if (context.open && isAdaptFullyHidden) {
+    setIsAdaptFullyHidden(false)
+  }
+
+  const handleSheetAnimationComplete = React.useCallback(
+    ({ open }: { open: boolean }) => {
+      if (!open) {
+        setIsAdaptFullyHidden(true)
+      }
+    },
+    []
+  )
+
+  return (
+    <SheetController
+      onOpenChange={(val) => {
+        if (isAdapted) {
+          props.onOpenChange?.(val)
+        }
+      }}
+      onAnimationComplete={handleSheetAnimationComplete}
+      open={context.open}
+      hidden={!isAdapted}
+    >
+      <DialogAdaptHiddenContext.Provider value={isAdaptFullyHidden}>
+        {props.children}
+      </DialogAdaptHiddenContext.Provider>
+    </SheetController>
+  )
+}
+
+export {
+  //
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+  //
+  DialogWarningProvider,
+}
+export type {
+  DialogCloseProps,
+  DialogContentProps,
+  DialogDescriptionProps,
+  DialogOverlayProps,
+  DialogPortalProps,
+  DialogProps,
+  DialogTitleProps,
+  DialogTriggerProps,
+}