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 component | What 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. |
Money | The 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): stringoptions2: 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): stringProp
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>>): stringProp
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 | nullProp
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 | nullProp
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 | nullProp
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 | nullProp
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 | nullProp
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
KeyValueitem withfigureputs 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.