@gearbox-protocol/ui-kit 3.4.0 → 3.5.0

package/dist/types/components/composites/index.d.ts

@@ -0,0 +1 @@
+export * from './pool-table';

package/dist/types/components/composites/pool-table/columns.d.ts

@@ -0,0 +1,98 @@
+import { PoolDTO, PoolTableCellContext, PoolTableColumnDef } from './types';
+import type * as React from "react";
+/**
+ * Pool name column — displays token icon, pool name and optional description.
+ *
+ * Used in both charts and client-v3.
+ */
+export declare function poolColumn<P extends PoolDTO = PoolDTO>(options?: {
+    header?: React.ReactNode;
+    renderDescription?: (ctx: PoolTableCellContext<P>) => React.ReactNode;
+    /** Custom pool name formatter. Defaults to "TOKEN vN" for v3 pools. */
+    getPoolName?: (ctx: PoolTableCellContext<P>) => string;
+    width?: string;
+}): PoolTableColumnDef<P>;
+/**
+ * Total supply column — shows total expected liquidity in USD and native token.
+ *
+ * Used in both charts and client-v3.
+ */
+export declare function supplyColumn<P extends PoolDTO = PoolDTO>(options?: {
+    header?: React.ReactNode;
+    width?: string;
+    sortField?: string;
+    hideOnMedium?: boolean;
+}): PoolTableColumnDef<P>;
+/**
+ * Supply APY column — shows compound APY with tooltip breakdown.
+ *
+ * Used in both charts and client-v3.
+ */
+export declare function supplyApyColumn<P extends PoolDTO = PoolDTO>(options?: {
+    header?: React.ReactNode;
+    headerTip?: React.ReactNode;
+    width?: string;
+    sortField?: string;
+}): PoolTableColumnDef<P>;
+/**
+ * Total borrowed column — shows total borrowed in USD and native token.
+ *
+ * Used in both charts and client-v3.
+ */
+export declare function borrowedColumn<P extends PoolDTO = PoolDTO>(options?: {
+    header?: React.ReactNode;
+    width?: string;
+}): PoolTableColumnDef<P>;
+/**
+ * Borrow APY column — formatted borrow rate (`percentageTemplate`: **basis points**, 10_000 = 100%).
+ *
+ * Prefer `pool.borrowAPY` when the backend (or adapter) fills it; otherwise pass `getBorrowRate`.
+ */
+export declare function borrowApyColumn<P extends PoolDTO = PoolDTO>(options?: {
+    header?: React.ReactNode;
+    headerTip?: React.ReactNode;
+    width?: string;
+    /** Custom getter for borrow rate (basis points). Used when `pool.borrowAPY` is undefined. */
+    getBorrowRate?: (pool: P) => number;
+}): PoolTableColumnDef<P>;
+/**
+ * Utilization column — `pool.utilization` (0–100) with a progress bar.
+ */
+export declare function utilizationColumn<P extends PoolDTO = PoolDTO>(options?: {
+    header?: React.ReactNode;
+    width?: string;
+    sortField?: string;
+}): PoolTableColumnDef<P>;
+/**
+ * Collateral / assets column — shows a list of collateral asset icons.
+ *
+ * Default: reads `pool.collateralTokens` and renders {@link AssetsListCell}.
+ * Override with `cell` / `mobileCell` for custom asset shapes (e.g. client-v3 quota objects).
+ */
+export declare function collateralColumn<P extends PoolDTO = PoolDTO>(options?: {
+    header?: React.ReactNode;
+    width?: string;
+    gapBefore?: "sm" | "md" | "none";
+    cell?: (ctx: PoolTableCellContext<P>) => React.ReactNode;
+    mobileCell?: (ctx: PoolTableCellContext<P>) => React.ReactNode;
+    align?: "left" | "right";
+    /** @default 5 */
+    maxAssets?: number;
+}): PoolTableColumnDef<P>;
+/**
+ * User balance column (client-v3 style) — USD + amount in pool token.
+ *
+ * Default: `pool.userBalanceInUSD`, `pool.userBalance`, `pool.poolTokenSymbol` (and underlying decimals for formatting).
+ */
+export declare function balanceColumn<P extends PoolDTO = PoolDTO>(options?: {
+    header?: React.ReactNode;
+    width?: string;
+    className?: string;
+    headerClassName?: string;
+    sortField?: string;
+    cell?: (ctx: PoolTableCellContext<P>) => React.ReactNode;
+}): PoolTableColumnDef<P>;
+/**
+ * Generic custom column — convenience helper to create a column with minimal boilerplate.
+ */
+export declare function customColumn<P extends PoolDTO = PoolDTO>(def: PoolTableColumnDef<P>): PoolTableColumnDef<P>;

package/dist/types/components/composites/pool-table/index.d.ts

@@ -0,0 +1,3 @@
+export { balanceColumn, borrowApyColumn, borrowedColumn, collateralColumn, customColumn, poolColumn, supplyApyColumn, supplyColumn, utilizationColumn, } from './columns';
+export { PoolTable } from './pool-table';
+export type { PoolApyDTO, PoolDTO, PoolTableCellContext, PoolTableColumnDef, PoolTableColumnSortDef, PoolTableColumnSortState, PoolTableProps, PoolTableRowDTO, } from './types';

package/dist/types/components/composites/pool-table/pool-table-backend-contract.types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Pool Table — Backend API Contract
+ * ==================================
+ *
+ * Self-contained type definitions for the pool-list endpoint response.
+ * The client maps this response 1-to-1 into the `PoolTable` component from
+ * `@gearbox-protocol/ui-kit`.
+ *
+ * Copy this file into your backend repo — it has **zero npm dependencies**.
+ *
+ * ## Quick start
+ *
+ * Implement one endpoint that returns {@link PoolTableListResponse}.
+ *
+ * ## JSON serialization
+ *
+ * - `bigint` fields → decimal **strings** (`"13190000000000000000000000"`).
+ *   The client converts them back via `BigInt(value)`.
+ * - `Address` → `0x`-prefixed hex string, lower-case preferred.
+ *
+ * @packageDocumentation
+ */
+type Address = `0x${string}`;
+/**
+ * ```jsonc
+ * GET /v1/pools?chainIds=1,42161&wallet=0x…
+ * {
+ *   "tokens": { "0xabc…": { "symbol":"USDC", "title":"USDC", "decimals":6 } },
+ *   "rows": [ … ]
+ * }
+ * ```
+ */
+export interface PoolTableListResponse {
+    /** One entry per pool visible in the table. */
+    rows: PoolTableRowDTO[];
+    /**
+     * Global token dictionary shared by all rows.
+     * Must contain **at least** every `underlyingToken`, every address in
+     * `collateralTokens`, and every `rewardToken` from `apy.extraAPY`.
+     *
+     * Key = lower-case token address.
+     */
+    tokens: Record<Address, TokenMetaDTO>;
+}
+export interface PoolTableRowDTO {
+    pool: PoolDTO;
+    /** Supply / deposit APY breakdown (column + tooltip). */
+    apy?: PoolApyDTO | null;
+    /** Points / rewards for the APY tooltip. `null` or `[]` = no points. */
+    points?: PoolApyPointDTO[] | null;
+    chainId: number;
+    /** Deep-link to pool detail page (client can also build this locally). */
+    href?: string;
+}
+export interface PoolDTO {
+    address: Address;
+    underlyingToken: Address;
+    /** Display name, e.g. "USDC v3". */
+    name?: string;
+    /** Semver-like integer: 300 = v3, 310 = v3.1, etc. */
+    version?: number;
+    /** Human-readable network label, e.g. "Mainnet", "Arbitrum". */
+    network?: string;
+    chainId?: number;
+    /** Market configurator address (rendered as curator badge). */
+    marketConfigurator?: Address;
+    /** Total supplied liquidity in underlying token (bigint → string in JSON). */
+    expectedLiquidity?: bigint;
+    /** Same value converted to USD. */
+    expectedLiquidityInUSD?: number;
+    /** Total borrowed in underlying token (bigint → string in JSON). */
+    totalBorrowed?: bigint;
+    /** Same value converted to USD. */
+    totalBorrowedInUSD?: number;
+    /** Utilization ratio, 0–100 (percent). */
+    utilization?: number;
+    /** Base deposit APY, already in **percent** (e.g. `5.2` = 5.2%). */
+    depositAPY?: number;
+    /**
+     * Borrow rate for the "Borrow APY" column.
+     * Unit: **basis points** (10 000 = 100%).
+     */
+    borrowAPY?: number;
+    /** Active collateral token addresses for the "Collateral" column. */
+    collateralTokens?: Address[];
+    /** User's pool position value in USD ("Your Balance" column). */
+    userBalanceInUSD?: number;
+    /** User's position amount in pool/deposit token (bigint → string). */
+    userBalance?: bigint;
+    /** Pool deposit token symbol, e.g. `"edgeUSDC"`. */
+    poolTokenSymbol?: string;
+    /** `true` when the pool has active points/rewards (shows indicator icon). */
+    hasPoints?: boolean;
+}
+export interface PoolApyDTO {
+    /** Total combined supply APY in percent (`8.33` = 8.33%). */
+    totalAPY: number;
+    baseAPY: PoolBaseApyDTO[];
+    extraAPY: PoolExtraRewardApyDTO[];
+    externalAPY?: PoolExternalApyDTO;
+    /** Snapshot from 7 days ago (for 1D / 7D comparison in tooltip). */
+    apy7DAgo?: PoolApy7DaysAgoDTO;
+}
+export interface PoolBaseApyDTO {
+    type: "supplyAPY" | "tokenYield";
+    /** Already in percent. */
+    apy: number;
+}
+export interface PoolExtraRewardApyDTO {
+    /** Extra reward APY in percent. */
+    apy: number;
+    /** Reward token address (hex). */
+    rewardToken: string;
+    /** Reward token ticker, e.g. "ARB", "GEAR". */
+    rewardTokenSymbol: string;
+}
+export interface PoolExternalApyDTO {
+    totalValue: number;
+    value?: number;
+    /** Source name, e.g. "Curve". */
+    name: string;
+    /** i18n key or free-form string for tooltip. */
+    tooltip?: string;
+}
+export interface PoolApy7DaysAgoDTO {
+    totalAPY?: number;
+    baseAPY?: PoolBaseApyDTO[];
+    extraAPY?: PoolExtraRewardApyDTO[];
+    externalAPY?: PoolExternalApyDTO;
+}
+export interface PoolApyPointDTO {
+    /** Formatted amount string, e.g. "2.5x". */
+    amount: string;
+    /** Program / reward name, e.g. "Gearbox Points". */
+    name: string;
+    /** Token title for icon lookup. */
+    tokenTitle?: string;
+    /** Full tooltip text (already formatted, UI-ready). */
+    fullTip: string;
+    reward?: PoolApyPointRewardHintDTO;
+}
+export interface PoolApyPointRewardHintDTO {
+    duration?: string;
+    condition?: string;
+    name?: string;
+    type?: string;
+}
+export interface TokenMetaDTO {
+    /** Ticker, e.g. "USDC". */
+    symbol: string;
+    /** Human-readable name, e.g. "USD Coin". */
+    title?: string;
+    /** URL or static asset path for the token icon. */
+    icon?: string;
+    /** Full token name (rarely different from title). */
+    name?: string;
+    /** Token decimals — required for correct amount formatting on the client. */
+    decimals: number;
+}
+export {};

package/dist/types/components/composites/pool-table/pool-table.d.ts

@@ -0,0 +1,32 @@
+import { PoolDTO, PoolTableProps } from './types';
+/**
+ * PoolTable — configurable pool table constructor component.
+ *
+ * Accepts an array of column definitions (built-in + custom) and row data.
+ * Handles loading skeletons, error states, empty states, mobile layout,
+ * and partial loading out of the box.
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   PoolTable,
+ *   poolColumn,
+ *   supplyColumn,
+ *   supplyApyColumn,
+ *   borrowedColumn,
+ *   utilizationColumn,
+ *   customColumn,
+ * } from "@gearbox-protocol/ui-kit";
+ *
+ * const columns = [
+ *   poolColumn({ renderDescription: (ctx) => <Curator ... /> }),
+ *   supplyColumn(),
+ *   supplyApyColumn(),
+ *   borrowedColumn(),
+ *   utilizationColumn(),
+ * ];
+ *
+ * <PoolTable columns={columns} rows={rows} loading={isLoading} sort={sort} />
+ * ```
+ */
+export declare function PoolTable<P extends PoolDTO = PoolDTO>({ columns, rows, loading, partialLoading, error, emptyContent, skeletonRows, rowHeight, size, mobileColumnsXs, mobileColumnsMd, className, wrapperClassName, sort, }: PoolTableProps<P>): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/components/composites/pool-table/types.d.ts

@@ -0,0 +1,127 @@
+import { Address } from 'viem';
+import { ExternalAPYData, ExtraRewardApy, PoolBaseAPY } from '../../compound-apy';
+import { SortDirection } from '../../head-cell';
+import { PoolAPYPointsTip } from '../../pool-apy-tooltip';
+import { TokenMetaInfo } from '../../../types/common';
+import type * as React from "react";
+export interface PoolDTO {
+    address: Address;
+    underlyingToken: Address;
+    /** Display name, e.g. "USDC v3". */
+    name?: string;
+    /** Semver-like integer: 300 = v3, 310 = v3.1, etc. */
+    version?: number;
+    /** Human-readable network label (e.g. "Mainnet", "Arbitrum"). */
+    network?: string;
+    chainId?: number;
+    /** Market configurator address (curator badge in client-v3). */
+    marketConfigurator?: Address;
+    expectedLiquidity?: bigint;
+    expectedLiquidityInUSD?: number;
+    totalBorrowed?: bigint;
+    totalBorrowedInUSD?: number;
+    /** Utilization ratio, 0–100 (percent). */
+    utilization?: number;
+    /** Deposit APY (already percent). */
+    depositAPY?: number;
+    /**
+     * Borrow rate for the Borrow APY column.
+     * **Basis points** (10_000 = 100%), compatible with `percentageTemplate`.
+     */
+    borrowAPY?: number;
+    /** Active collateral token addresses. */
+    collateralTokens?: Address[];
+    /** User position in this pool — USD. */
+    userBalanceInUSD?: number;
+    /** User position — amount in pool/deposit token. */
+    userBalance?: bigint;
+    /** Pool / deposit token symbol (e.g. "edgeUSDC"). */
+    poolTokenSymbol?: string;
+    /** Whether this pool has active points/rewards (shows indicator icon). */
+    hasPoints?: boolean;
+}
+export interface PoolApyDTO {
+    totalAPY: number;
+    baseAPY: Array<PoolBaseAPY>;
+    extraAPY: Array<ExtraRewardApy>;
+    externalAPY?: ExternalAPYData;
+    /** Snapshot from 7 days ago (1D / 7D comparison in tooltip). */
+    apy7DAgo?: {
+        totalAPY?: number;
+        baseAPY?: Array<PoolBaseAPY>;
+        extraAPY?: Array<ExtraRewardApy>;
+        externalAPY?: ExternalAPYData;
+        loading7DAgo?: boolean;
+    };
+}
+export interface PoolTableCellContext<P extends PoolDTO = PoolDTO> {
+    pool: P;
+    tokensList: Record<Address, TokenMetaInfo> | undefined;
+    /** Underlying token meta (resolved from `pool.underlyingToken`). */
+    underlyingToken: TokenMetaInfo | undefined;
+    apy: PoolApyDTO | undefined;
+    /** Points / rewards data for tooltip. */
+    points: Array<PoolAPYPointsTip> | undefined;
+    /** Whether prices are still loading. */
+    loading?: boolean;
+    chainId: number;
+    /** Whether the current viewport is mobile. */
+    isMobile?: boolean;
+}
+export interface PoolTableColumnSortDef {
+    field: string;
+    defaultDirection?: "asc" | "desc";
+}
+export interface PoolTableColumnDef<P extends PoolDTO = PoolDTO> {
+    id: string;
+    header: React.ReactNode | ((sort: PoolTableColumnSortState | undefined) => React.ReactNode);
+    headerTip?: React.ReactNode;
+    headerClassName?: string;
+    cell: (ctx: PoolTableCellContext<P>) => React.ReactNode;
+    mobileCell?: (ctx: PoolTableCellContext<P>) => React.ReactNode;
+    mobileTitle?: React.ReactNode;
+    hideOnMobile?: boolean;
+    width?: string;
+    align?: "left" | "right" | "center";
+    gapBefore?: "sm" | "md" | "none";
+    sort?: PoolTableColumnSortDef;
+    hideOnMedium?: boolean;
+    className?: string;
+}
+export interface PoolTableColumnSortState {
+    direction: SortDirection;
+    onSort: () => void;
+}
+export interface PoolTableRowDTO<P extends PoolDTO = PoolDTO> {
+    pool: P;
+    tokensList: Record<Address, TokenMetaInfo> | undefined;
+    apy: PoolApyDTO | undefined;
+    points: Array<PoolAPYPointsTip> | undefined;
+    chainId: number;
+    href?: string;
+    loading?: boolean;
+}
+export interface PoolTableProps<P extends PoolDTO = PoolDTO> {
+    columns: Array<PoolTableColumnDef<P>>;
+    rows: Array<PoolTableRowDTO<P>> | undefined;
+    loading?: boolean;
+    partialLoading?: boolean;
+    error?: Error | null;
+    emptyContent?: React.ReactNode;
+    skeletonRows?: number;
+    rowHeight?: number;
+    size?: "sm" | "default" | "lg";
+    /** @default 3 */
+    mobileColumnsXs?: number;
+    /** @default 3 */
+    mobileColumnsMd?: number;
+    className?: string;
+    wrapperClassName?: string;
+    sort?: {
+        state: {
+            field: string;
+            sort: "asc" | "desc";
+        } | null;
+        set: (field: string, startFromSort?: "asc" | "desc") => void;
+    };
+}

package/dist/types/components/index.d.ts

@@ -24,6 +24,7 @@ export * from './checkbox-item';
 export * from './client-adapters';
 export * from './colored-text';
 export * from './complex-input';
+export * from './composites';
 export type { ExternalAPYData, ExtraRewardApy, PoolBaseAPY, } from './compound-apy';
 export * from './compound-apy';
 export * from './confirm-menu';

package/dist/types/index.d.ts

@@ -24,6 +24,7 @@ export * from './components/checkbox';
 export * from './components/client-adapters';
 export * from './components/colored-text';
 export * from './components/complex-input';
+export * from './components/composites';
 export * from './components/compound-apy';
 export * from './components/confirm-menu';
 export * from './components/credit-session-status';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gearbox-protocol/ui-kit",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Internal UI components",
   "repository": "https://github.com/gearbox-protocol/ui-kit",
   "license": "MIT",