# Money

An amount of money, written in the locale: tabular digits, the currency's symbol where the locale puts it, and the figure in its own isolate so it keeps its order in a right-to-left page. It never animates: a new amount replaces the old one in place, with no count or crossfade, so the figure on screen is always the one given.

Decimals follow `formatMoney`: a whole amount without them ("$20") unless `decimals="always"` ("$20.00"; "¥20" in a currency without them), and a fraction never rounded ("$0.0042" stays). An amount that isn't known (`null`, or a value that isn't a finite number) reads "Not measured", never "$0".

With `low` and `high` it is an estimate's range, "about $0.41–$0.99": each end goes to the currency's usual decimals, the low end rounded down and the high end up, so it never claims more precision than an estimate has. When either end has a fraction, both are written with the currency's decimals ("about $12.30–$20.00"), so the two ends read alike. A low end above zero but under the smallest unit gives "up to $0.50", and a range wholly under it "under $0.01". A negative end keeps its sign and is rounded outward too ("about -$0.01–$0.20"). `estimated` adds a visible "est." after the figure, and screen readers hear "estimated".

- Registry name: `money` (`@candor/money`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/money

## Install

```bash
npx candor-ui@4 add money
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/money`.
It brings in: locale, ops, tokens, utils.

## Example

```tsx
"use client"

import { Money } from "@/components/candor/money"

export default function Example() {
  return (
    <dl className="grid max-w-sm grid-cols-[auto_1fr] gap-x-6 gap-y-2 text-sm">
      <dt className="text-muted-foreground">Spent this round</dt>
      <dd>
        <Money amount={7.36} decimals="always" />
      </dd>
      <dt className="text-muted-foreground">Cap</dt>
      <dd>
        <Money amount={25} decimals="always" />
      </dd>
      <dt className="text-muted-foreground">Next round</dt>
      <dd>
        <Money low={4.12} high={9.87} decimals="always" estimated />
      </dd>
      <dt className="text-muted-foreground">Last month</dt>
      <dd>
        <Money amount={null} />
      </dd>
    </dl>
  )
}
```

## <Money>

Props:

- `amount?: number | null | undefined`: The amount, in `currency`. `null` (or left out, without `low` and `high`) reads as not measured, never as zero.
- `low?: number | undefined`: The low end of an estimate's range. With `high`, the range is shown in place of `amount`, rounded outward.
- `high?: number | undefined`: The high end of an estimate's range. With `low`, the range is shown in place of `amount`, rounded outward.
- `currency?: string | undefined` (default `"USD"`): The ISO 4217 code the amount is in, e.g. `"EUR"`. Defaults to `"USD"`. The symbol and its place come from the locale; a code the browser doesn't know is written after the number.
- `decimals?: "auto" | "always" | undefined` (default `"auto"`): `"auto"` (the default): a whole amount without decimals ("$20"). `"always"`: at least the currency's usual decimals ("$20.00", "¥20"). Either way an amount with more decimals keeps them.
- `estimated?: boolean | undefined` (default `false`): The figure is an estimate, not a measured charge: a visible "est." follows it, and screen readers hear "estimated".
- `className?: string | undefined`: Classes for the figure, merged with Candor's.

## Strings (`money`)

The fixed words, English by default. Override any of them under `money` in `<LocaleProvider strings={{ money: { … } }}>`; the table is exported as `moneyStrings`.

- `notMeasured`: Not measured
- `range`: about {low}–{high}
- `under`: under {amount}
- `upTo`: up to {high}
- `estimatedMark`: est.
- `estimated`: estimated
- `withMark`: {amount} {mark}

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.
