dolfindevelopers

Bill match panel

ComponentPayablesSDK + UI

Three-way match blocks: BillMatchPanel (the bill page's card with each line's variance badges, matched documents, suggestions, resolve actions, linking a purchase order and matching by hand, with loading, empty and error states; by bill id it fetches and wires every action, Approve included where the bill's state offers it (asking first; hideApprove leaves it out), given a match it fetches nothing and shows a button per callback passed, with per-line progress (`pendingId`), the running write (`pendingAction`, which keeps every write button waiting) and errors), plus the workspace blocks MatchHeader, MatchDocumentCards, MatchLinesTable (ordered, billed and received per line with totals) and MatchSummaryCard.

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

Choose your integration

Ready to connect to Dolfin. Loads data through SDK hooks, with appearance and behaviour you can customise. Requires DolfinProvider.

Loading preview…

Installation

Needs the Dolfin registry token. The CLI copies the source into your app.

Terminal
bunx --bun shadcn@4.23.0 add @dolfin/ap-bill-match-panel

Also installs: button, card, popover, ap-match-line, ap-link-po-dialog, base-info-hint, base-page, base-states, base-status-badge, ui-ap-bill-match-panel.

Usage

screen.tsx
import { BillMatchPanel } from "@/components/dolfin/ap/bill-match-panel";

// Place it anywhere inside your <DolfinProvider>.
<BillMatchPanel />

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

PropTypeDescription
billIdstringFetches the bill's match and wires every action. Also where "Open match workspace" leads.
matchMatchGroupModelYour match, e.g. `useMatchGroup(billId).match`. Passing `match`, `loading` or `error` means nothing is fetched; `null` is the "no match yet" state. Buttons then show only for the callbacks you pass. Given with `billId`, the match wins.
loadingboolean
errorError
onRetry() => voidShows "Try again" in the error state.
currencystringDefaults to the bill's own currency (by id).
editablebooleanBy id: whether the match can change. Defaults to whether the bill is still in review.
onConfirmLine(lineId: string, pick: MatchLinePick) => voidConfirm one of a line's suggestions. By id, each `onX` you pass replaces the SDK's own handler.
onResolveLine(lineId: string, action: MatchLineResolveAction) => voidAccept a line's variance, or ask the supplier for a credit note.
onDisputeLine(lineId: string) => void
onUndoLine(lineId: string) => voidTake back the decision recorded on a line.
onUnlinkLine(lineId: string, allocationId: string) => voidRemove one of a line's matched documents.
onMatchLineManually(line: MatchLineModel) => voidShows "Match manually" on the lines that can take one; open your matching dialog.
onLinkPurchaseOrder() => voidShows "Link purchase order"; open your linking dialog.
onApprove() => voidShows "Approve" in the header. By id the SDK wires it where the bill's state offers approval, and its own asks first; yours replaces it, confirmation included, and runs at once.
approveDisabledReasonstringA non-empty reason disables Approve and says why. By id, the reason comes from the user's role and the match.
hideApprovebooleanHides Approve (for a page that shows the bill's own actions beside the panel).
pendingIdstringThe line a write is running on: it shows progress.
pendingActionBillMatchPanelActionThe write running now, with or without a line (linking an order, removing a document, re-running the match, approving). While `pendingId` or `pendingAction` is set, every write button waits.
errorsReadonly<Record<string, string>>Why the last write failed, per bill line id, shown on that line.
onOpenMatchUi() => voidReplaces the "Open match workspace" link (which goes to the `ap.billMatch` route).
hideWorkspaceLinkbooleanHide the link to the match workspace.
hideLinkingbooleanBy id: hide "Link purchase order" and "Match manually".
headerActionsstring | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.Re…Extra header buttons.
childrenstring | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.Re…Rendered inside the card after the lines (your dialogs, a note).
classNamestring

Customisation

Without editing the source, you can change:

Class names
className
Messages
ap.bill.actionsap.matchbase.infoHint.moreAboutbase.states.retry

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.

useBilluseBillActionsuseBillPermissionsuseDolfinLocaleuseMatchGroupuseMatchLineCommandsuseMessagesusePermissions

Files

Written to your app by the install command:

  • components/dolfin/ap/bill-match-panel.tsx 303 lines
  • components/dolfin/ap/match-overview.tsx 187 lines
  • components/dolfin/ap/match-lines-table.tsx 104 lines