@scattered-light/loomiere-base-ui 0.6.1 → 0.7.0

package/dist/design-system/components/MoneyField/README.md

@@ -0,0 +1,52 @@
+# MoneyField
+
+Loomiere component, not part of Base UI. An amount of money, built on Number field. The value is an integer in minor units (cents, yen, fils) so 0.1 + 0.2 and 1.005 * 100 cannot drift, and so the number matches what a payment API sends. Number field counts in major units; Money field converts at the edge and rounds half away from zero. The default maximum is 10^15 - 1 minor units, so the major amount stays inside 15 significant digits. Changing currency keeps the number the person typed and re-rounds it to the new currency's digits (12.50 USD becomes 13 JPY). There is no exchange rate. When the app controls both the value and the currency, it decides whether to apply that rounding: onValueChange still reports the re-rounded minor units. Keyboard is Number field's: ArrowUp and ArrowDown step one major unit, Shift steps 100 major units, Alt steps one minor unit, Home and End jump to the minimum and maximum. The currency symbol is not in the text, so the caret does not fight it. A fixed symbol is aria-hidden; the currency name is in the input's accessible description. A picker is its own tab stop, before the input when the locale puts the symbol first and after it when the locale puts the symbol last. State on the root: data-currency (USD), data-affix (start or end), data-affix-kind (symbol or picker), data-negative (below zero; set data-color on the field to color it, never on by default), data-align (start or end), data-size (xs, sm, md, lg), data-readonly, plus data-invalid, data-disabled, data-focused and data-scrubbing. The affix (symbol or picker) is drawn inside the field so it can later be lifted into a general Input affix for units, https://, or @. Position comes from the locale, with logical properties so RTL mirrors it. The group, not the input, carries the field border, hover, focus halo, invalid edge and disabled fill, so the affix reads as part of the field.
+
+Use `Loomiere.MoneyField`, this package's component: it puts the class names on for you (`import { MoneyField } from '@scattered-light/loomiere-base-ui'`, or from `@scattered-light/loomiere-base-ui/custom`).
+
+Not a Base UI part, so there is no base-ui.com page for it.
+
+## Classes
+
+| Class | Data attributes it answers to |
+|---|---|
+| `MoneyField` | `data-size`: `xs`, `sm`, `lg`; `data-invalid`; `data-disabled`; `data-affix-kind`: `symbol`; `data-affix`: `start`, `end`; `data-steppers`; `data-align`: `end`, `start`; `data-focused`; `data-readonly`; `data-negative`; `data-color`; `data-scrubbing` |
+| `MoneyFieldGroup` |   |
+| `MoneyFieldInput` |   |
+| `MoneyFieldAffix` |   |
+| `MoneyFieldCurrencyTrigger` | `data-popup-open` |
+| `MoneyFieldSign` |   |
+| `MoneyFieldCurrency` |   |
+| `MoneyFieldCurrencyField` |   |
+| `ComboboxRoot` |   |
+| `MoneyFieldCurrencyIcon` |   |
+| `MoneyFieldCurrencyPopup` |   |
+| `MoneyFieldCurrencyItem` |   |
+| `MoneyFieldCurrencySymbol` |   |
+| `ComboboxInput` |   |
+
+Base UI sets the state attributes (`data-checked`, `data-open`, `data-disabled`...) itself. Set `data-size`, `data-emphasis`, `data-variant` and `data-color` yourself; `data-color` takes any palette name (`primary`, `secondary`, `error`...) and repaints the part in it.
+
+## Example
+
+From the MoneyField stories (`Default`):
+
+```tsx
+export const Default: Story = {
+  render: () => (
+    <Labeled>
+      <MoneyField currency="USD" defaultValue={123450} name="amount" />
+    </Labeled>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByRole('textbox');
+    await userEvent.clear(input);
+    await userEvent.type(input, '1234.5');
+    await userEvent.tab();
+    await expect(input).toHaveValue('1,234.50');
+  },
+};
+```
+
+The preview also shows `Yen`, `Dinar`, `EuroInGerman`.