@softize/opus 19.0.0 → 20.0.0

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

@@ -5,53 +5,105 @@ title: Como consumir
 # Como consumir a UI
 
 Esta documentação é a referência visual e de uso de `@softize/opus/ui`. Os exemplos são renderizados
-com o tema e o contrato entregues aos aplicativos.
+com o mesmo tema e os mesmos componentes entregues aos aplicativos.
 
-## Por que esta doc existe
+## Por que esta documentação existe
 
-O catálogo do shadcn documenta seu próprio código e pode mostrar composições que não fazem parte do
+O catálogo do shadcn documenta o próprio código e pode mostrar composições que não fazem parte do
 Opus. Consulte estas páginas para conhecer os componentes, as variações e os comportamentos
 suportados pelo pacote.
 
 Cada página combina exemplos vivos, código e uma referência de propriedades por componente. A
-orientação inicial vem de `componentMeta`, a mesma fonte usada pelo catálogo e pelas ferramentas.
+orientação inicial de cada componente vem de `componentMeta`, a mesma fonte usada pelo catálogo e
+pelas ferramentas.
 
-## Como consumir
+## Importar componentes e tema
 
 Importe componentes e hooks de `@softize/opus/ui/react` e o tema por CSS. Não copie a implementação
 para o aplicativo quando a API pública já atender ao caso.
 
 ```tsx
-// Componentes e hooks — tudo do mesmo barrel.
+// Componentes e hooks vêm do mesmo ponto de entrada.
 import { Button, Dialog, useAction } from '@softize/opus/ui/react'
 ```
 
 ```css
-/* index.css — o tema canônico + os componentes do Opus no scan do Tailwind. */
+/* index.css — o tema do Opus e os componentes do pacote no scan do Tailwind. */
 @import '@softize/opus/ui/theme.css';
 @source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}';
 ```
 
+## Montar os providers
+
+Os hooks de action e os componentes que executam actions dependem de três providers na raiz da
+aplicação. O app criado por `opus create` já nasce com eles:
+
+```tsx
+// main.tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { OpusProvider, TooltipProvider } from '@softize/opus/ui/react'
+import { fetchClient } from '@softize/opus/client/fetch'
+import { App } from './App.tsx'
+
+const queryClient = new QueryClient()
+// Mesma origem: as actions respondem em /api. Aponte baseUrl para outro servidor quando houver.
+const client = fetchClient({ baseUrl: '' })
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <OpusProvider client={client}>
+        <TooltipProvider>
+          <App />
+        </TooltipProvider>
+      </OpusProvider>
+    </QueryClientProvider>
+  </StrictMode>,
+)
+```
+
+- `QueryClientProvider` guarda o cache das consultas; `useListAction` e as invalidações entre
+  actions dependem dele.
+- `OpusProvider` informa como chamar as actions. Fora dele, os hooks de action lançam erro ao
+  montar.
+- `TooltipProvider` é exigido pelos tooltips da aplicação e por componentes do Opus que usam
+  tooltip, como `Dock` e `Truncate`.
+
+`fetchClient` chama cada action por HTTP em `<baseUrl><apiPrefix>`; `apiPrefix` tem padrão `/api`,
+o mesmo dos servidores do Opus. `headers` e `beforeRequest` acrescentam cabeçalhos fixos ou
+calculados a cada chamada, como um token de acesso.
+
+## Propriedades de OpusProvider
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `client` | `ClientAdapter` | obrigatório | Executa as actions chamadas pelos hooks e componentes; normalmente `fetchClient`. |
+| `dicts` | `Record<string, DictLike>` | `{}` | Dicionários por referência, usados por `options: { kind: 'dictionary', ref }` em campos e filtros. Sem registro, o campo usa os dados do `t.dict` que viajam no schema do contrato. |
+| `children` | `ReactNode` | obrigatório | A árvore que usa as actions. |
+
 ## Prebundle do Vite
 
-A entrada `@softize/opus/ui/react` é um `.tsx`, e o prebundle do Vite só considera entradas
-`.js`/`.ts`. Sem ajuste, o dev server avisa `Cannot optimize dependency` e serve a árvore do Opus
-arquivo a arquivo na carga fria. Há duas saídas, cada uma com um custo conhecido:
+A entrada `@softize/opus/ui/react` é um arquivo `.tsx`, e o prebundle do Vite só considera entradas
+`.js` e `.ts`. Sem ajuste, o dev server avisa `Cannot optimize dependency` e serve os arquivos do
+Opus um a um na primeira carga. Há duas saídas, cada uma com um custo conhecido:
 
 - `optimizeDeps.include: ['@softize/opus/ui/react']` com `extensions: ['.tsx']` pré-empacota o
-  Opus, mas pode duplicar `@tanstack/react-query` quando o app também o importa direto (dois
-  `QueryClient`, hooks fora do provider).
-- `optimizeDeps.exclude: ['@softize/opus/ui/react']` evita a duplicação e infla a carga fria.
+  Opus, mas pode duplicar `@tanstack/react-query` quando o app também o importa diretamente. O
+  resultado são dois `QueryClient` e hooks que não encontram o provider.
+- `optimizeDeps.exclude: ['@softize/opus/ui/react']` evita a duplicação e deixa a primeira carga
+  mais lenta.
 
-Escolha pelo sintoma que aparece no seu app e registre a decisão no `vite.config.ts`. A saída
-definitiva (entrada `.ts` no pacote) está no radar do Opus.
+Escolha pelo sintoma que aparece no seu app e registre a decisão no `vite.config.ts`. Uma entrada
+`.ts` no pacote, que resolveria os dois custos, ainda não existe.
 
-## Origem e anti-drift
+## Origem dos componentes
 
-> Cada componente declara de onde veio — e a regra de sincronização vem junto.
+Cada componente declara de onde veio, e essa origem define como ele acompanha mudanças:
 
-- **Origem shadcn** — port curado do shadcn (Radix + cmdk). Toda divergência do upstream é
-  DECLARADA no componente ou no tema — o que diverge sem declaração é drift e deve ser
-  sincronizado (skill `build-opus-ui`).
-- **Nativo do Opus** — nasceu aqui (os patterns de action). Não tem upstream para acompanhar; a
-  referência é esta doc.
+- **Origem shadcn:** adaptação do shadcn (Radix e cmdk). Toda divergência do original é declarada
+  no componente ou no tema. Uma divergência sem declaração deve ser sincronizada; a skill
+  `$build-opus-ui` orienta esse trabalho.
+- **Nativo do Opus:** criado no próprio Opus, como os componentes de action. Não há versão externa a
+  acompanhar; a referência é esta documentação.

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

@@ -4,74 +4,83 @@ title: Atualizar o Opus
 
 # Atualizar o Opus
 
-Use este fluxo para atualizar o Opus por uma ou várias versões. O changelog explica as mudanças e os
-gates apontam as adaptações necessárias no projeto.
+Use este fluxo para atualizar o Opus por uma ou várias versões. O [changelog](/changelog) explica
+as mudanças, e os gates apontam as adaptações necessárias no projeto. Em projetos que usam as
+skills do Opus, a skill `$upgrade-opus` conduz as mesmas etapas: lê o changelog, atualiza a
+dependência, materializa os artefatos e aplica as migrações.
 
-## 1. Identificar a versão disponível
+## 1. Atualizar a dependência
 
-O **Maestro** compara o pin (`opus.json`) com a versão instalada e com a fonte a cada
-sessão — o alerta no rodapé diz a distância (`v18.0.1 → v18.1.0`) e o **Atualizar** faz
-a parte mecânica: bump da dependência, re-materialização da camada de IA (skills,
-hooks, agentes) e re-sync do bloco gerenciado do CLAUDE.md.
-
-Fora do Maestro, faça essa parte à mão:
+A versão adotada pelo projeto fica no `package.json` e no `opus.json` de cada app. Compare-a com a
+versão publicada e atualize:
 
 ```bash
 pnpm outdated @softize/opus          # distância até a versão publicada
-pnpm -r up @softize/opus@<versão>    # em todo workspace que declara o Opus
-pnpm run setup                       # opus setup && base setup: re-materializa base.json e skills
+pnpm -r up @softize/opus@<versão>    # em todo pacote do workspace que declara o Opus
+pnpm run setup                       # opus setup && base setup: materializa base.json e skills
 ```
 
-Rode `setup` no diretório de cada app que tem `opus.json`; num monorepo criado por
+Rode `setup` no diretório de cada app que tem `opus.json`. Num monorepo criado por
 `opus create --monorepo`, a raiz não tem esse script, e `pnpm -r run setup` alcança todos os apps.
-O postinstall do pacote tenta materializar sozinho, mas é best-effort; se a camada materializada
-ainda corresponder à versão anterior, o `opus check` aborta com
+O postinstall do pacote tenta materializar os artefatos sozinho, mas não garante o resultado. Se a
+camada materializada ainda corresponder à versão anterior, o `opus check` para com
 `base.json: Opus aplicado X, instalado Y`.
 
+Interfaces de desenvolvimento podem mostrar a diferença entre a versão aplicada na
+sua cópia de trabalho e a adotada pela branch principal. Esse aviso não atualiza o pacote; a
+atualização continua sendo este fluxo.
+
 ## 2. Ler as mudanças acumuladas
 
-O changelog **viaja no pacote** — depois do bump, está em
-`node_modules/@softize/opus/CHANGELOG.md`. Uma entrada por versão; quando quebra,
-a seção **Breaking** diz a migração (o que renomeou, o que fazer no seu código).
-A esteira de release **recusa** publicar versão sem entrada — o arquivo não defasa.
+O changelog também acompanha o pacote: depois da atualização, ele está em
+`node_modules/@softize/opus/CHANGELOG.md`. Cada versão tem uma entrada, e a publicação é recusada
+quando a entrada falta. Quando uma versão quebra compatibilidade, a seção **Breaking** descreve o
+que mudou e como migrar o seu código.
 
-- **minor e patch** (18.0 → 18.1): leia todas as entradas intermediárias. Minors podem pedir ação,
-  como a troca de `PageHeader` por `PageIntro` no `PageShell` (17.2.0) ou o layout desktop fixo (18.1.0).
-- **major** (17.x → 18.0): além disso, aplique as seções Breaking de cada versão pulada, na ordem.
+- **Minor e patch** (18.0 → 18.5): leia todas as entradas intermediárias, porque elas também podem
+  mudar comportamento observável. Na 18.1.1, por exemplo, uma action que não é `public` passou a
+  exigir usuário antes de executar os `loads`.
+- **Major** (18.x → 19.0): além disso, aplique as seções Breaking de cada versão pulada, na ordem.
+  Na 19.0.0, por exemplo, os headers de `Card`, `Dialog` e `Drawer` passaram a aceitar somente os
+  slots da própria família.
 
 ## 3. Executar as verificações
 
-O Opus é publicado como código-fonte TypeScript: o que quebrou aparece com arquivo e linha.
-Rode, na ordem:
+O Opus é publicado como código-fonte TypeScript, então uma incompatibilidade aparece com arquivo e
+linha. Rode, na ordem:
 
 ```bash
-pnpm typecheck               # a API nova cobra os tipos
-pnpm exec opus check         # convenções (regras novas inclusas)
-pnpm exec opus copy --check  # inventário de copy em dia
-pnpm exec base copy check    # política de copy da base
+pnpm typecheck               # a API nova confere os tipos
+pnpm exec opus check         # convenções, inclusive regras novas
+pnpm exec opus copy --check  # inventário de copy atualizado
+pnpm exec base copy check    # política de copy da Base
 pnpm test                    # comportamento
-pnpm manifest:check          # a spec projetada ficou fresca?
+pnpm manifest:check          # o manifest projetado continua atualizado
 ```
 
-Num monorepo, `typecheck` e `test` existem na raiz, mas `manifest:check` é script de cada app:
-rode-o no diretório do app ou com `pnpm -r run manifest:check`. Nenhum desses comandos migra o
+Num monorepo, `typecheck` e `test` existem na raiz, mas `manifest:check` é um script de cada app:
+rode-o no diretório do app ou com `pnpm -r run manifest:check`. Nenhum desses comandos altera o
 banco. Se o projeto tiver testes de integração, eles usam o banco que o próprio projeto configurar.
 
 ## 4. Migrar o banco, se houver
 
 Se o `opus.config.ts` declara `database`, confira o schema e aplique a migração como uma etapa
-separada, contra o banco do ambiente que você pretende alterar:
+separada:
 
 ```bash
 pnpm exec opus db check      # compara entidades e banco, sem escrever
 pnpm exec opus db migrate    # aplica o schema idempotente; escreve no banco
 ```
 
-Com todas as verificações verdes, revise a atualização como qualquer outra mudança de código antes
-de entregá-la.
+Os comandos `opus db` carregam o `.env` que está ao lado do `opus.config.ts` antes de abrir a
+conexão, e uma variável já definida no ambiente vence o arquivo. Antes de migrar, confirme para
+qual banco a factory `database` vai apontar. Para migrar outro ambiente, informe a variável no
+próprio comando, como `DATABASE_URL=… pnpm exec opus db migrate` quando a factory lê essa variável.
+
+Com todas as verificações aprovadas, revise a atualização como qualquer outra mudança de código
+antes de entregá-la.
 
 ## Pulou muitas versões?
 
-O ritual não muda, só o volume: leia todas as entradas acumuladas, não só as seções Breaking
-(o changelog é uma lista, não um diff), aplique na ordem e deixe os gates validarem o conjunto.
-Não há caminho especial — é o mesmo laço, com mais iterações.
+O fluxo é o mesmo, com mais entradas para ler. Leia todas as entradas acumuladas, não só as seções
+Breaking, aplique as migrações na ordem das versões e deixe os gates validarem o conjunto.

package/src/ui/docs/plugin.ts

@@ -11,6 +11,11 @@
  * `mountDocs`. Importando o MESMO CSS do app, a doc herda identidade e utilitários de
  * graça. É dev-only (apply: 'serve') — nada vai pro bundle de produção.
  *
+ * O CSS entra por um entry CSS virtual que importa o do app e acrescenta um `@source` para
+ * as páginas `.md` da doc do Opus. Os exemplos ```tsx preview usam classes que só aparecem
+ * nesses `.md`, e o Tailwind do app não varre o pacote instalado. O `@source` fica só nesse
+ * entry: o CSS de produção do app não muda.
+ *
  * Uso (vite.config.ts do app):
  *   import { opusDocs } from '@softize/opus/ui/docs/plugin'
  *   export default defineConfig({ plugins: [react(), tailwindcss(), opusDocs()] })
@@ -36,6 +41,29 @@ const VIRTUAL_ID = 'virtual:opus-docs-entry'
 // O `/@id/` é como o vite serve módulos por id; o `\0` (convenção de virtual) vira `__x00__` na URL.
 const RESOLVED_ID = '\0' + VIRTUAL_ID
 const ENTRY_URL = '/@id/__x00__' + VIRTUAL_ID
+// A extensão `.css` faz o Vite e o @tailwindcss/vite tratarem o módulo virtual como folha de estilo.
+const VIRTUAL_CSS_ID = 'virtual:opus-docs-entry.css'
+const RESOLVED_CSS_ID = '\0' + VIRTUAL_CSS_ID
+
+/**
+ * Pasta das páginas `.md` da doc do Opus, ao lado deste arquivo. O Node carrega o plugin pelo
+ * caminho real (resolve o symlink do pnpm/workspace), então `import.meta.url` já aponta para
+ * onde o scanner do Tailwind encontra os arquivos.
+ *
+ * Sem builtins do Node: o arquivo mora em `ui/`, e o gate de fronteira proíbe `node:*` ali.
+ * Sem `new URL('./content', import.meta.url)`: o Vite reescreve esse padrão como asset.
+ */
+export function opusDocsContentDir(moduleUrl: string = import.meta.url): string {
+  const folder = moduleUrl.slice(0, moduleUrl.lastIndexOf('/'))
+  const path = decodeURIComponent(new URL(folder).pathname)
+  // No Windows o pathname vem como `/C:/…`; o Tailwind espera `C:/…`.
+  return (/^\/[A-Za-z]:\//.test(path) ? path.slice(1) : path) + '/content'
+}
+
+/** O CSS do entry virtual: o do app (tema + tailwind) + a varredura dos `.md` da doc. */
+export function opusDocsEntryCss(appCss: string, contentDir: string = opusDocsContentDir()): string {
+  return [`@import ${JSON.stringify(appCss)};`, `@source ${JSON.stringify(contentDir + '/*.md')};`].join('\n')
+}
 
 export function opusDocs(options: opusDocsOptions = {}): Plugin {
   const basePath = options.basePath ?? '/__docs'
@@ -48,12 +76,18 @@ export function opusDocs(options: opusDocsOptions = {}): Plugin {
     apply: 'serve',
     resolveId(id) {
       if (id === VIRTUAL_ID) return RESOLVED_ID
+      if (id === VIRTUAL_CSS_ID) return RESOLVED_CSS_ID
       return undefined
     },
-    load(id) {
+    async load(id) {
+      if (id === RESOLVED_CSS_ID) {
+        // O `@import` do entry virtual não tem pasta de referência: vai com o caminho resolvido.
+        const resolved = await this.resolve(css)
+        return opusDocsEntryCss(resolved?.id ?? css)
+      }
       if (id !== RESOLVED_ID) return undefined
       // Sempre importa o CSS do app (tema + tailwind) antes de subir a doc.
-      const head = `import ${JSON.stringify(css)}`
+      const head = `import ${JSON.stringify(VIRTUAL_CSS_ID)}`
       if (source === undefined || source === '') {
         // Sem `source`: a doc do próprio Opus (DOC_SECTIONS), como sempre.
         return [head, `import { mountDocs } from '@softize/opus/ui/docs/standalone'`, `mountDocs({ basePath: ${JSON.stringify(basePath)} })`].join('\n')

package/src/ui/docs/registry.tsx

@@ -37,6 +37,7 @@ import executionsMd from "./content/executions.md?raw";
 import schedulerMd from "./content/scheduler.md?raw";
 import actionsMd from "./content/actions.md?raw";
 import dataMd from "./content/data.md?raw";
+import dataProductsMd from "./content/data-products.md?raw";
 import storageMd from "./content/storage.md?raw";
 import aiMd from "./content/ai.md?raw";
 import mcpMd from "./content/mcp.md?raw";
@@ -276,6 +277,11 @@ export const PROTOCOL_SECTIONS: DocSection[] = [
             render: doc(runtimeMd),
           },
           { slug: "data", title: "Camada de dados", render: doc(dataMd) },
+          {
+            slug: "data-products",
+            title: "Produtos de Dados",
+            render: doc(dataProductsMd),
+          },
           {
             slug: "testing",
             title: "Testes de action",

package/src/ui/drivers/react.tsx

@@ -83,11 +83,19 @@ export function OpusProvider({
   return <OpusContext.Provider value={value}>{children}</OpusContext.Provider>
 }
 
-function useClient(): ClientAdapter {
+/**
+ * O adapter do provider. `hook` nomeia quem chamou, para a mensagem apontar o hook que a
+ * pessoa vê no stack — muitas vezes chamado por dentro de ActionForm, ActionList ou
+ * ActionView, e não diretamente pela tela.
+ */
+function useClient(hook: string): ClientAdapter {
   const ctx = useContext(OpusContext)
   if (ctx === null) {
     throw new Error(
-      'useAction/useLookupAction precisam estar dentro de <OpusProvider>.',
+      `${hook} foi chamado fora de um <OpusProvider> e não tem como executar a action. ` +
+        'Os hooks de action e os componentes que os usam, como ActionForm, ActionList e ActionView, ' +
+        'precisam de um <OpusProvider client={...}> acima deles na árvore. Envolva a aplicação no provider; ' +
+        'em testes e previews, envolva o componente renderizado.',
     )
   }
   return ctx.client
@@ -113,7 +121,7 @@ export interface UseActionResult<TInput, TData> extends ActionState<TData> {
 export function useAction<TInput = unknown, TData = unknown>(
   action: ActionDef,
 ): UseActionResult<TInput, TData> {
-  const client = useClient()
+  const client = useClient('useAction')
   const [state, setState] = useState<ActionState<TData>>(() => idleAction<TData>())
 
   const run = useCallback(
@@ -173,7 +181,7 @@ export interface UseLookupActionResult<TInput, TItem>
 export function useLookupAction<TInput = unknown, TItem = unknown>(
   action: ActionDef,
 ): UseLookupActionResult<TInput, TItem> {
-  const client = useClient()
+  const client = useClient('useLookupAction')
   const [state, setState] = useState<ListState<TItem>>(() => idleLookup<TItem>())
 
   const run = useCallback(
@@ -257,7 +265,7 @@ export function useListAction<TItem = unknown, TInput extends Record<string, unk
   action: { name: string; kind: 'list' },
   input?: TInput,
 ): UseListActionResult<TItem> {
-  const client = useClient()
+  const client = useClient('useListAction')
 
   const query = useQuery<Paginated<TItem>, ActionError>({
     queryKey: [action.name, input ?? {}],
@@ -358,7 +366,7 @@ export function useFormAction<
   action: FormContract<TInput, TData>,
   options: UseFormActionOptions<TInput, TData> = {},
 ): UseFormActionResult<TInput, TData> {
-  const client = useClient()
+  const client = useClient('useFormAction')
   const queryClient = useQueryClient()
 
   const resolver = useMemo(() => {
@@ -484,7 +492,7 @@ export function useViewAction<TInput = unknown, TData = unknown>(
   action: { name: string; kind: 'view' },
   input: TInput,
 ): UseViewActionResult<TData> {
-  const client = useClient()
+  const client = useClient('useViewAction')
 
   // TanStack Query serializa queryKey → dedupe automático mesmo com input
   // inline (referência nova a cada render). Sem isso entraria em loop.
@@ -551,7 +559,7 @@ export function useTriggerAction<TInput = unknown, TData = unknown>(
   action: ActionContract<TInput, TData>,
   options: UseTriggerActionOptions<TInput, TData> = {},
 ): UseTriggerActionResult<TInput, TData> {
-  const client = useClient()
+  const client = useClient('useTriggerAction')
   const queryClient = useQueryClient()
   const [state, setState] = useState<ActionState<TData>>(() =>
     idleAction<TData>(),