@liberfi.io/ui-tokens 3.0.22 → 3.0.24

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType } from 'react';
 import * as _liberfi_io_types from '@liberfi.io/types';
-import { Token, GetTokenListOptions, TokenProtocol, Chain, WalletTag, TokenSocialMedias, TokenHoldersSortBy, TokenHolder, ActivitiesSortBy, Activity, TokenStats, TokenSecurity as TokenSecurity$1, TokenLiquidity, PortfolioPnl, LimitOrderState, LimitOrder, TokenFieldOption } from '@liberfi.io/types';
+import { Token, GetTokenListOptions, TokenProtocol, Chain, WalletTag, TokenSocialMedias, TokenHoldersSortBy, TokenHolder, ActivitiesSortBy, Activity, TokenStats, TokenSecurity as TokenSecurity$1, TokenLiquidity, PortfolioPnl, LimitOrderState, LimitOrder, TokenTopTrader, TokenTopTradersSortBy, TokenFieldOption } from '@liberfi.io/types';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { PopoverProps } from '@liberfi.io/ui';
 export { formatAmount } from '@liberfi.io/utils';
@@ -23,12 +23,14 @@ interface PulseListProps {
     onSelectToken?: (token: Token) => void;
     /** called when the list should pause/resume adding new items (e.g. mouse hover) */
     onPauseChange?: (isPaused: boolean) => void;
+    /** callback function when the virtualized list scroll state changes */
+    onScrollingChange?: (isScrolling: boolean) => void;
     /** custom styles */
     className?: string;
     /** whether to hide the header */
     hideHeader?: boolean;
 }
-declare function PulseList({ title, tokens, isLoading, itemHeight, renderHeaderExtra, renderItemAction, onSelectToken, onPauseChange, className, hideHeader, }: PulseListProps): react_jsx_runtime.JSX.Element;
+declare function PulseList({ title, tokens, isLoading, itemHeight, renderHeaderExtra, renderItemAction, onSelectToken, onPauseChange, onScrollingChange, className, hideHeader, }: PulseListProps): react_jsx_runtime.JSX.Element;
 
 interface PulseListHeaderProps {
     title: string;
@@ -85,6 +87,10 @@ type UsePulseNewListScriptParams = {
     filters?: TokenListFiltersType;
     /** whether to pause adding new items (existing items still update) */
     isPaused?: boolean;
+    /** defer websocket updates while the list is actively scrolling */
+    deferUpdates?: boolean;
+    /** minimum interval for batched websocket updates */
+    updateFlushInterval?: number;
 };
 type UsePulseNewListScriptResult = {
     /** whether tokens are loading */
@@ -92,7 +98,7 @@ type UsePulseNewListScriptResult = {
     /** token list */
     tokens: Token[];
 };
-declare function usePulseNewListScript({ chain, filters, isPaused, }: UsePulseNewListScriptParams): UsePulseNewListScriptResult;
+declare function usePulseNewListScript({ chain, filters, isPaused, deferUpdates, updateFlushInterval, }: UsePulseNewListScriptParams): UsePulseNewListScriptResult;
 
 interface PulseNewListWidgetProps {
     /** chain id */
@@ -123,6 +129,10 @@ type UsePulseMigratedListScriptParams = {
     isPaused?: boolean;
     /** refetch interval in milliseconds */
     refetchInterval?: number;
+    /** defer websocket updates while the list is actively scrolling */
+    deferUpdates?: boolean;
+    /** minimum interval for batched websocket updates */
+    updateFlushInterval?: number;
 };
 type UsePulseMigratedListScriptResult = {
     /** whether tokens are loading */
@@ -130,7 +140,7 @@ type UsePulseMigratedListScriptResult = {
     /** token list */
     tokens: Token[];
 };
-declare function usePulseMigratedListScript({ chain, filters, isPaused, refetchInterval, }: UsePulseMigratedListScriptParams): UsePulseMigratedListScriptResult;
+declare function usePulseMigratedListScript({ chain, filters, isPaused, refetchInterval, deferUpdates, updateFlushInterval, }: UsePulseMigratedListScriptParams): UsePulseMigratedListScriptResult;
 
 interface PulseMigratedListWidgetProps {
     /** chain id */
@@ -161,6 +171,10 @@ type UsePulseFinalStretchListScriptParams = {
     isPaused?: boolean;
     /** refetch interval in milliseconds */
     refetchInterval?: number;
+    /** defer websocket updates while the list is actively scrolling */
+    deferUpdates?: boolean;
+    /** minimum interval for batched websocket updates */
+    updateFlushInterval?: number;
 };
 type UsePulseFinalStretchListScriptResult = {
     /** whether tokens are loading */
@@ -168,7 +182,7 @@ type UsePulseFinalStretchListScriptResult = {
     /** token list */
     tokens: Token[];
 };
-declare function usePulseFinalStretchListScript({ chain, filters, isPaused, refetchInterval, }: UsePulseFinalStretchListScriptParams): UsePulseFinalStretchListScriptResult;
+declare function usePulseFinalStretchListScript({ chain, filters, isPaused, refetchInterval, deferUpdates, updateFlushInterval, }: UsePulseFinalStretchListScriptParams): UsePulseFinalStretchListScriptResult;
 
 interface PulseFinalStretchListWidgetProps {
     /** chain id */
@@ -1321,7 +1335,7 @@ interface TokenOrdersListWidgetProps {
 declare function TokenOrdersListWidget({ chain, wallet, tokenAddress, tokenSymbol, limit, initialStateFilter, initialCurrency, nativeSymbol, onCancelAll, renderActions, className, }: TokenOrdersListWidgetProps): react_jsx_runtime.JSX.Element;
 
 interface TokenTopTradersListProps {
-    traders: Array<TokenHolder>;
+    traders: Array<TokenTopTrader>;
     isLoading?: boolean;
     hasMore?: boolean;
     onLoadMore?: () => void;
@@ -1336,10 +1350,7 @@ interface TokenTopTradersListProps {
  * Presentational Top Traders list — visually parallel to
  * {@link TokenHoldersList} but with its own header + filters.
  *
- * The server currently returns the same row shape as holders, ranked by
- * realised PnL; the Realized PnL column stays blank (`—`) until the API
- * adds per-holder PnL fields. When that lands, extend
- * `TokenHolder` with the new fields and wire them into the cells here.
+ * Uses the token top-traders endpoint and its trader-specific PnL fields.
  */
 declare function TokenTopTradersList({ traders, isLoading, hasMore, onLoadMore, onlyTracked, onOnlyTrackedChange, now, renderAddress, className, }: TokenTopTradersListProps): react_jsx_runtime.JSX.Element;
 
@@ -1347,11 +1358,15 @@ interface UseTokenTopTradersListScriptParams {
     chain: Chain;
     address: string;
     limit?: number;
+    /** initial sortBy; undefined means the first request uses server default ordering. */
+    initialSortBy?: TokenTopTradersSortBy;
     initialOnlyTracked?: boolean;
 }
 interface UseTokenTopTradersListScriptResult {
-    traders: Array<TokenHolder>;
+    traders: Array<TokenTopTrader>;
     isLoading: boolean;
+    sortBy: TokenTopTradersSortBy | undefined;
+    setSortBy: (s: TokenTopTradersSortBy) => void;
     hasMore: boolean;
     loadMore: () => void;
     onlyTracked: boolean;
@@ -1360,13 +1375,12 @@ interface UseTokenTopTradersListScriptResult {
 /**
  * Script for the top-traders list widget.
  *
- * Builds on {@link useTokenTopTradersQuery} (bridge over the holders
- * endpoint with `sortBy=realizedPnl`). `onlyTracked` is a client-side
+ * Builds on {@link useTokenTopTradersQuery}. `onlyTracked` is a client-side
  * filter retained for UI parity with Axiom — until the server flags
  * tracked wallets, the toggle narrows visible rows to those whose `tags`
  * list is non-empty (a reasonable proxy for "tracked by someone").
  */
-declare function useTokenTopTradersListScript({ chain, address, limit, initialOnlyTracked, }: UseTokenTopTradersListScriptParams): UseTokenTopTradersListScriptResult;
+declare function useTokenTopTradersListScript({ chain, address, limit, initialSortBy, initialOnlyTracked, }: UseTokenTopTradersListScriptParams): UseTokenTopTradersListScriptResult;
 
 interface TokenTopTradersListWidgetProps {
     chain: Chain;
@@ -1626,24 +1640,30 @@ type TokenListFilterModalProps = Pick<TokenListFilterProps, "protocols" | "resol
     triggerVariant?: "default" | "plain";
     /** active badge placement on the trigger */
     badgePlacement?: "outer" | "icon";
+    /** trigger button className */
+    className?: string;
 };
-declare function TokenListFilterModal({ protocols, resolution, filters, onFiltersChange, triggerVariant, badgePlacement, }: TokenListFilterModalProps): react_jsx_runtime.JSX.Element;
+declare function TokenListFilterModal({ protocols, resolution, filters, onFiltersChange, triggerVariant, badgePlacement, className, }: TokenListFilterModalProps): react_jsx_runtime.JSX.Element;
 
 type TokenListFilterPopoverProps = Pick<PopoverProps, "placement"> & Pick<TokenListFilterProps, "protocols" | "resolution" | "filters" | "onFiltersChange"> & {
     /** whether to render only the filter icon in the trigger */
     iconOnly?: boolean;
+    /** trigger button className */
+    className?: string;
 };
-declare function TokenListFilterPopover({ protocols, resolution, filters, onFiltersChange, iconOnly, }: TokenListFilterPopoverProps): react_jsx_runtime.JSX.Element;
+declare function TokenListFilterPopover({ protocols, resolution, filters, onFiltersChange, iconOnly, className, }: TokenListFilterPopoverProps): react_jsx_runtime.JSX.Element;
 
 type TokenListFilterWidgetProps = TokenListFilterModalProps & {
     /** Popover placement used on non-mobile screens. @default "bottom-end" */
     popoverPlacement?: PopoverProps["placement"];
     /** whether to render only the filter icon in the non-mobile trigger */
     iconOnly?: boolean;
+    /** trigger button className */
+    className?: string;
     /** overlay used on non-mobile screens. @default "popover" */
     desktopOverlay?: "popover" | "modal";
 };
-declare function TokenListFilterWidget({ popoverPlacement, iconOnly, desktopOverlay, ...filterProps }: TokenListFilterWidgetProps): react_jsx_runtime.JSX.Element;
+declare function TokenListFilterWidget({ popoverPlacement, iconOnly, className, desktopOverlay, ...filterProps }: TokenListFilterWidgetProps): react_jsx_runtime.JSX.Element;
 
 declare function TokenListResolutionSelectorDesktop({ resolution, onResolutionChange, resolutionOptions, }: TokenListResolutionSelectorProps): react_jsx_runtime.JSX.Element;
 
@@ -1747,10 +1767,8 @@ type UseNewTokensScriptParams = {
     chain: Chain;
     /** resolution */
     resolution: TokenListResolution;
-    /** fetch tokens options */
+    /** local display options */
     options?: GetTokenListOptions;
-    /** refetch tokens interval */
-    refetchInterval?: number;
     /** defer websocket updates while the list is actively scrolling */
     deferUpdates?: boolean;
     /** minimum interval for batched websocket updates */
@@ -1762,7 +1780,7 @@ type UseNewTokensScriptResult = {
     /** tokens */
     tokens: Array<Token>;
 };
-declare function useNewTokensScript({ chain, resolution, options, refetchInterval, deferUpdates, updateFlushInterval, }: UseNewTokensScriptParams): UseNewTokensScriptResult;
+declare function useNewTokensScript({ chain, options, deferUpdates, updateFlushInterval, }: UseNewTokensScriptParams): UseNewTokensScriptResult;
 
 type NewTokenListWidgetProps = {
     /** chain id */

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType } from 'react';
 import * as _liberfi_io_types from '@liberfi.io/types';
-import { Token, GetTokenListOptions, TokenProtocol, Chain, WalletTag, TokenSocialMedias, TokenHoldersSortBy, TokenHolder, ActivitiesSortBy, Activity, TokenStats, TokenSecurity as TokenSecurity$1, TokenLiquidity, PortfolioPnl, LimitOrderState, LimitOrder, TokenFieldOption } from '@liberfi.io/types';
+import { Token, GetTokenListOptions, TokenProtocol, Chain, WalletTag, TokenSocialMedias, TokenHoldersSortBy, TokenHolder, ActivitiesSortBy, Activity, TokenStats, TokenSecurity as TokenSecurity$1, TokenLiquidity, PortfolioPnl, LimitOrderState, LimitOrder, TokenTopTrader, TokenTopTradersSortBy, TokenFieldOption } from '@liberfi.io/types';
 import * as _tanstack_react_query from '@tanstack/react-query';
 import { PopoverProps } from '@liberfi.io/ui';
 export { formatAmount } from '@liberfi.io/utils';
@@ -23,12 +23,14 @@ interface PulseListProps {
     onSelectToken?: (token: Token) => void;
     /** called when the list should pause/resume adding new items (e.g. mouse hover) */
     onPauseChange?: (isPaused: boolean) => void;
+    /** callback function when the virtualized list scroll state changes */
+    onScrollingChange?: (isScrolling: boolean) => void;
     /** custom styles */
     className?: string;
     /** whether to hide the header */
     hideHeader?: boolean;
 }
-declare function PulseList({ title, tokens, isLoading, itemHeight, renderHeaderExtra, renderItemAction, onSelectToken, onPauseChange, className, hideHeader, }: PulseListProps): react_jsx_runtime.JSX.Element;
+declare function PulseList({ title, tokens, isLoading, itemHeight, renderHeaderExtra, renderItemAction, onSelectToken, onPauseChange, onScrollingChange, className, hideHeader, }: PulseListProps): react_jsx_runtime.JSX.Element;
 
 interface PulseListHeaderProps {
     title: string;
@@ -85,6 +87,10 @@ type UsePulseNewListScriptParams = {
     filters?: TokenListFiltersType;
     /** whether to pause adding new items (existing items still update) */
     isPaused?: boolean;
+    /** defer websocket updates while the list is actively scrolling */
+    deferUpdates?: boolean;
+    /** minimum interval for batched websocket updates */
+    updateFlushInterval?: number;
 };
 type UsePulseNewListScriptResult = {
     /** whether tokens are loading */
@@ -92,7 +98,7 @@ type UsePulseNewListScriptResult = {
     /** token list */
     tokens: Token[];
 };
-declare function usePulseNewListScript({ chain, filters, isPaused, }: UsePulseNewListScriptParams): UsePulseNewListScriptResult;
+declare function usePulseNewListScript({ chain, filters, isPaused, deferUpdates, updateFlushInterval, }: UsePulseNewListScriptParams): UsePulseNewListScriptResult;
 
 interface PulseNewListWidgetProps {
     /** chain id */
@@ -123,6 +129,10 @@ type UsePulseMigratedListScriptParams = {
     isPaused?: boolean;
     /** refetch interval in milliseconds */
     refetchInterval?: number;
+    /** defer websocket updates while the list is actively scrolling */
+    deferUpdates?: boolean;
+    /** minimum interval for batched websocket updates */
+    updateFlushInterval?: number;
 };
 type UsePulseMigratedListScriptResult = {
     /** whether tokens are loading */
@@ -130,7 +140,7 @@ type UsePulseMigratedListScriptResult = {
     /** token list */
     tokens: Token[];
 };
-declare function usePulseMigratedListScript({ chain, filters, isPaused, refetchInterval, }: UsePulseMigratedListScriptParams): UsePulseMigratedListScriptResult;
+declare function usePulseMigratedListScript({ chain, filters, isPaused, refetchInterval, deferUpdates, updateFlushInterval, }: UsePulseMigratedListScriptParams): UsePulseMigratedListScriptResult;
 
 interface PulseMigratedListWidgetProps {
     /** chain id */
@@ -161,6 +171,10 @@ type UsePulseFinalStretchListScriptParams = {
     isPaused?: boolean;
     /** refetch interval in milliseconds */
     refetchInterval?: number;
+    /** defer websocket updates while the list is actively scrolling */
+    deferUpdates?: boolean;
+    /** minimum interval for batched websocket updates */
+    updateFlushInterval?: number;
 };
 type UsePulseFinalStretchListScriptResult = {
     /** whether tokens are loading */
@@ -168,7 +182,7 @@ type UsePulseFinalStretchListScriptResult = {
     /** token list */
     tokens: Token[];
 };
-declare function usePulseFinalStretchListScript({ chain, filters, isPaused, refetchInterval, }: UsePulseFinalStretchListScriptParams): UsePulseFinalStretchListScriptResult;
+declare function usePulseFinalStretchListScript({ chain, filters, isPaused, refetchInterval, deferUpdates, updateFlushInterval, }: UsePulseFinalStretchListScriptParams): UsePulseFinalStretchListScriptResult;
 
 interface PulseFinalStretchListWidgetProps {
     /** chain id */
@@ -1321,7 +1335,7 @@ interface TokenOrdersListWidgetProps {
 declare function TokenOrdersListWidget({ chain, wallet, tokenAddress, tokenSymbol, limit, initialStateFilter, initialCurrency, nativeSymbol, onCancelAll, renderActions, className, }: TokenOrdersListWidgetProps): react_jsx_runtime.JSX.Element;
 
 interface TokenTopTradersListProps {
-    traders: Array<TokenHolder>;
+    traders: Array<TokenTopTrader>;
     isLoading?: boolean;
     hasMore?: boolean;
     onLoadMore?: () => void;
@@ -1336,10 +1350,7 @@ interface TokenTopTradersListProps {
  * Presentational Top Traders list — visually parallel to
  * {@link TokenHoldersList} but with its own header + filters.
  *
- * The server currently returns the same row shape as holders, ranked by
- * realised PnL; the Realized PnL column stays blank (`—`) until the API
- * adds per-holder PnL fields. When that lands, extend
- * `TokenHolder` with the new fields and wire them into the cells here.
+ * Uses the token top-traders endpoint and its trader-specific PnL fields.
  */
 declare function TokenTopTradersList({ traders, isLoading, hasMore, onLoadMore, onlyTracked, onOnlyTrackedChange, now, renderAddress, className, }: TokenTopTradersListProps): react_jsx_runtime.JSX.Element;
 
@@ -1347,11 +1358,15 @@ interface UseTokenTopTradersListScriptParams {
     chain: Chain;
     address: string;
     limit?: number;
+    /** initial sortBy; undefined means the first request uses server default ordering. */
+    initialSortBy?: TokenTopTradersSortBy;
     initialOnlyTracked?: boolean;
 }
 interface UseTokenTopTradersListScriptResult {
-    traders: Array<TokenHolder>;
+    traders: Array<TokenTopTrader>;
     isLoading: boolean;
+    sortBy: TokenTopTradersSortBy | undefined;
+    setSortBy: (s: TokenTopTradersSortBy) => void;
     hasMore: boolean;
     loadMore: () => void;
     onlyTracked: boolean;
@@ -1360,13 +1375,12 @@ interface UseTokenTopTradersListScriptResult {
 /**
  * Script for the top-traders list widget.
  *
- * Builds on {@link useTokenTopTradersQuery} (bridge over the holders
- * endpoint with `sortBy=realizedPnl`). `onlyTracked` is a client-side
+ * Builds on {@link useTokenTopTradersQuery}. `onlyTracked` is a client-side
  * filter retained for UI parity with Axiom — until the server flags
  * tracked wallets, the toggle narrows visible rows to those whose `tags`
  * list is non-empty (a reasonable proxy for "tracked by someone").
  */
-declare function useTokenTopTradersListScript({ chain, address, limit, initialOnlyTracked, }: UseTokenTopTradersListScriptParams): UseTokenTopTradersListScriptResult;
+declare function useTokenTopTradersListScript({ chain, address, limit, initialSortBy, initialOnlyTracked, }: UseTokenTopTradersListScriptParams): UseTokenTopTradersListScriptResult;
 
 interface TokenTopTradersListWidgetProps {
     chain: Chain;
@@ -1626,24 +1640,30 @@ type TokenListFilterModalProps = Pick<TokenListFilterProps, "protocols" | "resol
     triggerVariant?: "default" | "plain";
     /** active badge placement on the trigger */
     badgePlacement?: "outer" | "icon";
+    /** trigger button className */
+    className?: string;
 };
-declare function TokenListFilterModal({ protocols, resolution, filters, onFiltersChange, triggerVariant, badgePlacement, }: TokenListFilterModalProps): react_jsx_runtime.JSX.Element;
+declare function TokenListFilterModal({ protocols, resolution, filters, onFiltersChange, triggerVariant, badgePlacement, className, }: TokenListFilterModalProps): react_jsx_runtime.JSX.Element;
 
 type TokenListFilterPopoverProps = Pick<PopoverProps, "placement"> & Pick<TokenListFilterProps, "protocols" | "resolution" | "filters" | "onFiltersChange"> & {
     /** whether to render only the filter icon in the trigger */
     iconOnly?: boolean;
+    /** trigger button className */
+    className?: string;
 };
-declare function TokenListFilterPopover({ protocols, resolution, filters, onFiltersChange, iconOnly, }: TokenListFilterPopoverProps): react_jsx_runtime.JSX.Element;
+declare function TokenListFilterPopover({ protocols, resolution, filters, onFiltersChange, iconOnly, className, }: TokenListFilterPopoverProps): react_jsx_runtime.JSX.Element;
 
 type TokenListFilterWidgetProps = TokenListFilterModalProps & {
     /** Popover placement used on non-mobile screens. @default "bottom-end" */
     popoverPlacement?: PopoverProps["placement"];
     /** whether to render only the filter icon in the non-mobile trigger */
     iconOnly?: boolean;
+    /** trigger button className */
+    className?: string;
     /** overlay used on non-mobile screens. @default "popover" */
     desktopOverlay?: "popover" | "modal";
 };
-declare function TokenListFilterWidget({ popoverPlacement, iconOnly, desktopOverlay, ...filterProps }: TokenListFilterWidgetProps): react_jsx_runtime.JSX.Element;
+declare function TokenListFilterWidget({ popoverPlacement, iconOnly, className, desktopOverlay, ...filterProps }: TokenListFilterWidgetProps): react_jsx_runtime.JSX.Element;
 
 declare function TokenListResolutionSelectorDesktop({ resolution, onResolutionChange, resolutionOptions, }: TokenListResolutionSelectorProps): react_jsx_runtime.JSX.Element;
 
@@ -1747,10 +1767,8 @@ type UseNewTokensScriptParams = {
     chain: Chain;
     /** resolution */
     resolution: TokenListResolution;
-    /** fetch tokens options */
+    /** local display options */
     options?: GetTokenListOptions;
-    /** refetch tokens interval */
-    refetchInterval?: number;
     /** defer websocket updates while the list is actively scrolling */
     deferUpdates?: boolean;
     /** minimum interval for batched websocket updates */
@@ -1762,7 +1780,7 @@ type UseNewTokensScriptResult = {
     /** tokens */
     tokens: Array<Token>;
 };
-declare function useNewTokensScript({ chain, resolution, options, refetchInterval, deferUpdates, updateFlushInterval, }: UseNewTokensScriptParams): UseNewTokensScriptResult;
+declare function useNewTokensScript({ chain, options, deferUpdates, updateFlushInterval, }: UseNewTokensScriptParams): UseNewTokensScriptResult;
 
 type NewTokenListWidgetProps = {
     /** chain id */