@softize/opus 25.0.0 → 25.1.0

package/docs/releasing.md

@@ -59,14 +59,20 @@ O token usado para publicar é exclusivamente o token do npm no `~/.npmrc` globa
 pra testar publicação seria a guarda atrapalhando quem está experimentando.
 
 **Gate de qualidade**: depois do bump e da materialização, mas antes de publicar, roda
-`pnpm typecheck` + `pnpm test` + `pnpm copy:check` + `base copy check` e **aborta a release
-se qualquer um falhar**. O Opus declara `@softize/base ^2.4.0` em `dependencies`, pois usa
+`pnpm typecheck` + `pnpm test` + `pnpm test:browser` + `pnpm copy:check` + `base copy check` e
+**aborta a release se qualquer um falhar**. O Opus declara `@softize/base ^2.4.0` em `dependencies`, pois usa
 suas APIs públicas de filesystem em runtime, e materializa os artefatos Base no próprio repo;
 a release não baixa uma política ad hoc. Como o
 Opus **ship source** (`.ts`, sem build), essa é a última barreira antes do tarball — sem ela,
 um `tsc` vermelho, inventário desatualizado ou violação da política vaza pro cliente. Emergência (evite):
 `pnpm release --skip-checks`.
 
+`pnpm test:browser` roda em Chromium real, pelo modo navegador do Vitest com Playwright, os testes
+que o `happy-dom` não reproduz com fidelidade, como o foco e o Tab da camada flutuante (ADR 0052).
+Ele fica fora do `pnpm test` para que o ciclo comum não dependa de navegador. O Chromium é o da
+revisão fixada pela versão exata do `playwright` nas devDependencies; se a estação não o tiver, o
+comando falha dizendo isso, e `pnpm exec playwright install chromium` o instala.
+
 O gate roda `pnpm test`, não `pnpm test:cov`: o threshold de 100% de cobertura em
 `vitest.config.ts` é uma meta aspiracional e **não** faz parte do gate de release. Uma release
 não é bloqueada por cobertura abaixo de 100%; a cobertura é acompanhada com `pnpm test:cov`.

package/docs/stacking-scale.md

@@ -0,0 +1,53 @@
+# Escala de empilhamento
+
+> **Status: decidido (out/2026).** As sobreposições do Opus ocupam quatro faixas de `z-index`,
+> definidas pela ADR 0052. Os valores são detalhe de implementação; a ordem entre as faixas é o
+> contrato.
+
+## Contexto
+
+Até a camada flutuante, toda sobreposição do Opus usava `z-50`: véu e conteúdo de Dialog e Drawer,
+Popover, Menu e Tooltip. A ordem no DOM desempatava, e o que abria depois ficava por cima. Isso
+bastava enquanto só existiam modais e sobreposições presas a um gatilho.
+
+A camada flutuante (`FloatingLayer`) precisa ficar acima de Dialog e Drawer e, ao mesmo tempo,
+abaixo dos diálogos de resposta obrigatória, que a cobrem com o véu (decisão 4 da seção 9 da ADR
+0052). A ordem no DOM não garante isso: o hospedeiro da camada é montado uma vez e continua no
+`body` enquanto modais abrem e fecham depois dele.
+
+## Decisão
+
+Do fundo para a frente:
+
+| Faixa                     | `z-index`     | Quem ocupa                                                                                     |
+| ------------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
+| Conteúdo                  | `auto`        | A página.                                                                                      |
+| Modal                     | `50`          | Dialog, Drawer, seus véus e Popover, Menu e Tooltip abertos fora da camada.                    |
+| Camada flutuante          | `60`          | O hospedeiro `div[data-slot="floating-layer"]`.                                                |
+| Resposta obrigatória      | `70`          | Véu e conteúdo de `Dialog mode="alert"`, que também serve às confirmações do `DialogHost`.     |
+| Avisos                    | `999999999`   | O `Toaster`, com o valor do Sonner.                                                            |
+
+- Dentro de uma faixa, a ordem no DOM continua desempatando, como antes.
+- O hospedeiro da camada cria um contexto de empilhamento próprio. Popover, Menu, Tooltip, Dialog e
+  Drawer abertos de dentro dela são portados para o hospedeiro e mantêm o `z-50` lá dentro, acima
+  do painel que os abriu.
+- Popover, Menu e Tooltip abertos de dentro de um alerta herdam a faixa do alerta (`z-70`); sem
+  isso, ficariam por baixo do véu que o próprio alerta desenha.
+- Componente novo que abre uma sobreposição usa as faixas acima e lê o contêiner da camada; o
+  teste `tests/architecture/floating-layer.test.ts` cobra o contêiner de todo portal.
+- Um alerta em animação de saída deixa de receber clique (`pointer-events: none`). Sem isso, o véu
+  dele, ainda em `z-70`, cobriria por cerca de 150 ms o Dialog que a resposta abre na faixa de
+  baixo.
+
+## Consequências
+
+- Um consumidor que posiciona elementos próprios com `z-index` acima de `50` passa a competir com a
+  camada. Use a camada para o que precisa ficar acima dos modais, em vez de subir o `z-index`.
+- Um elemento do consumidor com `z-index` entre `51` e `69` ficava acima de um alerta, que estava em
+  `z-50`, e agora fica abaixo dele.
+- Uma sobreposição de outra biblioteca que fixa `z-50` e é aberta de dentro de um alerta fica abaixo
+  do véu do alerta, porque não lê a faixa que os primitives do Opus herdam. Suba a faixa dela para
+  `z-70` ou troque-a por um primitive do Opus.
+- Mudar um valor exige mudar todos os pontos que dependem dele: `overlayClasses` e o conteúdo em
+  `dialog.tsx` e `drawer.tsx`, o hospedeiro em `floating-layer.tsx` e a faixa do alerta em
+  `modal-layers.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "25.0.0",
+  "version": "25.1.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -362,6 +362,7 @@
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.10.0",
     "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@tailwindcss/vite": "^4.3.2",
     "@tanstack/react-query": "^5.62.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",
@@ -371,6 +372,7 @@
     "@types/pg": "^8.11.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@vitest/browser": "2.1.9",
     "@vitest/coverage-v8": "^2.1.0",
     "better-sqlite3": "^11.0.0",
     "bullmq": "^5.0.0",
@@ -381,9 +383,11 @@
     "node-cron": "^3.0.3",
     "pg": "^8.13.0",
     "pino": "^9.5.0",
+    "playwright": "1.62.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-hook-form": "^7.54.0",
+    "tailwindcss": "^4.3.2",
     "tsx": "^4.19.0",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
@@ -400,6 +404,7 @@
     "copy:check": "node ./bin/cli.mjs copy --check",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
     "test:watch": "vitest",
     "test:cov": "vitest run --coverage",
     "registry:up": "npx -y verdaccio --config ~/.config/verdaccio/config.yaml",

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>
   );