@naculus/connect-appkit-react 0.1.2

package/src/token-list/TokenSelector.tsx

@@ -0,0 +1,351 @@
+/**
+ * TokenSelector — chain-aware, searchable token selection component.
+ *
+ * Features:
+ * - Loads token list for the given chain
+ * - Search by symbol, name, or address
+ * - Displays token logo, symbol, name, and decimals
+ * - Calls onSelect when a token is chosen
+ */
+
+import React, { useCallback } from "react";
+import type { TokenListEntry } from "@naculus/connect-core";
+import { useTokenList } from "./useTokenList";
+import { useTokenSearch } from "./useTokenSearch";
+
+export interface TokenSelectorProps {
+  /** Chain ID in CAIP-2 format (e.g. "eip155:1") */
+  chainId: string;
+  /** Called when a token is selected */
+  onSelect: (token: TokenListEntry) => void;
+  /** Called to close/dismiss the selector */
+  onClose: () => void;
+  /** Optional configuration */
+  options?: {
+    /** Show popular/recommended tokens (default: true) */
+    showRecommendations?: boolean;
+    /** Custom filter for tokens */
+    filter?: (token: TokenListEntry) => boolean;
+  };
+}
+
+/**
+ * TokenSelector — a dropdown/modal component for selecting tokens.
+ *
+ * @example
+ * <TokenSelector
+ *   chainId="eip155:1"
+ *   onSelect={(token) => setSelectedToken(token)}
+ *   onClose={() => setOpen(false)}
+ * />
+ */
+export function TokenSelector({
+  chainId,
+  onSelect,
+  onClose,
+  options,
+}: TokenSelectorProps) {
+  const [searchQuery, setSearchQuery] = React.useState("");
+
+  const {
+    tokens: allTokens,
+    isLoading,
+    error,
+  } = useTokenList(chainId);
+
+  const { results, isSearching } = useTokenSearch(
+    searchQuery,
+    searchQuery ? chainId : undefined,
+  );
+
+  const showRecommendations = options?.showRecommendations ?? true;
+
+  // Display tokens: when searching, show results; otherwise show the full list
+  const displayTokens = React.useMemo(() => {
+    if (searchQuery.trim()) {
+      const combined = [...results.exact, ...results.fuzzy].map((m) => m.token);
+      return options?.filter
+        ? combined.filter(options.filter)
+        : combined;
+    }
+
+    const tokens = allTokens;
+    return options?.filter
+      ? tokens.filter(options.filter)
+      : tokens;
+  }, [searchQuery, results, allTokens, options?.filter]);
+
+  // Popular tokens for recommendation section
+  const popularTokens = React.useMemo(() => {
+    if (!showRecommendations || searchQuery.trim()) return [];
+    return allTokens.slice(0, 6); // Top 6
+  }, [allTokens, showRecommendations, searchQuery]);
+
+  const handleSelect = useCallback(
+    (token: TokenListEntry) => {
+      onSelect(token);
+      onClose();
+    },
+    [onSelect, onClose],
+  );
+
+  return (
+    <div
+      style={{
+        background: "hsl(var(--background))",
+        borderRadius: "12px",
+        padding: "16px",
+        color: "hsl(var(--foreground))",
+        minWidth: "320px",
+        maxWidth: "400px",
+        fontFamily: "system-ui, sans-serif",
+      }}
+    >
+      {/* Header */}
+      <div
+        style={{
+          display: "flex",
+          justifyContent: "space-between",
+          alignItems: "center",
+          marginBottom: "12px",
+        }}
+      >
+        <h3 style={{ margin: 0, fontSize: "16px", fontWeight: 600 }}>
+          Select Token
+        </h3>
+        <button
+          onClick={onClose}
+          style={{
+            background: "none",
+            border: "none",
+            color: "hsl(var(--muted-foreground))",
+            cursor: "pointer",
+            fontSize: "18px",
+            padding: "4px 8px",
+          }}
+        >
+          ✕
+        </button>
+      </div>
+
+      {/* Search Input */}
+      <input
+        type="text"
+        placeholder="Search token name or paste address"
+        value={searchQuery}
+        onChange={(e) => setSearchQuery(e.target.value)}
+        style={{
+          width: "100%",
+          padding: "10px 12px",
+          borderRadius: "8px",
+          border: "1px solid #333",
+          background: "hsl(var(--card))",
+          color: "hsl(var(--foreground))",
+          fontSize: "14px",
+          outline: "none",
+          boxSizing: "border-box",
+          marginBottom: "12px",
+        }}
+        autoFocus
+      />
+
+      {/* Loading / Error States */}
+      {isLoading && !isSearching && (
+        <div style={{ textAlign: "center", padding: "20px", color: "hsl(var(--muted-foreground))" }}>
+          Loading tokens...
+        </div>
+      )}
+      {error && (
+        <div
+          style={{
+            textAlign: "center",
+            padding: "12px",
+            color: "hsl(var(--destructive))",
+            fontSize: "13px",
+          }}
+        >
+          Error: {error.message}
+        </div>
+      )}
+
+      {/* Popular / Recommended Section */}
+      {showRecommendations && popularTokens.length > 0 && !searchQuery.trim() && (
+        <div style={{ marginBottom: "12px" }}>
+          <div
+            style={{
+              fontSize: "11px",
+              color: "hsl(var(--muted-foreground))",
+              textTransform: "uppercase",
+              letterSpacing: "0.5px",
+              marginBottom: "8px",
+            }}
+          >
+            Popular
+          </div>
+          <div style={{ display: "flex", gap: "6px", flexWrap: "wrap" }}>
+            {popularTokens.map((token) => (
+              <button
+                key={`${token.chainId}:${token.address}`}
+                onClick={() => handleSelect(token)}
+                style={{
+                  background: "hsl(var(--card))",
+                  border: "1px solid #333",
+                  borderRadius: "20px",
+                  padding: "6px 14px",
+                  color: "hsl(var(--foreground))",
+                  cursor: "pointer",
+                  fontSize: "13px",
+                  display: "flex",
+                  alignItems: "center",
+                  gap: "4px",
+                }}
+              >
+                {token.logoURI ? (
+                  <img
+                    src={token.logoURI}
+                    alt=""
+                    style={{ width: "16px", height: "16px", borderRadius: "50%" }}
+                    onError={(e) => {
+                      (e.target as HTMLImageElement).style.display = "none";
+                    }}
+                  />
+                ) : null}
+                {token.symbol}
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {/* Search Result Count */}
+      {searchQuery.trim() && !isLoading && (
+        <div
+          style={{
+            fontSize: "11px",
+            color: "hsl(var(--muted-foreground))",
+            marginBottom: "8px",
+          }}
+        >
+          {displayTokens.length > 0 ? (
+            <>
+              {results.exact.length} exact, {results.fuzzy.length} fuzzy
+              {results.hasMore ? " (more available)" : ""}
+            </>
+          ) : (
+            "No results found"
+          )}
+        </div>
+      )}
+
+      {/* Token List */}
+      <div
+        style={{
+          maxHeight: "320px",
+          overflowY: "auto",
+          display: "flex",
+          flexDirection: "column",
+          gap: "2px",
+        }}
+      >
+        {displayTokens.map((token) => (
+          <button
+            key={`${token.chainId}:${token.address}`}
+            onClick={() => handleSelect(token)}
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: "10px",
+              padding: "10px 8px",
+              background: "transparent",
+              border: "none",
+              borderRadius: "8px",
+              color: "hsl(var(--foreground))",
+              cursor: "pointer",
+              textAlign: "left",
+              width: "100%",
+              fontSize: "14px",
+            }}
+            onMouseEnter={(e) => {
+              (e.target as HTMLElement).style.background = "hsl(var(--card))";
+            }}
+            onMouseLeave={(e) => {
+              (e.target as HTMLElement).style.background = "transparent";
+            }}
+          >
+            {/* Logo */}
+            <div
+              style={{
+                width: "32px",
+                height: "32px",
+                borderRadius: "50%",
+                background: "hsl(var(--border))",
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "center",
+                fontSize: "12px",
+                fontWeight: 600,
+                flexShrink: 0,
+                overflow: "hidden",
+              }}
+            >
+              {token.logoURI ? (
+                <img
+                  src={token.logoURI}
+                  alt={token.symbol}
+                  style={{ width: "100%", height: "100%" }}
+                  onError={(e) => {
+                    const img = e.target as HTMLImageElement;
+                    img.style.display = "none";
+                    (img.parentElement as HTMLElement).textContent =
+                      token.symbol.slice(0, 2);
+                  }}
+                />
+              ) : (
+                token.symbol.slice(0, 2)
+              )}
+            </div>
+
+            {/* Token info */}
+            <div style={{ flex: 1, minWidth: 0 }}>
+              <div
+                style={{
+                  fontWeight: 600,
+                  fontSize: "14px",
+                  overflow: "hidden",
+                  textOverflow: "ellipsis",
+                  whiteSpace: "nowrap",
+                }}
+              >
+                {token.symbol}
+              </div>
+              <div
+                style={{
+                  fontSize: "12px",
+                  color: "hsl(var(--muted-foreground))",
+                  overflow: "hidden",
+                  textOverflow: "ellipsis",
+                  whiteSpace: "nowrap",
+                }}
+              >
+                {token.name}
+              </div>
+            </div>
+
+            {/* Decimals & Chain Info */}
+            <div
+              style={{
+                fontSize: "11px",
+                color: "#666",
+                textAlign: "right",
+                flexShrink: 0,
+              }}
+            >
+              <div>{token.decimals} decimals</div>
+              <div>Chain {token.chainId}</div>
+            </div>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/token-list/defaults.ts

@@ -0,0 +1,39 @@
+/**
+ * Default token list sources for React hooks.
+ */
+
+import type { TokenListSource } from "@naculus/connect-core";
+import {
+  DEFAULT_SOURCES,
+  ETHEREUM_MAINNET_TOKENS,
+  POLYGON_TOKENS,
+  OPTIMISM_TOKENS,
+  ARBITRUM_TOKENS,
+  BASE_TOKENS,
+} from "@naculus/connect-core";
+
+/**
+ * Get default sources for useTokenList / useTokenSearch hooks.
+ * Includes built-in tokens and remote source URLs.
+ */
+export function getDefaultSources(): TokenListSource[] {
+  return [
+    {
+      name: "built-in",
+      tokens: [
+        ...ETHEREUM_MAINNET_TOKENS,
+        ...POLYGON_TOKENS,
+        ...OPTIMISM_TOKENS,
+        ...ARBITRUM_TOKENS,
+        ...BASE_TOKENS,
+      ],
+      enabled: true,
+    },
+    {
+      name: "uniswap-default",
+      url: "https://tokens.uniswap.org",
+      enabled: true,
+      refreshInterval: 24 * 60 * 60 * 1000,
+    },
+  ];
+}

package/src/token-list/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Token Discovery — React hooks and components.
+ *
+ * @see docs/features/token-discovery.md
+ */
+
+export { useTokenList } from "./useTokenList";
+export type { UseTokenListOptions, UseTokenListReturn } from "./useTokenList";
+
+export { useTokenSearch } from "./useTokenSearch";
+export type { UseTokenSearchReturn } from "./useTokenSearch";
+
+export { TokenSelector } from "./TokenSelector";
+export type { TokenSelectorProps } from "./TokenSelector";

package/src/token-list/useTokenList.ts

@@ -0,0 +1,119 @@
+/**
+ * useTokenList — React hook for loading token lists.
+ *
+ * Manages TokenListManager lifecycle and provides reactive
+ * token data scoped to a specific chain.
+ */
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { TokenListManager } from "@naculus/connect-core";
+import type { TokenListEntry, TokenListSource, TokenListManagerConfig } from "@naculus/connect-core";
+
+export interface UseTokenListOptions {
+  /** Auto-load on mount (default: true) */
+  autoLoad?: boolean;
+  /** Custom sources (overrides defaults) */
+  sources?: TokenListSource[];
+}
+
+export interface UseTokenListReturn {
+  /** Loaded tokens for the specified chain */
+  tokens: TokenListEntry[];
+  /** Whether the initial load is in progress */
+  isLoading: boolean;
+  /** Whether tokens have been loaded at least once */
+  isLoaded: boolean;
+  /** Last error, if any */
+  error: Error | null;
+  /** Force a full refresh from all sources */
+  refetch: () => Promise<void>;
+}
+
+/**
+ * React hook for accessing token lists for a specific chain.
+ *
+ * @example
+ * const { tokens, isLoading } = useTokenList("eip155:1");
+ * // tokens → [WETH, USDC, USDT, DAI, ...]
+ */
+export function useTokenList(
+  chainId?: string,
+  options?: UseTokenListOptions,
+): UseTokenListReturn {
+  const managerRef = useRef<TokenListManager | null>(null);
+  const [tokens, setTokens] = useState<TokenListEntry[]>([]);
+  const [isLoading, setIsLoading] = useState(options?.autoLoad !== false);
+  const [isLoaded, setIsLoaded] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Initialize manager once
+  if (!managerRef.current) {
+    const config: Partial<TokenListManagerConfig> = {};
+    if (options?.sources) {
+      config.sources = options.sources;
+    }
+    managerRef.current = new TokenListManager(config);
+  }
+
+  const load = useCallback(async () => {
+    const manager = managerRef.current;
+    if (!manager) return;
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      await manager.load();
+      const numericChainId = chainId ? parseChainId(chainId) : undefined;
+      const loaded = manager.getTokens(
+        numericChainId !== undefined ? { chainId: numericChainId } : undefined,
+      );
+      setTokens(loaded);
+      setIsLoaded(true);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [chainId]);
+
+  const refetch = useCallback(async () => {
+    const manager = managerRef.current;
+    if (!manager) return;
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      await manager.refresh();
+      const numericChainId = chainId ? parseChainId(chainId) : undefined;
+      const loaded = manager.getTokens(
+        numericChainId !== undefined ? { chainId: numericChainId } : undefined,
+      );
+      setTokens(loaded);
+      setIsLoaded(true);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [chainId]);
+
+  useEffect(() => {
+    if (options?.autoLoad !== false) {
+      load();
+    }
+  }, [load, options?.autoLoad]);
+
+  return { tokens, isLoading, isLoaded, error, refetch };
+}
+
+/**
+ * Parse a CAIP-2 chain ID like "eip155:1" into a numeric chain ID (1).
+ * Returns undefined for non-numeric chains.
+ */
+function parseChainId(chainId: string): number | undefined {
+  const parts = chainId.split(":");
+  const numeric = parseInt(parts[parts.length - 1], 10);
+  return isNaN(numeric) ? undefined : numeric;
+}

package/src/token-list/useTokenSearch.ts

@@ -0,0 +1,99 @@
+/**
+ * useTokenSearch — React hook for searching tokens.
+ *
+ * Debounced search over loaded token lists.
+ * Returns structured results (exact + fuzzy matches).
+ */
+
+import { useState, useEffect, useRef, useMemo } from "react";
+import { TokenListManager } from "@naculus/connect-core";
+import type { TokenSearchResult, TokenListSource, TokenListManagerConfig } from "@naculus/connect-core";
+import { getDefaultSources } from "./defaults";
+
+const DEBOUNCE_MS = 300;
+
+export interface UseTokenSearchReturn {
+  /** Structured search results */
+  results: TokenSearchResult;
+  /** Whether a search is currently running */
+  isSearching: boolean;
+}
+
+// Shared manager instance across hooks
+let sharedManager: TokenListManager | null = null;
+
+function getManager(): TokenListManager {
+  if (!sharedManager) {
+    sharedManager = new TokenListManager({
+      sources: getDefaultSources(),
+    });
+    // Start loading in background
+    sharedManager.load().catch(() => {});
+  }
+  return sharedManager;
+}
+
+/**
+ * React hook for searching tokens by symbol, name, or address.
+ *
+ * Debounced 300ms to avoid excessive re-renders during typing.
+ *
+ * @example
+ * const { results, isSearching } = useTokenSearch("USDC");
+ * // results.exact → [USDC on ETH]
+ * // results.fuzzy → [USDC.e on AVAX]
+ */
+export function useTokenSearch(
+  query: string,
+  chainId?: string,
+): UseTokenSearchReturn {
+  const [results, setResults] = useState<TokenSearchResult>({
+    exact: [],
+    fuzzy: [],
+    hasMore: false,
+  });
+  const [isSearching, setIsSearching] = useState(false);
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const trimmedQuery = query.trim();
+
+  useEffect(() => {
+    if (!trimmedQuery) {
+      setResults({ exact: [], fuzzy: [], hasMore: false });
+      setIsSearching(false);
+      return;
+    }
+
+    // Debounce
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current);
+    }
+
+    setIsSearching(true);
+
+    debounceRef.current = setTimeout(() => {
+      const manager = getManager();
+      const numericChainId = chainId ? parseChainId(chainId) : undefined;
+      const searchResults = manager.search(trimmedQuery, {
+        chainId: numericChainId,
+        limit: 20,
+      });
+      setResults(searchResults);
+      setIsSearching(false);
+    }, DEBOUNCE_MS);
+
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, [trimmedQuery, chainId]);
+
+  return { results, isSearching };
+}
+
+function parseChainId(chainId: string): number | undefined {
+  const parts = chainId.split(":");
+  const numeric = parseInt(parts[parts.length - 1], 10);
+  return isNaN(numeric) ? undefined : numeric;
+}