Skip to Content
BBRICKSv0.7.4
Foundations

Money

2-decimal strings, Money, formatMoney, the "?" notes and MoneyNotesProvider.

Money in BRICKS is a 2-decimal string: "1234.50", "-61200.00". The server sends it that way and components take it that way, so no floating-point number ever touches a shown figure. formatMoney does its arithmetic in BigInt cents.

Formatting

Function or componentWhat it gives
formatMoney(value, { language, currency?, showCurrency?, decimals?, compact?, sign? })"EGP 1,234.50", "− EGP 61,200.00" (a real minus sign), compact "EGP 184.3K", showCurrency: false "1,234.50", decimals: 'auto' "EGP 43,390". The one formatter. A missing or invalid value gives "—".
moneyParts(value, display)The sign and the digits apart, with no currency word, for a component that places the word itself.
MoneyThe same as a <span dir="ltr">, with tabular digits. It takes the provider's currency, and money (or compact, its shorthand) for how it is shown.
formatAmount(value)Deprecated. The grouped figure with no currency, cents only when there are any ("43,390", "1,200.50"): formatMoney(value, { language, showCurrency: false, decimals: 'auto' }).
amountInText(amount, language, currency?)A figure for a sentence, isolated left to right in Arabic.

How a figure is shown (the currency word, whole units, K / M, a "+" on money in) is a MoneyDisplay, set per component, per slot or for the whole app: see Money display.

Strings in, strings out

Money arrives as a 2-decimal string and leaves as text; no float touches a figure. A missing or invalid value draws "—" rather than a wrong number.

Code
import { Money, formatMoney, useLanguage } from '@ergasti/bricks';

function Formatting() {
  const language = useLanguage();
  const rows: Array<[string, string | null]> = [['61840.00', null], ['-61200.00', null], ['184300.00', 'compact'], ['999950.00', 'compact'], ['1500.5', null], ['not a number', null]];
  return (
    <table style={{ borderCollapse: 'collapse' }}>
      <thead><tr><th>Input</th><th>formatMoney</th><th>Money</th><th>No currency, 'auto'</th></tr></thead>
      <tbody>
        {rows.map(([input, mode]) => (
          <tr key={input}>
            <td><code>{input}</code>{mode ? ' compact' : ''}</td>
            <td>{formatMoney(input, { language, compact: !!mode })}</td>
            <td><Money value={input} compact={!!mode} /></td>
            <td>{formatMoney(input, { language, showCurrency: false, decimals: 'auto' })}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

formatMoney

function

The one money formatter, for a server 2-dp string: "EGP 1,234.50", "− EGP 61,200.00", compact "EGP 184.3K", showCurrency: false "27,645.00", decimals: 'auto' "EGP 43,390", sign: 'always' "+ EGP 250,000.00"; Arabic puts the word after the figure ("1,234.50 ج.م"). String in, string out; a missing or invalid value shows "—" rather than a wrong number.

function formatMoney(value: string | null | undefined, options2: FormatMoneyOptions): string

options2: FormatMoneyOptions (required)

Prop

Type

Source: src/lib/format.ts (line 126)

formatAmount

function deprecated

Deprecated

Since 0.3.0: use formatMoney(value, { language, showCurrency: false, decimals: 'auto' }), the one formatter. Removed in 1.0.

The hero's big figure: grouped, no currency, cents only when there are any ("43,390", "− 500", "1,200.50").

function formatAmount(value: string | null | undefined): string

Prop

Type

Source: src/lib/format.ts (line 137)

amountInText

function

A grouped amount (formatAmount's "5,000") with the currency word, for a sentence: "EGP 5,000" / "5,000 ج.م". The Arabic run is isolated left to right (LRI … PDI), so it reads like Money inside Arabic words.

function amountInText(amount: string, lang: Lang, currency?: Readonly<Record<Lang, string>>): string

Prop

Type

Source: src/lib/format.ts (line 145)

Doing maths on money

Never divide, add or compare money as floats: Number("184000.00") / 708 is a float that has already lost cents. The package exports the maths it uses itself, on the server's 2-dp strings in whole BigInt cents. Each returns a 2-dp string (or a number for percentOf, -1/0/1 for compareAmounts) and null when an input is not a plain 2-dp amount, never 0, so you decide what "unknown" means. An average price is divideAmount(sales, units), then <Money value={…}>.

import { divideAmount, Money } from '@ergasti/bricks';

const average = divideAmount('184000.00', 708); // "259.89", rounded half away from zero
<Money value={average} />;

divideAmount

function

amount / parts, rounded half away from zero to the cent ("4500.00" / 10 → "450.00"); null for no amount or no parts.

function divideAmount(amount: string | null | undefined, parts: number): string | null

Prop

Type

Source: src/lib/money.ts (line 46)

addAmounts

function

base + delta (both 2-dp strings; sign -1 subtracts); null when either is not an amount.

function addAmounts(base: string | null | undefined, delta: string | null | undefined, sign?: 1 | -1): string | null

Prop

Type

Source: src/lib/money.ts (line 53)

subtractAmounts

function

base − delta; null when either is not an amount.

function subtractAmounts(base: string | null | undefined, delta: string | null | undefined): string | null

Prop

Type

Source: src/lib/money.ts (line 60)

compareAmounts

function

-1, 0 or 1 as a is below, equal to or above b; null when either is not an amount.

function compareAmounts(a: string | null | undefined, b: string | null | undefined): 0 | 1 | -1 | null

Prop

Type

Source: src/lib/money.ts (line 63)

percentOf

function

part as a whole percent of whole, half up (for a bar or a label); null unless both are amounts and whole > 0.

function percentOf(part: string | null | undefined, whole: string | null | undefined): number | null

Prop

Type

Source: src/lib/money.ts (line 71)

The "?" notes

Every money figure can carry a "?" note that says what it includes and excludes. The dictionary is the server's (money_notes): one entry per figure key with a label, includes and excludes, already in the page's language. Give it to BricksProvider moneyNotes or to a MoneyNotesProvider; below it:

  • MoneyNote figure="sales" draws the small "?" button (or, with children, turns the label into a dotted term);
  • MoneyFigure figure="wallet_balance" amount="61840.00" draws a label and its amount together;
  • a table column or a KeyValue item with figure puts the "?" next to its header or label;
  • useMoneyLabel() gives the dictionary's label for a figure, for headers that must match.

Notes beside figures

Every money figure can have a "?" note saying what it includes and excludes. The dictionary comes from the server (money_notes); MoneyNotesProvider hands it to every MoneyNote and MoneyFigure below.

Code
import { MoneyFigure, MoneyNote, MoneyNotesProvider, useLanguage } from '@ergasti/bricks';
import { moneyNotes } from './sample-data';

function Notes() {
  const language = useLanguage();
  return (
    <MoneyNotesProvider notes={moneyNotes(language)}>
      <div style={{ display: 'grid', gap: 10, paddingTop: 90 }}>
        <span>Sales <MoneyNote figure="sales" amount="184300.00" /></span>
        <MoneyFigure figure="wallet_balance" amount="61840.00" />
        <MoneyFigure figure="wallet_held" amount="18450.00" />
      </div>
    </MoneyNotesProvider>
  );
}

The popover opens on press, hover or focus, closes on Escape, an outside press, scroll or resize, and returns focus to the "?" when Escape closes it. A figure key the dictionary does not have draws no note (the wrapped label still shows), so keep the dictionary complete: the library's own test asserts that no component formats money without a figure beside it, and that every figure name it uses is one of MONEY_FIGURES.

MONEY_FIGURES

constant

Every figure the console may show with a "?" (keys of affiliate::money). Typed, so a surface cannot name a figure the dictionary lacks; MoneyNoteCoverage.test checks this list against EN and AR.

const MONEY_FIGURES: readonly ["earned", "other", "paid", "balance", "on_hold", "negative_balances", "owed_now", "pending_approval", "declined", "sales", "delivered_orders", "average_order", "program_cost", "avg_commission_per_order", "net_profit", "wallet_available", "wallet_balance", "wallet_held", "wallet_topped_up", "challenge_sales", "challenge_commission", "wallet_left_percent", "payout_batch_total", "sales_per_commission", "coupon_sales", "creator_sales", "always_on_sales", "product_sales", "product_avg_price", "order_commission", "order_line", "paid_this_month"]

Source: src/kit/MoneyNote.tsx (line 42)

Where notes appear

A "?" is part of: HeroCard and WalletLedger (their figures), Tile, DataTable and RowList columns (a column's figure), KeyValue items (figure), RowItems (figure), SummaryLine (figure), and the bundle and top-up blocks. Anywhere else, put a MoneyNote or MoneyFigure beside a Money yourself. See MoneyNote for the popover and its keyboard behaviour.

Commission rates

A commission is a rate, not an amount: a percentage of the sale or a fixed amount per item. Show it with CommissionRate (or commissionRateText for a string), so every screen words it the same way: "15%" or "EGP 30 per item", and with form="long" "15% of sale". It takes the provider's currency and language.

import { CommissionRate, Pill } from '@ergasti/bricks';

<Pill tone="lime"><CommissionRate kind="per_item" value="30.00" /></Pill>
<CommissionRate kind="percent" value="15" form="long" />

See CommissionRate.

Currency

Currency and formatter come from the provider: see The provider and presets. Pass currency.format to replace the formatter completely (grouping, sign, compact suffixes, where the word goes); it receives the language and the resolved Money display options.

On this page