Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve BYO Wallet Selector Docs #361

Merged
merged 4 commits into from
Jul 11, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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.
Loading