npm package: @liberfi.io/ui-perpetuals
Description: Perpetuals for Liberfi React SDK
Author: liberfi.io
Latest version: 0.1.141

# @liberfi.io/ui-perpetuals

`@liberfi.io/ui-perpetuals` provides perpetual trading UI widgets, container hooks, and typed client contracts for the Liberfi React SDK. It is designed for host apps that want ready-to-use perpetual modules (order book, trades, place order, positions, orders, history) while still controlling networking, side effects, and provider wiring.

## Design Philosophy

- Keep data logic and presentation separated (`*.script.tsx` + `*.ui.tsx` + `*.widget.tsx`).
- Keep client integration explicit via `PerpetualsProvider` and `usePerpetualsClient`.
- Prefer typed hooks over ad-hoc data fetching to keep cache keys and API calls consistent.
- Expose building blocks (UI + hooks + types) so consumers can compose custom flows.

## Installation

```bash
pnpm add @liberfi.io/ui-perpetuals
```

Required peer dependencies:

- `react`
- `react-dom`
- `@tanstack/react-query`
- `react-hook-form`

## API Reference

### Components

- `CoinInfoWidget(props: CoinInfoWidgetProps)`
- `CoinInfoUI(props: CoinInfoUIProps)`
- `CoinInfoSkeletonsUI()`
- `CoinInfoNotFoundUI()`
- `SearchCoinsWidget(props: SearchCoinsWidgetProps)`
- `SearchCoinsUI(props: SearchCoinsUIProps)`
- `OrderBookWidget(props: OrderBookWidgetProps)`
- `OrderBookUI(props: OrderBookUIProps)`
- `TradesWidget(props: TradesWidgetProps)`
- `TradesUI(props: TradesUIProps)`
- `PlaceOrderFormWidget(props: PlaceOrderFormWidgetProps)`
- `PlaceOrderFormUI(props: PlaceOrderFormUIProps)` (uses `react-hook-form` `UseFormReturn`)
- `PositionsWidget(props: PositionsWidgetProps)`
- `PositionsUI(props: PositionsUIProps)`
- `PositionsSkeleton()`
- `PositionsEmpty()`
- `OpenOrdersWidget(props: OpenOrdersWidgetProps)`
- `OpenOrdersUI(props: OpenOrdersUIProps)`
- `OpenOrdersSkeleton()`
- `OpenOrdersEmpty()`
- `TradeHistoryWidget(props: TradeHistoryWidgetProps)`
- `TradeHistoryUI(props: TradeHistoryUIProps)`
- `TradeHistorySkeleton()`
- `TradeHistoryEmpty()`
- `PerpetualsProvider(props: PerpetualsProviderProps)`

### Hooks

- Context hook:
  - `usePerpetualsClient()`
- Query hooks:
  - `useCoinsQuery`, `useMarketQuery`, `useMarketsQuery`, `useKlinesQuery`
  - `useOrderBookQuery`, `useRecentTradesQuery`
  - `usePositionsQuery`, `useOrdersQuery`, `useTradesQuery`
- Mutation hooks:
  - `useCreateOrderMutation`, `useCancelOrderMutation`
- Subscription hooks:
  - `useMarketDataSubscription`, `useCandlesSubscription`, `useUserDataSubscription`
- Component script hooks:
  - `useCoinInfo`, `useSearchCoinsScript`, `useOrderBookScript`, `useTradesScript`
  - `usePlaceOrderFormScript`, `usePositionsScript`, `useOpenOrdersScript`, `useTradeHistoryScript`
- Also exported helpers from hook modules:
  - Query keys and fetchers such as `coinsQueryKey`/`fetchCoins`, `marketQueryKey`/`fetchMarket`, `ordersQueryKey`/`fetchOrders`, etc.
  - Trade operation helpers: `createOrder`, `cancelOrder`.

### Functions / Utilities

- `HyperliquidPerpetualsClient` class implementing `IPerpetualsClient`.
- `usePerpetualsClient()` as the context accessor utility.

### Types & Enums

- Client-related:
  - `IPerpetualsClient`, `HyperliquidClientConfig`, `HyperliquidEnvironment`, `HyperliquidApiError`
  - `PerpetualsContextValue`, `PerpetualsProviderProps`
- Domain enums/types:
  - `Symbol`, `TradingProvider`, `OrderSide`, `OrderType`, `OrderStatus`, `KlineInterval`, `TradeSide`
- Domain entities:
  - `Coin`, `MarketData`, `Kline`, `OrderBookLevel`, `OrderBook`, `Trade`, `Account`
  - `Position`, `Order`, `TradeHistory`
- Request/response contracts:
  - `PlaceOrderParams`, `CancelOrderParams`, `GetPositionsParams`, `GetOpenOrdersParams`, `GetTradesParams`
  - `PlaceOrderResult`, `CancelOrderResult`, `GetPositionsResult`, `GetOpenOrdersResult`, `GetTradesResult`
- UI and script props/result types:
  - All `*Props`, `Use*Params`, `Use*Result` types re-exported by each component/hook index.

### Constants

- `version` (package version string).

## Usage Examples

```tsx
import {
  HyperliquidPerpetualsClient,
  PerpetualsProvider,
  PlaceOrderFormWidget,
  OrderBookWidget,
  TradesWidget,
} from "@liberfi.io/ui-perpetuals";

const client = new HyperliquidPerpetualsClient({ environment: "testnet" });

export function PerpsPanel() {
  return (
    <PerpetualsProvider client={client}>
      <OrderBookWidget symbol="BTC-USDC" />
      <TradesWidget symbol="BTC-USDC" />
      <PlaceOrderFormWidget symbol="BTC-USDC" userAddress="0x..." />
    </PerpetualsProvider>
  );
}
```

```tsx
import { useForm } from "react-hook-form";
import {
  PlaceOrderFormUI,
  type PlaceOrderFormData,
} from "@liberfi.io/ui-perpetuals";

const methods = useForm<PlaceOrderFormData>({
  defaultValues: {
    amount: 0,
    leverage: 1,
    takeProfitPercent: 0,
    stopLossPercent: 0,
  },
});

// Pass methods directly to PlaceOrderFormUI if you build your own container.
```

## Future Improvements

- Add integration tests for order submit/cancel and subscription lifecycle.
- Add i18n wiring for all user-facing strings in `ui-perpetuals` components.
- Replace placeholder account/margin values in place-order script with real account sources.