@softize/opus 12.7.1 → 12.8.0

package/src/core/dictionary.ts

@@ -0,0 +1,152 @@
+/**
+ * Apresentação de dicionários — o vocabulário fechado e a tabela de decisão (ADR 0003).
+ *
+ * Mora no CORE porque é isomórfico: o driver de schema valida o que `t.dict` declara, o
+ * manifest projeta a metadata e a UI aplica os defaults lendo a meta que viaja no contrato.
+ * Nada aqui depende de React; `DictionaryValue` (ui/react) é só a materialização visual.
+ */
+
+import { getLogicalType } from './logical-type.ts'
+import type { LogicalTypeMeta } from './types.ts'
+
+/** Papel de apresentação declarado no nível do dicionário. */
+export const DICT_PRESENTATIONS = ['classification', 'status', 'stage', 'plain'] as const
+export type DictPresentation = (typeof DICT_PRESENTATIONS)[number]
+
+/** Tom explícito de uma entrada — honrado apenas por status e estágios. */
+export const DICT_TONES = ['neutral', 'info', 'success', 'warning', 'danger'] as const
+export type DictTone = (typeof DICT_TONES)[number]
+
+/**
+ * Meta de cada chave de um dict. `label` obrigatório; resto livre.
+ *
+ * - `doc` é o entendimento de negócio da chave (o que aquele estado significa, quando se
+ *   entra/sai) — a fonte rica de consulta rápida; flui pro manifest/Lens e NÃO vira tooltip.
+ * - `description` é o texto curto voltado à pessoa: aparece no tooltip do `DictionaryValue`
+ *   e como apoio de opção. Não repetir o rótulo — descrição igual ao rótulo não renderiza.
+ * - `tone` é o tom tonal do badge de status/estágio; classificação ignora.
+ * - `icon` é o identificador estável do catálogo de ícones do Opus (`iconPickerIcons`);
+ *   nome fora do catálogo não renderiza ícone.
+ * - `color` permanece metadata livre (lida pela Lens); o renderer não a interpreta.
+ */
+export interface DictEntryMeta {
+  label: string
+  doc?: string
+  description?: string
+  tone?: DictTone
+  icon?: string
+  color?: string
+  order?: number
+  [key: string]: unknown
+}
+
+export function isDictPresentation(value: unknown): value is DictPresentation {
+  return typeof value === 'string' && (DICT_PRESENTATIONS as readonly string[]).includes(value)
+}
+
+export function isDictTone(value: unknown): value is DictTone {
+  return typeof value === 'string' && (DICT_TONES as readonly string[]).includes(value)
+}
+
+/** Forma normalizada de um dicionário, independente de onde a meta foi lida. */
+export interface DictionaryDescriptor {
+  keys: string[]
+  entries: Record<string, DictEntryMeta>
+  presentation?: DictPresentation
+  doc?: string
+}
+
+/**
+ * Lê a meta de `t.dict` de qualquer portador: a própria `LogicalTypeMeta`, um `DictType`
+ * (`{ meta }`) ou o schema com a meta anexada por `attachLogicalType` (o `.zod()` do dict).
+ * Retorna `undefined` quando a fonte não é um dicionário reconhecível.
+ */
+export function dictionaryDescriptor(source: unknown): DictionaryDescriptor | undefined {
+  if (source === null || typeof source !== 'object') return undefined
+  const attached = getLogicalType(source)
+  const meta = attached !== undefined
+    ? attached
+    : 'logicalType' in source
+      ? (source as LogicalTypeMeta)
+      : (source as { meta?: unknown }).meta
+  if (meta === null || typeof meta !== 'object') return undefined
+  const { logicalType, params } = meta as LogicalTypeMeta
+  if (logicalType !== 'dict' || params === undefined) return undefined
+  const keys = Array.isArray(params.keys) ? (params.keys as unknown[]).filter((k): k is string => typeof k === 'string') : []
+  const entries = params.entries !== null && typeof params.entries === 'object'
+    ? (params.entries as Record<string, DictEntryMeta>)
+    : {}
+  return {
+    keys,
+    entries,
+    ...(isDictPresentation(params.presentation) ? { presentation: params.presentation } : {}),
+    ...(typeof params.doc === 'string' ? { doc: params.doc } : {}),
+  }
+}
+
+/** Resultado da tabela de decisão para UM valor — o que o renderer materializa. */
+export interface DictionaryValuePresentation {
+  value: string
+  /** Rótulo sempre presente; valor desconhecido devolve o próprio código. */
+  label: string
+  /** False quando o valor não está no dicionário. */
+  known: boolean
+  presentation: DictPresentation
+  /** `null` = texto; `'outline'` = classificação; tom = badge tonal de status/estágio. */
+  badge: 'outline' | DictTone | null
+  /** Identificador do catálogo, só quando declarado na entrada. */
+  icon: string | null
+  /** Só quando `description` existe e acrescenta algo ao rótulo. */
+  description: string | null
+}
+
+const normalizeText = (value: string): string =>
+  value.trim().replace(/\s+/g, ' ').replace(/[.。]+$/u, '').toLocaleLowerCase()
+
+/** Descrição que só repete o rótulo não vira tooltip. */
+export function dictionaryDescription(label: string, description: unknown): string | null {
+  if (typeof description !== 'string') return null
+  const text = description.trim()
+  if (text.length === 0) return null
+  return normalizeText(text) === normalizeText(label) ? null : text
+}
+
+/**
+ * Aplica a tabela de decisão da ADR 0003:
+ *
+ * | papel            | forma | variante                  |
+ * | classification   | badge | outline (ignora `tone`)   |
+ * | status / stage   | badge | tonal: `tone` ?? neutral  |
+ * | plain / ausente  | texto | —                         |
+ *
+ * Ícone só quando declarado; tooltip só quando `description` acrescenta. Valor fora do
+ * dicionário vira texto puro com o código — nunca um badge colorido sobre algo desconhecido.
+ */
+export function presentDictionaryValue(
+  descriptor: DictionaryDescriptor,
+  value: string,
+  overrides: { presentation?: DictPresentation } = {},
+): DictionaryValuePresentation {
+  const presentation = overrides.presentation ?? descriptor.presentation ?? 'plain'
+  const entry = Object.prototype.hasOwnProperty.call(descriptor.entries, value)
+    ? descriptor.entries[value]
+    : undefined
+  if (entry === undefined || typeof entry.label !== 'string') {
+    return { value, label: value, known: false, presentation, badge: null, icon: null, description: null }
+  }
+  const badge: DictionaryValuePresentation['badge'] =
+    presentation === 'classification'
+      ? 'outline'
+      : presentation === 'status' || presentation === 'stage'
+        ? (isDictTone(entry.tone) ? entry.tone : 'neutral')
+        : null
+  return {
+    value,
+    label: entry.label,
+    known: true,
+    presentation,
+    badge,
+    icon: typeof entry.icon === 'string' && entry.icon.length > 0 ? entry.icon : null,
+    description: dictionaryDescription(entry.label, entry.description),
+  }
+}

package/src/core/index.ts

@@ -138,6 +138,24 @@ export { normalizeTraceContext } from './trace.ts'
 // `@softize/opus/schema` re-exporta os dois pra manter a API de sempre.
 export { attachLogicalType, getLogicalType } from './logical-type.ts'
 
+// — Dicionários (apresentação declarada — ADR 0003) ————————————————————————————
+export {
+  DICT_PRESENTATIONS,
+  DICT_TONES,
+  isDictPresentation,
+  isDictTone,
+  dictionaryDescriptor,
+  dictionaryDescription,
+  presentDictionaryValue,
+} from './dictionary.ts'
+export type {
+  DictPresentation,
+  DictTone,
+  DictEntryMeta,
+  DictionaryDescriptor,
+  DictionaryValuePresentation,
+} from './dictionary.ts'
+
 // — Action ————————————————————————————————————————————————————————————————————
 export {
   defineAction,

package/src/core/types.ts

@@ -626,8 +626,13 @@ export interface ListColumnSpec {
   key: string
   label: I18nRef
   /** Render padrão: 'text' (default) · 'number' (alinha à direita) · 'date' (Intl) ·
-   *  'badge' (chip com o valor; dict/cores via célula custom por enquanto). */
+   *  'badge' (chip `outline` com o valor — legado; coluna de dicionário com `presentation`
+   *  declarado usa `DictionaryValue` e dispensa este tipo). */
   type?: 'text' | 'number' | 'date' | 'badge'
+  /** Referência do dicionário registrado em `TbdlibProvider dicts` que esta coluna mostra,
+   *  quando o schema de saída não carrega a meta de `t.dict` (ex.: campo `z.string()`).
+   *  Coluna cujo campo de saída É um `t.dict().zod()` resolve sozinha, sem esta chave. */
+  dictionary?: string
   /** Header clicável (asc ↔ desc). Convenção: a UI escreve `sort: '<key>:<dir>'` no
    *  input; o handler implementa o orderBy. */
   sortable?: boolean
@@ -637,6 +642,9 @@ export interface ListColumnSpec {
   hidden?: boolean
   /** Formato quando `type: 'date'` (Intl.DateTimeFormatOptions). */
   dateFormat?: Intl.DateTimeFormatOptions
+  /** O que a ausência do valor significa nesta coluna (“Nunca enviado”, “Sem vencimento”).
+   *  Sem isto, a célula mostra o travessão e “Não informado” à leitura assistiva. */
+  empty?: I18nRef
 }
 
 export interface SortSpec {

package/src/schema/drivers/zod.ts

@@ -28,6 +28,14 @@
 
 import { z, type ZodTypeAny, type ZodSchema } from 'zod'
 import { attachLogicalType, type LogicalTypeMeta } from '../index.ts'
+import {
+  DICT_PRESENTATIONS,
+  DICT_TONES,
+  isDictPresentation,
+  isDictTone,
+  type DictEntryMeta,
+  type DictPresentation,
+} from '../../core/dictionary.ts'
 import {
   formatDatetime,
   formatDate,
@@ -646,18 +654,11 @@ function isLogicalType(value: unknown): value is LogicalType<unknown> {
 // =============================================================================
 
 /**
- * Meta de cada chave de um dict. `label` obrigatório; resto livre. `doc` é o
- * entendimento de negócio da chave (o que aquele estado significa, quando se
- * entra/sai) — a fonte rica de consulta rápida; flui pro manifest/lente.
+ * Meta de cada chave de um dict — o tipo mora no core (`@softize/opus/core`, ADR 0003) e é
+ * reexportado aqui pra manter a API: `label` obrigatório, `doc` (negócio, manifest/Lens),
+ * `description` (tooltip), `tone` (badge tonal de status/estágio), `icon` (catálogo).
  */
-export interface DictEntryMeta {
-  label: string
-  doc?: string
-  color?: string
-  icon?: string
-  order?: number
-  [key: string]: unknown
-}
+export type { DictEntryMeta }
 
 /**
  * Option pronta pra UI: combina key + meta da entrada.
@@ -686,11 +687,19 @@ export interface DictType<K extends string, M extends DictEntryMeta> {
   has(key: string): key is K
   /** Doc de negócio do dicionário inteiro (o que esse vocabulário representa). */
   doc?: string
+  /** Papel de apresentação declarado (ADR 0003); ausente = texto (`plain`). */
+  presentation?: DictPresentation
 }
 
-/** Opções do dict: `doc` = o entendimento do vocabulário como um todo. */
+/**
+ * Opções do dict: `doc` = o entendimento do vocabulário como um todo; `presentation` = o
+ * papel de apresentação (`classification` · `status` · `stage` · `plain`) que o
+ * `DictionaryValue` e as colunas de `ActionList` honram. Sem `presentation`, o valor
+ * renderiza como texto — a apresentação é declarada, nunca inferida.
+ */
 export interface DictOpts {
   doc?: string
+  presentation?: DictPresentation
 }
 
 const dict = <const M extends Record<string, DictEntryMeta>>(
@@ -702,10 +711,33 @@ const dict = <const M extends Record<string, DictEntryMeta>>(
   if (keys.length === 0) {
     throw new Error('t.dict precisa de pelo menos uma entrada')
   }
+  if (opts?.presentation !== undefined && !isDictPresentation(opts.presentation)) {
+    throw new Error(
+      `t.dict: presentation "${String(opts.presentation)}" inválida; use ${DICT_PRESENTATIONS.join(' | ')}`,
+    )
+  }
+  const tonal = opts?.presentation === 'status' || opts?.presentation === 'stage'
+  for (const key of keys) {
+    const tone = (entries[key] as DictEntryMeta).tone
+    if (tone === undefined) continue
+    if (!isDictTone(tone)) {
+      throw new Error(`t.dict: tone "${String(tone)}" inválido em "${key}"; use ${DICT_TONES.join(' | ')}`)
+    }
+    if (!tonal) {
+      throw new Error(
+        `t.dict: tone em "${key}" exige presentation "status" ou "stage" (classificação usa outline; plain é texto)`,
+      )
+    }
+  }
   const zodSchema = z.enum(keys as [K, ...K[]])
   const meta: LogicalTypeMeta = {
     logicalType: 'dict',
-    params: { keys, entries, ...(opts?.doc !== undefined ? { doc: opts.doc } : {}) },
+    params: {
+      keys,
+      entries,
+      ...(opts?.doc !== undefined ? { doc: opts.doc } : {}),
+      ...(opts?.presentation !== undefined ? { presentation: opts.presentation } : {}),
+    },
   }
   attachLogicalType(zodSchema as unknown as object, meta)
 
@@ -713,6 +745,7 @@ const dict = <const M extends Record<string, DictEntryMeta>>(
     zod: () => zodSchema,
     meta,
     ...(opts?.doc !== undefined ? { doc: opts.doc } : {}),
+    ...(opts?.presentation !== undefined ? { presentation: opts.presentation } : {}),
     keys: () => [...keys],
     labelFor: (key, _locale) => {
       // _locale reservado pra i18n futuro; no v1 sempre retorna o label cru.

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

@@ -20,7 +20,7 @@
  */
 
 import { useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react'
-import { ArrowDown, ArrowUp, ArrowUpDown, Calendar as CalendarIcon, ChevronLeft, ChevronRight, Eraser, RefreshCw, Settings2, SlidersHorizontal, Table2, X } from 'lucide-react'
+import { ArrowDown, ArrowUp, ArrowUpDown, Calendar as CalendarIcon, Eraser, RefreshCw, Settings2, SlidersHorizontal, Table2, X } from 'lucide-react'
 import type {
   ActionDef,
   FilterSpec,
@@ -30,9 +30,22 @@ import type {
   ListColumnSpec,
   SortSpec,
 } from '../../../core/index.ts'
+import { dictionaryDescriptor, getLogicalType, type DictionaryDescriptor } from '../../../core/index.ts'
 import { useDicts, useListAction, useLookupAction, type DictLike } from '../../drivers/react.tsx'
 import { cn } from '../../lib/cn.ts'
+import { objectSchemaShape } from '../../lib/object-schema.ts'
 import { Badge } from '../primitives/badge.tsx'
+import { DictionaryValue } from '../primitives/dictionary-value.tsx'
+import { EmptyValue, isAbsentValue } from '../primitives/empty-value.tsx'
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from '../primitives/pagination.tsx'
 import { Button } from '../primitives/button.tsx'
 import { Calendar } from '../primitives/calendar.tsx'
 import { Checkbox } from '../primitives/checkbox.tsx'
@@ -158,6 +171,9 @@ export function presetRange(preset: string, now = new Date()): { from: string; t
 export interface ListActionLike {
   name: string
   kind: 'list'
+  /** Schema de saída (item). Coluna cujo campo carrega a meta de `t.dict` renderiza
+   *  `DictionaryValue` sem configuração — ver `columnDictionary`. */
+  output?: unknown
   columns?: ListColumnSpec[] | undefined
   filters?: Record<string, FilterSpec> | undefined
   sort?: { fields: string[]; default?: SortSpec[] } | undefined
@@ -270,6 +286,42 @@ function optionsFor(name: string, spec: FilterSpec, runtime?: Record<string, Sel
   return []
 }
 
+/** Desce wrappers (optional/nullable/default) até o schema do campo. Estrutural, sem
+ *  `instanceof`, pra funcionar com as representações v3 e v4 do Zod. */
+function innerSchema(schema: object): object {
+  let current = schema
+  for (;;) {
+    const inner = (current as { _def?: { innerType?: unknown } })._def?.innerType
+    if (inner === null || typeof inner !== 'object') return current
+    current = inner
+  }
+}
+
+/** Dicionário que uma coluna mostra (ADR 0003). Precedência: `dictionary` explícito no
+ *  contrato (resolvido pelos dicts do provider) > meta de `t.dict` no campo do schema de
+ *  saída (zero-config) > nada (a célula segue como texto). */
+function columnDictionary(
+  column: ListColumnSpec,
+  outputShape: Record<string, unknown> | undefined,
+  dicts: Record<string, DictLike>,
+): DictionaryDescriptor | undefined {
+  if (column.dictionary !== undefined) {
+    const dict = dicts[column.dictionary]
+    if (dict === undefined) return undefined
+    const fromMeta = dictionaryDescriptor(dict)
+    if (fromMeta !== undefined) return fromMeta
+    // Dict-like custom (só `options()`): rótulos sem papel de apresentação.
+    const options = dict.options()
+    return {
+      keys: options.map((o) => o.value),
+      entries: Object.fromEntries(options.map((o) => [o.value, { ...o, label: o.label }])),
+    }
+  }
+  const field = outputShape?.[column.key]
+  if (field === null || typeof field !== 'object') return undefined
+  return dictionaryDescriptor(getLogicalType(innerSchema(field)))
+}
+
 /** Opções de `options: { kind: 'dictionary', ref }` via dicts do provider. */
 function dictOptionsFor(spec: FilterSpec, dicts: Record<string, DictLike>): SelectOption[] {
   if (spec.options?.kind !== 'dictionary') return []
@@ -319,7 +371,9 @@ function FilterField({
   options: SelectOption[]
   /** Todos os valores de filtro vigentes — habilita `depends` e alimenta o lookup. */
   allValues: Record<string, unknown>
-  /** Largura do contexto: a toolbar usa os defaults compactos; o modal manda w-full. */
+  /** Largura do contexto: inline, cada tipo tem largura fixa e previsível (select `w-40`,
+   *  lookup e múltiplo `w-52`, texto `w-40`); nunca cresce pelo conteúdo. O modal manda
+   *  `w-full`, que vence pelo merge de classes. */
   className?: string
 }): React.ReactElement {
   const label = text(spec.label, name)
@@ -344,7 +398,7 @@ function FilterField({
         onChange={(v) => onChange(v)}
         options={effOptions}
         placeholder={placeholder}
-        className={cn('min-w-44', className)}
+        className={cn('w-52', className)}
         disabled={!enabled}
         {...(lookup.onSearch !== undefined ? { onSearch: lookup.onSearch, loading: lookup.loading } : {})}
       />
@@ -362,7 +416,7 @@ function FilterField({
         onChange={(v) => onChange(v)}
         options={effOptions}
         placeholder={placeholder}
-        className={cn('min-w-44', className)}
+        className={cn('w-52', className)}
         disabled={!enabled}
         {...(lookup.onSearch !== undefined ? { onSearch: lookup.onSearch, loading: lookup.loading } : {})}
       />
@@ -380,7 +434,7 @@ function FilterField({
         onChange={(v) => onChange(v === ALL ? '' : v)}
         options={[{ value: ALL, label: text(spec.placeholder, 'Todos') }, ...base]}
         disabled={!enabled}
-        className={cn('min-w-36', className)}
+        className={cn('w-40', className)}
       />
     )
   }
@@ -497,7 +551,15 @@ function Labeled({
 }): React.ReactElement {
   return (
     <div data-slot={slot} className="flex shrink-0 flex-col gap-1">
-      <span className="px-0.5 text-xs font-medium text-muted-foreground">{label}</span>
+      {/* w-0 + min-w-full: a label acompanha a largura do controle e nunca a dita —
+          um rótulo longo trunca em vez de alargar o filtro. */}
+      <span
+        data-slot="action-filter-label"
+        title={label}
+        className="block w-0 min-w-full truncate px-0.5 text-xs font-medium text-muted-foreground"
+      >
+        {label}
+      </span>
       {children}
     </div>
   )
@@ -993,11 +1055,16 @@ export function ActionList<TInput, TItem>({
   // — Colunas: prop explícita > derivadas do contrato (+ células custom). O column
   //   picker (state.columns) escolhe o subconjunto visível; null = o default (!hidden).
   const visibleKeys = state.columns
+  const dicts = useDicts()
   const derived: Array<ActionListColumn<TItem> & { spec?: ListColumnSpec }> = useMemo(() => {
     if (columns !== undefined) return columns
+    const outputShape = objectSchemaShape(action.output)
     return (action.columns ?? [])
       .filter((c) => (visibleKeys !== null ? visibleKeys.includes(c.key) : c.hidden !== true))
-      .map((c) => ({
+      .map((c) => {
+        // Resolvido uma vez por coluna: não depende do item.
+        const dictionary = cells?.[c.key] === undefined ? columnDictionary(c, outputShape, dicts) : undefined
+        return {
         key: c.key,
         header: text(c.label, c.key),
         sortable: c.sortable === true,
@@ -1007,7 +1074,24 @@ export function ActionList<TInput, TItem>({
           cells?.[c.key] ??
           ((item: TItem): ReactNode => {
             const v = (item as Record<string, unknown>)[c.key]
-            if (v === null || v === undefined || v === '') return null
+            // Ausência (null · undefined · '' · só espaços) tem representação padrão; 0 e
+            // false são valores. O contrato troca o significado por `empty`.
+            if (isAbsentValue(v)) {
+              const label = text(c.empty, '')
+              return <EmptyValue compact {...(label !== '' ? { label } : {})} />
+            }
+            if (dictionary !== undefined && typeof v === 'string') {
+              // Sem `presentation` declarado o valor é texto (rótulo); `type: 'badge'`
+              // legado mantém o chip outline, agora com o rótulo em vez do código.
+              const legacyBadge = c.type === 'badge' && dictionary.presentation === undefined
+              return (
+                <DictionaryValue
+                  dict={dictionary}
+                  value={v}
+                  {...(legacyBadge ? { variant: 'outline' as const } : {})}
+                />
+              )
+            }
             if (c.type === 'date') {
               // Date-only ('YYYY-MM-DD') parseia LOCAL — new Date() iria pra meia-noite
               // UTC e deslocaria um dia no fuso; ISO completo segue no caminho normal.
@@ -1020,8 +1104,9 @@ export function ActionList<TInput, TItem>({
             if (c.type === 'badge') return <Badge variant="outline">{String(v)}</Badge>
             return typeof v === 'object' ? null : String(v)
           }),
-      }))
-  }, [columns, action.columns, cells, visibleKeys])
+        }
+      })
+  }, [columns, action.columns, action.output, cells, visibleKeys, dicts])
 
   // — Column picker: só faz sentido na tabela derivada do contrato —
   const pickerColumns = columns === undefined ? (action.columns ?? []) : []
@@ -1330,47 +1415,47 @@ export function ActionList<TInput, TItem>({
           Página {state.page} de {pages}
         </span>
         {pages > 1 && (
-          <div className="flex items-center gap-0.5">
-            <Button
-              size="sm"
-              variant="ghost"
-              className="size-7 p-0"
-              aria-label="Página anterior"
-              disabled={state.page <= 1}
-              onClick={() => goTo(state.page - 1)}
-            >
-              <ChevronLeft className="size-3.5" />
-            </Button>
-            {pageWindow(state.page, pages).map((n, i) =>
-              n === '…' ? (
-                // eslint-disable-next-line react/no-array-index-key
-                <span key={`e${i}`} className="px-1">
-                  …
-                </span>
-              ) : (
-                <Button
-                  key={n}
-                  size="sm"
-                  variant={n === state.page ? 'secondary' : 'ghost'}
-                  className="size-7 p-0"
-                  aria-current={n === state.page ? 'page' : undefined}
-                  onClick={() => goTo(n)}
-                >
-                  {n}
-                </Button>
-              ),
-            )}
-            <Button
-              size="sm"
-              variant="ghost"
-              className="size-7 p-0"
-              aria-label="Próxima página"
-              disabled={state.page >= pages}
-              onClick={() => goTo(state.page + 1)}
-            >
-              <ChevronRight className="size-3.5" />
-            </Button>
-          </div>
+          // A primitiva pública na escala densa do rodapé: setas quadradas `size-7`,
+          // números `h-7 min-w-7` que crescem com os dígitos (5726 e 5727 não se colam).
+          <Pagination className="mx-0 w-auto">
+            <PaginationContent className="gap-0.5">
+              <PaginationItem>
+                <PaginationPrevious
+                  iconOnly
+                  className="size-7"
+                  iconClassName="size-3.5"
+                  disabled={state.page <= 1}
+                  onClick={() => goTo(state.page - 1)}
+                />
+              </PaginationItem>
+              {pageWindow(state.page, pages).map((n, i) =>
+                n === '…' ? (
+                  // eslint-disable-next-line react/no-array-index-key
+                  <PaginationItem key={`e${i}`}>
+                    <PaginationEllipsis className="size-7" />
+                  </PaginationItem>
+                ) : (
+                  <PaginationItem key={n}>
+                    <PaginationLink
+                      page={n}
+                      isActive={n === state.page}
+                      className="h-7 min-w-7 text-xs"
+                      onClick={() => goTo(n)}
+                    />
+                  </PaginationItem>
+                ),
+              )}
+              <PaginationItem>
+                <PaginationNext
+                  iconOnly
+                  className="size-7"
+                  iconClassName="size-3.5"
+                  disabled={state.page >= pages}
+                  onClick={() => goTo(state.page + 1)}
+                />
+              </PaginationItem>
+            </PaginationContent>
+          </Pagination>
         )}
         {/* Com 1 página o pager some; o placeholder segura a coluna do meio. */}
         {pages <= 1 && <span />}

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

@@ -18,6 +18,9 @@ export const badgeVariants = cva(
         success: 'border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-400',
         warning: 'border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-400',
         info: 'border-blue-500/30 bg-blue-500/10 text-blue-700 dark:text-blue-400',
+        // `danger` é o tom tonal da família (status/estágio em `DictionaryValue`);
+        // `destructive` continua sólido, reservado a alerta/ação.
+        danger: 'border-red-500/30 bg-red-500/10 text-red-700 dark:text-red-400',
       },
     },
     defaultVariants: { variant: 'default' },

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

@@ -1,6 +1,7 @@
 import * as React from 'react'
 
 import { cn } from '../../lib/cn.ts'
+import { EmptyValue, isAbsentValue } from './empty-value.tsx'
 
 export type DetailGroupVariant = 'plain' | 'framed'
 export type DetailGroupOrientation = 'vertical' | 'horizontal'
@@ -60,9 +61,13 @@ export interface DetailFieldProps extends Omit<
   'children'
 > {
   label: React.ReactNode
+  /** `null`, `undefined`, string vazia ou só com espaços renderizam a ausência
+   *  (“Não informado” ou `empty`); `0` e `false` seguem como valores. */
   value: React.ReactNode
   /** Ícone decorativo que identifica o campo antes do par chave/valor. */
   icon?: React.ReactNode
+  /** O que a ausência significa neste campo: um rótulo (“Nunca enviado”) ou um nó próprio. */
+  empty?: React.ReactNode
 }
 
 function DetailField({
@@ -70,8 +75,14 @@ function DetailField({
   label,
   value,
   icon,
+  empty,
   ...props
 }: DetailFieldProps): React.ReactElement {
+  const content = !isAbsentValue(value)
+    ? value
+    : empty === undefined || typeof empty === 'string'
+      ? <EmptyValue {...(empty !== undefined ? { label: empty } : {})} />
+      : empty
   return (
     <div
       data-slot="detail-field"
@@ -104,7 +115,7 @@ function DetailField({
         data-slot="detail-field-value"
         className="min-w-0 text-sm leading-snug font-normal"
       >
-        {value}
+        {content}
       </dd>
     </div>
   )