@softize/opus 24.1.0 → 25.1.0

package/src/ui/components/primitives/dialog.tsx

@@ -19,16 +19,34 @@ import {
   type StructuralMediaProps,
 } from "../patterns/structural-media.tsx";
 import { CloseButton, type CloseButtonSize } from "./close-button.tsx";
+import {
+  ANSWER_BAND_CLASS,
+  LAYER_MODAL_ATTRIBUTE,
+  LayerPortalProvider,
+  exemptLayerFirst,
+  focusIsInLayer,
+  handleModalTabKey,
+  isLayerInteraction,
+  routeEscapeToLayer,
+  useLayerPortal,
+  useModalLayerEntry,
+  type ModalMark,
+} from "../../lib/modal-layers.ts";
 
 export type DialogMode = "default" | "alert";
 
 interface DialogContextValue {
   mode: DialogMode;
   onResult?: (result: string) => void;
+  /** Estado de aberto, que a pilha de modais da camada flutuante acompanha (ADR 0052). */
+  open: boolean;
+  modal: boolean;
 }
 
 const DialogContext = React.createContext<DialogContextValue>({
   mode: "default",
+  open: false,
+  modal: true,
 });
 
 interface DialogContentContextValue {
@@ -67,6 +85,139 @@ function useDialogContext(): DialogContextValue {
   return React.useContext(DialogContext);
 }
 
+/**
+ * Estado de aberto controlado ou não, como o do Radix, mas visível ao Opus: a pilha de modais da
+ * camada flutuante precisa saber quando o modal fecha, e não só quando desmonta (ADR 0052).
+ */
+export function useModalOpenState({
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+}: {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}): [boolean, (open: boolean) => void] {
+  const [uncontrolled, setUncontrolled] = React.useState(defaultOpen ?? false);
+  const controlled = openProp !== undefined;
+  const open = controlled ? openProp : uncontrolled;
+  const onOpenChangeRef = React.useRef(onOpenChange);
+  onOpenChangeRef.current = onOpenChange;
+  const setOpen = React.useCallback(
+    (next: boolean) => {
+      if (!controlled) setUncontrolled(next);
+      onOpenChangeRef.current?.(next);
+    },
+    [controlled],
+  );
+  return [open, setOpen];
+}
+
+interface OutsideEvent {
+  defaultPrevented: boolean;
+  preventDefault(): void;
+  detail: { originalEvent: Event };
+}
+
+/**
+ * Isenções da camada flutuante compostas antes dos handlers de dispensa do consumidor e do
+ * `closeDisabled`, para Dialog e Drawer (seção 8 da ADR 0052). Fora de um modal de trabalho,
+ * devolve só a composição de sempre.
+ */
+export function composeModalDismissHandlers<
+  Escape extends KeyboardEvent,
+  Pointer extends OutsideEvent,
+  Interact extends OutsideEvent,
+  CloseFocus extends Event,
+>({
+  mark,
+  closeDisabled,
+  onEscapeKeyDown,
+  onPointerDownOutside,
+  onInteractOutside,
+  onCloseAutoFocus,
+}: {
+  mark: ModalMark;
+  closeDisabled: boolean;
+  onEscapeKeyDown: ((event: Escape) => void) | undefined;
+  onPointerDownOutside: ((event: Pointer) => void) | undefined;
+  onInteractOutside: ((event: Interact) => void) | undefined;
+  onCloseAutoFocus: ((event: CloseFocus) => void) | undefined;
+}): {
+  onEscapeKeyDown: ((event: Escape) => void) | undefined;
+  onPointerDownOutside: ((event: Pointer) => void) | undefined;
+  onInteractOutside: ((event: Interact) => void) | undefined;
+  onCloseAutoFocus: (event: CloseFocus) => void;
+} {
+  const escape = preventDismissWhen(closeDisabled, onEscapeKeyDown);
+  const interact = preventDismissWhen(closeDisabled, onInteractOutside);
+  // O modal que fecha com a pessoa na camada não leva o foco ao gatilho dele: o foco fica onde
+  // ela está digitando. O handler do consumidor roda antes e pode decidir outra coisa.
+  const closeAutoFocus = (event: CloseFocus): void => {
+    onCloseAutoFocus?.(event);
+    if (!event.defaultPrevented && focusIsInLayer()) event.preventDefault();
+  };
+  if (mark !== "work") {
+    return {
+      onEscapeKeyDown: escape,
+      onPointerDownOutside,
+      onInteractOutside: interact,
+      onCloseAutoFocus: closeAutoFocus,
+    };
+  }
+  return {
+    onEscapeKeyDown: exemptLayerFirst(routeEscapeToLayer, escape),
+    onPointerDownOutside: exemptLayerFirst(
+      isLayerInteraction,
+      onPointerDownOutside,
+    ),
+    onInteractOutside: exemptLayerFirst(isLayerInteraction, interact),
+    onCloseAutoFocus: closeAutoFocus,
+  };
+}
+
+type RefCleanup = () => void;
+
+function setRef<T>(
+  ref: React.Ref<T> | undefined,
+  value: T | null,
+): RefCleanup | void {
+  if (typeof ref === "function") {
+    const cleanup = ref(value);
+    return typeof cleanup === "function" ? cleanup : undefined;
+  }
+  if (ref !== null && ref !== undefined) {
+    (ref as React.RefObject<T | null>).current = value;
+  }
+}
+
+/**
+ * Compõe a ref do consumidor com a do Opus sem perder nenhuma das duas, como o `composeRefs` do
+ * Radix: quando alguma callback ref devolve limpeza (React 19), a composição também devolve, e o
+ * React passa a chamá-la em vez de chamar as refs com `null`. As refs sem limpeza recebem `null`
+ * nesse momento.
+ */
+export function useComposedRef<T>(
+  ...refs: Array<React.Ref<T> | undefined>
+): (node: T | null) => RefCleanup | undefined {
+  return React.useCallback(
+    (node: T | null) => {
+      const cleanups = refs.map((ref) => setRef(ref, node));
+      if (!cleanups.some((cleanup) => typeof cleanup === "function")) {
+        return undefined;
+      }
+      return () => {
+        cleanups.forEach((cleanup, index) => {
+          if (typeof cleanup === "function") cleanup();
+          else setRef(refs[index], null);
+        });
+      };
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    refs,
+  );
+}
+
 export interface DialogProps extends React.ComponentProps<
   typeof DialogPrimitive.Root
 > {
@@ -80,16 +231,40 @@ export function Dialog({
   mode = "default",
   onResult,
   modal,
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
   ...props
 }: DialogProps) {
-  const context = React.useMemo(() => ({ mode, onResult }), [mode, onResult]);
+  const [open, setOpen] = useModalOpenState({
+    open: openProp,
+    defaultOpen,
+    onOpenChange,
+  });
+  // O `AlertDialog` do Radix força o modo modal e ignora `modal`.
+  const isModal = mode === "alert" || modal !== false;
+  const context = React.useMemo(
+    () => ({ mode, onResult, open, modal: isModal }),
+    [mode, onResult, open, isModal],
+  );
 
   return (
     <DialogContext.Provider value={context}>
       {mode === "alert" ? (
-        <AlertDialogPrimitive.Root data-slot="dialog" {...props} />
+        <AlertDialogPrimitive.Root
+          data-slot="dialog"
+          open={open}
+          onOpenChange={setOpen}
+          {...props}
+        />
       ) : (
-        <DialogPrimitive.Root data-slot="dialog" modal={modal} {...props} />
+        <DialogPrimitive.Root
+          data-slot="dialog"
+          modal={modal}
+          open={open}
+          onOpenChange={setOpen}
+          {...props}
+        />
       )}
     </DialogContext.Provider>
   );
@@ -107,13 +282,25 @@ export function DialogTrigger({
 }
 
 export function DialogPortal({
+  container,
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Portal>) {
   const { mode } = useDialogContext();
+  // Aberto de dentro de uma camada flutuante, o modal vai para o hospedeiro dela (ADR 0052).
+  const layer = useLayerPortal();
+  const target = container ?? layer.container;
   return mode === "alert" ? (
-    <AlertDialogPrimitive.Portal data-slot="dialog-portal" {...props} />
+    <AlertDialogPrimitive.Portal
+      data-slot="dialog-portal"
+      container={target}
+      {...props}
+    />
   ) : (
-    <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />
+    <DialogPrimitive.Portal
+      data-slot="dialog-portal"
+      container={target}
+      {...props}
+    />
   );
 }
 
@@ -163,6 +350,13 @@ export function DialogClose({
   );
 }
 
+/**
+ * Alerta em animação de saída deixa de receber clique: o Dialog que a resposta abre em seguida fica
+ * na faixa de baixo e seria coberto pelo véu do alerta até a animação terminar. O `!` vence o
+ * `pointer-events` que o Radix grava no estilo do véu e do conteúdo.
+ */
+const answerClosingClasses = "data-[state=closed]:pointer-events-none!";
+
 /** Véu compartilhado por Dialog e Drawer: mesmo escurecimento e animação. */
 export const overlayClasses =
   "fixed inset-0 z-50 bg-black/30 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0";
@@ -172,17 +366,25 @@ export function DialogOverlay({
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
   const { mode } = useDialogContext();
-  const overlay = cn(overlayClasses, className);
+  const layer = useLayerPortal();
+  const internal = layer.container !== undefined || undefined;
   return mode === "alert" ? (
     <AlertDialogPrimitive.Overlay
       data-slot="dialog-overlay"
-      className={overlay}
+      {...{ [LAYER_MODAL_ATTRIBUTE]: internal }}
+      className={cn(
+        overlayClasses,
+        ANSWER_BAND_CLASS,
+        answerClosingClasses,
+        className,
+      )}
       {...props}
     />
   ) : (
     <DialogPrimitive.Overlay
       data-slot="dialog-overlay"
-      className={overlay}
+      {...{ [LAYER_MODAL_ATTRIBUTE]: internal }}
+      className={cn(overlayClasses, layer.zIndexClass, className)}
       {...props}
     />
   );
@@ -211,7 +413,11 @@ export function DialogContent({
   layout = "sectioned",
   "aria-describedby": ariaDescribedBy,
   onEscapeKeyDown,
+  onPointerDownOutside,
   onInteractOutside,
+  onCloseAutoFocus,
+  onKeyDown,
+  ref,
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Content> & {
   /** Mostra a ação “Fechar” no modo padrão. O modo `alert` exige uma resposta identificável. */
@@ -226,7 +432,32 @@ export function DialogContent({
   /** Anatomia da superfície: `sectioned` (default) ou `continuous` — ADR 0023. */
   layout?: SurfaceLayout;
 }) {
-  const { mode } = useDialogContext();
+  const { mode, open, modal } = useDialogContext();
+  const layer = useLayerPortal();
+  const internal = layer.container !== undefined;
+  // Seção 6 da ADR 0052: o alerta é resposta obrigatória; o modal portado para uma camada é
+  // interno a ela; os demais são de trabalho e convivem com a camada.
+  const mark: ModalMark =
+    mode === "alert" ? "answer" : internal ? "internal" : "work";
+  const entryRef = useModalLayerEntry({ open, modal, mark, surface: "dialog" });
+  const composedRef = useComposedRef(ref, entryRef);
+  const dismiss = composeModalDismissHandlers({
+    mark,
+    closeDisabled,
+    onEscapeKeyDown,
+    onPointerDownOutside,
+    onInteractOutside,
+    onCloseAutoFocus,
+  });
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>): void => {
+    onKeyDown?.(event);
+    handleModalTabKey(event);
+  };
+  // Os portais abertos daqui herdam a marca de modal quando este Dialog mora numa camada.
+  const nestedPortal = React.useMemo(
+    () => ({ ...layer, modalSubtree: layer.modalSubtree || internal }),
+    [layer, internal],
+  );
   const showClose = showCloseButton ?? mode !== "alert";
   const contentClasses =
     "fixed left-[50%] top-[50%] z-50 w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] overflow-clip rounded-xl border border-transparent bg-background text-foreground shadow-xl duration-200 outline-none [--surface-background:var(--background)] data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 dark:border-border/70";
@@ -236,25 +467,45 @@ export function DialogContent({
       <DialogPortal>
         <DialogOverlay />
         <AlertDialogPrimitive.Content
+          ref={composedRef}
           data-slot="dialog-content"
           data-mode="alert"
-          className={cn(contentClasses, "grid max-w-xs gap-4 p-6", className)}
+          {...{ [LAYER_MODAL_ATTRIBUTE]: internal || undefined }}
+          className={cn(
+            contentClasses,
+            ANSWER_BAND_CLASS,
+            answerClosingClasses,
+            "grid max-w-xs gap-4 p-6",
+            className,
+          )}
           aria-describedby={ariaDescribedBy}
-          onEscapeKeyDown={preventDismissWhen(closeDisabled, onEscapeKeyDown)}
+          // O `AlertDialog` do Radix cancela sozinho o clique fora; só o Esc é composto.
+          onEscapeKeyDown={dismiss.onEscapeKeyDown}
+          onCloseAutoFocus={dismiss.onCloseAutoFocus}
+          onKeyDown={onKeyDown}
           {...props}
         >
           {/* Sem anatomia seccionada (exceção da ADR 0023), mas a altura continua sendo
               decisão do diálogo: a cadeia `fill` da página não atravessa o portal. */}
           <FillBoundary>
-            <DialogContentContext.Provider
+            {/* Popover, Menu e Tooltip abertos daqui sobem para a faixa do alerta. */}
+            <LayerPortalProvider
               value={{
-                showCloseButton: false,
-                closeDisabled: true,
-                closeSize,
+                container: layer.container,
+                zIndexClass: ANSWER_BAND_CLASS,
+                modalSubtree: internal,
               }}
             >
-              {children}
-            </DialogContentContext.Provider>
+              <DialogContentContext.Provider
+                value={{
+                  showCloseButton: false,
+                  closeDisabled: true,
+                  closeSize,
+                }}
+              >
+                {children}
+              </DialogContentContext.Provider>
+            </LayerPortalProvider>
           </FillBoundary>
         </AlertDialogPrimitive.Content>
       </DialogPortal>
@@ -265,26 +516,34 @@ export function DialogContent({
     <DialogPortal>
       <DialogOverlay />
       <DialogPrimitive.Content
+        ref={composedRef}
         data-slot="dialog-content"
         data-mode="default"
         data-layout={layout}
+        {...{ [LAYER_MODAL_ATTRIBUTE]: internal || undefined }}
         className={cn(
           contentClasses,
           "flex max-h-[85vh] max-w-lg flex-col",
+          layer.zIndexClass,
           className,
         )}
         aria-describedby={ariaDescribedBy}
-        onEscapeKeyDown={preventDismissWhen(closeDisabled, onEscapeKeyDown)}
-        onInteractOutside={preventDismissWhen(closeDisabled, onInteractOutside)}
+        onEscapeKeyDown={dismiss.onEscapeKeyDown}
+        onPointerDownOutside={dismiss.onPointerDownOutside}
+        onInteractOutside={dismiss.onInteractOutside}
+        onCloseAutoFocus={dismiss.onCloseAutoFocus}
+        onKeyDown={handleKeyDown}
         {...props}
       >
-        <SurfaceLayoutProvider value={layout}>
-          <DialogContentContext.Provider
-            value={{ showCloseButton: showClose, closeDisabled, closeSize }}
-          >
-            {children}
-          </DialogContentContext.Provider>
-        </SurfaceLayoutProvider>
+        <LayerPortalProvider value={nestedPortal}>
+          <SurfaceLayoutProvider value={layout}>
+            <DialogContentContext.Provider
+              value={{ showCloseButton: showClose, closeDisabled, closeSize }}
+            >
+              {children}
+            </DialogContentContext.Provider>
+          </SurfaceLayoutProvider>
+        </LayerPortalProvider>
       </DialogPrimitive.Content>
     </DialogPortal>
   );

package/src/ui/components/primitives/drawer.tsx

@@ -18,7 +18,19 @@ import {
   type StructuralMediaProps,
 } from "../patterns/structural-media.tsx";
 import { CloseButton, type CloseButtonSize } from "./close-button.tsx";
-import { overlayClasses, preventDismissWhen } from "./dialog.tsx";
+import {
+  composeModalDismissHandlers,
+  overlayClasses,
+  useComposedRef,
+  useModalOpenState,
+} from "./dialog.tsx";
+import {
+  LAYER_MODAL_ATTRIBUTE,
+  LayerPortalProvider,
+  handleModalTabKey,
+  useLayerPortal,
+  useModalLayerEntry,
+} from "../../lib/modal-layers.ts";
 
 interface DrawerContentContextValue {
   showCloseButton: boolean;
@@ -34,10 +46,36 @@ const DrawerContentContext = React.createContext<DrawerContentContextValue>({
 
 const DrawerIntroContext = React.createContext(false);
 
+/** Estado de aberto que a pilha de modais da camada flutuante acompanha (ADR 0052). */
+const DrawerStateContext = React.createContext({ open: false, modal: true });
+
 function Drawer({
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+  modal,
   ...props
 }: React.ComponentProps<typeof DrawerPrimitive.Root>) {
-  return <DrawerPrimitive.Root data-slot="drawer" {...props} />;
+  const [open, setOpen] = useModalOpenState({
+    open: openProp,
+    defaultOpen,
+    onOpenChange,
+  });
+  const state = React.useMemo(
+    () => ({ open, modal: modal !== false }),
+    [open, modal],
+  );
+  return (
+    <DrawerStateContext.Provider value={state}>
+      <DrawerPrimitive.Root
+        data-slot="drawer"
+        modal={modal}
+        open={open}
+        onOpenChange={setOpen}
+        {...props}
+      />
+    </DrawerStateContext.Provider>
+  );
 }
 
 function DrawerTrigger({
@@ -53,19 +91,30 @@ function DrawerClose({
 }
 
 function DrawerPortal({
+  container,
   ...props
 }: React.ComponentProps<typeof DrawerPrimitive.Portal>) {
-  return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />;
+  // Aberto de dentro de uma camada flutuante, o Drawer vai para o hospedeiro dela (ADR 0052).
+  const layer = useLayerPortal();
+  return (
+    <DrawerPrimitive.Portal
+      data-slot="drawer-portal"
+      container={container ?? layer.container}
+      {...props}
+    />
+  );
 }
 
 function DrawerOverlay({
   className,
   ...props
 }: React.ComponentProps<typeof DrawerPrimitive.Overlay>) {
+  const layer = useLayerPortal();
   return (
     <DrawerPrimitive.Overlay
       data-slot="drawer-overlay"
-      className={cn(overlayClasses, className)}
+      {...{ [LAYER_MODAL_ATTRIBUTE]: layer.container !== undefined || undefined }}
+      className={cn(overlayClasses, layer.zIndexClass, className)}
       {...props}
     />
   );
@@ -95,7 +144,11 @@ function DrawerContent({
   layout = "sectioned",
   "aria-describedby": ariaDescribedBy,
   onEscapeKeyDown,
+  onPointerDownOutside,
   onInteractOutside,
+  onCloseAutoFocus,
+  onKeyDown,
+  ref,
   ...props
 }: React.ComponentProps<typeof DrawerPrimitive.Content> & {
   side?: "top" | "right" | "bottom" | "left";
@@ -109,12 +162,44 @@ function DrawerContent({
   /** Anatomia da superfície: `sectioned` (default) ou `continuous` — ADR 0023. */
   layout?: SurfaceLayout;
 }) {
+  const { open, modal } = React.useContext(DrawerStateContext);
+  const layer = useLayerPortal();
+  const internal = layer.container !== undefined;
+  // Seção 6 da ADR 0052: portado para uma camada, o Drawer é interno a ela; fora, é de trabalho.
+  const mark = internal ? "internal" : "work";
+  const entryRef = useModalLayerEntry({
+    open,
+    modal,
+    mark,
+    surface: "drawer",
+    side,
+  });
+  const composedRef = useComposedRef(ref, entryRef);
+  const dismiss = composeModalDismissHandlers({
+    mark,
+    closeDisabled,
+    onEscapeKeyDown,
+    onPointerDownOutside,
+    onInteractOutside,
+    onCloseAutoFocus,
+  });
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>): void => {
+    onKeyDown?.(event);
+    handleModalTabKey(event);
+  };
+  // Os portais abertos daqui herdam a marca de modal quando este Drawer mora numa camada.
+  const nestedPortal = React.useMemo(
+    () => ({ ...layer, modalSubtree: layer.modalSubtree || internal }),
+    [layer, internal],
+  );
   return (
     <DrawerPortal>
       <DrawerOverlay />
       <DrawerPrimitive.Content
+        ref={composedRef}
         data-slot="drawer-content"
         data-layout={layout}
+        {...{ [LAYER_MODAL_ATTRIBUTE]: internal || undefined }}
         className={cn(
           "fixed z-50 flex flex-col overflow-hidden rounded-xl border bg-background shadow-lg transition ease-in-out [--surface-background:var(--background)] data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:animate-in data-[state=open]:duration-500",
           side === "right" &&
@@ -125,20 +210,26 @@ function DrawerContent({
             "inset-x-1 top-1 h-auto data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
           side === "bottom" &&
             "inset-x-1 bottom-1 h-auto data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
+          layer.zIndexClass,
           className,
         )}
         aria-describedby={ariaDescribedBy}
-        onEscapeKeyDown={preventDismissWhen(closeDisabled, onEscapeKeyDown)}
-        onInteractOutside={preventDismissWhen(closeDisabled, onInteractOutside)}
+        onEscapeKeyDown={dismiss.onEscapeKeyDown}
+        onPointerDownOutside={dismiss.onPointerDownOutside}
+        onInteractOutside={dismiss.onInteractOutside}
+        onCloseAutoFocus={dismiss.onCloseAutoFocus}
+        onKeyDown={handleKeyDown}
         {...props}
       >
-        <SurfaceLayoutProvider value={layout}>
-          <DrawerContentContext.Provider
-            value={{ showCloseButton, closeDisabled, closeSize }}
-          >
-            {children}
-          </DrawerContentContext.Provider>
-        </SurfaceLayoutProvider>
+        <LayerPortalProvider value={nestedPortal}>
+          <SurfaceLayoutProvider value={layout}>
+            <DrawerContentContext.Provider
+              value={{ showCloseButton, closeDisabled, closeSize }}
+            >
+              {children}
+            </DrawerContentContext.Provider>
+          </SurfaceLayoutProvider>
+        </LayerPortalProvider>
       </DrawerPrimitive.Content>
     </DrawerPortal>
   );

package/src/ui/components/primitives/floating-layer.tsx

@@ -0,0 +1,79 @@
+import * as React from "react";
+import { createPortal } from "react-dom";
+
+import { cn } from "../../lib/cn.ts";
+import {
+  LayerPortalProvider,
+  registerFloatingLayer,
+} from "../../lib/modal-layers.ts";
+
+export interface FloatingLayerProps {
+  children: React.ReactNode;
+  /** Classes do hospedeiro. A posição de cada filho continua sendo do consumidor. */
+  className?: string;
+  /**
+   * Esc enquanto a pessoa está na camada, com ou sem modal aberto. É chamado uma vez por tecla.
+   * Nenhum modal fecha nesse caso, e o Opus não fecha a camada sozinho, porque o estado de aberto
+   * pertence ao consumidor.
+   */
+  onEscapeKeyDown?: (event: KeyboardEvent) => void;
+}
+
+/**
+ * Hospedeiro fixo, na tela inteira e acima dos modais de trabalho. Ele mesmo não recebe clique;
+ * os filhos diretos recebem, mesmo com o `body` bloqueado por um modal.
+ */
+const hostClasses =
+  "pointer-events-none fixed inset-0 z-60 *:pointer-events-auto";
+
+/**
+ * Região da aplicação que fica acima do conteúdo e dos modais de trabalho (Dialog e Drawer) e
+ * continua utilizável enquanto eles estão abertos, como o botão e o painel de um assistente
+ * (ADR 0052).
+ *
+ * Os filhos são portados para `div[data-slot="floating-layer"]` no `body`. O hospedeiro publica o
+ * modal de trabalho do topo em `data-modal` (`none`, `dialog` ou `drawer`) e o lado do Drawer em
+ * `data-modal-side`, para o consumidor reposicionar o que precisar. Popover, Menu, Tooltip, Dialog
+ * e Drawer abertos de dentro da camada vão para o mesmo hospedeiro.
+ */
+export function FloatingLayer({
+  children,
+  className,
+  onEscapeKeyDown,
+}: FloatingLayerProps) {
+  const [host, setHost] = React.useState<HTMLElement | null>(null);
+  const escapeRef = React.useRef(onEscapeKeyDown);
+  escapeRef.current = onEscapeKeyDown;
+
+  React.useLayoutEffect(() => {
+    const element = document.createElement("div");
+    element.setAttribute("data-slot", "floating-layer");
+    document.body.appendChild(element);
+    const unregister = registerFloatingLayer(element, (event) =>
+      escapeRef.current?.(event),
+    );
+    setHost(element);
+    // Desfaz o registro, retira o hospedeiro e, se o foco estava nele com um modal aberto,
+    // devolve o foco ao modal.
+    return unregister;
+  }, []);
+
+  React.useLayoutEffect(() => {
+    if (host !== null) host.className = cn(hostClasses, className);
+  }, [host, className]);
+
+  const portal = React.useMemo(
+    () => ({
+      container: host ?? undefined,
+      zIndexClass: undefined,
+      modalSubtree: false,
+    }),
+    [host],
+  );
+
+  if (host === null) return null;
+  return createPortal(
+    <LayerPortalProvider value={portal}>{children}</LayerPortalProvider>,
+    host,
+  );
+}