@softize/opus 19.0.0 → 20.0.0

package/src/ui/docs/content/action-form.md

@@ -1,8 +1,28 @@
+## Pré-requisitos
+
+`ActionForm` executa a action pelo cliente registrado no `OpusProvider` e usa o React Query para
+invalidar as consultas afetadas. Monte os dois providers uma vez na raiz do aplicativo; todos os
+exemplos desta página pressupõem essa montagem.
+
+```tsx
+/* main.tsx do app. */
+<QueryClientProvider client={queryClient}>
+  <OpusProvider client={apiClient}>
+    <App />
+  </OpusProvider>
+</QueryClientProvider>
+```
+
 ## Formulário derivado do contrato
 
 Use `ActionForm` para gerar campos, validação e mensagens a partir de uma `FormAction`. Sem
-`children`, o componente escolhe o controle adequado para cada campo e preserva a ordem declarada
-no contrato. No exemplo, altere um valor para habilitar a ação principal.
+`children`, o componente monta um campo para cada chave declarada em `fields` no contrato, na ordem
+dessa declaração, e escolhe o controle pelo tipo do campo no schema de input. Um campo presente no
+schema, mas sem entrada em `fields`, não aparece no modo automático: declare-o em `fields` ou
+posicione-o com `ActionFormField`, como mostra a próxima seção.
+
+A ação principal permanece desabilitada até que algum valor mude. No exemplo, preencha o nome para
+habilitá-la; o valor “Softize” simula um erro devolvido pelo servidor.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -13,36 +33,43 @@ no contrato. No exemplo, altere um valor para habilitar a ação principal.
 ## Composição dos campos
 
 Passe `children` quando a disposição automática não atender ao formulário. Cada
-`ActionFormField` mantém rótulo, ajuda, controle, obrigatoriedade e erro derivados do contrato;
-o consumidor define apenas a grade, as condições e o espaçamento. Execução, validação, toast e
-invalidação continuam sob responsabilidade de `ActionForm`.
+`ActionFormField` mantém rótulo, ajuda, controle, obrigatoriedade e erro derivados do contrato; o
+consumidor define apenas a grade e as condições. O espaçamento vertical entre os filhos vem do
+`FieldGroup` que o formulário já aplica. Execução, validação, toast e invalidação continuam sob
+responsabilidade de `ActionForm`.
+
+Nesse modo, qualquer campo do schema de input pode ser posicionado, mesmo sem entrada em `fields`;
+nesse caso, o rótulo exibido é o próprio nome técnico do campo e não há ajuda. Declare o campo em
+`fields` para nomeá-lo.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
   <ActionForm action={docWorkspaceCreate}>
-    <div className="space-y-6">
-      <div className="grid grid-cols-2 gap-4">
-        <ActionFormField name="name" />
-        <ActionFormField name="status" />
-      </div>
-      <ActionFormField name="contact" />
-      <ActionFormField name="notes" />
+    <div className="grid grid-cols-2 gap-4">
+      <ActionFormField name="name" />
+      <ActionFormField name="status" />
     </div>
+    <ActionFormField name="contact" />
+    <ActionFormField name="notes" />
   </ActionForm>
 </DocBrowserActionProvider>
 ```
 
 ## Valores iniciais e rótulos
 
-`defaultValues` preenche o formulário para edição. Criação e edição comuns mantêm o rótulo padrão
-`Salvar`; use `submitLabel` somente quando a operação pedir outro verbo, como `Renomear`.
-`onCancel` devolve ao consumidor a decisão de fechar um painel ou navegar para outra página.
+`defaultValues` preenche o formulário antes da primeira alteração. Em uma edição, carregue ali os
+valores atuais do registro; em uma criação, use-o para sugerir um ponto de partida, como o status
+inicial do exemplo. A ação principal continua desabilitada até que a pessoa altere algum campo.
+
+Criação e edição comuns mantêm o rótulo padrão `Salvar`; use `submitLabel` somente quando a
+operação pedir outro verbo, como `Renomear`. `onCancel` acrescenta `Cancelar` e devolve ao
+consumidor a decisão de fechar um painel ou navegar para outra página.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
   <ActionForm
     action={docWorkspaceCreate}
-    defaultValues={{ name: "Empresa X", status: "active" }}
+    defaultValues={{ status: "active" }}
     onCancel={() => undefined}
   />
 </DocBrowserActionProvider>
@@ -50,58 +77,17 @@ invalidação continuam sob responsabilidade de `ActionForm`.
 
 ## Formulário modal
 
-[`ActionFormDialog`](/ui/action-form-dialog) acrescenta a moldura, o corpo rolável e o footer ao formulário. Por padrão, as
-ações ficam alinhadas no fim da faixa e preservam a largura do conteúdo; `Cancelar` usa `ghost`.
-Use `footerDistribution="equal"` somente quando as duas decisões precisarem do mesmo peso visual.
-Nesse caso, o cancelamento muda para `outline`, salvo escolha explícita em `cancelVariant`.
-As propriedades do wrapper estão documentadas na página dele.
-
-## Pré-requisitos
-
-Monte os providers de consulta e execução uma vez na raiz do aplicativo:
+[`ActionFormDialog`](/ui/action-form-dialog) acrescenta a moldura, o corpo rolável e o rodapé ao
+formulário. Por padrão, as ações ficam alinhadas no fim da faixa e preservam a largura do conteúdo;
+`Cancelar` usa `ghost`. Use `footerDistribution="equal"` somente quando as duas decisões precisarem
+do mesmo peso visual. Nesse caso, o cancelamento muda para `outline`, salvo escolha explícita em
+`cancelVariant`. Para apresentar o formulário como uma seção delimitada da página, use
+[`ActionFormCard`](/ui/action-form-card). As propriedades de cada wrapper estão na página dele.
 
-```tsx
-/* main.tsx do app. */
-<QueryClientProvider client={queryClient}>
-  <OpusProvider client={apiClient}>
-    <App />
-  </OpusProvider>
-</QueryClientProvider>
-```
-
-## useFormAction
-
-`ActionForm` é uma composição sobre `useFormAction(action, { defaultValues, onSuccess, onError })`,
-que devolve o `form` do react-hook-form já com o resolver Zod em pt-BR, `submit`, `isLoading`,
-`error`, `isSuccess` e `reset`. Use o hook direto quando o formulário precisar de um layout ou de um
-ciclo de vida que o pattern não cobre; validação e execução continuam iguais.
-
-## Propriedades de ActionForm
-
-| Propriedade                                            | Tipo                                                  | Padrão                            | Descrição                                                                                                                                                                               |
-| ------------------------------------------------------ | ----------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `action`                                               | `FormContract<TInput, TData>`                         |                                   | O contrato da FormAction — dele saem campos (input Zod + fields), mensagens e invalidação de cache.                                                                                     |
-| `defaultValues`                                        | `Partial<TInput>`                                     |                                   | Valores iniciais — o modo edição de um update/patch.                                                                                                                                    |
-| `onSuccess`                                            | `(data: TData) => void`                               |                                   | Pós-sucesso (o toast e a invalidação de cache já aconteceram).                                                                                                                          |
-| `submitLabel / cancelLabel / cancelVariant / onCancel` | `string / string / 'ghost' \| 'outline' / () => void` | `'Salvar' / 'Cancelar' / 'ghost'` | Rodapé do form — o Cancelar só aparece com onCancel. Fora de um modal, mantenha `ghost`; o `ActionFormDialog` usa `outline` somente com `footerDistribution="equal"`.                                                                    |
-| `disabled`                                             | `boolean`                                             | `false`                           | Bloqueia campos e ações sem desmontar o formulário. |
-| `onLoadingChange`                                      | `(loading: boolean) => void`                          |                                   | Informa início e fim da execução a quem coordena ações como um grupo. |
-| `fieldOptions`                                         | `Record<string, SelectOption[]>`                      |                                   | Opções de runtime por campo (ex.: ids de skills) — sobrepõe as inferidas do z.enum.                                                                                                     |
-| `className / body / footer`                            | `string / (node) => node / (node) => node`            |                                   | className = classes do `<form>`. body/footer = slots: recebem os campos / os botões e escolhem o invólucro — é como o ActionFormDialog injeta DialogBody/DialogFooter (scroll + faixa). |
-| `children`                                             | `ReactNode`                                           |                                   | Modo composição: diagrame com `<ActionFormField name />`. Sem children, o automático monta todos os campos na ordem do contrato.                                                        |
+## Ajuda no rótulo
 
-## Propriedades de ActionFormField
-
-| Propriedade | Tipo             | Descrição                                                                      |
-| ----------- | ---------------- | ------------------------------------------------------------------------------ |
-| `name`      | `string`         | O campo do contrato (chave em `fields`/schema). Fora do schema, não renderiza. |
-| `options`   | `SelectOption[]` | Opções por id de runtime — sobrepõe o fieldOptions do form e o z.enum.         |
-| `className` | `string`         | Classes do invólucro (ex.: `col-span-2` em uma grid).                          |
-
-## Ajuda na label
-
-`FieldSpec.help` aparece como um ícone junto à label, com o texto num tooltip. Escreva ali o
-critério, o efeito ou a limitação que a label não diz; ajuda que só repete a label deve ser omitida.
+`FieldSpec.help` aparece como um ícone junto ao rótulo, com o texto em um tooltip. Escreva ali o
+critério, o efeito ou a limitação que o rótulo não diz; ajuda que só repete o rótulo deve ser omitida.
 Não existe texto auxiliar sob o campo: quem precisa de uma frase permanente abaixo do controle usa
 `FieldDescription` na composição própria.
 
@@ -110,20 +96,14 @@ lugar:
 
 ```tsx preview col md
 <Field>
-  <FieldLabel htmlFor="staff" className="items-center gap-1.5">
-    <span>Staff</span>
-    <LabelHelp help="Tem acesso ao back-office e a todos os workspaces." />
+  <FieldLabel htmlFor="billing-contact" className="items-center gap-1.5">
+    <span>Contato</span>
+    <LabelHelp help="Recebe os avisos de faturamento e de integração do workspace." />
   </FieldLabel>
-  <Input id="staff" placeholder="Empresa X" />
+  <Input id="billing-contact" type="email" placeholder="email@cliente.com" />
 </Field>
 ```
 
-### Propriedades de LabelHelp
-
-| Propriedade | Tipo     | Descrição                                                    |
-| ----------- | -------- | ------------------------------------------------------------ |
-| `help`      | `string` | O texto do tooltip. Vazio ou ausente, o ícone não renderiza. |
-
 ## Origem das opções de seleção
 
 As opções seguem esta precedência: `options` no campo, `fieldOptions` no formulário, `options` no
@@ -137,7 +117,7 @@ referência; itens estáticos permanecem como declarados no contrato.
 O literal canônico do grupo de escolhas é sempre kebab-case: `widget: 'toggle-group'`. Em enum ele
 renderiza seleção única; em array de enum, seleção múltipla. As opções seguem a mesma precedência e
 o mesmo `SelectOption` rico dos selects. Use esse widget quando cada opção funcionar como uma
-escolha rica em card, com conteúdo de apoio; para uma lista textual comum, prefira `RadioGroup`.
+escolha rica em card, com conteúdo de apoio; para uma lista textual comum, prefira [`RadioGroup`](/ui/radio-group).
 Outros identificadores continuam válidos como metadado
 para renderers próprios; o `ActionForm` aplica sua inferência normal quando não reconhece o widget.
 
@@ -170,3 +150,38 @@ function PermissionGrid() {
 
 O contexto também expõe `shape` (Zod por campo), `fields` (FieldSpec) e `fieldOptions`.
 Fora de um `<ActionForm>`, o hook lança um erro que informa o provider ausente.
+
+## useFormAction
+
+`ActionForm` é uma composição sobre `useFormAction(action, { defaultValues, onSuccess, onError })`,
+que devolve o `form` do react-hook-form já com o resolver Zod em pt-BR, `submit`, `isLoading`,
+`error`, `isSuccess` e `reset`. Use o hook direto quando o formulário precisar de um layout ou de um
+ciclo de vida que o pattern não cobre; validação e execução continuam iguais.
+
+## Propriedades de ActionForm
+
+| Propriedade                                            | Tipo                                                  | Padrão                            | Descrição                                                                                                                                                                               |
+| ------------------------------------------------------ | ----------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`                                               | `FormContract<TInput, TData>`                         |                                   | O contrato da FormAction — dele saem campos (input Zod + fields), mensagens e invalidação de cache.                                                                                     |
+| `defaultValues`                                        | `Partial<TInput>`                                     |                                   | Valores iniciais: os dados atuais do registro em uma edição ou uma sugestão em uma criação. Não contam como alteração para habilitar a ação principal. |
+| `onSuccess`                                            | `(data: TData) => void`                               |                                   | Pós-sucesso (o toast e a invalidação de cache já aconteceram).                                                                                                                          |
+| `submitLabel / cancelLabel / cancelVariant / onCancel` | `string / string / 'ghost' \| 'outline' / () => void` | `'Salvar' / 'Cancelar' / 'ghost'` | Rodapé do form — o Cancelar só aparece com onCancel. Fora de um modal, mantenha `ghost`; o `ActionFormDialog` usa `outline` somente com `footerDistribution="equal"`.                                                                    |
+| `disabled`                                             | `boolean`                                             | `false`                           | Bloqueia campos e ações sem desmontar o formulário. |
+| `onLoadingChange`                                      | `(loading: boolean) => void`                          |                                   | Informa início e fim da execução a quem coordena ações como um grupo. |
+| `fieldOptions`                                         | `Record<string, SelectOption[]>`                      |                                   | Opções de runtime por campo (ex.: ids de skills) — sobrepõe as inferidas do z.enum.                                                                                                     |
+| `className / body / footer`                            | `string / (node) => node / (node) => node`            |                                   | className = classes do `<form>`. body/footer = slots: recebem os campos / os botões e escolhem o invólucro — é como o ActionFormDialog injeta DialogBody/DialogFooter (scroll + faixa). |
+| `children`                                             | `ReactNode`                                           |                                   | Modo composição: diagrame com `<ActionFormField name />`. Sem children, o modo automático monta um campo por chave de `fields`, na ordem declarada; campo sem entrada em `fields` não aparece. |
+
+## Propriedades de ActionFormField
+
+| Propriedade | Tipo             | Descrição                                                                      |
+| ----------- | ---------------- | ------------------------------------------------------------------------------ |
+| `name`      | `string`         | O campo do schema de input. Sem entrada em `fields`, usa o nome técnico como rótulo; fora do schema, não renderiza. |
+| `options`   | `SelectOption[]` | Opções por id de runtime — sobrepõe o fieldOptions do form e o z.enum.         |
+| `className` | `string`         | Classes do invólucro (ex.: `col-span-2` em uma grid).                          |
+
+## Propriedades de LabelHelp
+
+| Propriedade | Tipo     | Descrição                                                    |
+| ----------- | -------- | ------------------------------------------------------------ |
+| `help`      | `string` | O texto do tooltip. Vazio ou ausente, o ícone não renderiza. |

package/src/ui/docs/content/action-list-dialog.md

@@ -1,76 +1,113 @@
 ## Listagem em um modal
 
-Use `ActionListDialog` para consultar e apresentar uma `ListAction` sem sair do contexto atual. A
-lista carrega ao abrir, refaz a consulta quando `input` muda e acompanha invalidações declaradas por
-outras actions. O consumidor compõe os itens por `children`; o modal mantém os estados e a barra de
-ações.
+Use `ActionListDialog` para consultar e apresentar uma `ListAction` sem sair do contexto atual. O
+modal monta um [`ActionList`](/ui/action-list) no modo de composição: busca, filtros, os estados de
+carregamento, erro e vazio, além do rodapé com total e paginação, continuam os da listagem. A consulta
+roda ao abrir, é refeita quando `input` muda e acompanha as invalidações declaradas por outras
+actions. O consumidor compõe somente os itens, por `children`.
 
 ```tsx preview col
+type Workspace = {
+  id: string;
+  name: string;
+  status: "active" | "onboarding" | "paused";
+  agents: number;
+};
+
 const [open, setOpen] = useState(false);
 
 render(
   <DocBrowserActionProvider>
-    <Button onClick={() => setOpen(true)}>Workspaces</Button>
+    <Button onClick={() => setOpen(true)}>Ver workspaces</Button>
     <ActionListDialog
       action={docWorkspaceList}
       input={{}}
       open={open}
       onOpenChange={setOpen}
       title="Workspaces"
-      actions={
-        <Button>Criar workspace</Button>
-      }
+      actions={<Button>Criar workspace</Button>}
       emptyMessage="Nenhum workspace."
     >
-      {(workspaces) => (
-        <div className="space-y-2">
-          {workspaces.map((w) => (
-            <div
-              key={w.id}
-              className="flex items-center gap-2 rounded-md border border-border p-3"
-            >
-              <span className="text-sm font-semibold">{w.name}</span>
-              <DictionaryValue dict={docWorkspaceStatus} value={w.status} />
-              <span className="ml-auto text-xs text-muted-foreground">
-                {w.agents} agentes
-              </span>
-            </div>
+      {(workspaces: Workspace[]) => (
+        <ItemGroup variant="framed">
+          {workspaces.map((w, index) => (
+            <React.Fragment key={w.id}>
+              {index > 0 && <ItemSeparator />}
+              <Item size="sm">
+                <ItemHeader>
+                  <ItemTitle>{w.name}</ItemTitle>
+                  <ItemDescription>
+                    {w.agents === 1 ? "1 agente" : `${w.agents} agentes`}
+                  </ItemDescription>
+                </ItemHeader>
+                <ItemActions>
+                  <DictionaryValue dict={docWorkspaceStatus} value={w.status} />
+                </ItemActions>
+              </Item>
+            </React.Fragment>
           ))}
-        </div>
+        </ItemGroup>
       )}
     </ActionListDialog>
   </DocBrowserActionProvider>,
 );
 ```
 
+`actions` ocupa o extremo direito da linha acima da lista e costuma receber a criação do recurso;
+`note` acrescenta um contexto curto do lado oposto. Quando a criação precisar de um formulário
+próprio em modal, use [`ActionFormDialog`](/ui/action-form-dialog).
+
 ## Estado adicional do consumidor
 
-Quando o modal depender de outra consulta, `loading` combina esse carregamento ao estado da lista.
-Use `empty` para substituir a regra de vazio, por exemplo enquanto um formulário de criação ocupa o
-corpo do modal.
+Quando os itens dependerem de outra consulta, `loading` soma esse carregamento ao estado da lista.
+Use `empty` para substituir a regra de vazio. No exemplo, um formulário de criação aberto no corpo
+conta como conteúdo, e o modal deixa de exibir o estado vazio enquanto a pessoa preenche o
+formulário.
 
 ```tsx
-<ActionListDialog
+const [adding, setAdding] = useState(false);
+const roles = useListAction<Role>(roleListContract, { workspaceId });
+const roleOptions = roles.items.map((role) => ({ value: role.id, label: role.name }));
+
+<ActionListDialog<Agent, { workspaceId: string }>
   action={agentListContract}
   input={{ workspaceId }}
-  loading={rolesLoading}                                  // A query irmã.
-  empty={(repos) => repos.length === 0 && !adding}        // Form inline aberto ⇒ children.
-  ...
-/>
+  open={open}
+  onOpenChange={setOpen}
+  title="Agentes"
+  actions={<Button onClick={() => setAdding(true)}>Criar agente</Button>}
+  loading={roles.isLoading}
+  empty={(agents) => agents.length === 0 && !adding}
+>
+  {(agents) => (
+    <>
+      {adding && (
+        <ActionForm
+          action={agentCreateContract}
+          defaultValues={{ workspaceId }}
+          fieldOptions={{ role: roleOptions }}
+          onSuccess={() => setAdding(false)}
+          onCancel={() => setAdding(false)}
+        />
+      )}
+      <AgentItems agents={agents} />
+    </>
+  )}
+</ActionListDialog>;
 ```
 
 ## Propriedades de ActionListDialog
 
 | Propriedade                                | Tipo                                | Padrão               | Descrição                                                                                         |
 | ------------------------------------------ | ----------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------- |
-| `action / input`                           | `ListAction / TInput`               | `input`: `{}`        | O contrato e o escopo base opcional da consulta — mudou o input, re-busca; `invalidates` de forms/triggers refaz sozinho. |
-| `open / onOpenChange`                      | `boolean / (open) => void`          |                      | Controle do modal — de quem orquestra.                                                            |
+| `action / input`                           | `ListAction / TInput`               | `input`: `{}`        | O contrato e o escopo base da consulta. Uma mudança em `input` refaz a consulta; as invalidações declaradas por forms e triggers também. |
+| `open / onOpenChange`                      | `boolean / (open) => void`          |                      | Estado controlado do modal.                                                                       |
 | `title`                                    | `string`                            |                      | Nome da lista exibido no cabeçalho fixo.                                                          |
 | `intro`                                    | `ReactNode`                         |                      | Contexto relevante no início do corpo, como texto ou `Alert`.                                     |
-| `children`                                 | `(items, refetch) => ReactNode`     |                      | O layout dos itens (cards/linhas) — os estados já saíram daqui.                                   |
-| `note`                                     | `ReactNode`                         |                      | Contexto curto à esquerda da toolbar. O total de itens já aparece no rodapé do `ActionList`.      |
-| `actions`                                  | `ReactNode`                         |                      | Ação à direita da toolbar — em geral o botão de criar.                                            |
-| `empty`                                    | `(items) => boolean`                | `items.length === 0` | Sobrepõe o vazio derivado.                                                                        |
-| `loading`                                  | `boolean`                           |                      | Carga extra agregada à do fetch (query irmã).                                                     |
+| `children`                                 | `(items, refetch) => ReactNode`     |                      | A composição dos itens. Carregamento, erro e vazio já são tratados pelo `ActionList`.            |
+| `note`                                     | `ReactNode`                         |                      | Contexto curto à esquerda da linha de ações. O total de itens já aparece no rodapé do `ActionList`. |
+| `actions`                                  | `ReactNode`                         |                      | Ação à direita da linha de ações, em geral a criação do recurso.                                  |
+| `empty`                                    | `(items) => boolean`                | `items.length === 0` | Substitui a regra que decide o estado vazio.                                                      |
+| `loading`                                  | `boolean`                           |                      | Carregamento adicional somado ao da consulta, como uma consulta de que os `children` dependem.    |
 | `emptyMessage / errorMessage / retryLabel` | `string`                            | `'Nenhum resultado.'` / `'Não foi possível carregar.'` / `'Tentar de novo'` | Textos dos estados, herdados do `ActionList`; `retryLabel` nomeia a ação somente com ícone e seu tooltip. |
-| `className`                                | `string`                            | `max-w-3xl`          | Largura do DialogContent.                                                                         |
+| `className`                                | `string`                            | `max-w-3xl`          | Classes do `DialogContent`, em geral para ajustar a largura.                                      |