thirdweb 5.69.1-nightly-f368793375d099eec53569330af7a083e558e483-20241120000334 → 5.70.0-nightly-ecaa304a812188da3c81888bb52ca6064093c139-20241121000332

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

@@ -0,0 +1,175 @@
+"use client";
+
+import { type UseQueryOptions, useQuery } from "@tanstack/react-query";
+import type React from "react";
+import type { JSX } from "react";
+import {
+  type ResolveNameOptions,
+  resolveName,
+} from "../../../../../extensions/ens/resolve-name.js";
+import { getSocialProfiles } from "../../../../../social/profiles.js";
+import type { SocialProfile } from "../../../../../social/types.js";
+import { useAccountContext } from "./provider.js";
+
+/**
+ * Props for the AccountName component
+ * @component
+ * @account
+ */
+export interface AccountNameProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children">,
+    Omit<ResolveNameOptions, "client" | "address"> {
+  /**
+   * A function used to transform (format) the name of the account.
+   * it should take in a string and output a string.
+   *
+   * This function is particularly useful
+   */
+  formatFn?: (str: string) => string;
+  /**
+   * Use this prop to prioritize the social profile that you want to display
+   * This is useful for a wallet containing multiple social profiles
+   */
+  socialType?: SocialProfile["type"];
+  /**
+   * This component will be shown while the name of the account is being fetched
+   * If not passed, the component will return `null`.
+   *
+   * You can pass a loading sign or spinner to this prop.
+   * @example
+   * ```tsx
+   * <AccountName loadingComponent={<Spinner />} />
+   * ```
+   */
+  loadingComponent?: JSX.Element;
+  /**
+   * This component will be shown if the request for fetching the name is done but could not retreive any result.
+   * You can pass the wallet address as the fallback option if that's the case.
+   *
+   * If not passed, the component will return `null`
+   *
+   * @example
+   * ```tsx
+   * <AccountName fallbackComponent={"0x1234....3f3f"} />
+   * ```
+   */
+  fallbackComponent?: JSX.Element;
+  /**
+   * Optional `useQuery` params
+   */
+  queryOptions?: Omit<UseQueryOptions<string>, "queryKey" | "queryFn">;
+}
+
+/**
+ * This component is used to display the name of the account.
+ * A "name" in this context is the username, or account of the social profiles that the wallet may have.
+ * In case a name is not found or failed to resolve, you can always fallback to displaying the wallet address instead by using the `fallbackComponent` prop.
+ *
+ * This component inherits all attribute of a native HTML <span> element, so you can style it just like how you would style a <span>.
+ *
+ * @param props
+ * @returns A `<span>` containing the name of the account
+ * ```html
+ * <span>{name}</span>
+ * ```
+ *
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * import { AccountProvider, AccountName } from "thirdweb/react";
+ *
+ * <AccountProvider address="0x1234...3f3f" client={client}>
+ *   <AccountName />
+ * </AccountProvider>
+ * ```
+ *
+ * ### Show wallet address while social name is being loaded
+ * ```tsx
+ * <AccountName
+ *   loadingComponent={<AccountAddress />}
+ * />
+ * ```
+ *
+ *
+ * ### Fallback to showing wallet address if fail to resolve social name
+ * ```tsx
+ * <AccountName
+ *   fallbackComponent={<AccountAddress />}
+ * />
+ * ```
+ *
+ * ### Transform the account name using `formatFn` prop
+ * ```tsx
+ * import { isAddress, shortenAddress } from "thirdweb/utils";
+ * import { AccountProvider, AccountName } from "thirdweb/react";
+ *
+ * // Let's say we want the name to be capitalized without using CSS
+ * const formatName = (name: string) => name.toUpperCase();
+ *
+ * return <AccountName formatFn={formatName} />
+ * ```
+ *
+ *
+ * ### Custom query options for useQuery
+ * This component uses `@tanstack-query`'s useQuery internally.
+ * You can use the `queryOptions` prop for more fine-grained control
+ * ```tsx
+ * <AccountName
+ *   queryOptions={{
+ *     enabled: isEnabled,
+ *     retry: 3
+ *   }}
+ * />
+ * ```
+ *
+ * @component
+ * @account
+ * @beta
+ */
+export function AccountName({
+  resolverAddress,
+  resolverChain,
+  socialType,
+  formatFn,
+  queryOptions,
+  loadingComponent,
+  fallbackComponent,
+  ...restProps
+}: AccountNameProps) {
+  const { address, client } = useAccountContext();
+  const nameQuery = useQuery({
+    queryKey: ["account-name", address],
+    queryFn: async () => {
+      const [socialData, ensName] = await Promise.all([
+        getSocialProfiles({ address, client }),
+        resolveName({
+          client,
+          address,
+          resolverAddress,
+          resolverChain,
+        }),
+      ]);
+
+      const name =
+        socialData?.filter(
+          (p) => p.name && (socialType ? p.type === socialType : true),
+        )[0]?.name || ensName;
+
+      if (!name) {
+        throw new Error("Failed to resolve account name");
+      }
+      return formatFn ? formatFn(name) : name;
+    },
+    ...queryOptions,
+  });
+
+  if (nameQuery.isLoading) {
+    return loadingComponent || null;
+  }
+
+  if (!nameQuery.data) {
+    return fallbackComponent || null;
+  }
+
+  return <span {...restProps}>{nameQuery.data}</span>;
+}

package/src/react/web/ui/prebuilt/Account/provider.test.tsx

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "~test/react-render.js";
+import { TEST_CLIENT } from "~test/test-clients.js";
+import { AccountAddress } from "./address.js";
+import { AccountProvider } from "./provider.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("AccountProvider component", () => {
+  it("should render children correctly", () => {
+    render(
+      <AccountProvider
+        address="0x12345674b599ce99958242b3D3741e7b01841DF3"
+        client={TEST_CLIENT}
+      >
+        <div>Child Component</div>
+      </AccountProvider>,
+    );
+
+    expect(screen.getByText("Child Component")).toBeInTheDocument();
+  });
+
+  it("should pass the address correctly to the children props", () => {
+    render(
+      <AccountProvider
+        address="0x12345674b599ce99958242b3D3741e7b01841DF3"
+        client={TEST_CLIENT}
+      >
+        <AccountAddress />
+      </AccountProvider>,
+    );
+
+    expect(
+      screen.getByText("0x12345674b599ce99958242b3D3741e7b01841DF3", {
+        exact: true,
+        selector: "span",
+      }),
+    ).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,69 @@
+"use client";
+import type { Address } from "abitype";
+import type React from "react";
+import { createContext, useContext } from "react";
+import type { ThirdwebClient } from "../../../../../client/client.js";
+
+/**
+ * Props for the <AccountProvider /> component
+ * @component
+ * @account
+ */
+export type AccountProviderProps = {
+  /**
+   * The user's wallet address
+   */
+  address: Address;
+  /**
+   * thirdweb Client
+   */
+  client: ThirdwebClient;
+};
+
+const AccountProviderContext = /* @__PURE__ */ createContext<
+  AccountProviderProps | undefined
+>(undefined);
+
+/**
+ * A React context provider component that supplies Account-related data to its child components.
+ *
+ * This component serves as a wrapper around the `AccountProviderContext.Provider` and passes
+ * the provided account data down to all of its child components through the context API.
+ *
+ * @example
+ * ```tsx
+ * import { AccountProvider, AccountAvatar, AccountName, AccountAddress  } from "thirdweb/react";
+ *
+ * <AccountProvider>
+ *   <AccountAvatar />
+ *   <AccountName />
+ *   <AccountAddress />
+ * </AccountProvider>
+ * ```
+ *
+ * @component
+ * @account
+ * @beta
+ */
+export function AccountProvider(
+  props: React.PropsWithChildren<AccountProviderProps>,
+) {
+  return (
+    <AccountProviderContext.Provider value={props}>
+      {props.children}
+    </AccountProviderContext.Provider>
+  );
+}
+
+/**
+ * @internal
+ */
+export function useAccountContext() {
+  const ctx = useContext(AccountProviderContext);
+  if (!ctx) {
+    throw new Error(
+      "AccountProviderContext not found. Make sure you are using AccountName, AccountAvatar, etc. inside an <AccountProvider /> component",
+    );
+  }
+  return ctx;
+}

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

@@ -2,7 +2,10 @@ import { useContext } from "react";
 import { describe, expect, it } from "vitest";
 import { render, screen, waitFor } from "~test/react-render.js";
 import { DOODLES_CONTRACT } from "~test/test-contracts.js";
-import { NFT, NFTProviderContext, getNFTInfo } from "./NFT.js";
+import { getNFTInfo } from "./hooks.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 () => {
@@ -42,9 +45,9 @@ describe.runIf(process.env.TW_SECRET_KEY)("NFT prebuilt component", () => {
 
   it("should render children correctly", () => {
     render(
-      <NFT contract={DOODLES_CONTRACT} tokenId={0n}>
+      <NFTProvider contract={DOODLES_CONTRACT} tokenId={0n}>
         <div>Child Component</div>
-      </NFT>,
+      </NFTProvider>,
     );
 
     expect(screen.getByText("Child Component")).toBeInTheDocument();
@@ -64,9 +67,9 @@ describe.runIf(process.env.TW_SECRET_KEY)("NFT prebuilt component", () => {
       );
     }
     render(
-      <NFT contract={DOODLES_CONTRACT} tokenId={0n}>
+      <NFTProvider contract={DOODLES_CONTRACT} tokenId={0n}>
         <NFTConsumer />
-      </NFT>,
+      </NFTProvider>,
     );
 
     expect(screen.getByText(/Contract:/)).toBeInTheDocument();
@@ -75,9 +78,9 @@ describe.runIf(process.env.TW_SECRET_KEY)("NFT prebuilt component", () => {
 
   it("should render the NFT image", () => {
     render(
-      <NFT contract={DOODLES_CONTRACT} tokenId={0n}>
-        <NFT.Media />
-      </NFT>,
+      <NFTProvider contract={DOODLES_CONTRACT} tokenId={0n}>
+        <NFTMedia />
+      </NFTProvider>,
     );
 
     waitFor(() => expect(screen.getByRole("img")).toBeInTheDocument());
@@ -85,9 +88,9 @@ describe.runIf(process.env.TW_SECRET_KEY)("NFT prebuilt component", () => {
 
   it("should render the NFT name", () => {
     render(
-      <NFT contract={DOODLES_CONTRACT} tokenId={1n}>
-        <NFT.Name />
-      </NFT>,
+      <NFTProvider contract={DOODLES_CONTRACT} tokenId={1n}>
+        <NFTName />
+      </NFTProvider>,
     );
 
     waitFor(() => expect(screen.getByText("Doodle #1")).toBeInTheDocument());
@@ -95,9 +98,9 @@ describe.runIf(process.env.TW_SECRET_KEY)("NFT prebuilt component", () => {
 
   it("should render the NFT description", () => {
     render(
-      <NFT contract={DOODLES_CONTRACT} tokenId={1n}>
-        <NFT.Name />
-      </NFT>,
+      <NFTProvider contract={DOODLES_CONTRACT} tokenId={1n}>
+        <NFTName />
+      </NFTProvider>,
     );
 
     waitFor(() =>

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>;
+}