@softize/opus 18.0.1 → 18.1.1

package/src/ui/components/primitives/select.tsx

@@ -92,7 +92,7 @@ interface SelectCustomBase extends SelectBaseProps {
   clearable?: boolean
   /** `outline`: compacto com borda; `ghost`: compacto sem borda nem fundo. */
   variant?: 'default' | 'outline' | 'ghost'
-  /** Placeholder enquanto se digita a busca (cai pro `placeholder`). */
+  /** Placeholder da linha de busca dentro da lista. Default: `'Buscar…'`. */
   searchPlaceholder?: string
   emptyText?: string
   /** Ação custom no FIM do campo, dentro do controle (antes do chevron) — ex.: um botão que
@@ -161,7 +161,7 @@ function NativeSelect({
         aria-describedby={rest['aria-describedby']}
         onChange={(e) => onChange(e.target.value)}
         className={cn(
-          "h-9 w-full min-w-0 appearance-none rounded-md border border-input bg-transparent px-3 py-2 pr-9 text-sm transition-[color,box-shadow] outline-none selection:bg-primary selection:text-primary-foreground disabled:pointer-events-none disabled:cursor-not-allowed data-[size=sm]:h-8 data-[size=sm]:py-1 data-[shape=pill]:rounded-full dark:bg-input/30 dark:hover:bg-input/50",
+          "h-9 w-full min-w-0 appearance-none rounded-md border border-input bg-muted/30 px-3 py-2 pr-9 text-sm transition-[color,box-shadow] outline-none selection:bg-primary selection:text-primary-foreground disabled:pointer-events-none disabled:cursor-not-allowed data-[size=sm]:h-8 data-[size=sm]:py-1 data-[shape=pill]:rounded-full dark:bg-input/30 dark:hover:bg-input/50",
           focusRing,
           'aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 dark:aria-invalid:ring-context-danger/40',
           icon ? 'pl-9' : '',
@@ -360,7 +360,7 @@ function CustomSelect(props: Exclude<SelectProps, SelectNativeProps>): React.Rea
                 'flex items-center gap-1.5 rounded-md outline-none transition-[color,box-shadow] data-[shape=pill]:rounded-full',
                 ghost
                   ? cn('min-h-9 px-3 py-1 text-muted-foreground hover:bg-muted hover:text-foreground data-[size=sm]:min-h-8 data-[size=sm]:px-2', focusRingWithin)
-                  : cn('min-h-9 border border-input bg-transparent px-3 py-1 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 data-[size=sm]:min-h-8 data-[size=sm]:py-0.5 dark:bg-input/30 dark:aria-invalid:ring-context-danger/40', focusRingWithin),
+                  : cn('min-h-9 border border-input bg-muted/30 px-3 py-1 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 data-[size=sm]:min-h-8 data-[size=sm]:py-0.5 dark:bg-input/30 dark:aria-invalid:ring-context-danger/40', focusRingWithin),
                 variant === 'default' && 'flex-wrap',
                 outline && 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-input/50',
                 "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",

package/src/ui/components/primitives/table.tsx

@@ -2,36 +2,45 @@ import * as React from "react"
 
 import { cn } from '../../lib/cn.ts'
 
+type TableVariant = 'plain' | 'framed'
+const TableVariantContext = React.createContext<TableVariant>('plain')
+
 export interface TableProps extends React.ComponentProps<"table"> {
   /** `framed` aplica a moldura canônica de datagrid no contêiner da tabela. */
-  variant?: 'plain' | 'framed'
+  variant?: TableVariant
 }
 
 function Table({ className, variant = 'plain', ...props }: TableProps) {
   return (
-    <div
-      data-slot="table-container"
-      data-variant={variant}
-      className={cn(
-        "relative w-full overflow-x-auto",
-        variant === 'framed' &&
-          'rounded-lg border border-border [&_[data-slot=table-header]]:bg-muted/20',
-      )}
-    >
-      <table
-        data-slot="table"
-        className={cn("w-full caption-bottom text-sm", className)}
-        {...props}
-      />
-    </div>
+    <TableVariantContext.Provider value={variant}>
+      <div
+        data-slot="table-container"
+        data-variant={variant}
+        className={cn(
+          "relative w-full overflow-x-auto",
+          variant === 'framed' && 'rounded-lg border border-border',
+        )}
+      >
+        <table
+          data-slot="table"
+          className={cn("w-full caption-bottom text-sm", className)}
+          {...props}
+        />
+      </div>
+    </TableVariantContext.Provider>
   )
 }
 
 function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
+  const variant = React.useContext(TableVariantContext)
   return (
     <thead
       data-slot="table-header"
-      className={cn("[&_tr]:border-b", className)}
+      className={cn(
+        "[&_tr]:border-b",
+        variant === 'framed' && 'bg-muted/30 dark:bg-input/30',
+        className,
+      )}
       {...props}
     />
   )

package/src/ui/components/primitives/tabs.tsx

@@ -11,6 +11,9 @@ import { controlHeight, type ControlSize } from './control.ts'
 // da escala de control.ts.
 type TabsSize = Extract<ControlSize, "default" | "sm">
 const TabsSizeContext = React.createContext<TabsSize>("default")
+type TabsOrientation = "horizontal" | "vertical"
+const TabsOrientationContext = React.createContext<TabsOrientation>("horizontal")
+const TabsListVariantContext = React.createContext<"default" | "line">("default")
 
 function Tabs({
   className,
@@ -19,19 +22,21 @@ function Tabs({
   ...props
 }: React.ComponentProps<typeof TabsPrimitive.Root> & { size?: TabsSize }) {
   return (
-    <TabsSizeContext.Provider value={size}>
-      <TabsPrimitive.Root
-        data-slot="tabs"
-        data-orientation={orientation}
-        data-size={size}
-        orientation={orientation}
-        className={cn(
-          "group/tabs flex gap-2 data-[orientation=horizontal]:flex-col",
-          className
-        )}
-        {...props}
-      />
-    </TabsSizeContext.Provider>
+    <TabsOrientationContext.Provider value={orientation}>
+      <TabsSizeContext.Provider value={size}>
+        <TabsPrimitive.Root
+          data-slot="tabs"
+          data-orientation={orientation}
+          data-size={size}
+          orientation={orientation}
+          className={cn(
+            "group/tabs flex gap-2 data-[orientation=horizontal]:flex-col",
+            className
+          )}
+          {...props}
+        />
+      </TabsSizeContext.Provider>
+    </TabsOrientationContext.Provider>
   )
 }
 
@@ -44,7 +49,7 @@ const tabsListVariants = cva(
     variants: {
       variant: {
         default: "bg-muted",
-        line: "gap-1 bg-transparent",
+        line: "gap-5 bg-transparent",
       },
     },
     defaultVariants: {
@@ -55,27 +60,66 @@ const tabsListVariants = cva(
 
 function TabsList({
   className,
+  children,
+  style,
   variant = "default",
   ...props
 }: React.ComponentProps<typeof TabsPrimitive.List> &
   VariantProps<typeof tabsListVariants>) {
   // O size vem do <Tabs> (contexto) — a altura mora aqui, na list.
   const size = React.useContext(TabsSizeContext)
+  const orientation = React.useContext(TabsOrientationContext)
+  const normalizedVariant = variant ?? "default"
+  const hasHorizontalLine = normalizedVariant === "line" && orientation === "horizontal"
   return (
-    <TabsPrimitive.List
-      data-slot="tabs-list"
-      data-variant={variant}
-      data-size={size}
-      className={cn(tabsListVariants({ variant }), controlHeight[size], className)}
-      {...props}
-    />
+    <TabsListVariantContext.Provider value={normalizedVariant}>
+      <TabsPrimitive.List
+        data-slot="tabs-list"
+        data-variant={normalizedVariant}
+        data-size={size}
+        className={cn(tabsListVariants({ variant: normalizedVariant }), controlHeight[size], className)}
+        style={{
+          ...(hasHorizontalLine
+            ? { position: "relative", width: "100%", height: "auto", justifyContent: "flex-start" }
+            : {}),
+          ...style,
+        }}
+        {...props}
+      >
+        {hasHorizontalLine && (
+          <span
+            aria-hidden="true"
+            data-slot="tabs-line"
+            style={{
+              position: "absolute",
+              insetInline: "calc(var(--opus-inline-gutter, 0rem) * -1)",
+              bottom: 0,
+              borderBottomWidth: "0.0625rem",
+              borderBottomStyle: "solid",
+              borderBottomColor: "var(--border)",
+              pointerEvents: "none",
+            }}
+          />
+        )}
+        {children}
+      </TabsPrimitive.List>
+    </TabsListVariantContext.Provider>
   )
 }
 
 function TabsTrigger({
   className,
+  style,
+  icon,
+  children,
   ...props
-}: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
+}: React.ComponentProps<typeof TabsPrimitive.Trigger> & {
+  /** Ícone decorativo antes do rótulo. Em uma aba sem texto, declare também `aria-label`. */
+  icon?: React.ReactNode
+}) {
+  const variant = React.useContext(TabsListVariantContext)
+  const orientation = React.useContext(TabsOrientationContext)
+  const hasHorizontalLine = variant === "line" && orientation === "horizontal"
   return (
     <TabsPrimitive.Trigger
       data-slot="tabs-trigger"
@@ -85,10 +129,23 @@ function TabsTrigger({
         "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent dark:group-data-[variant=line]/tabs-list:data-[state=active]:border-transparent dark:group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent",
         "data-[state=active]:bg-background data-[state=active]:text-foreground dark:data-[state=active]:border-input dark:data-[state=active]:text-foreground",
         "after:absolute after:bg-foreground after:opacity-0 after:transition-opacity group-data-[orientation=horizontal]/tabs:after:inset-x-0 group-data-[orientation=horizontal]/tabs:after:bottom-[-1px] group-data-[orientation=horizontal]/tabs:after:h-0.5 group-data-[orientation=vertical]/tabs:after:inset-y-0 group-data-[orientation=vertical]/tabs:after:-right-1 group-data-[orientation=vertical]/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-[state=active]:after:opacity-100",
+        hasHorizontalLine && "px-0 py-3",
         className
       )}
+      style={{ ...(hasHorizontalLine ? { flex: "none", height: "auto" } : {}), ...style }}
       {...props}
-    />
+    >
+      {icon !== undefined && (
+        <span
+          data-slot="tabs-trigger-icon"
+          aria-hidden="true"
+          className="flex size-4 shrink-0 items-center justify-center [&_svg]:size-4"
+        >
+          {icon}
+        </span>
+      )}
+      {children}
+    </TabsPrimitive.Trigger>
   )
 }
 

package/src/ui/components/primitives/textarea.tsx

@@ -7,7 +7,7 @@ function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
     <textarea
       data-slot="textarea"
       className={cn(
-        "flex field-sizing-content min-h-16 w-full rounded-md border border-input bg-transparent px-3 py-2 text-base transition-[color,box-shadow] outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 md:text-sm dark:bg-input/30 dark:aria-invalid:ring-context-danger/40",
+        "flex field-sizing-content min-h-16 w-full rounded-md border border-input bg-muted/30 px-3 py-2 text-sm transition-[color,box-shadow] outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 dark:bg-input/30 dark:aria-invalid:ring-context-danger/40",
         className
       )}
       {...props}

package/src/ui/components/primitives/toggle-group.tsx

@@ -18,6 +18,12 @@ const ToggleGroupContext = React.createContext<
   shape: "default",
 })
 
+type ToggleGroupItemProps = React.ComponentProps<typeof ToggleGroupPrimitive.Item> &
+  VariantProps<typeof toggleVariants> & {
+    'data-slot'?: string
+    'data-state'?: string
+  }
+
 function ToggleGroup({
   className,
   variant,
@@ -58,9 +64,10 @@ function ToggleGroupItem({
   variant,
   size,
   shape,
+  'data-slot': _composedSlot,
+  'data-state': _composedState,
   ...props
-}: React.ComponentProps<typeof ToggleGroupPrimitive.Item> &
-  VariantProps<typeof toggleVariants>) {
+}: ToggleGroupItemProps) {
   const context = React.useContext(ToggleGroupContext)
 
   return (

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

@@ -3,8 +3,11 @@
 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.
-Quando há cancelamento, o rodapé usa um `ButtonGroup` dividido: `Cancelar` aparece em `outline` e
-a ação principal permanece `solid`, ambas no tamanho normal de uma decisão modal.
+O rodapé agrupa as decisões em um `ButtonGroup` cuja largura acompanha o conteúdo: `Cancelar`
+aparece em `ghost` e a ação principal permanece `solid`, ambas no tamanho normal de uma decisão
+modal. `Cancelar` está sempre presente; sem `onCancel` próprio, ele fecha o modal.
+Com `footerDistribution="equal"`, as duas decisões dividem a faixa e `Cancelar` passa a `outline`,
+salvo escolha explícita em `cancelVariant`.
 
 ```tsx preview
 const [open, setOpen] = useState(false);
@@ -26,8 +29,12 @@ render(
 
 | Propriedade           | Tipo                                              | Padrão     | Descrição                                                                                                                                                                   |
 | --------------------- | ------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `open / onOpenChange` | `boolean / (open: boolean) => void`               |            | Estado controlado do modal. `onOpenChange(false)` é chamado no sucesso e ao cancelar.                                                                                       |
+| `open / onOpenChange` | `boolean / (open: boolean) => void`               |            | Estado controlado do modal. `onOpenChange(false)` é chamado no sucesso e, quando não há `onCancel` próprio, ao cancelar.                                                                                       |
 | `title`               | `string`                                          |            | Nome da tarefa exibido no cabeçalho.                                                                                                                                        |
 | `intro`               | `ReactNode`                                       |            | Contexto relevante no início do corpo, como texto ou `Alert`.                                                                                                               |
 | `submitLabel`         | `string`                                          | `'Salvar'` | Resultado da ação principal. Preserve o padrão em criação e edição comuns; sobrescreva apenas quando a operação tiver outro efeito, como `Renomear` ou `Criar nova versão`. |
-| `…ActionFormProps`    | `action, defaultValues, onSuccess, fieldOptions…` |            | Demais propriedades repassadas ao `ActionForm` interno.                                                                                                                     |
+| `footerDistribution`  | `'content' \| 'equal'`                            | `'content'` | Mantém a largura das ações pelo conteúdo ou divide a faixa igualmente. |
+| `cancelVariant`       | `'ghost' \| 'outline'`                            | `'ghost'`; `'outline'` com `equal` | Tratamento do `Cancelar`. O valor explícito vence o default derivado de `footerDistribution`. |
+| `onCancel`            | `() => void`                                      | fecha o modal | Substitui o fechamento padrão do `Cancelar`; nesse caso, o consumidor decide quando chamar `onOpenChange(false)`. |
+| `onSuccess`           | `(data: TData) => void`                           |            | Executado depois do sucesso, antes de o componente fechar o modal. |
+| `…ActionFormProps`    | `action, defaultValues, fieldOptions…`            |            | Demais propriedades repassadas ao `ActionForm` interno. `className`, `body` e `footer` não são repassadas: o wrapper as substitui para montar o corpo rolável e o footer do modal. |

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

@@ -34,7 +34,8 @@ invalidação continuam sob responsabilidade de `ActionForm`.
 
 ## Valores iniciais e rótulos
 
-`defaultValues` preenche o formulário para edição. `submitLabel` e `cancelLabel` nomeiam as ações;
+`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.
 
 ```tsx preview col md
@@ -42,12 +43,19 @@ invalidação continuam sob responsabilidade de `ActionForm`.
   <ActionForm
     action={docWorkspaceCreate}
     defaultValues={{ name: "Empresa X", status: "active" }}
-    submitLabel="Atualizar"
     onCancel={() => undefined}
   />
 </DocBrowserActionProvider>
 ```
 
+## 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:
@@ -75,7 +83,9 @@ ciclo de vida que o pattern não cobre; validação e execução continuam iguai
 | `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. Use `outline` quando ele dividir o footer com a ação principal.                                                                    |
+| `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.                                                        |

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

@@ -18,9 +18,7 @@ render(
       onOpenChange={setOpen}
       title="Workspaces"
       actions={
-        <Button size="sm" variant="outline">
-          <Plus /> Workspace
-        </Button>
+        <Button>Criar workspace</Button>
       }
       emptyMessage="Nenhum workspace."
     >
@@ -65,14 +63,14 @@ corpo do modal.
 
 | 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. |
+| `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.                                                            |
 | `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 \| (items) => ReactNode` | `"N no total"`       | Nota à esquerda da toolbar — o default é derivado dos itens.                                      |
+| `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ã).                                                     |
-| `emptyMessage / errorMessage / retryLabel` | `string`                            |                      | Textos dos estados; `retryLabel` nomeia a ação somente com ícone e seu tooltip.                   |
-| `className`                                | `string`                            | `sm:max-w-3xl`       | Largura do DialogContent.                                                                         |
+| `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.                                                                         |

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

@@ -64,6 +64,44 @@ Seletores inline mantêm largura previsível (`w-40`; lookup e múltiplo usam `w
 são truncados no controle, mas permanecem completos na lista. No modal de filtros avançados, o
 seletor ocupa toda a largura. Busca, filtros e período aparecem somente quando declarados.
 
+## Onde cada filtro aparece
+
+Cada filtro declara `placement`. `inline`, o padrão, mantém o controle na barra; `advanced` o leva
+ao modal “Filtros”; `external` mantém o filtro no estado navegável e no input, mas deixa a
+apresentação para o consumidor, como cards de status acima da lista. No modal, filtros com a mesma
+`section` formam um grupo, e `advancedFilters.columns` distribui os grupos em até três colunas.
+Campos de data avançados usam calendário. A antiga `advanced: true` continua aceita durante a
+migração e equivale a `placement: 'advanced'`.
+
+```tsx
+// No contrato:
+filters: {
+  status: {
+    label: 'Status',
+    type: 'select',
+    placement: 'inline',
+    options: { kind: 'dictionary', ref: 'workspace.status' },
+  },
+  client: {
+    label: 'Cliente',
+    type: 'lookup',
+    placement: 'advanced',
+    section: 'Relacionamento',
+    options: { kind: 'lookup', source: 'client.lookup' },
+  },
+  createdAt: { label: 'Criado em', type: 'date', placement: 'advanced', section: 'Datas' },
+  stage: {
+    label: 'Estágio',
+    type: 'select',
+    placement: 'external',
+    options: { kind: 'dictionary', ref: 'workspace.stage' },
+  },
+}
+
+// Na tela:
+<ActionList action={workspaceList} input={{}} advancedFilters={{ columns: 2 }} />
+```
+
 ## Colunas de dicionário
 
 Quando o campo de saída usa `t.dict().zod()`, a coluna apresenta o valor com `DictionaryValue` e
@@ -88,6 +126,10 @@ Renderer customizado reutiliza `EmptyValue`.
 
 Use `cells` somente quando uma coluna precisar de apresentação própria, como link, composição ou
 ação. A chave corresponde à `key` da coluna. Valores de dicionário não precisam desse override.
+O valor principal preserva o `text-sm` e o foreground da tabela; use
+`text-xs text-muted-foreground` apenas em metadado subordinado a outro valor na mesma célula.
+Cabeçalhos e `EmptyValue` continuam muted. O fato de uma coluna ser técnica, temporal ou menos
+destacada não reduz nem atenua seu valor principal.
 
 ```tsx preview col
 render(
@@ -291,6 +333,7 @@ render(
 | `state`         | `ActionFilterState`                                  |         | Estado atual da barra.                                                             |
 | `onStateChange` | `(next) => void`                                     |         | Recebe o estado completo depois de cada alteração.                                 |
 | `filterOptions` | `Record<string, SelectOption[]>`                     |         | Fornece opções de runtime para filtros select e lookup.                            |
+| `advancedFilters` | `{ columns?: 1 \| 2 \| 3 }`                       | `{ columns: 1 }` | Define as colunas do diálogo de filtros avançados; o Opus deriva a largura correspondente. |
 | `onRefresh`     | `() => Promise<void> \| void`                        |         | Exibe a ação de recarregar e executa a consulta do consumidor.                     |
 | `refreshing`    | `boolean`                                            | `false` | Desabilita e anima a ação de recarregar durante a consulta.                        |
 | `controls`      | `ReactNode`                                          |         | Controles auxiliares agrupados com recarregar em um `ButtonGroup` espaçado.        |
@@ -300,11 +343,11 @@ render(
 
 | Chave     | O que declara                                                                                                                                                                                                                                      |
 | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `columns` | `{ key, label, type?, sortable?, fit?, hidden?, dateFormat?, dictionary?, empty? }` — a tabela. `hidden` fica fora (base do futuro column picker); `dictionary` nomeia o dicionário do provider; `empty` dá o significado da ausência.             |
-| `filters` | `{ [nome]: { label, type, options?, multiple?, advanced?, depends?, … } }` — a toolbar. `advanced` vai para o modal; `depends` desabilita/cascateia; options `kind: 'lookup'` busca em uma action. Valor aplicado entra no input com o mesmo nome. |
+| `columns` | `{ key, label, type?, sortable?, fit?, hidden?, dateFormat?, dictionary?, empty? }` — a tabela. `hidden` nasce oculta e pode ser exibida pelo seletor de colunas; `dictionary` nomeia o dicionário do provider; `empty` dá o significado da ausência.             |
+| `filters` | `{ [nome]: { label, type, options?, multiple?, placement?, section?, depends?, … } }` — a toolbar. `placement` classifica o controle como `inline`, `advanced` ou `external`; filtros avançados com `section` são agrupados no diálogo; `external` mantém estado e input, mas delega a apresentação ao consumidor. `depends` desabilita/cascateia; options `kind: 'lookup'` busca em uma action. Valor aplicado entra no input com o mesmo nome. |
 | `text`    | `{ fields }` — liga a busca; convenção: param `q` no input. Com período/filtros no contrato ela fica à direita; sendo a ÚNICA forma de recorte, abre a linha.                                                                                      |
 | `sort`    | `{ fields, default }` — ordenação inicial; header ordenável escreve `sort: 'chave:dir'`.                                                                                                                                                           |
-| `periods` | `{ value, label }[]` — o controle de período (presets + Personalizado com calendário); materializa em `from`/`to` no input.                                                                                                                        |
+| `periods` | `{ value, label, default? }[]` — o controle de período (presets + Personalizado com calendário); `default: true` marca o preset inicial, senão vale o primeiro; materializa em `from`/`to` no input.                                                                                                                        |
 
 ## useListAction
 
@@ -318,16 +361,21 @@ chamar a action.
 
 | Propriedade             | Tipo                                  | Padrão                         | Descrição                                                                                                                                                                    |
 | ----------------------- | ------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `action`                | `ListAction<TInput, TItem>`           |                                | A ListAction do Opus (kind list, output = item, paginate cursor).                                                                                                            |
+| `action`                | `ListAction<TInput, TItem>`           |                                | A ListAction do Opus (kind list, output = item). A paginação envia `limit`/`page` e usa o `total` devolvido.                                                                                                            |
 | `input`                 | `TInput`                              |                                | O ESCOPO BASE (ex.: { workspaceId }) — a toolbar soma por cima, nunca sobrescreve.                                                                                           |
 | `cells`                 | `Record<string, (item) => ReactNode>` |                                | Células custom por cima das colunas do contrato (chave = column.key).                                                                                                        |
 | `filterOptions`         | `Record<string, SelectOption[]>`      |                                | Opções de runtime para os filtros select/lookup (chave = nome do filtro).                                                                                                    |
+| `advancedFilters`       | `{ columns?: 1 \| 2 \| 3 }`         | `{ columns: 1 }`               | Define as colunas dos grupos de filtros avançados; o Opus deriva a largura correspondente do diálogo.                                                                       |
+| `views`                 | `Record<string, ActionListView<TItem>>` |                         | Visualizações alternativas `{ label, icon?, render }`; o seletor alterna entre a tabela e estas. |
+| `beforeContent`         | `ReactNode`                           |                                | Conteúdo entre a toolbar e o corpo, como um resumo que reage ao recorte atual. |
 | `columns`               | `ActionListColumn<TItem>[]`           |                                | Tabela EXPLÍCITA — sobrepõe as colunas do contrato (escape hatch).                                                                                                           |
 | `children`              | `(items, refetch) => ReactNode`       |                                | Modo composição: layout livre; a toolbar segue. Tem precedência sobre columns.                                                                                               |
-| `batch`                 | `ActionListBatchAction[]`             |                                | Ações em lote: `{ label, can?, run, confirm?, destructive? }` — liga a multi-seleção.                                                                                        |
+| `batch`                 | `ActionListBatchAction[]`             |                                | Ações em lote: `{ label, can?, run, confirm?: { title, message? }, destructive? }` — liga a multi-seleção.                                                                                        |
 | `rowId`                 | `(item) => string`                    | `item.id`                      | Identidade da linha para seleção.                                                                                                                                            |
 | `pageSize`              | `number`                              | `50`                           | Itens por página padrão (vira `limit`/`page` no input; handler devolve `total`). O usuário troca no popover de exibição.                                                     |
 | `state / onStateChange` | `ActionListState / (next) => void`    | interno                        | Estado da toolbar controlado — para quem embala sincronizar com a URL.                                                                                                       |
+| `empty`                 | `(items) => boolean`                  | `items.length === 0`           | Sobrepõe o vazio derivado, por exemplo quando um formulário inline aberto conta como conteúdo. |
+| `loading`               | `boolean`                             |                                | Carga extra agregada à da consulta, como uma query irmã de que os `children` dependem. |
 | `emptyMessage`          | `string`                              | `'Nenhum resultado.'`          | Frase do estado vazio (o `Empty` do `DataState`).                                                                                                                            |
 | `errorMessage`          | `string`                              | `'Não foi possível carregar.'` | Título do aviso de erro; a ação de tentar de novo refaz a consulta.                                                                                                          |
 | `retryLabel`            | `string`                              | `'Tentar de novo'`             | Nome acessível e tooltip da ação de recuperação.                                                                                                                             |

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

@@ -2,7 +2,8 @@
 
 Use `ActionTrigger` para executar uma `SimpleAction` a partir de um botão. Sem confirmação, o clique
 inicia a operação, desabilita o controle durante a execução e apresenta as mensagens do contrato em
-um toast. O rótulo padrão vem de `action.label`.
+um toast. O rótulo padrão vem de `action.label` quando ele é texto; se o label for uma referência
+de tradução ou estiver ausente, o botão usa `action.name`.
 
 ```tsx preview
 <DocBrowserActionProvider>
@@ -58,7 +59,8 @@ não aciona o item clicável ao redor. `itemLabel` identifica o registro na mens
 ## Erro que a pessoa entende
 
 Quando a action falha, uma mensagem do servidor substitui o texto genérico somente nos erros de
-negócio `conflict`, `validation` e `not_found`:
+negócio `conflict`, `validation` e `not_found`, e nos erros de acesso `authorization` e
+`authentication`, cuja frase o runtime já entrega em pt-BR:
 
 > Este agente tem 3 conversas — desabilite em vez de excluir.
 
@@ -78,10 +80,12 @@ um atalho, um arrastar, um item de menu.
 |---|---|---|---|
 | `action` | `SimpleContract<TInput, TData>` | | A SimpleAction do Opus — label, messages e confirm vêm do contrato. |
 | `input` | `TInput` | | O que a action recebe — geralmente { id }. |
-| `label` | `string` | `action.label` | Sobrepõe o texto do botão. |
-| `context / variant / size` | `do Button` | gatilho: `primary`/`solid`; `danger` quando a action é `destructive`; no modo ícone, `ghost` e `neutral` (ou `danger` se destrutiva) / `icon-xs` | Visual do gatilho; `context` explícito vence. O botão de confirmar é sempre `solid`: `danger` quando a action é `destructive`, senão a prop `context` do gatilho (ou `primary`). |
-| `confirm` | `{ title, description?, actionLabel?, cancelLabel? }` | | Confirmação via prop — sobrepõe o ConfirmSpec do contrato. |
+| `label` | `string` | `action.label` quando é texto; senão `action.name` | Sobrepõe o texto do botão. |
+| `context / variant / size` | `do Button` | gatilho: `primary`/`solid`; `danger` quando a action é `destructive`; no modo ícone, `ghost` e `neutral` (ou `danger` se destrutiva) / `default`, ou `icon-xs` com `icon` | Visual do gatilho; `context` explícito vence. O botão de confirmar é sempre `solid`: `danger` quando a action é `destructive`, senão a prop `context` do gatilho (ou `primary`). |
+| `confirm` | `{ title, body?, actionLabel?, cancelLabel? }` | | Confirmação via prop — sobrepõe o ConfirmSpec do contrato. |
+| `disabled` | `boolean` | `false` | Desabilita o botão independentemente da execução em andamento. |
 | `onSuccess` | `(data: TData) => void` | | Pós-sucesso (cache já invalidado pelo action.invalidates). |
+| `onLoadingChange` | `(loading: boolean) => void` | | Informa início e fim da execução a quem coordena bloqueio entre várias actions. |
 | `icon` | `React.ReactNode` | | Torna o botão icon-only: rótulo no tooltip e no `aria-label`, clique que não vaza para o item. |
 | `itemLabel` | `string` | | Nome do alvo na pergunta (sai entre aspas, em destaque, antes da mensagem do contrato). |
 | `className` | `string` | | Classes do botão. O tamanho vem de `size` (escala única); com `icon`, o default é `icon-xs`. |

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

@@ -1,6 +1,6 @@
 ## Carregar um recurso
 
-Use `ActionView` para carregar um recurso por uma `ViewAction` e manter carregamento, erro e vazio no
+Use `ActionView` para carregar um recurso por uma `ViewAction` e manter carregamento e erro no
 mesmo fluxo. No exemplo, alterne entre os workspaces para observar o carregamento e a recuperação de
 erro. O consumidor compõe somente o conteúdo disponível.
 
@@ -12,7 +12,7 @@ render(
     <div className="w-full space-y-3">
       <div className="flex flex-wrap gap-2">
         <Button variant="outline" size="sm" onClick={() => setId('empresa-x')}>Empresa X</Button>
-        <Button variant="outline" size="sm" onClick={() => setId('softize-multica')}>Softize · Multica</Button>
+        <Button variant="outline" size="sm" onClick={() => setId('empresa-y')}>Empresa Y</Button>
         <Button variant="outline" size="sm" onClick={() => setId('sessao-fantasma')}>Inexistente (erro)</Button>
       </div>
       <div className="rounded-lg border border-border p-4">
@@ -21,7 +21,7 @@ render(
             <div className="space-y-1.5">
               <div className="flex items-center gap-2">
                 <h3 className="text-sm font-semibold">{ws.name}</h3>
-                <Badge context={ws.status === 'active' ? 'success' : 'warning'}>{ws.status}</Badge>
+                <DictionaryValue dict={docWorkspaceStatus} value={ws.status} />
               </div>
               <p className="text-sm text-muted-foreground">
                 Cliente {ws.client} · {ws.agents} agentes vinculados.
@@ -35,6 +35,10 @@ render(
 )
 ```
 
+O handler da view deve devolver um valor. Uma consulta que resolve `undefined` é tratada como erro
+pelo react-query, então `ActionView` apresenta o estado de erro, não um vazio. Represente um recurso
+ausente com o erro `not_found`, cuja frase aparece para a pessoa.
+
 ## useViewAction
 
 `ActionView` é uma composição sobre `useViewAction(action, input)`, que devolve `data`, `error`,
@@ -45,11 +49,11 @@ mais de uma região da tela ou quando o carregamento precisa ser orquestrado por
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `action` | `ViewAction<TInput, TData>` | | A ViewAction do Opus (kind view, 1 recurso). |
+| `action` | `ViewContract<TInput, TData>` | | A ViewAction do Opus (kind view, 1 recurso). |
 | `input` | `TInput` | | Geralmente { id } — mudou, recarrega. |
-| `children` | `(data: TData, refetch) => ReactNode` | | Conteúdo apresentado quando os dados estão disponíveis. `refetch` permite recarregar por código. |
-| `render` | `(data: TData, refetch) => ReactNode` | | Alias de compatibilidade de `children`; `children` tem precedência. |
+| `children` | `(data: TData, refetch) => ReactNode` | | Obrigatório, salvo quando `render` é informado. Conteúdo apresentado quando os dados estão disponíveis. `refetch` permite recarregar por código. |
+| `render` | `(data: TData, refetch) => ReactNode` | | Alias de compatibilidade de `children`; `children` tem precedência. Sem nenhum dos dois, o componente lança erro. |
 | `loading` | `ReactNode \| boolean` | `3 skeletons` | Sobrescreve o carregamento: um nó próprio, `true` para o padrão ou `false` para não renderizar nada enquanto carrega. |
-| `empty` | `ReactNode` | `emptyMessage` ou nada | Sobrescreve o estado vazio (200 sem dado). |
-| `emptyMessage` | `string` | | Atalho do vazio: a frase na mesma superfície de `DataState` (`Empty` com moldura sólida). |
+| `empty` | `ReactNode` | `emptyMessage` ou nada | Estado reservado a `data` indefinido. Como o react-query converte esse resultado em erro, ele não aparece na prática; devolva um valor ou o erro `not_found`. |
+| `emptyMessage` | `string` | | Atalho do vazio, sujeito à mesma limitação de `empty`: a frase na mesma superfície de `DataState` (`Empty` com moldura sólida). |
 | `error` | `(err, retry) => ReactNode` | `"Não foi possível carregar" + Tentar de novo` | Sobrescreve o estado de erro padrão. Sem ele, a frase do servidor só aparece quando é legível pela pessoa (`conflict`, `validation`, `not_found`, `authorization`, `authentication`); código técnico nunca vira título, e o botão de tentar de novo some quando o problema é de permissão ou sessão. |