@liberfi.io/ui-perpetuals 0.1.49 → 0.1.51

package/README.md

@@ -0,0 +1,146 @@
+# @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.