update

Author: kien-ngo

.changeset/serious-bananas-boil.md

@@ -0,0 +1,9 @@
+---
+"thirdweb": minor
+---
+
+Improve NFT Components
+- Add custom resolver methods to NFTMedia, NFTName and NFTDescription
+- Add caching for the NFT-info-getter method to improve performance
+- Small fix to handle falsy values for NFT media src, name and description
+- Improve test coverage by extracting internal logics and testing them

packages/thirdweb/src/react/web/ui/prebuilt/NFT/description.test.tsx

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { DOODLES_CONTRACT, DROP1155_CONTRACT } from "~test/test-contracts.js";
+import { fetchNftDescription } from "./description.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("NFTDescription", () => {
+  it("fetchNftDescription should work with ERC721", async () => {
+    const desc = await fetchNftDescription({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+    });
+    expect(desc).toBe(
+      "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.",
+    );
+  });
+
+  it("fetchNftDescription should work with ERC1155", async () => {
+    const desc = await fetchNftDescription({
+      contract: DROP1155_CONTRACT,
+      tokenId: 0n,
+    });
+    expect(desc).toBe("");
+  });
+
+  it("fetchNftDescription should respect descriptionResolver as a string", async () => {
+    const desc = await fetchNftDescription({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      descriptionResolver: "string",
+    });
+    expect(desc).toBe("string");
+  });
+
+  it("fetchNftDescription should respect descriptionResolver as a non-async function", async () => {
+    const desc = await fetchNftDescription({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      descriptionResolver: () => "non-async",
+    });
+    expect(desc).toBe("non-async");
+  });
+
+  it("fetchNftDescription should respect descriptionResolver as a async function", async () => {
+    const desc = await fetchNftDescription({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      descriptionResolver: async () => "async",
+    });
+    expect(desc).toBe("async");
+  });
+});

packages/thirdweb/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,53 @@ 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(),
+    ],
+    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;
 }

packages/thirdweb/src/react/web/ui/prebuilt/NFT/hooks.tsx

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { DOODLES_CONTRACT, DROP1155_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).toBe("ipfs://QmUEfFfwAh4wyB5UfHCVPUxis4j4Q4kJXtm5x5p3g1fVUn");
+  });
+
+  it("fetchNftMedia should work with ERC1155", async () => {
+    const desc = await fetchNftMedia({
+      contract: DROP1155_CONTRACT,
+      tokenId: 0n,
+    });
+    expect(desc).toBe(
+      "ipfs://QmeGCqV1mSHTZrvuFzW1XZdCRRGXB6AmSotTqHoxA2xfDo/1.mp4",
+    );
+  });
+
+  it("fetchNftMedia should respect mediaResolver as a string", async () => {
+    const desc = await fetchNftMedia({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      mediaResolver: "string",
+    });
+    expect(desc).toBe("string");
+  });
+
+  it("fetchNftMedia should respect mediaResolver as a non-async function", async () => {
+    const desc = await fetchNftMedia({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      mediaResolver: () => "non-async",
+    });
+    expect(desc).toBe("non-async");
+  });
+
+  it("fetchNftMedia should respect mediaResolver as a async function", async () => {
+    const desc = await fetchNftMedia({
+      contract: DOODLES_CONTRACT,
+      tokenId: 0n,
+      mediaResolver: async () => "async",
+    });
+    expect(desc).toBe("async");
+  });
+});