@softize/opus 25.0.0 → 25.1.0

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,
+  );
+}

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

@@ -5,6 +5,7 @@ import { DropdownMenu as MenuPrimitive } from "radix-ui";
 
 import { useDismissOnIframeFocus } from "../../lib/dismiss-on-iframe.ts";
 import { cn } from "../../lib/cn.ts";
+import { layerModalMarker, useLayerPortal } from "../../lib/modal-layers.ts";
 
 function Menu({ ...props }: React.ComponentProps<typeof MenuPrimitive.Root>) {
   return <MenuPrimitive.Root data-slot="menu" {...props} />;
@@ -16,9 +17,17 @@ function Menu({ ...props }: React.ComponentProps<typeof MenuPrimitive.Root>) {
  * próxima versão major.
  */
 function MenuPortal({
+  container,
   ...props
 }: React.ComponentProps<typeof MenuPrimitive.Portal>) {
-  return <MenuPrimitive.Portal data-slot="menu-portal" {...props} />;
+  const layer = useLayerPortal();
+  return (
+    <MenuPrimitive.Portal
+      data-slot="menu-portal"
+      container={container ?? layer.container}
+      {...props}
+    />
+  );
 }
 
 function MenuTrigger({
@@ -35,14 +44,18 @@ function MenuContent({
   // Mesma razão do Popover: clique dentro de iframe não chega aqui fora.
   const ref = React.useRef<HTMLDivElement>(null);
   useDismissOnIframeFocus(ref);
+  // Aberto de dentro de uma camada flutuante, vai para o hospedeiro dela (ADR 0052).
+  const layer = useLayerPortal();
   return (
-    <MenuPrimitive.Portal>
+    <MenuPrimitive.Portal container={layer.container}>
       <MenuPrimitive.Content
         ref={ref}
         data-slot="menu-content"
+        {...layerModalMarker(layer)}
         sideOffset={sideOffset}
         className={cn(
           "z-50 max-h-(--radix-dropdown-menu-content-available-height) min-w-[10rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md will-change-[transform,opacity] 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",
+          layer.zIndexClass,
           className,
         )}
         {...props}
@@ -215,11 +228,13 @@ function MenuSubContent({
   className,
   ...props
 }: React.ComponentProps<typeof MenuPrimitive.SubContent>) {
+  const layer = useLayerPortal();
   return (
     <MenuPrimitive.SubContent
       data-slot="menu-sub-content"
       className={cn(
         "z-50 min-w-[10rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md will-change-[transform,opacity] 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",
+        layer.zIndexClass,
         className,
       )}
       {...props}

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

@@ -2,6 +2,7 @@ import * as React from "react"
 import { Popover as PopoverPrimitive } from "radix-ui"
 
 import { useDismissOnIframeFocus } from "../../lib/dismiss-on-iframe.ts"
+import { layerModalMarker, useLayerPortal } from "../../lib/modal-layers.ts"
 import { cn } from '../../lib/cn.ts'
 
 function Popover({
@@ -26,15 +27,19 @@ function PopoverContent({
   // pendurado sobre o conteúdo. Na cabine, o preview É um iframe.
   const ref = React.useRef<HTMLDivElement>(null)
   useDismissOnIframeFocus(ref)
+  // Aberto de dentro de uma camada flutuante, vai para o hospedeiro dela (ADR 0052).
+  const layer = useLayerPortal()
   return (
-    <PopoverPrimitive.Portal>
+    <PopoverPrimitive.Portal container={layer.container}>
       <PopoverPrimitive.Content
         ref={ref}
         data-slot="popover-content"
+        {...layerModalMarker(layer)}
         align={align}
         sideOffset={sideOffset}
         className={cn(
           "z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border border-border bg-popover p-4 text-popover-foreground shadow-md outline-hidden data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 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",
+          layer.zIndexClass,
           className
         )}
         {...props}

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

@@ -2,6 +2,7 @@ import * as React from "react"
 import { Tooltip as TooltipPrimitive } from "radix-ui"
 
 import { cn } from '../../lib/cn.ts'
+import { layerModalMarker, useLayerPortal } from "../../lib/modal-layers.ts"
 
 function TooltipProvider({
   delayDuration = 0,
@@ -34,13 +35,17 @@ function TooltipContent({
   children,
   ...props
 }: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  // Aberto de dentro de uma camada flutuante, vai para o hospedeiro dela (ADR 0052).
+  const layer = useLayerPortal()
   return (
-    <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Portal container={layer.container}>
       <TooltipPrimitive.Content
         data-slot="tooltip-content"
+        {...layerModalMarker(layer)}
         sideOffset={sideOffset}
         className={cn(
           "z-50 w-fit max-w-sm origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-foreground px-3 py-1.5 text-xs text-pretty text-background fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
+          layer.zIndexClass,
           className
         )}
         {...props}

package/src/ui/docs/content/dialog.md

@@ -441,6 +441,9 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Arqu
 - O comportamento selecionado por `mode` determina o papel de acessibilidade; `role` não configura
   o comportamento.
 - O foco permanece dentro do diálogo aberto e retorna ao gatilho após o fechamento.
+- No modo padrão, uma [`FloatingLayer`](/ui/floating-layer), como o painel de um assistente,
+  continua utilizável com o diálogo aberto: o Tab passa por ela, o foco não é puxado de volta e o Esc
+  age onde a pessoa está. O modo `alert` cobre a camada até a resposta.
 - `DialogHost` apresenta uma solicitação por vez para que cada resposta tenha um alvo inequívoco.
 
 ## Propriedades de Dialog

package/src/ui/docs/content/drawer.md

@@ -170,6 +170,9 @@ de continuar, use [`Dialog mode="alert"`](/ui/dialog), que não fecha pelo cliqu
 - Com `modal` ativo, o padrão, o foco permanece dentro do painel e o restante da página fica
   inacessível até o fechamento.
 - Ao fechar, o foco retorna ao gatilho.
+- Uma [`FloatingLayer`](/ui/floating-layer), como o painel de um assistente, continua utilizável
+  com o painel lateral aberto: o Tab passa por ela, o foco não é puxado de volta e o Esc age onde a
+  pessoa está. Ela recebe o lado do Drawer em `data-modal-side` para sair da frente dele.
 - O botão de fechar tem o nome acessível `Fechar`. Botões só com ícone no cabeçalho precisam de
   `aria-label`.
 

package/src/ui/docs/content/floating-layer.md

@@ -0,0 +1,178 @@
+Use `FloatingLayer` para uma região que acompanha a aplicação inteira e precisa continuar utilizável
+por cima de qualquer `Dialog` ou `Drawer`, como o botão e o painel de um assistente. Quem está
+preenchendo um formulário em um modal pode abrir o painel, perguntar e voltar ao formulário, que
+continua aberto e com o que já foi digitado.
+
+No exemplo, abra o formulário, digite um nome e use o assistente no canto inferior direito. O modal
+não fecha, e fechar o painel devolve o foco ao campo em que você estava.
+
+```tsx preview
+function AssistantDemo() {
+  const [editing, setEditing] = useState(false);
+  const [assistant, setAssistant] = useState(false);
+
+  return (
+    <>
+      <Dialog
+        open={editing}
+        onOpenChange={(open) => {
+          setEditing(open);
+          if (!open) setAssistant(false);
+        }}
+      >
+        <DialogTrigger asChild>
+          <Button variant="outline">Editar cliente</Button>
+        </DialogTrigger>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Editar cliente</DialogTitle>
+          </DialogHeader>
+          <DialogBody>
+            <Input aria-label="Nome do cliente" placeholder="Nome do cliente" />
+          </DialogBody>
+          <DialogFooter>
+            <DialogClose asChild>
+              <Button>Salvar</Button>
+            </DialogClose>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      {editing && (
+        <FloatingLayer onEscapeKeyDown={() => setAssistant(false)}>
+          {assistant ? (
+            <aside
+              aria-label="Assistente"
+              className="absolute right-4 bottom-4 flex w-80 flex-col gap-3 rounded-xl border border-border bg-background p-4 shadow-lg"
+            >
+              <p className="text-sm">Pergunte sobre o cliente que você está editando.</p>
+              <Textarea aria-label="Mensagem" placeholder="Sua pergunta" />
+              <Button variant="ghost" onClick={() => setAssistant(false)}>
+                Fechar o assistente
+              </Button>
+            </aside>
+          ) : (
+            <Button className="absolute right-4 bottom-4" onClick={() => setAssistant(true)}>
+              Abrir o assistente
+            </Button>
+          )}
+        </FloatingLayer>
+      )}
+    </>
+  );
+}
+
+render(<AssistantDemo />);
+```
+
+O exemplo monta a camada só enquanto o formulário está aberto para não deixar um botão fixo nesta
+página. Em uma aplicação, a camada costuma ficar montada o tempo todo, na raiz.
+
+## Posicionar os filhos
+
+`FloatingLayer` porta os filhos para um hospedeiro próprio, `div[data-slot="floating-layer"]`, no
+fim do `body`. O hospedeiro ocupa a janela inteira, fica acima dos modais e não recebe clique; cada
+filho direto recebe. Por isso, posicione cada filho com `absolute` contra a janela, como `right-4
+bottom-4`, e não espere que ele siga a moldura da página.
+
+Com um modal aberto, o hospedeiro informa qual `Dialog` ou `Drawer` está no topo. Diálogos que exigem
+resposta não entram nesse sinal, porque cobrem a camada enquanto estão abertos:
+
+- `data-modal` vale `none`, `dialog` ou `drawer`;
+- `data-modal-side` traz o lado do Drawer: `left`, `right`, `top` ou `bottom`.
+
+O Opus não desloca nem redimensiona modais por causa da camada. Use esses atributos para tirar o
+painel de cima do que a pessoa precisa ver. Um Drawer abre, por padrão, do lado direito, o mesmo
+canto do botão do exemplo; com a variante `in-data-*` do Tailwind, o painel troca de lado enquanto
+esse Drawer estiver aberto:
+
+```tsx
+<aside
+  aria-label="Assistente"
+  className="absolute right-4 bottom-4 in-data-[modal-side=right]:right-auto in-data-[modal-side=right]:left-4"
+>
+  …
+</aside>
+```
+
+Podem existir várias camadas ao mesmo tempo. A que monta depois fica por cima.
+
+## O que muda enquanto um modal está aberto
+
+Sem nenhum modal aberto, a camada é uma região comum da página. Com um `Dialog` ou `Drawer` aberto,
+o modal passa a tratar a camada como parte de dentro dele:
+
+| Aspecto         | Comportamento                                                                                          |
+| --------------- | ------------------------------------------------------------------------------------------------------ |
+| Clique          | A camada recebe clique e não fecha o modal, mesmo que o elemento clicado suma no próprio clique.       |
+| Véu             | Clicar no véu continua fechando o modal, respeitando `closeDisabled`.                                  |
+| Foco            | O foco pode ir para a camada por clique ou por código e não é puxado de volta.                         |
+| Tab             | Depois do último elemento do modal vem a camada; depois da camada, o primeiro elemento do modal.       |
+| Rolagem         | A camada rola; a página atrás continua travada.                                                        |
+| Leitor de tela  | O modal e a camada ficam visíveis; o resto da página continua escondido.                               |
+
+Quando o painel fecha com o foco dentro dele, ou a camada inteira sai da tela, o foco volta ao
+elemento do modal que a pessoa usava antes de entrar na camada. Se esse elemento não existir mais,
+vai para o primeiro elemento do modal. No sentido inverso, um modal que fecha enquanto a pessoa
+digita na camada não leva o foco de volta ao botão que o abriu: o foco fica na camada.
+
+Os patterns construídos sobre `Dialog` e `Drawer`, como [`ActionFormDialog`](/ui/action-form-dialog),
+[`ActionListDialog`](/ui/action-list-dialog) e [`Presentation`](/ui/presentation), ganham esse
+comportamento sem nenhuma configuração.
+
+## Esc
+
+O Esc age onde a pessoa está. Com o foco na camada, ou depois de um clique em uma área do painel que
+não recebe foco, nenhum modal fecha e o Opus chama `onEscapeKeyDown` uma vez por tecla. Com o foco
+no modal, o Esc fecha o modal, como sempre. Sem modal aberto, `onEscapeKeyDown` também é chamado
+quando a pessoa está na camada.
+
+Trate o Esc da camada só por `onEscapeKeyDown`. Para impedir que o modal feche, o Opus marca o evento
+com `preventDefault` antes de ele chegar aos elementos da camada; um `onKeyDown` próprio para Esc no
+painel trataria a tecla duas vezes ou leria um evento já marcado.
+
+Um popover ou menu aberto dentro da camada fecha primeiro, e só o Esc seguinte chega a ela. O mesmo
+vale, no sentido inverso, para um popover aberto dentro do modal: ele fecha antes, mesmo com a
+pessoa na camada.
+
+## Conteúdo aberto de dentro da camada
+
+`Popover`, `Menu`, `Tooltip`, `Select`, `Dialog` e `Drawer` abertos de dentro da camada vão para o
+hospedeiro dela. Assim, o menu de uma conversa abre por cima do painel que o abriu, e não por baixo
+dele.
+
+Um `Dialog` ou `Drawer` aberto de dentro da camada é modal para tudo, inclusive para a própria
+camada: prende o foco, fecha pelo véu e pelo Esc e não chama o `onEscapeKeyDown` da camada.
+
+## Diálogos de resposta obrigatória
+
+`Dialog mode="alert"` e as confirmações de [`dialog.confirm`](/ui/dialog) exigem uma resposta antes
+de qualquer outra coisa. Enquanto um deles está aberto, o véu dele cobre a camada, o foco não chega
+a ela e o leitor de tela a esconde. Isso vale também para um `Dialog` aberto de dentro do alerta.
+Ao responder, a camada volta a funcionar com o modal que estava aberto antes.
+
+## Rolagem no toque
+
+Num arrasto de toque, a rolagem que chega ao fim de uma área do painel pode passar a rolar a página
+atrás do modal. Aplique `overscroll-contain` nas áreas roláveis da camada, como o histórico de uma
+conversa. A propriedade só age no contêiner que rola, por isso o Opus não consegue aplicá-la por
+você.
+
+## Acessibilidade
+
+- O hospedeiro não tem papel ARIA. Dê semântica aos filhos, como um `aside` com `aria-label` para o
+  painel e um nome claro para o botão que o abre.
+- O hospedeiro carrega `aria-live="off"`, o valor padrão do atributo: a camada não anuncia mudanças
+  por conta própria, e regiões vivas de dentro dela, como a de um [`Ask`](/ui/ask), mantêm o próprio
+  comportamento. O atributo é o que mantém a camada visível ao leitor de tela com um modal aberto.
+- O foco e o Tab descritos acima são verificados em Chromium por testes automatizados. Safari,
+  Firefox e a leitura com VoiceOver ainda não foram verificados: o roteiro manual da ADR 0052 roda
+  na adoção pela Grand Brasil, em Safari com VoiceOver e no Firefox, antes de ela chegar à versão
+  principal da plataforma. Leitores de tela do Windows, como o NVDA, ficam fora dessa verificação.
+
+## Propriedades de FloatingLayer
+
+| Propriedade       | Tipo                             | Padrão | Descrição                                                                                                                                            |
+| ----------------- | -------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`        | `ReactNode`                      |        | Elementos da camada. Cada filho direto recebe clique e se posiciona contra a janela.                                                                 |
+| `className`       | `string`                         |        | Classes do hospedeiro. A posição de cada filho continua sendo sua.                                                                                   |
+| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` |        | Chamado uma vez por tecla quando a pessoa aperta Esc na camada, com ou sem modal aberto. Nenhum modal fecha nesse caso, e o Opus não fecha a camada. |

package/src/ui/docs/registry.tsx

@@ -78,6 +78,7 @@ import detailMd from "./content/detail.md?raw";
 import dictionaryValueMd from "./content/dictionary-value.md?raw";
 import emptyValueMd from "./content/empty-value.md?raw";
 import drawerMd from "./content/drawer.md?raw";
+import floatingLayerMd from "./content/floating-layer.md?raw";
 import menuMd from "./content/menu.md?raw";
 import emptyMd from "./content/empty.md?raw";
 import fieldMd from "./content/field.md?raw";
@@ -793,6 +794,11 @@ export const UI_SECTIONS: DocSection[] = [
             title: "Drawer",
             render: comp("Drawer", "drawer", drawerMd),
           },
+          {
+            slug: "floating-layer",
+            title: "Floating Layer",
+            render: comp("Floating Layer", "floating-layer", floatingLayerMd),
+          },
           { slug: "menu", title: "Menu", render: comp("Menu", "menu", menuMd) },
           {
             slug: "popover",

package/src/ui/lib/dismiss-on-iframe.ts

@@ -1,13 +1,16 @@
 import * as React from 'react'
 
 /**
- * Fecha a camada flutuante quando o clique cai DENTRO de um iframe.
+ * Fecha um popover ou menu aberto quando o clique cai DENTRO de um iframe.
  *
  * O navegador entrega o clique ao documento do iframe, e o documento de fora nunca fica
  * sabendo. Como toda dispensa por "clique fora" escuta eventos do documento de fora, o
  * popover/menu simplesmente NÃO fecha — fica pendurado sobre o conteúdo, e a pessoa
  * precisa achar um pedaço de página livre pra clicar.
  *
+ * Não confundir com a camada flutuante (`FloatingLayer`, ADR 0052), a região que convive com
+ * Dialog e Drawer modais; aqui o assunto são sobreposições transitórias presas a um gatilho.
+ *
  * Não é caso de borda pra nós: a cabine embute o preview num iframe, então metade da tela
  * é justamente a área onde clicar não fecha nada.
  *