<!--
Summary provided to audience:
-->
<style>
/* make code examples suck less */
pre code {
margin: 0 !important;
font-size: 1.25em !important;
}
pre {
padding: 0 !important;
text-align: left !important;
}
section {
font-size: 0.8em !important;
}
.align-left {
text-align: left !important;
}
.small-li li {
font-size: 0.85em !important;
}
</style>
<!-- .slide: data-cover -->
# Amount (AmountPlaceholder?) for Stage 2 (continuation)
Ben Allen (Igalia)
September 2025
---
## Intended use cases
Amount is not intended to be a backdoor to doing math on arbitrary mathematical values. Amount offers a container for mathematical values (probably within limits -- discussion ongoing, including in this plenary!) with limited functionality: storing precision & unit.
Even a future with unit conversions (not this proposal!) wouldn't offer users a path to doing arbitrary arithmetic on unbounded values.
*Maybe we should rename things to avoid this suggestion?*
`LabeledNumber`, `PlainAmount`, `FixedAmount`, `AnnotatedNumeric`, `Dimension`
---
## Other ways to represent precision
Our design is consistent with a future extension in which we support other approaches, such as error bars.
In the future `AmountPlaceholder` could, for example, get a `.resolution` property:
- `0.500 kg` measured with a scale that can detect individual grams would have `.resolution = 0.001` and `.fractionDigit = 3`
- `0.500 kg` measured with a scale that can detect five grams increments would have `.resolution = 0.005` and `.fractionDigit = 3`
Or it can get a percentage-based `.tolerance`, or an absolute-based `.intervalRadius`, or other similar properties. All of them still have a `.fractionDigit`-based approximation for rendering purposes.
---
## Protocol for AmountPlaceholder
* We're happy with a String protocol for AmountPlaceholder (``"123.456[kg]"``)
* Syntax TBD
* We'd like to have a notation that's future-proof and extensible, with an eye toward e.g. error bar-based precision
* A duck-typing approach (objects that have `.unit` and `.fractionDigits` properties) could also work
---
## Interaction with `<amount>` HTML element
* In-progress [explainer](https://github.com/mozilla/explainers/blob/main/amount.md) by Tantek Celik (Mozilla)
* Like `<time>`, `<amount>` is only for expressing semantics. You still need _something_ that generates the string to put inside it.
```javascript
function PriceComponent({ price }: { price: AmountPlaceholder }) {
const numberFormat = useLocalized(Intl.NumberFormat);
return (
<amount
currency={price.unit}
value={price.toString({ displayUnit: never })}
>
${numberFormat.format(price)}
</amount> );
}
```
---
## Integration with `<amount>` (continued)
Maybe a full integration with HTML:
```javascript
function PriceComponent({ price }: { price: AmountPlaceholder }) {
const numberFormat = useLocalized(Intl.NumberFormat);
return (
<amount value={price}>
${numberFormat.format(price)}
</amount>
);
}
```
---
## `</v8>`
---
## Resolving puzzles with significant digits
Should we drop significant digits or derive them from fraction digits?
* [entirely remove support for significant digits](https://github.com/tc39/proposal-amount/pull/65)
* [compute significant digits from fraction digits](https://github.com/tc39/proposal-amount/pull/66)
---
## Concerns to be handled in stage 2
* We will align with Intl on limits on mathematical values ([agenda item in this plenary](https://github.com/tc39/ecma402/pull/1022))
* Significant digits for zero ("0", "0.00", ".000", etc.)
---
## Continuation, part 2
---
## Awkward arithmetic
Doing arithmetic on Amounts *can* be done, but is rather bulky:
```json=
function addAmounts(amount1, amount2) {
if (amount1.unit !== amount2.unit) { throw new RangeError("unit mismatch");
return new Amount(
amount1.toNumber() + amount2.toNumber(), {
unit: amount1.unit,
fractionDigits: Math.min(amount1.fractionDigits, amount2.fractionDigits)
});
);
```
---
# Continuation part 3: Resolved
* Significant digits
* going with [compute significant digits from fraction digits](https://github.com/tc39/proposal-amount/pull/66)
---
# Continuation part 3: Open questions
* Naming (Amount vs. something other than Amount)
* Numeric conversion methods
* users could use `Number.parseFloat(amount)` for making Amount values into Numbers?
* similar for BigInt (strip Amount's unit first)
* Reasons for more than just a protocol?
---
## <strong>Stage 2?</strong>
{"type":"slide","slideOptions":{"transition":"slide","theme":"igalia","controlsLayout":"edges","slideNumber":"c/t"}}