WalletLedger
"Where your money went": the wallet's entries grouped by challenge (native <details>, each with its signed total, a tone icon, its entries and why, then "Open the challenge →" or the top-up's proof), or one flat list; the balance at the end. Money out is red with a minus, money in green with a plus: the sign is always written.
import { WalletLedger } from '@ergasti/bricks';Examples
Wallet ledger
Entries grouped by challenge (each group opens and shows its total), or as one flat list; the group's challenge, a proof button and an export are callbacks.
Code
import { useState } from 'react';
import { MoneyNotesProvider, WalletLedger, useLanguage, type LedgerView } from '@ergasti/bricks';
import { blocksData, moneyNotes } from './sample-data';
function Ledger() {
const language = useLanguage();
const [view, setView] = useState<LedgerView>('grouped');
return (
<MoneyNotesProvider notes={moneyNotes(language)}>
<WalletLedger groups={blocksData.LEDGER(language, () => {})} balance="61840.00" view={view} onViewChange={setView} onExport={() => {}} />
</MoneyNotesProvider>
);
}Loading, error and empty
status draws the first two; an empty groups draws the empty state.
Code
import { WalletLedger } from '@ergasti/bricks';
function States() {
return (
<div style={{ display: 'grid', gap: 16 }}>
<WalletLedger groups={[]} balance="0.00" status="loading" />
<WalletLedger groups={[]} balance="0.00" status="error" error="We could not load the ledger." onRetry={() => {}} />
<WalletLedger groups={[]} balance="0.00" />
</div>
);
}Receipts and a footer
A group's proof can be a link (href) and a download (kind: 'download', "Download receipt"); footer sits under the entries (the flat view's pager); labels rename the grouping ("By type").
Code
import { MoneyNotesProvider, WalletLedger, useLanguage } from '@ergasti/bricks';
import { blocksData, moneyNotes } from './sample-data';
function ReceiptAndFooter() {
const language = useLanguage();
const groups = blocksData.LEDGER(language, () => {}).map((g) => (g.proof ? { ...g, proof: { context: g.proof.context, href: '#receipt', kind: 'download' as const } } : g));
return (
<MoneyNotesProvider notes={moneyNotes(language)}>
<WalletLedger groups={groups} balance="61840.00" view="flat" onViewChange={() => {}} labels={{ grouped: 'By type' }} footer={<small>Page 1 of 3</small>} />
</MoneyNotesProvider>
);
}Entries that open
onSelect on an entry makes the whole row one button (named by its label) that opens your entry drawer; proof adds a "Download receipt" link in the row (a bank top-up's transfer proof), its own target.
Code
import { MoneyNotesProvider, WalletLedger, useLanguage } from '@ergasti/bricks';
import { blocksData, moneyNotes } from './sample-data';
function ClickableEntries() {
const language = useLanguage();
const groups = blocksData.LEDGER(language, () => {}).map((g) => ({
...g, open: true,
entries: g.entries.map((e, i) => ({ ...e, onSelect: () => {}, ...(g.proof && i === 0 ? { proof: { context: g.proof.context, href: '#receipt' } } : {}) })),
}));
return (
<MoneyNotesProvider notes={moneyNotes(language)}>
<WalletLedger groups={groups} balance="61840.00" />
</MoneyNotesProvider>
);
}A receipt in a modal
An entry's proof with only onOpen reads "View receipt" and opens your receipt modal; with a safe href it reads "Download receipt" and saves the file (fileName names it). Use onOpen when the app shows receipts in place, href when it serves a file.
Code
import { useState } from 'react';
import { MoneyNotesProvider, WalletLedger, useLanguage } from '@ergasti/bricks';
import { blocksData, moneyNotes } from './sample-data';
function ReceiptInModal() {
const language = useLanguage();
const [opened, setOpened] = useState('');
const groups = blocksData.LEDGER(language, () => {}).map((g) => ({
...g, open: true,
entries: g.entries.map((e, i) => (g.proof && i === 0 ? { ...e, proof: { context: g.proof.context, onOpen: () => setOpened(g.proof!.context) } }
: g.proof && i === 1 ? { ...e, proof: { context: g.proof.context, href: '#receipt', fileName: 'receipt-88531.pdf' } } : e)),
}));
return (
<MoneyNotesProvider notes={moneyNotes(language)}>
<WalletLedger groups={groups} balance="61840.00" />
{opened && <p><small>Receipt opened: {opened}</small></p>}
</MoneyNotesProvider>
);
}Props
Prop
Type
Labels
Every word this component draws, in both languages. Override one per component and language with BricksProvider labels under the key walletLedger, or with the component's own prop where it has one. A {name} is a value the component fills in.
| Key | English | Arabic |
|---|---|---|
title | Where your money went | فلوسك راحت فين |
sub | Grouped by challenge. Open one to see each entry and why. | متقسّمة حسب التحدي. افتح أي واحد تشوف كل حركة وسببها. |
view | Show entries | اعرض الحركات |
grouped | By challenge | حسب التحدي |
flat | All entries | كل الحركات |
exportCsv | Export CSV | نزّل CSV |
openChallenge | Open the challenge → | افتح التحدي ← |
balance | Balance now | الرصيد دلوقتي |
empty | No wallet entries yet. | لسه مفيش حركات في المحفظة. |
Design guidance
How the BRICKS design system uses WalletLedger. Written in docs/content/components/WalletLedger.md; the props above are read from the code, which wins where the two disagree.
"Where your money went": the wallet's movements grouped by challenge in accordions (or one flat list), each group's signed total, the entries with their reason, and the balance at the end; use it on the Wallet tab under the balance and health cards.
It is the mock's walletGroups accordion card. Money out is red with a minus, money in green with a plus, and the sign is always written. Every group's total adds up to balance; the server computes all figures and the card only formats them through the money slots.
Anatomy
- Card header: title "Where your money went", sub "Grouped by challenge. Open one to see each entry and why.", and actions: a
Segmented"By challenge / All entries" (onViewChange) and a small "Export CSV" button (onExport). - Group (grouped view, native
<details class="kit-acc">): a 34px tone icon (flagfor money out,walletfor money in), the group name, the signed total (800 weight), the chevron. - Entries (
.kit-blk-line): bold label over a muted note ("15% of EGP 184,300 sales"), an optional proof link, the signed amount (tabular numbers, no currency by default). - Group footer line: "Open the challenge →" link button (
onOpenChallenge) or the group's proof ("View proof" / "Download receipt"). - Footer slot (
.kit-blk-ledger-foot): e.g. the flat view'sPager. - Balance line (
.kit-blk-balance): "Balance now" (aMoneyNoteterm) and the balance.
Variants
| Prop | Value | Look | Use when |
|---|---|---|---|
view | 'grouped' (default) | Accordions, one per group | The default, by challenge. |
view | 'flat' | One list; each entry's note is prefixed with its group name | The user picks "All entries". |
labels.grouped / labels.sub | e.g. "By type" | Relabels the grouping | Groups are entry types, not challenges (story ByType). |
LedgerGroup.tone | 'lime' | 'rasp' | 'butter' | 'sky' | 'lilac' | Icon tint | Pick per group (the mock: rasp, sky, butter for challenges; lime for top-ups). |
ProofLink.kind | 'view' / 'download' / 'receipt' | "View proof" / "Download receipt" / "View receipt" | Group proof defaults to 'view'; entry proof defaults to 'download' with a safe href, else 'receipt'. |
States
| State | How |
|---|---|
| Ready | status="ready" (default) with groups. |
| Loading | status="loading": skeleton rows, aria-busy, "Loading" for screen readers. |
| Error | status="error", error message, onRetry adds a "Try again" button (role="alert"). |
| Empty | groups=[]: "No wallet entries yet." (the footer and balance line are hidden with the entries). |
| Group open | LedgerGroup.open (the mock opens the first). |
| Clickable entry | LedgerEntry.onSelect: the whole row is one stretched button named by the label; row hover --row-hover. |
| Money in / out / zero | Total or amount starting with - is red; a non-zero positive is green; zero is ink. |
| Narrow card | A container query moves group totals under the name (indented 46px). |
Types
LedgerEntry: { id, label, note?, amount, onSelect?, proof? }. ProofLink: { context, href?, onOpen?, kind?, fileName? }; without a safe href or onOpen nothing is drawn.
LedgerGroup (groups): { id, name, tone, total, entries, onOpenChallenge?, proof?, open? }; total is a signed 2-dp string. LedgerView (view): 'grouped' | 'flat'. BlockStatus (status): 'ready' | 'loading' | 'error'.
WalletLedgerCopy (labels): title, sub, view, grouped, flat, exportCsv, openChallenge, balance, empty.
Usage
const groups: LedgerGroup[] = [
{ id: 'wg', name: 'Winter glow launch', tone: 'rasp', total: '-102760.00', open: true,
onOpenChallenge: () => openChallenge('wg'),
entries: [
{ id: 1, label: 'Commission on 214 delivered orders', note: '15% of EGP 184,300 sales', amount: '-27645.00' },
{ id: 2, label: 'Gifts sent: 68 of 100', note: '68 gift orders at EGP 900 each, delivery included', amount: '-61200.00' },
{ id: 3, label: 'TRNDR fee', note: 'Platform fee on this challenge', amount: '-13915.00' },
] },
{ id: 'top', name: 'Top-ups', tone: 'lime', total: '287800.00',
proof: { context: 'ref PMB-88412', onOpen: () => openProof('PMB-88412') },
entries: [{ id: 8, label: 'Card top-up, ref PMB-88412', note: 'Paid by card (Paymob) · 1 Nov', amount: '250000.00' }] },
];
// MoneyNotesProvider gives the "Balance now" term its "?" note
<MoneyNotesProvider notes={moneyNotes}>
<WalletLedger groups={groups} balance="61840.00" view={view} onViewChange={setView} onExport={exportCsv} />
</MoneyNotesProvider>// Flat view with server paging in the footer slot
<WalletLedger
groups={page.groups}
balance={wallet.balance}
view="flat"
onViewChange={setView}
footer={<Pager page={page.number} lastPage={page.last} total={page.total} loading={loading} label="Wallet entries" onPage={setPage} />}
/>import { WalletLedger, type BlockStatus, type LedgerGroup } from '@ergasti/bricks';
// Loading and error from your fetch
export function Ledger({ groups, balance, status, error, refetch }: { groups: LedgerGroup[] | null; balance: string; status: BlockStatus; error: string | null; refetch: () => void }) {
return <WalletLedger groups={groups ?? []} balance={balance} status={status} error={error} onRetry={refetch} />;
}Where it appears
- Brand › Payments › Wallet tab › "Where your money went" (full width under the hero and Wallet health).
- Dashboard screen: Payments › Wallet (
gallery/screens/PaymentsWalletScreen.tsx).
Guidelines
Do
- Send signed 2-dp strings; let the card write the sign and colour.
- Say why in every entry's
note("15% of EGP 184,300 sales"). - Open only the first group by default.
- Use
labelswhen groups are types, so the switch and subtitle tell the truth.
Don't
- Don't pre-format amounts or add your own "+"/"−".
- Don't put more than one action per group footer: challenge link or proof.
- Don't nest interactive content in an entry label when
onSelectis set (the row is one button).
RTL and Arabic
- Rows, summary and icon mirror; the chevron moves to the left.
- Arabic copy: "فلوسك راحت فين", "حسب التحدي", "كل الحركات", "نزّل CSV", "افتح التحدي ←", "الرصيد دلوقتي".
- Amounts stay tabular; the sign and currency position follow the provider's Arabic money format.
Tokens
--ok, --bad (signed figures), --line (row dividers), --row-hover, --ink-3, --soft, --focus-ring-inset; .kit-acc accordion and Card tokens; tone tints via .kit-blk-tone--* (--lime-50, --olive, --rasp-50, --butter, --butter-ink, --sky, --lilac families).
Accessibility
- Groups are native
<details>/<summary>: keyboard (Enter/Space) and state come from the browser; the tone icon isaria-hidden. - A clickable entry is a stretched
<button>under the content, labelled by the entry label (aria-labelledby), so the proof link is never nested in it. - Proof links have a name with context ("View proof · ref PMB-88412"); download links use
download. - Signs are written, not colour-only. Error is
role="alert"; loading isaria-busy.
Found in the source
- ARIA attributes set:
aria-labelledby,aria-hidden.
Read from the component's source and tests. See Accessibility for the patterns the library follows.
Related
WalletHealthCard: the low / below-zero warning beside the hero.ReceiptCard: the proof modal a group's "View proof" opens.ActivityLog: a time-ordered event list without money grouping.DataTable: for a sortable ledger export view.
See also: Card · Button · Icon · MoneyNote · Money · ProofButton · Segmented · useLanguage · useMoneyDisplay · MoneyNotesProvider · PayoutBatchDetail · PayoutWindowCard
Source
src/blocks/payments/WalletLedger.tsx (line 147) on GitHub.