platform-bible-react
    Preparing search index...

    Function useDismissOnWindowBlur

    • Experimental

      Treats the window losing focus as a press outside the calling surface, so an open menu or popover dismisses itself.

      Web views are iframes, so a click in another web view, or in another application, never produces a pointerdown in this document and Radix's outside-press detection never runs. Native menus close when their application is deactivated; this hook gives Radix surfaces the same behavior. From mount until unmount, a blur on window dispatches a synthetic pointerdown on the content's parent element. A closed surface has no content node (unmounted) or a content node marked data-state="closed" (animating out), and the blur is ignored in both cases, so a mounted-but-closed surface never presses on an unrelated open layer. Radix's DismissableLayer listens for pointerdown on the owner document and does not check isTrusted, so the event takes its normal outside-press path: onPointerDownOutside runs and can call preventDefault() to keep the surface open, and a surface whose open is controlled without an onOpenChange stays open.

      The press lands "outside this surface, but inside whatever hosts it". A popover portaled into a dialog (via PopoverPortalContainerProvider) closes while the dialog's own DismissableLayer sees an inside press and stays open. A popover or menu portaled to document.body is pressed on from its own Radix popper wrapper (data-radix-popper-content-wrapper, what parentElement resolves to there), which is outside it. A modal menu opened from inside a dialog is protected by Radix anyway: a layer below the top-most layer that disables outside pointer events does not dismiss.

      Focus rule: a dismissal caused by a click into another frame does not return focus to the trigger. The user has already put focus somewhere else, and Radix's default close-auto-focus would pull it back: a menu closing in one frame by returning focus to its trigger blurs the main window, which would close the menu the user just opened in another frame. The returned onCloseAutoFocus calls preventDefault() per shouldSuppressFocusReturn: when the active element is an <iframe> (the user clicked into a web view from this document), or when this window is a web view whose document has lost focus (the user clicked into another frame, or switched applications). In the main document a lost document.hasFocus() can only mean the OS window was deactivated, so the hook focuses the trigger itself and prevents Radix's default. After an outside interaction, which the synthetic press is, the non-modal Popover and the Menubar would skip their own restore, while a modal DropdownMenu would restore anyway; the outcome is the same for all three. The trigger is the element whose aria-controls names the content's id, looked up at close and, failing that, as found when the content mounted; else the element the content's aria-labelledby names. A surface without either (a context menu) restores nothing. Focus is never taken from an element the user focused elsewhere. Any other close, such as Escape or a click elsewhere in this document, restores focus as usual. The rule reads state at close time rather than remembering that a blur dismissal happened: Radix runs close-auto-focus from its own timer after an asynchronous unmount, so a flag cleared by a timeout loses that race under load.

      The synthetic press is untrusted and carries a window-blur marker (checked by the internal isWindowBlurPress). The focus modality tracker and the overlay service's press recorder skip it, and the overlay service's own surfaces ignore it. Window service gesture tracking, the content-zoom bootstrap and the editor's selection snapshot see it and were judged benign. Another document-level pointerdown listener that must ignore it can check the marker the same way.

      Hidden-view case (the repo's rule on hidden views): a keyboard tab switch can hide a pane that holds an open menu. The blur listener then dismisses it on the next window blur, which is harmless, so there is deliberately no catch-up logic. The one deliberate exception is a non-modal compact BookChapterControl: its onInteractOutside prevents this hook's synthetic press from dismissing it, so it stays open while its tab is hidden and closes through its trigger once the tab is visible again, or on Escape with focus in it.

      Type Parameters

      • T extends HTMLElement

      Parameters

      • props: DismissOnWindowBlurProps<T>

        The caller's ref and onCloseAutoFocus for the Radix Content. Both still work: the ref receives the element too, and the caller's handler runs first and can itself prevent the default.

      Returns { onCloseAutoFocus: (event: Event) => void; ref: RefCallback<T> }

      ref: ref callback to attach to the surface's content element. The element is null while the surface is closed, which makes the blur a no-op. Its identity is stable unless props.ref changes. onCloseAutoFocus: handler to pass to the content. Spread both onto the Radix Content. This export is unstable and may change shape or disappear without notice

      • onCloseAutoFocus: (event: Event) => void

        Close-auto-focus handler for the Radix Content; also calls the caller's handler

      • ref: RefCallback<T>

        Ref callback for the Radix Content; also forwards the caller's ref