@softize/opus 12.7.1 → 12.8.1

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>
   )

package/src/ui/components/primitives/dictionary-value.tsx

@@ -0,0 +1,141 @@
+import * as React from 'react'
+import type { LucideIcon } from 'lucide-react'
+
+import {
+  dictionaryDescriptor,
+  presentDictionaryValue,
+  type DictionaryDescriptor,
+  type DictPresentation,
+  type DictTone,
+} from '../../../core/index.ts'
+import { cn } from '../../lib/cn.ts'
+import { Badge, type BadgeProps } from './badge.tsx'
+import { iconPickerIcons } from './icon-picker.tsx'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './tooltip.tsx'
+
+/**
+ * Fonte aceita pelo renderer: o `DictType` de `t.dict` (tem `meta`), a própria
+ * `LogicalTypeMeta` lida do schema, ou um descritor já normalizado.
+ */
+export type DictionaryValueSource =
+  | { meta: unknown }
+  | { logicalType: string; params?: Record<string, unknown> }
+  | DictionaryDescriptor
+
+export interface DictionaryValueProps extends Omit<React.ComponentProps<'span'>, 'children'> {
+  /** O dicionário (`t.dict`) ou a meta lida do schema do contrato. */
+  dict: DictionaryValueSource
+  /** O código a apresentar. Vazio renderiza `fallback`. */
+  value: string | null | undefined
+  /** Sobrepõe o papel declarado no dicionário SÓ nesta ocorrência. */
+  presentation?: DictPresentation
+  /** Sobrepõe a variante do badge (override explícito). Valor fora do dicionário segue texto. */
+  variant?: BadgeProps['variant']
+  /** `false` esconde o ícone declarado; um nó substitui o ícone do catálogo. */
+  icon?: boolean | React.ReactNode
+  /** Catálogo de ícones nome → componente. Default: `iconPickerIcons`. */
+  icons?: Record<string, LucideIcon>
+  /** `false` suprime o tooltip mesmo com `description` na entrada. */
+  tooltip?: boolean
+  /** Conteúdo quando `value` é vazio. Default: nada. */
+  fallback?: React.ReactNode
+}
+
+const toneVariant: Record<DictTone, NonNullable<BadgeProps['variant']>> = {
+  neutral: 'secondary',
+  info: 'info',
+  success: 'success',
+  warning: 'warning',
+  danger: 'danger',
+}
+
+function isDescriptor(source: DictionaryValueSource): source is DictionaryDescriptor {
+  return 'entries' in source && 'keys' in source
+}
+
+/**
+ * Renderiza um valor de dicionário com a apresentação que o DICIONÁRIO declarou (ADR 0003):
+ * classificação → Badge `outline`; status/estágio → Badge tonal pelo `tone` da entrada
+ * (`neutral` sem tom); `plain` ou sem papel → texto. Ícone só quando a entrada declara `icon`
+ * do catálogo; tooltip só quando `description` acrescenta ao rótulo. O rótulo é sempre texto —
+ * cor e ícone nunca comunicam sozinhos. Valor fora do dicionário mostra o código como texto.
+ */
+export function DictionaryValue({
+  dict,
+  value,
+  presentation,
+  variant,
+  icon = true,
+  icons = iconPickerIcons,
+  tooltip = true,
+  fallback = null,
+  className,
+  ...props
+}: DictionaryValueProps): React.ReactElement | null {
+  if (value === null || value === undefined || value === '') return <>{fallback}</>
+  const descriptor = isDescriptor(dict) ? dict : dictionaryDescriptor(dict)
+  const resolved = presentDictionaryValue(
+    descriptor ?? { keys: [], entries: {} },
+    value,
+    presentation !== undefined ? { presentation } : {},
+  )
+
+  const IconComponent = resolved.icon !== null ? icons[resolved.icon] : undefined
+  const iconNode =
+    icon === false
+      ? null
+      : icon === true
+        ? IconComponent !== undefined
+          ? <IconComponent aria-hidden="true" />
+          : null
+        : icon
+  const description = tooltip ? resolved.description : null
+
+  const dataProps = {
+    'data-dictionary-presentation': resolved.presentation,
+    'data-dictionary-value': resolved.value,
+    ...(resolved.known ? {} : { 'data-dictionary-unknown': true }),
+    ...(description !== null ? { tabIndex: 0 } : {}),
+  }
+
+  // Forma: texto quando o papel não pede badge e ninguém sobrepôs a variante. Valor fora do
+  // dicionário é sempre texto — override não promove código desconhecido a badge.
+  const badgeVariant: BadgeProps['variant'] = !resolved.known
+    ? undefined
+    : variant ??
+      (resolved.badge === null ? undefined : resolved.badge === 'outline' ? 'outline' : toneVariant[resolved.badge])
+
+  const content =
+    badgeVariant === undefined ? (
+      <span
+        data-slot="dictionary-value"
+        className={cn('inline-flex items-center gap-1 [&>svg]:size-3.5 [&>svg]:shrink-0', className)}
+        {...dataProps}
+        {...props}
+      >
+        {iconNode}
+        {resolved.label}
+      </span>
+    ) : (
+      <Badge
+        data-slot="dictionary-value"
+        variant={badgeVariant}
+        className={className}
+        {...dataProps}
+        {...props}
+      >
+        {iconNode}
+        {resolved.label}
+      </Badge>
+    )
+
+  if (description === null) return content
+  return (
+    <TooltipProvider delayDuration={300}>
+      <Tooltip>
+        <TooltipTrigger asChild>{content}</TooltipTrigger>
+        <TooltipContent className="max-w-sm">{description}</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  )
+}

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

@@ -0,0 +1,50 @@
+import * as React from 'react'
+
+import { cn } from '../../lib/cn.ts'
+
+/**
+ * Ausência de valor: `null`, `undefined`, string vazia ou só com espaços. `0`, `false` e
+ * coleções vazias são valores legítimos e nunca contam como ausência — quem apresenta
+ * booleanos e listas decide a própria forma.
+ */
+export function isAbsentValue(value: unknown): boolean {
+  return value === null || value === undefined || (typeof value === 'string' && value.trim().length === 0)
+}
+
+export interface EmptyValueProps extends Omit<React.ComponentProps<'span'>, 'children'> {
+  /** O que a ausência significa neste domínio. Default: “Não informado”. */
+  label?: string
+  /** Célula compacta: mostra o travessão e reserva o `label` à leitura assistiva. */
+  compact?: boolean
+}
+
+/**
+ * Representação padrão de valor ausente. Em texto corrido (DetailField) o rótulo aparece;
+ * em célula compacta (`compact`, o default das colunas de ActionList) aparece o travessão
+ * e o rótulo vai para o leitor de tela. Um domínio troca o rótulo por `label`
+ * (“Nunca enviado”, “Sem vencimento”, “Não se aplica”) em vez de repetir a condicional.
+ */
+export function EmptyValue({
+  label = 'Não informado',
+  compact = false,
+  className,
+  ...props
+}: EmptyValueProps): React.ReactElement {
+  return (
+    <span
+      data-slot="empty-value"
+      data-compact={compact || undefined}
+      className={cn('text-muted-foreground', className)}
+      {...props}
+    >
+      {compact ? (
+        <>
+          <span aria-hidden="true">—</span>
+          <span className="sr-only">{label}</span>
+        </>
+      ) : (
+        label
+      )}
+    </span>
+  )
+}

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

@@ -1,117 +1,147 @@
-import * as React from "react"
-import {
-  ChevronLeftIcon,
-  ChevronRightIcon,
-  MoreHorizontalIcon,
-} from "lucide-react"
+import * as React from 'react'
+import { ChevronLeftIcon, ChevronRightIcon, MoreHorizontalIcon } from 'lucide-react'
 
 import { cn } from '../../lib/cn.ts'
-import { buttonVariants, type Button } from './button.tsx'
+import { buttonVariants, type ButtonProps } from './button.tsx'
 
-function Pagination({ className, ...props }: React.ComponentProps<"nav">) {
+function Pagination({ className, ...props }: React.ComponentProps<'nav'>) {
   return (
     <nav
       role="navigation"
-      aria-label="pagination"
+      aria-label="Paginação"
       data-slot="pagination"
-      className={cn("mx-auto flex w-full justify-center", className)}
+      className={cn('mx-auto flex w-full justify-center', className)}
       {...props}
     />
   )
 }
 
-function PaginationContent({
-  className,
-  ...props
-}: React.ComponentProps<"ul">) {
+function PaginationContent({ className, ...props }: React.ComponentProps<'ul'>) {
   return (
     <ul
       data-slot="pagination-content"
-      className={cn("flex flex-row items-center gap-1", className)}
+      className={cn('flex flex-row items-center gap-1', className)}
       {...props}
     />
   )
 }
 
-function PaginationItem({ ...props }: React.ComponentProps<"li">) {
+function PaginationItem({ ...props }: React.ComponentProps<'li'>) {
   return <li data-slot="pagination-item" {...props} />
 }
 
-type PaginationLinkProps = {
+export interface PaginationLinkProps extends Omit<React.ComponentProps<'a'>, 'children'> {
+  /** Página atual: vira `outline` e ganha `aria-current="page"`. */
   isActive?: boolean
-} & Pick<React.ComponentProps<typeof Button>, "size"> &
-  React.ComponentProps<"a">
+  /** Escala do Button. `default` (números: altura fixa, largura mínima quadrada que cresce
+   *  com os dígitos) ou uma escala `icon*` (setas quadradas, sem padding horizontal). */
+  size?: ButtonProps['size']
+  /** Número da página: dá o nome acessível (“Página N”) e o conteúdo, quando `children` falta. */
+  page?: number
+  /** Sem `href` o link é um `<button>`; `disabled` vale só nesse modo. */
+  disabled?: boolean
+  children?: React.ReactNode
+}
 
-function PaginationLink({
-  className,
-  isActive,
-  size = "icon",
-  ...props
-}: PaginationLinkProps) {
+/**
+ * Um link de página. Altura fixa, largura mínima quadrada e largura que cresce com o
+ * número (`min-w-9 w-auto px-2`, dígitos tabulares): 5726 e 5727 nunca se sobrepõem. Com
+ * `href` é `<a>`; sem `href` é `<button type="button">`, que preserva foco e teclado no
+ * modo controlado. Ajuste a escala por `className` (ex.: `h-7 min-w-7 text-xs`).
+ */
+function PaginationLink({ className, isActive, page, disabled, href, size = 'default', children, ...props }: PaginationLinkProps) {
+  const square = typeof size === 'string' && size.startsWith('icon')
+  const shared = {
+    'aria-current': isActive ? ('page' as const) : undefined,
+    'aria-label': props['aria-label'] ?? (page !== undefined ? `Página ${page}` : undefined),
+    'data-slot': 'pagination-link',
+    'data-active': isActive,
+    className: cn(
+      buttonVariants({ variant: isActive ? 'outline' : 'ghost', size }),
+      // Número: a largura mínima é quadrada e o conteúdo manda no resto. Escala `icon*`
+      // fica quadrada de verdade (sem `has-[>svg]:px-*` do `default`).
+      !square && 'h-9 w-auto min-w-9 px-2 tabular-nums',
+      className,
+    ),
+  }
+  const content = children ?? page
+  if (href !== undefined) {
+    return (
+      <a href={href} {...props} {...shared}>
+        {content}
+      </a>
+    )
+  }
+  const { onClick, ...rest } = props as React.ComponentProps<'button'>
   return (
-    <a
-      aria-current={isActive ? "page" : undefined}
-      data-slot="pagination-link"
-      data-active={isActive}
-      className={cn(
-        buttonVariants({
-          variant: isActive ? "outline" : "ghost",
-          size,
-        }),
-        className
-      )}
-      {...props}
-    />
+    <button type="button" disabled={disabled} onClick={onClick} {...rest} {...shared}>
+      {content}
+    </button>
   )
 }
 
+export interface PaginationControlProps extends Omit<PaginationLinkProps, 'page' | 'isActive'> {
+  /** Nome acessível e texto visível. Default: “Página anterior” / “Próxima página”. */
+  label?: string
+  /** Só a seta, quadrada (escala `icon`, `size-9`); o `label` continua como nome acessível. */
+  iconOnly?: boolean
+  /** Classe do ícone (ex.: `size-3.5` na escala densa). Vai no próprio svg, porque o
+   *  fallback `[&_svg:not([class*='size-'])]:size-4` do Button vence qualquer seletor de fora. */
+  iconClassName?: string
+}
+
 function PaginationPrevious({
   className,
+  label = 'Página anterior',
+  iconOnly = false,
+  iconClassName,
+  size,
   ...props
-}: React.ComponentProps<typeof PaginationLink>) {
+}: PaginationControlProps) {
   return (
     <PaginationLink
-      aria-label="Go to previous page"
-      size="default"
-      className={cn("gap-1 px-2.5 sm:pl-2.5", className)}
+      aria-label={label}
+      size={size ?? (iconOnly ? 'icon' : 'default')}
+      className={cn(!iconOnly && 'gap-1 px-2.5 sm:pl-2.5', className)}
       {...props}
     >
-      <ChevronLeftIcon />
-      <span className="hidden sm:block">Previous</span>
+      <ChevronLeftIcon className={iconClassName} />
+      {!iconOnly && <span className="hidden sm:block">{label}</span>}
     </PaginationLink>
   )
 }
 
 function PaginationNext({
   className,
+  label = 'Próxima página',
+  iconOnly = false,
+  iconClassName,
+  size,
   ...props
-}: React.ComponentProps<typeof PaginationLink>) {
+}: PaginationControlProps) {
   return (
     <PaginationLink
-      aria-label="Go to next page"
-      size="default"
-      className={cn("gap-1 px-2.5 sm:pr-2.5", className)}
+      aria-label={label}
+      size={size ?? (iconOnly ? 'icon' : 'default')}
+      className={cn(!iconOnly && 'gap-1 px-2.5 sm:pr-2.5', className)}
       {...props}
     >
-      <span className="hidden sm:block">Next</span>
-      <ChevronRightIcon />
+      {!iconOnly && <span className="hidden sm:block">{label}</span>}
+      <ChevronRightIcon className={iconClassName} />
     </PaginationLink>
   )
 }
 
-function PaginationEllipsis({
-  className,
-  ...props
-}: React.ComponentProps<"span">) {
+/** Decorativa: `aria-hidden`; os números ao redor já dizem que há páginas no vão. */
+function PaginationEllipsis({ className, ...props }: React.ComponentProps<'span'>) {
   return (
     <span
       aria-hidden
       data-slot="pagination-ellipsis"
-      className={cn("flex size-9 items-center justify-center", className)}
+      className={cn('flex size-9 items-center justify-center', className)}
       {...props}
     >
       <MoreHorizontalIcon className="size-4" />
-      <span className="sr-only">More pages</span>
     </span>
   )
 }

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

@@ -27,7 +27,7 @@ render(
           {workspaces.map((w) => (
             <div key={w.id} className="flex items-center gap-2 rounded-md border border-border p-3">
               <span className="text-sm font-semibold">{w.name}</span>
-              <Badge variant={w.status === 'active' ? 'success' : 'warning'}>{w.status}</Badge>
+              <DictionaryValue dict={docWorkspaceStatus} value={w.status} />
               <span className="ml-auto text-xs text-muted-foreground">{w.agents} agentes</span>
             </div>
           ))}

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

@@ -28,16 +28,37 @@ superfícies que não são listagens, como relatórios. O estado é controlado p
 />
 ```
 
-Busca e filtros são renderizados somente quando declarados. Períodos incluem os presets do
+Selects inline têm largura fixa e previsível (`w-40`; lookup e múltiplo `w-52`): nem a label nem
+o valor selecionado alargam o controle — o rótulo trunca e a opção inteira continua na lista. No
+modal de filtros avançados, o select ocupa a largura toda. 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`.
 
+## Colunas de dicionário
+
+Coluna cujo campo no schema de saída é um `t.dict().zod()` renderiza `DictionaryValue` com a
+apresentação que o dicionário declarou (`presentation`: classificação em badge `outline`, status
+e estágio em badge tonal, `plain` ou ausente como texto). Nada a configurar na tela. Quando o
+campo de saída é uma string comum, a coluna nomeia o dicionário registrado no provider:
+`{ key: 'source', label: 'Fonte', dictionary: 'customerSource' }`. Dimensões independentes, como
+tipo e estágio, ficam em colunas distintas — a leitura de comparação depende disso. `type:
+'badge'` continua sendo o chip `outline` legado; com dicionário, ele mostra o rótulo em vez do
+código.
+
+## Valor ausente
+
+Célula escalar com `null`, `undefined`, string vazia ou só espaços mostra o travessão e “Não
+informado” à leitura assistiva, sem condicional na tela. `0` e `false` são valores; array e objeto
+sem `cells` continuam sem representação padrão, porque a forma de uma coleção é de quem a
+apresenta. A coluna do contrato
+troca o significado com `empty`: `{ key: 'sentAt', label: 'Último envio', empty: 'Nunca enviado' }`.
+Renderer customizado reutiliza `EmptyValue`.
+
 ## 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.
+As colunas do contrato descrevem DADOS; apresentação especial entra por cima com `cells` (chave = key da coluna). É onde vivem links, composições e a coluna de ações; valor de dicionário já resolve sozinho pela coluna, sem `cells`.
 
 ```tsx preview col
-const STATUS_VARIANT = { active: 'success', onboarding: 'warning', paused: 'outline' }
-
 render(
   <DocBrowserActionProvider>
     <div className="w-full">
@@ -45,7 +66,11 @@ render(
         action={docWorkspaceList}
         input={{}}
         cells={{
-          status: (w) => <Badge variant={STATUS_VARIANT[w.status]}>{w.status}</Badge>,
+          name: (w) => (
+            <a href="#" onClick={(e) => e.preventDefault()} className="font-medium underline-offset-4 hover:underline">
+              {w.name}
+            </a>
+          ),
         }}
       />
     </div>
@@ -68,7 +93,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 primeiro carregamento, `DataState` centraliza o spinner; no refetch com a lista já na tela, o corpo esmaece (`aria-busy`) até os dados chegarem.
+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") compõe a primitiva `Pagination` na escala densa — números com largura mínima que cresce com os dígitos, setas quadradas, nome acessível por página — e 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)
 
@@ -106,7 +131,7 @@ render(
                   <div key={w.id} className="rounded-lg border border-border p-3">
                     <div className="flex items-center gap-2">
                       <span className="text-sm font-semibold">{w.name}</span>
-                      <Badge variant={w.status === 'active' ? 'success' : 'warning'}>{w.status}</Badge>
+                      <DictionaryValue dict={docWorkspaceStatus} value={w.status} />
                     </div>
                     <p className="mt-1 text-xs text-muted-foreground">{w.agents} agentes.</p>
                   </div>
@@ -171,7 +196,7 @@ render(
               <div key={w.id} className="rounded-lg border border-border p-3">
                 <div className="flex items-center gap-2">
                   <span className="text-sm font-semibold">{w.name}</span>
-                  <Badge variant={w.status === 'active' ? 'success' : 'warning'}>{w.status}</Badge>
+                  <DictionaryValue dict={docWorkspaceStatus} value={w.status} />
                 </div>
                 <p className="mt-1 text-xs text-muted-foreground">{w.agents} agentes.</p>
               </div>
@@ -188,7 +213,7 @@ render(
 
 | Chave | O que declara |
 |---|---|
-| `columns` | `{ key, label, type?, sortable?, fit?, hidden?, dateFormat? }` — a tabela. `hidden` fica fora (base do futuro column picker). |
+| `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 pro modal; `depends` desabilita/cascateia; options `kind: 'lookup'` busca numa 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'`. |

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

@@ -12,13 +12,16 @@ Button.
 
 ## Tons de status da casa
 
-success/warning/info (fill tingido + borda translúcida) — convenção da casa pra estado semântico,
-igual ao KindBadge do Maestro. Não-interativos.
+success/warning/info/danger (fill tingido + borda translúcida) — convenção da casa pra estado
+semântico, igual ao KindBadge do Maestro. Não-interativos. `danger` é o tom tonal da família;
+`destructive` continua sólido, pra alerta e ação. Valor de dicionário com papel declarado usa
+`DictionaryValue`, que escolhe o tom pela metadata em vez de repetir esta escolha em cada tela.
 
 ```tsx preview
 <Badge variant="success">Ativa</Badge>
 <Badge variant="warning">Aguardando revisor</Badge>
 <Badge variant="info">Em sessão</Badge>
+<Badge variant="danger">Bloqueada</Badge>
 ```
 
 ## Com ícone
@@ -44,5 +47,5 @@ variantes.
 
 | Prop | Tipo | Default | Descrição |
 |---|---|---|---|
-| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'warning' \| 'info'` | `'default'` | Intenção (default/secondary/destructive/outline) ou tom de status da casa (success/warning/info). |
+| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'warning' \| 'info' \| 'danger'` | `'default'` | Intenção (default/secondary/destructive/outline) ou tom de status da casa (success/warning/info/danger). |
 | `asChild` | `boolean` | `false` | Renderiza como o filho (Radix Slot) em vez de `<span>` — ex.: um `<a>` com cara de badge. |

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

@@ -6,8 +6,13 @@ para entrada e validação; use DetailField quando a pessoa apenas consulta um v
 <DetailGroup columns={2}>
   <DetailField label="Cliente" value="João Silva" />
   <DetailField
-    label="Tipo"
-    value={<Badge variant="secondary">Prospect</Badge>}
+    label="Estágio"
+    value={
+      <DictionaryValue
+        dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', tone: 'success' } }, presentation: 'stage' }}
+        value="prospect"
+      />
+    }
   />
   <DetailField
     className="sm:col-span-2"
@@ -18,6 +23,18 @@ para entrada e validação; use DetailField quando a pessoa apenas consulta um v
 </DetailGroup>
 ```
 
+## Valor ausente
+
+`null`, `undefined`, string vazia ou só com espaços mostram “Não informado”; `empty` troca o
+significado no domínio. `0` e `false` seguem como valores. Ver `EmptyValue`.
+
+```tsx preview col
+<DetailGroup columns={2}>
+  <DetailField label="Telefone" value={null} />
+  <DetailField label="Último envio" value="" empty="Nunca enviado" />
+</DetailGroup>
+```
+
 ## Moldura e divisórias internas
 
 `variant="framed"` adiciona a superfície e a borda externa. `dividers` desenha apenas as