@0xsequence/marketplace-sdk 1.2.0 → 2.0.0

package/src/react/ui/components/marketplace-collectible-card/utils/formatPrice.ts

@@ -1,17 +1,18 @@
 import { formatUnits } from 'viem';
+import type { Currency } from '../../../../_internal';
 
 export const OVERFLOW_PRICE = 100000000;
 export const UNDERFLOW_PRICE = 0.0001;
 
 export const formatPriceNumber = (
-	amount: string,
+	amount: bigint,
 	decimals: number,
 ): {
 	formattedNumber: string;
 	isUnderflow: boolean;
 	isOverflow: boolean;
 } => {
-	const formattedPrice = formatUnits(BigInt(amount), decimals);
+	const formattedPrice = formatUnits(amount, decimals);
 	const numericPrice = Number.parseFloat(formattedPrice);
 
 	if (numericPrice < UNDERFLOW_PRICE) {
@@ -43,3 +44,71 @@ export const formatPriceNumber = (
 		isOverflow: false,
 	};
 };
+
+/**
+ * Formatted price data structure
+ */
+export type FormattedPrice = {
+	/** Price type determines the presentation style */
+	type: 'free' | 'underflow' | 'overflow' | 'normal';
+	/** Formatted display text (e.g., "0.0001", "100,000,000") */
+	displayText: string;
+	/** Currency symbol (e.g., "ETH", "USDC") */
+	symbol: string;
+};
+
+/**
+ * Formats price data into a structured object for presentation.
+ * This pure data transformation function is easily testable and
+ * separates business logic from UI concerns.
+ *
+ * @param amount - Raw amount bigint (in base units)
+ * @param currency - Currency object with symbol and decimals
+ * @returns FormattedPrice object for presentation layer
+ *
+ * @example
+ * ```ts
+ * const priceData = formatPriceData(1000000000000000000n, {
+ *   symbol: 'ETH',
+ *   decimals: 18
+ * });
+ * // Returns: { type: 'normal', displayText: '1', symbol: 'ETH' }
+ * ```
+ */
+export function formatPriceData(
+	amount: bigint,
+	currency: Currency,
+): FormattedPrice {
+	const isFree = amount === 0n;
+
+	if (isFree) {
+		return { type: 'free', displayText: 'Free', symbol: '' };
+	}
+
+	const { formattedNumber, isUnderflow, isOverflow } = formatPriceNumber(
+		amount,
+		currency.decimals,
+	);
+
+	if (isUnderflow) {
+		return {
+			type: 'underflow',
+			displayText: formattedNumber,
+			symbol: currency.symbol,
+		};
+	}
+
+	if (isOverflow) {
+		return {
+			type: 'overflow',
+			displayText: formattedNumber,
+			symbol: currency.symbol,
+		};
+	}
+
+	return {
+		type: 'normal',
+		displayText: formattedNumber,
+		symbol: currency.symbol,
+	};
+}

package/src/react/ui/components/marketplace-collectible-card/utils/index.ts

@@ -1,2 +1,5 @@
+export * from './determineCardAction';
 export * from './formatPrice';
+export * from './renderSkeleton';
+export * from './shopCardState';
 export * from './supplyStatus';

package/src/react/ui/components/marketplace-collectible-card/utils/renderSkeleton.tsx

@@ -0,0 +1,44 @@
+import type { ContractType } from '@0xsequence/api-client';
+import { Card } from '../Card';
+
+/**
+ * Determines whether to render a skeleton loading state for a card
+ * and returns the skeleton component if appropriate.
+ *
+ * @param params - Loading state parameters
+ * @param params.cardLoading - Whether the card data is loading
+ * @param params.balanceIsLoading - Whether the balance data is loading (optional)
+ * @param params.collectionType - Type of collection (ERC721/ERC1155)
+ * @param params.isShop - Whether this is a shop card variant
+ * @returns Skeleton component if loading, null otherwise
+ *
+ * @example
+ * ```tsx
+ * const skeleton = renderSkeletonIfLoading({
+ *   cardLoading,
+ *   balanceIsLoading,
+ *   collectionType,
+ *   isShop: false
+ * });
+ * if (skeleton) return skeleton;
+ * ```
+ */
+export function renderSkeletonIfLoading(params: {
+	cardLoading: boolean;
+	balanceIsLoading?: boolean;
+	collectionType: ContractType | undefined;
+	isShop: boolean;
+}): React.ReactElement | null {
+	const {
+		cardLoading,
+		balanceIsLoading = false,
+		collectionType,
+		isShop,
+	} = params;
+
+	if (cardLoading || balanceIsLoading) {
+		return <Card.Skeleton type={collectionType} isShop={isShop} />;
+	}
+
+	return null;
+}

package/src/react/ui/components/marketplace-collectible-card/utils/shopCardState.ts

@@ -0,0 +1,83 @@
+import type { Address } from '@0xsequence/api-client';
+import { ContractType } from '@0xsequence/api-client';
+
+export type ShopCardStateParams = {
+	quantityRemaining?: bigint;
+	quantityInitial?: bigint;
+	unlimitedSupply?: boolean;
+	collectionType?: ContractType;
+	salesContractAddress?: Address;
+};
+
+export type ShopCardState = {
+	isOutOfStock: boolean;
+	isMissingStockInfo: boolean;
+	showActionButton: boolean;
+	mediaClassName: string;
+	titleClassName: string | undefined;
+};
+
+/**
+ * Calculates the display state for a shop card based on stock availability
+ *
+ * @param params - Stock and collection parameters
+ * @returns Computed state for visual styling and interaction
+ *
+ * @example
+ * ```tsx
+ * const shopState = getShopCardState({
+ *   quantityRemaining: '5',
+ *   quantityInitial: '100',
+ *   unlimitedSupply: false,
+ *   collectionType: ContractType.ERC1155,
+ *   salesContractAddress: '0x...'
+ * });
+ *
+ * // Use computed state
+ * <Card.Media className={shopState.mediaClassName} />
+ * <Card.Title className={shopState.titleClassName} />
+ * <Card.Actions show={shopState.showActionButton} />
+ * ```
+ */
+export function getShopCardState(params: ShopCardStateParams): ShopCardState {
+	const {
+		quantityRemaining,
+		quantityInitial,
+		unlimitedSupply,
+		collectionType,
+		salesContractAddress,
+	} = params;
+
+	// Check if item is out of stock
+	const isOutOfStock =
+		!unlimitedSupply &&
+		(quantityRemaining === 0n || quantityRemaining === undefined);
+
+	// Check if stock information is missing
+	const isMissingStockInfo =
+		quantityInitial === undefined || quantityRemaining === undefined;
+
+	// Show action button only if:
+	// 1. Sales contract exists
+	// 2. Collection is ERC1155
+	// 3. Either unlimited supply OR has remaining quantity
+	const showActionButton =
+		!!salesContractAddress &&
+		collectionType === ContractType.ERC1155 &&
+		(unlimitedSupply ||
+			(quantityRemaining !== undefined && quantityRemaining > 0n));
+
+	// Styling for out of stock items
+	const mediaClassName = isOutOfStock ? 'opacity-50' : 'opacity-100';
+
+	// Styling for items with missing stock info
+	const titleClassName = isMissingStockInfo ? 'text-text-50' : undefined;
+
+	return {
+		isOutOfStock,
+		isMissingStockInfo,
+		showActionButton,
+		mediaClassName,
+		titleClassName,
+	};
+}

package/src/react/ui/components/marketplace-collectible-card/utils/supplyStatus.ts

@@ -1,11 +1,11 @@
-import { ContractType } from '../../../../_internal';
+import { ContractType } from '@0xsequence/api-client';
 
 export const getSupplyStatusText = ({
 	quantityRemaining,
 	collectionType,
 	unlimitedSupply,
 }: {
-	quantityRemaining: string | undefined;
+	quantityRemaining: bigint | undefined;
 	collectionType: ContractType;
 	unlimitedSupply?: boolean;
 }): string => {
@@ -23,13 +23,13 @@ export const getSupplyStatusText = ({
 	if (
 		collectionType === ContractType.ERC1155 &&
 		!unlimitedSupply &&
-		quantityRemaining === '0'
+		quantityRemaining === 0n
 	) {
 		return 'Out of stock';
 	}
 
-	if (quantityRemaining && Number(quantityRemaining) > 0) {
-		return `Supply: ${quantityRemaining}`;
+	if (quantityRemaining && quantityRemaining > 0n) {
+		return `Supply: ${quantityRemaining.toString()}`;
 	}
 
 	return 'Out of stock';

package/src/react/ui/components/marketplace-collectible-card/variants/MarketCard.tsx

@@ -1,20 +1,36 @@
 'use client';
 
-import { CollectibleCardAction } from '../../../../../types';
-import type { ContractType } from '../../../../_internal';
-import { ActionButtonWrapper } from '../components/ActionButtonWrapper';
-import { BaseCard } from '../components/BaseCard';
-import { Footer } from '../components/footer';
+import type { ContractType } from '@0xsequence/api-client';
+import { useCurrency } from '../../../../hooks/currency/currency';
 import type { MarketCollectibleCardProps } from '../types';
+import { determineCardAction, renderSkeletonIfLoading } from '../utils';
+import { MarketCardPresentation } from './MarketCardPresentation';
 
+/**
+ * MarketCard - Smart component with built-in data fetching
+ *
+ * This component handles currency fetching and action determination automatically.
+ * Use this for convenient plug-and-play integration.
+ *
+ * For full control over data fetching (e.g., SSR/SSG), use MarketCardPresentation instead.
+ *
+ * @example
+ * ```tsx
+ * <MarketCard
+ *   tokenId="123"
+ *   chainId={1}
+ *   collectionAddress="0x..."
+ *   collectible={collectible}
+ * />
+ * ```
+ */
 export function MarketCard({
-	collectibleId,
+	tokenId,
 	chainId,
 	collectionAddress,
 	collectionType,
 	assetSrcPrefixUrl,
 	cardLoading,
-	orderbookKind,
 	collectible,
 	onCollectibleClick,
 	onOfferClick,
@@ -23,94 +39,63 @@ export function MarketCard({
 	onCannotPerformAction,
 	prioritizeOwnerActions,
 	hideQuantitySelector,
+	classNames,
 }: MarketCollectibleCardProps) {
 	const collectibleMetadata = collectible?.metadata;
 	const highestOffer = collectible?.offer;
 	const lowestListing = collectible?.listing;
 
+	// Fetch currency details for the listing price
+	const { data: currency } = useCurrency({
+		chainId,
+		currencyAddress: lowestListing?.priceCurrencyAddress,
+		query: {
+			enabled: !!lowestListing?.priceCurrencyAddress,
+		},
+	});
+
 	if (!collectibleMetadata) {
 		console.error('Collectible metadata is undefined');
 		return null;
 	}
 
-	const showActionButton =
-		!balanceIsLoading && (!!highestOffer || !!collectible);
+	// Show loading skeleton
+	const skeleton = renderSkeletonIfLoading({
+		cardLoading,
+		balanceIsLoading,
+		collectionType,
+		isShop: false,
+	});
+	if (skeleton) return skeleton;
 
-	const action = (
-		balance
-			? (highestOffer && CollectibleCardAction.SELL) ||
-				(!collectible?.listing && CollectibleCardAction.LIST) ||
-				CollectibleCardAction.TRANSFER
-			: (collectible?.listing && CollectibleCardAction.BUY) ||
-				CollectibleCardAction.OFFER
-	) as CollectibleCardAction;
+	const showActionButton = !!highestOffer || !!collectible;
 
-	const handleKeyDown = (e: React.KeyboardEvent) => {
-		if (e.key === 'Enter' || e.key === ' ') {
-			onCollectibleClick?.(collectibleId);
-		}
-	};
+	const action = determineCardAction({
+		hasBalance: !!balance,
+		hasOffer: !!highestOffer,
+		hasListing: !!lowestListing,
+	});
 
 	return (
-		<BaseCard
-			collectibleId={collectibleId}
+		<MarketCardPresentation
+			tokenId={tokenId}
 			chainId={chainId}
 			collectionAddress={collectionAddress}
-			collectionType={collectionType}
+			collectionType={collectionType as ContractType}
+			collectibleMetadata={collectibleMetadata}
+			currency={currency}
+			lowestListing={lowestListing}
+			highestOffer={highestOffer}
+			balance={balance}
 			assetSrcPrefixUrl={assetSrcPrefixUrl}
-			cardLoading={cardLoading}
-			cardType="market"
-			name={collectibleMetadata.name || ''}
-			image={collectibleMetadata.image}
-			video={collectibleMetadata.video}
-			animationUrl={collectibleMetadata.animation_url}
-			contractType={collectionType as ContractType}
-			isShop={false}
-			onClick={() => onCollectibleClick?.(collectibleId)}
-			onKeyDown={handleKeyDown}
+			onCollectibleClick={onCollectibleClick}
+			onOfferClick={onOfferClick}
+			action={action}
+			showActionButton={showActionButton}
+			onCannotPerformAction={onCannotPerformAction}
+			prioritizeOwnerActions={prioritizeOwnerActions}
 			hideQuantitySelector={hideQuantitySelector}
-		>
-			<Footer
-				chainId={chainId}
-				name={collectibleMetadata.name || ''}
-				type={collectionType}
-				onOfferClick={(e) => onOfferClick?.({ order: highestOffer, e })}
-				highestOffer={highestOffer}
-				lowestListing={lowestListing}
-				balance={balance}
-				decimals={collectibleMetadata.decimals}
-				quantityInitial={
-					highestOffer?.quantityInitial !== undefined
-						? highestOffer.quantityInitial
-						: collectible?.listing?.quantityInitial !== undefined
-							? collectible.listing.quantityInitial
-							: undefined
-				}
-				quantityRemaining={
-					highestOffer?.quantityRemaining !== undefined
-						? highestOffer.quantityRemaining
-						: collectible?.listing?.quantityRemaining !== undefined
-							? collectible.listing.quantityRemaining
-							: undefined
-				}
-				cardType="market"
-			/>
-
-			<ActionButtonWrapper
-				show={showActionButton ?? false}
-				chainId={chainId}
-				collectionAddress={collectionAddress}
-				tokenId={collectibleId}
-				orderbookKind={orderbookKind}
-				action={action}
-				highestOffer={highestOffer}
-				lowestListing={collectible?.listing}
-				owned={!!balance}
-				onCannotPerformAction={onCannotPerformAction}
-				cardType="market"
-				prioritizeOwnerActions={prioritizeOwnerActions}
-				hideQuantitySelector={hideQuantitySelector}
-			/>
-		</BaseCard>
+			classNames={classNames}
+		/>
 	);
 }

package/src/react/ui/components/marketplace-collectible-card/variants/MarketCardPresentation.tsx

@@ -0,0 +1,170 @@
+'use client';
+
+import type {
+	Address,
+	ContractType,
+	Currency,
+	Order,
+} from '@0xsequence/api-client';
+import type { CollectibleCardAction } from '../../../../../types';
+import { ActionButton } from '../ActionButton/ActionButton';
+import { Card } from '../Card';
+import type { CollectibleMetadata } from '../Card/card-media';
+import {
+	CARD_TITLE_MAX_LENGTH_DEFAULT,
+	CARD_TITLE_MAX_LENGTH_WITH_OFFER,
+} from '../constants';
+import type { CardClassNames } from '../types';
+
+export interface MarketCardPresentationProps {
+	/** Token identification */
+	tokenId: bigint;
+	chainId: number;
+	collectionAddress: Address;
+	collectionType: ContractType;
+
+	/** Display data */
+	collectibleMetadata: CollectibleMetadata;
+	currency?: Currency;
+	lowestListing?: Order;
+	highestOffer?: Order;
+	balance?: string;
+
+	/** Asset configuration */
+	assetSrcPrefixUrl?: string;
+
+	/** Interaction handlers */
+	onCollectibleClick?: (tokenId: bigint) => void;
+	onOfferClick?: (params: {
+		order: Order;
+		e: React.MouseEvent<HTMLButtonElement>;
+	}) => void;
+
+	/** Action button configuration */
+	action: CollectibleCardAction;
+	showActionButton?: boolean;
+	onCannotPerformAction?: (
+		action: CollectibleCardAction.BUY | CollectibleCardAction.OFFER,
+	) => void;
+	prioritizeOwnerActions?: boolean;
+	hideQuantitySelector?: boolean;
+	classNames?: CardClassNames;
+}
+
+/**
+ * MarketCardPresentation - Pure presentation component for market cards
+ *
+ * This is a "dumb" component that receives all data as props and handles no data fetching.
+ * Use this when you want full control over data fetching, or for SSR/SSG scenarios.
+ *
+ * For a convenient "smart" component with built-in data fetching, use MarketCard instead.
+ *
+ * @example
+ * ```tsx
+ * // With pre-fetched data
+ * <MarketCardPresentation
+ *   tokenId="123"
+ *   chainId={1}
+ *   collectibleMetadata={metadata}
+ *   currency={currency}
+ *   lowestListing={listing}
+ * />
+ * ```
+ */
+export function MarketCardPresentation({
+	tokenId,
+	chainId,
+	collectionAddress,
+	collectionType,
+	collectibleMetadata,
+	currency,
+	lowestListing,
+	highestOffer,
+	balance,
+	assetSrcPrefixUrl,
+	onCollectibleClick,
+	onOfferClick,
+	action,
+	showActionButton = true,
+	onCannotPerformAction,
+	prioritizeOwnerActions,
+	hideQuantitySelector,
+	classNames,
+}: MarketCardPresentationProps) {
+	// Only define handlers if callback exists
+	const handleClick = onCollectibleClick
+		? () => onCollectibleClick(tokenId)
+		: undefined;
+
+	const handleKeyDown = onCollectibleClick
+		? (e: React.KeyboardEvent) => {
+				if (e.key === 'Enter' || e.key === ' ') {
+					onCollectibleClick(tokenId);
+				}
+			}
+		: undefined;
+
+	return (
+		<Card
+			onClick={handleClick}
+			onKeyDown={handleKeyDown}
+			className={classNames?.cardRoot}
+		>
+			<Card.Media
+				metadata={collectibleMetadata}
+				assetSrcPrefixUrl={assetSrcPrefixUrl}
+				className={classNames?.cardMedia}
+			/>
+
+			<Card.Content className={classNames?.cardContent}>
+				<Card.Title
+					highestOffer={highestOffer}
+					onOfferClick={(e) =>
+						onOfferClick?.({ order: highestOffer as Order, e })
+					}
+					balance={balance}
+					maxLength={
+						highestOffer
+							? CARD_TITLE_MAX_LENGTH_WITH_OFFER
+							: CARD_TITLE_MAX_LENGTH_DEFAULT
+					}
+					className={classNames?.cardTitle}
+				>
+					{collectibleMetadata.name || 'Untitled'}
+				</Card.Title>
+
+				<div className="flex items-center gap-1">
+					<Card.Price
+						amount={lowestListing?.priceAmount}
+						currency={currency}
+						className={classNames?.cardPrice}
+						type={'market'}
+					/>
+				</div>
+
+				<Card.Badge
+					type={collectionType}
+					balance={balance}
+					className={classNames?.cardBadge}
+				/>
+			</Card.Content>
+
+			<Card.Footer show={showActionButton} className={classNames?.cardFooter}>
+				<ActionButton
+					chainId={chainId}
+					collectionAddress={collectionAddress}
+					tokenId={tokenId}
+					action={action}
+					highestOffer={highestOffer}
+					lowestListing={lowestListing}
+					owned={!!balance}
+					onCannotPerformAction={onCannotPerformAction}
+					cardType="market"
+					prioritizeOwnerActions={prioritizeOwnerActions}
+					hideQuantitySelector={hideQuantitySelector}
+					className={classNames?.cardActionButton}
+				/>
+			</Card.Footer>
+		</Card>
+	);
+}