@txnlab/use-wallet-ui-react 1.3.0 → 1.4.0

package/README.md

@@ -18,6 +18,7 @@ Ready-to-use React UI components for Algorand wallet integration, built as a com
 - [Hooks](#hooks)
 - [Tanstack Query Integration](#tanstack-query-integration)
 - [Plugins](#plugins)
+- [Passkey Wallet](#passkey-wallet)
 - [Migration from v0.x](#migration-from-v0x)
 - [License](#license)
 
@@ -322,6 +323,7 @@ Required wrapper that enables theming, NFD lookups, and data prefetching.
   enablePrefetching={true}    // Prefetch data for all wallet accounts
   prefetchNfdView="thumbnail" // NFD data view: 'tiny' | 'thumbnail' | 'brief' | 'full'
   queryClient={queryClient}   // Optional: your existing Tanstack Query client
+  passkeyLayout="list"        // Passkey wallet layout: 'list' | 'featured'
 >
   {children}
 </WalletUIProvider>
@@ -336,6 +338,7 @@ All-in-one wallet connection component.
   size="md"              // 'sm' | 'md' | 'lg'
   className="..."        // Additional CSS classes
   style={{...}}          // Inline styles (supports CSS variable overrides)
+  passkeyLayout="featured" // Optional: overrides WalletUIProvider's passkeyLayout
 />
 ```
 
@@ -356,6 +359,9 @@ Dropdown menu for wallet selection (disconnected state).
 <ConnectWalletMenu>
   <button>My Custom Button</button>
 </ConnectWalletMenu>
+
+// With its own passkey layout (overrides WalletUIProvider's passkeyLayout)
+<ConnectWalletMenu passkeyLayout="featured" />
 ```
 
 ### ConnectWalletButton
@@ -426,12 +432,31 @@ function Profile() {
 
 ### WalletList
 
-Renders a list of available wallets (used internally by ConnectWalletMenu).
+Renders a list of wallets (used internally by ConnectWalletMenu). The dialog renders the passkey wallet in its own section above the list, so pass the other wallets here.
+
+```jsx
+<WalletList
+  wallets={wallets}
+  handleWalletClick={(wallet) => wallet.connect()}
+/>
+```
+
+### PasskeyConnect
+
+The passkey section of the connect dialog, for custom connect menus. Signing in (**Continue with passkey**, or **Sign in with passkey** in the list layout) calls `handleWalletClick(wallet)`, and **Create a passkey** calls `handleWalletClick(wallet, { create: true })`. Forward `args` to `wallet.connect(args)` before any `await`, or Safari and iOS browsers drop the passkey prompt. Pass `status` (`{ walletId, pending, error }`) to disable the controls while the prompt is open and to show an error.
 
 ```jsx
-<WalletList onWalletSelected={() => closeMenu()} />
+<PasskeyConnect
+  wallet={passkeyWallet}
+  handleWalletClick={(wallet, args) => wallet.connect(args)}
+  layout="list"     // 'list' (default) | 'featured'
+  showLabel={true}  // 'list' only: show the "Passkey" group label
+/>
 ```
 
+In the list layout, label your own wallet group to match (the dialog uses "Wallets").
+
+
 ## Hooks
 
 ### useNfd
@@ -581,6 +606,74 @@ function App() {
 
 See the [Plugin Architecture Guide](PLUGINS.md) for full documentation.
 
+## Passkey Wallet
+
+[`@txnlab/use-wallet-passkey`](https://github.com/TxnLab/use-wallet/tree/main/packages/wallets/passkey#readme) (use-wallet 5.2+) derives an app-scoped Falcon-1024 account from a passkey. Register it, and the connect dialog shows a Passkey group with **Sign in with passkey** and **Create a passkey**, above your other wallets. The [`passkeyLayout`](#passkey-layout) option can lead with a **Continue with passkey** button instead. A missing passkey and a cancelled prompt raise the same browser error, so creating stays a separate choice.
+
+```bash
+npm install @txnlab/use-wallet-passkey
+```
+
+```tsx
+import { lute } from '@galaxypay/use-wallet-lute'
+import { pera } from '@perawallet/use-wallet-pera'
+import { passkey } from '@txnlab/use-wallet-passkey'
+import { WalletManager, WalletProvider } from '@txnlab/use-wallet-react'
+import { WalletButton, WalletUIProvider } from '@txnlab/use-wallet-ui-react'
+import { passkeyPlugin } from '@txnlab/use-wallet-ui-react/plugins/passkey'
+
+const manager = new WalletManager({
+  wallets: [passkey({ session: true }), lute(), pera()],
+})
+
+const plugins = [passkeyPlugin({ session: true })]
+
+function App() {
+  return (
+    <WalletProvider manager={manager}>
+      <WalletUIProvider plugins={plugins}>
+        <WalletButton />
+      </WalletUIProvider>
+    </WalletProvider>
+  )
+}
+```
+
+The connect dialog:
+
+- Starts the passkey prompt straight from the tap, as Safari and iOS browsers require
+- While the prompt is open, shows "Waiting for your passkey…" on the control the user pressed and dims the other
+- Stays open on passkey errors and explains them: a cancelled or timed-out prompt (or no passkey found), an in-app browser (open the page in Safari or Chrome), or a passkey provider without the PRF extension (try another provider)
+
+The connected wallet menu tags a passkey account with its domain (for example, `Passkey · localhost`), since the account belongs to the site that created it.
+
+`passkeyPlugin()` adds to the connected wallet menu, only while the passkey wallet is active:
+
+- **Back up account**: a dialog that reveals the account's 25-word recovery phrase after a fresh passkey prompt, and tells users to import it as a Falcon / quantum account (in Lute, Add account → Falcon25 account → Import; in Pera, the quantum import). It hides the phrase after a timeout and clears the clipboard when it closes, if it can.
+- **Session status** (with `session: true`): Locked or Unlocked, with Unlock and Lock buttons
+- **A note on whose account it is** (with `disclosure: true`): "This account is created by and for example.com. Keep only what you need here, and move larger amounts to a wallet you control." It shows until the user chooses **Got it**, once per account.
+
+The plugin uses `useWalletManager()`, so it requires `@txnlab/use-wallet-react` 5.2 or later, which any app with the passkey wallet has. The main entry still supports v4.6+. See [Passkey Plugin](PLUGINS.md#passkey-plugin) for options, and the adapter's [security model](https://github.com/TxnLab/use-wallet/tree/main/packages/wallets/passkey#security-model) before you ship it.
+
+For your own connect UI, `getPasskeyErrorMessage(error)` returns a message for a `PasskeyError`, or `null` for any other error.
+
+### Passkey layout
+
+Choose how the connect dialog presents the passkey wallet with `passkeyLayout`:
+
+- **`'list'`** (default): **Sign in with passkey** and **Create a passkey** rows in a "Passkey" group, above a "Wallets" group. For crypto-native apps where most users bring a wallet like Pera or Lute, and the passkey is one choice among many.
+- **`'featured'`**: a full-width **Continue with passkey** button and a "New here? **Create a passkey**" link, then the other wallets under "or connect a wallet". For consumer apps where most users have no wallet, so the passkey is the main way in.
+
+```tsx
+// App-wide
+<WalletUIProvider passkeyLayout="featured">
+
+// Per menu: a WalletButton or ConnectWalletMenu prop wins over the provider
+<WalletButton passkeyLayout="list" />
+```
+
+With only the passkey wallet configured, neither layout shows the other-wallets heading. Without a passkey wallet, the dialog is the same in both.
+
 ## License
 
 MIT

package/dist/cjs/chunks/passkey-C8Dw6sNL.cjs

@@ -0,0 +1,2 @@
+"use strict";const n="passkey";function a(e,s){return e??s??"list"}function i(e){return(e==null?void 0:e.id)===n}function t(e){if(!(e instanceof Error)||e.name!=="PasskeyError")return null;const{code:s}=e;return typeof s=="string"?s:null}function u(e){const s=t(e);if(!s)return null;switch(s){case"cancelled":return"The passkey request was cancelled or timed out, or no passkey was found.";case"unsupported":return"This browser can't use passkeys here. If you opened this page inside another app, open it in Safari or Chrome instead.";case"prf-unsupported":return"Your passkey provider doesn't support passkey accounts. Try a different provider, such as iCloud Keychain or Google Password Manager.";case"key-mismatch":return"This passkey belongs to a different account. Choose the passkey you used for this account.";default:return e.message||"The passkey request failed."}}function c(e){const r=(e==null?void 0:e.lastIndexOf(" · "))??-1;if(e&&r!==-1){const o=e.slice(r+3).trim();if(o)return o}return typeof location<"u"?location.hostname:""}exports.getPasskeyAccountDomain=c;exports.getPasskeyErrorCode=t;exports.getPasskeyErrorMessage=u;exports.isPasskeyWallet=i;exports.resolvePasskeyLayout=a;
+//# sourceMappingURL=passkey-C8Dw6sNL.cjs.map

package/dist/cjs/chunks/passkey-C8Dw6sNL.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"passkey-C8Dw6sNL.cjs","sources":["../../../src/utils/passkey.ts"],"sourcesContent":["/** The wallet id registered by `passkey()` from `@txnlab/use-wallet-passkey` */\nexport const PASSKEY_WALLET_ID = 'passkey'\n\n/**\n * The `PasskeyAdapter` members this library uses. Typed structurally so the\n * library needs no dependency on `@txnlab/use-wallet-passkey`.\n */\nexport interface PasskeyWalletAdapter {\n  /** True when the session key is unlocked */\n  readonly isUnlocked: boolean\n  /** Unlock the session with one passkey prompt */\n  unlock: () => Promise<void>\n  /** Drop the session key; the account stays connected */\n  lock: () => void\n  /** Return the account's recovery phrase after a fresh passkey prompt */\n  exportRecoveryPhrase: () => Promise<{ scheme: 'falcon-1024'; phrase: string }>\n}\n\n/** The status of a passkey connect request, shown under the passkey section */\nexport interface PasskeyConnectStatus {\n  walletId: string\n  pending: boolean\n  error: string | null\n  /** Which control started the request, so it can show the pending state */\n  action?: 'sign-in' | 'create'\n}\n\n/**\n * How the connect dialog presents a passkey wallet:\n * - `'list'` (default): \"Sign in with passkey\" and \"Create a passkey\" rows in\n *   a Passkey group above a Wallets group. Suits apps where most users bring\n *   a wallet.\n * - `'featured'`: a \"Continue with passkey\" button leads, with the other\n *   wallets below. Suits apps where most users have no wallet.\n */\nexport type PasskeyConnectLayout = 'featured' | 'list'\n\n/** A menu's own layout wins over the provider's; the default is `'list'` */\nexport function resolvePasskeyLayout(\n  menuLayout?: PasskeyConnectLayout,\n  providerLayout?: PasskeyConnectLayout,\n): PasskeyConnectLayout {\n  return menuLayout ?? providerLayout ?? 'list'\n}\n\n/** Arguments for connecting the passkey wallet */\nexport interface PasskeyConnectArgs {\n  /** Create a new passkey (and account) instead of signing in */\n  create?: boolean\n}\n\nexport function isPasskeyWallet(\n  wallet: { id: string } | null | undefined,\n): boolean {\n  return wallet?.id === PASSKEY_WALLET_ID\n}\n\n/** Returns a `PasskeyError`'s code, or null for any other error */\nexport function getPasskeyErrorCode(error: unknown): string | null {\n  if (!(error instanceof Error) || error.name !== 'PasskeyError') return null\n  const { code } = error as Error & { code?: unknown }\n  return typeof code === 'string' ? code : null\n}\n\n/**\n * Returns a message to show users for a `PasskeyError`, or null for any other\n * error.\n */\nexport function getPasskeyErrorMessage(error: unknown): string | null {\n  const code = getPasskeyErrorCode(error)\n  if (!code) return null\n\n  switch (code) {\n    case 'cancelled':\n      return 'The passkey request was cancelled or timed out, or no passkey was found.'\n    case 'unsupported':\n      return \"This browser can't use passkeys here. If you opened this page inside another app, open it in Safari or Chrome instead.\"\n    case 'prf-unsupported':\n      return \"Your passkey provider doesn't support passkey accounts. Try a different provider, such as iCloud Keychain or Google Password Manager.\"\n    case 'key-mismatch':\n      return 'This passkey belongs to a different account. Choose the passkey you used for this account.'\n    default:\n      return (error as Error).message || 'The passkey request failed.'\n  }\n}\n\n/**\n * The domain a passkey account belongs to. The adapter names the account\n * `Passkey · <domain>`; fall back to the page's hostname.\n */\nexport function getPasskeyAccountDomain(accountName?: string | null): string {\n  const separator = ' · '\n  const index = accountName?.lastIndexOf(separator) ?? -1\n  if (accountName && index !== -1) {\n    const domain = accountName.slice(index + separator.length).trim()\n    if (domain) return domain\n  }\n  return typeof location !== 'undefined' ? location.hostname : ''\n}\n"],"names":["PASSKEY_WALLET_ID","resolvePasskeyLayout","menuLayout","providerLayout","isPasskeyWallet","wallet","getPasskeyErrorCode","error","code","getPasskeyErrorMessage","getPasskeyAccountDomain","accountName","index","domain"],"mappings":"aACO,MAAMA,EAAoB,UAqC1B,SAASC,EACdC,EACAC,EACsB,CACtB,OAAOD,GAAcC,GAAkB,MACzC,CAQO,SAASC,EACdC,EACS,CACT,OAAOA,GAAA,YAAAA,EAAQ,MAAOL,CACxB,CAGO,SAASM,EAAoBC,EAA+B,CACjE,GAAI,EAAEA,aAAiB,QAAUA,EAAM,OAAS,eAAgB,OAAO,KACvE,KAAM,CAAE,KAAAC,GAASD,EACjB,OAAO,OAAOC,GAAS,SAAWA,EAAO,IAC3C,CAMO,SAASC,EAAuBF,EAA+B,CACpE,MAAMC,EAAOF,EAAoBC,CAAK,EACtC,GAAI,CAACC,EAAM,OAAO,KAElB,OAAQA,EAAA,CACN,IAAK,YACH,MAAO,2EACT,IAAK,cACH,MAAO,yHACT,IAAK,kBACH,MAAO,wIACT,IAAK,eACH,MAAO,6FACT,QACE,OAAQD,EAAgB,SAAW,6BAAA,CAEzC,CAMO,SAASG,EAAwBC,EAAqC,CAE3E,MAAMC,GAAQD,GAAA,YAAAA,EAAa,YAAY,SAAc,GACrD,GAAIA,GAAeC,IAAU,GAAI,CAC/B,MAAMC,EAASF,EAAY,MAAMC,EAAQ,CAAgB,EAAE,KAAA,EAC3D,GAAIC,EAAQ,OAAOA,CACrB,CACA,OAAO,OAAO,SAAa,IAAc,SAAS,SAAW,EAC/D"}