@orbe-agro/client-core 5.6.239 → 5.6.241

package/lib/@ecme/services/sseParser.ts

@@ -0,0 +1,75 @@
+/**
+ * Parser de Server-Sent Events sobre um ReadableStream.
+ *
+ * O EventSource nativo do browser nao serve aqui: ele so faz GET e nao aceita
+ * headers, e o chat e um POST autenticado. Entao lemos o corpo do `fetch` na
+ * mao.
+ *
+ * Duas bordas do protocolo que uma implementacao ingenua erra:
+ *
+ * 1. um chunk da rede pode cortar um evento no meio — por isso o resto fica no
+ *    buffer ate chegar o proximo `\n\n`;
+ * 2. um chunk pode trazer varios eventos de uma vez.
+ */
+
+export type SseEvent = {
+    event: string
+    data: string
+}
+
+const SEPARADOR = /\r?\n\r?\n/
+
+/** Le o stream ate o fim, chamando `onEvent` a cada evento completo. */
+export async function readSse(
+    body: ReadableStream<Uint8Array>,
+    onEvent: (evento: SseEvent) => void,
+): Promise<void> {
+    const reader = body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+
+    try {
+        for (;;) {
+            const { done, value } = await reader.read()
+
+            if (done) {
+                // O ultimo evento pode nao vir seguido de linha em branco.
+                emitir(buffer, onEvent)
+                return
+            }
+
+            buffer += decoder.decode(value, { stream: true })
+
+            const blocos = buffer.split(SEPARADOR)
+            // O ultimo pedaco pode estar incompleto: volta para o buffer.
+            buffer = blocos.pop() ?? ''
+            blocos.forEach((bloco) => emitir(bloco, onEvent))
+        }
+    } finally {
+        reader.releaseLock()
+    }
+}
+
+/** Converte um bloco "event: x\ndata: y" em SseEvent. */
+function emitir(bloco: string, onEvent: (evento: SseEvent) => void) {
+    if (!bloco.trim()) {
+        return
+    }
+
+    let event = 'message'
+    const dados: string[] = []
+
+    bloco.split(/\r?\n/).forEach((linha) => {
+        if (linha.startsWith('event:')) {
+            event = linha.slice(6).trim()
+        } else if (linha.startsWith('data:')) {
+            // O espaco depois de "data:" e opcional no protocolo.
+            dados.push(linha.slice(5).replace(/^ /, ''))
+        }
+        // Linhas iniciadas por ":" sao comentarios (keep-alive) e sao ignoradas.
+    })
+
+    if (dados.length) {
+        onEvent({ event, data: dados.join('\n') })
+    }
+}

package/lib/@ecme/views/concepts/ai/Chat/components/AiErrorMessage.tsx

@@ -0,0 +1,28 @@
+import { TbPlugConnectedX } from 'react-icons/tb'
+
+/**
+ * Mensagem de erro do agente Orbe AI — exibida no lugar da resposta quando a
+ * comunicação com o serviço de IA falha, com acento vermelho para sinalizar
+ * o erro sem quebrar o tom visual do chat.
+ */
+const AiErrorMessage = () => {
+    return (
+        <span className="flex items-start gap-3">
+            <span className="mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-full bg-red-100 text-red-500 dark:bg-red-500/15 dark:text-red-400">
+                <TbPlugConnectedX size={18} />
+            </span>
+            <span className="flex flex-col gap-0.5">
+                <span className="text-sm font-semibold text-red-600 dark:text-red-400">
+                    Falha na comunicação
+                </span>
+                <span className="text-sm text-red-500/90 dark:text-red-300/90">
+                    Desculpe, estou com um pequeno problema de comunicação e
+                    não consigo te atender no momento. Tente novamente em
+                    instantes.
+                </span>
+            </span>
+        </span>
+    )
+}
+
+export default AiErrorMessage

package/lib/@ecme/views/concepts/ai/Chat/components/ApprovalCard.tsx

@@ -0,0 +1,103 @@
+import { useState } from 'react'
+import { TbLock } from 'react-icons/tb'
+import Button from '@/components/ui/Button'
+import { camposVisiveis, iconeFerramenta, rotularFerramenta } from './toolPresentation'
+import type { PendingApproval } from '../types'
+
+type ApprovalCardProps = {
+    approval: PendingApproval
+    onDecide: (approved: boolean) => void
+}
+
+/**
+ * Confirmacao de uma operacao que grava no ERP.
+ *
+ * O agente fica PARADO enquanto este card estiver na tela — so volta a
+ * responder depois do clique. Por isso ele nao usa a paleta de alerta: nao e um
+ * aviso de erro, e uma decisao de negocio que o usuario precisa tomar.
+ */
+const ApprovalCard = ({ approval, onDecide }: ApprovalCardProps) => {
+    const [decisao, setDecisao] = useState<'aprovar' | 'negar' | null>(null)
+
+    const decidir = (aprovado: boolean) => {
+        setDecisao(aprovado ? 'aprovar' : 'negar')
+        onDecide(aprovado)
+    }
+
+    return (
+        <div className="not-prose mt-1 overflow-hidden rounded-xl border border-gray-200 bg-white shadow-sm dark:border-gray-700 dark:bg-gray-800">
+            <div className="flex items-center gap-2 border-b border-gray-200 px-4 py-2.5 dark:border-gray-700">
+                <TbLock size={16} className="text-gray-400 dark:text-gray-500" />
+                <span className="text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">
+                    Confirmação necessária
+                </span>
+            </div>
+
+            <div className="px-4 py-3.5">
+                {approval.calls.map((call) => {
+                    const Icone = iconeFerramenta(call.name)
+                    const campos = camposVisiveis(call.args)
+
+                    return (
+                        <div key={call.id} className="mb-4 last:mb-0">
+                            <div className="mb-3 flex items-start gap-2.5">
+                                <span className="mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-lg bg-primary-subtle text-primary">
+                                    <Icone size={17} />
+                                </span>
+                                <div className="min-w-0">
+                                    <div className="font-semibold text-gray-900 dark:text-gray-100">
+                                        {rotularFerramenta(call.name)}
+                                    </div>
+                                    <div className="text-sm text-gray-500 dark:text-gray-400">
+                                        Revise os dados antes de confirmar.
+                                    </div>
+                                </div>
+                            </div>
+
+                            <dl className="divide-y divide-gray-100 rounded-lg border border-gray-100 dark:divide-gray-700 dark:border-gray-700">
+                                {campos.map((campo) => (
+                                    <div
+                                        key={campo.chave}
+                                        className="flex items-baseline justify-between gap-4 px-3 py-2"
+                                    >
+                                        <dt className="shrink-0 text-sm text-gray-500 dark:text-gray-400">
+                                            {campo.rotulo}
+                                        </dt>
+                                        <dd className="truncate text-sm font-medium text-gray-900 dark:text-gray-100">
+                                            {campo.valor}
+                                        </dd>
+                                    </div>
+                                ))}
+                            </dl>
+                        </div>
+                    )
+                })}
+
+                <div className="mt-4 flex items-center gap-2">
+                    <Button
+                        variant="solid"
+                        size="sm"
+                        loading={decisao === 'aprovar'}
+                        disabled={decisao !== null}
+                        onClick={() => decidir(true)}
+                    >
+                        Confirmar
+                    </Button>
+                    <Button
+                        size="sm"
+                        loading={decisao === 'negar'}
+                        disabled={decisao !== null}
+                        onClick={() => decidir(false)}
+                    >
+                        Cancelar
+                    </Button>
+                    <span className="ml-auto text-xs text-gray-400 dark:text-gray-500">
+                        Nada é gravado até você confirmar
+                    </span>
+                </div>
+            </div>
+        </div>
+    )
+}
+
+export default ApprovalCard

package/lib/@ecme/views/concepts/ai/Chat/components/ChatView.tsx

@@ -6,15 +6,35 @@ import ChatMobileNav from './ChatMobileNav'
 import ChatCustomContent from './ChatCustomContent'
 import ChatCustomAction from './ChatCustomAction'
 import AiThinkingIndicator from './AiThinkingIndicator'
+import AiErrorMessage from './AiErrorMessage'
+import ToolCallChip from './ToolCallChip'
+import ApprovalCard from './ApprovalCard'
 import { usGenerativeChatStore } from '../store/generativeChatStore'
 import useChatSend from '../hooks/useChatSend'
+import type { Conversation } from '../types'
 import type { ScrollBarRef } from '@/components/ui/ScrollBar'
 
+/**
+ * O balao de fala do agente, desenhado aqui em vez de vir do ChatBox.
+ *
+ * O `botBubbleClass` abaixo zera o balao que o Message desenharia, para os chips
+ * de ferramenta e o card de aprovacao ficarem FORA dele — antes tudo dividia a
+ * mesma caixa cinza e as ferramentas eram lidas como uma segunda mensagem.
+ * Usado tambem pelo indicador de "pensando", que passa pelo mesmo balao zerado.
+ *
+ * Repete `prose text-sm` do balao original de proposito: o reset de margem do
+ * @tailwindcss/typography e `.prose > :first-child`, filho DIRETO. Sem o `prose`
+ * aqui, o markdown ficaria um nivel abaixo do container e o primeiro paragrafo
+ * voltaria a ter margem, inflando todos os baloes.
+ */
+const BALAO_AGENTE =
+    'prose rounded-xl bg-gray-100 px-5 py-2.5 text-sm text-gray-900 dark:bg-gray-700 dark:text-gray-100'
+
 const ChatView = () => {
     const scrollRef = useRef<ScrollBarRef>(null)
     const { selectedConversation, chatHistory, isTyping, disabledChatFresh } =
         usGenerativeChatStore()
-    const { handleSend } = useChatSend()
+    const { handleSend, handleApproval } = useChatSend()
 
     const scrollToBottom = () => {
         if (scrollRef.current?.getScrollElement) {
@@ -61,7 +81,13 @@ const ChatView = () => {
                 showAvatar={false}
                 avatarGap={false}
                 myBubbleClass="bg-primary text-white"
-                renderTyping={() => <AiThinkingIndicator />}
+                botBubbleClass="bg-transparent dark:bg-transparent p-0 rounded-none"
+                errorBubbleClass="bg-red-50 dark:bg-red-500/10 border border-red-200 dark:border-red-500/20"
+                renderTyping={() => (
+                    <div className={BALAO_AGENTE}>
+                        <AiThinkingIndicator />
+                    </div>
+                )}
                 containerClass="h-[calc(100%-30px)] xl:h-full"
                 messageListClass="h-[calc(100%-100px)] xl:h-[calc(100%-70px)]"
                 typing={
@@ -74,22 +100,60 @@ const ChatView = () => {
                         : false
                 }
                 customRenderer={(message) => {
+                    if (message.isError) {
+                        return <AiErrorMessage />
+                    }
+
                     if (message.sender.id === 'ai') {
+                        // As ferramentas e a aprovacao chegam pelo streaming e
+                        // vivem no Conversation; o tipo do ChatBox nao os conhece.
+                        const { tools, pendingApproval } = message as Conversation
+                        // Enquanto as ferramentas rodam o conteudo ainda e '':
+                        // sem esta guarda sobraria um balao cinza vazio.
+                        const temTexto = Boolean(
+                            (message.content as string)?.trim(),
+                        )
+
                         return (
-                            <ChatCustomContent
-                                content={message.content as string}
-                                triggerTyping={
-                                    message.fresh ? message.fresh : false
-                                }
-                                onFinish={() => handleFinish(message.id)}
-                            />
+                            <div className="flex flex-col items-start gap-1.5">
+                                {tools?.map((tool) => (
+                                    <ToolCallChip key={tool.id} tool={tool} />
+                                ))}
+                                {temTexto && (
+                                    <div className={BALAO_AGENTE}>
+                                        <ChatCustomContent
+                                            content={message.content as string}
+                                            triggerTyping={
+                                                message.fresh
+                                                    ? message.fresh
+                                                    : false
+                                            }
+                                            onFinish={() =>
+                                                handleFinish(message.id)
+                                            }
+                                        />
+                                    </div>
+                                )}
+                                {pendingApproval && (
+                                    <ApprovalCard
+                                        approval={pendingApproval}
+                                        onDecide={(aprovado) =>
+                                            handleApproval(
+                                                selectedConversation,
+                                                message.id,
+                                                aprovado,
+                                            )
+                                        }
+                                    />
+                                )}
+                            </div>
                         )
                     }
 
                     return message.content
                 }}
                 customAction={(message) => {
-                    if (message.sender.id === 'ai') {
+                    if (message.sender.id === 'ai' && !message.isError) {
                         return (
                             <ChatCustomAction
                                 content={message.content as string}

package/lib/@ecme/views/concepts/ai/Chat/components/ToolCallChip.tsx

@@ -0,0 +1,218 @@
+import { useState } from 'react'
+import {
+    TbAlertTriangle,
+    TbCheck,
+    TbChevronDown,
+    TbClock,
+    TbLoader2,
+} from 'react-icons/tb'
+import classNames from '@/components/ui/utils/classNames'
+import {
+    camposVisiveis,
+    iconeFerramenta,
+    rotularExecucao,
+    rotularFerramenta,
+} from './toolPresentation'
+import type { ToolCall } from '../types'
+
+/**
+ * Uma consulta ou operacao que o agente executou, no meio da conversa.
+ *
+ * Deliberadamente discreto: e informacao de apoio, nao a resposta. Por isso vive
+ * FORA do balao de fala (ver ChatView) e tem forma de pilula — contorno fino,
+ * largura do conteudo, letra menor — para nunca ser lido como uma segunda
+ * mensagem do agente. Fechado mostra so o que aconteceu e em que estado esta;
+ * aberto, os parametros ja traduzidos para a linguagem do negocio.
+ */
+
+type Estado = {
+    texto: string
+    Icone: typeof TbCheck
+    classe: string
+    /**
+     * Se o texto do estado acompanha o icone na pilula.
+     *
+     * So quando o icone sozinho nao basta: "aguardando confirmacao" e "nao
+     * concluida" pedem uma acao ou explicam uma falha. Em execucao o rotulo ja
+     * esta no gerundio ("Consultando contratos…") e o ✓ de concluida e obvio —
+     * escrever isso de novo so engorda a pilula.
+     */
+    mostrarTexto?: boolean
+}
+
+const estadoDe = (tool: ToolCall): Estado => {
+    if (tool.awaitingApproval) {
+        return {
+            texto: 'Aguardando confirmação',
+            Icone: TbClock,
+            classe: 'text-amber-600 dark:text-amber-400',
+            mostrarTexto: true,
+        }
+    }
+    if (tool.running) {
+        return {
+            texto: 'Em andamento',
+            Icone: TbLoader2,
+            classe: 'text-blue-600 dark:text-blue-400',
+        }
+    }
+    if (tool.isError) {
+        return {
+            texto: 'Não concluída',
+            Icone: TbAlertTriangle,
+            classe: 'text-red-600 dark:text-red-400',
+            mostrarTexto: true,
+        }
+    }
+    return {
+        texto: 'Concluída',
+        Icone: TbCheck,
+        classe: 'text-emerald-600 dark:text-emerald-400',
+    }
+}
+
+type ToolCallChipProps = {
+    tool: ToolCall
+}
+
+const ToolCallChip = ({ tool }: ToolCallChipProps) => {
+    const [aberto, setAberto] = useState(false)
+    const estado = estadoDe(tool)
+    const IconeFerramenta = iconeFerramenta(tool.name)
+    const emAndamento = tool.running && !tool.awaitingApproval
+    const campos = camposVisiveis(tool.args)
+    const rotulo = emAndamento
+        ? `${rotularExecucao(tool.name)}…`
+        : rotularFerramenta(tool.name)
+
+    return (
+        // not-prose: o balao do agente e `prose`, que aplicaria margens de
+        // tipografia no dl/dt/dd/pre daqui e desmontaria a compactacao.
+        <div className="not-prose max-w-full">
+            <button
+                type="button"
+                className="inline-flex w-fit max-w-full items-center gap-1.5 rounded-full border border-gray-200 px-2.5 py-1 text-left transition-colors hover:border-gray-300 hover:bg-gray-50 dark:border-gray-700 dark:hover:border-gray-600 dark:hover:bg-gray-800/60"
+                aria-expanded={aberto}
+                title={`${rotulo} — ${estado.texto}`}
+                onClick={() => setAberto((atual) => !atual)}
+            >
+                <IconeFerramenta
+                    size={13}
+                    className="shrink-0 text-gray-400 dark:text-gray-500"
+                />
+
+                <span className="truncate text-xs font-medium text-gray-600 dark:text-gray-300">
+                    {rotulo}
+                </span>
+
+                <span
+                    className={classNames(
+                        'flex shrink-0 items-center gap-1 text-xs font-medium',
+                        estado.classe,
+                    )}
+                >
+                    <estado.Icone
+                        size={12}
+                        className={emAndamento ? 'motion-safe:animate-spin' : ''}
+                    />
+                    {estado.mostrarTexto && estado.texto}
+                </span>
+
+                <TbChevronDown
+                    size={12}
+                    className={classNames(
+                        'shrink-0 text-gray-400 transition-transform',
+                        aberto && 'rotate-180',
+                    )}
+                />
+            </button>
+
+            {aberto && (
+                <div className="mt-1 rounded-lg border border-gray-200 px-2.5 py-2 dark:border-gray-700">
+                    {campos.length > 0 && (
+                        <dl className="grid grid-cols-[minmax(0,auto)_minmax(0,1fr)] gap-x-3 gap-y-1 text-xs">
+                            {campos.map((campo) => (
+                                <div key={campo.chave} className="contents">
+                                    <dt className="text-gray-500 dark:text-gray-400">
+                                        {campo.rotulo}
+                                    </dt>
+                                    <dd className="truncate font-medium text-gray-800 dark:text-gray-100">
+                                        {campo.valor}
+                                    </dd>
+                                </div>
+                            ))}
+                        </dl>
+                    )}
+
+                    {tool.result !== undefined && (
+                        <Resultado
+                            texto={tool.result}
+                            erro={tool.isError}
+                            separar={campos.length > 0}
+                        />
+                    )}
+                </div>
+            )}
+        </div>
+    )
+}
+
+/**
+ * O retorno da ferramenta.
+ *
+ * Quando e JSON (uma listagem, por exemplo), fica atras de um toggle: e dado
+ * tecnico que so interessa para conferencia, e o usuario ja tem a resposta do
+ * agente logo abaixo. Mensagens em texto — erros de permissao, cancelamentos —
+ * aparecem direto, porque explicam o que aconteceu.
+ */
+const Resultado = ({
+    texto,
+    erro,
+    separar,
+}: {
+    texto: string
+    erro?: boolean
+    /** Linha divisoria: so faz sentido quando ha parametros logo acima. */
+    separar?: boolean
+}) => {
+    const [mostrarBruto, setMostrarBruto] = useState(false)
+    const ehJson = /^\s*[[{]/.test(texto)
+    const separador = separar
+        ? 'mt-2 border-t border-gray-200 pt-2 dark:border-gray-700'
+        : ''
+
+    if (!ehJson) {
+        return (
+            <p
+                className={classNames(
+                    'text-xs',
+                    separador,
+                    erro
+                        ? 'text-red-600 dark:text-red-400'
+                        : 'text-gray-600 dark:text-gray-300',
+                )}
+            >
+                {texto}
+            </p>
+        )
+    }
+
+    return (
+        <div className={separador}>
+            <button
+                type="button"
+                className="text-xs font-medium text-gray-500 underline-offset-2 hover:underline dark:text-gray-400"
+                onClick={() => setMostrarBruto((atual) => !atual)}
+            >
+                {mostrarBruto ? 'Ocultar' : 'Ver'} dados retornados
+            </button>
+            {mostrarBruto && (
+                <pre className="mt-1.5 max-h-40 overflow-auto whitespace-pre-wrap break-words rounded border border-gray-200 bg-white p-2 text-xs text-gray-600 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-300">
+                    {texto}
+                </pre>
+            )}
+        </div>
+    )
+}
+
+export default ToolCallChip

package/lib/@ecme/views/concepts/ai/Chat/components/toolPresentation.ts

@@ -0,0 +1,137 @@
+import { formatQuantity } from '@base/utils/functions/stringUtils'
+import { TbFilePlus, TbListSearch, TbSearch, TbTool } from 'react-icons/tb'
+import type { IconType } from 'react-icons'
+
+/**
+ * Como as ferramentas do agente sao apresentadas ao usuario.
+ *
+ * Compartilhado pelo chip de execucao e pelo card de aprovacao, para os dois
+ * falarem a mesma lingua: o usuario ve "Consulta de contratos" e "Mercado
+ * interno", nunca `listar_contratos_armazenagem_graos` ou `MERCADO_INTERNO`.
+ *
+ * Tudo tem fallback: uma ferramenta ou campo novo no backend nao quebra a tela,
+ * so aparece com o nome tecnico humanizado ate ganhar entrada aqui.
+ */
+
+type Ferramenta = {
+    rotulo: string
+    /** Frase no gerundio, para o estado "executando". */
+    executando: string
+    icone: IconType
+}
+
+const FERRAMENTAS: Record<string, Ferramenta> = {
+    buscar_contrato_armazenagem_graos: {
+        rotulo: 'Consulta de contrato',
+        executando: 'Consultando contrato',
+        icone: TbSearch,
+    },
+    listar_contratos_armazenagem_graos: {
+        rotulo: 'Consulta de contratos',
+        executando: 'Consultando contratos',
+        icone: TbListSearch,
+    },
+    criar_contrato_armazenagem_graos: {
+        rotulo: 'Criação de contrato de armazenagem',
+        executando: 'Criando contrato',
+        icone: TbFilePlus,
+    },
+}
+
+const humanizar = (texto: string) =>
+    texto
+        .replaceAll('_', ' ')
+        .toLowerCase()
+        .replace(/^./, (letra) => letra.toUpperCase())
+
+export const rotularFerramenta = (nome: string) =>
+    FERRAMENTAS[nome]?.rotulo ?? humanizar(nome)
+
+export const rotularExecucao = (nome: string) =>
+    FERRAMENTAS[nome]?.executando ?? humanizar(nome)
+
+export const iconeFerramenta = (nome: string): IconType =>
+    FERRAMENTAS[nome]?.icone ?? TbTool
+
+/** Rotulos dos parametros, na linguagem do negocio. */
+const CAMPOS: Record<string, string> = {
+    business_partner_id: 'Parceiro de negócio',
+    produto_id: 'Produto',
+    safra_id: 'Safra',
+    saldo_negociado: 'Saldo negociado',
+    tipo_contrato: 'Tipo de contrato',
+    contrato_venda: 'Contrato de venda',
+    ordem_venda: 'Ordem de venda',
+    id: 'Contrato',
+    page_number: 'Página',
+    page_size: 'Itens por página',
+    sort_field: 'Ordenar por',
+    sort_order: 'Ordem',
+    filtro: 'Filtro',
+}
+
+export const rotularCampo = (chave: string) => CAMPOS[chave] ?? humanizar(chave)
+
+/** Campos que sao referencia a um registro: exibidos como "#123". */
+const REFERENCIAS = new Set([
+    'business_partner_id',
+    'produto_id',
+    'safra_id',
+    'contrato_venda',
+    'ordem_venda',
+    'id',
+])
+
+const ORDENACAO: Record<string, string> = { ASC: 'Crescente', DESC: 'Decrescente' }
+
+/** Converte o valor tecnico no que o usuario espera ler. */
+export const formatarValor = (chave: string, valor: unknown): string => {
+    if (valor === null || valor === undefined || valor === '') {
+        return '—'
+    }
+    if (chave === 'saldo_negociado' && typeof valor === 'number') {
+        return formatQuantity(valor)
+    }
+    if (chave === 'sort_order' && typeof valor === 'string') {
+        return ORDENACAO[valor] ?? humanizar(valor)
+    }
+    if (typeof valor === 'number') {
+        return REFERENCIAS.has(chave) ? `#${valor}` : String(valor)
+    }
+    if (typeof valor === 'boolean') {
+        return valor ? 'Sim' : 'Não'
+    }
+    if (typeof valor === 'string') {
+        // Enums do backend chegam em CAIXA_ALTA_COM_UNDERSCORE.
+        return /^[A-Z][A-Z0-9_]+$/.test(valor) ? humanizar(valor) : valor
+    }
+    if (Array.isArray(valor)) {
+        return valor.length ? `${valor.length} item(ns)` : '—'
+    }
+    if (typeof valor === 'object') {
+        const entradas = Object.entries(valor as Record<string, unknown>)
+        if (!entradas.length) {
+            return '—'
+        }
+        return entradas
+            .map(([k, v]) => `${rotularCampo(k)}: ${formatarValor(k, v)}`)
+            .join(', ')
+    }
+    return String(valor)
+}
+
+/** Pares (rotulo, valor) prontos para exibir, ignorando o que esta vazio. */
+export const camposVisiveis = (args: Record<string, unknown>) =>
+    Object.entries(args)
+        .filter(([, valor]) => {
+            if (valor === null || valor === undefined || valor === '') return false
+            if (typeof valor === 'object' && !Array.isArray(valor)) {
+                return Object.keys(valor as object).length > 0
+            }
+            return true
+        })
+        .map(([chave, valor]) => ({
+            chave,
+            rotulo: rotularCampo(chave),
+            valor: formatarValor(chave, valor),
+        }))