update

Author: kien-ngo

.changeset/metal-cows-hear.md

@@ -0,0 +1,5 @@
+---
+"thirdweb": minor
+---
+
+Add headless UI component: Account (Name, Image, Address, Balance)

apps/playground-web/src/app/local/page.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import { THIRDWEB_CLIENT } from "@/lib/client";
+import { sepolia } from "thirdweb/chains";
+import { Account, ThirdwebProvider } from "thirdweb/react";
+import { shortenAddress } from "thirdweb/utils";
+
+export default function Page() {
+  return (
+    <ThirdwebProvider>
+      <Account.Provider
+        address="0x12345674b599ce99958242b3D3741e7b01841DF3"
+        client={THIRDWEB_CLIENT}
+      >
+        <div className="flex h-full w-full flex-col items-center gap-3">
+          <div className="my-3 flex flex-col gap-3 border p-5">
+            <div>
+              Let&apos;s rebuild a basic ConnectButton-details component
+            </div>
+            <BasicConnectedButton />
+          </div>
+        </div>
+      </Account.Provider>
+    </ThirdwebProvider>
+  );
+}
+
+const BasicConnectedButton = () => {
+  const roundUpBalance = (num: number) => Math.round(num * 10) / 10;
+  return (
+    <Button className="flex h-12 w-40 flex-row justify-start gap-3 px-2">
+      <Account.Avatar
+        className="h-10 w-10 rounded-full"
+        loadingComponent={
+          <Account.Blobbie className="h-10 w-10 rounded-full" />
+        }
+        fallbackComponent={
+          <Account.Blobbie className="h-10 w-10 rounded-full" />
+        }
+      />
+      <div className="flex flex-col items-start">
+        <Account.Name
+          loadingComponent={<Account.Address formatFn={shortenAddress} />}
+          fallbackComponent={<Account.Address formatFn={shortenAddress} />}
+        />
+        <Account.Balance
+          chain={sepolia}
+          formatFn={roundUpBalance}
+          loadingComponent={<span>Loading...</span>}
+          fallbackComponent={<span>N/A</span>}
+        />
+      </div>
+    </Button>
+  );
+};

packages/thirdweb/src/exports/react.ts

@@ -199,3 +199,6 @@ export type {
 // Site Embed and Linking
 export { SiteEmbed } from "../react/web/ui/SiteEmbed.js";
 export { SiteLink } from "../react/web/ui/SiteLink.js";
+
+// Account
+export * as Account from "../react/web/ui/prebuilt/Account/index.js";

packages/thirdweb/src/react/web/ui/ConnectWallet/Blobbie.tsx

@@ -21,13 +21,27 @@ const COLOR_OPTIONS = [
   ["#fda4af", "#be123c"],
 ];
 
+/**
+ * Props for the Blobbie component
+ * @component
+ */
+export type BlobbieProps = {
+  address: Address;
+  style?: Omit<React.CSSProperties, "backgroundImage">;
+  className?: string;
+  size?: number;
+};
+
 /**
  * A unique gradient avatar based on the provided address.
  * @param props The component props.
  * @param props.address The address to generate the gradient with.
- * @param props.size The size of each side of the square avatar (in pixels)
+ * @param props.style The CSS style for the component - excluding `backgroundImage`
+ * @param props.className The className for the component
+ * @param props.size The size of each side of the square avatar (in pixels). This prop will override the `width` and `height` attributes from the `style` prop.
+ * @component
  */
-export function Blobbie(props: { address: Address; size: number }) {
+export function Blobbie(props: BlobbieProps) {
   const id = useId();
   const colors = useMemo(
     () =>
@@ -41,10 +55,16 @@ export function Blobbie(props: { address: Address; size: number }) {
     <div
       id={id}
       style={{
-        width: `${props.size}px`,
-        height: `${props.size}px`,
+        ...props.style,
         backgroundImage: `radial-gradient(ellipse at left bottom, ${colors[0]}, ${colors[1]})`,
+        ...(props.size
+          ? {
+              width: `${props.size}px`,
+              height: `${props.size}px`,
+            }
+          : undefined),
       }}
+      className={props.className}
     />
   );
 }

packages/thirdweb/src/react/web/ui/prebuilt/Account/address.test.tsx

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "~test/react-render.js";
+import { TEST_CLIENT } from "~test/test-clients.js";
+import { shortenAddress } from "../../../../../utils/address.js";
+import { Address } from "./address.js";
+import { Provider } from "./provider.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("Account.Provider component", () => {
+  it("should format the address properly", () => {
+    render(
+      <Provider
+        address="0x12345674b599ce99958242b3D3741e7b01841DF3"
+        client={TEST_CLIENT}
+      >
+        <Address formatFn={shortenAddress} />
+      </Provider>,
+    );
+
+    waitFor(() =>
+      expect(
+        screen.getByText("0x1234...1DF3", {
+          exact: true,
+          selector: "span",
+        }),
+      ).toBeInTheDocument(),
+    );
+  });
+});

packages/thirdweb/src/react/web/ui/prebuilt/Account/address.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { useAccountContext } from "./provider.js";
+
+/**
+ * @component
+ * @account
+ */
+export interface AccountAddressProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+  /**
+   * The function used to transform (format) the wallet address
+   * Specifically useful for shortening the wallet.
+   *
+   * This function should take in a string and output a string
+   */
+  formatFn?: (str: string) => string;
+}
+
+/**
+ *
+ * @returns a <span> containing the full wallet address of the account
+ *
+ * @example
+ * ### Basic usage
+ * ```tsx
+ * import { Account } from "thirdweb/react";
+ *
+ * <Account address="0x12345674b599ce99958242b3D3741e7b01841DF3" client={TW_CLIENT}>
+ *   <Account.Address />
+ * </Account>
+ * ```
+ * Result:
+ * ```html
+ * <span>0x12345674b599ce99958242b3D3741e7b01841DF3</span>
+ * ```
+ *
+ *
+ * ### Shorten the address
+ * ```tsx
+ * import { Account } from "thirdweb/react";
+ * import { shortenAddress } from "thirdweb/utils";
+ *
+ * <Account address="0x12345674b599ce99958242b3D3741e7b01841DF3" client={TW_CLIENT}>
+ *   <Account.Address formatFn={shortenAddress} />
+ * </Account>
+ * ```
+ * Result:
+ * ```html
+ * <span>0x1234...1DF3</span>
+ * ```
+ *
+ * @component
+ * @account
+ */
+export const Address = ({ formatFn, ...restProps }: AccountAddressProps) => {
+  const { address } = useAccountContext();
+  const value = formatFn ? formatFn(address) : address;
+  return <span {...restProps}>{value}</span>;
+};

packages/thirdweb/src/react/web/ui/prebuilt/Account/avatar.test.tsx

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "~test/react-render.js";
+import { TEST_CLIENT } from "~test/test-clients.js";
+import { TEST_ACCOUNT_A } from "~test/test-wallets.js";
+import { Avatar } from "./avatar.js";
+import { Provider } from "./provider.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("Account.Provider component", () => {
+  it("should render an image", () => {
+    render(
+      <Provider
+        address={"0x12345674b599ce99958242b3D3741e7b01841DF3"}
+        client={TEST_CLIENT}
+      >
+        <Avatar />
+      </Provider>,
+    );
+
+    waitFor(() => expect(screen.getByRole("img")).toBeInTheDocument());
+  });
+
+  it("should fallback properly if failed to load", () => {
+    render(
+      <Provider address={TEST_ACCOUNT_A.address} client={TEST_CLIENT}>
+        <Avatar fallbackComponent={<span>oops</span>} />
+      </Provider>,
+    );
+
+    waitFor(() =>
+      expect(
+        screen.getByText("oops", {
+          exact: true,
+          selector: "span",
+        }),
+      ).toBeInTheDocument(),
+    );
+  });
+
+  it("should NOT render anything if fail to resolve avatar", () => {
+    render(
+      <Provider address={"invalid-wallet-address"} client={TEST_CLIENT}>
+        <Avatar />
+      </Provider>,
+    );
+
+    waitFor(() => expect(screen.getByRole("img")).not.toBeInTheDocument());
+  });
+});