@softize/opus 24.1.0 → 25.1.0

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/cli.md

@@ -20,11 +20,13 @@ opus db check         # drift entidade ↔ banco (read-only)
 opus seed check       # bindings, dependências, ciclos e scripts paralelos de seed
 ```
 
-`opus check` lê o código-fonte sem executá-lo e aplica regras em três grupos: actions
+`opus check` lê o código-fonte sem executá-lo e aplica regras em quatro grupos: actions
 (`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`, `ignored-by-kind`), UI
-(`ui-structure`, `ui-structure-split`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`) e
+(`ui-structure`, `ui-structure-split`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`),
 [Produtos de Dados](/docs/data-products) (`data-product-export`, `-id`, `-duplicate`, `-version`,
-`-interfaces`, `-interface`, `-entities` e `-entity`, todas com o prefixo `data-product`). Um projeto
+`-interfaces`, `-interface`, `-entities` e `-entity`, todas com o prefixo `data-product`) e
+[exclusão lógica](/docs/data) (`soft-delete-retention`, que cobra a retenção de cada entidade e a
+ligação com o domínio). Um projeto
 marcado com `opus.json` e ainda sem actions passa sem achados; sem o marcador, nenhuma action
 encontrada é falha, porque um gate que não verificou nada não é aprovação. `opus check --help` descreve cada regra.
 

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

@@ -30,6 +30,48 @@ export const SkillEntity = defineEntity({
 })
 ```
 
+## Exclusão lógica e expurgo
+
+Use `softDelete` quando um registro excluído precisa continuar no banco por um tempo, como
+histórico ou para atender uma regra de guarda. `kyselyRepo` passa a marcar `deletedAt` em
+`remove`, e `findById`, `all` e `list` deixam os excluídos de fora.
+
+A declaração também diz quando o registro excluído sai de vez. Informe o prazo em `retainDays`, o
+fuso da rotina e os textos da action que o Opus gera para expurgar:
+
+```ts
+export const ReportEntity = defineEntity({
+  name: 'report',
+  fields: { title: t.string() },
+  softDelete: {
+    retainDays: 90,
+    timezone: 'America/Sao_Paulo',
+    label: 'Expurgar relatórios excluídos',
+    description: 'Apaga de vez os relatórios excluídos há mais de 90 dias.',
+  },
+})
+```
+
+O domínio que lista a entidade em `entities` ganha a action `report.purge-deleted` e a rotina
+diária `report.purge-deleted.daily`, às 3h30 no fuso declarado. Só o sistema executa a action,
+que fica fora do REST e da IA, e ela nunca expurga antes do prazo. Com `kyselyData` no runtime, o
+handler padrão apaga as linhas em lotes, das mais antigas para as mais novas; a rotina exige um
+[agendador](/docs/scheduler). Cada lote que apaga algo registra `opus.purge` no log com os ids
+removidos, e a execução termina com `opus.purge.total`, que traz a quantidade.
+
+Antes de declarar `retainDays`, confira as chaves estrangeiras que apontam para a tabela. Uma chave
+restritiva faz cada execução falhar no lote da linha travada, que está entre as mais antigas, e o
+expurgo fica parado até a chave ganhar cascata ou um `bindPurge` apagar os dependentes primeiro.
+
+Quando apagar a linha não basta, como ao remover arquivos em outro serviço, registre um handler
+próprio com `bindPurge`, de `@softize/opus/data`, em `purges` no mesmo domínio. O handler recebe o
+corte e só apaga o que foi excluído antes dele: é isso que garante o prazo. Para guardar o
+registro excluído para sempre, declare o motivo: `softDelete: { retain: 'forever', reason }`.
+
+O [`opus check`](/docs/cli) reprova `softDelete: true`, que não diz por quanto tempo o registro
+fica guardado. Opções, nomes gerados e erros estão no `docs/protocol.md` do pacote, §15, "Retenção
+e expurgo".
+
 ## Código em camelCase, banco em snake_case
 
 O schema tipado do Kysely e todas as consultas usam camelCase (`workspaceId`, `ghRepo`). O banco

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

@@ -79,6 +79,10 @@ seção). Com schedules registrados e sem `scheduler`, o `start()` falha com
 `runtime.scheduler_required`. Um schedule com `enabled: false` não é registrado nem
 conferido, então pode apontar para uma action que ainda não existe no ambiente.
 
+Uma entidade com exclusão lógica e `retainDays` traz a própria rotina de expurgo, que o domínio
+registra junto com a action, como `report.purge-deleted.daily`. Ela também exige o `scheduler`.
+Veja "Exclusão lógica e expurgo" na página [Camada de dados](/docs/data).
+
 ## Preparar a action agendada
 
 O schedule executa a action como o sistema, sem uma pessoa por trás. Uma action que exige usuário

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