Skip to content
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
9 changes: 7 additions & 2 deletions .claude/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ cd examples/react-css-only && pnpm dev # CSS-only example
cd examples/react-custom && pnpm dev # Custom trigger/menu example
cd examples/react-web3auth && pnpm dev # Web3Auth + export-key plugin (needs VITE_WEB3AUTH_CLIENT_ID, see .env.example; open http://127.0.0.1:5173)
cd examples/vue && pnpm dev # Vue example
cd examples/react-passkey && pnpm dev # Passkey wallet + passkey plugin (http://localhost:5176)
cd examples/vue-passkey && pnpm dev # Vue passkey example (http://localhost:5177)
```

## Architecture
Expand All @@ -56,22 +58,24 @@ cd examples/vue && pnpm dev # Vue example
- `examples/react-custom/` - React example with custom triggers and menus
- `examples/react-web3auth/` - React example with Web3Auth and the export-key plugin
- `examples/vue/` - Vue example with Tailwind CSS
- `examples/react-passkey/`, `examples/vue-passkey/` - Passkey, Lute and Pera with the passkey plugin; e2e runs the `passkey-react` and `passkey-vue` projects against them with Chromium's virtual authenticator
- `e2e/` - Playwright E2E tests

### React Package Organization (`packages/react/src/`)

- `components/` - UI components (WalletButton, ConnectWalletMenu, ConnectedWalletMenu, NfdAvatar)
- `hooks/` - React hooks (useNfd, useAccountInfo, useResolvedTheme)
- `providers/` - WalletUIProvider (context for NFD lookups, theming, prefetching)
- `plugins/` - Plugin system and the `export-key` plugin (separate `./plugins/export-key` entry)
- `utils/` - Utilities (cn for classnames, IPFS URL conversion, font loading)
- `plugins/` - Plugin system, the `export-key` plugin and the `passkey` plugin (separate `./plugins/export-key` and `./plugins/passkey` entries)
- `utils/` - Utilities (cn for classnames, IPFS URL conversion, font loading, passkey error messages)

`packages/vue/src/` mirrors this layout, with `composables/` in place of `hooks/`.

### Key Dependencies

- Built on `@txnlab/use-wallet-react` / `@txnlab/use-wallet-vue` and `algosdk` v3 (use-wallet core 5.1+ requires `^3.7.0`). The peer range is `^4.6.0 || ^5.0.0`; devDependencies and examples use v5.
- Keep the library source compatible with both use-wallet v4 and v5. For example, `ConnectWalletMenu` uses `availableWallets ?? wallets` because v4 has no `availableWallets`.
- Passkey wallet (`id: 'passkey'`, use-wallet 5.2+): the connect dialog renders `PasskeyConnect` in one of two layouts, chosen by `passkeyLayout` (menu or `WalletButton` prop > `WalletUIProvider` prop > `'list'`, via `resolvePasskeyLayout`): `'list'` shows "Sign in with passkey" / "Create a passkey" rows in a Passkey group above a Wallets group; `'featured'` leads with "Continue with passkey" and a "Create a passkey" link, then the other wallets. `WalletList` never renders the passkey wallet. `ConnectedWalletMenu` tags passkey accounts with their domain. All of that is in the core entry, which works on any supported peer. The plugin's disclosure is off by default and shows once per address (`localStorage`, with an in-memory fallback). Only the `./plugins/passkey` entry imports `useWalletManager` (React/Vue 5.2+); never import it from the main entry. The adapter is typed structurally (`PasskeyWalletAdapter`); `@txnlab/use-wallet-passkey` is a devDependency only, for tests and examples. Call `connect`/`unlock`/`exportRecoveryPhrase` before any `await` in click handlers (iOS drops the tap).
- use-wallet v5 configures wallets with adapter factories (`pera()`, `defly()`, …) from separate packages, not the `WalletId` enum.
- Uses `@tanstack/react-query` / `@tanstack/vue-query` for data fetching (NFD, account info)
- Uses `@floating-ui/*` and `@headlessui/*` for dropdowns/dialogs
Expand All @@ -80,6 +84,7 @@ cd examples/vue && pnpm dev # Vue example
### Styling System

The library has dual styling support:

1. **Tailwind CSS** - Components use Tailwind utility classes
2. **Standalone CSS** - Pre-built CSS via `dist/style.css` scoped with `[data-wallet-ui]` attribute

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ jobs:
run: pnpm --filter @txnlab/use-wallet-ui-e2e e2e:validate

- name: Run E2E tests
run: pnpm --filter @txnlab/use-wallet-ui-e2e e2e --project=chromium --project=customization --project=vue-chromium
run: pnpm --filter @txnlab/use-wallet-ui-e2e e2e --project=chromium --project=customization --project=vue-chromium --project=passkey-react --project=passkey-vue

- name: Upload Playwright report
uses: actions/upload-artifact@v6
Expand Down
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,10 @@ See the package documentation for full API references and customization guides:
| [react](./examples/react) | Tailwind CSS integration |
| [react-css-only](./examples/react-css-only) | Standalone CSS usage |
| [react-custom](./examples/react-custom) | All customization patterns |
| [react-web3auth](./examples/react-web3auth) | Web3Auth + export-key plugin |
| [react-passkey](./examples/react-passkey) | Passkey wallet + plugin |
| [vue](./examples/vue) | Vue 3 + Tailwind integration |
| [vue-passkey](./examples/vue-passkey) | Vue passkey wallet + plugin |

## Development

Expand Down
7 changes: 4 additions & 3 deletions e2e/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,8 @@ e2e/
│ └── vue/ # Mirrored Vue tests
│ ├── theme/
│ └── visual/
├── fixtures/ # Test fixtures and utilities
│ └── passkey/ # Passkey flows (React and Vue passkey examples)
├── fixtures/ # Test fixtures and utilities (passkey.ts: virtual authenticator)
├── scripts/ # Helper scripts
│ ├── run-e2e-docker.sh
│ └── update-snapshots.sh
Expand All @@ -96,8 +97,8 @@ e2e/

The Playwright configuration (`playwright.config.ts`) includes:

- **Projects**: React (`chromium`, `chromium-dark`, `firefox`, `webkit`, `customization`) and Vue (`vue-chromium`, `vue-chromium-dark`, `vue-firefox`, `vue-webkit`)
- **Web Server**: Automatically starts React (5173), React custom (5174), and Vue (5175) example apps
- **Projects**: React (`chromium`, `chromium-dark`, `firefox`, `webkit`, `customization`), Vue (`vue-chromium`, `vue-chromium-dark`, `vue-firefox`, `vue-webkit`), and passkey (`passkey-react`, `passkey-vue`; Chromium only, using its virtual authenticator with PRF over CDP)
- **Web Server**: Automatically starts React (5173), React custom (5174), Vue (5175), React passkey (5176), and Vue passkey (5177) example apps
- **Visual Comparison**: 5% pixel difference tolerance for font rendering variations
- **Retries**: 2 retries in CI, none locally

Expand Down
72 changes: 72 additions & 0 deletions e2e/fixtures/passkey.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
import { test as base, type CDPSession, type Page } from '@playwright/test'

type AuthenticatorOptions = {
hasPrf?: boolean
isUserVerified?: boolean
/** false keeps passkey prompts open, to see the pending state */
automaticPresenceSimulation?: boolean
}

export interface VirtualAuthenticator {
client: CDPSession
authenticatorId: string
}

/**
* Adds a Chromium virtual authenticator with the PRF extension, so passkey
* prompts resolve without UI. Passkeys work on localhost in Chrome.
*/
export async function addVirtualAuthenticator(
page: Page,
{
hasPrf = true,
isUserVerified = true,
automaticPresenceSimulation = true,
}: AuthenticatorOptions = {},
): Promise<VirtualAuthenticator> {
const client = await page.context().newCDPSession(page)
await client.send('WebAuthn.enable')
const { authenticatorId } = await client.send(
'WebAuthn.addVirtualAuthenticator',
{
options: {
protocol: 'ctap2',
ctap2Version: 'ctap2_1',
transport: 'internal',
hasResidentKey: true,
hasUserVerification: true,
isUserVerified,
hasPrf,
automaticPresenceSimulation,
},
},
)
return { client, authenticatorId }
}

export const test = base.extend<{ pageErrors: Error[] }>({
// Collect uncaught page errors so each test can assert there were none.
// `auto` attaches the listener before the test body runs.
pageErrors: [
async ({ page }, use) => {
const errors: Error[] = []
page.on('pageerror', (error) => errors.push(error))
await use(errors)
},
{ auto: true },
],

page: async ({ page }, use) => {
// Keep NFD lookups off the network: passkey accounts are new and have none
await page.route(/api(\.testnet)?\.nf\.domains/, (route) =>
route.fulfill({
status: 404,
contentType: 'application/json',
body: '{}',
}),
)
await use(page)
},
})

export { expect } from '@playwright/test'
57 changes: 53 additions & 4 deletions e2e/playwright.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,11 @@ export default defineConfig({
// Desktop Chrome - Light Mode (default)
{
name: 'chromium',
testIgnore: [/customization\/.+\.spec\.ts/, /vue\/.+\.spec\.ts/],
testIgnore: [
/customization\/.+\.spec\.ts/,
/vue\/.+\.spec\.ts/,
/passkey\/.+\.spec\.ts/,
],
use: {
...devices['Desktop Chrome'],
},
Expand All @@ -72,7 +76,11 @@ export default defineConfig({
// Desktop Chrome - Dark Mode (system preference)
{
name: 'chromium-dark',
testIgnore: [/customization\/.+\.spec\.ts/, /vue\/.+\.spec\.ts/],
testIgnore: [
/customization\/.+\.spec\.ts/,
/vue\/.+\.spec\.ts/,
/passkey\/.+\.spec\.ts/,
],
use: {
...devices['Desktop Chrome'],
colorScheme: 'dark',
Expand All @@ -82,7 +90,11 @@ export default defineConfig({
// Desktop Firefox
{
name: 'firefox',
testIgnore: [/customization\/.+\.spec\.ts/, /vue\/.+\.spec\.ts/],
testIgnore: [
/customization\/.+\.spec\.ts/,
/vue\/.+\.spec\.ts/,
/passkey\/.+\.spec\.ts/,
],
use: {
...devices['Desktop Firefox'],
},
Expand All @@ -91,7 +103,11 @@ export default defineConfig({
// Desktop Safari
{
name: 'webkit',
testIgnore: [/customization\/.+\.spec\.ts/, /vue\/.+\.spec\.ts/],
testIgnore: [
/customization\/.+\.spec\.ts/,
/vue\/.+\.spec\.ts/,
/passkey\/.+\.spec\.ts/,
],
use: {
...devices['Desktop Safari'],
},
Expand Down Expand Up @@ -132,6 +148,25 @@ export default defineConfig({
},
},

// Passkey tests - run against the passkey examples with Chromium's
// virtual authenticator (WebAuthn over CDP), so Chromium only
{
name: 'passkey-react',
testMatch: /passkey\/.+\.spec\.ts/,
use: {
...devices['Desktop Chrome'],
baseURL: 'http://localhost:5176',
},
},
{
name: 'passkey-vue',
testMatch: /passkey\/.+\.spec\.ts/,
use: {
...devices['Desktop Chrome'],
baseURL: 'http://localhost:5177',
},
},

// Customization tests - runs against react-custom example
// This project tests CSS customization patterns (not run by default in CI)
{
Expand Down Expand Up @@ -167,5 +202,19 @@ export default defineConfig({
timeout: 120000,
cwd: '..',
},
{
command: 'pnpm --filter @txnlab/use-wallet-ui-react-passkey-example dev',
url: 'http://localhost:5176',
reuseExistingServer: !CI,
timeout: 120000,
cwd: '..',
},
{
command: 'pnpm --filter @txnlab/use-wallet-ui-vue-passkey-example dev',
url: 'http://localhost:5177',
reuseExistingServer: !CI,
timeout: 120000,
cwd: '..',
},
],
})
Loading
Loading