@softize/opus 12.7.0 → 12.8.0

package/src/ui/docs/content/dictionary-value.md

@@ -0,0 +1,120 @@
+Um valor de dicionário (`t.dict`) apresentado do jeito que o **dicionário** declarou. A tela não
+decide se o valor vira badge, cor ou ícone: ela passa o dicionário e o código, e o renderer
+aplica os defaults da apresentação declarada. O rótulo está sempre presente como texto — cor e
+ícone nunca comunicam sozinhos.
+
+```tsx preview
+<DictionaryValue
+  dict={{ keys: ['pf', 'pj'], entries: { pf: { label: 'Pessoa física', icon: 'user' }, pj: { label: 'Empresa', icon: 'building' } }, presentation: 'classification' }}
+  value="pj"
+/>
+<DictionaryValue
+  dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', tone: 'success' } }, presentation: 'stage' }}
+  value="customer"
+/>
+<DictionaryValue
+  dict={{ keys: ['open', 'blocked'], entries: { open: { label: 'Aberto', tone: 'warning', icon: 'clock', description: 'Aguarda uma decisão da Fonte.' }, blocked: { label: 'Bloqueado', tone: 'danger' } }, presentation: 'status' }}
+  value="open"
+/>
+<DictionaryValue
+  dict={{ keys: ['nbs', 'followize'], entries: { nbs: { label: 'NBS' }, followize: { label: 'Followize' } } }}
+  value="nbs"
+/>
+```
+
+## O dicionário declara o papel
+
+`presentation` fica no `t.dict`, ao lado de `doc`. Sem ele, o valor é texto: a apresentação é
+declarada, nunca inferida pelo nome do dicionário.
+
+```ts
+export const customerKindDict = t.dict(
+  {
+    pf: { label: 'Pessoa física', icon: 'user' },
+    pj: { label: 'Empresa', icon: 'building' },
+  },
+  { doc: 'Natureza da parte no cadastro global.', presentation: 'classification' },
+)
+
+export const customerStageDict = t.dict(
+  {
+    prospect: { label: 'Prospect', description: 'Relacionamento ainda em prospecção.' },
+    customer: { label: 'Cliente', tone: 'success' },
+  },
+  { doc: 'Estágio comercial atual da parte.', presentation: 'stage' },
+)
+```
+
+| Papel | Quando | Forma | Variante |
+|---|---|---|---|
+| `classification` | Tipo, categoria, natureza — uma dimensão estável de comparação. | Badge | `outline`; ignora `tone`. |
+| `status` | Situação operacional que muda com o tempo. | Badge | Tonal pelo `tone` da entrada; `neutral` sem tom. Nunca `outline`. |
+| `stage` | Etapa de um ciclo ou funil. | Badge | Igual a `status`. |
+| `plain` ou ausente | Valor que só precisa ser legível. | Texto | — |
+
+## Por entrada: tom, ícone e descrição
+
+- `tone` (`neutral` · `info` · `success` · `warning` · `danger`) só existe em status e estágio;
+  `t.dict` rejeita o tom em classificação e em `plain`.
+- `icon` é um nome do catálogo do Opus (`iconPickerIcons`). Nome fora do catálogo não renderiza
+  ícone; o renderer não inventa. Vocabulário próprio entra por `icons`.
+- `description` é o texto curto para a pessoa e aparece em tooltip focável. Descrição igual ao
+  rótulo não vira tooltip. `doc` é o entendimento de negócio para manifest e Lens; não aparece.
+
+```tsx preview
+<DictionaryValue
+  dict={{ keys: ['closed'], entries: { closed: { label: 'Fechado', icon: 'nao-existe', description: 'Fechado' } }, presentation: 'status' }}
+  value="closed"
+/>
+<DictionaryValue
+  dict={{ keys: ['closed'], entries: { closed: { label: 'Fechado', icon: 'archive' } }, presentation: 'status' }}
+  value="closed"
+  icons={{ archive: Archive }}
+/>
+```
+
+## Override explícito
+
+Os defaults vêm do dicionário; a tela sobrepõe só quando tem um motivo, e sobrepõe às claras.
+
+```tsx preview
+<DictionaryValue
+  dict={{ keys: ['customer'], entries: { customer: { label: 'Cliente', tone: 'success' } }, presentation: 'stage' }}
+  value="customer"
+  presentation="plain"
+/>
+<DictionaryValue
+  dict={{ keys: ['pf'], entries: { pf: { label: 'Pessoa física', icon: 'user' } }, presentation: 'classification' }}
+  value="pf"
+  icon={false}
+/>
+<DictionaryValue
+  dict={{ keys: ['pf'], entries: { pf: { label: 'Pessoa física' } }, presentation: 'classification' }}
+  value={null}
+  fallback={<span className="text-muted-foreground">—</span>}
+/>
+```
+
+Valor fora do dicionário aparece como texto com o próprio código, marcado com
+`data-dictionary-unknown`, sem badge, ícone ou tooltip, mesmo com `variant` sobreposto.
+
+## Em ActionList
+
+Coluna cujo campo do schema de saída é um `t.dict().zod()` já renderiza `DictionaryValue` com o
+papel declarado, sem `cells`. 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 (tipo e estágio, por exemplo) ficam em colunas distintas; não empilhar
+uma sob a outra como texto secundário.
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `dict` | `DictType \| LogicalTypeMeta \| DictionaryDescriptor` | — | O dicionário (`t.dict`), a meta lida do schema ou um descritor normalizado. |
+| `value` | `string \| null \| undefined` | — | O código. Vazio renderiza `fallback`. |
+| `presentation` | `'classification' \| 'status' \| 'stage' \| 'plain'` | do dicionário | Sobrepõe o papel só nesta ocorrência. |
+| `variant` | variante de `Badge` | pelo papel | Sobrepõe a variante e promove texto a badge. |
+| `icon` | `boolean \| ReactNode` | `true` | `false` esconde o ícone declarado; um nó substitui. |
+| `icons` | `Record<string, LucideIcon>` | `iconPickerIcons` | Catálogo nome → componente. |
+| `tooltip` | `boolean` | `true` | `false` suprime a descrição. |
+| `fallback` | `ReactNode` | `null` | Conteúdo quando `value` é vazio. |

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

@@ -0,0 +1,48 @@
+Valor ausente tem uma representação padrão. Em célula compacta de tabela aparece o travessão,
+e a leitura assistiva recebe “Não informado”; em texto corrido, como no `DetailField`, aparece o
+próprio rótulo. As colunas de `ActionList` e o `DetailField` já fazem isso sozinhos; um renderer
+customizado reutiliza a primitiva em vez de repetir a condicional.
+
+```tsx preview
+<div className="flex items-center gap-6 text-sm">
+  <EmptyValue />
+  <EmptyValue compact />
+  <EmptyValue label="Nunca enviado" />
+  <EmptyValue compact label="Sem vencimento" />
+</div>
+```
+
+## O que conta como ausência
+
+`null`, `undefined`, string vazia e string só com espaços. `0`, `false` e coleções vazias são
+valores legítimos: quem apresenta booleanos e listas decide a própria forma. `isAbsentValue`
+exporta a mesma regra para renderers customizados.
+
+## O domínio dá o significado
+
+A ausência raramente é neutra: um envio que nunca aconteceu, um prazo que não existe, um campo
+que não se aplica. `label` troca o texto, e `ListColumnSpec.empty` faz o mesmo na coluna do
+contrato, sem condicional na tela.
+
+```tsx preview col
+<DetailGroup columns={2}>
+  <DetailField label="E-mail" value="" />
+  <DetailField label="Último envio" value={null} empty="Nunca enviado" />
+  <DetailField label="Saldo" value={0} />
+  <DetailField label="Vencimento" value={undefined} empty="Sem vencimento" />
+</DetailGroup>
+```
+
+```ts
+columns: [
+  { key: 'email', label: 'E-mail' },                               // — · “Não informado”
+  { key: 'sentAt', label: 'Último envio', empty: 'Nunca enviado' }, // — · “Nunca enviado”
+]
+```
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `label` | `string` | `'Não informado'` | O que a ausência significa neste domínio. |
+| `compact` | `boolean` | `false` | Célula compacta: travessão visível, rótulo só para leitura assistiva. |

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

@@ -1,6 +1,10 @@
 ## Básico
 
-É composição: Pagination embrulha PaginationContent, e cada PaginationItem segura um link. isActive no PaginationLink marca a página atual (vira outline).
+É composição: Pagination embrulha PaginationContent, e cada PaginationItem segura um link. `page`
+dá o número e o nome acessível (“Página N”); `isActive` marca a página atual (vira outline). Cada
+número tem altura fixa e largura mínima quadrada que cresce com os dígitos — 5726 e 5727 nunca se
+colam. As setas seguem quadradas e já falam pt-BR; `label` localiza, `iconOnly` deixa só a seta.
+É o único paginador da casa: `ActionList` compõe esta primitiva no rodapé, na escala densa.
 
 ```tsx preview
 <Pagination>
@@ -9,15 +13,13 @@
       <PaginationPrevious href="#" />
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#">1</PaginationLink>
+      <PaginationLink href="#" page={1} />
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#" isActive>
-        2
-      </PaginationLink>
+      <PaginationLink href="#" page={2} isActive />
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#">3</PaginationLink>
+      <PaginationLink href="#" page={3} />
     </PaginationItem>
     <PaginationItem>
       <PaginationNext href="#" />
@@ -26,6 +28,37 @@
 </Pagination>
 ```
 
+## Números longos
+
+A largura mínima é quadrada; o número manda no resto. Na escala densa de um rodapé, ajuste por
+`className` (`h-7 min-w-7 text-xs` nos números; `size-7` mais `iconClassName="size-3.5"` nas
+setas com `iconOnly`).
+
+```tsx preview
+<Pagination>
+  <PaginationContent className="gap-0.5">
+    <PaginationItem>
+      <PaginationPrevious href="#" iconOnly className="size-7" iconClassName="size-3.5" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" page={1} className="h-7 min-w-7 text-xs" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationEllipsis className="size-7" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" page={5726} className="h-7 min-w-7 text-xs" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationLink href="#" page={5727} isActive className="h-7 min-w-7 text-xs" />
+    </PaginationItem>
+    <PaginationItem>
+      <PaginationNext href="#" iconOnly className="size-7" iconClassName="size-3.5" />
+    </PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
 ## Com elipse
 
 PaginationEllipsis é o atalho decorativo (aria-hidden) entre blocos de páginas distantes — útil quando a lista de sessões do workspace tem páginas demais pra caber na barra.
@@ -37,18 +70,16 @@ PaginationEllipsis é o atalho decorativo (aria-hidden) entre blocos de páginas
       <PaginationPrevious href="#" />
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#">1</PaginationLink>
+      <PaginationLink href="#" page={1} />
     </PaginationItem>
     <PaginationItem>
       <PaginationEllipsis />
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#" isActive>
-        8
-      </PaginationLink>
+      <PaginationLink href="#" page={8} isActive />
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#">9</PaginationLink>
+      <PaginationLink href="#" page={9} />
     </PaginationItem>
     <PaginationItem>
       <PaginationNext href="#" />
@@ -59,7 +90,9 @@ PaginationEllipsis é o atalho decorativo (aria-hidden) entre blocos de páginas
 
 ## Controlado
 
-Os links são <a> — sem href, vire onClick e guarde a página no estado. Aqui a barra pagina os repositórios do workspace Empresa X.
+Sem `href`, cada link vira `<button>`: foco, teclado e `disabled` funcionam como em qualquer
+botão. Guarde a página no estado e responda ao `onClick`. Aqui a barra pagina os repositórios do
+workspace Empresa X.
 
 ```tsx preview col
 const [page, setPage] = useState(2)
@@ -70,18 +103,18 @@ render(
     <PaginationContent>
       <PaginationItem>
         <PaginationPrevious
+          disabled={page <= 1}
           onClick={() => setPage((p) => Math.max(1, p - 1))}
         />
       </PaginationItem>
       {pages.map((n) => (
         <PaginationItem key={n}>
-          <PaginationLink isActive={n === page} onClick={() => setPage(n)}>
-            {n}
-          </PaginationLink>
+          <PaginationLink page={n} isActive={n === page} onClick={() => setPage(n)} />
         </PaginationItem>
       ))}
       <PaginationItem>
         <PaginationNext
+          disabled={page >= pages.length}
           onClick={() => setPage((p) => Math.min(pages.length, p + 1))}
         />
       </PaginationItem>
@@ -94,6 +127,10 @@ render(
 
 | Prop | Tipo | Default | Descrição |
 |---|---|---|---|
+| `page (PaginationLink)` | `number` | | Número da página: vira o conteúdo (quando não há `children`) e o nome acessível “Página N”. |
 | `isActive (PaginationLink)` | `boolean` | `false` | Marca a página atual: vira outline e ganha aria-current="page". Os demais ficam ghost. |
-| `size (PaginationLink)` | `'default' \| 'sm' \| 'lg' \| 'icon'` | `'icon'` | Tamanho do link, herdado do Button. Previous/Next já forçam default pra caber o texto. |
-| `href (PaginationLink)` | `string` | | Cada link é um <a>: passe href pra navegação real, ou use onClick no modo controlado. |
+| `href (PaginationLink)` | `string` | | Com `href` o link é um `<a>`; sem `href` é um `<button>` controlado por `onClick`, com `disabled`. |
+| `size (PaginationLink)` | `'default' \| 'sm' \| 'lg' \| 'icon' \| 'icon-sm' \| 'icon-xs'` | `'default'` | Escala do Button. Números usam `default` (largura mínima quadrada que cresce); as setas com `iconOnly` usam `icon`. |
+| `label (Previous/Next)` | `string` | `'Página anterior'` / `'Próxima página'` | Nome acessível e texto visível das setas. |
+| `iconOnly (Previous/Next)` | `boolean` | `false` | Só a seta, quadrada (`size="icon"`); o `label` continua como nome acessível. |
+| `iconClassName (Previous/Next)` | `string` | | Classe do svg da seta, para a escala densa (`size-3.5`). |

package/src/ui/docs/doc-client.tsx

@@ -6,8 +6,8 @@
  */
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { z } from 'zod'
-import { defineContract, error } from '../../core/index.ts'
-import type { ActionDef, ActionResult, ClientAdapter, Paginated } from '../../core/index.ts'
+import { attachLogicalType, defineContract, error } from '../../core/index.ts'
+import type { ActionDef, ActionResult, ClientAdapter, LogicalTypeMeta, Paginated } from '../../core/index.ts'
 import { TbdlibProvider } from '../react.tsx'
 
 // — Dados enlatados (domínio da casa) —
@@ -28,6 +28,23 @@ const WORKSPACES: DocBrowserWorkspace[] = [
 
 const STATUS = ['active', 'onboarding', 'paused'] as const
 
+/** O vocabulário de status do workspace com a apresentação declarada (ADR 0003). O palco mora
+ *  na UI, e a fronteira ui→core não deixa importar o driver de schema; isto é exatamente o que
+ *  `t.dict(entries, { presentation: 'status' })` produz — o enum com a meta lógica anexada. */
+export const docWorkspaceStatus: LogicalTypeMeta = {
+  logicalType: 'dict',
+  params: {
+    keys: [...STATUS],
+    entries: {
+      active: { label: 'Ativo', tone: 'success', description: 'Agentes em operação para o cliente.' },
+      onboarding: { label: 'Onboarding', tone: 'warning' },
+      paused: { label: 'Pausado' },
+    },
+    presentation: 'status',
+  },
+}
+const workspaceStatus = attachLogicalType(z.enum(STATUS), docWorkspaceStatus)
+
 // — Contratos fake (mesmo shape dos reais; ver apps/admin/shared/src/workspaces.ts) —
 export const docWorkspaceCreate = defineContract({
   name: 'workspace.create',
@@ -65,7 +82,7 @@ export const docWorkspaceList = defineContract({
     id: z.string(),
     name: z.string(),
     client: z.string(),
-    status: z.enum(STATUS),
+    status: workspaceStatus,
     agents: z.number(),
   }),
   // O modo DECLARATIVO do ActionList: a tabela e a toolbar derivam daqui.
@@ -104,7 +121,7 @@ export const docWorkspaceView = defineContract({
     id: z.string(),
     name: z.string(),
     client: z.string(),
-    status: z.enum(STATUS),
+    status: workspaceStatus,
     agents: z.number(),
   }),
   projection: ['id', 'name', 'client', 'status', 'agents'],

package/src/ui/docs/registry.tsx

@@ -68,6 +68,8 @@ import composerMd from './content/composer.md?raw'
 import copyableMd from './content/copyable.md?raw'
 import dialogMd from './content/dialog.md?raw'
 import detailMd from './content/detail.md?raw'
+import dictionaryValueMd from './content/dictionary-value.md?raw'
+import emptyValueMd from './content/empty-value.md?raw'
 import drawerMd from './content/drawer.md?raw'
 import menuMd from './content/menu.md?raw'
 import emptyMd from './content/empty.md?raw'
@@ -106,6 +108,7 @@ import {
   docSessionDelete,
   docWorkspaceCreate,
   docWorkspaceList,
+  docWorkspaceStatus,
   docWorkspaceView,
 } from './doc-client'
 import actionFormMd from './content/action-form.md?raw'
@@ -175,6 +178,7 @@ const patternScope = {
   DocBrowserActionProvider,
   docWorkspaceCreate,
   docWorkspaceList,
+  docWorkspaceStatus,
   docWorkspaceView,
   docSessionArchive,
   docSessionDelete,
@@ -365,6 +369,8 @@ export const UI_SECTIONS: DocSection[] = [
           { slug: 'carousel', title: 'Carousel', render: comp('Carousel', 'carousel', carouselMd) },
           { slug: 'copyable', title: 'Copyable', render: comp('Copyable', 'copyable', copyableMd) },
           { slug: 'detail', title: 'Detail', render: comp('Detail', 'detail', detailMd) },
+          { slug: 'dictionary-value', title: 'Dictionary Value', render: comp('Dictionary Value', 'dictionary-value', dictionaryValueMd) },
+          { slug: 'empty-value', title: 'Empty Value', render: comp('Empty Value', 'empty-value', emptyValueMd) },
           { slug: 'item', title: 'Item', render: comp('Item', 'item', itemMd) },
           { slug: 'kbd', title: 'Kbd', render: comp('Kbd', 'kbd', kbdMd) },
           { slug: 'markdown', title: 'Markdown', render: comp('Markdown', 'markdown', markdownMd) },

package/src/ui/meta.ts

@@ -27,7 +27,19 @@ export const componentMeta = {
     name: 'badge',
     ancestry: 'shadcn',
     whenToUse:
-      'Rótulo curto de status/categoria. `variant` pra intenção (default/secondary/destructive/outline) ou tom de status (success/warning/info, fill tingido). Não-interativo — pra clique, use Button ou `asChild` num <a>.',
+      'Rótulo curto de status/categoria. `variant` pra intenção (default/secondary/destructive/outline) ou tom de status (success/warning/info/danger, fill tingido). Não-interativo — pra clique, use Button ou `asChild` num <a>. Valor de dicionário com papel declarado usa DictionaryValue em vez de escolher a variante à mão.',
+  },
+  'empty-value': {
+    name: 'empty-value',
+    ancestry: 'opus',
+    whenToUse:
+      'Representação padrão de valor ausente (`null`, `undefined`, string vazia ou só espaços): em célula compacta (`compact`) mostra o travessão e reserva “Não informado” à leitura assistiva; em texto corrido mostra o rótulo. `label` troca o significado da ausência no domínio (“Nunca enviado”, “Sem vencimento”). `0` e `false` são valores, nunca ausência. Colunas de ActionList e DetailField já a usam; renderer customizado reutiliza em vez de repetir a condicional.',
+  },
+  'dictionary-value': {
+    name: 'dictionary-value',
+    ancestry: 'opus',
+    whenToUse:
+      'Valor de um `t.dict` com a apresentação que o dicionário declarou (ADR 0003): `classification` vira Badge outline, `status`/`stage` viram Badge tonal pelo `tone` da entrada, `plain` ou sem papel vira texto. Ícone só quando a entrada declara `icon` do catálogo; tooltip só quando `description` acrescenta ao rótulo. O texto está sempre presente. Overrides explícitos por `presentation`, `variant`, `icon`, `tooltip` e `fallback`; não inferir badge, cor ou ícone a partir do nome do dicionário. Colunas de ActionList cujo campo é dicionário já usam este renderer.',
   },
   'dot': {
     name: 'dot',
@@ -293,7 +305,7 @@ export const componentMeta = {
     name: 'pagination',
     ancestry: 'shadcn',
     whenToUse:
-      'Navegação entre páginas montada por composição (shadcn): Pagination › PaginationContent › PaginationItem com PaginationLink, mais PaginationPrevious/PaginationNext e PaginationEllipsis. Marque a página atual com `isActive` no PaginationLink; os links são `<a>`, então use `href` pra navegação real ou `onClick` no modo controlado. Pra rolagem infinita ou listas curtas, dispense a barra.',
+      'Navegação entre páginas montada por composição: Pagination › PaginationContent › PaginationItem com PaginationLink, mais PaginationPrevious/PaginationNext e PaginationEllipsis. `page` dá o número e o nome acessível (“Página N”); `isActive` marca a atual. Com `href` o link é `<a>`; sem `href` vira `<button>` (modo controlado, com foco e `disabled`). Os números têm largura mínima quadrada e crescem com os dígitos; as setas seguem quadradas (`iconOnly`). `label` localiza as setas. É o único paginador: ActionList compõe esta primitiva na escala densa do rodapé. Pra rolagem infinita ou listas curtas, dispense a barra.',
   },
   'progress': {
     name: 'progress',

package/src/ui/react.tsx

@@ -47,6 +47,11 @@ export { Label } from './components/primitives/label.tsx'
 export { Badge, badgeVariants } from './components/primitives/badge.tsx'
 export type { BadgeProps } from './components/primitives/badge.tsx'
 
+export { DictionaryValue } from './components/primitives/dictionary-value.tsx'
+export { EmptyValue, isAbsentValue } from './components/primitives/empty-value.tsx'
+export type { EmptyValueProps } from './components/primitives/empty-value.tsx'
+export type { DictionaryValueProps, DictionaryValueSource } from './components/primitives/dictionary-value.tsx'
+
 export { DetailField, DetailGroup } from './components/primitives/detail.tsx'
 export type {
   DetailFieldProps,
@@ -172,6 +177,7 @@ export { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from './comp
 export { Item, ItemActions, ItemContent, ItemDescription, ItemFooter, ItemGroup, ItemHeader, ItemMedia, ItemSeparator, ItemTitle } from './components/primitives/item.tsx'
 export { Kbd, KbdGroup } from './components/primitives/kbd.tsx'
 export { Pagination, PaginationContent, PaginationEllipsis, PaginationItem, PaginationLink, PaginationNext, PaginationPrevious } from './components/primitives/pagination.tsx'
+export type { PaginationLinkProps, PaginationControlProps } from './components/primitives/pagination.tsx'
 export { Progress } from './components/primitives/progress.tsx'
 export { RadioGroup, RadioGroupItem } from './components/primitives/radio-group.tsx'
 export { ScrollArea, ScrollBar } from './components/primitives/scroll-area.tsx'