@softize/opus 12.5.5 → 12.6.1

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

@@ -51,10 +51,10 @@ export function DialogContent({
       <DialogPrimitive.Content
         data-slot="dialog-content"
         className={cn(
-          // Superfície PURA: só a casca (borda/bg/raio/sombra) + coluna flex com teto de
+          // Superfície PURA: só a casca (bg/raio/sombra) + coluna flex com teto de
           // altura. O padding mora nos SLOTS (Header/Body/Footer), não aqui — assim ninguém
           // precisa negar margem pra escapar de um p-6 embutido.
-          "fixed left-[50%] top-[50%] z-50 flex max-h-[85vh] w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] flex-col overflow-hidden rounded-xl border border-border bg-card text-card-foreground shadow-lg duration-200 outline-none data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 sm:max-w-lg",
+          "fixed left-[50%] top-[50%] z-50 flex max-h-[85vh] w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] flex-col overflow-clip rounded-xl bg-card text-card-foreground shadow-lg duration-200 outline-none data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 sm:max-w-lg",
           className,
         )}
         {...props}
@@ -110,7 +110,7 @@ export function DialogFooter({ className, ...props }: React.ComponentProps<'div'
       data-slot="dialog-footer"
       // Faixa destacada (divergência da casa, ao estilo do site do shadcn): borda em cima
       // + fundo muted. Sangra até as bordas sozinha — o content não tem padding, então não
-      // há -mx pra compensar; o overflow-hidden do content arredonda o canto de baixo.
+      // há -mx pra compensar; o recorte do content arredonda o canto de baixo.
       className={cn(
         'flex shrink-0 flex-col-reverse gap-2 border-t bg-muted/30 px-5 py-4 sm:flex-row sm:justify-end',
         className,

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

@@ -7,7 +7,7 @@ function Empty({ className, ...props }: React.ComponentProps<"div">) {
     <div
       data-slot="empty"
       className={cn(
-        "flex min-w-0 flex-1 flex-col items-center justify-center gap-6 rounded-lg border-dashed p-6 text-center text-balance md:p-12",
+        "flex min-w-0 flex-1 flex-col items-center justify-center gap-6 rounded-lg border border-dashed border-border p-6 text-center text-balance md:p-12",
         className
       )}
       {...props}

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

@@ -44,7 +44,7 @@ function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
     <div
       data-slot="field-group"
       className={cn(
-        "group/field-group @container/field-group flex w-full flex-col gap-7 data-[slot=checkbox-group]:gap-3 [&>[data-slot=field-group]]:gap-4",
+        "group/field-group @container/field-group flex w-full flex-col gap-5 data-[slot=checkbox-group]:gap-3 [&>[data-slot=field-group]]:gap-4",
         className
       )}
       {...props}
@@ -53,18 +53,18 @@ function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
 }
 
 const fieldVariants = cva(
-  "group/field flex w-full gap-3 data-[invalid=true]:text-destructive",
+  "group/field flex w-full data-[invalid=true]:text-destructive",
   {
     variants: {
       orientation: {
-        vertical: ["flex-col [&>*]:w-full [&>.sr-only]:w-auto"],
+        vertical: ["flex-col gap-2 [&>*]:w-full [&>.sr-only]:w-auto"],
         horizontal: [
-          "flex-row items-center",
+          "flex-row items-center gap-3",
           "[&>[data-slot=field-label]]:flex-auto",
           "has-[>[data-slot=field-content]]:items-start has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
         ],
         responsive: [
-          "flex-col @md/field-group:flex-row @md/field-group:items-center [&>*]:w-full @md/field-group:[&>*]:w-auto [&>.sr-only]:w-auto",
+          "flex-col gap-2 @md/field-group:flex-row @md/field-group:items-center @md/field-group:gap-3 [&>*]:w-full @md/field-group:[&>*]:w-auto [&>.sr-only]:w-auto",
           "@md/field-group:[&>[data-slot=field-label]]:flex-auto",
           "@md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
         ],

package/src/ui/components/primitives/icon-picker.tsx

@@ -106,6 +106,8 @@ export interface IconPickerProps {
   disabled?: boolean
   className?: string
   id?: string
+  'aria-invalid'?: boolean
+  'aria-describedby'?: string
 }
 
 /**
@@ -122,6 +124,8 @@ export function IconPicker({
   disabled,
   className,
   id,
+  'aria-invalid': ariaInvalid,
+  'aria-describedby': ariaDescribedBy,
 }: IconPickerProps): React.ReactElement {
   const [open, setOpen] = React.useState(false)
   const Current = value !== '' ? icons[value] : undefined
@@ -133,6 +137,8 @@ export function IconPicker({
           type="button"
           id={id}
           disabled={disabled}
+          aria-invalid={ariaInvalid}
+          aria-describedby={ariaDescribedBy}
           data-slot="icon-picker"
           className={cn(
             'flex h-10 w-full items-center gap-2 rounded-md border border-input bg-transparent px-3 text-sm outline-none transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 dark:bg-input/30',

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

@@ -5,14 +5,36 @@ import { Slot } from "radix-ui"
 import { cn } from '../../lib/cn.ts'
 import { Separator } from './separator.tsx'
 
-function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
+const itemGroupVariants = cva("group/item-group @container/item-group flex flex-col", {
+  variants: {
+    variant: {
+      plain: "",
+      framed:
+        "overflow-hidden rounded-xl border border-border bg-card text-card-foreground [&>[data-slot=item]]:rounded-none [&>[data-slot=item-container]>[data-slot=item]]:rounded-none",
+    },
+  },
+  defaultVariants: {
+    variant: "plain",
+  },
+})
+
+const ItemGroupContext = React.createContext(false)
+
+function ItemGroup({
+  className,
+  variant = "plain",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof itemGroupVariants>) {
   return (
-    <div
-      role="list"
-      data-slot="item-group"
-      className={cn("group/item-group flex flex-col", className)}
-      {...props}
-    />
+    <ItemGroupContext.Provider value>
+      <div
+        role="list"
+        data-slot="item-group"
+        data-variant={variant}
+        className={cn(itemGroupVariants({ variant, className }))}
+        {...props}
+      />
+    </ItemGroupContext.Provider>
   )
 }
 
@@ -56,12 +78,16 @@ function Item({
   variant = "default",
   size = "default",
   asChild = false,
+  role,
   ...props
 }: React.ComponentProps<"div"> &
   VariantProps<typeof itemVariants> & { asChild?: boolean }) {
+  const grouped = React.useContext(ItemGroupContext)
   const Comp = asChild ? Slot.Root : "div"
-  return (
+
+  const content = (
     <Comp
+      role={role ?? (!asChild && grouped ? "listitem" : undefined)}
       data-slot="item"
       data-variant={variant}
       data-size={size}
@@ -69,6 +95,18 @@ function Item({
       {...props}
     />
   )
+
+  if (asChild && grouped) {
+    return (
+      <div role="listitem" data-slot="item-container">
+        {content}
+      </div>
+    )
+  }
+
+  return (
+    content
+  )
 }
 
 const itemMediaVariants = cva(

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

@@ -57,6 +57,8 @@ interface SelectBaseProps {
   id?: string
   /** Ícone LEADING dentro do campo — identifica o filtro sem jogar o ícone ao lado. */
   icon?: React.ReactNode
+  'aria-invalid'?: boolean
+  'aria-describedby'?: string
   /** Altura: `default` (h-9, a do Input/Button) ou `sm` (h-8) pra toolbar densa. */
   size?: 'sm' | 'default'
   /** Geometria do controle; `pill` preserva a variante visual escolhida. */
@@ -155,6 +157,8 @@ function NativeSelect({
         disabled={disabled}
         value={value}
         aria-label={rest['aria-label']}
+        aria-invalid={rest['aria-invalid']}
+        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",
@@ -345,6 +349,7 @@ function CustomSelect(props: Exclude<SelectProps, SelectNativeProps>): React.Rea
               data-size={size}
               data-shape={shape}
               data-variant={variant}
+              aria-invalid={props['aria-invalid']}
               onClick={() => {
                 if (disabled !== true) {
                   setOpen(true)
@@ -417,6 +422,8 @@ function CustomSelect(props: Exclude<SelectProps, SelectNativeProps>): React.Rea
                 role="combobox"
                 aria-expanded={open}
                 aria-label={props['aria-label']}
+                aria-invalid={props['aria-invalid']}
+                aria-describedby={props['aria-describedby']}
                 value={props.multiple ? '' : triggerText}
                 onChange={() => {}}
                 onFocus={() => {

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

@@ -9,7 +9,7 @@ faixa de modal). Pra estruturar uma seção da página como painel. O título é
     title="Editar workspace"
     action={docWorkspaceCreate}
     defaultValues={{ name: 'Empresa X', status: 'active' }}
-    submitLabel="Salvar"
+    submitLabel="Salvar alterações"
   />
 </DocBrowserActionProvider>
 ```

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

@@ -16,6 +16,7 @@ render(
       title="Novo workspace"
       description="O workspace agrupa os repositórios e agentes do cliente."
       action={docWorkspaceCreate}
+      submitLabel="Criar workspace"
     />
   </DocBrowserActionProvider>,
 )
@@ -27,4 +28,5 @@ render(
 |---|---|---|---|
 | `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. |
+| `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. |

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

@@ -12,6 +12,25 @@ render(
 )
 ```
 
+## Barra de filtros compartilhada
+
+`ActionFilterBar` expõe a mesma linguagem declarativa de busca, filtros e período para
+superfícies que não são listagens, como relatórios. O estado é controlado pelo consumidor;
+`onRefresh` refaz sua consulta sem alterar o recorte vigente.
+
+```tsx
+<ActionFilterBar
+  action={{ text, filters, periods }}
+  state={filterState}
+  onStateChange={setFilterState}
+  onRefresh={refetch}
+  refreshing={isLoading}
+/>
+```
+
+Busca e filtros são renderizados somente quando declarados. Períodos incluem os presets do
+contrato e o intervalo personalizado no mesmo calendário usado pela `ActionList`.
+
 ## Células custom (cells)
 
 As colunas do contrato descrevem DADOS; apresentação especial entra por cima com `cells` (chave = key da coluna). É onde vivem chips coloridos por dict, links e a coluna de ações.
@@ -49,7 +68,7 @@ periods: [
 
 ## Paginação e loading
 
-O pattern manda `limit` (= `pageSize`, default 50) e `page` no input; o handler implementa o OFFSET e devolve `total` no Paginated. O rodapé (Página X de Y · páginas numeradas com reticências · "N itens no total") aparece sempre que há total; mudar filtro/busca/sort/período volta pra página 1 (a página vive na URL: `?page=2`). No refetch com a lista já na tela, o corpo esmaece (`aria-busy`) até os dados chegarem — o skeleton é só do primeiro load.
+O pattern manda `limit` (= `pageSize`, default 50) e `page` no input; o handler implementa o OFFSET e devolve `total` no Paginated. O rodapé (Página X de Y · páginas numeradas com reticências · "N itens no total") aparece sempre que há total; mudar filtro/busca/sort/período volta pra página 1 (a página vive na URL: `?page=2`). No primeiro carregamento, `DataState` centraliza o spinner; no refetch com a lista já na tela, o corpo esmaece (`aria-busy`) até os dados chegarem.
 
 ## Multi-seleção com can (batch)
 

package/src/ui/docs/content/alert-dialog.md

@@ -70,4 +70,4 @@ composição e onde o `variant` entra:
 | `open` (AlertDialog) | `boolean` | | Estado de aberto no modo controlado — pareie com onOpenChange. No padrão, o Trigger cuida disso. |
 | `onOpenChange` (AlertDialog) | `(open: boolean) => void` | | Chamado quando o diálogo abre ou fecha (Trigger, Cancel, Action ou Esc). |
 | `variant` (AlertDialogAction) | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'default'` | Intenção do botão de confirmar (herdada do Button) — destructive pra ação perigosa. |
-| `variant` (AlertDialogCancel) | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'outline'` | Intenção do botão de cancelar (herdada do Button). |
+| `variant` (AlertDialogCancel) | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'ghost'` | Intenção do botão de cancelar (herdada do Button). |

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

@@ -4,10 +4,10 @@ variant é intenção, não decoração: default pra ação principal (uma por t
 quando destrói de verdade.
 
 ```tsx preview
-<Button>Salvar</Button>
+<Button>Criar workspace</Button>
 <Button variant="secondary">Duplicar</Button>
-<Button variant="outline">Cancelar</Button>
-<Button variant="ghost">Detalhes</Button>
+<Button variant="outline">Ver prévia</Button>
+<Button variant="ghost">Cancelar</Button>
 <Button variant="destructive">Excluir</Button>
 <Button variant="link">Ver documentação</Button>
 ```
@@ -33,7 +33,7 @@ centralizado/Skeleton num nível de página.
 
 ```tsx preview
 <Button disabled>Desabilitado</Button>
-<Button busy>Salvar</Button>
+<Button busy>Salvando…</Button>
 <Button icon={Plus}>Novo</Button>
 <Button icon={Plus} busy>Novo</Button>
 ```

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

@@ -39,7 +39,7 @@ de 16, sem transformar esse valor em uma regra da biblioteca.
 > vence o conflito. Pra layout local (largura, margem, grid) — não pra repintar o visual da casa.
 
 ```tsx
-<Button className="w-full">Salvar</Button>
+<Button className="w-full">Continuar</Button>
 <Card className="max-w-sm" />
 <DialogContent className="sm:max-w-2xl" />
 ```

package/src/ui/docs/content/data-state.md

@@ -1,7 +1,8 @@
 ## Estados
 
 Um lugar só pro erro/carregando/vazio/conteúdo de uma carga. Carregando = Spinner centralizado;
-vazio = texto; erro = aviso calmo (a mensagem técnica não vai pra tela). É o "antes" do conteúdo —
+vazio = texto em uma moldura sólida no modo bloco; erro = aviso calmo (a mensagem técnica não vai
+pra tela). É o "antes" do conteúdo —
 pro "depois" (ação em andamento), use o busy do Button.
 
 ```tsx preview col
@@ -20,8 +21,10 @@ pro "depois" (ação em andamento), use o busy do Button.
 
 ## Em tabela (colSpan)
 
-Em lista de tabela, passe colSpan: o estado vira UMA linha de largura cheia (`<tr><td colSpan>`)
-que cabe direto no `<tbody>`; o conteúdo são as `<tr>` dos itens.
+Em lista ou tabela já emoldurada, passe colSpan: o estado vira UMA linha de largura cheia
+(`<tr><td colSpan>`) que cabe direto no `<tbody>`; o conteúdo são as `<tr>` dos itens. A tabela
+continua dona da borda, sem uma segunda moldura no vazio. Para uma região disponível para criação
+ou vínculo, com título, descrição ou ação, use `Empty`, cuja moldura é tracejada.
 
 ```tsx preview col
 <table className="w-full overflow-hidden rounded-lg border border-border text-sm">

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

@@ -18,7 +18,7 @@ Content é superfície pura; o espaço mora nos slots (body p-5; header/footer p
     </DialogBody>
     <DialogFooter>
       <DialogClose asChild>
-        <Button variant="outline" size="sm">Cancelar</Button>
+        <Button variant="ghost" size="sm">Cancelar</Button>
       </DialogClose>
       <Button size="sm">Criar</Button>
     </DialogFooter>
@@ -42,7 +42,7 @@ showCloseButton={false} esconde o X: o usuário decide pelos botões — pra con
     </DialogHeader>
     <DialogFooter>
       <DialogClose asChild>
-        <Button variant="outline" size="sm">Cancelar</Button>
+        <Button variant="ghost" size="sm">Cancelar</Button>
       </DialogClose>
       <DialogClose asChild>
         <Button variant="destructive" size="sm">Excluir</Button>

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

@@ -38,9 +38,9 @@ side aceita top|right|bottom|left. DrawerFooter ancora as ações no rodapé; Dr
     </div>
     <DrawerFooter>
       <DrawerClose asChild>
-        <Button variant="outline" size="sm">Cancelar</Button>
+        <Button variant="ghost" size="sm">Cancelar</Button>
       </DrawerClose>
-      <Button size="sm">Salvar</Button>
+      <Button size="sm">Salvar alterações</Button>
     </DrawerFooter>
   </DrawerContent>
 </Drawer>

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

@@ -1,3 +1,13 @@
+## Quando usar
+
+Use `Empty` quando a própria região está disponível para receber ou criar conteúdo. A moldura
+tracejada diferencia esse espaço de uma estrutura de dados já estabelecida e pode combinar título,
+descrição, mídia e ação.
+
+Para uma lista ou tabela carregada, mas sem registros, use `DataState` ou `ActionList`: a moldura
+sólida preserva a estrutura. Se a região já estiver emoldurada pelo pai, mantenha a borda somente
+no pai para evitar uma moldura dupla.
+
 ## Com ícone
 
 EmptyMedia variant=icon desenha o quadrado de fundo muted atrás do ícone; o EmptyHeader agrupa mídia, título e descrição no centro.

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

@@ -17,12 +17,12 @@ A composição completa: ItemMedia à esquerda, ItemContent (ItemTitle + ItemDes
 </Item>
 ```
 
-## Lista
+## Lista emoldurada
 
-Empilhe vários Item num ItemGroup e separe com ItemSeparator — o padrão pra listas de repositórios, agentes ou sessões.
+`ItemGroup variant="framed"` aplica a superfície canônica. Os divisores continuam explícitos com `ItemSeparator`, tanto no modo `framed` quanto no `plain` — o padrão pra listas de repositórios, agentes ou sessões.
 
 ```tsx preview col
-<ItemGroup>
+<ItemGroup variant="framed">
   <Item>
     <ItemMedia variant="icon">
       <GitBranch />
@@ -78,6 +78,7 @@ asChild funde o Item num <a> — a linha inteira vira alvo (hover no fundo). siz
 
 | Prop | Tipo | Default | Descrição |
 |---|---|---|---|
+| `variant` (ItemGroup) | `'plain' \| 'framed'` | `'plain'` | `framed` aplica moldura e superfície; `plain` mantém a composição livre. Os divisores são explícitos nos dois modos. |
 | `variant` (Item) | `'default' \| 'outline' \| 'muted'` | `'default'` | O fundo da linha — default transparente, outline com borda, muted levemente tingido. |
 | `size` (Item) | `'default' \| 'sm'` | `'default'` | O respiro interno — sm aperta o padding pra listas densas. |
 | `asChild` (Item) | `boolean` | `false` | Funde o Item no filho (ex.: <a> ou <button>) — a linha inteira vira o alvo. |

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

@@ -2,9 +2,9 @@
 
 Use `Page` para manter título, contexto, ações e conteúdo no mesmo ritmo visual nas telas do
 back-office. As ações ficam à direita e acompanham a base do conjunto formado pelo título e pela
-descrição. O componente ocupa a largura disponível; passe `className="max-w-5xl"` quando a tela
-pedir conteúdo mais estreito e centralizado. A área abaixo do cabeçalho permanece livre para
-tabelas, cards ou outras composições.
+descrição. O container é centralizado e ocupa a largura disponível até `72rem` (`max-w-6xl`). Use
+`className` somente quando a composição pedir explicitamente outro teto ou largura total. A área
+abaixo do cabeçalho permanece livre para tabelas, cards ou outras composições.
 
 ```tsx preview col
 render(
@@ -35,5 +35,5 @@ render(
 | `count` | `number` | | Total de itens ao lado do título (mono, esmaecido). |
 | `description` | `ReactNode` | | Linha de contexto sob o título (ex.: "N no total · X ativos"). |
 | `actions` | `ReactNode` | | Ações à direita do cabeçalho, alinhadas à base do título e da descrição. |
-| `className` | `string` | largura cheia | Classes do container (`max-w-5xl` estreita e centra). |
+| `className` | `string` | `max-w-6xl` | Classes do container para substituir o teto padrão de `72rem`. |
 | `children` | `ReactNode` | | O conteúdo — espaçamento e diagramação são seus. |

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

@@ -15,7 +15,7 @@ PopoverHeader agrupa título e descrição; o corpo é livre (form curto, detalh
     <div className="mt-3 space-y-2">
       <Label htmlFor="pop-titulo">Título</Label>
       <Input id="pop-titulo" defaultValue="Onboarding do faturamento" />
-      <Button size="sm" className="w-full">Salvar</Button>
+      <Button size="sm" className="w-full">Renomear</Button>
     </div>
   </PopoverContent>
 </Popover>

package/src/ui/meta.ts

@@ -83,6 +83,12 @@ export const componentMeta = {
     whenToUse:
       'A caixa de escrever da casa (o composer do Chat, extraído): textarea numa pílula elevada, Enter envia / Shift+Enter quebra linha, enviar dentro. Use SOZINHO quando há entrada de texto mas não um chat — ex.: o composer de criação de sessão do Maestro (sem histórico). Com `actions`, ganha uma barra embaixo pra seletores discretos à esquerda (app, agente, contexto…) — o mesmo lugar onde o Maestro põe app/task e a GB poria o agente. Sem `actions`, é a linha única de sempre. Controlado (`value`/`onChange`/`onSubmit`); `submitDisabled` gateia além de vazio/busy. Pra um chat completo (mensagens + este composer), use Chat.',
   },
+  'content-header': {
+    name: 'content-header',
+    ancestry: 'opus',
+    whenToUse:
+      'Cabeçalho semântico de uma seção de conteúdo: título, descrição, meta e ações na mesma composição. Use `variant="section"` dentro de páginas e painéis; `Page` já fornece o cabeçalho principal e não deve receber outro ContentHeader equivalente. O `level` controla a hierarquia do heading sem alterar a hierarquia visual.',
+  },
   'copyable': {
     name: 'copyable',
     ancestry: 'opus',
@@ -245,7 +251,7 @@ export const componentMeta = {
     name: 'empty',
     ancestry: 'shadcn',
     whenToUse:
-      'Estado vazio dentro de uma região: moldura tracejada centrada com `EmptyHeader` (mídia + `EmptyTitle` + `EmptyDescription`) e `EmptyContent` pras ações. `EmptyMedia variant` icon (quadrado muted) ou default (sem fundo). Pra erro inline use Alert; pra carregamento, Skeleton.',
+      'Região disponível para receber ou criar conteúdo: moldura tracejada centrada com `EmptyHeader` (mídia + `EmptyTitle` + `EmptyDescription`) e `EmptyContent` pras ações. Para lista ou tabela carregada sem registros, use DataState ou ActionList, que preservam a moldura sólida da estrutura. `EmptyMedia variant` icon (quadrado muted) ou default (sem fundo). Pra erro inline use Alert; pra carregamento, Skeleton.',
   },
   'field': {
     name: 'field',
@@ -269,7 +275,7 @@ export const componentMeta = {
     name: 'item',
     ancestry: 'shadcn',
     whenToUse:
-      'Linha de conteúdo composta — mídia + título/descrição + ações numa linha clicável ou estática. Item é o container (`variant` default/outline/muted, `size` default/sm, `asChild` pra virar link/botão); componha ItemMedia (`variant` icon/image), ItemContent (ItemTitle + ItemDescription), ItemActions e, na borda, ItemHeader/ItemFooter. Empilhe vários num ItemGroup separados por ItemSeparator — o padrão pra listas de workspaces, agentes, repositórios e sessões.',
+      'Linha de conteúdo composta — mídia + título/descrição + ações numa linha clicável ou estática. Item é o container (`variant` default/outline/muted, `size` default/sm, `asChild` pra virar link/botão); componha ItemMedia (`variant` icon/image), ItemContent (ItemTitle + ItemDescription), ItemActions e, na borda, ItemHeader/ItemFooter. Empilhe vários num ItemGroup: `variant="framed"` aplica a moldura e a superfície; ItemSeparator declara os divisores internos tanto no modo framed quanto no plain. É o padrão pra listas de workspaces, agentes, repositórios e sessões.',
   },
   'kbd': {
     name: 'kbd',
@@ -384,7 +390,7 @@ export const componentMeta = {
     name: 'page',
     ancestry: 'opus',
     whenToUse:
-      'O esqueleto de página do back-office: <main> + container de largura cheia (className="max-w-5xl" estreita e centra) + header com título, descrição e ação à direita (em geral o criar). Presentacional (a página agrega N fontes); o action-driven mora dentro. Pra listagem em modal, ActionListDialog.',
+      'O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 72rem (`max-w-6xl`) + header com título, descrição e ação à direita (em geral o criar). `className` substitui o teto quando a composição pede outra largura. Presentacional (a página agrega N fontes); o action-driven mora dentro. Pra listagem em modal, ActionListDialog.',
   },
   'router': {
     name: 'router',
@@ -396,7 +402,7 @@ export const componentMeta = {
     name: 'data-state',
     ancestry: 'opus',
     whenToUse:
-      'O estado "carregando" (ANTES do conteúdo): orquestra erro/carregando/vazio/conteúdo de uma carga assíncrona num só lugar — Spinner centralizado no loading, texto no vazio, aviso calmo no erro. Pra "processando" (ação em andamento DEPOIS do clique), use o `busy` do Button. Pra placeholder com forma, Skeleton.',
+      'O estado "carregando" (ANTES do conteúdo): orquestra erro/carregando/vazio/conteúdo de uma carga assíncrona num só lugar — Spinner centralizado no loading, texto em moldura sólida no vazio em bloco e aviso calmo no erro. Em tabela emoldurada, `colSpan` mantém a borda somente no pai. Pra uma região disponível para criação ou vínculo, use Empty, cuja moldura é tracejada. Pra "processando" (ação em andamento DEPOIS do clique), use o `busy` do Button. Pra placeholder com forma, Skeleton.',
   },
   'action-list-dialog': {
     name: 'action-list-dialog',

package/src/ui/react.tsx

@@ -187,8 +187,8 @@ export type { ActionFormDialogProps } from './components/patterns/form-dialog.ts
 export { ActionFormCard } from './components/patterns/action-form-card.tsx'
 export type { ActionFormCardProps } from './components/patterns/action-form-card.tsx'
 
-export { ActionList, emptyListState, presetRange, listParamsToState, listStateToParams } from './components/patterns/list.tsx'
-export type { ActionListProps, ActionListColumn, ActionListState, ActionListView, ActionListBatchAction, ListActionLike } from './components/patterns/list.tsx'
+export { ActionFilterBar, ActionList, emptyListState, presetRange, listParamsToState, listStateToParams } from './components/patterns/list.tsx'
+export type { ActionFilterBarProps, ActionFilterState, ActionListProps, ActionListColumn, ActionListState, ActionListView, ActionListBatchAction, ListActionLike } from './components/patterns/list.tsx'
 
 export { ActionView } from './components/patterns/view.tsx'
 export type { ActionViewProps } from './components/patterns/view.tsx'
@@ -210,6 +210,14 @@ export type { DataStateProps } from './components/patterns/data-state.tsx'
 export { Page } from './components/patterns/page.tsx'
 export type { PageProps } from './components/patterns/page.tsx'
 
+// Cabeçalho de conteúdo em duas hierarquias visuais, sem impor espaçamento externo.
+export { ContentHeader } from './components/patterns/content-header.tsx'
+export type {
+  ContentHeaderProps,
+  ContentHeaderLevel,
+  ContentHeaderVariant,
+} from './components/patterns/content-header.tsx'
+
 // Layout composicional: Split decide a relação espacial; Pane carrega conteúdo com inset.
 export { Split, Pane } from './components/patterns/split.tsx'
 export type { SplitProps, PaneProps, PaneSize, SplitLayout, SplitLayoutChange } from './components/patterns/split.tsx'