@softize/opus 25.0.0 → 25.2.0

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/content/mcp.md

@@ -60,7 +60,9 @@ Quando a action declara o que faz com os dados, a tool traz também as anotaçõ
 `readOnlyHint` vem de `effect`. Numa action que escreve, `destructiveHint` vai sempre explícito, a
 partir de `ai.destructive`, porque o MCP trata a ausência numa escrita como destrutiva.
 Em `_meta`, `com.softize.opus/effect` repete o efeito e `com.softize.opus/personal-data` diz se a
-resposta contém dado pessoal. Veja [Actions](/docs/actions).
+resposta contém dado pessoal. Na action dona de um tipo de recurso, `com.softize.opus/assistant`
+traz o assistente declarado, para o host conhecê-lo pelo catálogo que já consulta e aplicar à saída
+a mesma projeção com `projectAssistantContext`. Veja [Actions](/docs/actions).
 
 `CallTool` recusa com erro qualquer nome fora dessa lista; os demais seguem por `runtime.execute`.
 A exposição declarada em `ai` decide o que o cliente MCP pode executar, e a autorização do contexto

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.
  *