ui-oauth-connection-card

Component contract

• provider: ProviderDef — { name, displayName, logoUrl, oauthAuthorizeUrl, oauthCallbackPath, sandboxAvailable }
• connectionState: "disconnected" | "connecting" | "connected" | "revoked" | "error" — controlled
• lastSuccessAt?: ISOString — surfaced as "Last successful sync: 2 hours ago"
• connectedAccount?: { displayName, externalId } — e.g., "Connected as alice@acme.com (org-id: 00D…)" — only when connected
• onConnect?: () => void — opens OAuth authorize URL in popup or redirect
• onDisconnect?: () => Promise — disconnect uses ui-destructive-confirmation
• onReconnect?: () => void — for revoked state; same as connect but copy differs
• fixture?: "sandbox" | "mock" | "live" — mirrors the consumer's usesIntegration.fixture; affects which OAuth URL is used (sandbox vs prod)
• auditLogPath?: string — when provided, shows "View audit log" link
• errorReason?: string — surfaced inline when state=error

Composition

• ui-status-pill — primary state display; uses registry kinds (connected / disconnected / syncing — for in-flight reconnect / failed for error)
• ui-destructive-confirmation — disconnect prompt
• ui-toast — success/failure notifications after connect/disconnect/reconnect
• ui-modal — when OAuth flow is popup-style (server returns to a callback that posts a message back to the parent window)

Interaction surface

1. Disconnected state.

   Card shows provider logo + name + "Not connected" status pill + "Connect" button. Clicking opens OAuth authorize URL.

2. Connecting state (in-flight OAuth).

   Status pill "Connecting…" with subtle pulse animation (respects prefers-reduced-motion). Connect button replaced by "Cancel" which closes the popup. If the popup is closed by user without completing, returns to disconnected.

3. Connected state.

   Card shows provider logo + connectedAccount.displayName + "Connected" status pill + "Disconnect" button + lastSuccessAt timestamp + audit-log link. Sandbox-mode connections have a small "Sandbox" badge.

4. Revoked state.

   Status pill "Revoked" (warning tone) + "Reconnect" button. Card shows when revocation was detected. Different from disconnected — preserves the previously-connected account info to make reconnection seamless.

5. Error state.

   Status pill "Error" (danger tone) + errorReason inline + "Retry" button + audit-log link to investigate. Distinct from revoked — error means transient or schema-drift, revoked means provider explicitly revoked our access.

6. Disconnect.

   Click Disconnect → ui-destructive-confirmation modal: "Disconnect from [provider]? Existing data syncs will stop." On confirm, onDisconnect() runs; on success, transitions to disconnected + toast "Disconnected from [provider]."

Failure modes

Accessibility

• Card is a <article> with aria-labelledby pointing at the provider name heading.
• Status changes announced via aria-live=polite (inherited from ui-status-pill).
• OAuth popup return announces "Connected to [provider]" via aria-live region.
• Disconnect modal inherits ui-destructive-confirmation a11y.
• Color contrast: provider logo placement ensures background contrast ≥ 4.5:1; status pill inherits its registry contrast.
• axe-clean ≥ serious across all states.

Stable test attributes

Agent test plan

- disconnected-state-shows-connect: connect button visible, others hidden
- connecting-state-shows-cancel: pulsing animation, cancel button visible
- connected-state-shows-account: displayName + lastSuccess + disconnect visible
- revoked-state-shows-reconnect: reconnect visible, account info preserved
- error-state-shows-reason-and-retry: errorReason visible, retry button visible
- sandbox-badge-only-when-sandbox: fixture=sandbox → badge visible
- popup-blocked-falls-back-to-redirect: stub popup blocked, redirect-flow used
- oauth-cancel-no-error: stub popup closed without callback, no error toast
- oauth-error-callback: stub error callback, state transitions to error
- revocation-detected-on-401: stub 401 invalid_token, state transitions to revoked
- reconnect-same-account-silent-success: stub same account on reconnect, no prompt
- reconnect-different-account-prompts: stub different account, prompt visible
- sandbox-prod-isolation: switch fixture, requires disconnect-reconnect
- disconnect-during-sync-warns: stub running sync, disconnect prompt has warning
- audit-log-link-permission-gated: stub no audit:read, link hidden
- connect-rate-limit: 6 clicks in 60s, 6th shows rate-limit message
- cross-tenant-state-forgery-404: forge state, callback 404
- schema-drift-graceful: stub null displayName, fallback "Connected (account info unavailable)"
- aria-live-status-announce: state change, aria-live announces transition
- color-contrast-status-pill: ≥ 4.5:1 inherited
- axe-clean-serious: across all states

Current consumers

Each consumer's usesIntegration envelope's fixture field maps directly to the card's fixture prop. The card centralizes the OAuth UX while the envelope centralizes the contract metadata. Together they form the integration surface contract.