thirdweb 5.76.0-nightly-015293eb826b346871696183e96d49da44f31393-20241209000527 → 5.76.0-nightly-485dcc6020089a80d994c24882f389c24a0af039-20241210000351

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

@@ -1,10 +1,10 @@
 "use client";
 
-import type { UseQueryOptions } from "@tanstack/react-query";
+import { type UseQueryOptions, useQuery } from "@tanstack/react-query";
 import type { JSX } from "react";
-import type { NFT } from "../../../../../utils/nft/parseNft.js";
-import { useNftInfo } from "./hooks.js";
+import type { ThirdwebContract } from "../../../../../contract/contract.js";
 import { useNFTContext } from "./provider.js";
+import { getNFTInfo } from "./utils.js";
 
 export interface NFTDescriptionProps
   extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
@@ -13,7 +13,12 @@ export interface NFTDescriptionProps
   /**
    * Optional `useQuery` params
    */
-  queryOptions?: Omit<UseQueryOptions<NFT>, "queryFn" | "queryKey">;
+  queryOptions?: Omit<UseQueryOptions<string>, "queryFn" | "queryKey">;
+  /**
+   * This prop can be a string or a (async) function that resolves to a string, representing the description of the NFT
+   * This is particularly useful if you already have a way to fetch the data.
+   */
+  descriptionResolver?: string | (() => string) | (() => Promise<string>);
 }
 
 /**
@@ -58,6 +63,21 @@ export interface NFTDescriptionProps
  * </NFTProvider>
  * ```
  *
+ * ### Override the description with the `descriptionResolver` prop
+ * If you already have the url, you can skip the network requests and pass it directly to the NFTDescription
+ * ```tsx
+ * <NFTDescription descriptionResolver="The desc of the NFT" />
+ * ```
+ *
+ * You can also pass in your own custom (async) function that retrieves the description
+ * ```tsx
+ * const getDescription = async () => {
+ *   // ...
+ *   return description;
+ * };
+ *
+ * <NFTDescription descriptionResolver={getDescription} />
+ * ```
  * @component
  * @nft
  * @beta
@@ -66,22 +86,61 @@ export function NFTDescription({
   loadingComponent,
   fallbackComponent,
   queryOptions,
+  descriptionResolver,
   ...restProps
 }: NFTDescriptionProps) {
   const { contract, tokenId } = useNFTContext();
-  const nftQuery = useNftInfo({
-    contract,
-    tokenId,
-    queryOptions,
+  const descQuery = useQuery({
+    queryKey: [
+      "_internal_nft_description_",
+      contract.chain.id,
+      tokenId.toString(),
+      {
+        resolver:
+          typeof descriptionResolver === "string"
+            ? descriptionResolver
+            : typeof descriptionResolver === "function"
+              ? descriptionResolver.toString()
+              : undefined,
+      },
+    ],
+    queryFn: async (): Promise<string> =>
+      fetchNftDescription({ descriptionResolver, contract, tokenId }),
+    ...queryOptions,
   });
 
-  if (nftQuery.isLoading) {
+  if (descQuery.isLoading) {
     return loadingComponent || null;
   }
 
-  if (!nftQuery.data?.metadata?.description) {
+  if (!descQuery.data) {
     return fallbackComponent || null;
   }
 
-  return <span {...restProps}>{nftQuery.data.metadata.description}</span>;
+  return <span {...restProps}>{descQuery.data}</span>;
+}
+
+/**
+ * @internal Exported for tests
+ */
+export async function fetchNftDescription(props: {
+  descriptionResolver?: string | (() => string) | (() => Promise<string>);
+  contract: ThirdwebContract;
+  tokenId: bigint;
+}): Promise<string> {
+  const { descriptionResolver, contract, tokenId } = props;
+  if (typeof descriptionResolver === "string") {
+    return descriptionResolver;
+  }
+  if (typeof descriptionResolver === "function") {
+    return descriptionResolver();
+  }
+  const nft = await getNFTInfo({ contract, tokenId }).catch(() => undefined);
+  if (!nft) {
+    throw new Error("Failed to resolve NFT info");
+  }
+  if (typeof nft.metadata.description !== "string") {
+    throw new Error("Failed to resolve NFT description");
+  }
+  return nft.metadata.description;
 }

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

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import {
+  DOODLES_CONTRACT,
+  DROP1155_CONTRACT,
+  UNISWAPV3_FACTORY_CONTRACT,
+} from "~test/test-contracts.js";
+import { fetchNftMedia } from "./media.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("NFTMedia", () => {
+  it("fetchNftMedia should work with ERC721", async () => {
+    const desc = await fetchNftMedia({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+    });
+    expect(desc).toStrictEqual({
+      src: "ipfs://QmUEfFfwAh4wyB5UfHCVPUxis4j4Q4kJXtm5x5p3g1fVUn",
+      poster: undefined,
+    });
+  });
+
+  it("fetchNftMedia should work with ERC1155", async () => {
+    const desc = await fetchNftMedia({
+      contract: DROP1155_CONTRACT,
+      tokenId: 0n,
+    });
+    expect(desc).toStrictEqual({
+      src: "ipfs://QmeGCqV1mSHTZrvuFzW1XZdCRRGXB6AmSotTqHoxA2xfDo/1.mp4",
+      poster: "ipfs://QmeGCqV1mSHTZrvuFzW1XZdCRRGXB6AmSotTqHoxA2xfDo/0.png",
+    });
+  });
+
+  it("fetchNftMedia should respect mediaResolver as a string", async () => {
+    const desc = await fetchNftMedia({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      mediaResolver: {
+        src: "string",
+        poster: undefined,
+      },
+    });
+    expect(desc).toStrictEqual({ src: "string", poster: undefined });
+  });
+
+  it("fetchNftMedia should respect mediaResolver as a non-async function", async () => {
+    const desc = await fetchNftMedia({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      mediaResolver: () => ({
+        src: "non-async",
+        poster: undefined,
+      }),
+    });
+    expect(desc).toStrictEqual({ src: "non-async", poster: undefined });
+  });
+
+  it("fetchNftMedia should respect mediaResolver as a async function", async () => {
+    const desc = await fetchNftMedia({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      mediaResolver: async () =>
+        await {
+          src: "async",
+          poster: undefined,
+        },
+    });
+    expect(desc).toStrictEqual({ src: "async", poster: undefined });
+  });
+
+  it("fetchNftMedia should throw error if failed to resolve nft info", async () => {
+    await expect(() =>
+      fetchNftMedia({
+        contract: UNISWAPV3_FACTORY_CONTRACT,
+        tokenId: 0n,
+      }),
+    ).rejects.toThrowError("Failed to resolve NFT info");
+  });
+});

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

@@ -1,13 +1,25 @@
-import type { UseQueryOptions } from "@tanstack/react-query";
+import { type UseQueryOptions, useQuery } from "@tanstack/react-query";
 import type { JSX } from "react";
-import type { NFT } from "../../../../../utils/nft/parseNft.js";
+import type { ThirdwebContract } from "../../../../../contract/contract.js";
 import { MediaRenderer } from "../../MediaRenderer/MediaRenderer.js";
 import type { MediaRendererProps } from "../../MediaRenderer/types.js";
-import { useNftInfo } from "./hooks.js";
 import { useNFTContext } from "./provider.js";
+import { getNFTInfo } from "./utils.js";
 
 /**
  * @component
+ * @beta
+ * @wallet
+ */
+export type NFTMediaInfo = {
+  src: string;
+  poster: string | undefined;
+};
+
+/**
+ * @component
+ * @beta
+ * @wallet
  * 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
@@ -22,7 +34,16 @@ export type NFTMediaProps = Omit<
   /**
    * Optional `useQuery` params
    */
-  queryOptions?: Omit<UseQueryOptions<NFT>, "queryFn" | "queryKey">;
+  queryOptions?: Omit<UseQueryOptions<NFTMediaInfo>, "queryFn" | "queryKey">;
+  /**
+   * This prop can be a string or a (async) function that resolves to a string, representing the media url of the NFT
+   * This is particularly useful if you already have a way to fetch the image.
+   * In case of function, the function must resolve to an object of type `NFTMediaInfo`
+   */
+  mediaResolver?:
+    | NFTMediaInfo
+    | (() => NFTMediaInfo)
+    | (() => Promise<NFTMediaInfo>);
 };
 
 /**
@@ -76,6 +97,26 @@ export type NFTMediaProps = Omit<
  * ```tsx
  * <NFTMedia style={{ borderRadius: "8px" }} className="mx-auto" />
  * ```
+ *
+ * ### Override the media with the `mediaResolver` prop
+ * If you already have the url, you can skip the network requests and pass it directly to the NFTMedia
+ * ```tsx
+ * <NFTMedia mediaResolver={{
+ *   src: "/cat_video.mp4",
+ *   // Poster is applicable to medias that are videos and audios
+ *   poster: "/cat-image.png",
+ * }} />
+ * ```
+ *
+ * You can also pass in your own custom (async) function that retrieves the media url
+ * ```tsx
+ * const getMedia = async () => {
+ *   const url = getNFTMedia(props);
+ *   return url;
+ * };
+ *
+ * <NFTMedia mediaResolver={getMedia} />
+ * ```
  * @nft
  * @beta
  */
@@ -83,37 +124,82 @@ export function NFTMedia({
   loadingComponent,
   fallbackComponent,
   queryOptions,
+  mediaResolver,
   ...mediaRendererProps
 }: NFTMediaProps) {
   const { contract, tokenId } = useNFTContext();
-  const nftQuery = useNftInfo({
-    contract,
-    tokenId,
-    queryOptions,
+  const mediaQuery = useQuery({
+    queryKey: [
+      "_internal_nft_media_",
+      contract.chain.id,
+      tokenId.toString(),
+      {
+        resolver:
+          typeof mediaResolver === "object"
+            ? mediaResolver
+            : typeof mediaResolver === "function"
+              ? mediaResolver.toString()
+              : undefined,
+      },
+    ],
+    queryFn: async (): Promise<NFTMediaInfo> =>
+      fetchNftMedia({ mediaResolver, contract, tokenId }),
+    ...queryOptions,
   });
 
-  if (nftQuery.isLoading) {
+  if (mediaQuery.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) {
+  if (!mediaQuery.data) {
     return fallbackComponent || null;
   }
 
   return (
     <MediaRenderer
       client={contract.client}
-      src={animation_url || image}
-      poster={image}
+      src={mediaQuery.data.src}
+      poster={mediaQuery.data.poster}
       {...mediaRendererProps}
     />
   );
 }
+
+/**
+ * @internal Exported for tests only
+ */
+export async function fetchNftMedia(props: {
+  mediaResolver?:
+    | NFTMediaInfo
+    | (() => NFTMediaInfo)
+    | (() => Promise<NFTMediaInfo>);
+  contract: ThirdwebContract;
+  tokenId: bigint;
+}): Promise<{ src: string; poster: string | undefined }> {
+  const { mediaResolver, contract, tokenId } = props;
+  if (typeof mediaResolver === "object") {
+    return mediaResolver;
+  }
+  if (typeof mediaResolver === "function") {
+    return mediaResolver();
+  }
+  const nft = await getNFTInfo({ contract, tokenId }).catch(() => undefined);
+  if (!nft) {
+    throw new Error("Failed to resolve NFT info");
+  }
+  const animation_url = nft.metadata.animation_url;
+  const image = nft.metadata.image || nft.metadata.image_url;
+  if (animation_url) {
+    return {
+      src: animation_url,
+      poster: image || undefined,
+    };
+  }
+  if (image) {
+    return {
+      src: image,
+      poster: undefined,
+    };
+  }
+  throw new Error("Failed to resolve NFT media");
+}

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

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import {
+  DOODLES_CONTRACT,
+  DROP1155_CONTRACT,
+  UNISWAPV3_FACTORY_CONTRACT,
+} from "~test/test-contracts.js";
+import { fetchNftName } from "./name.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("NFTName", () => {
+  it("fetchNftName should work with ERC721", async () => {
+    const desc = await fetchNftName({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+    });
+    expect(desc).toBe("Doodle #0");
+  });
+
+  it("fetchNftName should work with ERC1155", async () => {
+    const desc = await fetchNftName({
+      contract: DROP1155_CONTRACT,
+      tokenId: 0n,
+    });
+    expect(desc).toBe("Aura OG");
+  });
+
+  it("fetchNftName should respect nameResolver as a string", async () => {
+    const desc = await fetchNftName({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      nameResolver: "string",
+    });
+    expect(desc).toBe("string");
+  });
+
+  it("fetchNftName should respect nameResolver as a non-async function", async () => {
+    const desc = await fetchNftName({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      nameResolver: () => "non-async",
+    });
+    expect(desc).toBe("non-async");
+  });
+
+  it("fetchNftName should respect nameResolver as a async function", async () => {
+    const desc = await fetchNftName({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      nameResolver: async () => "async",
+    });
+    expect(desc).toBe("async");
+  });
+
+  it("fetchNftName should throw error if failed to resolve nft info", async () => {
+    await expect(() =>
+      fetchNftName({
+        contract: UNISWAPV3_FACTORY_CONTRACT,
+        tokenId: 0n,
+      }),
+    ).rejects.toThrowError("Failed to resolve NFT info");
+  });
+});

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

@@ -1,8 +1,8 @@
-import type { UseQueryOptions } from "@tanstack/react-query";
+import { type UseQueryOptions, useQuery } from "@tanstack/react-query";
 import type { JSX } from "react";
-import type { NFT } from "../../../../../utils/nft/parseNft.js";
-import { useNftInfo } from "./hooks.js";
+import type { ThirdwebContract } from "../../../../../contract/contract.js";
 import { useNFTContext } from "./provider.js";
+import { getNFTInfo } from "./utils.js";
 
 export interface NFTNameProps
   extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
@@ -11,7 +11,12 @@ export interface NFTNameProps
   /**
    * Optional `useQuery` params
    */
-  queryOptions?: Omit<UseQueryOptions<NFT>, "queryFn" | "queryKey">;
+  queryOptions?: Omit<UseQueryOptions<string>, "queryFn" | "queryKey">;
+  /**
+   * This prop can be a string or a (async) function that resolves to a string, representing the name of the NFT
+   * This is particularly useful if you already have a way to fetch the name of the NFT.
+   */
+  nameResolver?: string | (() => string) | (() => Promise<string>);
 }
 
 /**
@@ -56,6 +61,22 @@ export interface NFTNameProps
  * </NFTProvider>
  * ```
  *
+ * ### Override the name with the `nameResolver` prop
+ * If you already have the name, you can skip the network requests and pass it directly to the NFTName
+ * ```tsx
+ * <NFTName nameResolver="Doodles #1" />
+ * ```
+ *
+ * You can also pass in your own custom (async) function that retrieves the name
+ * ```tsx
+ * const getName = async () => {
+ *   // ...
+ *   return name;
+ * };
+ *
+ * <NFTName nameResolver={getName} />
+ * ```
+ *
  * @nft
  * @component
  * @beta
@@ -64,22 +85,61 @@ export function NFTName({
   loadingComponent,
   fallbackComponent,
   queryOptions,
+  nameResolver,
   ...restProps
 }: NFTNameProps) {
   const { contract, tokenId } = useNFTContext();
 
-  const nftQuery = useNftInfo({
-    contract,
-    tokenId,
-    queryOptions,
+  const nameQuery = useQuery({
+    queryKey: [
+      "_internal_nft_name_",
+      contract.chain.id,
+      tokenId.toString(),
+      {
+        resolver:
+          typeof nameResolver === "string"
+            ? nameResolver
+            : typeof nameResolver === "function"
+              ? nameResolver.toString()
+              : undefined,
+      },
+    ],
+    queryFn: async (): Promise<string> =>
+      fetchNftName({ nameResolver, contract, tokenId }),
+    ...queryOptions,
   });
 
-  if (nftQuery.isLoading) {
+  if (nameQuery.isLoading) {
     return loadingComponent || null;
   }
 
-  if (!nftQuery.data?.metadata?.name) {
+  if (!nameQuery.data) {
     return fallbackComponent || null;
   }
-  return <span {...restProps}>{nftQuery.data.metadata.name}</span>;
+  return <span {...restProps}>{nameQuery.data}</span>;
+}
+
+/**
+ * @internal Exported for tests
+ */
+export async function fetchNftName(props: {
+  nameResolver?: string | (() => string) | (() => Promise<string>);
+  contract: ThirdwebContract;
+  tokenId: bigint;
+}): Promise<string> {
+  const { nameResolver, contract, tokenId } = props;
+  if (typeof nameResolver === "string") {
+    return nameResolver;
+  }
+  if (typeof nameResolver === "function") {
+    return nameResolver();
+  }
+  const nft = await getNFTInfo({ contract, tokenId }).catch(() => undefined);
+  if (!nft) {
+    throw new Error("Failed to resolve NFT info");
+  }
+  if (typeof nft.metadata.name !== "string") {
+    throw new Error("Failed to resolve NFT name");
+  }
+  return nft.metadata.name;
 }

package/src/react/web/ui/prebuilt/NFT/{NFT.test.tsx → provider.test.tsx}

@@ -1,48 +1,13 @@
-import { useContext } from "react";
-import { describe, expect, it } from "vitest";
-import { render, screen, waitFor } from "~test/react-render.js";
+import { type FC, useContext } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { render, renderHook, screen, waitFor } from "~test/react-render.js";
 import { DOODLES_CONTRACT } from "~test/test-contracts.js";
-import { getNFTInfo } from "./hooks.js";
+import { NFTDescription } from "./description.js";
 import { NFTMedia } from "./media.js";
 import { NFTName } from "./name.js";
-import { NFTProvider, NFTProviderContext } from "./provider.js";
-
-describe.runIf(process.env.TW_SECRET_KEY)("NFT prebuilt component", () => {
-  it("should fetch the NFT metadata", async () => {
-    const nft = await getNFTInfo({
-      contract: DOODLES_CONTRACT,
-      tokenId: 1n,
-    });
-    expect(nft.metadata).toStrictEqual({
-      attributes: [
-        {
-          trait_type: "face",
-          value: "holographic beard",
-        },
-        {
-          trait_type: "hair",
-          value: "white bucket cap",
-        },
-        {
-          trait_type: "body",
-          value: "purple sweater with satchel",
-        },
-        {
-          trait_type: "background",
-          value: "grey",
-        },
-        {
-          trait_type: "head",
-          value: "gradient 2",
-        },
-      ],
-      description:
-        "A community-driven collectibles project featuring art by Burnt Toast. Doodles come in a joyful range of colors, traits and sizes with a collection size of 10,000. Each Doodle allows its owner to vote for experiences and activations paid for by the Doodles Community Treasury. Burnt Toast is the working alias for Scott Martin, a Canadian–based illustrator, designer, animator and muralist.",
-      image: "ipfs://QmTDxnzcvj2p3xBrKcGv1wxoyhAn2yzCQnZZ9LmFjReuH9",
-      name: "Doodle #1",
-    });
-  });
+import { NFTProvider, NFTProviderContext, useNFTContext } from "./provider.js";
 
+describe.runIf(process.env.TW_SECRET_KEY)("NFTProvider", () => {
   it("should render children correctly", () => {
     render(
       <NFTProvider contract={DOODLES_CONTRACT} tokenId={0n}>
@@ -99,7 +64,7 @@ describe.runIf(process.env.TW_SECRET_KEY)("NFT prebuilt component", () => {
   it("should render the NFT description", () => {
     render(
       <NFTProvider contract={DOODLES_CONTRACT} tokenId={1n}>
-        <NFTName />
+        <NFTDescription />
       </NFTProvider>,
     );
 
@@ -111,4 +76,31 @@ describe.runIf(process.env.TW_SECRET_KEY)("NFT prebuilt component", () => {
       ).toBeInTheDocument(),
     );
   });
+
+  it("useNFTContext should return the context value when used within NFTProvider", () => {
+    const wrapper: FC = ({ children }: React.PropsWithChildren) => (
+      <NFTProvider contract={DOODLES_CONTRACT} tokenId={0n}>
+        {children}
+      </NFTProvider>
+    );
+
+    const { result } = renderHook(() => useNFTContext(), { wrapper });
+
+    expect(result.current.contract).toStrictEqual(DOODLES_CONTRACT);
+    expect(result.current.tokenId).toBe(0n);
+  });
+
+  it("useNFTContext should throw an error when used outside of NFTProvider", () => {
+    const consoleErrorSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    expect(() => {
+      renderHook(() => useNFTContext());
+    }).toThrow(
+      "NFTProviderContext not found. Make sure you are using NFTMedia, NFTDescription, etc. inside a <NFTProvider /> component",
+    );
+
+    consoleErrorSpy.mockRestore();
+  });
 });