thirdweb 5.69.0 → 5.70.0-nightly-ecaa304a812188da3c81888bb52ca6064093c139-20241121000332

package/src/react/web/ui/prebuilt/NFT/description.tsx

@@ -0,0 +1,87 @@
+"use client";
+
+import type { UseQueryOptions } from "@tanstack/react-query";
+import type { JSX } from "react";
+import type { NFT } from "../../../../../utils/nft/parseNft.js";
+import { useNftInfo } from "./hooks.js";
+import { useNFTContext } from "./provider.js";
+
+export interface NFTDescriptionProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+  loadingComponent?: JSX.Element;
+  fallbackComponent?: JSX.Element;
+  /**
+   * Optional `useQuery` params
+   */
+  queryOptions?: Omit<UseQueryOptions<NFT>, "queryFn" | "queryKey">;
+}
+
+/**
+ * This component fetches and displays an NFT's description. It inherits all the attributes of a <span>
+ * so you can style it just like how you would style a <span> element.
+ * @returns A <span> element containing the description of the NFT
+ *
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * import { NFTProvider, NFTDescription } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTDescription />
+ * </NFTProvider>
+ * ```
+ *
+ * ### Show a loading sign while the description is being fetched
+ * ```tsx
+ * import { NFTProvider, NFTDescription } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTDescription loadingComponent={<YourLoadingSign />} />
+ * </NFTProvider>
+ * ```
+ *
+ * ### Show something in case the description failed to resolve
+ * ```tsx
+ * import { NFTProvider, NFTDescription } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTDescription fallbackComponent={<span>Failed to load description</span>} />
+ * </NFTProvider>
+ * ```
+ *
+ * ### Custom query options for useQuery (tanstack-query)
+ * ```tsx
+ * import { NFTProvider, NFTDescription } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTDescription queryOptions={{ retry: 3, enabled: false, }} />
+ * </NFTProvider>
+ * ```
+ *
+ * @component
+ * @nft
+ * @beta
+ */
+export function NFTDescription({
+  loadingComponent,
+  fallbackComponent,
+  queryOptions,
+  ...restProps
+}: NFTDescriptionProps) {
+  const { contract, tokenId } = useNFTContext();
+  const nftQuery = useNftInfo({
+    contract,
+    tokenId,
+    queryOptions,
+  });
+
+  if (nftQuery.isLoading) {
+    return loadingComponent || null;
+  }
+
+  if (!nftQuery.data?.metadata?.description) {
+    return fallbackComponent || null;
+  }
+
+  return <span {...restProps}>{nftQuery.data.metadata.description}</span>;
+}

package/src/react/web/ui/prebuilt/NFT/hooks.tsx

@@ -0,0 +1,53 @@
+import { type UseQueryOptions, useQuery } from "@tanstack/react-query";
+import { getNFT as getNFT721 } from "../../../../../extensions/erc721/read/getNFT.js";
+import { getNFT as getNFT1155 } from "../../../../../extensions/erc1155/read/getNFT.js";
+import type { NFT } from "../../../../../utils/nft/parseNft.js";
+import type { NFTProviderProps } from "./provider.js";
+
+/**
+ * @internal Only used for the NFT prebuilt components
+ */
+export function useNftInfo(
+  props: NFTProviderProps & {
+    queryOptions?: Omit<UseQueryOptions<NFT>, "queryFn" | "queryKey">;
+  },
+) {
+  return useQuery({
+    queryKey: [
+      "__nft_component_internal__",
+      props.contract.chain.id,
+      props.contract.address,
+      props.tokenId.toString(),
+    ],
+    queryFn: () =>
+      getNFTInfo({ contract: props.contract, tokenId: props.tokenId }),
+    ...props.queryOptions,
+  });
+}
+
+/**
+ * @internal
+ */
+export async function getNFTInfo(options: NFTProviderProps): Promise<NFT> {
+  const nft = await Promise.allSettled([
+    getNFT721(options),
+    getNFT1155(options),
+  ]).then(([possibleNFT721, possibleNFT1155]) => {
+    // getNFT extension always return an NFT object
+    // so we need to check if the tokenURI exists
+    if (
+      possibleNFT721.status === "fulfilled" &&
+      possibleNFT721.value.tokenURI
+    ) {
+      return possibleNFT721.value;
+    }
+    if (
+      possibleNFT1155.status === "fulfilled" &&
+      possibleNFT1155.value.tokenURI
+    ) {
+      return possibleNFT1155.value;
+    }
+    throw new Error("Failed to load NFT metadata");
+  });
+  return nft;
+}

package/src/react/web/ui/prebuilt/NFT/media.tsx

@@ -0,0 +1,119 @@
+import type { UseQueryOptions } from "@tanstack/react-query";
+import type { JSX } from "react";
+import type { NFT } from "../../../../../utils/nft/parseNft.js";
+import { MediaRenderer } from "../../MediaRenderer/MediaRenderer.js";
+import type { MediaRendererProps } from "../../MediaRenderer/types.js";
+import { useNftInfo } from "./hooks.js";
+import { useNFTContext } from "./provider.js";
+
+/**
+ * @component
+ * The props for the <NFTMedia /> component
+ * It is similar to the [`MediaRendererProps`](https://portal.thirdweb.com/references/typescript/v5/MediaRendererProps)
+ * (excluding `src`, `poster` and `client`) that you can
+ * use to style the NFTMedia
+ */
+export type NFTMediaProps = Omit<
+  MediaRendererProps,
+  "src" | "poster" | "client"
+> & {
+  loadingComponent?: JSX.Element;
+  fallbackComponent?: JSX.Element;
+  /**
+   * Optional `useQuery` params
+   */
+  queryOptions?: Omit<UseQueryOptions<NFT>, "queryFn" | "queryKey">;
+};
+
+/**
+ * This component fetches and displays an NFT's media. It uses thirdweb [`MediaRenderer`](https://portal.thirdweb.com/refernces/typescript/v5/MediaRenderer) under the hood
+ * so you can style it just like how you would style a MediaRenderer.
+ * @returns A MediaRenderer component
+ *
+ * @component
+ *
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * import { NFTProvider, NFTMedia } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTMedia />
+ * </NFTProvider>
+ * ```
+ *
+ * ### Show a loading sign while the media is being fetched
+ * ```tsx
+ * import { NFTProvider, NFTMedia } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTMedia loadingComponent={<YourLoadingSign />} />
+ * </NFTProvider>
+ * ```
+ *
+ * ### Show something in case the media failed to resolve
+ * ```tsx
+ * import { NFTProvider, NFTMedia } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTMedia fallbackComponent={<span>Failed to load media</span>} />
+ * </NFTProvider>
+ * ```
+ *
+ * ### Custom query options for useQuery (tanstack-query)
+ * ```tsx
+ * import { NFTProvider, NFTMedia } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTMedia queryOptions={{ retry: 3, enabled: false, }} />
+ * </NFTProvider>
+ * ```
+ *
+ * ### Basic stylings
+ *
+ * You can style NFTMedia with the `style` and `className` props.
+ *
+ * ```tsx
+ * <NFTMedia style={{ borderRadius: "8px" }} className="mx-auto" />
+ * ```
+ * @nft
+ * @beta
+ */
+export function NFTMedia({
+  loadingComponent,
+  fallbackComponent,
+  queryOptions,
+  ...mediaRendererProps
+}: NFTMediaProps) {
+  const { contract, tokenId } = useNFTContext();
+  const nftQuery = useNftInfo({
+    contract,
+    tokenId,
+    queryOptions,
+  });
+
+  if (nftQuery.isLoading) {
+    return loadingComponent || null;
+  }
+
+  if (!nftQuery.data) {
+    return fallbackComponent || null;
+  }
+
+  const animation_url = nftQuery.data.metadata.animation_url;
+  const image =
+    nftQuery.data.metadata.image || nftQuery.data.metadata.image_url;
+
+  if (!animation_url && !image) {
+    return fallbackComponent || null;
+  }
+
+  return (
+    <MediaRenderer
+      client={contract.client}
+      src={animation_url || image}
+      poster={image}
+      {...mediaRendererProps}
+    />
+  );
+}

package/src/react/web/ui/prebuilt/NFT/name.tsx

@@ -0,0 +1,85 @@
+import type { UseQueryOptions } from "@tanstack/react-query";
+import type { JSX } from "react";
+import type { NFT } from "../../../../../utils/nft/parseNft.js";
+import { useNftInfo } from "./hooks.js";
+import { useNFTContext } from "./provider.js";
+
+export interface NFTNameProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+  loadingComponent?: JSX.Element;
+  fallbackComponent?: JSX.Element;
+  /**
+   * Optional `useQuery` params
+   */
+  queryOptions?: Omit<UseQueryOptions<NFT>, "queryFn" | "queryKey">;
+}
+
+/**
+ * This component fetches and displays an NFT's name. It takes in a `className` and `style` props
+ * so you can style it just like how you would style a <span> element.
+ * @returns A <span> element containing the name of the NFT
+ *
+ * @component
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * import { NFTProvider, NFTName } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTName />
+ * </NFTProvider>
+ * ```
+ *
+ * ### Show a loading sign while the name is being fetched
+ * ```tsx
+ * import { NFTProvider, NFTName } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTName loadingComponent={<YourLoadingSign />} />
+ * </NFTProvider>
+ * ```
+ *
+ * ### Show something in case the name failed to resolve
+ * ```tsx
+ * import { NFTProvider, NFTName } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTName fallbackComponent={<span>Failed to load name</span>} />
+ * </NFTProvider>
+ * ```
+ *
+ * ### Custom query options for useQuery (tanstack-query)
+ * ```tsx
+ * import { NFTProvider, NFTName } from "thirdweb/react";
+ *
+ * <NFTProvider>
+ *   <NFTName queryOptions={{ retry: 3, enabled: false, }} />
+ * </NFTProvider>
+ * ```
+ *
+ * @nft
+ * @beta
+ */
+export function NFTName({
+  loadingComponent,
+  fallbackComponent,
+  queryOptions,
+  ...restProps
+}: NFTNameProps) {
+  const { contract, tokenId } = useNFTContext();
+
+  const nftQuery = useNftInfo({
+    contract,
+    tokenId,
+    queryOptions,
+  });
+
+  if (nftQuery.isLoading) {
+    return loadingComponent || null;
+  }
+
+  if (!nftQuery.data?.metadata?.name) {
+    return fallbackComponent || null;
+  }
+  return <span {...restProps}>{nftQuery.data.metadata.name}</span>;
+}

package/src/react/web/ui/prebuilt/NFT/provider.tsx

@@ -0,0 +1,75 @@
+import { createContext, useContext } from "react";
+import type { ThirdwebContract } from "../../../../../contract/contract.js";
+
+/**
+ * Props for the <NFT> component
+ * @component
+ */
+export type NFTProviderProps = {
+  /**
+   * The NFT contract address. Accepts both ERC721 and ERC1155 contracts
+   */
+  contract: ThirdwebContract;
+  /**
+   * The tokenId whose info you want to display
+   */
+  tokenId: bigint;
+};
+
+/**
+ * @internal
+ */
+export const NFTProviderContext = /* @__PURE__ */ createContext<
+  NFTProviderProps | undefined
+>(undefined);
+
+/**
+ * @internal
+ */
+export function useNFTContext() {
+  const ctx = useContext(NFTProviderContext);
+  if (!ctx) {
+    throw new Error(
+      "NFTProviderContext not found. Make sure you are using NFTMedia, NFTDescription, etc. inside a <NFTProvider /> component",
+    );
+  }
+  return ctx;
+}
+
+/**
+ * A React context provider component that supplies NFT-related data to its child components.
+ *
+ * This component serves as a wrapper around the `NFTProviderContext.Provider` and passes
+ * the provided NFT data down to all of its child components through the context API.
+ *
+ *
+ * @param {React.PropsWithChildren<NFTProviderProps>} props - The props for the NFT provider
+ *
+ * @example
+ * ```tsx
+ * import { getContract } from "thirdweb";
+ * import { NFTProvider, NFTMedia, NFTDescription, NFTName } from "thirdweb/react";
+ *
+ * const contract = getContract({
+ *   address: "0x...",
+ *   chain: ethereum,
+ *   client: yourThirdwebClient,
+ * });
+ *
+ * <NFTProvider contract={contract} tokenId={0n}>
+ *    <NFTMedia />
+ *    <NFTDescription />
+ *    <NFTName />
+ * </NFTProvider>
+ * ```
+ * @component
+ * @nft
+ * @beta
+ */
+export function NFTProvider(props: React.PropsWithChildren<NFTProviderProps>) {
+  return (
+    <NFTProviderContext.Provider value={props}>
+      {props.children}
+    </NFTProviderContext.Provider>
+  );
+}

package/src/react/web/ui/prebuilt/Token/icon.tsx

@@ -0,0 +1,164 @@
+import { type UseQueryOptions, useQuery } from "@tanstack/react-query";
+import type { JSX } from "react";
+import { getChainMetadata } from "../../../../../chains/utils.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../../../../constants/addresses.js";
+import { getContract } from "../../../../../contract/contract.js";
+import { getContractMetadata } from "../../../../../extensions/common/read/getContractMetadata.js";
+import { resolveScheme } from "../../../../../utils/ipfs.js";
+import { useTokenContext } from "./provider.js";
+
+export interface TokenIconProps
+  extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src"> {
+  /**
+   * This prop can be a string or a (async) function that resolves to a string, representing the icon url of the token
+   * This is particularly useful if you already have a way to fetch the token icon.
+   */
+  iconResolver?: string | (() => string) | (() => Promise<string>);
+  /**
+   * This component will be shown while the avatar of the icon is being fetched
+   * If not passed, the component will return `null`.
+   *
+   * You can pass a loading sign or spinner to this prop.
+   * @example
+   * ```tsx
+   * <TokenIcon loadingComponent={<Spinner />} />
+   * ```
+   */
+  loadingComponent?: JSX.Element;
+  /**
+   * This component will be shown if the request for fetching the avatar is done
+   * but could not retreive any result.
+   * You can pass a dummy avatar/image to this prop.
+   *
+   * If not passed, the component will return `null`
+   *
+   * @example
+   * ```tsx
+   * <TokenIcon fallbackComponent={<DummyImage />} />
+   * ```
+   */
+  fallbackComponent?: JSX.Element;
+
+  /**
+   * Optional query options for `useQuery`
+   */
+  queryOptions?: Omit<UseQueryOptions<string>, "queryFn" | "queryKey">;
+}
+
+/**
+ * This component tries to resolve the icon of a given token, then return an image.
+ * @returns an <img /> with the src of the token icon
+ *
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * import { TokenProvider, TokenIcon } from "thirdweb/react";
+ *
+ * <TokenProvider address="0x-token-address" chain={chain} client={client}>
+ *   <TokenIcon />
+ * </TokenProvider>
+ * ```
+ *
+ * Result: An <img /> component with the src of the icon
+ * ```html
+ * <img src="token-icon.png" />
+ * ```
+ *
+ * ### Override the icon with the `iconResolver` prop
+ * If you already have the icon url, you can skip the network requests and pass it directly to the TokenIcon
+ * ```tsx
+ * <TokenIcon iconResolver="/usdc.png" />
+ * ```
+ *
+ * You can also pass in your own custom (async) function that retrieves the icon url
+ * ```tsx
+ * const getIcon = async () => {
+ *   const icon = getIconFromCoinMarketCap(tokenAddress, etc);
+ *   return icon;
+ * };
+ *
+ * <TokenIcon iconResolver={getIcon} />
+ * ```
+ *
+ * ### Show a loading sign while the icon is being loaded
+ * ```tsx
+ * <TokenIcon loadingComponent={<Spinner />} />
+ * ```
+ *
+ * ### Fallback to a dummy image if the token icon fails to resolve
+ * ```tsx
+ * <TokenIcon fallbackComponent={<img src="blank-image.png" />} />
+ * ```
+ *
+ * ### Usage with queryOptions
+ * TokenIcon uses useQuery() from tanstack query internally.
+ * It allows you to pass a custom queryOptions of your choice for more control of the internal fetching logic
+ * ```tsx
+ * <TokenIcon queryOptions={{ enabled: someLogic, retry: 3, }} />
+ * ```
+ *
+ * @component
+ * @token
+ * @beta
+ */
+export function TokenIcon({
+  iconResolver,
+  loadingComponent,
+  fallbackComponent,
+  queryOptions,
+  ...restProps
+}: TokenIconProps) {
+  const { address, client, chain } = useTokenContext();
+  const iconQuery = useQuery({
+    queryKey: ["_internal_token_icon_", chain.id, address] as const,
+    queryFn: async () => {
+      if (typeof iconResolver === "string") {
+        return iconResolver;
+      }
+      if (typeof iconResolver === "function") {
+        return iconResolver();
+      }
+      if (address.toLowerCase() === NATIVE_TOKEN_ADDRESS.toLowerCase()) {
+        const possibleUrl = await getChainMetadata(chain).then(
+          (data) => data.icon?.url,
+        );
+        if (!possibleUrl) {
+          throw new Error("Failed to resolve icon for native token");
+        }
+        return resolveScheme({ uri: possibleUrl, client });
+      }
+
+      // Try to get the icon from the contractURI
+      const contractMetadata = await getContractMetadata({
+        contract: getContract({
+          address,
+          chain,
+          client,
+        }),
+      });
+
+      if (
+        !contractMetadata.image ||
+        typeof contractMetadata.image !== "string"
+      ) {
+        throw new Error("Failed to resolve token icon from contract metadata");
+      }
+
+      return resolveScheme({
+        uri: contractMetadata.image,
+        client,
+      });
+    },
+    ...queryOptions,
+  });
+
+  if (iconQuery.isLoading) {
+    return loadingComponent || null;
+  }
+
+  if (!iconQuery.data) {
+    return fallbackComponent || null;
+  }
+
+  return <img src={iconQuery.data} alt={restProps.alt} />;
+}