Skip to Content
BBRICKSv0.7.4
BlocksPayments

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>
  );
}

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.

walletLedger
KeyEnglishArabic
titleWhere your money wentفلوسك راحت فين
subGrouped by challenge. Open one to see each entry and why.متقسّمة حسب التحدي. افتح أي واحد تشوف كل حركة وسببها.
viewShow entriesاعرض الحركات
groupedBy challengeحسب التحدي
flatAll entriesكل الحركات
exportCsvExport CSVنزّل CSV
openChallengeOpen the challenge →افتح التحدي ←
balanceBalance nowالرصيد دلوقتي
emptyNo 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

  1. 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).
  2. Group (grouped view, native <details class="kit-acc">): a 34px tone icon (flag for money out, wallet for money in), the group name, the signed total (800 weight), the chevron.
  3. 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).
  4. Group footer line: "Open the challenge →" link button (onOpenChallenge) or the group's proof ("View proof" / "Download receipt").
  5. Footer slot (.kit-blk-ledger-foot): e.g. the flat view's Pager.
  6. Balance line (.kit-blk-balance): "Balance now" (a MoneyNote term) and the balance.

Variants

PropValueLookUse when
view'grouped' (default)Accordions, one per groupThe default, by challenge.
view'flat'One list; each entry's note is prefixed with its group nameThe user picks "All entries".
labels.grouped / labels.sube.g. "By type"Relabels the groupingGroups are entry types, not challenges (story ByType).
LedgerGroup.tone'lime' | 'rasp' | 'butter' | 'sky' | 'lilac'Icon tintPick 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

StateHow
Readystatus="ready" (default) with groups.
Loadingstatus="loading": skeleton rows, aria-busy, "Loading" for screen readers.
Errorstatus="error", error message, onRetry adds a "Try again" button (role="alert").
Emptygroups=[]: "No wallet entries yet." (the footer and balance line are hidden with the entries).
Group openLedgerGroup.open (the mock opens the first).
Clickable entryLedgerEntry.onSelect: the whole row is one stretched button named by the label; row hover --row-hover.
Money in / out / zeroTotal or amount starting with - is red; a non-zero positive is green; zero is ink.
Narrow cardA 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 labels when 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 onSelect is 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 is aria-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 is aria-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.

See also: Card · Button · Icon · MoneyNote · Money · ProofButton · Segmented · useLanguage · useMoneyDisplay · MoneyNotesProvider · PayoutBatchDetail · PayoutWindowCard

Source

src/blocks/payments/WalletLedger.tsx (line 147) on GitHub.

On this page