Communitygithub.com

chambaz/solanaui

Integra componentes SolanaUI en aplicaciones Solana. Útil al construir interfaces de intercambio, páginas de trading de perpetuos, paneles de préstamos, mercados NFT, vistas de cartera, páginas de staking o cualquier UI DeFi en Solana. Proporciona 30 componentes React listos para producción con props TypeScript, patrones de diseño y guía de integración.

¿Qué es solanaui?

SolanaUI es una biblioteca de componentes React especializada para aplicaciones Solana, construida sobre shadcn/ui, Radix UI y Tailwind CSS. Ofrece 30 componentes presentacionales listos para producción que aceptan datos a través de props y emiten callbacks, sin dependencias de blockchain, adaptadores de wallet ni imports de SDK, lo que permite a los desarrolladores integrarlos con su propia capa de datos. Los componentes cubren una amplia gama de casos de uso DeFi, incluyendo formularios de intercambio (SwapBox), tablas de posiciones y pools, gráficos de velas y área, tarjetas NFT, indicadores de salud, sliders de apalancamiento y más. La instalación es sencilla a través del registro de shadcn/ui, y los componentes se integran mapeando datos de API o fuentes on-chain a las props del componente, conectando callbacks como onSubmit para la lógica de aplicación personalizada.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add chambaz/solanaui

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace solanaui?

Una biblioteca de componentes React enfocada en Solana, construida sobre shadcn/ui, Radix UI y Tailwind CSS. Todos los componentes son presentacionales: aceptan datos a través de props y emiten callbacks. No tienen dependencias de blockchain, adaptadores de wallet ni imports de SDK. Tú los conectas a tu propia capa de datos.

Cuándo usar

Usa los componentes de SolanaUI al construir interfaces de aplicaciones Solana. Los componentes manejan la capa de UI — renderizar íconos de tokens, formatear precios, mostrar tablas y gráficos — mientras que tu código se encarga de la obtención de datos, conexiones de wallet y lógica de transacciones.

Integración típica: obtén datos de tu API o fuente on-chain, transformalos para que coincidan con la interfaz de props del componente, pásalos. Conecta callbacks (onSubmit, onSelect, onValueChange) para activar tu lógica de aplicación.

Instalación

Requiere que shadcn/ui esté inicializado en tu proyecto (debe existir components.json). Si no, ejecuta primero pnpm dlx shadcn@latest init.

Agrega el registro de SolanaUI a tu components.json:

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

Luego instala componentes:

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

Cualquier primitiva necesaria de shadcn/ui (Card, Dialog, Button, etc.) se resuelve automáticamente como dependencia del registro. Los componentes también dependen de la utilidad cn() de @/lib/utils.

Convenciones de importación

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";

Patrones de integración

Conexión a fuentes de datos

Los componentes aceptan datos planos a través de props. Mapea tus datos a las formas de las props:

// Tu fuente de datos (API, on-chain, gestión de estado, etc.)
const positions = usePositions(); // tu hook

// Mapea a la forma de prop del componente
<PositionTable
  positions={positions.map(p => ({
    symbol: p.market.baseSymbol,
    icon: p.market.baseIconUrl,       // usa tus propias URL de íconos
    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)}
/>

Íconos de tokens

Los componentes aceptan URL de íconos como cadenas de texto. Usa cualquier fuente de íconos que tu proyecto ya tenga: tu propio CDN, registro de tokens o servicio de metadatos.

Si necesitas íconos de marcador de posición para prototipado, estas URL públicas de CDN funcionan:

  • 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

Manejo de callbacks

Los componentes emiten callbacks para acciones del usuario. Conéctalos a tu lógica de aplicación:

<SwapBox
  tokens={availableTokens}
  defaultFromToken="USDC"
  defaultToToken="SOL"
  fromBalance={wallet.usdcBalance}
  details={quoteDetails}
  submitLabel="Swap"
  // Tu lógica de ejecución de intercambio
  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)

Formulario de acción de una sola entrada para staking, préstamos, depósito en LP, puentes. La contraparte versátil de 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 de actividades cronológica con íconos, marcas de tiempo (objetos Date) y valores. Usa date-fns formatDistanceToNow para tiempo relativo.

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

AddressDisplay (address-display)

Dirección Solana truncada con copia al portapapeles y enlace opcional al explorador. explorerUrl es una URL base; la dirección se agrega automáticamente.

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

AuthCard (auth-card)

Tarjeta de inicio de sesión con entrada de correo electrónico opcional, botones de inicio de sesión social y botones de proveedores 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 progreso degradada (rojo a verde) con valor porcentual coloreado.

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

LeverageSlider (leverage-slider)

Control deslizante para seleccionar apalancamiento de trading con botones de acceso directo para mínimo/máximo.

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

NFTCard (nft-card)

Tarjeta que muestra imagen NFT, nombre, colección y precio con estados de carga/error.

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

OrderBook (order-book)

Libro de órdenes de trading con niveles de compra/venta, tamaños, totales acumulados, diferencial, precio medio y barras de profundidad.

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

OrderForm (order-form)

Formulario de órdenes TP/SL para posiciones abiertas. Entradas duales TP (precio + % de ganancia), entradas duales SL (precio + % de pérdida). Pasa entryPrice para sincronización automática entre campos de precio y porcentaje.

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)

Tarjeta versátil para pools de un solo token o múltiples tokens. Muestra íconos apilados, precio opcional, descripción, cuadrícula de métricas, gráfico de chispa y slot para hijos.

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)

Tabla de datos con íconos de token (uno o más por fila), columnas definidas por el usuario, ordenable y acciones de fila opcionales. Funciona para listados de pools, tablas de tokens, tablas 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)

Tarjeta que muestra una posición DeFi con ícono de token, cantidad, valor en USD, APY y pie de acción opcional.

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

PositionTable (position-table)

Tabla de posiciones de trading abiertas con tipo (largo/corto), ícono del activo, tamaño, apalancamiento, precios de entrada/marca y P&L coloreado. Columnas de acción integradas de edición de TP/SL y Cerrar con interfaces 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 áreas para historial de precio de token o valor de cartera con ejes, cuadrícula, relleno degradado e información emergente.

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

SparklineChart (sparkline-chart)

Minigráfico de chispa mínimo con color automático positivo/negativo y etiqueta de cambio porcentual.

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

StatCard (stat-card)

Tarjeta de visualización de estadísticas con etiqueta, valor, ícono opcional y badge de tendencia opcional.

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

SwapBox (swap-box)

Formulario de intercambio de dos lados con botón de voltear, filas de detalles y acción de envío. El botón de voltear intercambia los tokens seleccionados en el lugar (las etiquetas permanecen fijas).

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)

Menú desplegable con búsqueda para seleccionar un token con íconos y selección con marca de verificación.

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 buscar y seleccionar tokens. Pasa tokens (lista plana) o groups (seccionados), no 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)

Imagen de ícono de token circular con esqueleto de carga y fallback de error.

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

TokenIconGroup (token-icon-group)

Íconos de token superpuestos apilados para pares LP o grupos de múltiples tokens. Muestra badge +N cuando excede el máximo.

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

TokenInput (token-input)

Entrada numérica con selector de token integrado, saldo de wallet, botones Mitad/Máximo y visualización de valor en USD. Formatea con separadores de miles. onValueChange recibe la cadena sin formato.

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)

Formulario de trading de perpetuos/margen con alternancia largo/corto, entrada de token, control deslizante de apalancamiento, filas de detalles y envío. Para acciones que no son de trading, usa 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 alternancia para seleccionar dirección de trading (Largo/Corto o Comprar/Vender) con estados codificados por colores.

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

TradeChart (trade-chart)

Gráfico de velas impulsado por TradingView lightweight-charts con soporte de tema oscuro/claro.

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

TrendBadge (trend-badge)

Badge pequeño coloreado con ícono de tendencia para cambios positivos (verde) o negativos (rojo).

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

TxnTable (txn-table)

Tabla de transacciones con enlaces de firma truncados, marcas de tiempo relativas (objetos Date, mediante date-fns), badges de acción y cantidades de token.

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

Skills relacionados