Communitygithub.com

chambaz/solanaui

Integra componentes SolanaUI em aplicativos Solana. Use ao construir interfaces de swap, páginas de perpétuos, painéis de empréstimo, marketplaces de NFT, visualizações de portfólio, páginas de staking ou qualquer UI DeFi Solana. Fornece 30 componentes React prontos para produção com props TypeScript, padrões de layout e orientação de integração.

O que é solanaui?

SolanaUI é uma biblioteca de componentes React focada em Solana, construída sobre shadcn/ui, Radix UI e Tailwind CSS. Ela oferece 30 componentes prontos para produção, todos puramente apresentacionais: aceitam dados via props e emitem callbacks, sem dependências de blockchain, wallets ou SDKs. Isso significa que os componentes lidam exclusivamente com a camada de UI (renderização de ícones de tokens, formatação de preços, exibição de tabelas e gráficos), enquanto o desenvolvedor gerencia a lógica de dados, conexões de carteira e transações. A biblioteca suporta integração com shadcn/ui via registro personalizado e cobre uma ampla gama de casos de uso DeFi, como formulários de swap (SwapBox), ordens de perpétuos (TradeBox), livros de ordens (OrderBook), tabelas de posições (PositionTable), gráficos de velas (TradeChart) e muito mais. Projetada para a plataforma Solana, ela é agnóstica em relação a fontes de dados, funcionando tanto em aplicações com dados on-chain quanto off-chain.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add chambaz/solanaui

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que solanaui faz?

Uma biblioteca de componentes React focada em Solana, construída sobre shadcn/ui, Radix UI e Tailwind CSS. Todos os componentes são apresentacionais – eles aceitam dados via props e emitem callbacks. Não possuem dependências de blockchain, adaptadores de wallet ou importações de SDK. Você os conecta à sua própria camada de dados.

Quando Usar

Use os componentes SolanaUI ao construir interfaces de aplicativos Solana. Os componentes cuidam da camada de UI – renderizando ícones de tokens, formatando preços, exibindo tabelas e gráficos – enquanto seu código gerencia a busca de dados, conexões de wallet e lógica de transações.

Integração típica: busque dados da sua API ou fonte on-chain, transforme-os para corresponder à interface de props do componente e passe-os. Conecte-se aos callbacks (onSubmit, onSelect, onValueChange) para acionar sua lógica de aplicação.

Instalação

Requer que o shadcn/ui esteja inicializado no seu projeto (components.json deve existir). Se não, execute pnpm dlx shadcn@latest init primeiro.

Adicione o registro SolanaUI ao seu components.json:

{
  "registries": {
    "@solanaui": "https://solanaui.dev/r/{name}.json"
  }
}

Em seguida, instale os componentes:

pnpm dlx shadcn@latest add @solanaui/swap-box

Quaisquer primitivas shadcn/ui necessárias (Card, Dialog, Button, etc.) são resolvidas automaticamente como dependências do registro. Os componentes também dependem do utilitário cn() de @/lib/utils.

Convenções de Importação

import { SwapBox } from "@/components/sol/swap-box";
import { PoolTable } from "@/components/sol/pool-table";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Button } from "@/components/ui/button";

Padrões de Integração

Conectando a Fontes de Dados

Os componentes aceitam dados simples via props. Mapeie seus dados para as formas das props:

// Sua fonte de dados (API, on-chain, gerenciamento de estado, etc.)
const positions = usePositions(); // seu hook

// Mapeie para a forma da prop do componente
<PositionTable
  positions={positions.map(p => ({
    symbol: p.market.baseSymbol,
    icon: p.market.baseIconUrl,       // use suas próprias URLs de ícone
    side: p.direction,
    size: formatNumber(p.size),
    value: formatUsd(p.notionalValue),
    leverage: `${p.leverage}x`,
    entryPrice: formatUsd(p.entryPrice),
    markPrice: formatUsd(p.currentPrice),
    pnl: formatPnl(p.unrealizedPnl),
    pnlPercent: formatPercent(p.unrealizedPnlPercent),
    pnlTrend: p.unrealizedPnl >= 0 ? "up" : "down",
  }))}
  onClosePosition={(pos) => closePosition(pos.symbol)}
  onEditTpSl={(pos, values) => updateTpSl(pos.symbol, values)}
/>

Ícones de Token

Os componentes aceitam URLs de ícone como strings. Use qualquer fonte de ícone que seu projeto já tenha – seu próprio CDN, registro de tokens ou serviço de metadados.

Se você precisar de ícones de placeholder para prototipagem, estas URLs públicas de CDN funcionam:

  • SOL: https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png
  • USDC: https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/logo.png
  • BONK: https://arweave.net/hQiPZOsRZXGXBJd_82PhVdlM_hACsT_q6wqwf5cSY7I
  • JitoSOL: https://storage.googleapis.com/token-metadata/JitoSOL-256.png
  • mSOL: https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/mSoLzYCxHdYgdzU16g5QSh3i5K3z3KZK7ytfqcJm7So/logo.png

Manipulando Callbacks

Os componentes emitem callbacks para ações do usuário. Conecte-os à sua lógica de aplicação:

<SwapBox
  tokens={availableTokens}
  defaultFromToken="USDC"
  defaultToToken="SOL"
  fromBalance={wallet.usdcBalance}
  details={quoteDetails}
  submitLabel="Swap"
  // Sua lógica de execução de swap
  onSubmit={() => executeSwap(fromToken, toToken, amount)}
/>

<ActionBox
  tokens={supportedTokens}
  label="Stake"
  balance={wallet.solBalance}
  details={stakingDetails}
  submitLabel="Stake SOL"
  onSubmit={() => submitStakeTransaction(selectedToken, amount)}
/>

Catálogo de Componentes (30 componentes)

ActionBox (action-box)

Formulário de ação de entrada única para staking, empréstimo, depósito em LP, bridging. A contraparte versátil do TradeBox.

interface ActionBoxProps {
  tokens: { icon: string; symbol: string }[];
  defaultToken?: string;
  balance?: string;
  label?: string;
  details?: { label: string; value: string; className?: string }[];
  submitLabel?: string;
  onSubmit?: () => void;
  className?: string;
}

ActivityFeed (activity-feed)

Lista cronológica de atividades com ícones, timestamps (objetos Date) e valores. Usa date-fns formatDistanceToNow para tempo relativo.

interface ActivityFeedProps {
  items: { icon?: string; title: string; description?: string; timestamp: Date; value?: string }[];
  className?: string;
}

AddressDisplay (address-display)

Endereço Solana truncado com cópia para área de transferência e link opcional para explorador. explorerUrl é uma URL base; o endereço é anexado automaticamente.

interface AddressDisplayProps {
  address: string; truncate?: boolean; truncateChars?: [number, number];
  copyable?: boolean; explorerUrl?: string; className?: string;
}

AuthCard (auth-card)

Cartão de login com entrada de email opcional, botões de login social e botões de provedor de wallet.

interface AuthCardProps {
  title?: string; description?: string; showEmail?: boolean;
  socialProviders?: { name: string; icon: React.ReactNode }[];
  walletProviders?: { name: string; icon: React.ReactNode }[];
}

HealthBar (health-bar)

Barra de progresso gradiente (vermelho para verde) com valor percentual colorido.

interface HealthBarProps { value: number; label?: string; showValue?: boolean; className?: string }

LeverageSlider (leverage-slider)

Slider para selecionar alavancagem de negociação com botões de atalho min/máx.

interface LeverageSliderProps {
  min?: number; max?: number; step?: number; value?: number[];
  defaultValue?: number[]; onValueChange?: (value: number[]) => void; className?: string;
}

NFTCard (nft-card)

Cartão exibindo imagem, nome, coleção e preço do NFT com estados de carregamento/erro.

interface NFTCardProps {
  name: string; image: string; collection?: string;
  price?: string; currency?: string; className?: string;
}

OrderBook (order-book)

Livro de ordens de negociação com níveis de oferta/demanda, tamanhos, totais acumulados, spread, preço médio e barras de profundidade.

interface OrderBookProps {
  bids: { price: number; size: number }[];
  asks: { price: number; size: number }[];
  className?: string;
}

OrderForm (order-form)

Formulário de ordens TP/SL para posições abertas. Entradas duplas de TP (preço + % de ganho), entradas duplas de SL (preço + % de perda). Passe entryPrice para sincronizar automaticamente entre campos de preço e percentual.

interface OrderFormProps {
  title?: string; description?: string; entryPrice?: number;
  details?: { label: string; value: string; className?: string }[];
  onSubmit?: (values: { tpPrice: string; tpPercent: string; slPrice: string; slPercent: string }) => void;
  className?: string;
}

PoolCard (pool-card)

Cartão versátil para pools de token único ou múltiplo. Mostra ícones empilhados, preço opcional, descrição, grade de métricas, gráfico sparkline e slot para filhos.

interface PoolCardProps {
  tokens: { icon: string; symbol: string }[]; name?: string; price?: string; description?: string;
  metrics?: { label: string; value: string; highlight?: boolean; className?: string }[];
  series?: { time: string; value: number }[]; children?: React.ReactNode; className?: string;
}

PoolTable (pool-table)

Tabela de dados com ícones de token (um ou mais por linha), colunas definidas pelo usuário, ordenável e ações de linha opcionais. Funciona para listagens de pool, tabelas de token, tabelas de validadores.

interface PoolTableProps {
  columns: { key: string; label: string; className?: string }[];
  rows: { icons: { src: string; alt?: string }[]; name?: string; data: Record<string, string> }[];
  actions?: React.ReactNode[]; className?: string;
}

PositionCard (position-card)

Cartão mostrando uma posição DeFi com ícone de token, valor, valor em USD, APY e rodapé de ação opcional.

interface PositionCardProps {
  symbol: string; icon: string; amount: string; value: string;
  apy?: string; trend?: "up" | "down"; children?: React.ReactNode; className?: string;
}

PositionTable (position-table)

Tabela de posições de negociação abertas com tipo (long/short), ícone do ativo, tamanho, alavancagem, preços de entrada/marcação e P&L colorido. Colunas de ação TP/SL editável e Fechar incorporadas com UIs de diálogo.

interface PositionTablePosition {
  symbol: string; icon: string; side: "long" | "short";
  size: string; value: string; leverage: string;
  entryPrice: string; markPrice: string; liquidationPrice?: string;
  pnl: string; pnlPercent?: string; pnlTrend?: "up" | "down";
}
interface PositionTableProps {
  positions: PositionTablePosition[];
  onEditTpSl?: (position: PositionTablePosition, values: { tpPrice: string; tpPercent: string; slPrice: string; slPercent: string }) => void;
  onClosePosition?: (position: PositionTablePosition) => void;
  className?: string;
}

PriceChart (price-chart)

Gráfico de área para histórico de preço de token ou valor de portfólio com eixos, grade, preenchimento gradiente e tooltips.

interface PriceChartProps {
  title?: string; description?: string;
  series: { time: string; value: number }[]; className?: string;
}

SparklineChart (sparkline-chart)

Sparkline inline mínimo com coloração automática positiva/negativa e rótulo de variação percentual.

interface SparklineChartProps { series: { time: string; value: number }[]; className?: string }

StatCard (stat-card)

Cartão de exibição de estatísticas com rótulo, valor, ícone opcional e badge de tendência opcional.

interface StatCardProps {
  label: string; value: string; change?: string;
  trend?: "up" | "down"; icon?: React.ReactNode; className?: string;
}

SwapBox (swap-box)

Formulário de swap de token de dois lados com botão de inversão, linhas de detalhes e ação de envio. O botão de inversão troca os tokens selecionados no lugar (os rótulos permanecem fixos).

interface SwapBoxProps {
  tokens: { icon: string; symbol: string }[];
  defaultFromToken?: string; defaultToToken?: string;
  fromBalance?: string; toBalance?: string; fromLabel?: string; toLabel?: string;
  details?: { label: string; value: string; className?: string }[];
  submitLabel?: string; onSubmit?: () => void; className?: string;
}

TokenCombobox (token-combobox)

Dropdown pesquisável para selecionar um token com ícones e seleção por checkmark.

interface TokenComboboxProps {
  tokens: { icon: string; symbol: string }[];
  defaultValue?: string; onSelect?: (token: { icon: string; symbol: string }) => void; className?: string;
}

TokenCommand (token-command)

Diálogo de comando Cmd+K para pesquisar e selecionar tokens. Passe tokens (lista plana) ou groups (seccionados), não ambos.

type TokenCommandProps = {
  onSelect?: (token: { icon: string; symbol: string }) => void; className?: string;
} & (
  | { tokens: { icon: string; symbol: string }[]; groups?: never }
  | { groups: { heading: string; tokens: { icon: string; symbol: string }[] }[]; tokens?: never }
)

TokenIcon (token-icon)

Imagem de ícone de token circular com skeleton de carregamento e fallback de erro.

type TokenIconProps = { src: string; alt: string; width?: number; height?: number; className?: string }

TokenIconGroup (token-icon-group)

Ícones de token sobrepostos empilhados para pares LP ou grupos de múltiplos tokens. Mostra badge +N quando excede o máximo.

interface TokenIconGroupProps {
  tokens: { src: string; alt?: string }[]; size?: number; overlap?: number; max?: number; className?: string;
}

TokenInput (token-input)

Entrada numérica com seletor de token integrado, saldo da wallet, botões Half/Max e exibição de valor em USD. Formata com separadores de milhar. onValueChange recebe a string bruta não formatada.

interface TokenInputProps {
  tokens: { icon: string; symbol: string }[]; defaultToken?: string; balance?: string;
  value?: string; usdValue?: string; onValueChange?: (value: string) => void;
  onTokenSelect?: (token: { icon: string; symbol: string }) => void; className?: string;
}

TradeBox (trade-box)

Formulário de negociação de perpétuos/margem com alternância long/short, entrada de token, slider de alavancagem, linhas de detalhes e envio. Para ações não comerciais, use ActionBox.

interface TradeBoxProps {
  tokens: { icon: string; symbol: string }[]; defaultToken?: string; balance?: string;
  labels?: [string, string]; defaultSide?: string;
  leverageMin?: number; leverageMax?: number; leverageDefault?: number; leverageStep?: number;
  details?: { label: string; value: string; className?: string }[];
  submitLabel?: string; onSubmit?: () => void; className?: string;
}

TradeButtons (trade-buttons)

Grupo de alternância para selecionar direção de negociação (Long/Short ou Buy/Sell) com estados codificados por cor.

interface TradeButtonsProps {
  defaultValue?: string; value?: string; onValueChange?: (value: string) => void;
  labels?: [string, string]; className?: string;
}

TradeChart (trade-chart)

Gráfico de velas alimentado por TradingView lightweight-charts com suporte a tema claro/escuro.

interface TradeChartProps {
  data: { time: string | number; open: number; high: number; low: number; close: number }[];
  visibleBars?: number; className?: string;
}

TrendBadge (trend-badge)

Badge pequeno colorido com ícone de tendência para mudanças positivas (verde) ou negativas (vermelho).

interface TrendBadgeProps { trend?: "up" | "down"; children: React.ReactNode; className?: string }

TxnTable (txn-table)

Tabela de transações com links de assinatura truncados, timestamps relativos (objetos Date, via date-fns), badges de ação e quantidades de tokens.

interface TxnTableProps {
  transactions: {
    signature: string; timestamp: Date; action: string; token: string;
    tokenIcon?: string; amount: string; value?: string; explorerUrl?: string;
  }[];
  className?: string;
}

VolumeChart (volume-chart)

Gráfico de barras para volume histórico de negociação com eixos, grade e tooltips. Dados de série temporal única com valores numéricos.

interface VolumeChartProps {
  title?: string; description?: string;
  series: { time: string; value: number }[]; className?: string;
}

WalletBalance (wallet-balance)

Cartão de saldo da wallet com ícone de token, saldo, valor em USD e botão de recarga.

interface WalletBalanceProps {
  icon: string; symbol: string; balance: string; value?: string;
  onRefresh?: () => void; className?: string;
}

Temas e Personalização

Os componentes herdam o tema global do shadcn/ui via CSS custom properties (variáveis CSS) definidas no seu globals.css. Para modificar o tema, edite essas variáveis -- os componentes as respeitam automaticamente.

Componentes de Grade

Para posicionar uniformemente os cartões de pool e ícones de token na sua página, use Tailwind:

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {pools.map(pool => <PoolCard key={pool.id} {...pool} />)}
</div>

Compatibilidade

  • Funciona com qualquer framework React (Next.js, Remix, Vite, etc.)
  • Íntegro com shadcn/ui e Radix UI
  • Funciona com qualquer solução de conexão Solana (Wallet Standard, Backpack, Phantom, Solflare, etc.)
  • Agnóstico de dados e estado
  • Pronto para TypeScript

Habilidades Relacionadas