@provex/components 1.2.3

package/dist/index.d.cts

@@ -0,0 +1,601 @@
+import { BoxProps } from '@chakra-ui/react';
+import { Hex } from 'viem';
+import * as React$1 from 'react';
+import React__default, { ReactNode, CSSProperties } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * @fileoverview Card container components.
+ *
+ * Provides styled card containers for content sections with:
+ * - Semantic token support for automatic light/dark mode
+ * - Optional horizontal-rule variant for edge-aligned content
+ * - No border radius for efficient horizontal space usage
+ */
+
+/**
+ * Card component for wrapping content sections.
+ * Features:
+ * - No border radius for better horizontal space usage
+ * - Box shadow instead of border to avoid affecting scrolling behavior
+ * - Configurable padding and background
+ * - Uses Chakra semantic tokens for automatic theming
+ */
+declare function Card(props: BoxProps): JSX.Element;
+/**
+ * Card variant with only top and bottom borders.
+ * Useful for content that should align with full-width elements
+ * without side padding or margins.
+ *
+ * Features:
+ * - Only top and bottom borders (no side borders)
+ * - No side margin to align with container edges
+ * - Configurable padding and background
+ * - Uses Chakra semantic tokens for automatic theming
+ *
+ * @example
+ * ```tsx
+ * <CardHorizontalRule>
+ *   <CurrencyList currencies={currencies} />
+ * </CardHorizontalRule>
+ * ```
+ */
+declare function CardHorizontalRule(props: BoxProps): JSX.Element;
+
+/**
+ * @fileoverview Currency flag icon component.
+ *
+ * Displays a country/region flag representing a fiat currency.
+ * Uses the currency's contractId (keccak256 hash) to look up flag data.
+ */
+
+/**
+ * Display a fiat currency's flag icon in a circular frame.
+ *
+ * Looks up the currency by its contract ID (keccak256 hash of the ticker)
+ * and displays the associated country flag. Falls back to a "?" indicator
+ * for unknown currencies.
+ *
+ * @param currencyId - The currency contract ID (keccak256 hash of ticker like "USD")
+ * @param size - The size of the icon in pixels (default: 16)
+ * @param useZoom - Whether to apply the currency's zoom level for better framing (default: true)
+ *
+ * @example
+ * ```tsx
+ * // Display USD flag
+ * <CurrencyIcon currencyId="0x..." size={24} />
+ * ```
+ */
+declare const CurrencyIcon: ({ currencyId, size, useZoom }: {
+    currencyId: Hex;
+    size?: number;
+    useZoom?: boolean;
+}) => JSX.Element;
+
+/**
+ * @fileoverview Deposit identifier display component.
+ *
+ * Displays a compact deposit identifier showing [chain icon][#id].
+ * Used throughout the UI to identify deposits uniquely across chains.
+ */
+
+/**
+ * Props for DepositIdentifier component.
+ */
+interface DepositIdentifierProps {
+    /** Chain icon element to display */
+    chainIcon: ReactNode;
+    /** @deprecated Version badge has been removed - this prop is ignored */
+    version?: "v2" | "v3";
+    /** The local deposit ID */
+    localId: bigint | number | string;
+    /** @deprecated Version badge has been removed - this prop is ignored */
+    versionBadgeColors?: {
+        bgV2: string;
+        bgV3: string;
+        text: string;
+    };
+    /** Size for each item in the stack (default: 20) */
+    itemSize?: number;
+    /** Gap between items in pixels (default: 2) */
+    gap?: number;
+    /** Text color for the ID (default: inherit) */
+    textColor?: string;
+}
+/**
+ * A compound identifier component that displays [chain][localId] in a compact stack.
+ * Used to uniquely identify deposits across chains.
+ *
+ * @example
+ * ```tsx
+ * <DepositIdentifier
+ *   chainIcon={<ChainIcon chainId={1} size={20} />}
+ *   localId={42}
+ * />
+ * ```
+ */
+declare function DepositIdentifier({ chainIcon, localId, itemSize, gap, textColor, }: DepositIdentifierProps): JSX.Element;
+
+/**
+ * @fileoverview Flag icon component with error handling.
+ *
+ * Displays a flag image in a circular frame with graceful fallback
+ * when the image fails to load. Creates a canvas-based placeholder
+ * showing the first 3 characters of the alt text.
+ */
+
+/**
+ * Props for FlagIcon component.
+ */
+interface FlagIconProps {
+    flag: string;
+    alt?: string;
+    size?: number;
+    className?: string;
+    borderColor?: string;
+}
+/**
+ * Display a flag icon with error handling fallback
+ * @param flag - URL to the flag image
+ * @param alt - Alt text for the image
+ * @param size - Size of the icon in pixels (default: 32)
+ * @param className - Additional CSS class names
+ * @param borderColor - Border color (default: #e5e7eb)
+ */
+declare const FlagIcon: React__default.FC<FlagIconProps>;
+
+/**
+ * @fileoverview Popover component for dropdown menus and tooltips.
+ *
+ * Provides a reusable popover with:
+ * - Automatic positioning to stay within viewport
+ * - Click-outside and Escape key handling
+ * - Header, section, and footer sub-components
+ * - Theme color customization
+ */
+
+/**
+ * Colors required by Popover components.
+ * Pass these from your app's theme context.
+ */
+interface PopoverColors {
+    bgCard: string;
+    border: string;
+    text: string;
+    textMuted: string;
+}
+interface PopoverProps {
+    /** Whether the popover is open */
+    isOpen: boolean;
+    /** Callback when popover should close */
+    onClose: () => void;
+    /** The trigger button */
+    trigger: ReactNode;
+    /** The popover content */
+    children: ReactNode;
+    /** Theme colors */
+    colors: PopoverColors;
+    /** Placement of popover relative to trigger */
+    placement?: "bottom-start" | "bottom-end" | "top-start" | "top-end";
+    /** Width of popover */
+    width?: number;
+    /** Min width of popover */
+    minWidth?: number;
+    /** When true, wrapper uses display:block and dropdown matches trigger width */
+    fullWidth?: boolean;
+    /** Gap in pixels between trigger and dropdown (default: 4) */
+    gap?: number;
+}
+/**
+ * Reusable popover component with positioning and click-outside handling.
+ * Uses fixed positioning to avoid clipping by overflow containers.
+ * @param isOpen - Whether the popover is open
+ * @param onClose - Callback when popover should close
+ * @param trigger - The trigger button element
+ * @param children - The popover content
+ * @param colors - Theme colors for styling
+ * @param placement - Placement relative to trigger (default: "bottom-start")
+ * @param width - Width of popover in pixels
+ * @param minWidth - Min width of popover in pixels (default: 200)
+ */
+declare function Popover({ isOpen, onClose, trigger, children, colors, placement, width, minWidth, fullWidth, gap, }: PopoverProps): JSX.Element;
+interface PopoverHeaderProps {
+    children: ReactNode;
+    colors: Pick<PopoverColors, "text">;
+}
+/**
+ * Popover header component with padding
+ * @param children - Header content
+ * @param colors - Theme colors for styling
+ */
+declare function PopoverHeader({ children, colors }: PopoverHeaderProps): JSX.Element;
+/**
+ * Popover section component for scrollable content.
+ * No padding so scrollbar hugs the edge.
+ * Items inside should have their own padding.
+ * @param children - Section content
+ */
+declare function PopoverSection({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+/**
+ * Popover footer component - no padding so buttons can hug edges
+ * @param children - Footer content
+ */
+declare function PopoverFooter({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+
+/**
+ * @fileoverview Single-select dropdown menu built on the Popover primitive.
+ *
+ * Unified menu component for all select-pattern dropdowns. Supports:
+ * - Default bordered trigger or custom trigger via renderTrigger
+ * - Per-option disabled state and icons
+ * - Consistent sizing: sm (32px) and md (40px) for both triggers and options
+ * - Fixed checkmark column (no layout shift on selection)
+ * - Keyboard navigation (Arrow keys, Enter, Escape)
+ * - ScrollContainer for consistent scrollbar styling
+ */
+
+interface MenuSelectOption<T extends string = string> {
+    value: T;
+    label: string;
+    icon?: ReactNode;
+    isDisabled?: boolean;
+}
+interface MenuSelectColors extends PopoverColors {
+    bg: string;
+}
+/** Trigger render prop args */
+interface MenuSelectTriggerProps {
+    /** Currently selected option (undefined if no selection) */
+    selected: {
+        value: string;
+        label: string;
+        icon?: ReactNode;
+    } | undefined;
+    /** Whether the dropdown is open */
+    isOpen: boolean;
+    /** Whether the control is disabled */
+    isDisabled: boolean;
+}
+interface MenuSelectProps<T extends string = string> {
+    /** Available options */
+    options: MenuSelectOption<T>[];
+    /** Currently selected value (empty string for no selection) */
+    value: T | "";
+    /** Callback when a new value is selected */
+    onChange: (value: T) => void;
+    /** Placeholder text when no value is selected */
+    placeholder?: string;
+    /** Whether the control is disabled */
+    isDisabled?: boolean;
+    /** Theme colors */
+    colors: MenuSelectColors;
+    /** Size variant — controls trigger and option heights uniformly */
+    size?: "sm" | "md";
+    /** Minimum width in pixels */
+    minWidth?: number;
+    /** Maximum dropdown height in pixels (default: 240) */
+    maxDropdownHeight?: number;
+    /** Dropdown placement relative to trigger (default: "bottom-start") */
+    placement?: "bottom-start" | "bottom-end" | "top-start" | "top-end";
+    /**
+     * Custom trigger render prop. When provided, replaces the default bordered
+     * trigger button. The rendered element receives click/keyboard handlers
+     * automatically via wrapper — just return the visual element.
+     */
+    renderTrigger?: (props: MenuSelectTriggerProps) => ReactNode;
+}
+declare function MenuSelect<T extends string = string>({ options, value, onChange, placeholder, isDisabled, colors, size, minWidth, maxDropdownHeight, placement, renderTrigger, }: MenuSelectProps<T>): JSX.Element;
+
+/**
+ * @fileoverview Multi-select filter component with icon stack display.
+ *
+ * A reusable filter pattern for selecting multiple items (currencies, payment methods, etc.)
+ * with a compact button showing selected items as an overlapping icon stack, and a
+ * popover dropdown for making selections.
+ */
+
+/**
+ * Colors required by MultiSelectFilter component.
+ * Pass these from your app's theme context.
+ */
+interface MultiSelectFilterColors extends PopoverColors {
+    bg: string;
+}
+/**
+ * Item with usage count for ordering
+ */
+interface ItemStat<T> {
+    item: T;
+    count: number;
+}
+/**
+ * Props for MultiSelectFilter component
+ */
+interface MultiSelectFilterProps<T extends string> {
+    /** All available item IDs */
+    allItems: Set<T>;
+    /** Currently selected item IDs */
+    selectedItems: Set<T>;
+    /** Callback when selection changes */
+    onSelectionChange: (items: Set<T>) => void;
+    /** Item usage stats for ordering (most used first) - used as fallback if getVolumeRank not provided */
+    itemStats: ItemStat<T>[];
+    /** Render function for item icon in the button's OverlappingStack */
+    renderIcon: (item: T) => ReactNode;
+    /** Render function for item icon in the dropdown list (can be smaller/different) */
+    renderListIcon?: (item: T) => ReactNode;
+    /** Get display label for an item */
+    getLabel: (item: T) => string;
+    /** Title shown in popover header */
+    title: string;
+    /** Theme colors */
+    colors: MultiSelectFilterColors;
+    /** Placeholder text when no items available */
+    placeholder?: string;
+    /** Button min/max width */
+    buttonWidth?: number;
+    /** Icon size in OverlappingStack */
+    iconSize?: number;
+    /** Max icons to show in button */
+    iconLimit?: number;
+    /** Overlap amount for icons */
+    iconOverlap?: number;
+    /** Whether rightmost icons overlap leftmost */
+    reverseZIndex?: boolean;
+    /**
+     * Optional function to get volume rank for an item (lower = more volume).
+     * If provided, items are sorted by volume rank first, then by stats count.
+     * This enables sorting by monthly usage data from MonthlyStatsContext.
+     */
+    getVolumeRank?: (item: T) => number;
+}
+/**
+ * Reusable multi-select filter component with icon stack button and popover.
+ * Used for currencies, payment methods, and similar filter patterns.
+ *
+ * @param allItems - Set of all available item IDs
+ * @param selectedItems - Currently selected item IDs
+ * @param onSelectionChange - Callback when selection changes
+ * @param itemStats - Item usage stats for ordering
+ * @param renderIcon - Render function for item icon in button
+ * @param renderListIcon - Render function for item icon in list (defaults to renderIcon)
+ * @param getLabel - Get display label for an item
+ * @param title - Title shown in popover header
+ * @param colors - Theme colors for styling
+ * @param placeholder - Placeholder when no items (default: title)
+ * @param buttonWidth - Button width (default: 112)
+ * @param iconSize - Icon size in stack (default: 24)
+ * @param iconLimit - Max icons in button (default: 3)
+ * @param iconOverlap - Overlap amount (default: 8)
+ * @param reverseZIndex - Rightmost icons overlap leftmost (default: true)
+ * @param getVolumeRank - Optional function to get volume rank for sorting by monthly data
+ */
+declare function MultiSelectFilter<T extends string>({ allItems, selectedItems, onSelectionChange, itemStats, renderIcon, renderListIcon, getLabel, title, colors, placeholder: _placeholder, buttonWidth, iconSize, iconLimit, iconOverlap, reverseZIndex, getVolumeRank, }: MultiSelectFilterProps<T>): JSX.Element;
+
+/**
+ * Props for OverlappingStack component.
+ */
+interface OverlappingStackProps {
+    /** Array of items to display */
+    items: ReactNode[];
+    /** Maximum items to show before "+X" */
+    limit?: number;
+    /**
+     * Overlap/spacing distance in pixels (default: 8)
+     * - Positive values create overlap (e.g., 8 = items overlap by 8px)
+     * - Zero creates no spacing (items are side-by-side)
+     * - Negative values create spacing (e.g., -2 = 2px gap between items)
+     */
+    overlap?: number;
+    /** Size of each item (for consistent sizing) */
+    itemSize?: number;
+    /**
+     * If true, rightmost items will overlap leftmost items (default: false)
+     * By default, leftmost items overlap rightmost items
+     */
+    reverseZIndex?: boolean;
+}
+/**
+ * Component to display items in an overlapping stack with overflow count.
+ * Useful for showing chain icons, version badges, and IDs in a compact space.
+ *
+ * @param items - Array of ReactNode items to display
+ * @param limit - Maximum items to show (default: 3)
+ * @param overlap - Overlap/spacing distance in pixels (default: 8). Use negative values for spacing.
+ * @param itemSize - Size of each item in pixels (default: 24)
+ * @param reverseZIndex - If true, rightmost items overlap leftmost (default: false)
+ */
+declare function OverlappingStack({ items, limit, overlap, itemSize, reverseZIndex, }: OverlappingStackProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * @fileoverview Combined payment method and currency icon component.
+ *
+ * Displays a composite icon with the currency flag as background and
+ * the payment method icon as a small badge overlay. Used in tables
+ * and lists to show both the payment method and currency in a single
+ * compact visual element.
+ */
+
+/**
+ * Colors required by PaymentCurrencyCombo component.
+ * Pass these from your app's theme context.
+ */
+interface PaymentCurrencyComboColors {
+    bg: string;
+}
+/**
+ * Display a combined payment method and currency icon
+ * Shows currency flag as background with payment provider badge overlay
+ * @param paymentMethodIcon - React node for the payment method icon
+ * @param currencyId - The currency contract ID (keccak256 hash of ticker)
+ * @param size - The height of the container in pixels (default: 20)
+ * @param colors - Theme colors
+ */
+declare const PaymentCurrencyCombo: ({ paymentMethodIcon, currencyId, size, colors, }: {
+    paymentMethodIcon: React__default.ReactNode;
+    currencyId: Hex;
+    size?: number;
+    colors: PaymentCurrencyComboColors;
+}) => JSX.Element;
+
+/**
+ * @fileoverview Payment method icon component.
+ *
+ * Displays payment provider icons (Venmo, Zelle, etc.) using Iconify.
+ * This is a pure rendering component - the host app determines which
+ * icon, color, and properties to display.
+ */
+/**
+ * Props for PaymentMethodIcon component.
+ */
+interface PaymentMethodIconProps {
+    /** Iconify icon identifier (e.g., "simple-icons:zelle") */
+    icon: string;
+    /** Icon color */
+    color?: string;
+    /** Background color for icons that need contrast */
+    backgroundColor?: string;
+    /** Size of the icon in pixels */
+    size?: number;
+    /** Whether this is an unknown/unrecognized payment method */
+    isUnknown?: boolean;
+    /** Tooltip text */
+    tooltip?: string;
+}
+/**
+ * Display a payment method icon using Iconify.
+ * This is a pure rendering component - use your app's payment method
+ * resolution logic to determine the icon, color, and other properties.
+ *
+ * @param icon - Iconify icon identifier (e.g., "simple-icons:zelle", "mdi:credit-card")
+ * @param color - Icon color (default: "#6b7280" for gray)
+ * @param backgroundColor - Optional background color for icons that need contrast (e.g., Revolut white on blue)
+ * @param size - Size of the icon in pixels (default: 16)
+ * @param isUnknown - Whether this is an unknown payment method (shows warning indicator)
+ * @param tooltip - Tooltip text on hover
+ */
+declare function PaymentMethodIcon({ icon, color, backgroundColor, size, isUnknown, tooltip, }: PaymentMethodIconProps): JSX.Element;
+/**
+ * Default icon for unknown payment methods
+ */
+declare const DEFAULT_PAYMENT_ICON = "mdi:credit-card";
+/**
+ * Default color for unknown payment methods
+ */
+declare const DEFAULT_PAYMENT_COLOR = "#6b7280";
+
+type ScrollDirection = "horizontal" | "vertical" | "both";
+declare function injectScrollbarStyles(direction: string): void;
+/** Returns the CSS class name for a given scroll direction. */
+declare function scrollbarClassName(direction: string): string;
+interface ScrollContainerProps {
+    children: ReactNode;
+    /** Scroll direction (default: "both") */
+    direction?: ScrollDirection;
+    /** Container height */
+    height?: number | string;
+    /** Maximum container height */
+    maxHeight?: number | string;
+    /** Container width */
+    width?: number | string;
+    /** Use negative margin to extend scrollbar to parent edges */
+    extendToEdges?: boolean;
+    /** Padding value when extendToEdges is true (default: 16) */
+    edgePadding?: number;
+    /** Additional CSS class name */
+    className?: string;
+    /** Additional inline styles */
+    style?: CSSProperties;
+    /** Scroll event handler */
+    onScroll?: (e: React.UIEvent<HTMLDivElement>) => void;
+    /** Controlled scroll position (0 to 1) for synchronized scrolling */
+    scrollPosition?: number;
+    /** Callback when scroll position changes (0 to 1) */
+    onScrollPositionChange?: (position: number) => void;
+    /** Scroll to end on initial mount */
+    scrollToEnd?: boolean;
+    /** Scrollbar position (default: "right") */
+    scrollbarPosition?: "left" | "right";
+}
+declare const ScrollContainer: React$1.ForwardRefExoticComponent<ScrollContainerProps & React$1.RefAttributes<HTMLDivElement>>;
+
+/**
+ * @fileoverview Tooltip component for hover hints.
+ *
+ * Simple hover tooltip with automatic top/bottom placement.
+ * Uses inline positioning — no portal or z-index layering required.
+ */
+
+interface TooltipProps {
+    /** Text shown in the tooltip */
+    label: string;
+    children: ReactNode;
+    /** Suppress the tooltip entirely */
+    isDisabled?: boolean;
+    /** Preferred placement relative to the trigger (default: "top") */
+    placement?: "top" | "bottom";
+    /**
+     * CSS display mode for the wrapper span.
+     * - "inline-flex" (default): wraps tightly around inline children
+     * - "flex" or "block": takes full width — use for block-level children
+     * - "contents": wrapper is invisible to layout — children render as if unwrapped
+     */
+    display?: CSSProperties["display"];
+}
+/**
+ * Wraps any element and shows a tooltip on hover.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip label="Loaded from: https://rpc.pulsechain.com">
+ *   <Badge>RPC</Badge>
+ * </Tooltip>
+ * ```
+ */
+declare function Tooltip({ label, children, isDisabled, placement, display }: TooltipProps): JSX.Element;
+
+/**
+ * @fileoverview Version badge component.
+ *
+ * Displays a small badge indicating the protocol version (v2 or v3).
+ * Used to visually distinguish deposits and transactions from different
+ * protocol versions.
+ */
+
+/**
+ * Color props for VersionBadge component.
+ * Pass these from your app's theme context.
+ */
+interface VersionBadgeColors {
+    /** Background color for v2 version */
+    bgV2: string;
+    /** Background color for v3 version */
+    bgV3: string;
+    /** Text color */
+    text: string;
+}
+type Version = "v2" | "v3";
+/**
+ * VersionBadge displays the protocol version (v2 or v3) as a small badge.
+ * Use this to indicate which version of the zkp2p protocol a deposit or
+ * transaction belongs to.
+ *
+ * @example
+ * ```tsx
+ * <VersionBadge version="v3" colors={themeColors} />
+ * ```
+ */
+declare function VersionBadge(props: {
+    /** The protocol version to display */
+    version: Version;
+    /** Color configuration for the badge */
+    colors: VersionBadgeColors;
+    /** Optional additional styles */
+    style?: React__default.CSSProperties;
+}): JSX.Element;
+
+export { Card, CardHorizontalRule, CurrencyIcon, DEFAULT_PAYMENT_COLOR, DEFAULT_PAYMENT_ICON, DepositIdentifier, type DepositIdentifierProps, FlagIcon, type ItemStat, MenuSelect, type MenuSelectColors, type MenuSelectOption, type MenuSelectProps, type MenuSelectTriggerProps, MultiSelectFilter, type MultiSelectFilterColors, type MultiSelectFilterProps, OverlappingStack, type OverlappingStackProps, PaymentCurrencyCombo, type PaymentCurrencyComboColors, PaymentMethodIcon, type PaymentMethodIconProps, Popover, type PopoverColors, PopoverFooter, PopoverHeader, type PopoverHeaderProps, type PopoverProps, PopoverSection, ScrollContainer, type ScrollContainerProps, Tooltip, type TooltipProps, type Version, VersionBadge, type VersionBadgeColors, injectScrollbarStyles, scrollbarClassName };