@nxgt/material 3.75.0 → 3.76.0

package/docs/guides/calculator.md

@@ -0,0 +1,468 @@
+# Calculator
+
+`@nxgt/material/calculator` is a calculator for your app: exact decimal
+arithmetic (`0.1 + 0.2` is `0.3`), the usual precedence (`2 + 3 × 4` is `14`),
+the whole expression shown above the result, a tape of past results, a memory,
+the physical keyboard, copy and paste, and a screen-reader announcement of each
+result. Standard, Scientific, the point of sale, Financial, Conversion and
+Programmer ship.
+
+The maths is `@nxgt/material-core/calculator`: a decimal engine on `BigInt`
+with its own expression parser, so nothing is evaluated as code and a strict
+Content Security Policy is satisfied. The component is a thin shell over it.
+
+- [Set up](#set-up)
+- [The Standard calculator](#the-standard-calculator)
+- [The Scientific calculator](#the-scientific-calculator)
+- [The point-of-sale calculator](#the-point-of-sale-calculator)
+- [The Financial calculator](#the-financial-calculator)
+- [The conversion calculator](#the-conversion-calculator)
+- [The Programmer calculator](#the-programmer-calculator)
+- [Props](#props)
+- [Keyboard](#keyboard)
+- [Tape and memory](#tape-and-memory)
+- [Copy and paste](#copy-and-paste)
+- [What is stored](#what-is-stored)
+- [Feedback](#feedback)
+- [Sizing](#sizing)
+- [Accessibility](#accessibility)
+- [Translations](#translations)
+- [Troubleshooting](#troubleshooting)
+
+## Set up
+
+```tsx
+import { Calculator } from '@nxgt/material/calculator';
+```
+
+The entry is its own: it is not in `@nxgt/material` or
+`@nxgt/material/components`. Its stylesheet is opt-in too: `styles.css` does
+not carry it, so import `@nxgt/material/calculator.css` once, after
+`styles.css` (also for `CalculatorField`, which opens the calculator):
+
+```css
+@import "@nxgt/material/styles.css";
+@import "@nxgt/material/calculator.css";
+```
+
+(or `import '@nxgt/material/calculator.css'` in your entry module). Colours and
+tokens still come from `styles.css`, which your app already imports. It renders on the server; the tape and memory
+are read from `localStorage` after mount, so the first client frame matches the
+server's.
+
+## The Standard calculator
+
+```tsx
+<Calculator />
+<Calculator locale="fr" persist={{ key: 'till-1' }} onResult={(value) => save(value)} />
+```
+
+The display shows the expression above a large result that previews the value
+while you type. The keypad has `( )` and the memory keys on top, then `C`, `±`,
+`%`, `÷ × − +`, the digits, the decimal separator of the locale, `⌫` and `=`, a
+primary pill. `%` follows the `percent` prop below. A result is
+exact; an inexact one (`1 / 3`) is rounded to 34 digits and shown with 16.
+
+## Loading
+
+Only Standard is in the entry itself. Every other variant, with its engine, is loaded
+on demand the first time it is shown (by `variant`, `defaultVariant` or the switcher,
+which starts the download on hover and focus). Until it arrives the body is a skeleton
+of Standard's size with a polite "Loading the calculator" status
+(`material.calculator.loading`); a download that fails says "This calculator could not
+be loaded." (`material.calculator.load-failed`) and offers "Try again"
+(`material.calculator.retry`), which loads it again. On the server that loading body is what
+renders, then the client hydrates and fetches the variant. The brief loading state the
+first time is expected, and there is no public preload. A browser may keep a failed dynamic
+import until the page reloads, so if Try again fails again, reload the page. Keys
+and paste do nothing while a variant loads. See
+[the troubleshooting entry](../troubleshooting.md#this-calculator-could-not-be-loaded).
+
+## The Scientific calculator
+
+```tsx
+<Calculator defaultVariant="scientific" />
+<Calculator variants={['scientific']} />
+```
+
+The switcher shows Standard, Scientific, Point of sale, Financial, Conversion and Programmer; `variants` narrows it (one hides
+it). Scientific calculates with `@nxgt/material-core/calculator/scientific`:
+exact to `precision` digits (34), so `sin(30)` is `0.5`, `cos(90)` is `0` and
+`tan(90)` is an error, never a huge number. It brings a toolbar and a pane of
+functions above the Standard keys on a phone, beside them from 600px to 719px
+and from 1000px up (from 720px to 999px the tape takes its column and the pane
+stays above).
+
+| Keys | |
+| --- | --- |
+| `sin cos tan sinh cosh tanh` | In the toolbar's angle unit; **2nd** turns them into `asin acos atan asinh acosh atanh` (the button stays, so focus stays) |
+| `ln log log₂ 10ˣ eˣ |x|` | `log` is base 10; `10ˣ` is `10^x` for any exponent (`10^2.5` is `316.2277…`) |
+| `x² xʸ √ ʸ√x n! 1/x` | `√`, `ʸ√x` (`nroot(x, y)`), `x²` and `1/x` open a call: type the argument; `=` closes it |
+| `π e EE mod , Ans` | `EE` starts the exponent of the number you are typing, so `3 EE 5` is `3e5` (300000), `± ` after it signs the exponent (`3e-5`) and it does nothing after an operator or `=`; `,` separates the arguments of `ʸ√x` (`nroot(x, y)`), `Ans` is the last result |
+
+Toolbar: **DEG RAD GRAD** (a named group of toggle buttons with
+`aria-pressed`; the unit applies to the trigonometric functions and their
+inverses), **2nd** (a toggle with `aria-pressed`, announced "Second functions
+on") and **Auto Sci Eng** (the same kind of group). Auto switches to powers of ten for results from
+16 digits or below 1e-7; Sci writes `1.2345678E+7` and Eng
+`12.345678E+6`, exponent a multiple of 3. Changing the unit or the notation is
+announced ("Angles in radians", "Scientific notation"). `%` is `/100` here
+(`100 + 10%` is `100.1`) unless you set `percent`. The keyboard also types
+`^`, `!`, `p` (π), `r` (√) and `;` between arguments. No graphs and no complex
+numbers: `sqrt(-1)` is "Undefined result".
+
+## The point-of-sale calculator
+
+```tsx
+<Calculator
+  defaultVariant="pos"
+  currency="EUR"
+  vatRates={[20, 5.5]}
+  denominations={[5, 10, 20, 50]}
+  onCharge={(total, ticket) => pay(total, ticket)}
+/>
+```
+
+The props below are read only by this variant (`currency` is shared). A point of sale till for a counter, on `@nxgt/material-core/calculator/pos`; the
+tab is named "Point of sale". The keys type an amount the way a till does:
+`1`, `2`, `5` is `1.25`, `00` adds two zeros, backspace drops the last digit,
+`C` clears it. `+` adds it to the ticket. `×` types a quantity first (`2.50 ×
+3 +` is a line of 7.50), `%` types a discount first, as a whole percent or,
+with the **Amount** choice, an amount; a discount typed with no price applies
+to the whole ticket. The chips above the keys (Price, Quantity, Discount,
+Tendered) show what the keys type into.
+
+The ticket lists its lines, each removable on its own; on a phone it sits under
+the keys and folds away, from 600px it sits beside them. The totals show the
+subtotal and discount when there is one, the VAT of each rate and the total.
+**Tendered** types what the customer hands over (the `+` key then only
+announces the result); the bills under the ticket are the exact total and up to
+three round amounts from `denominations` (`[5, 10, 20, 50]` for 17.30 gives
+17.30, 20, 50). The line under them is the change, or what is still due, and
+**Charge** is off while the payment is short.
+
+| Prop | Default | |
+| --- | --- | --- |
+| `currency` | none | ISO 4217 code (a prop of the calculator, shared by the variants that show amounts): sets the decimals (`JPY` 0, `EUR` 2, `KWD` 3) and is written beside the amounts. None: two decimals and no code |
+| `vatRates` | none | The VAT rates in percent (`[20, '5.5']`); the first is the default, a chip chooses the rate of the next line. None: no VAT |
+| `pricesIncludeVat` | `true` | The prices typed include the VAT; `false`: the VAT is added to them. The **Incl. VAT / Excl. VAT** choice switches it on screen |
+| `denominations` | none | Bills and coins for the round amounts; without them only the exact amount is offered |
+| `onCharge` | none | `(total, ticket)`: `total` is the exact amount as plain text (`'12.50'`), `ticket` a `PosTicket`, plain JSON-safe data (`JSON.stringify` it as is): `{ currency?, taxInclusive, lines: [{ id, unitPrice, quantity, vatRate, discount?, total }], discount?, totals: { subtotal, discount, vatByRate: [{ rate, base, vat }], total } }`, every amount as text with the currency's decimals (`'12.50'`), rates in percent (`'5.5'`). The ticket is then cleared |
+
+The amounts are exact decimals rounded to the currency's minor unit per line,
+so the lines add up to the total. The ticket lives in memory only: it is never
+written to `localStorage`, and the tape does not apply. The live region says
+the total after a line is added or removed, the change or the amount due after
+a tender, and the total charged; typing digits is not announced. Percentages
+are whole numbers (7.5 % is not typeable) and quantities are whole.
+
+## The Financial calculator
+
+```tsx
+<Calculator defaultVariant="financial" currency="EUR" locale="fr" />
+<Calculator variants={['financial']} />
+```
+
+Financial is a panel of forms, not a keypad: four sub-tabs, each with the
+library's own fields (`CurrencyField`, `PercentField`, `NumberField`) and its
+results in a card below. The maths is
+`@nxgt/material-core/calculator/financial`, exact decimals, amounts rounded to
+the currency's minor unit (half-up).
+
+| Tab | What it does |
+| --- | --- |
+| VAT | **Add VAT** to a price excluding VAT, or **Remove VAT** from one that includes it: price excluding VAT, VAT and price including VAT always add up |
+| Margin | **Rates** of a cost and a selling price (margin is the share of the PRICE that is profit, markup the share of the COST, so 80 sold at 100 is a 20 % margin and a 25 % markup); **Price** from a cost and a margin or a markup; **Cost** from a price and a margin or a markup |
+| % change | Percent change from one figure to another, and the difference (from `0` is an error) |
+| Loan | Monthly payment of a loan (yearly rate, number of monthly payments, `0` % allowed), total interest, total paid, and the first 12 payments as a real `<table>` with a caption ("First 12 of 240 payments"): payment, interest, principal and balance, the last payment absorbing the rounding |
+
+`currency` (an ISO 4217 code, shared with the point of sale; see
+[the troubleshooting entry](../troubleshooting.md#the-financial-calculator-shows-no-currency))
+is written after each amount and sets the decimals (`JPY` 0, `EUR` 2, `KWD`
+3); without it amounts have two decimals and no code. Amounts and percents are
+written in `locale`. Every tab keeps what was typed while another is open. A
+result is read by the live region once the fields stop changing, not at each
+digit, and an error (a margin of 100 % or more, a change from `0`) is read in
+the same place. The fields hand over JavaScript `number`s, so a figure beyond
+about 15 significant digits is out of range. The calculator keys, the tape and
+`globalKeyboard` do not apply to this variant, and typing in a field never
+reaches them.
+
+## The conversion calculator
+
+```tsx
+<Calculator defaultVariant="conversion" />
+<Calculator
+  defaultVariant="conversion"
+  currencyRates={{ base: 'EUR', rates: { USD: '1.085', JPY: '160.5' }, asOf: '2026-10-28' }}
+/>
+<Calculator
+  defaultVariant="conversion"
+  currencyRates={(signal) => fetch('/api/rates', { signal }).then((r) => r.json())}
+/>
+```
+
+A converter on `@nxgt/material-core/calculator/units`; the tab is named
+"Conversion". Choose a **Category** (length, mass, temperature, volume, area,
+speed, time, data), type a **Value** (in the locale's own separators: `1 234,5`
+in French) and pick the unit it is in (**From**) and the unit wanted (**To**).
+The swap button turns the pair around and keeps the value; choosing on one side
+the unit the other side has swaps them. The result is exact (`1 in` is `2.54
+cm`, `212 °F` is `100 °C`; temperatures keep their offsets) and written in the
+locale with up to 16 significant digits. The live region says it once the value
+stops changing, not at every digit. The variant has no keypad, tape or memory,
+and takes no calculator keys.
+
+`currencyRates` adds a **Currency** category, and only then:
+
+- An object `{ base, rates, asOf? }`: `rates[code]` is how much of `code` one
+  `base` buys, every rate a positive number or text (text keeps the digits
+  exact). `asOf` is shown as "Rates as of ...".
+- A function `(signal: AbortSignal) => Promise<{ base, rates, asOf? }>`, called
+  the first time Currency is chosen, with an `AbortSignal` that aborts when the panel closes
+  or the fetch is repeated (pass it to `fetch`). Meanwhile the panel says
+  "Loading exchange rates..."; when the promise rejects or the rates are not
+  valid it says so, with **Try again**, which calls the function again. Its
+  identity does not matter (an inline arrow is fine); only Try again calls it
+  a second time. A function that throws at once is an error like a rejection.
+
+A currency amount is rounded to the minor unit of the target currency (`JPY` 0,
+`EUR` 2, `KWD` 3). Nothing is fetched by the library, and no rate is built in.
+The types are `CalculatorCurrencyRates` (the object), `CalculatorRatesSource`
+(the object or the function) and `CalculatorConversionProps`, exported from
+`@nxgt/material/calculator`.
+
+Currency names follow the i18n language (the one the unit names are translated
+in); `locale` only formats the number and the quote date.
+
+### Wording
+
+The words live under `material.calculator.conversion` (categories, units,
+`rates.loading`, `rates.error`, `rates.retry`, `rates.as-of`, the announcement);
+the engine's messages are under `material.calculator.error`. Override one key
+with `mergeResources` (per language, your value wins; see the
+[i18n guide](./i18n.md)) and give the result to the provider:
+
+```tsx
+import { mergeResources, resources as materialResources } from '@nxgt/material/i18n';
+
+export const resources = mergeResources(materialResources, {
+  en: { material: { calculator: { conversion: { rates: { retry: 'Reload rates' } } } } },
+});
+// <I18nProvider resources={resources}>
+```
+
+| Prop | Default | |
+| --- | --- | --- |
+| `currencyRates` | none | The rates, or a function that fetches them (above). None: no Currency category |
+| `locale`, `precision`, `rounding` | | Read as everywhere: number format, significant digits and rounding of a result that does not terminate |
+
+## The Programmer calculator
+
+```tsx
+<Calculator defaultVariant="programmer" defaultWordSize={32} defaultSigned={false} />
+```
+
+Integers in a word of 8, 16, 32 or 64 bits, signed (two's complement, the
+default) or unsigned; every result wraps into the word (`127 + 1` is `-128` in
+a signed 8-bit word). The maths is
+`@nxgt/material-core/calculator/programmer`. The keypad adds `A` to `F`, the
+word operators (`AND`, `OR`, `XOR`, `NOT`, `NAND`, `NOR`), shifts (`<<` and
+`>>`, arithmetic) and rotates (`ROL`, `ROR`), and `mod`. `^` on the keyboard is
+`XOR`; the `>>` key is an arithmetic shift (it copies the sign bit in), and the
+logical shift `>>>` can be typed as text.
+
+- **Bases**: four readouts (HEX, DEC, OCT, BIN) show the number being edited
+  and are a single choice: the base chosen is the one the digit keys type in
+  and the big line is written in. Changing it rewrites the number in the new
+  base: an expression that calculates (`10+5`) collapses to its value and the
+  live region says "Converted to F"; one that does not calculate yet (`10+(`)
+  has each number literal rewritten in place (`a+(`), as does one that ends in
+  an operator (`10+` is `a+` in hex, without collapsing), and one that cannot be
+  rewritten cleanly keeps its base and says "Base not changed". Digits the base
+  does not have (`A` to `F` in decimal, `8` and `9` in octal, `2` to `9` in
+  binary) are `aria-disabled` (they stay in the tab order), press nothing, and
+  say "Not available in Octal", from the keypad or the keyboard.
+- **Word**: the size buttons and the **Signed** toggle change the word. A
+  narrower word cuts the number to its low bits and the live region says
+  "Value cut to 8 bits: 44"; a wider one, or a change of sign, rereads the same
+  bits.
+- **Bit pad**: behind a **Bit pad** disclosure, one toggle button per bit
+  (`aria-pressed`, "Bit 7"), most significant first, grouped by four: one
+  nibble a row under 400px, two from 400, four from 760. Pressing a bit flips it
+  and announces it. While the expression does not calculate (`10+(`) the pad is
+  inert (`aria-disabled`) and leaves the expression alone.
+- Copy writes the value in the base shown, upper case, with no prefix (`FF`);
+  Paste reads the text in the current base, so Copy then Paste round-trips. The
+  tape keeps the expression as typed and the result in decimal. Results are
+  announced in the chosen base.
+
+`defaultWordSize` (`8 | 16 | 32 | 64`, default `64`) and `defaultSigned`
+(default `true`) are read once, when the calculator mounts; the user changes
+the word from then on.
+
+## In a form: CalculatorField
+
+`CalculatorField` and `CalculatorFormField` are their own entry,
+`@nxgt/material/calculator-field`, so an app that only uses `Calculator` does
+not pay for the popover and sheet. `CalculatorField` is a number field with an "Open calculator" button inside it.
+The button opens a `Calculator` seeded with the field's number: a popover from
+768px wide, a bottom sheet below. **Apply** writes the result to the field;
+**Cancel** and Escape keep the number. Focus goes back to the button either way.
+
+```tsx
+import { CalculatorField, CalculatorFormField } from '@nxgt/material/calculator-field';
+
+<CalculatorField label="Quantity" value={qty} onChange={setQty} />
+<CalculatorField label="Price" currency="EUR" value={price} onChange={setPrice} onExactValueChange={(exact) => console.log(exact)} />
+<CalculatorFormField control={form.control} name="total" label="Total" currency="EUR" />
+```
+
+It is a `NumberField` (steppers, `min`, `max`, `step`, `suffix`), or a
+`CurrencyField` when `currency` is set; a currency field takes no `suffix`, `step` or `hideSteppers`, and `min` / `max` do not limit what is typed (Apply still holds the amount to them). It adds:
+
+| Prop | Default | |
+| --- | --- | --- |
+| `calculatorVariant` | `standard` | The variant the calculator opens with |
+| `calculatorVariants` | `['standard']` | The variants its switcher offers; one hides the switcher. Pass more to opt in: `['standard', 'scientific', 'financial']` |
+| `surface` | `auto` | `auto` (popover from 768px, sheet below), `popover` or `sheet` |
+| `onExactValueChange` | none | Called on Apply with the exact decimal result (`'3.3333333333333333333333333333333333'`), before it is rounded |
+| `fractionDigits` | the currency's | Decimals of a currency amount |
+
+Apply takes what the display shows, so an unfinished sum (`2 + 3 × 4` with no
+`=`) applies its result. A currency amount is rounded half-up to the currency's
+decimals (`10 ÷ 3` is `3.33` in EUR, `1235` for `1234.5` in JPY); any other
+number is the nearest `number`. The result is held to `min` and `max`, as typing
+is. Apply is disabled while the display has no number (empty, or an error), see [troubleshooting](../troubleshooting.md#calculator). The
+calculator keeps no tape or memory there (`persist={false}`), and each opening
+starts from the field's number again.
+
+`CalculatorFormField` takes `control` and `name`; the value is `number | null`.
+Focus moving into the calculator and back is not leaving, so the field is
+touched when focus leaves the field and its calculator.
+
+Two props of `Calculator` serve it, and an application can use them too:
+`defaultValue` (a number such as `'12.5'` the calculator opens with, as a
+finished result: a digit starts a new number, an operator carries on from it)
+and `onValueChange` (the display's exact value each time it changes, `''` when
+there is none).
+
+## Props
+
+| Prop | Default | |
+| --- | --- | --- |
+| `variant` / `defaultVariant` / `onVariantChange` | `standard` | The variant shown, controlled or not. A variant that is not available yet falls back to Standard |
+| `variants` | every registered variant | The variants the switcher offers; one hides the switcher. The default list grows with each variant the library adds, so an app that wants a fixed set passes `variants` |
+| `currency` | none | ISO 4217 code of the amounts (decimals and code), see [above](#the-point-of-sale-calculator) |
+| `vatRates`, `pricesIncludeVat`, `denominations`, `onCharge` | | Read only by the point of sale, [above](#the-point-of-sale-calculator) |
+| `defaultWordSize`, `defaultSigned` | `64`, `true` | Read only by the Programmer variant, [above](#the-programmer-calculator) |
+| `currencyRates` | none | Read only by Conversion: its Currency category, [above](#the-conversion-calculator) |
+| `locale` | the page's language | Separators, grouping and the decimal key's glyph |
+| `precision`, `rounding` | 34, `half-even` | The engine's context |
+| `percent` | `contextual` | `contextual` (`100 + 10%` is 110) or `literal` (always `/100`) |
+| `persist` | `true` | Keep the tape and memory in `localStorage`; `{ key }` names the slot; `false` keeps nothing |
+| `feedback` | none | `{ haptics, sound }`, both off |
+| `globalKeyboard` | `false` | Also take the keys typed anywhere on the page |
+| `defaultValue` | none | A number the calculator opens with, as a finished result, see [CalculatorField](#in-a-form-calculatorfield) |
+| `onValueChange` | none | `(value)`: the display's exact value (result or live preview) each time it changes; `''` when there is none |
+| `onResult` | none | `(value, expression)` after each `=`: the exact result and the canonical expression |
+| `className`, `aria-label` | | The root `role="group"`, named "Calculator" by default |
+
+## Keyboard
+
+The calculator takes the keys typed inside it (a key, the display or the
+tape): digits, `.` and `,` (the locale's decimal), `+ - * / x`, `%`, `(` `)`,
+`=` and Enter, Backspace, Delete (`CE`), Escape (`C`), and `Ctrl`/`Cmd` + `C`
+(copy) and `V` (paste, the browser's own paste event). It reads `event.key`, so an AZERTY keyboard types the digits it
+prints. Enter on a focused key is that key's click, not `=`.
+
+In the Programmer variant `a` to `f` type the hex digits (only where the base
+has them) and `^` is `XOR`; `&`, `|` and `~` are not mapped, use the `AND`,
+`OR` and `NOT` keys. `>>` is an arithmetic shift, and `>>>` (logical) can be
+typed as text.
+
+The keypad is one tab stop. Inside it the arrow keys move over the grid in two
+dimensions, Home and End along a row, and Ctrl with them to the first and last
+key. Escape closes the history when it lies over the keypad, and means `C`
+otherwise.
+
+`globalKeyboard` adds a window listener for the keys typed elsewhere on the
+page. It never takes a key typed in an input, a textarea, a select or an
+editable element.
+
+## Tape and memory
+
+Each `=` writes an entry to the tape (newest first, 100 at most). Open it with
+the history button; it takes the keypad's place below 720px and sits beside it
+from there (the history button stays, and focus moves into the
+history and back). The
+expression button replays the entry into the display, ready to edit; the result
+button types the result into the current expression. The bin clears the tape.
+
+`MC MR M+ M−` clear, recall, add to and subtract from the memory, at full
+precision. An `M` chip shows while the memory holds a value.
+
+## Copy and paste
+
+The copy button (or `Ctrl`/`Cmd` + `C` with nothing selected) copies the exact
+result in the locale's decimal, without grouping. The paste button
+(which asks the browser for clipboard permission) and `Ctrl`/`Cmd` + `V` (no
+permission, it reads the paste event) put the clipboard's text in as the expression, accepting
+the usual separators (`1.234,5 × 2` in German, `1,234.5 × 2` in English) and
+Arabic-Indic digits; press `=` to calculate it. A browser that denies
+clipboard access leaves the calculator as it was.
+
+## What is stored
+
+With `persist` on, `localStorage` holds `nxgt-calculator:<key>:history` (the
+tape) and `nxgt-calculator:<key>:memory`, versioned JSON that is read after
+mount and validated: anything unreadable gives an empty tape and a memory of
+`0`. Writes are debounced. A blocked or full storage is ignored. Use
+`persist={false}` where a calculator must not remember (a shared till), or a
+`key` per till.
+
+## Feedback
+
+`feedback={{ haptics: true }}` vibrates 8 ms on a key press where
+`navigator.vibrate` exists, and never under `prefers-reduced-motion`.
+`feedback={{ sound: true }}` plays a short tick through the Web Audio API,
+created on the first press. Both are off by default.
+
+## Sizing
+
+The calculator sizes itself by its own width (container queries), not the
+window's: under 360px a compact layout, 360-599 a phone, 600-899 a tablet,
+900 and up a desktop with a wider tape (where the tape sits is in
+[Tape and memory](#tape-and-memory)). Long results shrink instead of clipping. Keys
+are at least 44px on a coarse pointer. The result swap animation is off under
+reduced motion, and forced colours get borders.
+
+## Accessibility
+
+- The root is a named `role="group"`; the keypad is a `role="group"` of native
+  buttons, each with a spoken name ("Plus", "Divided by", "Equals"); the glyph
+  is decoration.
+- The display is a named group, not an input and not a tab stop. The expression and the result are read
+  left to right in a right-to-left page, as are the keys.
+- A polite live region announces the result after `=`, errors, memory changes,
+  copy and paste, not every key.
+- Errors are words ("Cannot divide by zero"), never `NaN` or `Infinity`.
+
+## Translations
+
+Every string is `material.calculator.*` in the base bundle, English and
+French; override a leaf in your own resources.
+
+The Programmer keys have their own leaves: `material.calculator.programmer.*`
+(the bases and their `set-*` announcements, word size, `signed`, `bits`, `bit`,
+`bit-on`, `bit-off`, `converted`, `base-kept`, `unavailable`), the key names
+under `material.calculator.keys` (`hex-a` to `hex-f`, `and`, `or`, `xor`,
+`not`, `nand`, `nor`, the shifts and rotates), and
+`material.calculator.announce.truncated`, `wordSigned` and `wordUnsigned`.
+
+`material.calculator.field.*` (`open`, `title`, `apply`, `cancel`) name the
+`CalculatorField` button and its dialog.
+
+## Troubleshooting
+
+See [the Calculator entries](../troubleshooting.md#calculator).

package/docs/guides/forms.md

@@ -116,7 +116,7 @@ export function PlanForm() {
 | --- | --- |
 | one input (`TextFormField`, `EmailFormField`, `TextareaFormField`, `SwitchFormField`, `CheckboxFormField`, …) | its input loses focus, as a native `blur` |
 | several controls (`OpeningHoursFormField`, inline by default: focus leaves the week editor and its phone sheet; `ContactsFormField`, inline by default: focus leaves the rows and the phone sheet; `AttributesFormField`, inline by default: focus leaves the rows, their open fields and the phone sheet; `PasswordFormField` and its eye button, `NumberFormField` and its steppers, `QuantityFormField`, `PhoneFormField`, `OtpFormField`, `SliderFormField` with two thumbs, `DurationFormField`, `RatingFormField`, `RadioGroupFormField`, `CheckboxGroupFormField`, `ChipGroupFormField`, `ChoiceCardGroupFormField`, `SortableListFormField`, `TransferListFormField`, `InlineEditFormField`, `LocalizedTextFormField`, `AttributeValuesFormFieldSet`, …) | focus leaves all of them; moving between them is not leaving |
-| a picker (`SelectFormField`, `ComboboxFormField`, `AutocompleteFormField`, `TreeSelectFormField`, `CountryFormField`, `TimezoneFormField`, `ColorFormField`, `DateFormField`, `DateRangeFormField`, `TimeFormField`, …) | focus leaves the trigger **and** the popover it opened. Opening the popover, or picking in it, is not leaving; closing it hands focus back to the trigger, and the next Tab or click elsewhere is. A typed `DateFormField`, `DateRangeFormField` or `TimeFormField` is one trigger: moving between its segments (both ends of a range) and its buttons is not leaving |
+| a picker (`SelectFormField`, `ComboboxFormField`, `AutocompleteFormField`, `TreeSelectFormField`, `CountryFormField`, `TimezoneFormField`, `ColorFormField`, `DateFormField`, `DateRangeFormField`, `TimeFormField`, `CalculatorFormField` (the number field and its calculator button), …) | focus leaves the trigger **and** the popover it opened. Opening the popover, or picking in it, is not leaving; closing it hands focus back to the trigger, and the next Tab or click elsewhere is. A typed `DateFormField`, `DateRangeFormField` or `TimeFormField` is one trigger: moving between its segments (both ends of a range) and its buttons is not leaving |
 | a dialog editor (`PostalAddressFormField`, `ContactsFormField` with `editing="dialog"`, `OpeningHoursFormField` with `editing="dialog"`, `AttributesFormField` with `editing="dialog"`, and `LocationFormField` from `@nxgt/material/map`) | focus leaves its buttons and the dialog they open. Closing the dialog hands focus back to the button that opened it |
 | an upload (`UploadFormField`, `NetworkUploadFormField`, `S3UploadFormField`, `ImageFormField`, `ImageS3FormField`, `FileListFormField`, `FileListS3FormField`) | focus leaves the drop zone and its buttons. Choosing a file in the browser's own dialog is not leaving |
 | `RichTextEditorFormField`, `CodeEditorFormField` | focus leaves the editor and its toolbar |
@@ -277,7 +277,8 @@ form grows with the page, and the page is the one scroll. The actions
 (`[data-slot="form-actions"]`) are sticky at the bottom of whatever scrolls
 the form, on a translucent, blurred background, so Cancel and Save stay in
 reach while the fields scroll under them; a form shorter than the screen
-shows them right under its fields.
+shows them right under its fields, on the fields' own surface (same
+tint, no gap): one slab, not two.
 
 - In a `DialogContent` without a `DialogBody`, or a `SheetContent`, which are capped to the screen
   and scroll themselves, the actions stick to the dialog's or the sheet's
@@ -488,6 +489,7 @@ or fails validation.
 | `PercentField` · `PercentFormField` | `number \| null`, `min` 0, `max` 100, `step` 1 by default | `null` |
 | `QuantityField` · `QuantityFormField` | `{ value: number \| null, unit: string }`. An error on the field, `.value` or `.unit` shows as one message under the pair | `{ value: null, unit: '' }` |
 | `CurrencyField` · `CurrencyFormField` | `number \| null`, the amount only, not rounded. `currency` (default `'EUR'`) and `fractionDigits` (the currency's own decimals by default) are display | `null` |
+| `CalculatorField` · `CalculatorFormField` (`@nxgt/material/calculator-field`) | `number \| null`. `null` when empty; what Apply writes (a currency amount rounded half-up to its decimals, held to `min` / `max`). `onExactValueChange` gets the exact decimal string | `null` |
 | `PhoneField` · `PhoneFormField` | E.164 `string` (`'+33612345678'`), or `null` when empty. `PhoneFormField` reports a non-empty number that is not yet possible as the field error `material.phone-field.incomplete`; `PhoneField` signals it with `onValidityChange`. `defaultCountry` is `'FR'` | `null` |
 | `UrlField` · `UrlFormField` | `string` (as typed) | `''` |
 | `SearchField` · `SearchFormField` | `string`, after `debounceMs` (default `0`) | `''` |

package/docs/guides/i18n.md

@@ -515,6 +515,11 @@ them the merged resources (see "Overriding a component's words" below).
 <Spinner variant="4" />     // role="img" aria-label="Chargement..."
 ```
 
+The calculator's loading state reads `material.calculator.loading` ("Loading the
+calculator"), `material.calculator.load-failed` ("This calculator could not be
+loaded.") and `material.calculator.retry` ("Try again"), shown while a variant
+other than Standard loads on demand or when its download failed.
+
 ### Overriding a component's words
 
 Give the provider the merged resources and every component translates through

package/docs/roadmap.md

@@ -6,8 +6,14 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Now
 
-- **Calculator** — `@nxgt/material/calculator` adds `Calculator`, in six variants (Standard, Scientific, point of sale, Financial, Unit conversion, Programmer) chosen by `variant` or by its own switcher, and `CalculatorField` / `CalculatorFormField`, a number field whose button opens it in a popover, or a bottom sheet on a phone. Every variant shows the whole expression above the result, honours operator precedence and computes in exact decimals (0.1 + 0.2 = 0.3) without `eval`, so a strict CSP holds. A history tape (persisted, with an opt-out), memory keys, the physical keyboard, copy and paste, locale formatting and screen-reader announcements come with each; haptic and sound feedback are opt-in. Point of sale charges through `onCharge(total)`; currency rates come from the app. React only for now; the Vue port is tracked in [#2100](https://github.com/softistx/nxgt-material/issues/2100). Tracked in [#2101](https://github.com/softistx/nxgt-material/issues/2101).
-
+- **Calculator** — `@nxgt/material/calculator` is an exact-decimal calculator
+  (Standard, Scientific, point of sale, Financial, Conversion, Programmer;
+  every variant but Standard loads on demand)
+  with a tape, a memory, the keyboard and screen-reader announcements, and
+  `@nxgt/material/calculator-field` adds `CalculatorField`, a number or
+  currency field whose button opens it. Its stylesheet is opt-in:
+  import `@nxgt/material/calculator.css` after `styles.css`
+  ([guide](guides/calculator.md)).
 - **Barcodes and label sheets** — `@nxgt/material/barcode` draws Code 128
   and Data Matrix as accessible SVG (themed, dark-aware, black on white in
   print) and lays labels out on a sheet to print: label size, columns, rows,
@@ -371,7 +377,7 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
-- **Moment (next minor)** — a transient full-screen announcement for a one-off event (a player is eliminated, a role is revealed): a modal dialog named by its title, with an illustration, description, action and tone, dismissed by Escape, a tap, its action or a timer, and no motion under reduced motion ([#2220](https://github.com/softistx/nxgt-material/issues/2220)).
+- **Moment (3.74.0)** — a transient full-screen announcement for a one-off event (a player is eliminated, a role is revealed): a modal dialog named by its title, with an illustration, description, action and tone, dismissed by Escape, a tap, its action or a timer, and no motion under reduced motion ([#2220](https://github.com/softistx/nxgt-material/issues/2220), [#2247](https://github.com/softistx/nxgt-material/pull/2247)). A `modal={false}` variant for live events (focus stays, taps pass through, polite status) follows in the next minor ([#2313](https://github.com/softistx/nxgt-material/issues/2313)).
 - **RecordActionsMenu (next minor)** — one menu for a record's lifecycle: archive with an Undo toast (or confirm first with `archivePolicy="confirm"`), restore, and delete that always confirms and shows the backend's refusal, with `ConfirmDialog` gaining `details` and `refusal` slots.
 - **Assistant approval card (next minor)** — `ChatActionProposal` shows an action an assistant proposes, with its status, deadline and Confirm / Reject, and `ChatToolActivity` is a compact row for a tool step in a chat thread ([#2134](https://github.com/softistx/nxgt-material/issues/2134)).