@ton/appkit-react 0.0.6-alpha.2 → 1.0.0-alpha.0

package/src/features/swap/components/swap-info/swap-info.tsx

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { ComponentProps, FC } from 'react';
+import type { SwapQuote, SwapProvider } from '@ton/appkit';
+
+import { InfoBlock } from '../../../../components/ui/info-block';
+import { useI18n } from '../../../settings/hooks/use-i18n';
+import type { AppkitUIToken } from '../../../../types/appkit-ui-token';
+import { getDisplayAmount } from '../../utils/get-display-amount';
+
+export interface SwapInfoProps extends ComponentProps<typeof InfoBlock.Container> {
+    toToken: AppkitUIToken | null;
+    slippage: number;
+    provider?: SwapProvider;
+    quote?: SwapQuote;
+    isQuoteLoading?: boolean;
+}
+
+export const SwapInfo: FC<SwapInfoProps> = ({ quote, provider, toToken, slippage, isQuoteLoading, ...props }) => {
+    const { t } = useI18n();
+
+    const minReceived = `${getDisplayAmount(quote?.minReceived, toToken?.decimals)} ${toToken?.symbol || ''}`;
+    const providerName = provider?.getMetadata().name;
+    const slippagePercent = `${(slippage / 100).toFixed(2)}%`;
+
+    return (
+        <InfoBlock.Container {...props}>
+            <InfoBlock.Row>
+                <InfoBlock.Label>{t('swap.minReceived')}</InfoBlock.Label>
+                {isQuoteLoading ? <InfoBlock.ValueSkeleton /> : <InfoBlock.Value>{minReceived}</InfoBlock.Value>}
+            </InfoBlock.Row>
+            <InfoBlock.Row>
+                <InfoBlock.Label>{t('swap.slippage')}</InfoBlock.Label>
+                <InfoBlock.Value>{slippagePercent}</InfoBlock.Value>
+            </InfoBlock.Row>
+            <InfoBlock.Row>
+                <InfoBlock.Label>{t('swap.provider')}</InfoBlock.Label>
+                {providerName ? <InfoBlock.Value>{providerName}</InfoBlock.Value> : <InfoBlock.ValueSkeleton />}
+            </InfoBlock.Row>
+        </InfoBlock.Container>
+    );
+};

package/src/features/swap/components/swap-settings-modal/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+export { SwapSettingsModal } from './swap-settings-modal';
+export type { SwapSettingsModalProps } from './swap-settings-modal';

package/src/features/swap/components/swap-settings-modal/swap-settings-modal.tsx

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { useEffect, useMemo, useState } from 'react';
+import type { FC } from 'react';
+import type { SwapProvider } from '@ton/appkit';
+
+import { Modal } from '../../../../components/ui/modal/modal';
+import { Button } from '../../../../components/ui/button';
+import { OptionSwitcher } from '../../../../components/shared/option-switcher';
+import { useI18n } from '../../../settings/hooks/use-i18n';
+import styles from './swap-settings-modal.module.css';
+
+/** Preset slippage values in basis points */
+const SLIPPAGE_PRESETS = [50, 100, 200] as const;
+
+const formatSlippage = (bps: number): string => `${(bps / 100).toFixed(2)}%`;
+
+const SLIPPAGE_OPTIONS = SLIPPAGE_PRESETS.map((bps) => ({ value: String(bps), label: formatSlippage(bps) }));
+
+export interface SwapSettingsModalProps {
+    open: boolean;
+    onClose: () => void;
+    slippage: number;
+    onSlippageChange: (bps: number) => void;
+    provider: SwapProvider | undefined;
+    providers: SwapProvider[];
+    onProviderChange: (providerId: string) => void;
+}
+
+export const SwapSettingsModal: FC<SwapSettingsModalProps> = ({
+    open,
+    onClose,
+    slippage,
+    onSlippageChange,
+    provider,
+    providers,
+    onProviderChange,
+}) => {
+    const { t } = useI18n();
+
+    const [stagedProviderId, setStagedProviderId] = useState<string | undefined>(provider?.providerId);
+    const [stagedSlippage, setStagedSlippage] = useState(slippage);
+
+    // Reset the staged values each time the modal reopens so values from an abandoned
+    // session don't leak into the next one.
+    useEffect(() => {
+        if (open) {
+            setStagedProviderId(provider?.providerId);
+            setStagedSlippage(slippage);
+        }
+    }, [open, provider?.providerId, slippage]);
+
+    const providerOptions = useMemo(
+        () => providers.map((p) => ({ value: p.providerId, label: p.getMetadata().name })),
+        [providers],
+    );
+
+    const handleSave = () => {
+        if (stagedSlippage !== slippage) onSlippageChange(stagedSlippage);
+        if (stagedProviderId && stagedProviderId !== provider?.providerId) onProviderChange(stagedProviderId);
+        onClose();
+    };
+
+    return (
+        <Modal open={open} onOpenChange={(isOpen) => !isOpen && onClose()} title={t('swap.settings')}>
+            <div className={styles.rows}>
+                <div className={styles.row}>
+                    <span className={styles.label}>{t('swap.provider')}</span>
+                    <OptionSwitcher value={stagedProviderId} options={providerOptions} onChange={setStagedProviderId} />
+                </div>
+                <div className={styles.row}>
+                    <span className={styles.label}>{t('swap.slippage')}</span>
+                    <OptionSwitcher
+                        value={String(stagedSlippage)}
+                        options={SLIPPAGE_OPTIONS}
+                        onChange={(v) => setStagedSlippage(Number(v))}
+                    />
+                </div>
+            </div>
+
+            <Button className={styles.saveButton} variant="fill" size="l" fullWidth onClick={handleSave}>
+                {t('swap.save')}
+            </Button>
+        </Modal>
+    );
+};

package/src/features/swap/components/swap-token-select-modal/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+export { SwapTokenSelectModal } from './swap-token-select-modal';
+export type { SwapTokenSelectModalProps } from './swap-token-select-modal';

package/src/features/swap/components/swap-token-select-modal/swap-token-select-modal.tsx

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { FC } from 'react';
+
+import { TokenSelectModal } from '../../../../components/shared/token-select-modal';
+import type { TokenSelectModalProps } from '../../../../components/shared/token-select-modal';
+import { useI18n } from '../../../settings/hooks/use-i18n';
+
+export type SwapTokenSelectModalProps = Omit<TokenSelectModalProps, 'title' | 'searchPlaceholder'>;
+
+export const SwapTokenSelectModal: FC<SwapTokenSelectModalProps> = (props) => {
+    const { t } = useI18n();
+
+    return <TokenSelectModal {...props} title={t('swap.selectToken')} searchPlaceholder={t('swap.searchToken')} />;
+};

package/src/features/swap/components/swap-widget/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+export * from './swap-widget';

package/src/features/swap/components/swap-widget/swap-widget.tsx

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { FC, ReactNode, ComponentProps } from 'react';
+
+import type { SwapWidgetRenderProps } from '../swap-widget-ui';
+import { SwapWidgetUI } from '../swap-widget-ui';
+import { SwapWidgetProvider, useSwapContext } from '../swap-widget-provider';
+import type { SwapProviderProps } from '../swap-widget-provider';
+
+/**
+ * Props for the SwapWidget component.
+ * Inherits all configuration from SwapProviderProps.
+ */
+export interface SwapWidgetProps extends Omit<SwapProviderProps, 'children'>, Omit<ComponentProps<'div'>, 'children'> {
+    /**
+     * Custom render function.
+     * When provided, it replaces the default widget UI and gives full control over the rendering.
+     * Accesses all state and actions from the swap context.
+     */
+    children?: (props: SwapWidgetRenderProps) => ReactNode;
+}
+
+const SwapWidgetContent: FC<
+    { children?: (props: SwapWidgetRenderProps) => ReactNode } & Omit<ComponentProps<'div'>, 'children'>
+> = ({ children, ...rest }) => {
+    const ctx = useSwapContext();
+
+    if (children) {
+        return <>{children({ ...ctx, ...rest })}</>;
+    }
+
+    return <SwapWidgetUI {...ctx} {...rest} />;
+};
+
+/**
+ * A high-level component that provides a complete swap interface.
+ *
+ * It manages the token selection, quote fetching, and transaction building
+ * for swaps between TON and Jettons. It can be used as a standalone widget
+ * with default UI or customized using a render function.
+ */
+export const SwapWidget: FC<SwapWidgetProps> = ({
+    children,
+    tokens,
+    network,
+    fiatSymbol,
+    defaultFromSymbol,
+    defaultToSymbol,
+    defaultSlippage,
+    ...rest
+}) => {
+    return (
+        <SwapWidgetProvider
+            tokens={tokens}
+            network={network}
+            fiatSymbol={fiatSymbol}
+            defaultFromSymbol={defaultFromSymbol}
+            defaultToSymbol={defaultToSymbol}
+            defaultSlippage={defaultSlippage}
+        >
+            <SwapWidgetContent {...rest}>{children}</SwapWidgetContent>
+        </SwapWidgetProvider>
+    );
+};

package/src/features/swap/components/swap-widget-provider/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+export * from './swap-widget-provider';

package/src/features/swap/components/swap-widget-provider/swap-widget-provider.tsx

@@ -0,0 +1,379 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { createContext, useCallback, useContext, useMemo, useState } from 'react';
+import type { FC, PropsWithChildren } from 'react';
+import { formatUnits } from '@ton/appkit';
+import type { Network } from '@ton/appkit';
+import type { GetSwapQuoteData } from '@ton/appkit/queries';
+import type { SwapProvider } from '@ton/appkit';
+import { getTonShortfall } from '@ton/appkit';
+import type { TonShortfall } from '@ton/appkit';
+import { calcMaxSpendable } from '@ton/appkit';
+
+import { useSwapQuote } from '../../hooks/use-swap-quote';
+import { useSwapProvider } from '../../hooks/use-swap-provider';
+import { useSwapProviders } from '../../hooks/use-swap-providers';
+import { useBuildSwapTransaction } from '../../hooks/use-build-swap-transaction';
+import { useAddress } from '../../../wallets';
+import { useBalance } from '../../../balances/hooks/use-balance';
+import { useNetwork } from '../../../network';
+import { useSendTransaction } from '../../../transaction/hooks/use-send-transaction';
+import { useDebounceValue } from '../../../../hooks/use-debounce-value';
+import type { AppkitUIToken } from '../../../../types/appkit-ui-token';
+import { mapSwapWidgetTokens } from '../../utils/map-swap-widget-tokens';
+import { useSwapTokenState } from './use-swap-token-state';
+import { useSwapBalances } from './use-swap-balances';
+import { useSwapValidation } from './use-swap-validation';
+
+export type { AppkitUIToken };
+
+/**
+ * Context type for the SwapWidget.
+ * Provides all necessary state and actions for building custom swap UIs.
+ */
+export interface SwapContextType {
+    /** Full list of available tokens for swapping */
+    tokens: AppkitUIToken[];
+    /** Currently selected source token */
+    fromToken: AppkitUIToken | null;
+    /** Currently selected target token */
+    toToken: AppkitUIToken | null;
+    /** Amount the user wants to swap (string to preserve input UX) */
+    fromAmount: string;
+    /** Calculated receive amount from the current quote */
+    toAmount: string;
+    /** Fiat currency symbol for price display, e.g. "$" */
+    fiatSymbol: string;
+    /** User's balance of the "from" token */
+    fromBalance: string | undefined;
+    /** User's balance of the "to" token */
+    toBalance: string | undefined;
+    /** True while the "from" balance is being fetched */
+    isFromBalanceLoading: boolean;
+    /** True while the "to" balance is being fetched */
+    isToBalanceLoading: boolean;
+    /** Whether the user can proceed with the swap (checks balance, amount, quote) */
+    canSubmit: boolean;
+    /** Raw swap quote from the provider */
+    quote: GetSwapQuoteData | undefined;
+    /** True while the quote is being fetched from the API */
+    isQuoteLoading: boolean;
+    /** Current validation or fetch error, null when everything is ok */
+    error: string | null;
+    /** Slippage tolerance in basis points (100 = 1%) */
+    slippage: number;
+    /** Currently selected swap provider (defaults to the first registered one) */
+    swapProvider: SwapProvider | undefined;
+    /** All registered swap providers */
+    swapProviders: SwapProvider[];
+    /** Updates the selected swap provider */
+    setSwapProviderId: (providerId: string) => void;
+    /** Updates the source token */
+    setFromToken: (token: AppkitUIToken) => void;
+    /** Updates the target token */
+    setToToken: (token: AppkitUIToken) => void;
+    /** Updates the swap amount */
+    setFromAmount: (amount: string) => void;
+    /** Updates the slippage tolerance */
+    setSlippage: (slippage: number) => void;
+    /** Swaps source and target tokens */
+    onFlip: () => void;
+    /** Sets the "from" amount to the maximum available balance */
+    onMaxClick: () => void;
+    /** Executes the swap transaction */
+    sendSwapTransaction: () => Promise<void>;
+    /** True while a transaction is being built or sent */
+    isSendingTransaction: boolean;
+    /** True when the built transaction outflow exceeds the user's TON balance */
+    isLowBalanceWarningOpen: boolean;
+    /** `reduce` when the outgoing token is TON (user can fix by changing amount), `topup` otherwise. */
+    lowBalanceMode: 'reduce' | 'topup';
+    /** Required TON amount for the pending operation, formatted as a decimal string. Empty when no pending op. */
+    lowBalanceRequiredTon: string;
+    /** Replace the input with a value that fits into the current TON balance and close the warning */
+    onLowBalanceChange: () => void;
+    /** Dismiss the low-balance warning without changing the input */
+    onLowBalanceCancel: () => void;
+}
+
+export const SwapContext = createContext<SwapContextType>({
+    tokens: [],
+    fromToken: null,
+    toToken: null,
+    fromAmount: '',
+    toAmount: '',
+    fiatSymbol: '$',
+    fromBalance: undefined,
+    toBalance: undefined,
+    isFromBalanceLoading: false,
+    isToBalanceLoading: false,
+    canSubmit: false,
+    quote: undefined,
+    isQuoteLoading: false,
+    error: null,
+    slippage: 50,
+    swapProvider: undefined,
+    swapProviders: [],
+    setSwapProviderId: () => {},
+    setFromToken: () => {},
+    setToToken: () => {},
+    setFromAmount: () => {},
+    setSlippage: () => {},
+    onFlip: () => {},
+    onMaxClick: () => {},
+    sendSwapTransaction: () => Promise.resolve(),
+    isSendingTransaction: false,
+    isLowBalanceWarningOpen: false,
+    lowBalanceMode: 'reduce',
+    lowBalanceRequiredTon: '',
+    onLowBalanceChange: () => {},
+    onLowBalanceCancel: () => {},
+});
+
+/**
+ * Hook to access the swap context.
+ * Must be used within a SwapWidgetProvider (or SwapWidget).
+ */
+export function useSwapContext() {
+    return useContext(SwapContext);
+}
+
+/**
+ * Props for the SwapWidgetProvider.
+ */
+export interface SwapProviderProps extends PropsWithChildren {
+    /** Full list of tokens available for swapping in the UI */
+    tokens: AppkitUIToken[];
+    /** Network to use for quote fetching. When omitted, uses the selected wallet's network. */
+    network?: Network;
+    /** Fiat currency symbol for price display, defaults to "$" */
+    fiatSymbol?: string;
+    /** Ticker of the token pre-selected for the source */
+    defaultFromSymbol?: string;
+    /** Ticker of the token pre-selected for the target */
+    defaultToSymbol?: string;
+    /** Initial slippage in basis points (100 = 1%), defaults to 100 (1%) */
+    defaultSlippage?: number;
+}
+
+export const SwapWidgetProvider: FC<SwapProviderProps> = ({
+    children,
+    tokens,
+    network: networkProp,
+    fiatSymbol = '$',
+    defaultFromSymbol,
+    defaultToSymbol,
+    defaultSlippage = 100,
+}) => {
+    // Input prep — derived from props, consumed by local-state hooks below.
+    const mappedTokens = useMemo(() => mapSwapWidgetTokens(tokens), [tokens]);
+
+    // 2. Queries and external readers (hoisted: `network` gates token filtering for local state below)
+    const walletNetwork = useNetwork();
+    const network = networkProp ?? walletNetwork;
+
+    const networkFilteredTokens = useMemo(
+        () => (network ? mappedTokens.filter((t) => t.network.chainId === network.chainId) : mappedTokens),
+        [mappedTokens, network],
+    );
+
+    // 1. Local state
+    const { fromToken, toToken, fromAmount, setFromToken, setToToken, setFromAmount, onFlip } = useSwapTokenState({
+        mappedTokens: networkFilteredTokens,
+        defaultFromSymbol,
+        defaultToSymbol,
+    });
+    const [slippage, setSlippage] = useState(defaultSlippage);
+    const [fromAmountDebounced] = useDebounceValue(fromAmount, 500);
+    const [pendingSwap, setPendingSwap] = useState<TonShortfall | undefined>(undefined);
+    const address = useAddress();
+    const [swapProvider, setSwapProviderId] = useSwapProvider();
+    const swapProviders = useSwapProviders();
+
+    // Stabilized query inputs — kept next to the query that consumes them.
+    const fromTokenParam = useMemo(
+        () =>
+            fromToken
+                ? {
+                      address: fromToken.address,
+                      decimals: fromToken.decimals,
+                      symbol: fromToken.symbol,
+                      name: fromToken.name,
+                  }
+                : undefined,
+        [fromToken],
+    );
+    const toTokenParam = useMemo(
+        () =>
+            toToken
+                ? { address: toToken.address, decimals: toToken.decimals, symbol: toToken.symbol, name: toToken.name }
+                : undefined,
+        [toToken],
+    );
+
+    const isNetworkSupported = useMemo(
+        () =>
+            !swapProvider || !network || swapProvider.getSupportedNetworks().some((n) => n.chainId === network.chainId),
+        [swapProvider, network],
+    );
+
+    const {
+        data: quote,
+        isFetching: isQuoteFetching,
+        error: quoteError,
+    } = useSwapQuote({
+        from: fromTokenParam,
+        to: toTokenParam,
+        amount: fromAmountDebounced,
+        network,
+        slippageBps: slippage,
+        providerId: swapProvider?.providerId,
+        query: { enabled: isNetworkSupported },
+    });
+    // Also show "loading" while the user is still typing (debounce in-flight) so the UI doesn't flash
+    // the previous quote as if it were final.
+    const isQuoteLoading = isQuoteFetching || fromAmount !== fromAmountDebounced;
+    const { fromBalance, toBalance, isFromBalanceLoading, isToBalanceLoading } = useSwapBalances({
+        fromToken,
+        toToken,
+        ownerAddress: address ?? undefined,
+        network,
+    });
+    const { data: tonBalance } = useBalance({ network, query: { refetchInterval: 5000 } });
+
+    // 3. Derivations
+    const toAmount = quote?.toAmount ?? '';
+    const { error, canSubmit } = useSwapValidation({
+        fromAmount,
+        fromAmountDebounced,
+        fromToken,
+        toToken,
+        fromBalance,
+        quoteError,
+        isNetworkSupported,
+    });
+    const isLowBalanceWarningOpen = pendingSwap !== undefined;
+    const lowBalanceMode: 'reduce' | 'topup' = pendingSwap?.mode ?? 'reduce';
+    const lowBalanceRequiredTon = useMemo(() => {
+        if (!pendingSwap) return '';
+        return formatUnits(pendingSwap.requiredNanos, 9);
+    }, [pendingSwap]);
+
+    // 4. Mutations
+    const { mutateAsync: buildTransaction, isPending: isBuildingTransaction } = useBuildSwapTransaction();
+    const { mutateAsync: sendTransaction, isPending: isSendingPending } = useSendTransaction();
+    const isSendingTransaction = isBuildingTransaction || isSendingPending;
+
+    // 5. Callbacks
+    const handleMaxClick = useCallback(() => {
+        if (!fromBalance || !fromToken) return;
+        setFromAmount(calcMaxSpendable({ balance: fromBalance, token: fromToken, feeReserveNanos: 350_000_000n }));
+    }, [fromBalance, fromToken, setFromAmount]);
+
+    const sendSwapTransaction = useCallback(async () => {
+        if (!quote || !address || !fromToken) return;
+
+        const tx = await buildTransaction({ quote, userAddress: address });
+
+        const shortfall = getTonShortfall({
+            messages: tx.messages,
+            tonBalance,
+            fromToken,
+            fromAmount,
+        });
+
+        if (shortfall) {
+            setPendingSwap(shortfall);
+            return;
+        }
+
+        await sendTransaction(tx);
+    }, [quote, address, fromToken, fromAmount, buildTransaction, sendTransaction, tonBalance]);
+
+    const onLowBalanceChange = useCallback(() => {
+        if (!pendingSwap || pendingSwap.mode !== 'reduce') return;
+        setFromAmount(pendingSwap.suggestedFromAmount);
+        setPendingSwap(undefined);
+    }, [pendingSwap, setFromAmount]);
+
+    const onLowBalanceCancel = useCallback(() => {
+        setPendingSwap(undefined);
+    }, []);
+
+    const value = useMemo(
+        () => ({
+            tokens: networkFilteredTokens,
+            fromToken,
+            toToken,
+            fromAmount,
+            toAmount,
+            fiatSymbol,
+            fromBalance,
+            toBalance,
+            isFromBalanceLoading,
+            isToBalanceLoading,
+            canSubmit,
+            quote,
+            isQuoteLoading,
+            error,
+            slippage,
+            swapProvider,
+            swapProviders,
+            setSwapProviderId,
+            setFromToken,
+            setToToken,
+            setFromAmount,
+            setSlippage,
+            onFlip,
+            onMaxClick: handleMaxClick,
+            sendSwapTransaction,
+            isSendingTransaction,
+            isLowBalanceWarningOpen,
+            lowBalanceMode,
+            lowBalanceRequiredTon,
+            onLowBalanceChange,
+            onLowBalanceCancel,
+        }),
+        [
+            networkFilteredTokens,
+            fromToken,
+            toToken,
+            fromAmount,
+            toAmount,
+            fiatSymbol,
+            fromBalance,
+            toBalance,
+            isFromBalanceLoading,
+            isToBalanceLoading,
+            canSubmit,
+            quote,
+            isQuoteLoading,
+            error,
+            slippage,
+            swapProvider,
+            swapProviders,
+            setSwapProviderId,
+            setFromToken,
+            setToToken,
+            setFromAmount,
+            setSlippage,
+            onFlip,
+            handleMaxClick,
+            sendSwapTransaction,
+            isSendingTransaction,
+            isLowBalanceWarningOpen,
+            lowBalanceMode,
+            lowBalanceRequiredTon,
+            onLowBalanceChange,
+            onLowBalanceCancel,
+        ],
+    );
+
+    return <SwapContext.Provider value={value}>{children}</SwapContext.Provider>;
+};