Chart of Accounts
Headless compound for the business's chart of accounts. It lists every ledger parent over child, ordered by sort code, under a type filter. CreateTrigger toggles a draft for a new top-level ledger, the way Add account reveals its panel. A click on a row opens its ledger's details in place, read-only (show them as text with DraftValue), and EditDetails turns them into the edit draft. EditTrigger opens the same draft ready to edit, AddChildTrigger opens it for a child that inherits from its parent, and DeleteTrigger asks for confirmation before it deletes. One thing is open at a time.
Anatomy
Import the primitive and compose the parts you need.
<ChartOfAccounts.Root // Optional. Without it there's no View report. onViewAccount={({ ledgerId }) => router.push(`/reports/ledger-statement/${ledgerId}`)}> {/* Header controls */} <ChartOfAccounts.TypeFilter> <Select> {/* any Select-Root-shaped child */} <ChartOfAccounts.TypeFilterItems> <ChartOfAccounts.TypeFilterItem /> </ChartOfAccounts.TypeFilterItems> </Select> </ChartOfAccounts.TypeFilter> <ChartOfAccounts.CreateTrigger /> {/* The create draft for a top-level ledger, revealed under the header */} <ChartOfAccounts.Create> <LedgerFields /> </ChartOfAccounts.Create> <ChartOfAccounts.ActionError /> <ChartOfAccounts.Loading>{/* skeleton rows */}</ChartOfAccounts.Loading> <ChartOfAccounts.Error> <ChartOfAccounts.ErrorMessage /> <ChartOfAccounts.Retry /> </ChartOfAccounts.Error> <ChartOfAccounts.Empty>{/* empty copy */}</ChartOfAccounts.Empty> <ChartOfAccounts.Success> <ChartOfAccounts.Rows> {/* Spread useRowProps() on the row for data-depth and data-open. */} <ChartOfAccounts.ChildMarker>{/* ↳ */}</ChartOfAccounts.ChildMarker> <ChartOfAccounts.SortCode /> <ChartOfAccounts.Name /> <ChartOfAccounts.Type /> <ChartOfAccounts.Subtype /> <ChartOfAccounts.TaxCategory /> <ChartOfAccounts.ViewAccountTrigger /> <ChartOfAccounts.EditTrigger /> <ChartOfAccounts.AddChildTrigger /> <ChartOfAccounts.DeleteTrigger /> {/* A click on the row opens its details read-only; the actions open it to act on its ledger. Gate the expansion on useRowExpanded(). One thing is open at a time. */} {/* Delete asks first, in the row it was chosen from (or use the root-level DeleteConfirm) */} <ChartOfAccounts.Deleting> <ChartOfAccounts.DeleteTargetName /> <ChartOfAccounts.CancelDelete /> <ChartOfAccounts.ConfirmDelete /> </ChartOfAccounts.Deleting> {/* The details show each field as text (DraftValue); EditDetails swaps them for the edit draft. An edit and a new child open the fields in the row. */} <ChartOfAccounts.Viewing> <ChartOfAccounts.DraftValue field="name" /> <ChartOfAccounts.DraftValue field="debitCredit" /> {/* …one per field */} <ChartOfAccounts.CancelDraft /> <ChartOfAccounts.EditDetails /> </ChartOfAccounts.Viewing> <ChartOfAccounts.Editing> <LedgerFields /> </ChartOfAccounts.Editing> <ChartOfAccounts.AddingChild> <LedgerFields /> </ChartOfAccounts.AddingChild> </ChartOfAccounts.Rows> </ChartOfAccounts.Success></ChartOfAccounts.Root>/* One set of fields serves create, add child and edit: */function LedgerFields() { return ( <> <ChartOfAccounts.SaveError /> <ChartOfAccounts.DraftIsChild> Sits under <ChartOfAccounts.DraftParentName /> </ChartOfAccounts.DraftIsChild> <ChartOfAccounts.DraftNameOnly> <ChartOfAccounts.DraftNameOnlyMessage /> </ChartOfAccounts.DraftNameOnly> <ChartOfAccounts.DraftName /> <ChartOfAccounts.DraftError field="name" /> <ChartOfAccounts.DraftSortCode /> <ChartOfAccounts.DraftError field="sortCode" /> <ChartOfAccounts.DraftType> <Select> <ChartOfAccounts.DraftTypeItems> <ChartOfAccounts.DraftTypeItem /> </ChartOfAccounts.DraftTypeItems> </Select> </ChartOfAccounts.DraftType> {/* DraftSubtype, DraftFinancialAccountType: same three-part shape */} <ChartOfAccounts.DraftIsEdit> <ChartOfAccounts.DraftDebitCredit>{/* … */}</ChartOfAccounts.DraftDebitCredit> </ChartOfAccounts.DraftIsEdit> <ChartOfAccounts.DraftSupportsTaxCategory> <ChartOfAccounts.DraftTaxCategory>{/* … */}</ChartOfAccounts.DraftTaxCategory> </ChartOfAccounts.DraftSupportsTaxCategory> <ChartOfAccounts.DraftDescription /> <ChartOfAccounts.DraftReportCashFlow /> <ChartOfAccounts.CancelDraft /> <ChartOfAccounts.Save /> </> )}Required scopes
The access token used by AssetProvider must include these scopes for this primitive to fetch data successfully:
ledger:readledger:createledger:updateledger:delete
API reference
Root props
| Prop | Type | Default | Description |
|---|---|---|---|
noun | string | "ledger" | What a ledger is called in the default copy ("Add ledger", "Delete ledger"). A household's chart might say "category". |
defaultTypeFilter | LedgerType | "all" | "all" | Initial type filter. The filter applies to top-level ledgers; a child is shown with its parent. |
defaultCreating | boolean | false | Open the create draft on mount. |
defaultEditingId | string | — | Open this ledger's edit draft once the chart has loaded — the deep link to editing one ledger. |
onViewAccount | (target: LedgerViewTarget) => void | — | Called with { ledgerId, type, subtype } when a row's View report is chosen. The host decides where it goes — see Viewing a ledger. Optional: without it ViewAccountTrigger renders nothing, so there is never a View report that goes nowhere. |
onCreated / onUpdated | (ledger: LedgerPublic) => void | — | Called with the ledger a create or an edit wrote, after the chart refetches — for a host's own confirmation. |
onDeleted | (ledgerId: string) => void | — | Called with the id of the ledger a delete removed. |
ledgers | LedgerOverride[] | — | Override the fetched ledgers (skips every request). Ordered and nested exactly as live data is, and adds, edits and deletes change a local copy — so a prototype or story works end to end without touching the API. A delete is refused while the ledger has children, or when it sets deletable: false, as the API refuses those. deletable: false makes it a system ledger, so an edit can change only its name. |
state | "loading" | "error" | "empty" | — | Force a specific state for testing. Skips every request. |
Parts
Container
Always rendered. Fetches the ledgers, builds the tree, owns the type filter, the draft, the delete confirmation and every write. A management surface rather than an entitled report, so it has no locked state.
| Part | Description |
|---|---|
ChartOfAccounts.Root | Owns fetching, the create/edit draft and the delete confirmation. |
Header controls
These read the root context rather than a row, so they keep working while the list is loading, empty or errored.
| Part | Description |
|---|---|
ChartOfAccounts.TypeFilter | Wires the type filter to a single Select-Root-shaped child (value is a LedgerType or "all"). A value it does not recognise is ignored. |
ChartOfAccounts.TypeFilterItems | Renders its children once per option — All types, then asset, liability, equity, revenue and expense. |
ChartOfAccounts.TypeFilterItemasChild? | One option — sets value and renders the label. |
ChartOfAccounts.CreateTriggerasChild? | Toggles a clean draft for a top-level ledger, and sets aria-expanded while it's open. Renders nothing without ledger:create. Default label "Add ledger" (the root's noun). |
ChartOfAccounts.ActionErrorasChild? | The last failed delete, in neutral copy: "This ledger can't be deleted." It never says why. Nothing when all is well. |
Rows
Renders inside Success, once per ledger, each parent followed by its children.
| Part | Description |
|---|---|
ChartOfAccounts.Success | State wrapper. |
ChartOfAccounts.Rows | Iterates the filtered chart, providing a per-row context. |
ChartOfAccounts.SortCode / Name / DescriptionasChild? | The ledger's own text. Each renders nothing when the ledger has none. |
ChartOfAccounts.TypeasChild? | The type as a label, with data-type for tone. |
ChartOfAccounts.Subtype / NormalBalance / FinancialAccountTypeasChild? | Wire enums as words — "Operating Expense", "Debit", "Bank Account". FinancialAccountType renders nothing when unset. |
ChartOfAccounts.TaxCategoryasChild? | The tax form's wording for the category ("Office expense"), or nothing when unset. |
ChartOfAccounts.ReportsCashFlowasChild? | Yes or No — whether the ledger is in the cash flow report. |
ChartOfAccounts.ChildMarker | Renders its children only on a child ledger — for the nested marker. |
ChartOfAccounts.useRowProps() | Spread onto the row element. The row is a button (role, tabIndex, aria-expanded): a click, or Enter or Space, opens the ledger's details read-only and a second closes them; it does nothing while the row is open for an edit, a new child or a delete, and ignores clicks on controls inside it. Also data-depth (0 top-level, 1 child, 2 grandchild, 3 great-grandchild), data-open while the row is open, and the depth as the --asset-row-depth style variable. |
ChartOfAccounts.useRowExpanded() | True while this row is open (edited, given a child, or confirmed for delete) — for an expand animation. |
Row actions
A host with actions of its own (moving line entries, say) renders them beside these in the row; each reads the row through useLedgerRow().
| Part | Description |
|---|---|
ChartOfAccounts.ViewAccountTriggerasChild? | Calls onViewAccount with the row's ledger id, type and subtype. Default label "View". Renders nothing without onViewAccount. |
ChartOfAccounts.EditTriggerasChild? | Opens the draft over this ledger, in its row, where Editing renders. Renders nothing without ledger:update. |
ChartOfAccounts.AddChildTriggerasChild? | Opens a create draft for a child of this ledger, in its row, where AddingChild renders. Renders nothing on a great-grandchild (a chart nests at most four levels: parent, child, grandchild and great-grandchild) or without ledger:create. |
ChartOfAccounts.DeleteTriggerasChild? | Asks to delete this ledger. Renders nothing without ledger:delete. On a system ledger (is_deletable: false) it stays in place but disabled (disabled, data-disabled); a ledger from an API that doesn't send the flag stays deletable. |
ChartOfAccounts.DeleteAvailable / DeleteUnavailable | Row-scoped: children when this ledger can be deleted, or when the token could delete but this ledger can't be — for wrapping the disabled Delete in a tooltip. |
ChartOfAccounts.DeleteUnavailableMessageasChild? | Why Delete is disabled on a system ledger: "System ledgers cannot be deleted" (with the chart's noun, e.g. "System categories"). |
ChartOfAccounts.DeleteConfirm | Children while a delete awaits confirmation — for asking at the top of the surface. |
ChartOfAccounts.Deleting | Row-scoped: children while this row's ledger awaits confirmation. DeleteTrigger also opens the row, so the question can sit in the row where Delete was chosen. |
ChartOfAccounts.DeleteTargetNameasChild? | The name of the ledger awaiting confirmation. |
ChartOfAccounts.ConfirmDelete / CancelDeleteasChild? | Deletes it ("Delete ledger", "Deleting…" in flight), or backs out. |
Draft
One set of fields serves create, add child and edit. Errors show once a field is touched or a save attempted.
| Part | Description |
|---|---|
ChartOfAccounts.Create | Children while a draft for a top-level ledger is open. |
ChartOfAccounts.Editing / AddingChild | Row-scoped: children while this row's ledger is being edited, or given a child. |
ChartOfAccounts.Viewing | Row-scoped: children while this row's ledger details are open read-only. The draft parts render the ledger with every field locked (text inputs readOnly, selects and the switch disabled) and Save hidden. Needs no write scope. |
ChartOfAccounts.DraftIsEdit | Children while the draft edits an existing ledger. |
ChartOfAccounts.DraftIsChild / DraftParentName | Children, and the parent's name, while the draft is for a child. |
ChartOfAccounts.DraftNameOnly / DraftNameOnlyMessage | Children, and the line "System ledgers can only be renamed.", while the draft edits a system ledger (is_deletable: false). Its other fields are locked (inputs disabled with data-locked, selects and the cash-flow switch disabled), only the name is validated, and Save sends the name alone. Other ledgers edit as usual. |
ChartOfAccounts.DraftName / DraftSortCode / DraftDescriptionasChild?, …input props | Controlled inputs. The sort code must be numeric; name and sort code are required. |
ChartOfAccounts.DraftType / DraftSubtype / DraftFinancialAccountType / DraftTaxCategory / DraftDebitCredit | Each wires a Select-Root-shaped child (value, onValueChange, disabled), with …Items and …Item parts for its options. Subtypes and tax categories follow the chosen type, and changing type drops one it no longer allows. The optional selects offer a None option (value LEDGER_NONE_VALUE). DraftDebitCredit (the normal balance) has the same shape and is only set by an edit — a new ledger takes its type's. |
ChartOfAccounts.DraftSupportsTaxCategory | Children when the chosen type carries a tax category — revenue and expense. |
ChartOfAccounts.DraftReportCashFlowasChild? | The cash-flow flag as a switch (role="switch", aria-checked, data-state). |
ChartOfAccounts.DraftErrorfield, asChild? | The problem with one field: name, sortCode, type, subtype or taxCategory. |
ChartOfAccounts.SaveErrorasChild? | The last failed create or update. |
ChartOfAccounts.Save / CancelDraftasChild? | Writes the draft ("Add ledger" or "Save") — disabled until it's valid, and on an edit until something has changed — or discards it ("Cancel", or "Close" on the details). Save renders nothing on the details. |
ChartOfAccounts.DraftValuefield, asChild? | One draft field as text, for read-only details: a chosen option's label, the text as typed, or "Yes" / "No" for reportCashFlow. An empty field reads "—" and carries data-empty. |
ChartOfAccounts.EditDetailsasChild? | Where an edit has Save, the details have Edit: it unlocks the fields in place. Renders nothing outside the details or without ledger:update. |
Loading / Error / Empty
| Part | Description |
|---|---|
ChartOfAccounts.Loading | While the list is first read. |
ChartOfAccounts.Error | When it couldn't be read. |
ChartOfAccounts.ErrorMessageasChild?, format? | Error copy. |
ChartOfAccounts.RetryasChild? | Refetches the list. |
ChartOfAccounts.Empty | When the business has no ledgers. |
Parents and children
Top-level ledgers are ordered by sort code (compared as numbers, so 6010 follows 6002), each followed by its children in the same order, at every depth the API holds. A chart nests at most four levels deep, so Add child is offered on every ledger down to grandchildren, not on great-grandchildren. A child whose parent isn't in the chart is listed as a top-level ledger rather than lost.
A child is its parent's kind of ledger: its type, subtype, financial account type and cash flow setting come from the parent and their draft fields are disabled. Its name, sort code, description and tax category are its own.
Viewing a ledger
The chart manages accounts and nothing else: no report, ledger table or transactions table renders inside it, and nothing else has to be embedded to use it. Viewing a ledger is the host's, through onViewAccount:
- Route to the Transactions component, filtered to the ledger's type and subtype.
- Read the ledger statement report from the API (“Retrieve the ledger statement report” in the General Ledger reference) with the business id and
ledgerId: every journal entry on that ledger. - Open a ledger page of the host's own.
Not here
Moving line entries from one ledger to another and bookkeeper notes are part of Asset's bookkeeping tools rather than the public API, so this compound leaves them out; a host with access adds them as its own row actions.