@naculus/connect-appkit-react 0.1.2

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@naculus/connect-appkit-react",
+  "version": "0.1.2",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@stencil/react-output-target": "^1.6.1",
+    "viem": "^2.54.6",
+    "@naculus/connect-core": "^0.1.2",
+    "@naculus/connector-walletconnect": "^0.1.2",
+    "@naculus/connector-evm-injected": "^0.1.2",
+    "@naculus/connector-embedded": "^0.1.2",
+    "@naculus/connector-passkeys": "^0.1.2",
+    "@naculus/connector-solana": "^0.1.2",
+    "@naculus/siwx": "^0.1.2",
+    "@naculus/wallet-engine": "^0.1.2",
+    "@naculus/connect-appkit-wc": "0.1.2"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.0.0",
+    "jsdom": "^25.0.0 || ^26.0.0 || ^28.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.3.6",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/chain-abstraction/index.ts

@@ -0,0 +1,8 @@
+export { useRouteQuote } from "./useRouteQuote";
+export type { UseRouteQuoteInput, UseRouteQuoteReturn, Quote, QuoteOptions } from "./useRouteQuote";
+
+export { useExecuteRoute } from "./useExecuteRoute";
+export type { UseExecuteRouteReturn, ExecuteError, ExecuteRouteResult, ExecuteOptions } from "./useExecuteRoute";
+
+export { useCompareCosts } from "./useCompareCosts";
+export type { UseCompareCostsInput, UseCompareCostsReturn, CostComparison, CostComparisonOperation, CostComparisonOptions } from "./useCompareCosts";

package/src/chain-abstraction/useCompareCosts.ts

@@ -0,0 +1,137 @@
+/**
+ * useCompareCosts — React hook for comparing operation costs across chains.
+ *
+ * Provides reactive state for comparing gas costs, fees, and estimated
+ * times for a given operation across multiple chains.
+ *
+ * @example
+ * ```tsx
+ * import { useCompareCosts } from "@naculus/connect-appkit-react";
+ *
+ * function CostComparisonPanel() {
+ *   const { comparisons, loading, error, refresh } = useCompareCosts({
+ *     operation: "send_erc20",
+ *     chains: ["eip155:1", "eip155:137", "eip155:10"],
+ *   });
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       {comparisons.map(c => (
+ *         <div key={c.chain}>
+ *           {c.chainName}: ${c.totalCost} (gas: ${c.gasCost})
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+import { useState, useEffect, useCallback, useRef } from "react";
+// ── Local type definitions (hook domain types, not core exports) ──────
+
+export interface CostComparison {
+  chain: string;
+  chainName: string;
+  totalCost: string;
+  gasCost: string;
+  estimatedTimeMs: number;
+}
+
+export type CostComparisonOperation = "send_erc20" | "swap" | "bridge" | (string & {});
+
+export interface CostComparisonOptions {
+  amount?: string;
+  token?: string;
+  [key: string]: unknown;
+}
+
+
+export interface UseCompareCostsInput {
+  operation: CostComparisonOperation;
+  chains: string[];
+  options?: CostComparisonOptions;
+}
+
+export interface UseCompareCostsReturn {
+  /** Sorted cost comparisons (cheapest first) */
+  comparisons: CostComparison[];
+  /** Whether a comparison request is in flight */
+  loading: boolean;
+  /** Error that occurred during the last request */
+  error: Error | null;
+  /** Manually trigger a refresh */
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Hook for comparing operation costs across multiple chains.
+ *
+ * Automatically re-fetches when input parameters change.
+ * Helpful for chain selection UIs ("show me the cheapest chain").
+ *
+ * @param input - Comparison parameters
+ * @param compareCostsFn - Function that performs the actual comparison
+ */
+export function useCompareCosts(
+  input: UseCompareCostsInput,
+  compareCostsFn?: (
+    operation: string,
+    chains: string[],
+    options?: CostComparisonOptions,
+  ) => Promise<CostComparison[]>,
+): UseCompareCostsReturn {
+  const { operation, chains, options } = input;
+  const [comparisons, setComparisons] = useState<CostComparison[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const mountedRef = useRef(true);
+
+  const fetchComparisons = useCallback(async () => {
+    if (!chains || chains.length === 0) {
+      setComparisons([]);
+      return;
+    }
+
+    if (!compareCostsFn) return;
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const result = await compareCostsFn(operation, chains, options);
+
+      if (mountedRef.current) {
+        setComparisons(result);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setComparisons([]);
+      }
+    } finally {
+      if (mountedRef.current) {
+        setLoading(false);
+      }
+    }
+  }, [operation, chains, options, compareCostsFn]);
+
+  useEffect(() => {
+    fetchComparisons();
+  }, [fetchComparisons]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const refresh = useCallback(async () => {
+    await fetchComparisons();
+  }, [fetchComparisons]);
+
+  return { comparisons, loading, error, refresh };
+}

package/src/chain-abstraction/useExecuteRoute.ts

@@ -0,0 +1,129 @@
+/**
+ * useExecuteRoute — React hook for executing cross-chain routes.
+ *
+ * Manages the execution lifecycle of a cross-chain transfer.
+ * Tracks execution status, bridge reference, and completion state.
+ *
+ * @example
+ * ```tsx
+ * import { useExecuteRoute } from "@naculus/connect-appkit-react";
+ *
+ * function RouteExecutionPanel({ quote }) {
+ *   const { execute, executing, result, error } = useExecuteRoute();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => execute(quote, "0xRecipient")} disabled={executing}>
+ *         {executing ? "Executing..." : "Execute Route"}
+ *       </button>
+ *       {result && <div>Tx: {result.fromTxHash}</div>}
+ *       {error && <div>Error: {error.message}</div>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+import { useState, useCallback, useRef } from "react";
+// ── Local type definitions (hook domain types, not core exports) ──────
+
+export interface Quote {
+  routeId: string;
+  provider: string;
+  totalCost?: bigint;
+  estimatedTimeMs?: number;
+}
+
+export interface ExecuteRouteResult {
+  fromTxHash: string;
+  toTxHash?: string;
+}
+
+export interface ExecuteOptions {
+  timeoutMs?: number;
+  gasLimit?: bigint;
+}
+
+export interface UseExecuteRouteReturn {
+  /** Execute a route (call this with the selected quote) */
+  execute: (quote: Quote, recipient: string, options?: ExecuteOptions) => Promise<void>;
+  /** Whether execution is in progress */
+  executing: boolean;
+  /** The execution result (populated after successful execution) */
+  result: ExecuteRouteResult | null;
+  /** Error that occurred during execution */
+  error: ExecuteError | null;
+  /** Reset execution state back to initial */
+  reset: () => void;
+}
+
+export interface ExecuteError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Hook for executing a cross-chain route.
+ *
+ * Manages the full lifecycle from calling executeRoute to
+ * tracking the result. For auto-approve flows, handles the
+ * approve → cross-chain sequence.
+ *
+ * @param executeRouteFn - Function that performs the actual route execution
+ */
+export function useExecuteRoute(
+  executeRouteFn?: (quote: Quote, recipient: string, options?: ExecuteOptions) => Promise<ExecuteRouteResult>,
+): UseExecuteRouteReturn {
+  const [executing, setExecuting] = useState(false);
+  const [result, setResult] = useState<ExecuteRouteResult | null>(null);
+  const [error, setError] = useState<ExecuteError | null>(null);
+  const mountedRef = useRef(true);
+
+  const execute = useCallback(async (
+    quote: Quote,
+    recipient: string,
+    options?: ExecuteOptions,
+  ) => {
+    if (!executeRouteFn) {
+      setError({
+        code: "no_executor",
+        message: "No executeRoute function provided",
+      });
+      return;
+    }
+
+    setExecuting(true);
+    setError(null);
+    setResult(null);
+
+    try {
+      const execResult = await executeRouteFn(quote, recipient, options);
+
+      if (mountedRef.current) {
+        setResult(execResult);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        const executionError = err as Error;
+        setError({
+          code: (executionError as any).code ?? "execution_failed",
+          message: executionError.message,
+          details: (executionError as any).details,
+        });
+      }
+    } finally {
+      if (mountedRef.current) {
+        setExecuting(false);
+      }
+    }
+  }, [executeRouteFn]);
+
+  const reset = useCallback(() => {
+    setResult(null);
+    setError(null);
+    setExecuting(false);
+  }, []);
+
+  return { execute, executing, result, error, reset };
+}

package/src/chain-abstraction/useRouteQuote.ts

@@ -0,0 +1,168 @@
+/**
+ * useRouteQuote — React hook for cross-chain route quoting.
+ *
+ * Provides reactive state for discovering routes and getting quotes
+ * from the RouteEngine. Returns loading, error, and result states.
+ *
+ * @example
+ * ```tsx
+ * import { useRouteQuote } from "@naculus/connect-appkit-react";
+ *
+ * function QuotePanel() {
+ *   const { quotes, loading, error, refresh } = useRouteQuote({
+ *     fromChain: "eip155:1",
+ *     toChain: "eip155:137",
+ *     fromToken: "USDC",
+ *     amount: "1000000",
+ *   });
+ *
+ *   if (loading) return <div>Loading quotes...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {quotes.map(q => (
+ *         <div key={q.routeId}>
+ *           {q.provider} — {q.netReceiveFormatted} {q.toTokenSymbol}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+import { useState, useEffect, useCallback, useRef } from "react";
+// ── Local type definitions (hook domain types, not core exports) ──────
+
+export interface Quote {
+  routeId: string;
+  provider: string;
+  netReceiveFormatted: string;
+  toTokenSymbol: string;
+}
+
+export interface QuoteOptions {
+  sortBy?: "cost" | "time" | "balance";
+  maxSlippage?: number;
+}
+
+export interface UseRouteQuoteInput {
+  fromChain: string;
+  toChain: string;
+  fromToken: string;
+  toToken?: string;
+  amount: string;
+  options?: QuoteOptions;
+}
+
+export interface UseRouteQuoteReturn {
+  /** Current list of quotes (sorted by options.sortBy) */
+  quotes: Quote[];
+  /** Whether a quote request is in flight */
+  loading: boolean;
+  /** Error that occurred during the last request */
+  error: Error | null;
+  /** Manually trigger a refresh (re-fetches quotes) */
+  refresh: () => Promise<void>;
+  /** Clear the current quotes and error state */
+  clear: () => void;
+}
+
+/**
+ * Hook for fetching cross-chain route quotes.
+ *
+ * Automatically re-fetches when input parameters change.
+ * Debounces rapid changes to avoid excessive API calls.
+ *
+ * @param input - Quote request parameters
+ * @param getQuoteFn - Function that performs the actual quote fetch
+ */
+export function useRouteQuote(
+  input: UseRouteQuoteInput,
+  getQuoteFn?: (from: string, to: string, token: string, amount: string, options?: QuoteOptions) => Promise<Quote[]>,
+): UseRouteQuoteReturn {
+  const { fromChain, toChain, fromToken, toToken, amount, options } = input;
+  const [quotes, setQuotes] = useState<Quote[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const mountedRef = useRef(true);
+
+  const fetchQuotes = useCallback(async () => {
+    if (!fromChain || !toChain || !fromToken || !amount || BigInt(amount) <= 0n) {
+      setQuotes([]);
+      return;
+    }
+
+    if (!getQuoteFn) return;
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const result = await getQuoteFn(
+        fromChain,
+        toChain,
+        fromToken,
+        amount,
+        options,
+      );
+
+      if (mountedRef.current) {
+        setQuotes(result);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setQuotes([]);
+      }
+    } finally {
+      if (mountedRef.current) {
+        setLoading(false);
+      }
+    }
+  }, [fromChain, toChain, fromToken, amount, options, getQuoteFn]);
+
+  // Debounced auto-fetch on input change
+  useEffect(() => {
+    if (debounceTimer.current) {
+      clearTimeout(debounceTimer.current);
+    }
+
+    // Don't fetch if parameters are incomplete
+    if (!fromChain || !toChain || !fromToken || !amount) {
+      setQuotes([]);
+      return;
+    }
+
+    debounceTimer.current = setTimeout(() => {
+      fetchQuotes();
+    }, 300); // 300ms debounce
+
+    return () => {
+      if (debounceTimer.current) {
+        clearTimeout(debounceTimer.current);
+      }
+    };
+  }, [fetchQuotes, fromChain, toChain, fromToken, amount]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const refresh = useCallback(async () => {
+    await fetchQuotes();
+  }, [fetchQuotes]);
+
+  const clear = useCallback(() => {
+    setQuotes([]);
+    setError(null);
+    setLoading(false);
+  }, []);
+
+  return { quotes, loading, error, refresh, clear };
+}