[SDK] Feature: Account components (#5388)

cnct-2137

<!-- start pr-codex -->

---

## PR-Codex overview
This PR introduces a new `Account` component suite to the `thirdweb` library, enhancing user account management with features like account name, address, avatar, and balance display. It also marks existing `NFT` components as `@beta`.

### Detailed summary
- Added `Account` components: `AccountName`, `AccountAddress`, `AccountAvatar`, `AccountBalance`, and `AccountBlobbie`.
- Updated existing `NFT` components to `@beta`.
- Introduced tests for new `Account` components.
- Enhanced `AccountProvider` for context management.
- Updated documentation for new components and props.

> ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}`

<!-- end pr-codex -->

Author: kien-ngo

.changeset/metal-cows-hear.md

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

apps/portal/src/app/react/v5/sidebar.tsx

@@ -109,6 +109,22 @@ export const sidebar: SideBar = {
               href: `${slug}/${name}`,
               icon: <CodeIcon />,
             })),
+            {
+              name: "Account",
+              isCollapsible: true,
+              links: [
+                "AccountProvider",
+                "AccountAddress",
+                "AccountAvatar",
+                "AccountName",
+                "AccountBlobbie",
+                "AccountBalance",
+              ].map((name) => ({
+                name,
+                href: `${slug}/${name}`,
+                icon: <CodeIcon />,
+              })),
+            },
           ],
         },
         {

apps/portal/src/app/references/components/TDoc/utils/getSidebarLinkgroups.ts

@@ -41,6 +41,7 @@ const tagsToGroup = {
   "@social": "Social API",
   "@modules": "Modules",
   "@client": "Client",
+  "@account": "Account Components",
 } as const;
 
 type TagKey = keyof typeof tagsToGroup;
@@ -79,6 +80,7 @@ const sidebarGroupOrder: TagKey[] = [
   "@theme",
   "@utils",
   "@others",
+  "@account",
 ];
 
 function findTag(

packages/thirdweb/src/exports/react.ts

@@ -212,3 +212,26 @@ export type {
 // Site Embed and Linking
 export { SiteEmbed } from "../react/web/ui/SiteEmbed.js";
 export { SiteLink } from "../react/web/ui/SiteLink.js";
+
+// Account
+export {
+  AccountAddress,
+  type AccountAddressProps,
+} from "../react/web/ui/prebuilt/Account/address.js";
+export {
+  AccountBalance,
+  type AccountBalanceProps,
+} from "../react/web/ui/prebuilt/Account/balance.js";
+export {
+  AccountName,
+  type AccountNameProps,
+} from "../react/web/ui/prebuilt/Account/name.js";
+export { AccountBlobbie } from "../react/web/ui/prebuilt/Account/blobbie.js";
+export {
+  AccountProvider,
+  type AccountProviderProps,
+} from "../react/web/ui/prebuilt/Account/provider.js";
+export {
+  AccountAvatar,
+  type AccountAvatarProps,
+} from "../react/web/ui/prebuilt/Account/avatar.js";

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

@@ -21,18 +21,34 @@ 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
+ * @wallet
  * @example
  * ```tsx
- * <Blobbie address="0x...." size={24} />
+ * import { Blobbie } from "thirdweb/react";
+ *
+ * <Blobbie address="0x...." className="w-10 h-10" />
  * ```
- * @wallet
  */
-export function Blobbie(props: { address: Address; size: number }) {
+export function Blobbie(props: BlobbieProps) {
   const id = useId();
   const colors = useMemo(
     () =>
@@ -46,10 +62,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 { AccountAddress } from "./address.js";
+import { AccountProvider } from "./provider.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("AccountAddress component", () => {
+  it("should format the address properly", () => {
+    render(
+      <AccountProvider
+        address="0x12345674b599ce99958242b3D3741e7b01841DF3"
+        client={TEST_CLIENT}
+      >
+        <AccountAddress formatFn={shortenAddress} />
+      </AccountProvider>,
+    );
+
+    waitFor(() =>
+      expect(
+        screen.getByText("0x1234...1DF3", {
+          exact: true,
+          selector: "span",
+        }),
+      ).toBeInTheDocument(),
+    );
+  });
+});

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

@@ -0,0 +1,64 @@
+"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 { AccountProvider, AccountAddress } from "thirdweb/react";
+ *
+ * <AccountProvider address="0x12345674b599ce99958242b3D3741e7b01841DF3" client={TW_CLIENT}>
+ *   <AccountAddress />
+ * </AccountProvider>
+ * ```
+ * Result:
+ * ```html
+ * <span>0x12345674b599ce99958242b3D3741e7b01841DF3</span>
+ * ```
+ *
+ *
+ * ### Shorten the address
+ * ```tsx
+ * import { AccountProvider, AccountAddress } from "thirdweb/react";
+ * import { shortenAddress } from "thirdweb/utils";
+ *
+ * <AccountProvider address="0x12345674b599ce99958242b3D3741e7b01841DF3" client={TW_CLIENT}>
+ *   <AccountAddress formatFn={shortenAddress} />
+ * </AccountProvider>
+ * ```
+ * Result:
+ * ```html
+ * <span>0x1234...1DF3</span>
+ * ```
+ *
+ * @component
+ * @account
+ * @beta
+ */
+export function AccountAddress({
+  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 { AccountAvatar } from "./avatar.js";
+import { AccountProvider } from "./provider.js";
+
+describe.runIf(process.env.TW_SECRET_KEY)("AccountAvatar component", () => {
+  it("should render an image", () => {
+    render(
+      <AccountProvider
+        address={"0x12345674b599ce99958242b3D3741e7b01841DF3"}
+        client={TEST_CLIENT}
+      >
+        <AccountAvatar />
+      </AccountProvider>,
+    );
+
+    waitFor(() => expect(screen.getByRole("img")).toBeInTheDocument());
+  });
+
+  it("should fallback properly if failed to load", () => {
+    render(
+      <AccountProvider address={TEST_ACCOUNT_A.address} client={TEST_CLIENT}>
+        <AccountAvatar fallbackComponent={<span>oops</span>} />
+      </AccountProvider>,
+    );
+
+    waitFor(() =>
+      expect(
+        screen.getByText("oops", {
+          exact: true,
+          selector: "span",
+        }),
+      ).toBeInTheDocument(),
+    );
+  });
+
+  it("should NOT render anything if fail to resolve avatar", () => {
+    render(
+      <AccountProvider address={"invalid-wallet-address"} client={TEST_CLIENT}>
+        <AccountAvatar />
+      </AccountProvider>,
+    );
+
+    waitFor(() => expect(screen.getByRole("img")).not.toBeInTheDocument());
+  });
+});