thirdweb 5.71.0 → 5.72.0-nightly-a98550d229e7fd124e1977fcc64dbd1b602ce656-20241126000403

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

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "~test/react-render.js";
+import { ethereum } from "../../../../../chains/chain-definitions/ethereum.js";
+import { defineChain } from "../../../../../chains/utils.js";
+import { ChainName } from "./name.js";
+import { ChainProvider } from "./provider.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("ChainName component", () => {
+  it("should return the correct chain name, if the name exists in the chain object", () => {
+    render(
+      <ChainProvider chain={ethereum}>
+        <ChainName />
+      </ChainProvider>,
+    );
+    waitFor(() =>
+      expect(
+        screen.getByText("Ethereum", {
+          exact: true,
+          selector: "span",
+        }),
+      ).toBeInTheDocument(),
+    );
+  });
+
+  it("should return the correct chain name, if the name is loaded from the server", () => {
+    render(
+      <ChainProvider chain={defineChain(1)}>
+        <ChainName />
+      </ChainProvider>,
+    );
+    waitFor(() =>
+      expect(
+        screen.getByText("Ethereum Mainnet", {
+          exact: true,
+          selector: "span",
+        }),
+      ).toBeInTheDocument(),
+    );
+  });
+
+  it("should return the correct FORMATTED chain name", () => {
+    render(
+      <ChainProvider chain={ethereum}>
+        <ChainName formatFn={(str: string) => `${str}-formatted`} />
+      </ChainProvider>,
+    );
+    waitFor(() =>
+      expect(
+        screen.getByText("Ethereum-formatted", {
+          exact: true,
+          selector: "span",
+        }),
+      ).toBeInTheDocument(),
+    );
+  });
+
+  it("should fallback properly when fail to resolve chain name", () => {
+    render(
+      <ChainProvider chain={defineChain(-1)}>
+        <ChainName fallbackComponent={<span>oops</span>} />
+      </ChainProvider>,
+    );
+
+    waitFor(() =>
+      expect(
+        screen.getByText("oops", {
+          exact: true,
+          selector: "span",
+        }),
+      ).toBeInTheDocument(),
+    );
+  });
+});

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

@@ -0,0 +1,185 @@
+"use client";
+
+import { type UseQueryOptions, useQuery } from "@tanstack/react-query";
+import type React from "react";
+import type { JSX } from "react";
+import { getChainMetadata } from "../../../../../chains/utils.js";
+import { useChainContext } from "./provider.js";
+
+/**
+ * Props for the ChainName component
+ * @component
+ * @chain
+ */
+export interface ChainNameProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+  /**
+   * This prop can be a string or a (async) function that resolves to a string, representing the name of the chain
+   * This is particularly useful if you already have a way to fetch the chain name.
+   */
+  nameResolver?: string | (() => string) | (() => Promise<string>);
+  /**
+   * A function to format the name's display value
+   * Particularly useful to avoid overflowing-UI issues
+   *
+   * ```tsx
+   * <ChainName formatFn={(str: string) => doSomething()} />
+   * ```
+   */
+  formatFn?: (str: string) => string;
+  /**
+   * This component will be shown while the name of the chain is being fetched
+   * If not passed, the component will return `null`.
+   *
+   * You can/should pass a loading sign or spinner to this prop.
+   * @example
+   * ```tsx
+   * <ChainName loadingComponent={<Spinner />} />
+   * ```
+   */
+  loadingComponent?: JSX.Element;
+  /**
+   * This component will be shown if the name fails to be retreived
+   * If not passed, the component will return `null`.
+   *
+   * You can/should pass a descriptive text/component to this prop, indicating that the
+   * name was not fetched succesfully
+   * @example
+   * ```tsx
+   * <ChainName fallbackComponent={"Failed to load"}
+   * />
+   * ```
+   */
+  fallbackComponent?: JSX.Element;
+  /**
+   * Optional `useQuery` params
+   */
+  queryOptions?: Omit<UseQueryOptions<string>, "queryFn" | "queryKey">;
+}
+
+/**
+ * This component fetches then shows the name of a chain.
+ * It inherits all the attributes of a HTML <span> component, hence you can style it just like how you would style a normal <span>
+ *
+ *
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * import { ChainProvider, ChainName } from "thirdweb/react";
+ * import { ethereum } from "thirdweb/chains";
+ *
+ * <ChainProvider {...props}>
+ *   <ChainName  />
+ * </ChainProvider>
+ * ```
+ * Result:
+ * ```html
+ * <span>Ethereum Mainnet</span>
+ * ```
+ *
+ * ### Custom name resolver
+ * By default ChainName will call the thirdweb API to retrieve the chain name.
+ * However if you have a different way to fetch the name, you can pass the function to the `nameResolver` prop.
+ * Note: nameResolver should either be a string or a function (async) that returns a string.
+ * ```tsx
+ * async function fetchNameMethod() {
+ *   // your own fetching logic
+ *   return "the chain name";
+ * }
+ *
+ * <ChainName nameResolver={fetchNameMethod} />
+ * ```
+ *
+ * Alternatively you can also pass in a string directly:
+ * ```tsx
+ * <ChainName nameResolver="ETH Mainnet" />
+ * ```
+ *
+ *
+ * ### Format the name (capitalize, truncate, etc.)
+ * The ChainName component accepts a `formatFn` which takes in a string and outputs a string
+ * The function is used to modify the name of the chain
+ *
+ * ```tsx
+ * const concatStr = (str: string):string => str + "Network"
+ *
+ * <ChainProvider {...props}>
+ *   <ChainName formatFn={concatStr} />
+ * </ChainProvider>
+ * ```
+ *
+ * Result:
+ * ```html
+ * <span>Ethereum Mainnet Network</span>
+ * ```
+ *
+ * ### Show a loading sign when the name is being fetched
+ * ```tsx
+ * import { ChainProvider, ChainName } from "thirdweb/react";
+ *
+ * <ChainProvider {...props}>
+ *   <ChainName loadingComponent={<Spinner />} />
+ * </ChainProvider>
+ * ```
+ *
+ * ### Fallback to something when the name fails to resolve
+ * ```tsx
+ * <ChainProvider {...props}>
+ *   <ChainName fallbackComponent={"Failed to load"} />
+ * </ChainProvider>
+ * ```
+ *
+ * ### 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
+ * <ChainName
+ *   queryOptions={{
+ *     enabled: isEnabled,
+ *     retry: 4,
+ *   }}
+ * />
+ * ```
+ *
+ * @component
+ * @chain
+ * @beta
+ */
+export function ChainName({
+  nameResolver,
+  formatFn,
+  loadingComponent,
+  fallbackComponent,
+  queryOptions,
+  ...restProps
+}: ChainNameProps) {
+  const { chain } = useChainContext();
+  const nameQuery = useQuery({
+    queryKey: ["_internal_chain_name_", chain.id] as const,
+    queryFn: async () => {
+      if (typeof nameResolver === "string") {
+        return nameResolver;
+      }
+      if (typeof nameResolver === "function") {
+        return nameResolver();
+      }
+      if (chain.name) {
+        return chain.name;
+      }
+      return getChainMetadata(chain).then((data) => data.name);
+    },
+    ...queryOptions,
+  });
+
+  if (nameQuery.isLoading) {
+    return loadingComponent || null;
+  }
+
+  if (!nameQuery.data) {
+    return fallbackComponent || null;
+  }
+
+  const displayValue = formatFn ? formatFn(nameQuery.data) : nameQuery.data;
+
+  return <span {...restProps}>{displayValue}</span>;
+}

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

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "~test/react-render.js";
+import { ethereum } from "../../../../../chains/chain-definitions/ethereum.js";
+import { ChainName } from "./name.js";
+import { ChainProvider } from "./provider.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("ChainProvider component", () => {
+  it("should render children correctly", () => {
+    render(
+      <ChainProvider chain={ethereum}>
+        <div>Child Component</div>
+      </ChainProvider>,
+    );
+
+    expect(screen.getByText("Child Component")).toBeInTheDocument();
+  });
+
+  it("should pass the chain correctly to the children props", () => {
+    render(
+      <ChainProvider chain={ethereum}>
+        <ChainName />
+      </ChainProvider>,
+    );
+
+    waitFor(() =>
+      expect(
+        screen.getByText("Ethereum", {
+          exact: true,
+          selector: "span",
+        }),
+      ).toBeInTheDocument(),
+    );
+  });
+});

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

@@ -0,0 +1,73 @@
+"use client";
+
+import type React from "react";
+import { createContext, useContext } from "react";
+import type { Chain } from "../../../../../chains/types.js";
+
+/**
+ * Props for the <ChainProvider /> component
+ * @component
+ * @chain
+ */
+export type ChainProviderProps = {
+  chain: Chain;
+};
+
+const ChainProviderContext = /* @__PURE__ */ createContext<
+  ChainProviderProps | undefined
+>(undefined);
+
+/**
+ * A React context provider component that supplies Chain-related data to its child components.
+ *
+ * This component serves as a wrapper around the `ChainProviderContext.Provider` and passes
+ * the provided chain data down to all of its child components through the context API.
+ *
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * import { ChainProvider, ChainIcon, ChainName } from "thirdweb/react";
+ * import { ethereum } from "thirdweb/chains";
+ *
+ * <ChainProvider chain={ethereum}>
+ *   <ChainIcon />
+ *   <ChainName />
+ * </ChainProvider>
+ * ```
+ *
+ * ### Usage with defineChain
+ * ```tsx
+ * import { defineChain } from "thirdweb/chains"l
+ * import { ChainProvider, ChainName } from "thirdweb/react";
+ *
+ * const chainId = someNumber;
+ *
+ * <ChainProvider chain={defineChain(chainId)}>
+ *   <ChainName />
+ * </ChainProvider>
+ * ```
+ * @component
+ * @chain
+ */
+export function ChainProvider(
+  props: React.PropsWithChildren<ChainProviderProps>,
+) {
+  return (
+    <ChainProviderContext.Provider value={props}>
+      {props.children}
+    </ChainProviderContext.Provider>
+  );
+}
+
+/**
+ * @internal
+ */
+export function useChainContext() {
+  const ctx = useContext(ChainProviderContext);
+  if (!ctx) {
+    throw new Error(
+      "ChainProviderContext not found. Make sure you are using ChainName, ChainIcon, etc. inside a <ChainProvider /> component",
+    );
+  }
+  return ctx;
+}

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

@@ -7,6 +7,11 @@ import { getContractMetadata } from "../../../../../extensions/common/read/getCo
 import { resolveScheme } from "../../../../../utils/ipfs.js";
 import { useTokenContext } from "./provider.js";
 
+/**
+ * Props for the TokenIcon component
+ * @component
+ * @token
+ */
 export interface TokenIconProps
   extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src"> {
   /**

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

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "~test/react-render.js";
+import { TEST_CLIENT } from "~test/test-clients.js";
+import { ethereum } from "../../../../../chains/chain-definitions/ethereum.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../../../../constants/addresses.js";
+import { TokenName } from "./name.js";
+import { TokenProvider } from "./provider.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("TokenProvider component", () => {
+  it("should render children correctly", () => {
+    render(
+      <TokenProvider
+        address={NATIVE_TOKEN_ADDRESS}
+        client={TEST_CLIENT}
+        chain={ethereum}
+      >
+        <div>Child Component</div>
+      </TokenProvider>,
+    );
+
+    expect(screen.getByText("Child Component")).toBeInTheDocument();
+  });
+
+  it("should pass the token data correctly to the children props", () => {
+    render(
+      <TokenProvider
+        address={NATIVE_TOKEN_ADDRESS}
+        client={TEST_CLIENT}
+        chain={ethereum}
+      >
+        <TokenName />
+      </TokenProvider>,
+    );
+
+    waitFor(() =>
+      expect(
+        screen.getByText("Ether", {
+          exact: true,
+          selector: "span",
+        }),
+      ).toBeInTheDocument(),
+    );
+  });
+});

package/src/react/web/ui/prebuilt/Token/symbol.test.tsx

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "~test/react-render.js";
+import { TEST_CLIENT } from "~test/test-clients.js";
+import { ethereum } from "../../../../../chains/chain-definitions/ethereum.js";
+import { NATIVE_TOKEN_ADDRESS } from "../../../../../constants/addresses.js";
+import { TokenProvider } from "./provider.js";
+import { TokenSymbol } from "./symbol.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("TokenSymbol component", () => {
+  it("should pass the address correctly to the children props", () => {
+    render(
+      <TokenProvider
+        address={NATIVE_TOKEN_ADDRESS}
+        client={TEST_CLIENT}
+        chain={ethereum}
+      >
+        <TokenSymbol />
+      </TokenProvider>,
+    );
+
+    waitFor(() =>
+      expect(
+        screen.getByText("ETH", {
+          exact: true,
+          selector: "span",
+        }),
+      ).toBeInTheDocument(),
+    );
+  });
+});

package/src/version.ts

@@ -1 +1 @@
-export const version = "5.71.0";
+export const version = "5.72.0-nightly-a98550d229e7fd124e1977fcc64dbd1b602ce656-20241126000403";