@liberfi.io/ui-predict 0.1.53 → 0.1.54

package/README.md

@@ -0,0 +1,263 @@
+# @liberfi.io/ui-predict
+
+Prediction market UI components, data hooks, and client for the Liberfi React SDK. Provides a full-stack prediction market experience — from event browsing and detail views to trading, order management, and real-time price feeds. Consumed by template apps (e.g. `dex-nextjs-template`) and composed with `@liberfi.io/ui` base components.
+
+## Design Philosophy
+
+- **Script / UI / Widget separation** — Each feature area (events, trade-form, order-book, etc.) is split into a `.script` (data hook), `.ui` (pure presentation), and `.widget` (wiring) layer. Presentational components are reusable without the full data stack.
+- **Inversion of Control** — Navigation, side effects, and framework-specific behaviour (e.g. Next.js `<Link>`) are injected via callbacks and component props. The package never imports a router or framework directly.
+- **V1 / V2 coexistence** — Legacy DFlow-backed components coexist with the prediction-server v2 client. Consumers migrate at their own pace; both APIs are stable and exported.
+- **Provider-based client injection** — `PredictProvider` / `PredictV2Provider` supply the API client via React Context. Hooks pull the client from context, keeping components testable and decoupled from concrete HTTP implementations.
+
+## Installation
+
+```bash
+pnpm add @liberfi.io/ui-predict
+```
+
+### Peer dependencies
+
+The consumer must provide:
+
+| Package                 | Version |
+| ----------------------- | ------- |
+| `react`                 | >= 18   |
+| `react-dom`             | >= 18   |
+| `@tanstack/react-query` | ^5.90.2 |
+
+## API Reference
+
+### Providers
+
+| Provider              | Props                                     | Description                                                                  |
+| --------------------- | ----------------------------------------- | ---------------------------------------------------------------------------- |
+| `PredictProvider`     | `client: IPredictClient`                  | Supplies the legacy DFlow predict client to all descendant hooks/components. |
+| `PredictV2Provider`   | `client: PredictClientV2`                 | Supplies the v2 prediction-server client.                                    |
+| `UserPredictProvider` | `walletAddress: string, enabled: boolean` | Provides user-specific prediction context (positions, orders).               |
+
+### Components — Events (V2)
+
+| Component            | Key Props                                                                                                                             | Description                                                                                                             |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `EventsPageV2`       | `onSelect`, `onSelectOutcome`, `getEventHref`, `LinkComponent`, `onHover`                                                             | Full events page with categories, toolbar, filters, and grid.                                                           |
+| `EventsWidgetV2`     | `tagSlugSelection`, `limit`, `status`, `sort_by`, `source`, `onSelect`, `onSelectOutcome`, `getEventHref`, `LinkComponent`, `onHover` | Container that wires `useEventsV2` data to `EventsV2UI`.                                                                |
+| `EventsV2UI`         | `events`, `hasMore`, `onFetchMore`, `onSelect`, `onSelectOutcome`, `getEventHref`, `LinkComponent`, `onHover`                         | Virtualized grid (react-window) rendering `EventItemV2UI` cards.                                                        |
+| `EventItemV2UI`      | `event`, `href`, `LinkComponent`, `onSelect`, `onSelectOutcome`, `onHover`                                                            | Single event card. Uses `Linkable` from `@liberfi.io/ui` — renders as a `<Link>` when `href` is set, `<div>` otherwise. |
+| `CategoriesWidgetV2` | `onSelect`, `trailing`                                                                                                                | Category/tag navigation (slug-based).                                                                                   |
+
+#### Link integration props
+
+These props enable framework-agnostic route link rendering and prefetching:
+
+- **`getEventHref?: (event: V2Event) => string`** — Generates the URL for each event card. When provided, cards render as link elements instead of plain divs.
+- **`LinkComponent?: LinkComponentType`** — A custom link component (e.g. `next/link`). Falls back to `<a>` when `href` is set without this prop. Import `LinkComponentType` from `@liberfi.io/ui`.
+- **`onHover?: (event: V2Event) => void`** — Called when a card is hovered (`onMouseEnter`). Use this to trigger data prefetching (e.g. `queryClient.prefetchQuery`).
+
+### Components — Event Detail
+
+| Component             | Key Props                                                               | Description                                          |
+| --------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- |
+| `EventDetailPage`     | `eventId`, `onTradeAction`                                              | Full detail page composing detail + trade form.      |
+| `EventDetailWidget`   | `eventId`, `initialMarketTickers`, `initialChartRange`, `onTradeAction` | Event detail with candlestick chart and market list. |
+| `EventDetailUI`       | `event`, `series`, `candlesticks`, `chartRange`, ...                    | Pure presentation for event detail.                  |
+| `EventDetailSkeleton` | `marketCount?`                                                          | Loading skeleton for the detail page.                |
+
+### Components — Trading
+
+| Component            | Description                                          |
+| -------------------- | ---------------------------------------------------- |
+| `TradeFormWidget`    | Trade form wiring (market, side, amount, execution). |
+| `OrderBookWidget`    | Live order book with depth visualization.            |
+| `OpenOrdersWidget`   | User's open orders with cancel support.              |
+| `TradeHistoryWidget` | Recent trade history.                                |
+| `PositionsWidget`    | User's prediction market positions.                  |
+
+### Hooks — Events
+
+| Hook                     | Params                       | Return                  | Description                                    |
+| ------------------------ | ---------------------------- | ----------------------- | ---------------------------------------------- |
+| `useEventsV2`            | `UseEventsV2Params`          | `UseEventsV2Result`     | V2 infinite-scroll events list (cursor-based). |
+| `useEventByIdQuery`      | `{ id, withNestedMarkets? }` | TanStack Query result   | Single event by ID/slug.                       |
+| `useEventsQuery`         | `EventQueryParams`           | TanStack Query result   | Legacy paginated events.                       |
+| `useEventsInfiniteQuery` | `EventQueryParams`           | TanStack infinite query | Legacy infinite-scroll events.                 |
+
+### Hooks — Markets & Data
+
+| Hook                                                      | Description                     |
+| --------------------------------------------------------- | ------------------------------- |
+| `useMarketsQuery`                                         | Markets by event.               |
+| `useMarketByIdQuery`                                      | Single market by ticker.        |
+| `useMarketByMintQuery`                                    | Market lookup by mint address.  |
+| `useMarketsBatchQuery`                                    | Batch market lookup.            |
+| `useOrderBookQuery`                                       | Order book for a market.        |
+| `useTradesQuery`                                          | Recent trades.                  |
+| `useOnchainTradesQuery` / `useOnchainTradesInfiniteQuery` | On-chain trade history.         |
+| `usePriceHistoryQuery`                                    | Candlestick data.               |
+| `useForecastHistoryQuery`                                 | AI forecast percentile history. |
+| `useLiveDataQuery`                                        | Real-time market data.          |
+| `useSeriesQuery`                                          | Series metadata.                |
+| `useCategoriesQuery`                                      | Tag/category list.              |
+| `useSearchQuery`                                          | Search events.                  |
+
+### Hooks — User & Trading
+
+| Hook                        | Description                      |
+| --------------------------- | -------------------------------- |
+| `usePositionsByWalletQuery` | User positions by wallet.        |
+| `useMarketPositions`        | Positions for a specific market. |
+| `useQuoteQuery`             | Trade quote.                     |
+| `useSwapMutation`           | Execute a swap/trade.            |
+| `useOrderQuery`             | Place a limit order.             |
+| `useIntentQuery`            | Intent-based trading.            |
+| `useOutcomeMintsQuery`      | Outcome token mints.             |
+| `useTokensQuery`            | Token list.                      |
+| `useVenuesQuery`            | Venue list.                      |
+
+### Hooks — WebSocket
+
+| Hook                       | Description                               |
+| -------------------------- | ----------------------------------------- |
+| `useWsConnection`          | WebSocket connection lifecycle.           |
+| `useWsClient`              | Access the WS client instance.            |
+| `usePricesSubscription`    | Subscribe to real-time price updates.     |
+| `useTradesSubscription`    | Subscribe to real-time trade updates.     |
+| `useOrderbookSubscription` | Subscribe to real-time orderbook updates. |
+
+### Hooks — V2
+
+| Hook                 | Description                             |
+| -------------------- | --------------------------------------- |
+| `usePredictV2Client` | Access the v2 prediction-server client. |
+| `useEventsV2Query`   | V2 events query (single page).          |
+| `useEventV2Query`    | V2 single event query.                  |
+
+### Functions / Utilities
+
+| Function                     | Signature                                                                             | Description                                                                         |
+| ---------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `eventByIdQueryKey`          | `(params: UseEventByIdQueryParams) => unknown[]`                                      | Stable query key for `useEventByIdQuery`. Useful for prefetching.                   |
+| `fetchEventById`             | `(client: IPredictClient, params: UseEventByIdQueryParams) => Promise<StandardEvent>` | Standalone fetch function for event detail. Useful for `queryClient.prefetchQuery`. |
+| `marketCandlesticksQueryKey` | `(params) => unknown[]`                                                               | Query key for candlestick data.                                                     |
+| `fetchMarketCandlesticks`    | `(client, params) => Promise<CandlesticksResponse>`                                   | Standalone candlestick fetch.                                                       |
+| `createPredictClientV2`      | `(baseURL: string) => PredictClientV2`                                                | Factory for the v2 client.                                                          |
+| `createPredictWsClient`      | `(config: WsClientConfig) => PredictWsClient`                                         | Factory for the WebSocket client.                                                   |
+
+### Key Types
+
+| Type               | Description                                               |
+| ------------------ | --------------------------------------------------------- | ---- | ---- | ------ |
+| `V2Event`          | V2 event with markets, metadata, and volume.              |
+| `V2Market`         | V2 market with outcomes, status, and pricing.             |
+| `StandardEvent`    | Legacy event model.                                       |
+| `StandardMarket`   | Legacy market model.                                      |
+| `IPredictClient`   | Interface for the prediction API client.                  |
+| `IPredictWsClient` | Interface for the WebSocket client.                       |
+| `TagSlugSelection` | Category/tag selection state `{ categorySlug, tagSlug }`. |
+| `ChartRangeType`   | `"1d"                                                     | "1w" | "1m" | "all"` |
+
+### Constants
+
+| Constant                    | Value                                   | Description                          |
+| --------------------------- | --------------------------------------- | ------------------------------------ |
+| `DEFAULT_PAGE_SIZE`         | 48                                      | Default events per page.             |
+| `MAX_PRICE_HISTORY_MARKETS` | 4                                       | Max markets for candlestick queries. |
+| `ChartRange`                | `{ ONE_DAY, ONE_WEEK, ONE_MONTH, ALL }` | Chart time range enum.               |
+| `CandlestickPeriod`         | `{ ONE_MINUTE, ONE_HOUR, ONE_DAY }`     | Candlestick granularity.             |
+
+## Usage Examples
+
+### Basic event list with Next.js Link prefetching
+
+```tsx
+import { useCallback } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import {
+  EventsPageV2,
+  eventByIdQueryKey,
+  fetchEventById,
+  usePredictClient,
+} from "@liberfi.io/ui-predict";
+import type { V2Event } from "@liberfi.io/ui-predict";
+
+function PredictListPage() {
+  const router = useRouter();
+  const queryClient = useQueryClient();
+  const predictClient = usePredictClient();
+
+  // TanStack Query data prefetch on hover
+  const handleHover = useCallback(
+    (event: V2Event) => {
+      queryClient.prefetchQuery({
+        queryKey: eventByIdQueryKey({
+          id: event.slug,
+          withNestedMarkets: true,
+        }),
+        queryFn: () =>
+          fetchEventById(predictClient, {
+            id: event.slug,
+            withNestedMarkets: true,
+          }),
+        staleTime: 30_000,
+      });
+    },
+    [queryClient, predictClient],
+  );
+
+  return (
+    <EventsPageV2
+      getEventHref={(event) => `/predict/${event.slug}`}
+      LinkComponent={Link}
+      onHover={handleHover}
+      onSelect={(event) => router.push(`/predict/${event.slug}`)}
+    />
+  );
+}
+```
+
+### Event list without Link (callback-only, backward compatible)
+
+```tsx
+import { EventsPageV2 } from "@liberfi.io/ui-predict";
+
+function PredictListPage() {
+  return (
+    <EventsPageV2
+      onSelect={(event) => console.log("selected", event.slug)}
+      onSelectOutcome={(event, market, side) =>
+        console.log("outcome", event.slug, market.slug, side)
+      }
+    />
+  );
+}
+```
+
+### Provider setup
+
+```tsx
+import {
+  PredictProvider,
+  PredictV2Provider,
+  PredictClient,
+  createPredictClientV2,
+} from "@liberfi.io/ui-predict";
+
+const legacyClient = new PredictClient("https://api.example.com");
+const v2Client = createPredictClientV2("https://predict-v2.example.com");
+
+function App({ children }) {
+  return (
+    <PredictProvider client={legacyClient}>
+      <PredictV2Provider client={v2Client}>{children}</PredictV2Provider>
+    </PredictProvider>
+  );
+}
+```
+
+## Future Improvements
+
+- Migrate remaining v1 components (events list, categories) to v2 client, then deprecate v1 hooks and types.
+- Add `onHover` callback support to `EventDetailWidget` for prefetching related series/candlestick data.
+- Consider a `usePrefetchEventDetail` convenience hook that combines route prefetch + query prefetch in one call.
+- Extract common virtualized grid logic (`EventsV2UI` pattern) into a shared `@liberfi.io/ui` component for reuse in token lists and channel lists.

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { S as StandardEvent, a as StandardMarket, E as EventQueryParams, V as V2EventSortField, b as V2ProviderSource, c as V2Event, d as V2Market, e as V2EventStatus, O as OrderResponse, f as OrderStatusResponse, g as SeriesResponse, C as CandlesticksResponse, h as OrderbookLevel, i as SingleTradeResponse, I as IPredictClient, j as IPredictWsClient, W as WalletPositionItem, P as PredictClientV2, k as V2ListEventsParams, l as V2Page, m as StandardEventsResponse, M as MarketQueryParams, n as StandardMarketsResponse, o as MarketsBatchRequest, p as OrderbookResponse, T as TradesQueryParams, q as MultiTradeResponse, r as TradesByMintQueryParams, s as OnchainTradesByWalletQueryParams, t as MultiOnchainTradeResponse, u as OnchainTradesByEventQueryParams, v as OnchainTradesByMarketQueryParams, w as CandlesticksQueryParams, F as ForecastPercentileHistoryQueryParams, x as ForecastPercentileHistoryResponse, y as ForecastPercentileHistoryByMintQueryParams, L as LiveDataQueryParams, z as LiveDataResponse, A as LiveDataByEventQueryParams, B as LiveDataByMintQueryParams, D as SeriesQueryParams, G as SeriesListResponse, H as TagsByCategoriesResponse, J as FiltersBySportsResponse, K as SearchQueryParams, N as SearchResponse, Q as PositionsByWalletQueryParams, R as WalletPositionsResponse, U as OutcomeMintsQueryParams, X as OutcomeMintsResponse, Y as FilterOutcomeMintsRequest, Z as FilterOutcomeMintsResponse, _ as QuoteQueryParams, $ as QuoteResponse, a0 as SwapRequestBody, a1 as SwapResponse, a2 as SwapInstructionsResponse, a3 as OrderQueryParams, a4 as OrderStatusQueryParams, a5 as IntentQuoteQueryParams, a6 as IntentQuoteResponse, a7 as IntentSwapRequestBody, a8 as IntentSwapResponse, a9 as PredictionMarketInitQueryParams, aa as PredictionMarketInitResponse, ab as TokenListResponse, ac as TokenListWithDecimalsResponse, ad as VenueListResponse, ae as WsConnectionStatus, af as WsPriceUpdate, ag as WsTradeUpdate, ah as WsOrderbookUpdate } from './index-DIcC-37S.mjs';
 export { aE as AccountMetaResponse, aR as BasePredictClient, aG as BlockhashWithMetadata, ax as CandlestickDataPoint, aw as CandlestickOHLC, aC as ComputeBudgetInfo, aO as CreateFeeAccountParams, aN as DestinationTokenAccountParam, aU as DflowPredictClient, aV as DflowPredictWsClient, aq as ExecutionMode, ay as ForecastPercentileDataPoint, aF as InstructionResponse, aJ as IntentExpiry, as as MarketAccountInfo, aj as MarketStatus, at as OnchainTrade, au as OnchainTradeSortBy, av as OnchainTradesBaseQueryParams, aH as OrderFill, aI as OrderRevert, am as OrderStatus, aL as OrderbookQueryParams, aB as PlatformFee, an as PlatformFeeMode, aP as PositiveSlippageParams, aU as PredictClient, aV as PredictWsClient, aM as PrioritizationFeeLamports, aD as PrioritizationType, ap as PriorityLevel, ai as ProviderType, aA as RoutePlanLeg, az as SeriesSettlementSource, ar as SettlementSource, ao as SlippageTolerance, ak as SortField, al as SortOrder, aK as TokenWithDecimals, aZ as V2MarketResult, a_ as V2MarketStatus, a$ as V2Outcome, b0 as V2ProviderMeta, b1 as V2SettlementSource, b2 as V2Tag, aX as WsClientConfig, aQ as WsSubscribeOptions, aS as buildQuery, aW as createDflowPredictWsClient, aY as createPredictClientV2, aW as createPredictWsClient, aT as toRecord } from './index-DIcC-37S.mjs';
+import { LinkComponentType } from '@liberfi.io/ui';
 import * as react from 'react';
 import { PropsWithChildren } from 'react';
 import * as _tanstack_react_query from '@tanstack/react-query';
@@ -13,7 +14,7 @@ declare global {
         };
     }
 }
-declare const _default: "0.1.53";
+declare const _default: "0.1.54";
 
 interface EventsPageProps {
     /** Callback when an event is selected */
@@ -213,8 +214,14 @@ interface EventsPageV2Props {
     onSelect?: (event: V2Event) => void;
     /** Callback when an outcome button (yes / no) is pressed */
     onSelectOutcome?: (event: V2Event, market: V2Market, side: "yes" | "no") => void;
+    /** Generate href for each event card. When set, cards render as links. */
+    getEventHref?: (event: V2Event) => string;
+    /** Custom link component (e.g. next/link). */
+    LinkComponent?: LinkComponentType;
+    /** Called when a card is hovered (for data prefetching). */
+    onHover?: (event: V2Event) => void;
 }
-declare function EventsPageV2({ onSelect, onSelectOutcome }: EventsPageV2Props): react_jsx_runtime.JSX.Element;
+declare function EventsPageV2({ onSelect, onSelectOutcome, getEventHref, LinkComponent, onHover, }: EventsPageV2Props): react_jsx_runtime.JSX.Element;
 
 interface EventsWidgetV2Props {
     /**
@@ -238,8 +245,14 @@ interface EventsWidgetV2Props {
     onSelect?: (event: V2Event) => void;
     /** Callback when an outcome button (yes/no) is pressed */
     onSelectOutcome?: (event: V2Event, market: V2Market, side: "yes" | "no") => void;
+    /** Generate href for each event card. When set, cards render as links. */
+    getEventHref?: (event: V2Event) => string;
+    /** Custom link component (e.g. next/link). */
+    LinkComponent?: LinkComponentType;
+    /** Called when a card is hovered (for data prefetching). */
+    onHover?: (event: V2Event) => void;
 }
-declare function EventsWidgetV2({ tagSlugSelection, limit, status, sort_by, sort_asc, source, with_markets, onSelect, onSelectOutcome, }: EventsWidgetV2Props): react_jsx_runtime.JSX.Element;
+declare function EventsWidgetV2({ tagSlugSelection, limit, status, sort_by, sort_asc, source, with_markets, onSelect, onSelectOutcome, getEventHref, LinkComponent, onHover, }: EventsWidgetV2Props): react_jsx_runtime.JSX.Element;
 
 /** Parameters for useEventsV2 */
 interface UseEventsV2Params {
@@ -313,15 +326,27 @@ type EventsV2UIProps = {
     onSelect?: (event: V2Event) => void;
     /** Callback when an outcome button (yes/no) is pressed */
     onSelectOutcome?: (event: V2Event, market: V2Market, side: "yes" | "no") => void;
+    /** Generate href for each event card. When set, cards render as links. */
+    getEventHref?: (event: V2Event) => string;
+    /** Custom link component (e.g. next/link). */
+    LinkComponent?: LinkComponentType;
+    /** Called when a card is hovered (for data prefetching). */
+    onHover?: (event: V2Event) => void;
 };
-declare function EventsV2UI({ events, hasMore, onFetchMore, onSelect, onSelectOutcome, }: EventsV2UIProps): react_jsx_runtime.JSX.Element;
+declare function EventsV2UI({ events, hasMore, onFetchMore, onSelect, onSelectOutcome, getEventHref, LinkComponent, onHover, }: EventsV2UIProps): react_jsx_runtime.JSX.Element;
 
 type EventItemV2UIProps = {
     event: V2Event;
+    /** URL for the detail page. When set, card renders as a link via Linkable. */
+    href?: string;
+    /** Custom link component (e.g. next/link). Passed to Linkable. */
+    LinkComponent?: LinkComponentType;
     onSelect?: (event: V2Event) => void;
     onSelectOutcome?: (event: V2Event, market: V2Market, side: "yes" | "no") => void;
+    /** Called when the card is hovered (for data prefetching). */
+    onHover?: (event: V2Event) => void;
 };
-declare function EventItemV2UI({ event, onSelect, onSelectOutcome, }: EventItemV2UIProps): react_jsx_runtime.JSX.Element;
+declare function EventItemV2UI({ event, href, LinkComponent, onSelect, onSelectOutcome, onHover, }: EventItemV2UIProps): react_jsx_runtime.JSX.Element;
 
 /** Default page size for list queries */
 declare const DEFAULT_PAGE_SIZE = 48;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { S as StandardEvent, a as StandardMarket, E as EventQueryParams, V as V2EventSortField, b as V2ProviderSource, c as V2Event, d as V2Market, e as V2EventStatus, O as OrderResponse, f as OrderStatusResponse, g as SeriesResponse, C as CandlesticksResponse, h as OrderbookLevel, i as SingleTradeResponse, I as IPredictClient, j as IPredictWsClient, W as WalletPositionItem, P as PredictClientV2, k as V2ListEventsParams, l as V2Page, m as StandardEventsResponse, M as MarketQueryParams, n as StandardMarketsResponse, o as MarketsBatchRequest, p as OrderbookResponse, T as TradesQueryParams, q as MultiTradeResponse, r as TradesByMintQueryParams, s as OnchainTradesByWalletQueryParams, t as MultiOnchainTradeResponse, u as OnchainTradesByEventQueryParams, v as OnchainTradesByMarketQueryParams, w as CandlesticksQueryParams, F as ForecastPercentileHistoryQueryParams, x as ForecastPercentileHistoryResponse, y as ForecastPercentileHistoryByMintQueryParams, L as LiveDataQueryParams, z as LiveDataResponse, A as LiveDataByEventQueryParams, B as LiveDataByMintQueryParams, D as SeriesQueryParams, G as SeriesListResponse, H as TagsByCategoriesResponse, J as FiltersBySportsResponse, K as SearchQueryParams, N as SearchResponse, Q as PositionsByWalletQueryParams, R as WalletPositionsResponse, U as OutcomeMintsQueryParams, X as OutcomeMintsResponse, Y as FilterOutcomeMintsRequest, Z as FilterOutcomeMintsResponse, _ as QuoteQueryParams, $ as QuoteResponse, a0 as SwapRequestBody, a1 as SwapResponse, a2 as SwapInstructionsResponse, a3 as OrderQueryParams, a4 as OrderStatusQueryParams, a5 as IntentQuoteQueryParams, a6 as IntentQuoteResponse, a7 as IntentSwapRequestBody, a8 as IntentSwapResponse, a9 as PredictionMarketInitQueryParams, aa as PredictionMarketInitResponse, ab as TokenListResponse, ac as TokenListWithDecimalsResponse, ad as VenueListResponse, ae as WsConnectionStatus, af as WsPriceUpdate, ag as WsTradeUpdate, ah as WsOrderbookUpdate } from './index-DIcC-37S.js';
 export { aE as AccountMetaResponse, aR as BasePredictClient, aG as BlockhashWithMetadata, ax as CandlestickDataPoint, aw as CandlestickOHLC, aC as ComputeBudgetInfo, aO as CreateFeeAccountParams, aN as DestinationTokenAccountParam, aU as DflowPredictClient, aV as DflowPredictWsClient, aq as ExecutionMode, ay as ForecastPercentileDataPoint, aF as InstructionResponse, aJ as IntentExpiry, as as MarketAccountInfo, aj as MarketStatus, at as OnchainTrade, au as OnchainTradeSortBy, av as OnchainTradesBaseQueryParams, aH as OrderFill, aI as OrderRevert, am as OrderStatus, aL as OrderbookQueryParams, aB as PlatformFee, an as PlatformFeeMode, aP as PositiveSlippageParams, aU as PredictClient, aV as PredictWsClient, aM as PrioritizationFeeLamports, aD as PrioritizationType, ap as PriorityLevel, ai as ProviderType, aA as RoutePlanLeg, az as SeriesSettlementSource, ar as SettlementSource, ao as SlippageTolerance, ak as SortField, al as SortOrder, aK as TokenWithDecimals, aZ as V2MarketResult, a_ as V2MarketStatus, a$ as V2Outcome, b0 as V2ProviderMeta, b1 as V2SettlementSource, b2 as V2Tag, aX as WsClientConfig, aQ as WsSubscribeOptions, aS as buildQuery, aW as createDflowPredictWsClient, aY as createPredictClientV2, aW as createPredictWsClient, aT as toRecord } from './index-DIcC-37S.js';
+import { LinkComponentType } from '@liberfi.io/ui';
 import * as react from 'react';
 import { PropsWithChildren } from 'react';
 import * as _tanstack_react_query from '@tanstack/react-query';
@@ -13,7 +14,7 @@ declare global {
         };
     }
 }
-declare const _default: "0.1.53";
+declare const _default: "0.1.54";
 
 interface EventsPageProps {
     /** Callback when an event is selected */
@@ -213,8 +214,14 @@ interface EventsPageV2Props {
     onSelect?: (event: V2Event) => void;
     /** Callback when an outcome button (yes / no) is pressed */
     onSelectOutcome?: (event: V2Event, market: V2Market, side: "yes" | "no") => void;
+    /** Generate href for each event card. When set, cards render as links. */
+    getEventHref?: (event: V2Event) => string;
+    /** Custom link component (e.g. next/link). */
+    LinkComponent?: LinkComponentType;
+    /** Called when a card is hovered (for data prefetching). */
+    onHover?: (event: V2Event) => void;
 }
-declare function EventsPageV2({ onSelect, onSelectOutcome }: EventsPageV2Props): react_jsx_runtime.JSX.Element;
+declare function EventsPageV2({ onSelect, onSelectOutcome, getEventHref, LinkComponent, onHover, }: EventsPageV2Props): react_jsx_runtime.JSX.Element;
 
 interface EventsWidgetV2Props {
     /**
@@ -238,8 +245,14 @@ interface EventsWidgetV2Props {
     onSelect?: (event: V2Event) => void;
     /** Callback when an outcome button (yes/no) is pressed */
     onSelectOutcome?: (event: V2Event, market: V2Market, side: "yes" | "no") => void;
+    /** Generate href for each event card. When set, cards render as links. */
+    getEventHref?: (event: V2Event) => string;
+    /** Custom link component (e.g. next/link). */
+    LinkComponent?: LinkComponentType;
+    /** Called when a card is hovered (for data prefetching). */
+    onHover?: (event: V2Event) => void;
 }
-declare function EventsWidgetV2({ tagSlugSelection, limit, status, sort_by, sort_asc, source, with_markets, onSelect, onSelectOutcome, }: EventsWidgetV2Props): react_jsx_runtime.JSX.Element;
+declare function EventsWidgetV2({ tagSlugSelection, limit, status, sort_by, sort_asc, source, with_markets, onSelect, onSelectOutcome, getEventHref, LinkComponent, onHover, }: EventsWidgetV2Props): react_jsx_runtime.JSX.Element;
 
 /** Parameters for useEventsV2 */
 interface UseEventsV2Params {
@@ -313,15 +326,27 @@ type EventsV2UIProps = {
     onSelect?: (event: V2Event) => void;
     /** Callback when an outcome button (yes/no) is pressed */
     onSelectOutcome?: (event: V2Event, market: V2Market, side: "yes" | "no") => void;
+    /** Generate href for each event card. When set, cards render as links. */
+    getEventHref?: (event: V2Event) => string;
+    /** Custom link component (e.g. next/link). */
+    LinkComponent?: LinkComponentType;
+    /** Called when a card is hovered (for data prefetching). */
+    onHover?: (event: V2Event) => void;
 };
-declare function EventsV2UI({ events, hasMore, onFetchMore, onSelect, onSelectOutcome, }: EventsV2UIProps): react_jsx_runtime.JSX.Element;
+declare function EventsV2UI({ events, hasMore, onFetchMore, onSelect, onSelectOutcome, getEventHref, LinkComponent, onHover, }: EventsV2UIProps): react_jsx_runtime.JSX.Element;
 
 type EventItemV2UIProps = {
     event: V2Event;
+    /** URL for the detail page. When set, card renders as a link via Linkable. */
+    href?: string;
+    /** Custom link component (e.g. next/link). Passed to Linkable. */
+    LinkComponent?: LinkComponentType;
     onSelect?: (event: V2Event) => void;
     onSelectOutcome?: (event: V2Event, market: V2Market, side: "yes" | "no") => void;
+    /** Called when the card is hovered (for data prefetching). */
+    onHover?: (event: V2Event) => void;
 };
-declare function EventItemV2UI({ event, onSelect, onSelectOutcome, }: EventItemV2UIProps): react_jsx_runtime.JSX.Element;
+declare function EventItemV2UI({ event, href, LinkComponent, onSelect, onSelectOutcome, onHover, }: EventItemV2UIProps): react_jsx_runtime.JSX.Element;
 
 /** Default page size for list queries */
 declare const DEFAULT_PAGE_SIZE = 48;