@softize/opus 12.5.5 → 12.6.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 12.6.0 — 2026-08-25
+
+`ContentHeader` oferece a composição compartilhada de título, descrição, metadados e ações para
+páginas e seções. `Page` usa a mesma estrutura, enquanto `level` mantém a hierarquia semântica
+independente do destaque visual.
+
+`ActionFilterBar` expõe os filtros declarativos de uma list action para telas que precisam da
+toolbar sem delegar a renderização dos resultados ao `ActionList`. `ItemGroup` também passa a
+oferecer moldura explícita, e seus itens carregam semântica de lista por padrão.
+
+Os patterns existentes passam a reutilizar os primitives canônicos: `ActionForm` usa `Field`,
+`FieldGroup`, descrições e erros associados ao controle; `ActionList` usa a moldura de `Table` e
+os estados seguros de `DataState`, preservando a tentativa de recuperação; e a confirmação de uma
+`ActionTrigger` destrutiva mantém o tratamento destrutivo mesmo quando o gatilho visual é discreto.
+
 ## 12.5.5 — 2026-08-25
 
 Só documentação: leva ao pacote a correção de nota que a 12.5.4 recebeu no repositório depois de

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.5.5",
+  "version": "12.6.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/ui/components/patterns/content-header.tsx

@@ -0,0 +1,88 @@
+import type { ReactNode } from 'react'
+import { cn } from '../../lib/cn.ts'
+
+export type ContentHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6
+export type ContentHeaderVariant = 'page' | 'section'
+
+export interface ContentHeaderProps {
+  title: ReactNode
+  /** Conteúdo complementar exibido ao lado do título, como uma contagem. */
+  meta?: ReactNode
+  description?: ReactNode
+  actions?: ReactNode
+  /** Nível semântico do heading, independente de seu destaque visual. */
+  level?: ContentHeaderLevel
+  /** Hierarquia visual: destaque principal ou cabeçalho interno de seção. */
+  variant?: ContentHeaderVariant
+  className?: string
+}
+
+interface ContentHeaderSlots {
+  root?: string
+  heading: string
+  actions: string
+}
+
+interface ContentHeaderFrameProps extends ContentHeaderProps {
+  slots: ContentHeaderSlots
+}
+
+const headingTags = {
+  1: 'h1',
+  2: 'h2',
+  3: 'h3',
+  4: 'h4',
+  5: 'h5',
+  6: 'h6',
+} as const
+
+/** Layout compartilhado com Page; mantém os slots históricos sem expô-los na API pública. */
+export function ContentHeaderFrame({
+  title,
+  meta,
+  description,
+  actions,
+  level = 2,
+  variant = 'section',
+  className,
+  slots,
+}: ContentHeaderFrameProps): React.ReactElement {
+  const Heading = headingTags[level]
+  const page = variant === 'page'
+
+  return (
+    <div
+      {...(slots.root === undefined ? {} : { 'data-slot': slots.root })}
+      className={cn(actions !== undefined && 'flex items-end justify-between gap-4', className)}
+    >
+      <div data-slot={slots.heading} className="min-w-0">
+        <Heading
+          className={cn(
+            'flex items-baseline gap-2 font-semibold',
+            page ? 'text-2xl tracking-tight' : 'text-sm',
+          )}
+        >
+          {title}
+          {meta}
+        </Heading>
+        {description !== undefined && (
+          <p className={cn('truncate text-muted-foreground', page ? 'mt-1 text-sm' : 'mt-0.5 text-xs')}>{description}</p>
+        )}
+      </div>
+      {actions !== undefined && (
+        <div data-slot={slots.actions} className={cn('flex shrink-0 items-center', page ? 'gap-4' : 'gap-2')}>
+          {actions}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export function ContentHeader(props: ContentHeaderProps): React.ReactElement {
+  return (
+    <ContentHeaderFrame
+      {...props}
+      slots={{ root: 'content-header', heading: 'content-header-heading', actions: 'content-header-actions' }}
+    />
+  )
+}

package/src/ui/components/patterns/data-state.tsx

@@ -9,6 +9,7 @@
  */
 import * as React from 'react'
 import { cn } from '../../lib/cn.ts'
+import { Button } from '../primitives/button.tsx'
 import { Spinner } from '../primitives/spinner.tsx'
 
 export interface DataStateProps {
@@ -22,6 +23,9 @@ export interface DataStateProps {
   emptyText?: string
   /** Aviso de erro (calmo, orientado ao usuário). Default: "Não foi possível carregar.". */
   errorText?: string
+  /** Recuperação opcional exibida somente no estado de erro. */
+  onRetry?: () => Promise<void> | void
+  retryText?: string
   /** Em TABELA: renderiza o estado como UMA linha (<tr><td colSpan>), não um bloco — pra
    *  caber direto no <tbody>. Passe o nº de colunas da tabela. */
   colSpan?: number
@@ -36,6 +40,8 @@ export function DataState({
   empty = false,
   emptyText = 'Nada por aqui.',
   errorText,
+  onRetry,
+  retryText = 'Tentar de novo',
   colSpan,
   children,
 }: DataStateProps): React.ReactElement {
@@ -50,7 +56,20 @@ export function DataState({
           colSpan={colSpan}
           className={cn('px-4 py-10 text-center text-sm', error ? 'text-destructive' : 'text-muted-foreground/60')}
         >
-          {error ? (errorText ?? 'Não foi possível carregar.') : loading ? <Spinner className="mx-auto" /> : emptyText}
+          {error ? (
+            <div className="flex flex-col items-center gap-3">
+              <span>{errorText ?? 'Não foi possível carregar.'}</span>
+              {onRetry !== undefined && (
+                <Button variant="outline" size="sm" onClick={() => void onRetry()}>
+                  {retryText}
+                </Button>
+              )}
+            </div>
+          ) : loading ? (
+            <Spinner className="mx-auto" />
+          ) : (
+            emptyText
+          )}
         </td>
       </tr>
     )
@@ -59,8 +78,13 @@ export function DataState({
   // Modo BLOCO (default).
   if (error) {
     return (
-      <div className="rounded-lg border border-destructive/30 bg-destructive/5 px-4 py-3 text-center text-sm text-destructive">
-        {errorText ?? 'Não foi possível carregar.'}
+      <div className="flex flex-col items-center gap-3 rounded-lg border border-destructive/30 bg-destructive/5 px-4 py-3 text-center text-sm text-destructive">
+        <span>{errorText ?? 'Não foi possível carregar.'}</span>
+        {onRetry !== undefined && (
+          <Button variant="outline" size="sm" onClick={() => void onRetry()}>
+            {retryText}
+          </Button>
+        )}
       </div>
     )
   }

package/src/ui/components/patterns/form.tsx

@@ -2,12 +2,11 @@
  * <ActionForm action /> — renderiza um FormAction do Opus em UI do Opus.
  *
  * Dois modos, um motor:
- * - AUTO (sem children): monta TODOS os campos na ordem do contrato — zero JSX de campo;
- *   o espaçamento entre campos (space-y-6) é deste modo, que é quem diagrama.
+ * - AUTO (sem children): monta TODOS os campos na ordem do contrato — zero JSX de campo.
  * - COMPOSIÇÃO (com children): você diagrama; <ActionFormField name /> coloca cada campo
  *   (label/hint/widget/erro/asterisco derivados do contrato) onde quiser. Condicional é
  *   JSX ({cond && <ActionFormField/>}); opções de runtime entram por prop no campo. O
- *   espaçamento é 100% seu — nenhuma margem imposta (o campo não sabe onde será colocado).
+ *   FieldGroup canônico permanece nos dois modos; grids e seções entram como filhos explícitos.
  *
  * Auto-detect do Zod (nos dois modos):
  * - z.enum(...) → <Select> com opções inferidas
@@ -28,12 +27,12 @@ import { toast } from '../primitives/sonner.tsx'
 import { Button } from '../primitives/button.tsx'
 import { Input } from '../primitives/input.tsx'
 import { Textarea } from '../primitives/textarea.tsx'
-import { Label } from '../primitives/label.tsx'
 import { Checkbox } from '../primitives/checkbox.tsx'
 import { IconPicker } from '../primitives/icon-picker.tsx'
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../primitives/tooltip.tsx'
 import { Info } from 'lucide-react'
 import { Select, type SelectOption } from '../primitives/select.tsx'
+import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from '../primitives/field.tsx'
 
 // =============================================================================
 // Inferência de tipo de field a partir do Zod schema
@@ -265,12 +264,6 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
   // Assina TODOS os valores: alimenta o showWhen e os widgets controlados.
   const formValues = form.watch()
 
-  // Clique na label foca o controle — todo controle da casa honra o id (o Select
-  // reaplica o dele, que o cmdk sobrescreve).
-  const focusControl = (): void => {
-    document.getElementById(name)?.focus()
-  }
-
   const spec: FieldSpec = fields[name] ?? {}
   const fieldSchema = shape[name]
   if (fieldSchema === undefined) return null
@@ -290,6 +283,9 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
             : inferred
   const fieldError = form.formState.errors[name]
   const errorMessage = typeof fieldError?.message === 'string' ? fieldError.message : undefined
+  const descriptionId = spec.hint !== undefined ? `${name}-description` : undefined
+  const errorId = errorMessage !== undefined ? `${name}-error` : undefined
+  const describedBy = [descriptionId, errorId].filter(Boolean).join(' ') || undefined
   // Precedência das opções: prop do campo > fieldOptions do form > spec.options
   // (dictionary via provider, static direto) > meta do t.dict no schema
   // (zero-config) > chaves cruas do z.enum.
@@ -314,34 +310,46 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
   // Checkbox tem layout próprio (controle + label na mesma linha).
   if (fieldKind.kind === 'checkbox') {
     return (
-      <div className={cn('space-y-2', className)}>
-        <label className="flex items-center gap-2">
+      <Field
+        className={className}
+        data-invalid={errorMessage !== undefined}
+        aria-invalid={errorMessage !== undefined}
+        aria-describedby={describedBy}
+      >
+        <FieldLabel htmlFor={name} className="items-center">
           <Checkbox
             id={name}
             checked={(formValues[name] as boolean | undefined) ?? false}
             onCheckedChange={(v) => setValue(v === true)}
+            aria-invalid={errorMessage !== undefined}
+            aria-describedby={describedBy}
           />
-          <span className="text-sm font-medium">
+          <span>
             {spec.label ?? name}
             <RequiredMark required={fieldKind.required} />
           </span>
           <LabelHelp help={spec.help} />
-        </label>
-        {spec.hint !== undefined && <p className="text-xs text-muted-foreground">{spec.hint}</p>}
-        {errorMessage !== undefined && <p className="text-xs text-destructive">{errorMessage}</p>}
-      </div>
+        </FieldLabel>
+        {spec.hint !== undefined && <FieldDescription id={descriptionId}>{spec.hint}</FieldDescription>}
+        {errorMessage !== undefined && <FieldError id={errorId}>{errorMessage}</FieldError>}
+      </Field>
     )
   }
 
   return (
-    <div className={cn('space-y-2', className)}>
-      <Label htmlFor={name} onClick={focusControl} className="flex items-center gap-1.5">
+    <Field
+      className={className}
+      data-invalid={errorMessage !== undefined}
+      aria-invalid={errorMessage !== undefined}
+      aria-describedby={describedBy}
+    >
+      <FieldLabel htmlFor={name} className="items-center gap-1.5">
         <span>
           {spec.label ?? name}
           <RequiredMark required={fieldKind.required} />
         </span>
         <LabelHelp help={spec.help} />
-      </Label>
+      </FieldLabel>
 
       {effectiveKind.kind === 'multiselect' ? (
         <Select
@@ -353,6 +361,8 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           options={options}
           placeholder={spec.placeholder ?? 'Selecione…'}
           className="w-full"
+          aria-invalid={errorMessage !== undefined}
+          aria-describedby={describedBy}
         />
       ) : effectiveKind.kind === 'select' ? (
         // w-full: campo de FORM alinha com os inputs (todos cheios) — coluna uniforme.
@@ -369,6 +379,8 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           searchable={options.length > 6}
           placeholder={spec.placeholder ?? 'Selecione…'}
           className="w-full"
+          aria-invalid={errorMessage !== undefined}
+          aria-describedby={describedBy}
         />
       ) : effectiveKind.kind === 'lines' ? (
         // Lista de strings num textarea: um item por linha. split/join round-trip
@@ -380,6 +392,8 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           className="max-h-80"
           value={((formValues[name] as string[] | undefined) ?? []).join('\n')}
           onChange={(e) => setValue(e.target.value.split('\n'))}
+          aria-invalid={errorMessage !== undefined}
+          aria-describedby={describedBy}
         />
       ) : effectiveKind.kind === 'refItems' ? (
         // Lista composta {ref, text}: cada linha = select de referência (opções de
@@ -392,16 +406,22 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
               {items.map((item, i) => (
                 <div key={i} className="flex items-start gap-2">
                   <Select
+                    id={i === 0 ? name : `${name}-${i}-ref`}
                     value={item.ref}
                     onChange={(v) => setItems(items.map((it, j) => (j === i ? { ...it, ref: v } : it)))}
                     options={options}
                     placeholder="Papel…"
                     className="w-44 shrink-0"
+                    aria-invalid={errorMessage !== undefined}
+                    aria-describedby={describedBy}
                   />
                   <Input
+                    id={`${name}-${i}-text`}
                     value={item.text}
                     placeholder={spec.placeholder ?? 'O quê (com critério)…'}
                     onChange={(e) => setItems(items.map((it, j) => (j === i ? { ...it, text: e.target.value } : it)))}
+                    aria-invalid={errorMessage !== undefined}
+                    aria-describedby={describedBy}
                   />
                   <Button
                     type="button"
@@ -419,7 +439,10 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
                 type="button"
                 variant="outline"
                 size="sm"
+                id={items.length === 0 ? name : undefined}
                 onClick={() => setItems([...items, { ref: '', text: '' }])}
+                aria-invalid={items.length === 0 && errorMessage !== undefined ? true : undefined}
+                aria-describedby={items.length === 0 ? describedBy : undefined}
               >
                 Adicionar item
               </Button>
@@ -433,6 +456,8 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           value={(formValues[name] as string | undefined) ?? ''}
           onChange={(v) => setValue(v)}
           placeholder={spec.placeholder ?? 'Selecione um ícone…'}
+          aria-invalid={errorMessage !== undefined}
+          aria-describedby={describedBy}
         />
       ) : effectiveKind.kind === 'textarea' ? (
         // max-h: o Textarea v4 auto-cresce (field-sizing-content) — capa e scrolla
@@ -442,23 +467,27 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           placeholder={spec.placeholder ?? ''}
           rows={5}
           className={spec.widget === 'code' ? 'max-h-80 font-mono text-xs' : 'max-h-80'}
+          aria-invalid={errorMessage !== undefined}
+          aria-describedby={describedBy}
           {...form.register(name)}
         />
       ) : (
         <Input
           id={name}
           placeholder={spec.placeholder ?? ''}
+          aria-invalid={errorMessage !== undefined}
+          aria-describedby={describedBy}
           {...form.register(name)}
         />
       )}
 
       {spec.hint !== undefined && (
-        <p className="text-xs text-muted-foreground">{spec.hint}</p>
+        <FieldDescription id={descriptionId}>{spec.hint}</FieldDescription>
       )}
       {errorMessage !== undefined && (
-        <p className="text-xs text-destructive">{errorMessage}</p>
+        <FieldError id={errorId}>{errorMessage}</FieldError>
       )}
-    </div>
+    </Field>
   )
 }
 
@@ -527,15 +556,12 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
       <div className="mt-6 flex shrink-0 justify-end gap-2">{actions}</div>
     ))
 
-  // Banner de erro do servidor (chrome do próprio form, nos dois modos). No AUTO o
-  // space-y-6 do wrapper espaça; na COMPOSIÇÃO ele carrega a própria separação (mt-6).
+  // Banner de erro do servidor (chrome do próprio form, nos dois modos). O FieldGroup
+  // mantém o mesmo ritmo entre campos, blocos compostos e este estado.
   const errorBanner =
     error !== undefined && !isSuccess ? (
       <div
-        className={cn(
-          'rounded-md border border-destructive/50 bg-destructive/10 p-3 text-sm text-destructive',
-          children !== undefined && 'mt-6',
-        )}
+        className="rounded-md border border-destructive/50 bg-destructive/10 p-3 text-sm text-destructive"
       >
         <strong>{error.code}</strong>: {error.message}
       </div>
@@ -552,22 +578,12 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
     >
       <form onSubmit={submit} className={cn('flex flex-col', className)} data-action={action.name}>
         {wrapBody(
-          children !== undefined ? (
-            // COMPOSIÇÃO: nenhum espaçamento imposto — o componente não sabe onde será
-            // colocado; a diagramação (grid/gap/space-y) é 100% de quem compõe.
-            <>
-              {children}
-              {errorBanner}
-            </>
-          ) : (
-            // AUTO: aqui o ActionForm É o pai que diagrama — o space-y-6 é dele.
-            <div className="space-y-6">
-              {Object.keys(fields).map((name) => (
-                <ActionFormField key={name} name={name} />
-              ))}
-              {errorBanner}
-            </div>
-          ),
+          <FieldGroup>
+            {children !== undefined
+              ? children
+              : Object.keys(fields).map((name) => <ActionFormField key={name} name={name} />)}
+            {errorBanner}
+          </FieldGroup>,
         )}
 
         {wrapFooter(