Document Details
Statement details with reconciliation, buffered transaction edits, and PDF or image preview. Other document types render the not-available state.
Anatomy
Import the primitive and compose the parts you need.
<DocumentDetails.Root documentId={documentId} onBack={onBack}> <DocumentDetails.Surface> <DocumentDetails.Loading>Loading…</DocumentDetails.Loading> <DocumentDetails.Error> <DocumentDetails.ErrorMessage /> <DocumentDetails.Retry /> </DocumentDetails.Error> <DocumentDetails.Back /> <DocumentDetails.NotAvailable><DocumentDetails.NotAvailableMessage /></DocumentDetails.NotAvailable> <DocumentDetails.Ready> <DocumentDetails.Title /> <DocumentDetails.CreatedDate /> <DocumentDetails.Type /> <DocumentDetails.Status /> <DocumentDetails.Processing><DocumentDetails.ProcessingMessage /></DocumentDetails.Processing> <DocumentDetails.AllSet><DocumentDetails.BannerTitle /><DocumentDetails.BannerDescription /></DocumentDetails.AllSet> <DocumentDetails.NeedsLook><DocumentDetails.BannerTitle /><DocumentDetails.BannerDescription /></DocumentDetails.NeedsLook> <DocumentDetails.AccountUnmatched>{/* AccountSelect + AccountOptions */}</DocumentDetails.AccountUnmatched> <DocumentDetails.Reconciliation> <DocumentDetails.Difference /> <DocumentDetails.ReadOnly><DocumentDetails.BeginningBalance /></DocumentDetails.ReadOnly> <DocumentDetails.Editing><DocumentDetails.BeginningBalanceInput /></DocumentDetails.Editing> <DocumentDetails.TransactionsToggle /> <DocumentDetails.Rows> <DocumentDetails.Row> <DocumentDetails.ReadOnly> <DocumentDetails.RowDate /><DocumentDetails.RowDescription /><DocumentDetails.RowAmount /> </DocumentDetails.ReadOnly> <DocumentDetails.Editing> <DocumentDetails.RowDateInput /><DocumentDetails.RowDescriptionInput /> <DocumentDetails.RowAmountInput /><DocumentDetails.Delete /> </DocumentDetails.Editing> </DocumentDetails.Row> </DocumentDetails.Rows> <DocumentDetails.Editing><DocumentDetails.AddTransaction /></DocumentDetails.Editing> <DocumentDetails.TransactionsTotal /> <DocumentDetails.ReadOnly><DocumentDetails.EndingBalance /><DocumentDetails.Edit /></DocumentDetails.ReadOnly> <DocumentDetails.Editing> <DocumentDetails.EndingBalanceInput /><DocumentDetails.Cancel /><DocumentDetails.Save /> </DocumentDetails.Editing> <DocumentDetails.SaveErrorMessage /> </DocumentDetails.Reconciliation> <DocumentDetails.PreviewImage><DocumentDetails.ZoomSurface> <DocumentDetails.Url asChild><img alt="Statement" /></DocumentDetails.Url> </DocumentDetails.ZoomSurface></DocumentDetails.PreviewImage> <DocumentDetails.PreviewPdf>{/* Url supplies src + scale to your PDF renderer */}</DocumentDetails.PreviewPdf> <DocumentDetails.PreviewZoomable><DocumentDetails.ZoomOut /><DocumentDetails.ZoomIn /></DocumentDetails.PreviewZoomable> <DocumentDetails.OpenOriginal>Open original</DocumentDetails.OpenOriginal> </DocumentDetails.Ready> </DocumentDetails.Surface></DocumentDetails.Root>Required scopes
The access token used by AssetProvider must include these scopes for this primitive to fetch data successfully:
document:readdocument:updateexternal_account:readledger:readjournal_entry:readjournal_entry:createjournal_entry:updatejournal_entry:deletetransaction:readtransaction:updatetransaction:delete
API reference
Root props
| Prop | Type | Default | Description |
|---|---|---|---|
documentIdrequired | string | — | The document to load. Changing it discards the previous document's edit session. |
onBack | () => void | — | Called by Back to documents. The host owns navigation. |
formatAmount | (amount: number) => string | — | Money formatter for balances, transactions, and banner amounts. Defaults to USD with two decimals. |
formatDate | (date: string) => string | — | Formats displayed dates, including the styled edit-mode date field. Input values retain YYYY-MM-DD calendar dates. |
document | DocumentPublic | — | Offline document override. Disables all network reads and server writes. Balances come from metadata_.statement_starting_balance and metadata_.statement_closing_balance. |
rows | JournalEntryEacPublic[] | — | Overrides journal entries, including their line_entries. Otherwise every page is fetched using document_id. Supply accounts and ledgers with offline rows to derive signed amounts. |
transactions | TransactionPublic[] | — | Overrides backing transaction reads. Their amounts establish the sign convention for transaction-backed row edits. Otherwise fetched by transaction_id; document overrides keep these reads offline too. |
accounts | ExternalAccountPublic[] | — | Overrides external accounts for the immediate-save picker and the statement account's ledger_id. |
ledgers | LedgerPublic[] | — | Overrides ledger lookup. Its debit_credit determines the signed statement amount. New rows prefer fallbackLedgerId, then look up Uncategorized Inflow or Uncategorized Outflow by name. |
fallbackLedgerId | string | — | Host-provided offset ledger ID for new rows, for either amount direction. Takes precedence over the legacy Uncategorized Inflow/Outflow name lookup. LedgerPublic has no unique uncategorized-ledger marker. If neither resolves, Save is disabled with the standard save error until the offset is available or the new row is removed. |
previewUrl | string | null | — | Overrides the signed URL request; null explicitly supplies no URL. The file extension is always read from document.name. |
state | "loading" | "error" | — | Forces a display state and disables network reads. |
onSave | (draft: DocumentDetailsDraft) => void | Promise<void> | — | Replaces statement server writes. Useful for offline demos. Reject to show the save error; the raw cause remains attached to the error. |
onSelectAccount | (id: string) => void | Promise<void> | — | Replaces the immediate account-association write. Account selection is separate from the edit buffer. |
childrenrequired | ReactNode | — | Compound parts. |
Parts
Container and state
| Part | Description |
|---|---|
Root | Owns reads, the edit buffer, sequential writes, and preview state. |
SurfaceasChild? | Wrapper carrying data-screen, data-saving, and aria-busy for layout and locking feedback. |
Loading | Children while document, account, ledgers, or journal pages load. |
Error | Children when a required read fails. |
ErrorMessageasChild?, format? | Standard load error. format receives Error | null. |
RetryasChild? | Refetches enabled reads. |
Ready | Children after all required reads succeed for an available document. |
Processing | Children while an eligible statement is processing, inside Ready. |
ProcessingMessageasChild? | Processing this statement… |
NotAvailable | Children for unsupported types or statements with an unavailable status. |
NotAvailableMessageasChild? | This document doesn't have a detail view yet. |
useDocumentDetails() | Context hook. Throws outside Root. Prefer slots when composing UI. |
Header and banners
| Part | Description |
|---|---|
BackasChild? | Back to documents; calls onBack. |
TitleasChild? | Statement description falling back to the file name. |
CreatedDateasChild?, format? | Created date; format receives the raw ISO date. |
TypeasChild? | Document type label. |
StatusasChild? | Uses the Documents status mapping and data-status tone. |
AllSet | Banner gate when the difference is zero and the account is matched. |
NeedsLook | Banner gate for a nonzero difference. |
AccountUnmatched | Banner gate for failure_code failed_account_matching. |
BannerTitleasChild? | Title of the active banner. |
BannerDescriptionasChild? | Explains the active banner. A nonzero difference uses a positive amount and more or less. |
AccountHintasChild? | Explains that missing accounts may need to be added from Accounts. |
AccountSelectchildren: ReactElement | Binds value, disabled, and onValueChange to a select child. Saves immediately and refetches the document. |
AccountOptions | Repeats children for each external account. |
AccountOptionasChild? | Supplies an option's value and account label, including mask. |
AccountErrorMessageasChild?, format? | Immediate account-save error with its original cause. |
AccountRetryasChild? | Retries the last account selection after a failure. |
Reconciliation and editing
| Part | Description |
|---|---|
Reconciliation | Children when the statement is not processing, including unmatched accounts. |
DifferenceasChild?, format? | Numeric value from the current buffer; format receives the unformatted number. |
BeginningBalanceasChild?, format? | Numeric value from the current buffer; format receives the unformatted number. |
EndingBalanceasChild?, format? | Numeric value from the current buffer; format receives the unformatted number. |
TransactionsTotalasChild?, format? | Numeric value from the current buffer; format receives the unformatted number. |
BeginningBalanceInputasChild?, input props | Signed money input. Sanitizes on change, formats on blur, and locks during a save. |
EndingBalanceInputasChild?, input props | Signed money input. Sanitizes on change, formats on blur, and locks during a save. |
TransactionsToggleasChild? | Transactions (n) button with aria-expanded; opens or collapses rows. |
TransactionsCountasChild? | Current buffered row count. |
Rows | Repeats children with row context while expanded. |
RowasChild? | Row wrapper with data-row-id. |
RowDateasChild?, format? | Date display; format receives the calendar date string. |
RowDescriptionasChild? | Buffered transaction description. |
RowAmountasChild?, format? | Signed account-ledger amount. Credit-normal ledgers reverse the debit/credit sign. |
RowDateInputasChild?, input props | Input for the current row's buffered value. RowDateInput passes the Root formatDate as format to an asChild date field. RowAmountInput sanitizes signed money. |
RowDescriptionInputasChild?, input props | Input for the current row's buffered value. RowDateInput passes the Root formatDate as format to an asChild date field. RowAmountInput sanitizes signed money. |
RowAmountInputasChild?, input props | Input for the current row's buffered value. RowDateInput passes the Root formatDate as format to an asChild date field. RowAmountInput sanitizes signed money. |
DeleteasChild? | Removes the row from the buffer; no immediate request. |
AddTransactionasChild? | Appends a blank buffered row. |
Editing | Children while the local edit buffer is open. |
ReadOnly | Children outside edit mode. |
EditasChild? | Starts editing a snapshot of the statement. |
CancelasChild? | Discards unsaved changes and exits. Already completed writes are not undone. |
SaveasChild? | Disabled until valid and dirty. Saves balances, one transaction-update batch, manual journal entry patches, one transaction-delete batch, manual journal entry deletes, then additions. Stops on the first failure and retries only remaining writes. |
SaveErrorMessageasChild?, format? | We couldn't save your changes. Try again. format receives the error with the raw cause attached. |
Preview
| Part | Description |
|---|---|
PreviewLoading | Children while the signed URL loads. |
PreviewError | Children when the signed URL request fails. |
PreviewErrorMessageasChild?, format? | Failed to load document preview. Try refreshing or downloading. |
PreviewRetryasChild? | Refetches the signed URL. |
PreviewPdf | Children for a PDF with a resolved URL. The SDK does not import a PDF renderer. |
PreviewImage | Children for jpg, jpeg, or png with a resolved URL. |
PreviewUnsupported | Children for any other file extension. |
PreviewUnsupportedMessageasChild? | Preview not available for this file type. |
PreviewZoomable | Children for a loaded PDF or image. |
UrlasChild? | Supplies src and scale to its child renderer; without asChild renders data-url and data-zoom. |
ZoomSurfaceasChild? | Width-based image zoom wrapper with data-zoom. |
ZoomOutasChild? | Decreases zoom by 0.25, stopping at 0.5. |
ZoomInasChild? | Increases zoom by 0.25, stopping at 3. |
OpenOriginalasChild? | Safe new-tab link to the signed URL. |
ShowPreviewasChild? | Sets Surface's data-screen to preview. |
ShowDetailsasChild? | Sets Surface's data-screen to details. |
Saving and permissions
The statement form locks during saves. After a partial save, the remaining batch stays fixed until Save retries it or Cancel discards it. Completed writes remain saved. Account selection saves independently and may return the document to Processing, which preserves the header and preview and shows Processing this statement… without footer actions.
Date, description, and amount are editable on every row. Rows with a transaction_id use the transaction update and delete routes; manual rows use journal entry routes. The edited amount preserves the sign relationship between the original displayed amount and the backing transaction amount. Transaction amount changes rebuild journal entries asynchronously, so the post-save refetch may briefly show the old amount or omit an entry while it is rebuilt. When rows are missing after an amount save, they refresh every 1.5 seconds until every updated transaction has a row, for up to 30 seconds. Recovery stops silently at the cap or when this document closes. Processing documents refresh every 2 seconds until their status changes.
DocumentDetails.scopes lists all required permissions, including external_account:read, ledger:read, and transaction:read for account choices, ledger lookup, and backing transaction amounts. The SDK and styled component require the same scopes.