tsdoc for combined hooks (#373)

* chore: tsdocs for useGetSwapPrices

* chore: useGetSwapQuotes tsdoc

* chore: pacakge build

* docs: modify link to docs

Author: VGabriel45

packages/connect/src/styles.ts

@@ -302,9 +302,6 @@ export const styles = String.raw`
   .my-4 {
     margin-block: calc(var(--spacing) * 4);
   }
-  .mt-0 {
-    margin-top: calc(var(--spacing) * 0);
-  }
   .mt-0\.5 {
     margin-top: calc(var(--spacing) * 0.5);
   }
@@ -386,9 +383,6 @@ export const styles = String.raw`
   .inline-flex {
     display: inline-flex;
   }
-  .table {
-    display: table;
-  }
   .aspect-square {
     aspect-ratio: 1 / 1;
   }
@@ -482,9 +476,6 @@ export const styles = String.raw`
   .min-h-full {
     min-height: 100%;
   }
-  .w-1 {
-    width: calc(var(--spacing) * 1);
-  }
   .w-1\/2 {
     width: calc(1/2 * 100%);
   }
@@ -560,9 +551,6 @@ export const styles = String.raw`
   .w-screen {
     width: 100vw;
   }
-  .max-w-1 {
-    max-width: calc(var(--spacing) * 1);
-  }
   .max-w-1\/2 {
     max-width: calc(1/2 * 100%);
   }
@@ -587,21 +575,12 @@ export const styles = String.raw`
   .min-w-full {
     min-width: 100%;
   }
-  .flex-shrink {
-    flex-shrink: 1;
-  }
   .shrink-0 {
     flex-shrink: 0;
   }
-  .flex-grow {
-    flex-grow: 1;
-  }
   .grow {
     flex-grow: 1;
   }
-  .border-collapse {
-    border-collapse: collapse;
-  }
   .origin-top {
     transform-origin: top;
   }
@@ -943,9 +922,6 @@ export const styles = String.raw`
   .pt-0 {
     padding-top: calc(var(--spacing) * 0);
   }
-  .pt-1 {
-    padding-top: calc(var(--spacing) * 1);
-  }
   .pt-1\.5 {
     padding-top: calc(var(--spacing) * 1.5);
   }
@@ -1215,9 +1191,6 @@ export const styles = String.raw`
   .ring-border-normal {
     --tw-ring-color: var(--seq-color-border-normal);
   }
-  .ring-white {
-    --tw-ring-color: var(--color-white);
-  }
   .ring-white\/10 {
     --tw-ring-color: color-mix(in oklab, var(--color-white) 10%, transparent);
   }
@@ -1253,10 +1226,6 @@ export const styles = String.raw`
     -webkit-backdrop-filter: var(--tw-backdrop-blur,) var(--tw-backdrop-brightness,) var(--tw-backdrop-contrast,) var(--tw-backdrop-grayscale,) var(--tw-backdrop-hue-rotate,) var(--tw-backdrop-invert,) var(--tw-backdrop-opacity,) var(--tw-backdrop-saturate,) var(--tw-backdrop-sepia,);
     backdrop-filter: var(--tw-backdrop-blur,) var(--tw-backdrop-brightness,) var(--tw-backdrop-contrast,) var(--tw-backdrop-grayscale,) var(--tw-backdrop-hue-rotate,) var(--tw-backdrop-invert,) var(--tw-backdrop-opacity,) var(--tw-backdrop-saturate,) var(--tw-backdrop-sepia,);
   }
-  .backdrop-filter {
-    -webkit-backdrop-filter: var(--tw-backdrop-blur,) var(--tw-backdrop-brightness,) var(--tw-backdrop-contrast,) var(--tw-backdrop-grayscale,) var(--tw-backdrop-hue-rotate,) var(--tw-backdrop-invert,) var(--tw-backdrop-opacity,) var(--tw-backdrop-saturate,) var(--tw-backdrop-sepia,);
-    backdrop-filter: var(--tw-backdrop-blur,) var(--tw-backdrop-brightness,) var(--tw-backdrop-contrast,) var(--tw-backdrop-grayscale,) var(--tw-backdrop-hue-rotate,) var(--tw-backdrop-invert,) var(--tw-backdrop-opacity,) var(--tw-backdrop-saturate,) var(--tw-backdrop-sepia,);
-  }
   .transition {
     transition-property: color, background-color, border-color, outline-color, text-decoration-color, fill, stroke, --tw-gradient-from, --tw-gradient-via, --tw-gradient-to, opacity, box-shadow, transform, translate, scale, rotate, filter, -webkit-backdrop-filter, backdrop-filter;
     transition-timing-function: var(--tw-ease, var(--default-transition-timing-function));

packages/hooks/src/hooks/Combination/useGetSwapPrices.ts

@@ -15,12 +15,28 @@ interface Balance {
   balance: string
 }
 
+/**
+ * Type representing a swap price with additional currency information
+ *
+ * @property price - The swap price information from the API
+ * @property info - Contract information for the currency, including name, symbol, decimals, etc.
+ * @property balance - The user's balance of this currency
+ */
 export type SwapPricesWithCurrencyInfo = {
   price: SwapPrice
   info: ContractInfo | undefined
   balance: Balance
 }
 
+/**
+ * Arguments for the useGetSwapPrices hook
+ *
+ * @property userAddress - The address of the user's wallet
+ * @property buyCurrencyAddress - The address of the currency to buy
+ * @property buyAmount - The amount of currency to buy (in base units)
+ * @property chainId - The chain ID where the swap will occur
+ * @property withContractInfo - Whether to fetch additional contract info for each currency
+ */
 export interface UseGetSwapPricesArgs {
   userAddress: string
   buyCurrencyAddress: string
@@ -138,7 +154,59 @@ const getSwapPrices = async (
 }
 
 /**
- * @description Gets the Swap Prices for a given currency
+ * Hook to fetch available swap prices for a given currency pair.
+ *
+ * This hook provides functionality to:
+ * - Get swap prices for a specified currency and amount
+ * - Fetch token information and balances for available swap options
+ * - Support both native tokens and ERC20 tokens
+ * - Handle currency conversions and price formatting
+ *
+ * The hook automatically handles:
+ * - Native token address normalization (between 0x0 and 0xEEE...)
+ * - Contract information fetching (name, symbol, decimals, etc.)
+ * - Error handling for failed API calls or balance fetches
+ *
+ * @see {@link https://docs.sequence.xyz/sdk/web/hooks/useGetSwapPrices} for more detailed documentation.
+ *
+ * @param args - Configuration object for the swap prices query {@link UseGetSwapPricesArgs}
+ * @param options - Optional configuration for the hook behavior {@link HooksOptions}
+ *
+ * @returns A React Query result object containing:
+ * - data: Array of {@link SwapPricesWithCurrencyInfo} objects
+ * - isLoading: Whether the query is in progress
+ * - isError: Whether an error occurred
+ * - error: Any error that occurred
+ * - Other standard React Query properties
+ *
+ * @example
+ * ```tsx
+ * import { useGetSwapPrices } from '@0xsequence/hooks'
+ *
+ * function SwapComponent() {
+ *   const { data: swapPrices, isLoading } = useGetSwapPrices({
+ *     userAddress: '0x123...',
+ *     buyCurrencyAddress: '0x456...',
+ *     buyAmount: '1000000000000000000', // 1 token in base units
+ *     chainId: 1,
+ *     withContractInfo: true
+ *   })
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *
+ *   return (
+ *     <div>
+ *       {swapPrices?.map(swap => (
+ *         <div key={swap.info?.address}>
+ *           Token: {swap.info?.symbol}
+ *           Price: {swap.price.price}
+ *           Balance: {swap.balance.balance}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ * ```
  */
 export const useGetSwapPrices = (args: UseGetSwapPricesArgs, options?: HooksOptions) => {
   const apiClient = useAPIClient()

packages/hooks/src/hooks/Combination/useGetSwapQuote.ts

@@ -7,7 +7,78 @@ import { compareAddress } from '../../utils/helpers'
 import { useAPIClient } from '../API/useAPIClient'
 
 /**
- * @description Gets the swap quote for a given currency pair
+ * Hook to fetch a swap quote for exchanging between two currencies.
+ *
+ * This hook provides functionality to:
+ * - Get a quote for swapping between two currencies (native or ERC20)
+ * - Fetch necessary approval data for ERC20 tokens
+ * - Generate transaction data for executing the swap
+ *
+ * The hook automatically handles:
+ * - Native token address normalization (between 0x0 and 0xEEE...)
+ * - Approval data generation for ERC20 tokens when needed
+ * - Transaction data generation for the swap
+ * - Error handling for failed API calls
+ *
+ * Go to {@link https://docs.sequence.xyz/sdk/web/hooks/useGetSwapQuote} for more detailed documentation.
+ *
+ * @param getSwapQuoteArgs - Configuration object for the swap quote query:
+ * - userAddress: The address of the user's wallet
+ * - buyCurrencyAddress: The address of the currency to buy
+ * - sellCurrencyAddress: The address of the currency to sell
+ * - buyAmount: The amount of currency to buy (in base units)
+ * - chainId: The chain ID where the swap will occur
+ * - includeApprove: Whether to include approval data for ERC20 tokens
+ *
+ * @param options - Optional configuration for the hook behavior:
+ * - disabled: Whether to disable the query
+ * - retry: Whether to retry failed queries
+ * - Other standard React Query options
+ *
+ * @returns A React Query result object containing:
+ * - data: The swap quote data including:
+ *   - currencyAddress: The address of the currency being swapped
+ *   - currencyBalance: The user's balance of the currency
+ *   - price: The price for the swap
+ *   - maxPrice: The maximum price (including slippage)
+ *   - to: The target contract address for the swap
+ *   - transactionData: The calldata for the swap transaction
+ *   - transactionValue: The value to send with the transaction (for native tokens)
+ *   - approveData: The approval transaction data (if needed)
+ * - isLoading: Whether the query is in progress
+ * - isError: Whether an error occurred
+ * - error: Any error that occurred
+ * - Other standard React Query properties
+ *
+ * @see {@link https://docs.sequence.xyz/sdk/web/hooks/useGetSwapQuote} for more detailed documentation.
+ *
+ * @example
+ * ```tsx
+ * import { useGetSwapQuote } from '@0xsequence/hooks'
+ *
+ * function SwapComponent() {
+ *   const { data: swapQuote, isLoading } = useGetSwapQuote({
+ *     userAddress: '0x123...',
+ *     buyCurrencyAddress: '0x456...',
+ *     sellCurrencyAddress: '0x789...',
+ *     buyAmount: '1000000000000000000', // 1 token in base units
+ *     chainId: 1,
+ *     includeApprove: true
+ *   })
+ *
+ *   if (isLoading) return <div>Loading...</div>
+ *
+ *   return (
+ *     <div>
+ *       <div>Price: {swapQuote?.price}</div>
+ *       <div>Max Price: {swapQuote?.maxPrice}</div>
+ *       <button onClick={() => executeSwap(swapQuote)}>
+ *         Swap Tokens
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
  */
 export const useGetSwapQuote = (getSwapQuoteArgs: GetSwapQuoteArgs, options?: HooksOptions) => {
   const apiClient = useAPIClient()