feat(converter): implement pinned pairs functionality for quick access

components/converter/converter-card.tsx

@@ -9,7 +9,10 @@ import {
   Check,
   Copy,
   Loader2,
+  MoveRight,
   RefreshCcw,
+  Star,
+  X,
 } from "lucide-react";
 
 import { CurrencyIcon } from "@/components/converter/currency-icon";
@@ -29,6 +32,7 @@ import { Separator } from "@/components/ui/separator";
 import { Skeleton } from "@/components/ui/skeleton";
 import { useCryptoMarket } from "@/hooks/use-crypto-market";
 import { useDebouncedValue } from "@/hooks/use-debounced-value";
+import { usePinnedPairs } from "@/hooks/use-pinned-pairs";
 import { getDisplaySymbol } from "@/lib/currency-display";
 import {
   MARKET_CHART_RANGES,
@@ -53,6 +57,7 @@ const DEFAULT_TO = "BTC";
 const QUICK_AMOUNTS = [10, 50, 100, 500, 1000] as const;
 const DEFAULT_MULTI_CONVERSION_CODES = ["USD", "EUR", "BTC", "ETH", "SOL"] as const;
 const MAX_MULTI_CONVERSIONS = 4;
+const MAX_PINNED_PAIRS = 6;
 const MARKET_RANGE_LABELS: Record<MarketChartRange, string> = {
   "24h": "24h",
   "7d": "7d",
@@ -150,6 +155,15 @@ export function ConverterCard({
   const [isCopied, setIsCopied] = useState(false);
   const [marketRange, setMarketRange] = useState<MarketChartRange>("24h");
   const [swapAnimationStep, setSwapAnimationStep] = useState(0);
+  const [pinStarAnimationStep, setPinStarAnimationStep] = useState(0);
+  const {
+    pinnedPairs,
+    isReady: isPinnedPairsReady,
+    isLimitReached: isPinnedPairsLimitReached,
+    isPinnedPair,
+    removePinnedPair,
+    togglePinnedPair,
+  } = usePinnedPairs(MAX_PINNED_PAIRS);
 
   const debouncedAmount = useDebouncedValue(amountInput, 120);
 
@@ -341,6 +355,45 @@ export function ConverterCard({
   }, [marketData, marketRange]);
 
   const amountPrefix = getDisplaySymbol(fromAsset);
+  const currentPair = useMemo(
+    () => ({ fromCode, toCode }),
+    [fromCode, toCode],
+  );
+  const isCurrentPairPinned = isPinnedPair(currentPair);
+  const hasReachedPinnedPairsLimit =
+    isPinnedPairsLimitReached && !isCurrentPairPinned;
+  const handleTogglePinnedCurrentPair = () => {
+    setPinStarAnimationStep((current) => current + 1);
+    togglePinnedPair(currentPair);
+  };
+  const pinnedPairItems = useMemo(
+    () =>
+      pinnedPairs
+        .map((pair) => {
+          const fromAssetEntry = rateMap.get(pair.fromCode);
+          const toAssetEntry = rateMap.get(pair.toCode);
+
+          if (!fromAssetEntry || !toAssetEntry || fromAssetEntry.code === toAssetEntry.code) {
+            return null;
+          }
+
+          return {
+            pair,
+            fromAsset: fromAssetEntry,
+            toAsset: toAssetEntry,
+          };
+        })
+        .filter(
+          (
+            item,
+          ): item is {
+            pair: { fromCode: string; toCode: string };
+            fromAsset: (typeof assets)[number];
+            toAsset: (typeof assets)[number];
+          } => Boolean(item),
+        ),
+    [pinnedPairs, rateMap],
+  );
   const amountInputPaddingLeft = useMemo(() => {
     if (!amountPrefix) {
       return undefined;
@@ -540,6 +593,136 @@ export function ConverterCard({
           />
         </div>
 
+        <div className="space-y-2">
+          <div className="flex flex-wrap items-center justify-between gap-2">
+            <p className="text-xs uppercase tracking-[0.12em] text-muted-foreground">
+              Pinned pairs
+            </p>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={handleTogglePinnedCurrentPair}
+              disabled={hasReachedPinnedPairsLimit}
+              aria-pressed={isCurrentPairPinned}
+              aria-label={
+                isCurrentPairPinned
+                  ? "Remove current pair from pinned pairs"
+                  : "Add current pair to pinned pairs"
+              }
+              className={cn(
+                "h-8 rounded-full border-border/70 px-3 text-xs transition-colors",
+                isCurrentPairPinned
+                  ? "border-amber-300/50 bg-amber-400/10 text-amber-100 hover:border-amber-300/60 hover:bg-amber-400/15"
+                  : "text-muted-foreground hover:text-foreground",
+              )}
+            >
+              <motion.span
+                key={`${pinStarAnimationStep}-${isCurrentPairPinned ? "on" : "off"}`}
+                className="mr-1.5 inline-flex"
+                initial={
+                  shouldReduceMotion
+                    ? false
+                    : { scale: 0.95, rotate: 0, opacity: 0.9 }
+                }
+                animate={
+                  shouldReduceMotion
+                    ? { scale: 1, rotate: 0, opacity: 1 }
+                    : {
+                        scale: [1, 1.18, 1],
+                        rotate: isCurrentPairPinned ? [0, -12, 8, 0] : [0, 12, -8, 0],
+                        opacity: [1, 1, 1],
+                      }
+                }
+                transition={{
+                  duration: shouldReduceMotion ? 0.01 : 0.24,
+                  ease: [0.22, 1, 0.36, 1],
+                }}
+              >
+                <Star
+                  className={cn(
+                    "h-3.5 w-3.5",
+                    isCurrentPairPinned ? "fill-amber-300 text-amber-300" : "",
+                  )}
+                />
+              </motion.span>
+              {isCurrentPairPinned ? "Pinned" : "Pin current pair"}
+            </Button>
+          </div>
+
+          {pinnedPairItems.length > 0 ? (
+            <div className="flex flex-wrap gap-2">
+              {pinnedPairItems.map(({ pair, fromAsset, toAsset }) => {
+                const isActive =
+                  pair.fromCode === fromCode && pair.toCode === toCode;
+
+                return (
+                  <div
+                    key={`${pair.fromCode}-${pair.toCode}`}
+                    className={cn(
+                      "inline-flex items-center rounded-full border border-border/70 bg-background/45 pr-0.5",
+                      isActive ? "border-cyan-300/40 bg-cyan-500/10" : "",
+                    )}
+                  >
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="sm"
+                      onClick={() => {
+                        setFromCode(pair.fromCode);
+                        setToCode(pair.toCode);
+                      }}
+                      className={cn(
+                        "h-8 rounded-full px-2.5 text-xs text-muted-foreground hover:text-foreground",
+                        isActive ? "text-cyan-100 hover:text-cyan-100" : "",
+                      )}
+                      aria-label={`Set pair ${pair.fromCode} to ${pair.toCode}`}
+                    >
+                      <span className="inline-flex items-center gap-1.5">
+                        <CurrencyIcon
+                          code={fromAsset.code}
+                          type={fromAsset.type}
+                          size="sm"
+                        />
+                        <span>{pair.fromCode}</span>
+                        <MoveRight className="h-3.5 w-3.5 text-cyan-300/90" />
+                        <CurrencyIcon
+                          code={toAsset.code}
+                          type={toAsset.type}
+                          size="sm"
+                        />
+                        <span>{pair.toCode}</span>
+                      </span>
+                    </Button>
+                    <Button
+                      type="button"
+                      variant="ghost"
+                      size="icon"
+                      onClick={() => removePinnedPair(pair)}
+                      className="h-7 w-7 rounded-full text-muted-foreground hover:text-red-300 focus-visible:text-red-200"
+                      aria-label={`Remove pinned pair ${pair.fromCode} to ${pair.toCode}`}
+                    >
+                      <X className="h-3.5 w-3.5" />
+                    </Button>
+                  </div>
+                );
+              })}
+            </div>
+          ) : null}
+
+          {isPinnedPairsReady && pinnedPairItems.length === 0 ? (
+            <p className="text-xs text-muted-foreground">
+              Pin your most-used pairs for one-click access.
+            </p>
+          ) : null}
+
+          {hasReachedPinnedPairsLimit ? (
+            <p className="text-xs text-amber-200/90">
+              Pinned pairs limit reached ({MAX_PINNED_PAIRS}). Remove one to add a new pair.
+            </p>
+          ) : null}
+        </div>
+
         <div className="rounded-xl border border-border/70 bg-background/50 p-4">
           <div className="flex items-center justify-between gap-2">
             <p className="text-xs uppercase tracking-[0.12em] text-muted-foreground">

hooks/use-pinned-pairs.ts

@@ -0,0 +1,196 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+export interface PinnedPair {
+  fromCode: string;
+  toCode: string;
+}
+
+const PINNED_PAIRS_STORAGE_KEY = "nexcurrency:pinned-pairs:v1";
+const CODE_PATTERN = /^[A-Z0-9]{2,12}$/;
+
+function normalizeCode(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const normalized = value.trim().toUpperCase();
+
+  if (!CODE_PATTERN.test(normalized)) {
+    return null;
+  }
+
+  return normalized;
+}
+
+function normalizePair(value: unknown): PinnedPair | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const record = value as Record<string, unknown>;
+  const fromCode = normalizeCode(record.fromCode);
+  const toCode = normalizeCode(record.toCode);
+
+  if (!fromCode || !toCode || fromCode === toCode) {
+    return null;
+  }
+
+  return { fromCode, toCode };
+}
+
+function toPairKey(pair: PinnedPair): string {
+  return `${pair.fromCode}:${pair.toCode}`;
+}
+
+function dedupeAndClampPairs(pairs: PinnedPair[], limit: number): PinnedPair[] {
+  const keys = new Set<string>();
+  const normalized: PinnedPair[] = [];
+
+  for (const pair of pairs) {
+    const key = toPairKey(pair);
+
+    if (keys.has(key)) {
+      continue;
+    }
+
+    keys.add(key);
+    normalized.push(pair);
+
+    if (normalized.length >= limit) {
+      break;
+    }
+  }
+
+  return normalized;
+}
+
+export function usePinnedPairs(limit = 6) {
+  const [pinnedPairs, setPinnedPairs] = useState<PinnedPair[]>([]);
+  const [isReady, setIsReady] = useState(false);
+  const isLimitReached = pinnedPairs.length >= limit;
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    try {
+      const raw = window.localStorage.getItem(PINNED_PAIRS_STORAGE_KEY);
+
+      if (!raw) {
+        setPinnedPairs([]);
+        setIsReady(true);
+        return;
+      }
+
+      const parsed = JSON.parse(raw) as unknown;
+      const parsedPairs = Array.isArray(parsed)
+        ? parsed.map(normalizePair).filter((pair): pair is PinnedPair => pair !== null)
+        : [];
+
+      setPinnedPairs(dedupeAndClampPairs(parsedPairs, limit));
+    } catch {
+      setPinnedPairs([]);
+    } finally {
+      setIsReady(true);
+    }
+  }, [limit]);
+
+  useEffect(() => {
+    if (!isReady || typeof window === "undefined") {
+      return;
+    }
+
+    try {
+      window.localStorage.setItem(
+        PINNED_PAIRS_STORAGE_KEY,
+        JSON.stringify(pinnedPairs),
+      );
+    } catch {
+      // Intentionally ignored: localStorage may be unavailable.
+    }
+  }, [isReady, pinnedPairs]);
+
+  const isPinnedPair = useCallback(
+    (pair: PinnedPair) => pinnedPairs.some((entry) => toPairKey(entry) === toPairKey(pair)),
+    [pinnedPairs],
+  );
+
+  const addPinnedPair = useCallback(
+    (pair: PinnedPair) => {
+      const normalized = normalizePair(pair);
+
+      if (!normalized) {
+        return;
+      }
+
+      setPinnedPairs((current) => {
+        const exists = current.some(
+          (entry) => toPairKey(entry) === toPairKey(normalized),
+        );
+
+        if (!exists && current.length >= limit) {
+          return current;
+        }
+
+        return dedupeAndClampPairs(
+          [
+            normalized,
+            ...current.filter((entry) => toPairKey(entry) !== toPairKey(normalized)),
+          ],
+          limit,
+        );
+      });
+    },
+    [limit],
+  );
+
+  const removePinnedPair = useCallback((pair: PinnedPair) => {
+    const normalized = normalizePair(pair);
+
+    if (!normalized) {
+      return;
+    }
+
+    setPinnedPairs((current) =>
+      current.filter((entry) => toPairKey(entry) !== toPairKey(normalized)),
+    );
+  }, []);
+
+  const togglePinnedPair = useCallback(
+    (pair: PinnedPair) => {
+      if (isPinnedPair(pair)) {
+        removePinnedPair(pair);
+        return;
+      }
+
+      addPinnedPair(pair);
+    },
+    [addPinnedPair, isPinnedPair, removePinnedPair],
+  );
+
+  return useMemo(
+    () => ({
+      pinnedPairs,
+      isReady,
+      isLimitReached,
+      isPinnedPair,
+      addPinnedPair,
+      removePinnedPair,
+      togglePinnedPair,
+      limit,
+    }),
+    [
+      pinnedPairs,
+      isReady,
+      isLimitReached,
+      isPinnedPair,
+      addPinnedPair,
+      removePinnedPair,
+      togglePinnedPair,
+      limit,
+    ],
+  );
+}