Skip to content

Commit

Permalink
Improve BYO Wallet Selector Docs (#361)
Browse files Browse the repository at this point in the history
* Improve BYO Wallet Selector Docs

* One more code sample

* Consistency

* Consistency
  • Loading branch information
blakezimmerman authored Jul 11, 2024
1 parent 7e45af8 commit 1f9a1fe
Show file tree
Hide file tree
Showing 10 changed files with 67 additions and 3 deletions.
70 changes: 67 additions & 3 deletions packages/wallet-adapter-react/docs/BYO-wallet-selector.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ The `@aptos-labs/wallet-adapter-react` package exposes all of the primitives tha

This document covers each primitive one-by-one, but if you want to see a full example of how these primitives can be composed to create a full wallet selector, refer to the implementation of the `shadcn/ui` wallet selector located in [`WalletSelector.tsx`](../../../apps/nextjs-example/src/components/WalletSelector.tsx) from the example Next.js app.

![shadcn/ui wallet selector](./images/wallet-selector.png)

## Headless Components

The following components are "headless", meaning that they do not include any styles. They simply provide elements with pre-attached event handlers and `aria-*` properties. It is up to you to compose and style them as you wish.
Expand Down Expand Up @@ -73,6 +75,26 @@ const WalletRow = ({ wallet, onConnect }: WalletItemProps) => (
);
```

![shadcn/ui WalletItem](./images/wallet-item-1.png)
![shadcn/ui WalletItem](./images/wallet-item-2.png)

```tsx
import { WalletItem, WalletItemProps } from "@aptos-labs/wallet-adapter-react";

const AptosConnectWalletRow = ({ wallet, onConnect }: WalletItemProps) => {
return (
<WalletItem wallet={wallet} onConnect={onConnect}>
<WalletItem.ConnectButton>
<WalletItem.Icon />
<WalletItem.Name />
</WalletItem.ConnectButton>
</WalletItem>
);
};
```

![shadcn/ui WalletItem](./images/wallet-item-3.png)

#### `WalletItem`

This is a headless component that serves as a wrapper element and sets up a React context to provide the wallet information to the rest of the `WalletItem.*` components.
Expand Down Expand Up @@ -108,6 +130,8 @@ const PrivacyPolicy = () => (
);
```

![shadcn/ui AptosPrivacyPolicy](./images/privacy-policy.png)

#### `AptosPrivacyPolicy`

This is a headless component that simply serves as a wrapper element for the rest of the `AptosPrivacyPolicy.*` components.
Expand Down Expand Up @@ -141,11 +165,37 @@ const WalletSelector = () => (
</AboutAptosConnect>
);

function renderEducationScreen(screen: AboutAptosConnectEducationScreen) {
return <></>;
}
const renderEducationScreen = (screen: AboutAptosConnectEducationScreen) => {
return (
<>
<div>
<button onClick={screen.cancel}>Cancel</button>
<h2>About Aptos Connect</h2>
</div>
<screen.Graphic />
<screen.Title />
<screen.Description />
<div>
<button onClick={screen.back}>Back</button>
<div>
{screen.screenIndicators.map((ScreenIndicator, i) => (
<ScreenIndicator key={i} />
))}
</div>
<button onClick={screen.next}>
{screen.screenIndex === screen.totalScreens - 1 ? "Finish" : "Next"}
</button>
</div>
</>
);
};
```

![shadcn/ui AboutAptosConnect.Trigger](./images/edu-trigger.png)
![shadcn/ui Education Screen 1](./images/edu-screen-1.png)
![shadcn/ui Education Screen 2](./images/edu-screen-2.png)
![shadcn/ui Education Screen 3](./images/edu-screen-3.png)

#### `AboutAptosConnect`

This component sets up a React context for managing the education screen flow, but does not render a wrapper element. Each of the education screens follow the same structure so the `renderEducationScreen` prop is a function that provides a `screen` object that you can map to a `ReactNode`. Each education screen will be rendered via your provided mapping function.
Expand All @@ -154,6 +204,20 @@ This component sets up a React context for managing the education screen flow, b

This is a headless component that renders a button element that when clicked will trigger the education screen flow. When triggered, the children of the `AboutAptosConnect` component will be replaced with the current education screen so `AboutAptosConnect` should wrap the entire body of your wallet selector UI.

#### `AboutAptosConnectEducationScreen`

This is the type of the `screen` object that is provided by `AboutAptosConnect`'s `renderEducationScreen` prop. You can map this object to a `ReactNode` to render each education screen. Each `screen` object has the following properties:

- `Graphic` - A component that renders an SVG to illustrate the idea of the current screen.
- `Title` - A headless component that renders the title of the current screen.
- `Description` - A headless component that renders the description text of the current screen.
- `screenIndex` - The index of the current education screen.
- `totalScreens` - The total number of education screens.
- `screenIndicators` - An array of headless components for indicating the current screen of the set. Each indicator will navigate the user to the screen it represents when clicked.
- `back` - A function that navigates the user to the previous education screen. If the user is on the first education screen, they will be navigated to the initial wallet selection screen.
- `next` - A function that navigates the user to the next education screen. If the user is on the last education screen, they will be navigated to the initial wallet selection screen.
- `cancel` - A function that navigates the user to the initial wallet selection screen.

## Utilities

### `isInstalledOrLoadable`
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 1f9a1fe

Please sign in to comment.