[RN/React-Core] Improve comments (#2082)

.changeset/polite-candles-rule.md

@@ -0,0 +1,6 @@
+---
+"@thirdweb-dev/react-native": patch
+"@thirdweb-dev/react-core": patch
+---
+
+Better comments

packages/react-core/src/core/providers/thirdweb-provider.tsx

@@ -84,11 +84,10 @@ export interface ThirdwebProviderCoreProps<TChains extends Chain[]>
 /**
  * @internal
  */
-export const ThirdwebProviderCore = <TChains extends Chain[]>({
-  createWalletStorage = createAsyncLocalStorage,
-  ...props
-}: React.PropsWithChildren<ThirdwebProviderCoreProps<TChains>>) => {
-  const { activeChain } = props;
+export const ThirdwebProviderCore = <TChains extends Chain[]>(
+  props: React.PropsWithChildren<ThirdwebProviderCoreProps<TChains>>,
+) => {
+  const { activeChain, createWalletStorage = createAsyncLocalStorage } = props;
 
   const supportedChains = (props.supportedChains || defaultChains) as Chain[];
 

packages/react-core/src/evm/contexts/thirdweb-auth.tsx

@@ -1,13 +1,18 @@
 import { createContext, useContext } from "react";
 
+/**
+ * Secure storage interface for storing auth tokens.
+ *
+ * The implementation of this interface should provide a secure way to store values. Either by encrypting the values or by storing them in a secure location.
+ */
 export interface ISecureStorage {
   getItem(key: string): Promise<string | null>;
   setItem(key: string, value: string): Promise<void>;
   removeItem(key: string): Promise<void>;
 }
 
 /**
- * The configuration to use the react SDK with an [auth](https://portal.thirdweb.com/auth) server.
+ * The configuration to use by the React and React Native SDKs with an [auth](https://portal.thirdweb.com/auth) server.
  *
  */
 export interface ThirdwebAuthConfig {

packages/react-core/src/evm/hooks/auth/useLogin.ts

@@ -12,8 +12,33 @@ import { AUTH_TOKEN_STORAGE_KEY } from "../../../core/constants/auth";
  *
  * @returns - A function to invoke to login with the connected wallet, and an isLoading state.
  *
- * @see {@link https://portal.thirdweb.com/react/react.uselogin?utm_source=sdk | Documentation}
+ * @example
+ * ```tsx
+ * function App() {
+ * const { isLoading, login } = useLogin();
  *
+ * return (
+ *   <button onClick={() => login()}>
+ *     {isLoading ? "Loading..." : "Sign in with Ethereum"}
+ *   </button>
+ * );
+ * }
+ * ```
+ *
+ * ```tsx
+ * // options
+ * login({
+ *         domain: "https://your-domain.com", // Your dapp domain
+ *         statement: "My statement", // Text that the user will sign
+ *         uri: "https://your-domain.com/login", // RFC 3986 URI referring to the resource that is the subject of the signing
+ *         version: "1.0", // The current version of the message, which MUST be 1 for this specification.
+ *         chainId: "mainnet", // Chain ID to which the session is bound
+ *         nonce: "my-nonce", // randomized token typically used to prevent replay attacks
+ *         expirationTime: new Date(2021, 1, 1), // When this message expires
+ *         invalidBefore: new Date(2020, 12, 1), // When this message becomes valid
+ *         resources: ["balance", "history", "info"], // A list of information or references to information the user wishes to have resolved
+ *       })
+ * ```
  */
 export function useLogin() {
   const queryClient = useQueryClient();

packages/react-core/src/evm/hooks/auth/useLogout.ts

@@ -10,8 +10,18 @@ import invariant from "tiny-invariant";
  *
  * @returns - A function to invoke to logout.
  *
- * @see {@link https://portal.thirdweb.com/react/react.uselogout?utm_source=sdk | Documentation}
+ * @example
+ * ```tsx
+ * function App() {
+ *  const { logout, isLoading } = useLogout();
  *
+ *  return (
+ *    <button onClick={() => logout()}>
+ *      {isLoading ? "Logging out..." : "Logout"}
+ *    </button>
+ *  );
+ *}
+ * ```
  */
 export function useLogout() {
   const queryClient = useQueryClient();

packages/react-core/src/evm/hooks/auth/useUser.ts

@@ -16,9 +16,23 @@ export interface UserWithData<
  * Hook to get the currently logged in user.
  *
  * @returns - The currently logged in user or null if not logged in, as well as a loading state.
+ * ```tsx
+ * {
+ *    user: {
+ *      address: string;
+ *      session?: Json;
+ *    } | undefined;
+ *    isLoggedIn: boolean;
+ *    isLoading: boolean;
+ *}
+ * ```
  *
- * @see {@link https://portal.thirdweb.com/react/react.useuser?utm_source=sdk | Documentation}
- *
+ * @example
+ * ```tsx
+ * function App() {
+ *  const { user, isLoggedIn, isLoading } = useUser();
+ * }
+ * ```
  */
 export function useUser<
   TData extends Json = Json,

packages/react-core/src/evm/hooks/storage/useStorage.ts

@@ -1,9 +1,27 @@
 import { useSDK } from "../useSDK";
 
 /**
- * Get the configured `ThirdwebStorage` instance
+ * Get the configured `ThirdwebStorage` instance in the `ThirdwebProvider`.
+ *
  * @returns The `storageInterface` configured on the `ThirdwebProvider`
- * @see {@link https://portal.thirdweb.com/react/react.usestorage?utm_source=sdk | Documentation}
+ *
+ * @example
+ * ```tsx
+ * const storage = useStorage();
+ *
+ * cost resp = storage?.download("ipfs-url"); // Download a file from IPFS
+ * if (resp.ok) {
+ *   const value = await resp?.json();
+ * }
+ *
+ * const fileIpfsHash = await storage?.upload({
+ *   name: 'file1',
+ *   type: 'file-mime-type',
+ *   uri: 'file-uri-on-device',
+ * }); // Upload a file to IPFS
+ * const objIpfsHash = await storage?.upload({key: 'value'}); // Upload an object to IPFS
+ * const strIpfsHash = await storage?.upload('string-to-upload'); // Upload a string to IPFS
+ * ```
  */
 export function useStorage() {
   const sdk = useSDK();

packages/react-native/src/evm/providers/thirdweb-provider.tsx

@@ -12,17 +12,16 @@ import { DEFAULT_WALLETS } from "../constants/wallets";
 import { DappContextProvider } from "./context-provider";
 import { UIContextProvider } from "./ui-context-provider";
 import { MainModal } from "../components/MainModal";
-import { ThemeProvider } from "../styles/ThemeProvider";
+import { ThemeProvider, ThemeType } from "../styles/ThemeProvider";
 import { SafeAreaProvider } from "react-native-safe-area-context";
 import { walletIds } from "@thirdweb-dev/wallets";
 import { ThirdwebStorage } from "../../core/storage/storage";
-import { useColorScheme } from "react-native";
 import type { Locale } from "../i18n/types";
 
 interface ThirdwebProviderProps<TChains extends Chain[]>
   extends Omit<
     ThirdwebProviderCoreProps<TChains>,
-    "supportedWallets" | "secretKey" | "signer"
+    "supportedWallets" | "secretKey" | "signer" | "theme"
   > {
   /**
    * Wallets that will be supported by the dApp
@@ -47,6 +46,27 @@ interface ThirdwebProviderProps<TChains extends Chain[]>
    */
   supportedWallets?: WalletConfig<any>[];
 
+  /**
+   * Set the theme for all thirdweb components
+   *
+   * By default it is set to "dark".
+   *
+   * theme can be set to either "dark" or "light" or a custom theme object.
+   *
+   * You can also import `lightTheme` or `darkTheme` functions from `@thirdweb-dev/react-native` to use the default themes as base and overrides parts of it.
+   *
+   * @example
+   * ```ts
+   * import { darkTheme } from "@thirdweb-dev/react-native";
+   * const customTheme = darkTheme({
+   *  colors: {
+   *      accentButtonColor: 'black',
+   *  },
+   * })
+   * ```
+   */
+  theme?: ThemeType;
+
   /**
    * Locale that the app will be displayed in
    *
@@ -87,10 +107,15 @@ interface ThirdwebProviderProps<TChains extends Chain[]>
   locale?: Locale;
 }
 
+/**
+ * Array of default supported chains by the thirdweb SDK
+ */
+export type DefaultChains = typeof defaultChains;
+
 /**
  *
  * The `<ThirdwebProvider />` component lets you control what networks you want users to connect to,
- * what types of wallets can connect to your app, and the settings for the [Thirdweb SDK](https://docs.thirdweb.com/typescript).
+ * what types of wallets can connect to your app, and the settings for the Thirdweb SDK.
  *
  * @example
  * You can wrap your application with the provider as follows:
@@ -107,21 +132,21 @@ interface ThirdwebProviderProps<TChains extends Chain[]>
  * };
  * ```
  */
-export const ThirdwebProvider = <
-  TChains extends Chain[] = typeof defaultChains,
->({
-  children,
-  createWalletStorage = createAsyncLocalStorage,
-  supportedWallets = DEFAULT_WALLETS,
-  authConfig,
-  theme,
-  storageInterface,
-  clientId,
-  sdkOptions,
-  locale = "en",
-  ...restProps
-}: PropsWithChildren<ThirdwebProviderProps<TChains>>) => {
-  const colorScheme = useColorScheme();
+export const ThirdwebProvider = <TChains extends Chain[] = DefaultChains>(
+  props: PropsWithChildren<ThirdwebProviderProps<TChains>>,
+) => {
+  const {
+    children,
+    createWalletStorage = createAsyncLocalStorage,
+    supportedWallets = DEFAULT_WALLETS,
+    authConfig,
+    theme,
+    storageInterface,
+    clientId,
+    sdkOptions,
+    locale = "en",
+    ...restProps
+  } = props;
 
   const coinbaseWalletObj = supportedWallets.find(
     (w) => w.id === walletIds.coinbase,
@@ -161,9 +186,7 @@ export const ThirdwebProvider = <
       {...sdkOptions}
       {...restProps}
     >
-      <ThemeProvider
-        theme={theme ? theme : colorScheme === "dark" ? "dark" : "light"}
-      >
+      <ThemeProvider theme={theme ? theme : "dark"}>
         <UIContextProvider locale={locale}>
           {hasMagicConfig ? (
             <SafeAreaProvider>

packages/react-native/src/evm/styles/ThemeProvider.tsx

@@ -5,8 +5,10 @@ import { PropsWithChildren, useContext } from "react";
 import { useColorScheme } from "react-native";
 import { useUIContext } from "../providers/ui-context-provider";
 
+export type ThemeType = "dark" | "light" | Theme;
+
 export type ThemeProviderProps = {
-  theme?: Theme | "light" | "dark";
+  theme?: ThemeType;
 };
 
 export function ThemeProvider({

packages/react-native/src/evm/wallets/wallets/coinbase-wallet.ts

@@ -66,6 +66,26 @@ export class CoinbaseWallet extends AbstractClientWallet<CoinbaseWalletConnector
   }
 }
 
+/**
+ * Wallet config for the Coinbase Wallet.
+ *
+ * @param config - The config for the Coinbase Wallet
+ * @returns The wallet config to be used by the ThirdwebProvider
+ *
+ * @example
+ * ```jsx
+ * import { ThirdwebProvider, coinbaseWallet } from "@thirdweb-dev/react-native";
+ *
+ * <ThirdwebProvider
+ *    supportedWallets={[
+ *      coinbaseWallet({
+ *         callbackURL: new URL('app-redirect-url://'),
+ *       }),
+ *    ]}>
+ *   <YourApp />
+ * </ThirdwebProvider>
+ * ```
+ */
 export const coinbaseWallet = (config?: {
   callbackURL?: URL;
   recommended?: boolean;

packages/react-native/src/evm/wallets/wallets/local-wallet.tsx

@@ -3,6 +3,24 @@ import { WalletOptions, walletIds } from "@thirdweb-dev/wallets";
 import { createSecureStorage } from "../../../core/SecureStorage";
 import { createAsyncLocalStorage } from "../../../core/AsyncStorage";
 
+/**
+ * Wallet config for a Local Wallet
+ *
+ * @param config - The config for the Local Wallet
+ * @returns The wallet config to be used by the ThirdwebProvider
+ *
+ * @example
+ * ```jsx
+ * import { ThirdwebProvider, localWallet } from "@thirdweb-dev/react-native";
+ *
+ * <ThirdwebProvider
+ *    supportedWallets={[
+ *      localWallet(),
+ *    ]}>
+ *   <YourApp />
+ * </ThirdwebProvider>
+ * ```
+ */
 export const localWallet = () => {
   const secureStorage = createSecureStorage(walletIds.localWallet);
   const asyncStorage = createAsyncLocalStorage(walletIds.localWallet);

packages/react-native/src/evm/wallets/wallets/metamask-wallet.ts

@@ -21,6 +21,22 @@ export class MetaMaskWallet extends WalletConnectBase {
   }
 }
 
+/**
+ * Wallet config for MetaMask Wallet.
+ *
+ * @param config - The config for MetamaskWallet
+ * @returns The wallet config to be used by the ThirdwebProvider
+ *
+ * @example
+ * ```jsx
+ * import { ThirdwebProvider, metamaskWallet } from "@thirdweb-dev/react-native";
+ *
+ * <ThirdwebProvider
+ *    supportedWallets={[metamaskWallet()]}>
+ *   <YourApp />
+ * </ThirdwebProvider>
+ * ```
+ */
 export const metamaskWallet = (config?: WalletConnectConfig) => {
   return {
     id: MetaMaskWallet.id,

packages/react-native/src/evm/wallets/wallets/rainbow-wallet.ts

@@ -22,6 +22,22 @@ export class RainbowWallet extends WalletConnectBase {
   }
 }
 
+/**
+ * Wallet config for Rainbow Wallet.
+ *
+ * @param config - The config for RainbowWallet
+ * @returns The wallet config to be used by the ThirdwebProvider
+ *
+ * @example
+ * ```jsx
+ * import { ThirdwebProvider, rainbowWallet } from "@thirdweb-dev/react-native";
+ *
+ * <ThirdwebProvider
+ *    supportedWallets={[rainbowWallet()]}>
+ *   <YourApp />
+ * </ThirdwebProvider>
+ * ```
+ */
 export const rainbowWallet = (config?: WalletConnectConfig) => {
   return {
     id: RainbowWallet.id,