Quote Table

Quando usar

Use a QuoteTable para o painel de cotacoes de um terminal de operacoes: um ativo por linha, com o ultimo preco negociado, a ponta de compra e venda e a variacao do dia. E o componente certo quando o operador precisa comparar varios ativos ao mesmo tempo e reagir a mudanca de preco em tempo real.

Nao e uma tabela genérica com uma coluna colorida: ela existe porque cotacao tem exigencia propria que uma Table comum nao cobre sozinha, entre elas fonte monoespacada obrigatoria em todo numero (para o digito nao "tremer" a cada tick) e a regra de que verde e vermelho aqui sao sempre preco (alta e baixa), nunca os tokens de sucesso e erro do produto.

Quando nao usar

Nao use QuoteTable para historico de negociacos ja fechados (isso e mais proximo de OrderTable ou de uma tabela comum com Table) nem para series de tempo (isso e grafico, nao tabela). Se o painel mostra so um ativo com detalhe grande, um cartao com Card comunica melhor do que uma tabela de uma linha so.

Anatomia

QuoteTable e um componente fechado: recebe rows e desenha a tabela inteira por dentro, compondo Table, TableHeader, TableBody, TableRow, TableHead, TableCell e Badge do proprio TRDR UI. Isso e proposital, ao contrario de Table (que e uma composicao aberta), cotacao tem um numero fixo de colunas com semantica propria (preco, variacao, tendencia), entao faz mais sentido o componente conhecer essa semantica do que o consumidor remontar tudo toda vez.

• Coluna Ativo: codigo do papel, texto comum.
• Coluna Ultimo: ultimo preco negociado. Recebe fundo proprio (surface-primary), para se destacar das demais colunas de preco (compra, venda, teorico), igual ao legado.
• Coluna Q. Ultimo: quantidade do ultimo negocio.
• Coluna Var. %: variacao percentual do dia, colorida (context-trading-up/down) e com sinal explicito (+1,20%/-0,72%). A cor nunca e a unica pista.
• Coluna Tend.: triangulo (▲/▼) que reforca visualmente o sentido da variacao, com um rotulo ("alta"/"baixa") so para leitor de tela.
• Coluna Dif.: diferenca de preco em relacao ao fechamento anterior.
• Coluna Status: rotulo textual (leilao, fechado...) dentro de um Badge neutral. So aparece quando a linha tem status.
• Colunas Q. Compra / Compra / Venda / Q. Venda: a ponta de oferta, quantidade e preco de compra e de venda.
• Coluna Teorico: preco teorico, usado em leilao.

Todas as colunas numericas usam a variante numeric de TableCell (font-mono, alinhado a direita). Nenhum numero desta tabela usa fonte proporcional.

API

interface QuoteRow {
  id: string
  symbol: string
  last: number
  lastQty?: number
  changePercent: number
  trend?: "up" | "down"
  diff?: number
  status?: string
  bidQty?: number
  bid?: number
  ask?: number
  askQty?: number
  theoretical?: number
}

interface QuoteTableProps {
  rows: QuoteRow[]
  columns?: QuoteTableColumnKey[] // quais colunas aparecem, em que ordem. Padrao: todas.
  selectedId?: string | null // selecao controlada
  onRowSelect?: (row: QuoteRow) => void
  caption: string // nome acessivel da tabela, obrigatorio
  emptyMessage?: React.ReactNode
  formatPrice?: (value: number) => string
  formatQuantity?: (value: number) => string
  formatPercent?: (value: number) => string
}

• Colunas configuraveis: columns e um array de chaves (QuoteTableColumnKey) na ordem desejada. Passar um subconjunto (["symbol", "last", "changePercent"]) mostra so essas tres, na ordem dada.
• Dado tipado, sem exemplo embutido: rows e QuoteRow[], o consumidor sempre traz os proprios dados. O componente nao guarda nenhuma linha de exemplo por dentro (o exemplo vive so no arquivo de demonstracao).
• Selecao controlada: selectedId + onRowSelect seguem o mesmo padrao de outros componentes controlados do React: o estado mora no consumidor, o componente so avisa a intencao de selecionar. A linha selecionada usa o data-state="selected" que a Table ja entende (mesmo destaque de fundo que qualquer outra linha selecionada do design system). Quando onRowSelect nao e passado, a linha nao vira alvo de clique nem de foco.
• Formatadores substituiveis: formatPrice/formatQuantity/formatPercent tem um padrao em pt-BR, mas cada instrumento pode ter casas decimais ou tick diferente, entao ficam substituiveis.

Migracao do componente legado

O TabelaCotacoes do Hub antigo (src/components/ui/TabelaCotacoes.tsx) recebia um array rows com nomes de campo em portugues (ativo, ultimo, varPct, qOfc, ofc...) e vinha com sete linhas de exemplo embutidas como valor padrao da prop, entao renderizava dado falso se ninguem passasse rows. O QuoteTable do TRDR UI:

• Usa nomes de campo em ingles (symbol, last, changePercent, bidQty, bid...): e a convencao do restante da biblioteca. Os rotulos em portugues (Ativo, Ultimo...) sao controlados pelo componente e aparecem so no cabecalho.
• Nao tem dado de exemplo embutido: rows e obrigatorio.
• Ganha columns para escolher e ordenar colunas, algo que o legado nao tinha (o legado sempre desenhava as doze colunas fixas).
• Troca o Badge success/warning do legado na coluna de variacao (que misturava o vocabulario de estado do produto com preco) por texto colorido com context-trading-up/down, que e o token correto para essa semantica.
• Formaliza a selecao de linha: o legado tinha uma prop solta selected por linha; agora e selectedId (controlado, uma unica fonte de verdade) mais onRowSelect.

Acessibilidade

• caption e obrigatorio e vira um <caption> visualmente oculto (sr-only): a tabela sempre tem nome acessivel, mesmo quando o titulo visivel vive fora dela no layout da pagina.
• Todo <th> usa scope="col".
• A variacao (alta/baixa) nunca depende so da cor: o sinal (+/-) no proprio numero e o triangulo da coluna Tend. (com rotulo "alta"/"baixa" para leitor de tela) carregam o significado, a cor e reforco.
• Quando onRowSelect esta presente, a linha vira alvo de teclado (tabIndex=0) e responde a Enter e Espaco, alem do clique.