solanaui은(는) 무엇을 하나요?
shadcn/ui, Radix UI 및 Tailwind CSS를 기반으로 구축된 Solana 특화 React 컴포넌트 라이브러리입니다. 모든 컴포넌트는 프레젠테이션 전용으로, props를 통해 데이터를 받고 콜백을 발생시킵니다. 블록체인 종속성, 지갑 어댑터 또는 SDK 임포트가 없습니다. 사용자가 직접 데이터 계층에 연결합니다.
사용 시기
Solana 앱 인터페이스를 구축할 때 SolanaUI 컴포넌트를 사용하세요. 컴포넌트는 UI 계층(토큰 아이콘 렌더링, 가격 형식 지정, 테이블 및 차트 표시)을 처리하고, 사용자 코드는 데이터 가져오기, 지갑 연결 및 트랜잭션 로직을 처리합니다.
일반적인 통합 방식: API 또는 온체인 소스에서 데이터를 가져와 컴포넌트의 prop 인터페이스에 맞게 변환한 후 전달합니다. (onSubmit, onSelect, onValueChange) 콜백에 연결하여 애플리케이션 로직을 트리거합니다.
설치
프로젝트에 shadcn/ui가 초기화되어 있어야 합니다(components.json이 존재해야 함). 그렇지 않은 경우 먼저 pnpm dlx shadcn@latest init을 실행하세요.
components.json에 SolanaUI 레지스트리를 추가합니다:
{
"registries": {
"@solanaui": "https://solanaui.dev/r/{name}.json"
}
}
그런 다음 컴포넌트를 설치합니다:
pnpm dlx shadcn@latest add @solanaui/swap-box
필요한 모든 shadcn/ui 프리미티브(Card, Dialog, Button 등)는 레지스트리 종속성으로 자동 해결됩니다. 컴포넌트는 또한 @/lib/utils의 cn() 유틸리티에 의존합니다.
임포트 규칙
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";
통합 패턴
데이터 소스 연결
컴포넌트는 props를 통해 일반 데이터를 받습니다. 데이터를 prop 형태에 매핑하세요:
// 데이터 소스 (API, 온체인, 상태 관리 등)
const positions = usePositions(); // 사용자 훅
// 컴포넌트 prop 형태에 매핑
<PositionTable
positions={positions.map(p => ({
symbol: p.market.baseSymbol,
icon: p.market.baseIconUrl, // 사용자 고유 아이콘 URL 사용
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)}
/>
토큰 아이콘
컴포넌트는 문자열로 아이콘 URL을 받습니다. 프로젝트에 이미 있는 아이콘 소스(자체 CDN, 토큰 레지스트리 또는 메타데이터 서비스)를 사용하세요.
프로토타입 제작용 플레이스홀더 아이콘이 필요한 경우 다음 공개 CDN URL을 사용할 수 있습니다:
- 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
콜백 처리
컴포넌트는 사용자 작업에 대한 콜백을 발생시킵니다. 이를 애플리케이션 로직에 연결하세요:
<SwapBox
tokens={availableTokens}
defaultFromToken="USDC"
defaultToToken="SOL"
fromBalance={wallet.usdcBalance}
details={quoteDetails}
submitLabel="Swap"
// 스왑 실행 로직
onSubmit={() => executeSwap(fromToken, toToken, amount)}
/>
<ActionBox
tokens={supportedTokens}
label="Stake"
balance={wallet.solBalance}
details={stakingDetails}
submitLabel="Stake SOL"
onSubmit={() => submitStakeTransaction(selectedToken, amount)}
/>
컴포넌트 카탈로그 (30개 컴포넌트)
ActionBox (action-box)
스테이킹, 대출, LP 예치, 브리징을 위한 단일 입력 액션 폼입니다. 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)
아이콘, 타임스탬프(Date 객체) 및 값을 포함한 시간순 활동 목록입니다. 상대 시간 표시를 위해 date-fns formatDistanceToNow를 사용합니다.
interface ActivityFeedProps {
items: { icon?: string; title: string; description?: string; timestamp: Date; value?: string }[];
className?: string;
}
AddressDisplay (address-display)
잘린 Solana 주소에 클립보드 복사 및 선택적 익스플로러 링크가 포함됩니다. explorerUrl은 기본 URL이며 주소가 자동으로 추가됩니다.
interface AddressDisplayProps {
address: string; truncate?: boolean; truncateChars?: [number, number];
copyable?: boolean; explorerUrl?: string; className?: string;
}
AuthCard (auth-card)
선택적 이메일 입력, 소셜 로그인 버튼 및 지갑 제공자 버튼이 포함된 로그인 카드입니다.
interface AuthCardProps {
title?: string; description?: string; showEmail?: boolean;
socialProviders?: { name: string; icon: React.ReactNode }[];
walletProviders?: { name: string; icon: React.ReactNode }[];
}
HealthBar (health-bar)
빨간색에서 녹색으로 변하는 그라데이션 진행률 표시줄과 색상이 있는 백분율 값이 포함됩니다.
interface HealthBarProps { value: number; label?: string; showValue?: boolean; className?: string }
LeverageSlider (leverage-slider)
최소/최대 단축 버튼이 있는 거래 레버리지 선택용 슬라이더입니다.
interface LeverageSliderProps {
min?: number; max?: number; step?: number; value?: number[];
defaultValue?: number[]; onValueChange?: (value: number[]) => void; className?: string;
}
NFTCard (nft-card)
NFT 이미지, 이름, 컬렉션 및 가격을 표시하며 로딩/오류 상태를 처리하는 카드입니다.
interface NFTCardProps {
name: string; image: string; collection?: string;
price?: string; currency?: string; className?: string;
}
OrderBook (order-book)
매수/매도 호가 레벨, 수량, 누적 합계, 스프레드, 중간 가격 및 깊이 막대가 포함된 거래 주문장입니다.
interface OrderBookProps {
bids: { price: number; size: number }[];
asks: { price: number; size: number }[];
className?: string;
}
OrderForm (order-form)
열린 포지션을 위한 TP/SL 주문 폼입니다. 이중 TP 입력(가격 + 이득 %), 이중 SL 입력(가격 + 손실 %)을 포함합니다. entryPrice를 전달하면 가격과 퍼센트 필드가 자동으로 동기화됩니다.
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)
단일 토큰 또는 다중 토큰 풀을 위한 다목적 카드입니다. 중첩 아이콘, 선택적 가격, 설명, 메트릭 그리드, 스파크라인 차트 및 children 슬롯을 표시합니다.
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)
행당 하나 이상의 토큰 아이콘, 사용자 정의 열, 정렬 가능 및 선택적 행 작업이 포함된 데이터 테이블입니다. 풀 목록, 토큰 테이블, 검증자 테이블에 사용할 수 있습니다.
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)
토큰 아이콘, 수량, USD 가치, APY 및 선택적 액션 푸터가 포함된 DeFi 포지션 카드입니다.
interface PositionCardProps {
symbol: string; icon: string; amount: string; value: string;
apy?: string; trend?: "up" | "down"; children?: React.ReactNode; className?: string;
}
PositionTable (position-table)
유형(롱/숏), 자산 아이콘, 크기, 레버리지, 진입/현재 가격 및 색상이 있는 손익이 포함된 거래 포지션 테이블입니다. 내장된 TP/SL 편집 및 종료 액션 열과 다이얼로그 UI가 포함됩니다.
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)
축, 그리드, 그라데이션 채우기 및 툴팁이 포함된 토큰 가격 또는 포트폴리오 가치 내역의 영역 차트입니다.
interface PriceChartProps {
title?: string; description?: string;
series: { time: string; value: number }[]; className?: string;
}
SparklineChart (sparkline-chart)
자동 양수/음수 색상 지정 및 백분율 변화 레이블이 있는 최소한의 인라인 스파크라인입니다.
interface SparklineChartProps { series: { time: string; value: number }[]; className?: string }
StatCard (stat-card)
레이블, 값, 선택적 아이콘 및 선택적 트렌드 배지가 포함된 통계 표시 카드입니다.
interface StatCardProps {
label: string; value: string; change?: string;
trend?: "up" | "down"; icon?: React.ReactNode; className?: string;
}
SwapBox (swap-box)
토글 버튼, 세부 정보 행 및 제출 액션이 포함된 양방향 토큰 스왑 폼입니다. 토글 버튼은 선택한 토큰을 제자리에서 교체합니다(레이블은 고정).
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)
아이콘과 체크 표시 선택이 있는 검색 가능한 토큰 선택 드롭다운입니다.
interface TokenComboboxProps {
tokens: { icon: string; symbol: string }[];
defaultValue?: string; onSelect?: (token: { icon: string; symbol: string }) => void; className?: string;
}
TokenCommand (token-command)
토큰 검색 및 선택을 위한 Cmd+K 명령 다이얼로그입니다. tokens(단일 목록) 또는 groups(섹션별) 중 하나만 전달하고 둘 다 전달하지 마세요.
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)
로딩 스켈레톤과 오류 폴백이 있는 원형 토큰 아이콘 이미지입니다.
type TokenIconProps = { src: string; alt: string; width?: number; height?: number; className?: string }
TokenIconGroup (token-icon-group)
LP 쌍 또는 다중 토큰 그룹을 위한 중첩된 겹치는 토큰 아이콘입니다. 최대 개수를 초과하면 +N 배지를 표시합니다.
interface TokenIconGroupProps {
tokens: { src: string; alt?: string }[]; size?: number; overlap?: number; max?: number; className?: string;
}
TokenInput (token-input)
통합 토큰 선택기, 지갑 잔액, 반/최대 버튼 및 USD 가치 표시가 포함된 숫자 입력입니다. 천 단위 구분 기호로 서식을 지정합니다. onValueChange는 서식이 지정되지 않은 원시 문자열을 받습니다.
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)
롱/숏 토글, 토큰 입력, 레버리지 슬라이더, 세부 정보 행 및 제출이 포함된 무기한 선물/증거금 거래 폼입니다. 거래가 아닌 액션에는 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)
거래 방향(롱/숏 또는 매수/매도) 선택을 위한 색상 코딩된 상태의 토글 그룹입니다.
interface TradeButtonsProps {
defaultValue?: string; value?: string; onValueChange?: (value: string) => void;
labels?: [string, string]; className?: string;
}
TradeChart (trade-chart)
어두운/밝은 테마를 지원하는 TradingView 라이트웨이트 차트 기반 캔들스틱 차트입니다.
interface TradeChartProps {
data: { time: string | number; open: number; high: number; low: number; close: number }[];
visibleBars?: number; className?: string;
}
TrendBadge (trend-badge)
양수(녹색) 또는 음수(빨간색) 변화를 위한 트렌드 아이콘이 있는 작은 색상 배지입니다.
interface TrendBadgeProps { trend?: "up" | "down"; children: React.ReactNode; className?: string }
TxnTable (txn-table)
잘린 서명 링크, 상대적 타임스탬프(Date 객체, date-fns 사용), 액션 배지 및 토큰 수량이 포함된 트랜잭션 테이블입니다.
interface TxnTableProps {
transactions: {
signature: string; timestamp: Date; action: string; token: string;
tokenIcon?: string; amount: string; value?: string; explorerUrl?: string;
}[];
className?: string;
}
TxnToast (txn-toast)
Solana 트랜잭션 진행 상황(보류 중, 확인됨, 최종)에 대한 알림 스타일 표시기입니다.
interface TxnToastProps { status: "pending" | "confirmed" | "finalized"; signature?: string; className?: string }
UserAvatar (user-avatar)
Solana 지갑 주소를 위한 아바타 표시입니다. 주소를 기반으로 결정론적 생성 아트를 생성합니다.
interface UserAvatarProps { address: string; size?: number; className?: string }
WalletConnector (wallet-connector)
Solana 지갑 연결 UI입니다. 지갑 어댑터 종속성을 포함하지 않습니다. 연결 버튼, 선택적 지갑 주소 표시 및 연결 끊기 버튼을 제공합니다. 지갑 상태를 충실히 반영하려면 부모 컴포넌트가 연결 상태를 관리해야 합니다.
interface WalletConnectorProps {
address?: string; balance?: string;
onConnect?: () => void; onDisconnect?: () => void; className?: string;
}
라이선스
MIT