From dd9fae2e336f195a33d32268ee6bedc6e69c233f Mon Sep 17 00:00:00 2001
From: The Joel <jotelfootball@gmail.com>
Date: Thu, 30 Jul 2026 00:45:10 +0100
Subject: [PATCH] Add holdings sorting by total value descending with unit
 tests

- Add calculatePositionTotalValue utility to compute individual position value
- Add sortHoldingsByTotalValue utility to sort holdings by total value descending
- Apply sorting in LandingPage component before rendering holdings list
- Add comprehensive unit tests covering all acceptance criteria:
  - Holdings rendered in descending total value order (1200, 500, 300)
  - Order updates when cache data changes (300 -> 1500 reorders to 1500, 1200, 500)
  - Stable secondary sort by creator ID for equal total values
  - Handles missing prices and zero quantities gracefully
  - Does not mutate original array
- Sort applied before render via useMemo in LandingPage
---
 src/pages/LandingPage.tsx                     |  62 +++++---
 .../__tests__/portfolioValue.utils.test.ts    | 140 ++++++++++++++++++
 src/utils/portfolioValue.utils.ts             |  37 +++++
 3 files changed, 221 insertions(+), 18 deletions(-)

diff --git a/src/pages/LandingPage.tsx b/src/pages/LandingPage.tsx
index b61b52ca..244aa680 100644
--- a/src/pages/LandingPage.tsx
+++ b/src/pages/LandingPage.tsx
@@ -37,6 +37,10 @@ import showToast from '@/utils/toast.util';
 import { getSignatureErrorMessage } from '@/utils/errorHandling.utils';
 import { formatCompactNumber, formatNumber } from '@/utils/numberFormat.utils';
 import { formatOwnershipPercent } from '@/utils/ownership.utils';
+import {
+	calculatePortfolioValue,
+	sortHoldingsByTotalValue,
+} from '@/utils/portfolioValue.utils';
 import PrecisionModeToggle, {
 	type PrecisionMode,
 } from '@/components/common/PrecisionModeToggle';
@@ -299,7 +303,10 @@ function LandingPage() {
 	const prefersReducedMotion = usePrefersReducedMotion();
 	const [sortOption, setSortOption] = useState<SortOption>(() => {
 		const sort = searchParams.get('sort') as SortOption | null;
-		if (sort && ['featured', 'price-asc', 'price-desc', 'supply-desc'].includes(sort)) {
+		if (
+			sort &&
+			['featured', 'price-asc', 'price-desc', 'supply-desc'].includes(sort)
+		) {
 			sortOptionRef.current = sort;
 			return sort;
 		}
@@ -386,7 +393,13 @@ function LandingPage() {
 			setSearchQuery('');
 		}
 		const sort = searchParams.get('sort') as SortOption | null;
-		if (sort && ['featured', 'price-asc', 'price-desc', 'supply-desc'].includes(sort) && sort !== sortOptionRef.current) {
+		if (
+			sort &&
+			['featured', 'price-asc', 'price-desc', 'supply-desc'].includes(
+				sort
+			) &&
+			sort !== sortOptionRef.current
+		) {
 			setSortOption(sort);
 		} else if (sort === null && sortOptionRef.current !== 'featured') {
 			setSortOption('featured');
@@ -648,17 +661,19 @@ function LandingPage() {
 
 	const heldKeyPositions = useMemo(
 		() =>
-			creators.map((creator, index) => ({
-				creatorId: creator.id,
-				quantity:
-					index === 0
-						? featuredHoldings
-						: (DEMO_HELD_KEY_QUANTITIES[index] ?? 0),
-				priceStroops: creator.priceStroops,
-				price: creator.price,
-				isPriceLoading: isPriceRefreshing,
-				isPriceStale: creatorsAreStale,
-			})),
+			sortHoldingsByTotalValue(
+				creators.map((creator, index) => ({
+					creatorId: creator.id,
+					quantity:
+						index === 0
+							? featuredHoldings
+							: (DEMO_HELD_KEY_QUANTITIES[index] ?? 0),
+					priceStroops: creator.priceStroops,
+					price: creator.price,
+					isPriceLoading: isPriceRefreshing,
+					isPriceStale: creatorsAreStale,
+				}))
+			),
 		[creators, creatorsAreStale, featuredHoldings, isPriceRefreshing]
 	);
 	const portfolioValue = useMemo(
@@ -831,7 +846,10 @@ function LandingPage() {
 								<span className="font-semibold uppercase tracking-[0.16em] text-white/40">
 									Shortcut
 								</span>
-								<span className="inline-flex items-center gap-1" aria-hidden="true">
+								<span
+									className="inline-flex items-center gap-1"
+									aria-hidden="true"
+								>
 									<Kbd className="border border-white/10 bg-white/10 text-white/70">
 										Ctrl/Cmd
 									</Kbd>
@@ -930,14 +948,20 @@ function LandingPage() {
 													>
 														<CreatorCard
 															creator={creator}
-															isPriceRefreshing={isPriceRefreshing}
+															isPriceRefreshing={
+																isPriceRefreshing
+															}
 														/>
 													</motion.div>
 												))}
 
 											{/* Separator between pinned and unpinned */}
-											{pagedCreators.some(creator => creator.isPinned) &&
-												pagedCreators.some(creator => !creator.isPinned) && (
+											{pagedCreators.some(
+												creator => creator.isPinned
+											) &&
+												pagedCreators.some(
+													creator => !creator.isPinned
+												) && (
 													<CreatorListGroupSeparator label="Other creators" />
 												)}
 
@@ -958,7 +982,9 @@ function LandingPage() {
 													>
 														<CreatorCard
 															creator={creator}
-															isPriceRefreshing={isPriceRefreshing}
+															isPriceRefreshing={
+																isPriceRefreshing
+															}
 														/>
 													</motion.div>
 												))}
diff --git a/src/utils/__tests__/portfolioValue.utils.test.ts b/src/utils/__tests__/portfolioValue.utils.test.ts
index e2589b17..c67a4475 100644
--- a/src/utils/__tests__/portfolioValue.utils.test.ts
+++ b/src/utils/__tests__/portfolioValue.utils.test.ts
@@ -3,6 +3,8 @@ import {
 	calculatePortfolioValue,
 	formatPortfolioValueDisplay,
 	getPortfolioValueHelperText,
+	calculatePositionTotalValue,
+	sortHoldingsByTotalValue,
 } from '../portfolioValue.utils';
 
 describe('calculatePortfolioValue', () => {
@@ -96,3 +98,141 @@ describe('calculatePortfolioValue', () => {
 		);
 	});
 });
+
+describe('calculatePositionTotalValue', () => {
+	it('calculates total value for a position with valid price and quantity', () => {
+		const result = calculatePositionTotalValue({
+			creatorId: 'alex',
+			quantity: 5,
+			priceStroops: 1_000_000,
+		});
+
+		expect(result).toBe(5_000_000);
+	});
+
+	it('returns null when price is missing', () => {
+		const result = calculatePositionTotalValue({
+			creatorId: 'alex',
+			quantity: 5,
+			priceStroops: null,
+			price: null,
+		});
+
+		expect(result).toBeNull();
+	});
+
+	it('returns null when quantity is zero', () => {
+		const result = calculatePositionTotalValue({
+			creatorId: 'alex',
+			quantity: 0,
+			priceStroops: 1_000_000,
+		});
+
+		expect(result).toBeNull();
+	});
+
+	it('returns null when quantity is null', () => {
+		const result = calculatePositionTotalValue({
+			creatorId: 'alex',
+			quantity: null,
+			priceStroops: 1_000_000,
+		});
+
+		expect(result).toBeNull();
+	});
+});
+
+describe('sortHoldingsByTotalValue', () => {
+	it('sorts holdings in descending order by total value', () => {
+		const positions = [
+			{ creatorId: 'alex', quantity: 5, priceStroops: 100_000 }, // 500,000
+			{ creatorId: 'sarah', quantity: 12, priceStroops: 100_000 }, // 1,200,000
+			{ creatorId: 'marcus', quantity: 3, priceStroops: 100_000 }, // 300,000
+		];
+
+		const sorted = sortHoldingsByTotalValue(positions);
+
+		expect(sorted[0].creatorId).toBe('sarah'); // 1,200,000
+		expect(sorted[1].creatorId).toBe('alex'); // 500,000
+		expect(sorted[2].creatorId).toBe('marcus'); // 300,000
+	});
+
+	it('updates order when data changes', () => {
+		const positions = [
+			{ creatorId: 'alex', quantity: 5, priceStroops: 100_000 }, // 500,000
+			{ creatorId: 'sarah', quantity: 12, priceStroops: 100_000 }, // 1,200,000
+			{ creatorId: 'marcus', quantity: 3, priceStroops: 100_000 }, // 300,000
+		];
+
+		const sorted = sortHoldingsByTotalValue(positions);
+		expect(sorted[0].creatorId).toBe('sarah'); // 1,200,000
+
+		// Update marcus to have higher value
+		const updatedPositions = [
+			{ creatorId: 'alex', quantity: 5, priceStroops: 100_000 }, // 500,000
+			{ creatorId: 'sarah', quantity: 12, priceStroops: 100_000 }, // 1,200,000
+			{ creatorId: 'marcus', quantity: 15, priceStroops: 100_000 }, // 1,500,000
+		];
+
+		const resorted = sortHoldingsByTotalValue(updatedPositions);
+		expect(resorted[0].creatorId).toBe('marcus'); // 1,500,000
+		expect(resorted[1].creatorId).toBe('sarah'); // 1,200,000
+		expect(resorted[2].creatorId).toBe('alex'); // 500,000
+	});
+
+	it('maintains stable secondary sort by creator ID for equal values', () => {
+		const positions = [
+			{ creatorId: 'alex', quantity: 10, priceStroops: 100_000 }, // 1,000,000
+			{ creatorId: 'sarah', quantity: 10, priceStroops: 100_000 }, // 1,000,000
+			{ creatorId: 'marcus', quantity: 10, priceStroops: 100_000 }, // 1,000,000
+		];
+
+		const sorted = sortHoldingsByTotalValue(positions);
+
+		// All have same value, should be sorted alphabetically by creator ID
+		expect(sorted[0].creatorId).toBe('alex');
+		expect(sorted[1].creatorId).toBe('marcus');
+		expect(sorted[2].creatorId).toBe('sarah');
+	});
+
+	it('handles positions with missing prices by treating them as zero value', () => {
+		const positions = [
+			{ creatorId: 'alex', quantity: 5, priceStroops: 100_000 }, // 500,000
+			{ creatorId: 'sarah', quantity: 10, priceStroops: null, price: null }, // null -> 0
+			{ creatorId: 'marcus', quantity: 3, priceStroops: 100_000 }, // 300,000
+		];
+
+		const sorted = sortHoldingsByTotalValue(positions);
+
+		expect(sorted[0].creatorId).toBe('alex'); // 500,000
+		expect(sorted[1].creatorId).toBe('marcus'); // 300,000
+		expect(sorted[2].creatorId).toBe('sarah'); // 0 (missing price)
+	});
+
+	it('handles positions with zero quantity by treating them as zero value', () => {
+		const positions = [
+			{ creatorId: 'alex', quantity: 5, priceStroops: 100_000 }, // 500,000
+			{ creatorId: 'sarah', quantity: 0, priceStroops: 100_000 }, // 0
+			{ creatorId: 'marcus', quantity: 3, priceStroops: 100_000 }, // 300,000
+		];
+
+		const sorted = sortHoldingsByTotalValue(positions);
+
+		expect(sorted[0].creatorId).toBe('alex'); // 500,000
+		expect(sorted[1].creatorId).toBe('marcus'); // 300,000
+		expect(sorted[2].creatorId).toBe('sarah'); // 0 (zero quantity)
+	});
+
+	it('does not mutate the original array', () => {
+		const positions = [
+			{ creatorId: 'alex', quantity: 5, priceStroops: 100_000 },
+			{ creatorId: 'sarah', quantity: 12, priceStroops: 100_000 },
+			{ creatorId: 'marcus', quantity: 3, priceStroops: 100_000 },
+		];
+
+		const originalOrder = positions.map(p => p.creatorId);
+		sortHoldingsByTotalValue(positions);
+
+		expect(positions.map(p => p.creatorId)).toEqual(originalOrder);
+	});
+});
diff --git a/src/utils/portfolioValue.utils.ts b/src/utils/portfolioValue.utils.ts
index 07f1d9f0..4b7128a8 100644
--- a/src/utils/portfolioValue.utils.ts
+++ b/src/utils/portfolioValue.utils.ts
@@ -128,3 +128,40 @@ export function getPortfolioValueHelperText(result: PortfolioValueResult) {
 
 	return `Across ${result.heldPositionCount} held creator ${result.heldPositionCount === 1 ? 'position' : 'positions'}.`;
 }
+
+/**
+ * Calculates the total value (in stroops) for a single held key position.
+ */
+export function calculatePositionTotalValue(
+	position: HeldKeyPosition
+): number | null {
+	const priceStroops = resolveCreatorKeyPriceStroops(position);
+	const quantity = normalizeHeldQuantity(position.quantity);
+
+	if (priceStroops == null || quantity === 0) {
+		return null;
+	}
+
+	return priceStroops * quantity;
+}
+
+/**
+ * Sorts held key positions by total value in descending order.
+ * Positions with equal total values maintain a stable secondary sort by creator ID.
+ */
+export function sortHoldingsByTotalValue(
+	positions: HeldKeyPosition[]
+): HeldKeyPosition[] {
+	return [...positions].sort((a, b) => {
+		const aValue = calculatePositionTotalValue(a) ?? 0;
+		const bValue = calculatePositionTotalValue(b) ?? 0;
+
+		// Primary sort: descending by total value
+		if (bValue !== aValue) {
+			return bValue - aValue;
+		}
+
+		// Secondary sort: stable by creator ID for equal values
+		return a.creatorId.localeCompare(b.creatorId);
+	});
+}