@softize/opus 25.0.0 → 25.2.0

package/src/ui/lib/modal-layers.ts

@@ -0,0 +1,547 @@
+import * as React from "react";
+
+/**
+ * Registro das camadas flutuantes e pilha dos modais do Opus (ADR 0052).
+ *
+ * Uma camada flutuante, como o FAB e o painel de um assistente, continua utilizável enquanto um
+ * Dialog ou Drawer modal está aberto. O modo modal do Radix continua valendo; este módulo abre
+ * exceções nas bordas dele, e só enquanto o topo da pilha é um modal **de trabalho**:
+ *
+ * - o aperto do ponteiro que nasce num hospedeiro fica registrado, e o Dialog e o Drawer não fecham
+ *   por ele, mesmo que o elemento apertado suma antes de o clique terminar;
+ * - um único ouvinte no `body`, em borbulha, impede que `focusin`, `focusout`, `wheel` e `touchmove`
+ *   ligados ao hospedeiro cheguem ao documento, onde a trava de foco do Radix e a trava de rolagem
+ *   os veriam;
+ * - o Esc age onde a pessoa está: na camada, chama o `onEscapeKeyDown` dela e não fecha o modal;
+ * - o Tab passa do último elemento do modal para a camada e da camada de volta ao modal;
+ * - quando o elemento focado da camada some, o foco volta ao modal;
+ * - o hospedeiro carrega `aria-live="off"`, que faz o `hideOthers` do Radix preservá-lo.
+ *
+ * Com um modal de resposta obrigatória (`mode="alert"`, `DialogHost`) ou um modal aberto de dentro
+ * da camada no topo, todas as exceções ficam suspensas e esse modal age sobre a camada como sobre o
+ * resto da página.
+ *
+ * O registro é um valor global do módulo, como o contexto do `DismissableLayer` do Radix: funciona
+ * com o `DialogHost`, fora do `OpusProvider` e nos exemplos da documentação, sem provider.
+ */
+
+/** Papel de um modal na pilha (seção 6 da ADR 0052). */
+export type ModalMark = "work" | "answer" | "internal";
+export type ModalSurface = "dialog" | "drawer";
+export type ModalSide = "top" | "right" | "bottom" | "left";
+
+interface ModalEntry {
+  mark: ModalMark;
+  surface: ModalSurface;
+  side: ModalSide | undefined;
+  content: HTMLElement | null;
+}
+
+interface LayerRecord {
+  host: HTMLElement;
+  escape: (event: KeyboardEvent) => void;
+  dispose: () => void;
+}
+
+/** Marca o conteúdo e o véu de um modal portado para um hospedeiro: nunca contam como camada. */
+export const LAYER_MODAL_ATTRIBUTE = "data-floating-layer-modal";
+
+const layers: LayerRecord[] = [];
+const stack: ModalEntry[] = [];
+const layerPointerEvents = new WeakSet<Event>();
+/** Camada do último aperto do ponteiro; decide onde a pessoa está quando o foco está no `body`. */
+let pointerLayer: LayerRecord | null = null;
+/**
+ * Filho direto do hospedeiro que contém o alvo desse aperto, como o painel inteiro. Quando ele sai
+ * do hospedeiro, o aperto deixa de dizer onde a pessoa está. O alvo em si não serve de âncora: o
+ * texto de uma resposta em streaming é trocado a cada pedaço, e a pessoa continua no painel.
+ */
+let pointerAnchor: Element | null = null;
+/** Último elemento focado dentro de uma camada, enquanto a pessoa não sai dela. */
+let layerFocus: Element | null = null;
+/** Último elemento focado fora das camadas: o destino da volta do foco (decisão 3 da seção 9). */
+let outsideFocus: Element | null = null;
+let restoreTimer: ReturnType<typeof setTimeout> | undefined;
+
+function topEntry(): ModalEntry | undefined {
+  return stack[stack.length - 1];
+}
+
+function topWorkEntry(): ModalEntry | undefined {
+  for (let index = stack.length - 1; index >= 0; index -= 1) {
+    if (stack[index]!.mark === "work") return stack[index];
+  }
+  return undefined;
+}
+
+/**
+ * Há na pilha um modal que suspende as exceções: de resposta obrigatória ou interno à camada.
+ * Basta um, em qualquer posição: um Dialog aberto de dentro de um alerta fica no topo como modal
+ * de trabalho, mas o alerta continua exigindo resposta e cobrindo a camada (decisão 4 da seção 9).
+ */
+function suspendingModalOpen(): boolean {
+  return stack.some((entry) => entry.mark !== "work");
+}
+
+/** As exceções da ADR só valem com uma camada montada, um modal de trabalho no topo e nenhum que as suspenda. */
+export function layerExemptionsActive(): boolean {
+  return (
+    layers.length > 0 && topEntry()?.mark === "work" && !suspendingModalOpen()
+  );
+}
+
+function layerOf(node: unknown): LayerRecord | null {
+  if (typeof Node === "undefined" || !(node instanceof Node)) return null;
+  for (const layer of layers) {
+    if (!layer.host.contains(node)) continue;
+    const element = node instanceof Element ? node : node.parentElement;
+    // A subárvore de um modal aberto de dentro da camada é modal, não camada (seção 6).
+    if (element?.closest(`[${LAYER_MODAL_ATTRIBUTE}]`)) return null;
+    return layer;
+  }
+  return null;
+}
+
+function bodyHasFocus(): boolean {
+  const active = document.activeElement;
+  return (
+    active === null ||
+    active === document.body ||
+    active === document.documentElement
+  );
+}
+
+/**
+ * Onde a pessoa está: o foco decide primeiro; com o foco no `body`, decide o último aperto do
+ * ponteiro (seção 5).
+ */
+function layerWherePersonIs(): LayerRecord | null {
+  if (!bodyHasFocus()) return layerOf(document.activeElement);
+  return pointerLayer !== null && layers.includes(pointerLayer)
+    ? pointerLayer
+    : null;
+}
+
+function syncHosts(): void {
+  const suspended = suspendingModalOpen();
+  const work = topWorkEntry();
+  for (const { host } of layers) {
+    // O `hideOthers` preserva todo `[aria-live]` e não desce nele. Retirar o atributo antes do
+    // `hideOthers` de um modal que suspende as exceções deixa esse modal esconder a camada.
+    if (suspended) host.removeAttribute("aria-live");
+    else host.setAttribute("aria-live", "off");
+    host.setAttribute("data-modal", work?.surface ?? "none");
+    if (work?.surface === "drawer" && work.side !== undefined) {
+      host.setAttribute("data-modal-side", work.side);
+    } else {
+      host.removeAttribute("data-modal-side");
+    }
+  }
+}
+
+/** Elementos alcançáveis pelo Tab dentro de `root`, na ordem do documento. */
+function tabbables(root: HTMLElement): HTMLElement[] {
+  const nodes: HTMLElement[] = [];
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, {
+    acceptNode(node) {
+      const element = node as HTMLElement;
+      if (element.hasAttribute(LAYER_MODAL_ATTRIBUTE) && element !== root) {
+        return NodeFilter.FILTER_REJECT;
+      }
+      const hiddenInput =
+        element.tagName === "INPUT" &&
+        (element as HTMLInputElement).type === "hidden";
+      if (
+        (element as HTMLButtonElement).disabled ||
+        element.hidden ||
+        hiddenInput
+      ) {
+        return NodeFilter.FILTER_SKIP;
+      }
+      return element.tabIndex >= 0
+        ? NodeFilter.FILTER_ACCEPT
+        : NodeFilter.FILTER_SKIP;
+    },
+  });
+  while (walker.nextNode()) nodes.push(walker.currentNode as HTMLElement);
+  return nodes.filter(
+    (element) =>
+      typeof element.checkVisibility !== "function" ||
+      element.checkVisibility({ checkVisibilityCSS: true }),
+  );
+}
+
+function focusFromKeyboard(element: HTMLElement): void {
+  element.focus();
+  // O Tab do navegador seleciona o texto do campo que recebe o foco; a passagem manual imita.
+  if (element instanceof HTMLInputElement && typeof element.select === "function") {
+    element.select();
+  }
+}
+
+/**
+ * Regiões do ciclo do Tab (decisão 2 da seção 9): o modal de trabalho do topo e as camadas, na
+ * ordem de montagem. Devolve o destino a partir da região `from`, ou `null` quando nenhuma outra
+ * região tem onde parar.
+ */
+function tabTarget(from: number, forward: boolean): HTMLElement | null {
+  const content = topEntry()?.content;
+  if (content === null || content === undefined) return null;
+  const regions = [content, ...layers.map((layer) => layer.host)];
+  for (let step = 1; step < regions.length + 1; step += 1) {
+    const index =
+      (from + (forward ? step : -step) + regions.length * 2) % regions.length;
+    if (index === from) return null;
+    const candidates = tabbables(regions[index]!);
+    if (candidates.length === 0) continue;
+    return forward ? candidates[0]! : candidates[candidates.length - 1]!;
+  }
+  return null;
+}
+
+function isTabKey(event: KeyboardEvent | React.KeyboardEvent): boolean {
+  return (
+    event.key === "Tab" && !event.altKey && !event.ctrlKey && !event.metaKey
+  );
+}
+
+/**
+ * Tab no modal de trabalho do topo: do último elemento vai para a camada, e o Shift+Tab do
+ * primeiro vai para o último elemento da camada. Roda antes do laço do Radix, que não age quando
+ * o foco já saiu do elemento da borda.
+ */
+export function handleModalTabKey(
+  event: React.KeyboardEvent<HTMLElement>,
+): void {
+  if (!isTabKey(event) || event.defaultPrevented || !layerExemptionsActive()) {
+    return;
+  }
+  const content = event.currentTarget;
+  if (topEntry()?.content !== content) return;
+  const candidates = tabbables(content);
+  const active = document.activeElement;
+  const atEdge =
+    candidates.length === 0
+      ? active === content
+      : event.shiftKey
+        ? active === candidates[0]
+        : active === candidates[candidates.length - 1];
+  if (!atEdge) return;
+  const target = tabTarget(0, !event.shiftKey);
+  if (target === null) return;
+  event.preventDefault();
+  focusFromKeyboard(target);
+}
+
+/** Para onde o foco volta quando sai da camada (decisão 3 da seção 9). */
+function modalFocusTarget(): HTMLElement | null {
+  const content = topEntry()?.content;
+  if (content === null || content === undefined) return null;
+  return outsideFocus instanceof HTMLElement &&
+    outsideFocus.isConnected &&
+    content.contains(outsideFocus)
+    ? outsideFocus
+    : (tabbables(content)[0] ?? content);
+}
+
+function restoreFocusToModal(): void {
+  modalFocusTarget()?.focus({ preventScroll: true });
+}
+
+/**
+ * O foco está numa camada, fora de qualquer modal aberto de dentro dela. Um modal que fecha nesse
+ * momento não deve levar o foco ao gatilho dele: a pessoa está digitando na camada.
+ */
+export function focusIsInLayer(): boolean {
+  return layerOf(document.activeElement) !== null;
+}
+
+/** O ouvinte único no `body` (seção 8): a trava do Radix não vê a passagem pela camada. */
+function shieldDocumentListeners(event: Event): void {
+  if (!layerExemptionsActive()) return;
+  if (event.type === "focusout") {
+    const { relatedTarget } = event as FocusEvent;
+    if (layerOf(event.target) !== null || layerOf(relatedTarget) !== null) {
+      event.stopPropagation();
+    }
+    return;
+  }
+  if (layerOf(event.target) !== null) event.stopPropagation();
+}
+
+/** O filho direto de `host` que contém `node`. */
+function hostChildOf(host: HTMLElement, node: Node): Element | null {
+  let current: Node | null = node;
+  while (current !== null && current.parentNode !== host) {
+    current = current.parentNode;
+  }
+  return current instanceof Element ? current : null;
+}
+
+function trackPointer(event: PointerEvent): void {
+  pointerLayer = layerOf(event.target);
+  pointerAnchor =
+    pointerLayer === null
+      ? null
+      : hostChildOf(pointerLayer.host, event.target as Node);
+  if (pointerLayer === null) layerFocus = null;
+}
+
+function trackFocus(event: FocusEvent): void {
+  if (layerOf(event.target) !== null) {
+    layerFocus = event.target as Element;
+    return;
+  }
+  layerFocus = null;
+  outsideFocus = event.target as Element;
+}
+
+const SHIELDED_EVENTS = ["focusin", "focusout", "wheel", "touchmove"] as const;
+
+function installGlobalListeners(): void {
+  for (const type of SHIELDED_EVENTS) {
+    document.body.addEventListener(type, shieldDocumentListeners, {
+      passive: true,
+    });
+  }
+  document.addEventListener("pointerdown", trackPointer, true);
+  document.addEventListener("focusin", trackFocus, true);
+}
+
+function removeGlobalListeners(): void {
+  for (const type of SHIELDED_EVENTS) {
+    document.body.removeEventListener(type, shieldDocumentListeners);
+  }
+  document.removeEventListener("pointerdown", trackPointer, true);
+  document.removeEventListener("focusin", trackFocus, true);
+  pointerLayer = null;
+  pointerAnchor = null;
+  layerFocus = null;
+  outsideFocus = null;
+  clearTimeout(restoreTimer);
+}
+
+/**
+ * Registra um hospedeiro de camada. O registro mantém os ouvintes enquanto houver ao menos uma
+ * camada montada; sem camada, os modais se comportam exatamente como antes. A função devolvida
+ * desfaz o registro e retira o hospedeiro do DOM.
+ */
+export function registerFloatingLayer(
+  host: HTMLElement,
+  escape: (event: KeyboardEvent) => void,
+): () => void {
+  const onPointerDown = (event: PointerEvent): void => {
+    // Pertença decidida no aperto: no fim do clique, o elemento apertado pode já ter sumido.
+    if (layerOf(event.target) !== null) layerPointerEvents.add(event);
+  };
+  // No documento, em borbulha: roda depois dos `onKeyDown` do React de dentro da camada, que
+  // podem tratar o Tab e marcá-lo com `preventDefault`.
+  const onKeyDown = (event: KeyboardEvent): void => {
+    if (!isTabKey(event) || event.defaultPrevented) return;
+    if (!layerExemptionsActive() || layerOf(document.activeElement) !== record) {
+      return;
+    }
+    const candidates = tabbables(host);
+    const edge = event.shiftKey
+      ? candidates[0]
+      : candidates[candidates.length - 1];
+    if (document.activeElement !== edge) return;
+    const target = tabTarget(layers.indexOf(record) + 1, !event.shiftKey);
+    if (target === null) return;
+    event.preventDefault();
+    focusFromKeyboard(target);
+  };
+  const onDocumentKeyDown = (event: KeyboardEvent): void => {
+    // Com um modal de trabalho aberto, a composição do modal já tratou o Esc e o marcou.
+    if (event.key !== "Escape" || event.defaultPrevented) return;
+    if (layerWherePersonIs() === record) escape(event);
+  };
+  const observer = new MutationObserver(() => {
+    if (pointerAnchor !== null && pointerAnchor.parentNode !== pointerLayer?.host) {
+      // O painel apertado saiu da camada, como quando é fechado por código e vira o FAB.
+      pointerAnchor = null;
+      pointerLayer = null;
+    }
+    // Decisão 3 da seção 9: o elemento focado da camada sumiu e o foco caiu no `body`.
+    if (!layerExemptionsActive() || layerFocus === null) return;
+    if (layerFocus.isConnected || !bodyHasFocus()) return;
+    layerFocus = null;
+    clearTimeout(restoreTimer);
+    // Uma tarefa depois: quem trocou o conteúdo da camada pode levar o foco a outro elemento dela.
+    restoreTimer = setTimeout(() => {
+      if (layerExemptionsActive() && bodyHasFocus()) restoreFocusToModal();
+    }, 0);
+  });
+
+  const record: LayerRecord = {
+    host,
+    escape,
+    dispose: () => {
+      host.removeEventListener("pointerdown", onPointerDown, true);
+      document.removeEventListener("keydown", onKeyDown);
+      document.removeEventListener("keydown", onDocumentKeyDown);
+      observer.disconnect();
+    },
+  };
+
+  if (layers.length === 0) installGlobalListeners();
+  layers.push(record);
+  host.addEventListener("pointerdown", onPointerDown, true);
+  document.addEventListener("keydown", onKeyDown);
+  document.addEventListener("keydown", onDocumentKeyDown);
+  observer.observe(host, { childList: true, subtree: true });
+  syncHosts();
+
+  return () => {
+    // A camada sai com o foco dentro dela e um modal aberto: sem isto, o foco cairia no `body`,
+    // porque o observador desligado abaixo não chega a ver a remoção.
+    const focusTarget =
+      layerExemptionsActive() && host.contains(document.activeElement)
+        ? modalFocusTarget()
+        : null;
+    record.dispose();
+    const index = layers.indexOf(record);
+    if (index !== -1) layers.splice(index, 1);
+    if (pointerLayer === record) {
+      pointerLayer = null;
+      pointerAnchor = null;
+    }
+    host.remove();
+    focusTarget?.focus({ preventScroll: true });
+    if (layers.length === 0) removeGlobalListeners();
+    else syncHosts();
+  };
+}
+
+/** Evento de “fora” (clique ou foco) que nasceu numa camada enquanto as exceções valem. */
+export function isLayerInteraction(event: {
+  detail: { originalEvent: Event };
+}): boolean {
+  if (!layerExemptionsActive()) return false;
+  const original = event.detail.originalEvent;
+  if (layerPointerEvents.has(original)) return true;
+  return original.type === "focusin" && layerOf(original.target) !== null;
+}
+
+/**
+ * Esc no modal de trabalho do topo com a pessoa na camada: nenhum modal fecha e a camada recebe a
+ * tecla uma única vez. O `preventDefault` impede o Radix de fechar e marca o evento para o ouvinte
+ * da própria camada, que ignora eventos já tratados.
+ */
+export function routeEscapeToLayer(event: KeyboardEvent): boolean {
+  if (!layerExemptionsActive()) return false;
+  const layer = layerWherePersonIs();
+  if (layer === null) return false;
+  event.preventDefault();
+  layer.escape(event);
+  return true;
+}
+
+/**
+ * Compõe uma isenção da camada antes de um handler de dispensa do modal. A isenção vem primeiro e
+ * interrompe a cadeia, como o `DismissableLayer.Branch` do Radix: um evento nascido na camada é de
+ * dentro do modal e não chega ao handler do consumidor.
+ */
+export function exemptLayerFirst<E extends { preventDefault(): void }>(
+  exempt: (event: E) => boolean,
+  handler: ((event: E) => void) | undefined,
+): (event: E) => void {
+  return (event) => {
+    if (exempt(event)) {
+      event.preventDefault();
+      return;
+    }
+    handler?.(event);
+  };
+}
+
+/**
+ * Registra um modal na pilha enquanto ele está aberto. O registro e a retirada acontecem em
+ * efeito de layout: antes do `hideOthers` do modal que abre (efeito comum, num commit posterior,
+ * porque o portal do Radix monta o conteúdo depois) e quando o modal **fecha**, não quando
+ * desmonta, já que o `Presence` o mantém montado durante a animação de saída.
+ */
+export function useModalLayerEntry({
+  open,
+  modal,
+  mark,
+  surface,
+  side,
+}: {
+  open: boolean;
+  modal: boolean;
+  mark: ModalMark;
+  surface: ModalSurface;
+  side?: ModalSide;
+}): (node: HTMLElement | null) => void {
+  const entry = React.useRef<ModalEntry | null>(null);
+  entry.current ??= { mark, surface, side, content: null };
+  const current = entry.current;
+
+  React.useLayoutEffect(() => {
+    if (
+      current.mark === mark &&
+      current.surface === surface &&
+      current.side === side
+    ) {
+      return;
+    }
+    current.mark = mark;
+    current.surface = surface;
+    current.side = side;
+    if (stack.includes(current)) syncHosts();
+  }, [current, mark, surface, side]);
+
+  React.useLayoutEffect(() => {
+    if (!open || !modal) return;
+    stack.push(current);
+    syncHosts();
+    return () => {
+      const index = stack.indexOf(current);
+      if (index !== -1) stack.splice(index, 1);
+      syncHosts();
+    };
+  }, [current, open, modal]);
+
+  return React.useCallback(
+    (node: HTMLElement | null) => {
+      current.content = node;
+    },
+    [current],
+  );
+}
+
+interface LayerPortal {
+  /** Onde os primitives com portal montam o conteúdo; `undefined` é o `body`. */
+  container: HTMLElement | undefined;
+  /** Faixa de empilhamento herdada pelos portais abertos de dentro de um modal de resposta. */
+  zIndexClass: string | undefined;
+  /**
+   * Os portais saem de dentro de um modal portado para uma camada. Eles vão para o hospedeiro como
+   * irmãos desse modal e precisam da mesma marca para nunca contar como camada (seção 6).
+   */
+  modalSubtree: boolean;
+}
+
+const LayerPortalContext = React.createContext<LayerPortal>({
+  container: undefined,
+  zIndexClass: undefined,
+  modalSubtree: false,
+});
+
+/** Atributo que marca o conteúdo de um portal aberto de dentro de um modal interno à camada. */
+export function layerModalMarker(
+  portal: LayerPortal,
+): Record<string, true | undefined> {
+  return { [LAYER_MODAL_ATTRIBUTE]: portal.modalSubtree || undefined };
+}
+
+/** Contêiner e faixa dos portais abertos daqui (seção 3 da ADR 0052). */
+export function useLayerPortal(): LayerPortal {
+  return React.useContext(LayerPortalContext);
+}
+
+export const LayerPortalProvider = LayerPortalContext.Provider;
+
+/** Faixa de resposta obrigatória: acima da camada flutuante (decisão 4 da seção 9). */
+export const ANSWER_BAND_CLASS = "z-70";

package/src/ui/meta.ts

@@ -257,6 +257,12 @@ export const componentMeta = {
     whenToUse:
       "Esconda um bloco secundário atrás de um gatilho, mantendo o restante da tela visível. Componha Collapsible > (CollapsibleTrigger + CollapsibleContent); o gatilho já renderiza o `<button>`. Use `defaultOpen` no modo não controlado e `open` com `onOpenChange` quando outra parte da tela precisar conhecer o estado; `disabled` trava o gatilho. Para vários painéis recolhíveis, use Accordion; para alternar entre painéis, Tabs; para ações ancoradas, Menu.",
   },
+  "floating-layer": {
+    name: "floating-layer",
+    ancestry: "opus",
+    whenToUse:
+      "Mantenha utilizável, por cima de qualquer Dialog ou Drawer aberto, uma região que acompanha a aplicação inteira, como o botão e o painel de um assistente. O modal continua aberto e intacto atrás; a camada recebe clique, foco, digitação, rolagem e Esc. Diálogos que exigem resposta, como `Dialog mode=\"alert\"` e `dialog.confirm`, continuam cobrindo a camada até a resposta. Cada filho se posiciona contra a janela, e o hospedeiro publica em `data-modal` e `data-modal-side` o Dialog ou Drawer aberto. Para ferramentas sobre uma única superfície, use Dock; para conteúdo preso a um gatilho, Popover.",
+  },
   drawer: {
     name: "drawer",
     ancestry: "opus",

package/src/ui/react.tsx

@@ -139,6 +139,10 @@ export type {
   DialogMode,
 } from "./components/primitives/dialog.tsx";
 
+// A camada que convive com Dialog e Drawer modais (ADR 0052).
+export { FloatingLayer } from "./components/primitives/floating-layer.tsx";
+export type { FloatingLayerProps } from "./components/primitives/floating-layer.tsx";
+
 // O pacote de anatomia que Surface, Dialog, Drawer e Pane declaram no root (ADR 0023). As
 // tabelas e o contexto continuam internos; o consumidor escolhe entre os dois nomes.
 export type { SurfaceLayout } from "./components/patterns/surface-anatomy.ts";