@softize/opus 12.11.0 → 13.0.0

package/src/ui/docs/DocBrowser.tsx

@@ -12,10 +12,16 @@
  * Nos dois, navegar emite `popstate`: host que guarda o path por conta própria acompanha.
  * `basePath` adapta o prefixo das URLs (`/docs` no Maestro, `/__docs` nos apps).
  */
-import { useEffect } from 'react'
+import { useEffect, useState } from 'react'
 import { DOC_SECTIONS, type DocSection, type DocEntry } from './registry'
 import { Pane, Split } from '../components/patterns/split.tsx'
-import { PaneBody, Sidebar, SidebarNav, type SidebarNavGroup } from '../components/patterns/sidebar.tsx'
+import {
+  PaneBody,
+  Sidebar,
+  SidebarGroupLabel,
+  SidebarItem,
+  SidebarTreeGroup,
+} from '../components/patterns/sidebar.tsx'
 import { navigate, usePathname } from '../router.ts'
 
 function findPage(sections: DocSection[], slug: string): DocEntry | undefined {
@@ -42,6 +48,95 @@ export interface DocBrowserProps {
   documentTitle?: (pageTitle: string) => string
 }
 
+function DocSidebarTree({
+  sections,
+  activeSlug,
+  onSelect,
+}: {
+  sections: DocSection[]
+  activeSlug?: string
+  onSelect: (slug: string) => void
+}): React.ReactElement {
+  const [closedGroups, setClosedGroups] = useState<Set<string>>(() => new Set())
+
+  useEffect(() => {
+    const activeGroup = sections.flatMap((section, sectionIndex) =>
+      section.groups.map((group, groupIndex) => ({
+        key: `${sectionIndex}:${groupIndex}`,
+        group,
+      })),
+    ).find(({ group }) => group.pages.some((page) => page.slug === activeSlug))
+
+    if (activeGroup === undefined) return
+    setClosedGroups((current) => {
+      if (!current.has(activeGroup.key)) return current
+      const next = new Set(current)
+      next.delete(activeGroup.key)
+      return next
+    })
+  }, [activeSlug, sections])
+
+  const toggleGroup = (key: string): void => {
+    setClosedGroups((current) => {
+      const next = new Set(current)
+      if (next.has(key)) next.delete(key)
+      else next.add(key)
+      return next
+    })
+  }
+
+  const renderPage = (page: DocEntry): React.ReactElement => (
+    <SidebarItem
+      key={page.slug}
+      label={page.title}
+      badge={page.badge === undefined ? undefined : (
+        <span className="rounded border border-border/60 px-1 font-mono text-[0.625rem] leading-tight text-muted-foreground/60">
+          {page.badge}
+        </span>
+      )}
+      active={page.slug === activeSlug}
+      onClick={() => onSelect(page.slug)}
+    />
+  )
+
+  return (
+    <nav aria-label="Navegação da documentação" className="space-y-4 p-2">
+      {sections.map((section, sectionIndex) => (
+        <div key={`${section.label}:${sectionIndex}`} className="space-y-0.5">
+          {section.label.trim() !== '' && (
+            <SidebarGroupLabel>{section.label}</SidebarGroupLabel>
+          )}
+          {section.groups.map((group, groupIndex) => {
+            const key = `${sectionIndex}:${groupIndex}`
+            if (group.pages.length === 0) return null
+            if ((group.label ?? '').trim() === '') {
+              return group.pages.map((page) => renderPage(page))
+            }
+
+            const expanded = !closedGroups.has(key)
+            return (
+              <div key={key} className="space-y-0.5">
+                <SidebarItem
+                  label={group.label!}
+                  icon={group.icon}
+                  expanded={expanded}
+                  onToggle={() => toggleGroup(key)}
+                  onClick={() => toggleGroup(key)}
+                />
+                {expanded && (
+                  <SidebarTreeGroup>
+                    {group.pages.map((page) => renderPage(page))}
+                  </SidebarTreeGroup>
+                )}
+              </div>
+            )
+          })}
+        </div>
+      ))}
+    </nav>
+  )
+}
+
 export function DocBrowser({
   basePath = '/docs',
   path: controlledPath,
@@ -76,31 +171,15 @@ export function DocBrowser({
     if (page && documentTitle) document.title = documentTitle(page.title)
   }, [page, documentTitle])
 
-  // Seção → grupo, e os grupos da seção → subgrupos. O tier do meio NÃO pode ser
-  // achatado: `docSectionsFromFolder` o preenche a partir de sub-pasta (ou do
-  // frontmatter `group:`), que é o caminho do `opusDocs({ source })`.
-  const navGroups: SidebarNavGroup[] = sections.map((section) => ({
-    label: section.label,
-    subgroups: section.groups.map((g) => ({
-      label: g.label,
-      items: g.pages.map((p) => ({
-        id: p.slug,
-        label: p.title,
-        badge: p.badge === undefined ? undefined : <span className="rounded border border-border/60 px-1 font-mono text-[0.625rem] leading-tight text-muted-foreground/60">{p.badge}</span>,
-      })),
-    })),
-  }))
-
   return (
     <Split className="h-full">
-      <Pane inset="none" className="w-56">
+      <Pane initialSize="14rem" inset="none">
         <Sidebar className="w-full">
           <PaneBody>
-            <SidebarNav
-              groups={navGroups}
-              activeId={page?.slug}
-              navLabel="Navegação da documentação"
-              onSelect={(slug) => go(`${basePath}/${slug}`)}
+            <DocSidebarTree
+              sections={sections}
+              activeSlug={page?.slug}
+              onSelect={(nextSlug) => go(`${basePath}/${nextSlug}`)}
             />
           </PaneBody>
         </Sidebar>

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

@@ -1,7 +1,8 @@
-## Padrão (single)
+## Um painel por vez
 
-`type=single` abre um painel por vez. `collapsible` deixa fechar o que está aberto — sem ele,
-sempre fica um item expandido. `defaultValue` deixa o estado com o componente.
+Use `type="single"` quando somente um painel deve permanecer aberto. Com `collapsible`, a pessoa
+também pode fechar o painel atual; sem essa propriedade, um item permanece expandido.
+`defaultValue` define o item inicialmente aberto no modo não controlado.
 
 ```tsx preview
 <Accordion type="single" collapsible defaultValue="overview" className="w-full">
@@ -28,8 +29,8 @@ sempre fica um item expandido. `defaultValue` deixa o estado com o componente.
 
 ## Múltiplos abertos
 
-`type=multiple` permite vários painéis expandidos ao mesmo tempo — `defaultValue` vira um
-array com os itens abertos de saída.
+Use `type="multiple"` quando os painéis puderem permanecer abertos ao mesmo tempo. Nesse modo,
+`defaultValue` recebe um array com os itens inicialmente expandidos.
 
 ```tsx preview
 <Accordion type="multiple" defaultValue={['skills', 'prompt']} className="w-full">
@@ -48,10 +49,10 @@ array com os itens abertos de saída.
 </Accordion>
 ```
 
-## Controlado (com estado)
+## Estado controlado
 
-No modo `single`, `value`/`onValueChange` tiram o estado do componente — dá pra abrir um item
-de fora. Exemplo **com estado** (o `render()` deixa o hook rodar):
+Use `value` e `onValueChange` quando outro elemento ou estado do aplicativo também precisar
+controlar o painel aberto.
 
 ```tsx preview
 const [open, setOpen] = React.useState('developer')
@@ -74,13 +75,18 @@ render(
 )
 ```
 
-## Props
+## Propriedades de Accordion
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `type` (Accordion) | `'single' \| 'multiple'` | | single abre um painel por vez; multiple permite vários. |
-| `collapsible` (Accordion) | `boolean` | `false` | Só no single — permite fechar o item aberto. |
-| `defaultValue` (Accordion) | `string \| string[]` | | Item(ns) aberto(s) no modo não controlado. |
-| `value` (Accordion) | `string \| string[]` | | Item(ns) aberto(s) no modo controlado — pareie com onValueChange. |
-| `onValueChange` (Accordion) | `(value) => void` | | Chamado quando o usuário abre ou fecha um item. |
-| `value` (AccordionItem) | `string` | | Identificador do item — é o que defaultValue/value referenciam. |
+| `type` | `'single' \| 'multiple'` | | `single` abre um painel por vez; `multiple` permite manter vários abertos. |
+| `collapsible` | `boolean` | `false` | No modo `single`, permite fechar o item aberto. |
+| `defaultValue` | `string \| string[]` | | Item ou itens inicialmente abertos no modo não controlado. |
+| `value` | `string \| string[]` | | Item ou itens abertos no modo controlado. Use com `onValueChange`. |
+| `onValueChange` | `(value) => void` | | Chamado quando a pessoa abre ou fecha um item. |
+
+## Propriedades de AccordionItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Identificador usado por `defaultValue` e `value` no `Accordion`. |

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

@@ -1,7 +1,7 @@
-## Form como card
+## Formulário em uma seção
 
-O ActionForm dentro de um Card — header, conteúdo e rodapé, no respiro do Card (sem divisor nem
-faixa de modal). Pra estruturar uma seção da página como painel. O título é opcional.
+Use `ActionFormCard` para apresentar um `ActionForm` como seção delimitada da página. O componente
+aplica a estrutura e o espaçamento de `Card`, sem a faixa de ações de um modal. O título é opcional.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -14,11 +14,11 @@ faixa de modal). Pra estruturar uma seção da página como painel. O título é
 </DocBrowserActionProvider>
 ```
 
-## Props
+## Propriedades de ActionFormCard
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `title` | `string` | | Título do header (com divisor embaixo). Sem ele, o card começa direto no corpo. |
+| `title` | `string` | | Título do cabeçalho. Sem ele, o card começa diretamente pelo corpo. |
 | `description` | `string` | | Subtítulo opcional, abaixo do título. |
-| `action / defaultValues / fieldOptions / submitLabel / onSuccess / onCancel` | `— (iguais ao ActionForm)` | | O resto é o ActionForm — o card injeta o corpo (CardBody) e o rodapé (CardFooter) por baixo. |
-| `cardClassName` | `string` | | Classes da SUPERFÍCIE do card (ex.: largura). `className` vai pro `<form>`. |
+| `action / defaultValues / fieldOptions / submitLabel / onSuccess / onCancel` | Propriedades de `ActionForm` | | Mantêm o mesmo comportamento do formulário interno. |
+| `cardClassName` | `string` | | Classes aplicadas à superfície do card. `className` continua sendo aplicado ao `<form>`. |

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

@@ -1,8 +1,8 @@
-## Form em modal
+## Formulário em um modal
 
-O open é de quem orquestra; o fechamento no sucesso é do pattern. Header e X fixos, os campos
-scrollam, o rodapé é a faixa da casa. O preview roda num client de mentira — no app, o contrato
-vem do spec.
+Use `ActionFormDialog` quando o formulário precisar interromper o fluxo atual sem levar a pessoa
+para outra página. O consumidor controla `open`; depois de uma execução bem-sucedida, o componente
+fecha o modal. O cabeçalho e o rodapé permanecem visíveis enquanto os campos podem rolar.
 
 ```tsx preview
 const [open, setOpen] = useState(false)
@@ -22,11 +22,11 @@ render(
 )
 ```
 
-## Props
+## Propriedades de ActionFormDialog
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `open / onOpenChange` | `boolean / (open: boolean) => void` | | Controle do modal — o pattern chama onOpenChange(false) no sucesso e no Cancelar. |
-| `title / description` | `string` | | O DialogHeader fixo — description é opcional. |
+| `open / onOpenChange` | `boolean / (open: boolean) => void` | | Estado controlado do modal. `onOpenChange(false)` é chamado no sucesso e ao cancelar. |
+| `title / description` | `string` | | Conteúdo do cabeçalho; `description` é opcional. |
 | `submitLabel` | `string` | `'Salvar'` | Resultado da ação principal. Em criação, informe `Criar {recurso}`; em edição, `Salvar alterações`. |
-| `…ActionFormProps` | `action, defaultValues, onSuccess, fieldOptions…` | | Todo o resto desce pro ActionForm interno — mesma API da página dele. |
+| `…ActionFormProps` | `action, defaultValues, onSuccess, fieldOptions…` | | Demais propriedades repassadas ao `ActionForm` interno. |

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

@@ -1,8 +1,8 @@
-## Form derivado do contrato
+## Formulário derivado do contrato
 
-Zero JSX de campo: enum vira Select, string longa vira Textarea, obrigatório ganha o asterisco. O
-preview roda num client de mentira — digite "Softize" no nome pra ver o erro de servidor inline; o
-submit só habilita com mudança real (dirty).
+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.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -10,13 +10,12 @@ submit só habilita com mudança real (dirty).
 </DocBrowserActionProvider>
 ```
 
-## Composição (diagramação livre)
+## Composição dos campos
 
-Com children, o AUTO desliga e você diagrama: `<ActionFormField name />` coloca cada campo — com
-label, hint, widget, erro e asterisco derivados do contrato — onde quiser. Condicional é JSX;
-opções de runtime entram por prop no campo. O comportamento (submit, validação, toast,
-invalidação) continua encapsulado — e o espaçamento é 100% seu: o campo não impõe margem
-(quem diagrama usa grid/gap/space-y como quiser).
+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`.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -35,8 +34,8 @@ invalidação) continua encapsulado — e o espaçamento é 100% seu: o campo n
 
 ## Valores iniciais e rótulos
 
-defaultValues pré-carrega (modo edição); submitLabel/cancelLabel trocam o rodapé. O onCancel é de
-quem orquestra (fechar drawer, voltar…).
+`defaultValues` preenche o formulário para edição. `submitLabel` e `cancelLabel` nomeiam as ações;
+`onCancel` devolve ao consumidor a decisão de fechar um painel ou navegar para outra página.
 
 ```tsx preview col md
 <DocBrowserActionProvider>
@@ -51,8 +50,7 @@ quem orquestra (fechar drawer, voltar…).
 
 ## Pré-requisitos
 
-O driver precisa dos dois providers no root — exatamente o wiring do admin (o consumidor
-canônico).
+Monte os providers de consulta e execução uma vez na raiz do aplicativo:
 
 ```tsx
 /* main.tsx do app. */
@@ -63,35 +61,32 @@ canônico).
 </QueryClientProvider>
 ```
 
-## Props
+## Propriedades de ActionForm
 
-| Prop | Tipo | Default | Descrição |
+| 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 / onCancel` | `string / string / () => void` | `'Salvar' / 'Cancelar'` | Rodapé do form — o Cancelar só aparece com onCancel. |
 | `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 AUTO monta todos os campos na ordem do contrato. |
+| `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. |
 
-## ActionFormField
+## Propriedades de ActionFormField
 
-| Prop | Tipo | Descrição |
+| 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` numa grid). |
+| `className` | `string` | Classes do invólucro (ex.: `col-span-2` em uma grid). |
 
-## De onde vêm as opções de um select
+## Origem das opções de seleção
 
-Precedência, da mais específica pra mais automática: **prop `options` do campo** >
-**`fieldOptions` do form** > **`options` do FieldSpec no contrato** (`{ kind: 'dictionary',
-ref }` resolve pelos dicts do `<TbdlibProvider dicts={{ ref: meuDict }}>` — o `DictType` do
-`t.dict` encaixa direto; `{ kind: 'static', items }` renderiza como declarado) > **meta do
-`t.dict` no schema** (zero-config: campo `meuDict.zod()` — ou multiselect com elemento dict —
-resolve value→label pela meta que viaja no contrato, sem registry) > **chaves cruas do
-z.enum**. Campo texto com opções declaradas (runtime ou spec) vira single-select por-id.
+As opções seguem esta precedência: `options` no campo, `fieldOptions` no formulário, `options` no
+`FieldSpec`, metadata de `t.dict` no schema e, por último, as chaves de `z.enum`. Uma fonte mais
+específica substitui as seguintes. Dicionários registrados no `TbdlibProvider` resolvem rótulos por
+referência; itens estáticos permanecem como declarados no contrato.
 
 ## Widgets declarativos
 
@@ -103,11 +98,10 @@ escolha rica em card, com conteúdo de apoio; para uma lista textual comum, pref
 Outros identificadores continuam válidos como metadado
 para renderers próprios; o `ActionForm` aplica sua inferência normal quando não reconhece o widget.
 
-## Controle custom: useActionFormContext
+## Controle próprio com useActionFormContext
 
-Campo com UI própria (grade de permissões, canvas…) que nenhum widget cobre? No modo
-composição, o hook dá acesso ao form do contrato — o campo custom participa do submit
-sem abandonar o `<ActionForm>`:
+Quando nenhum widget atender ao campo, use `useActionFormContext` no modo de composição. O controle
+próprio participa da mesma validação e execução sem abandonar o `ActionForm`:
 
 ```tsx
 import { useActionFormContext } from '@softize/opus/ui/react'
@@ -132,4 +126,4 @@ function PermissionGrid() {
 ```
 
 O contexto também expõe `shape` (Zod por campo), `fields` (FieldSpec) e `fieldOptions`.
-Fora de um `<ActionForm>`, o hook explode com mensagem clara — igual ao `ActionFormField`.
+Fora de um `<ActionForm>`, o hook lança um erro que informa o provider ausente.

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

@@ -1,6 +1,9 @@
-## ListAction em modal
+## Listagem em um modal
 
-O modo modal da listagem, action-driven: a lista é query-backed (busca no mount, re-busca quando o input muda e refaz sozinha quando um form/trigger invalida a action), os estados derivam do fetch, e a nota da toolbar já vem com o "N no total". Children diagrama os itens — composição, como nos irmãos.
+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.
 
 ```tsx preview col
 const [open, setOpen] = useState(false)
@@ -38,9 +41,11 @@ render(
 )
 ```
 
-## O que o contrato não sabe
+## Estado adicional do consumidor
 
-Dois escape hatches, pros casos em que o modal agrega mais de uma fonte: `loading` soma a carga de uma query irmã (ex.: os papéis que os cards precisam pra rotular) e `empty` sobrepõe o vazio derivado (ex.: com o form inline de criar aberto, a lista vazia mostra o form, não o emptyText).
+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.
 
 ```tsx
 <ActionListDialog
@@ -52,9 +57,9 @@ Dois escape hatches, pros casos em que o modal agrega mais de uma fonte: `loadin
 />
 ```
 
-## Props
+## Propriedades de ActionListDialog
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `action / input` | `ListAction / TInput` | | O contrato e os filtros — mudou o input, re-busca; `invalidates` de forms/triggers refaz sozinho. |
 | `open / onOpenChange` | `boolean / (open) => void` | | Controle do modal — de quem orquestra. |