Gmail connections panel
Bills from Gmail: Connect a mailbox, the connected mailboxes with their status, Sync, Backfill and Disconnect (asking first), and the selected mailbox's attachments that look like bills, filtered by state and paged, to Import (they become bills) or Dismiss. By default it runs the useGmail hooks and handles the return from Google; or pass your own connections or candidates (either selects data mode and fetches nothing).
Component: A piece you place inside your own screens: a table, a form, a card or a dialog. You decide the layout around it. Pages vs components
Ready to connect to Dolfin. Loads data through SDK hooks, with appearance and behaviour you can customise. Requires DolfinProvider.
Installation
Needs the Dolfin registry token. The CLI copies the source into your app.
bunx --bun shadcn@4.23.0 add @dolfin/ap-gmail-connections-panelAlso installs: button, popover, base-info-hint, base-states, base-status-badge, base-theme, ui-ap-gmail-connections-panel.
Usage
import { GmailConnectionsPanel } from "@/components/dolfin/ap/gmail-connections-panel";
// Place it anywhere inside your <DolfinProvider>.
<GmailConnectionsPanel />Renders inside DolfinProvider (set it up once). By default it loads its own data through the SDK. Supplied-data examples show how to override that behavior.
API reference
| Prop | Type | Description |
|---|---|---|
connections | readonly { id: string; emailAddress: string; status: components["schemas"]["GmailConnectionStatus"]; lastSyncedAt?: null | string; backfille… | Your mailboxes. The panel's data is `connections` and `candidates`: passing either (or their `loading` or `error`) fetches nothing, and buttons show only with their callbacks. |
loading | boolean | |
error | Error | |
onRetry | () => void | |
candidates | readonly { id: string; gmailConnectionId: string; messageInternalDate: string; senderEmail?: null | string; subject?: null | string; fileNam… | The selected mailbox's attachments. Passing them selects data mode too; without them, the attachments list hides. |
candidatesLoading | boolean | |
candidatesError | Error | |
onCandidatesRetry | () => void | |
selectedConnectionId | string | The mailbox whose attachments show. Uncontrolled, the first mailbox until one is picked. |
onSelectConnection | (connectionId: string) => void | |
candidateState | "Candidate" | "Imported" | "Dismissed" | "Failed" | "Filtered" | "All" | Which attachments show. Uncontrolled, "To review" until another is picked. |
onCandidateStateChange | (state: GmailCandidateStateFilter) => void | |
page | number | Attachment paging (1-based). |
hasNextPage | boolean | |
onPageChange | (page: number) => void | |
onConnect | () => void | Shows Connect a mailbox. By default it sends the browser to Google and back to this page. |
connectDisabledReason | string | Yours wins (`""` = enabled); by id, `undefined` means the SDK's reason for the user's role. |
onSync | (connectionId: string) => void | |
onBackfill | (connectionId: string) => void | |
onDisconnect | (connectionId: string) => void | Shows Disconnect. By id the SDK's own asks first; yours replaces it, confirmation included, and runs at once. |
onImport | (candidateId: string) => void | |
onDismiss | (candidateId: string) => void | |
pendingId | string | The mailbox or attachment being worked on. |
pendingAction | GmailAction | |
notice | string | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.Re… | A message above the mailboxes, such as the outcome of connecting. By default, the return from Google. |
hideHeader | boolean | Hides the title, description and Connect button (for a page that has its own header). |
className | string |
Customisation
Without editing the source, you can change:
- Class names
className- Messages
ap.gmailbase.infoHint.moreAboutbase.states.retrybase.states.staleErrorcore.errors
Or edit the installed file directly: it is your code. See theming for colours and fonts.
Hooks
The SDK hooks this component uses. Use them directly from @dolfinai/react to build your own version.
useDolfinLocaleuseGmailActionsuseGmailCandidatesuseGmailConnectReturnuseGmailConnectionsuseMessagesusePermissionsFiles
Written to your app by the install command:
components/dolfin/ap/gmail-connections-panel.tsx202 linescomponents/dolfin/ap/gmail-panel-parts.tsx141 lines