@djangocfg/ui-core 2.1.543 → 2.1.544

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.543",
+  "version": "2.1.544",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -130,7 +130,7 @@
     "check:contrast": "node scripts/check-preset-contrast.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.543",
+    "@djangocfg/i18n": "^2.1.544",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -206,9 +206,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/eslint-config": "^2.1.543",
-    "@djangocfg/i18n": "^2.1.543",
-    "@djangocfg/typescript-config": "^2.1.543",
+    "@djangocfg/eslint-config": "^2.1.544",
+    "@djangocfg/i18n": "^2.1.544",
+    "@djangocfg/typescript-config": "^2.1.544",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",

package/src/components/forms/money-field/README.md

@@ -59,11 +59,34 @@ the dependency direction and may not depend on it.
 | `defaultValue` | `number` | Uncontrolled initial amount, minor units. |
 | `onValueChange` | `(minorUnits: number) => void` | |
 | `currency` | `string` | ISO 4217. Drives symbol, decimals, minor-unit factor. Default `USD`. |
+| `fractionDigits` | `number` | Overrides the currency's decimals. `0` makes the field whole-unit — see below. |
 | `locale` | `string` | BCP 47. Defaults to the runtime's. |
 | `showSymbol` | `boolean` | Default `true`. Set false when the label carries the unit. |
 | `max` | `number` | Minor units. Entry beyond it is ignored, not clamped after the fact. |
 | `groupClassName` | `string` | Applied to the group, to size the whole control. |
 
+## Whole amounts
+
+The default suits money that is paid — a price, an invoice, a charge. It does
+not suit money that is merely large. On a property asking price the cents are
+two zeros the reader looks past and, because entry is right-anchored, two
+keystrokes they have to type: 1,400,000 costs nine digits, not seven.
+
+`fractionDigits={0}` makes the field whole-unit:
+
+```tsx
+const [asking, setAsking] = useState(1_400_000);   // dollars, not cents
+
+<MoneyField currency="USD" fractionDigits={0} value={asking} onValueChange={setAsking} />
+// shows "1,400,000"; typing 1400000 reads as 1,400,000
+```
+
+**The unit of `value` follows this prop.** Minor units at the default, major
+units at `0` — the component divides by `10 ** fractionDigits`, so a caller
+that changes the prop must change what it stores. This is deliberate: an
+integer at any precision keeps the exactness the component exists for, and a
+field that reported cents while displaying whole dollars would be a trap.
+
 ## Accessibility
 
 The currency symbol is `aria-hidden` — a screen reader announcing "dollar sign"

package/src/components/forms/money-field/index.tsx

@@ -59,14 +59,22 @@ function currencySymbol(currency: string, locale: string | undefined): string {
 // Format / parse
 // =============================================================================
 
+/** Minor units per major unit for a given precision — 100 at two digits, 1 at none. */
+function factorFor(digits: number): number {
+  return 10 ** digits;
+}
+
 /** Format minor units for display, grouped and with the locale's separators. */
-function formatMinor(minor: number, currency: string, locale: string | undefined): string {
-  const digits = currencyFractionDigits(currency);
+function formatMinor(
+  minor: number,
+  digits: number,
+  locale: string | undefined,
+): string {
   return new Intl.NumberFormat(locale, {
     minimumFractionDigits: digits,
     maximumFractionDigits: digits,
     useGrouping: true,
-  }).format(minor / minorUnitFactor(currency));
+  }).format(minor / factorFor(digits));
 }
 
 /**
@@ -77,7 +85,7 @@ function formatMinor(minor: number, currency: string, locale: string | undefined
  * entry people expect from a money field, and the reason the caret never has
  * to sit "before the decimal point".
  */
-function parseToMinor(raw: string, _currency: string): number {
+function parseToMinor(raw: string): number {
   const digits = raw.replace(/\D/g, '');
   if (!digits) return 0;
   // Number, not parseInt: 16 digits of cents is past MAX_SAFE_INTEGER, and
@@ -133,6 +141,21 @@ export interface MoneyFieldProps
   onValueChange?: (minorUnits: number) => void;
   /** ISO 4217 code — drives the symbol, the decimals and the minor-unit factor. */
   currency?: string;
+  /**
+   * Digits after the decimal separator, overriding the currency's own.
+   *
+   * The default is right for money that is paid: a price, an invoice, a
+   * charge. It is wrong for money that is merely large — a property asking
+   * price, a valuation, a budget — where the cents are always two zeros the
+   * reader has to look past and two keystrokes they have to type, since entry
+   * is right-anchored.
+   *
+   * `0` makes the field whole-unit: `value` is then dollars rather than cents,
+   * and typing "1400000" reads as 1,400,000. The unit of `value` always
+   * follows this — minor units at 2, major units at 0 — so a caller that
+   * changes it must change what it stores.
+   */
+  fractionDigits?: number;
   /** BCP 47 tag for separators and symbol placement. Defaults to the runtime's. */
   locale?: string;
   /** Show the currency symbol before the input. Set false when the label carries it. */
@@ -177,6 +200,7 @@ const MoneyField = React.forwardRef<HTMLInputElement, MoneyFieldProps>(
       defaultValue,
       onValueChange,
       currency = 'USD',
+      fractionDigits,
       locale,
       showSymbol = true,
       max,
@@ -195,9 +219,11 @@ const MoneyField = React.forwardRef<HTMLInputElement, MoneyFieldProps>(
     const [internal, setInternal] = React.useState<number>(defaultValue ?? 0);
     const minor = isControlled ? value : internal;
 
+    const digits = fractionDigits ?? currencyFractionDigits(currency);
+
     const display = React.useMemo(
-      () => formatMinor(minor, currency, locale),
-      [minor, currency, locale],
+      () => formatMinor(minor, digits, locale),
+      [minor, digits, locale],
     );
     const symbol = React.useMemo(
       () => currencySymbol(currency, locale),
@@ -230,7 +256,7 @@ const MoneyField = React.forwardRef<HTMLInputElement, MoneyFieldProps>(
         const typed = el.value;
         const caret = el.selectionStart ?? typed.length;
 
-        let next = parseToMinor(typed, currency);
+        let next = parseToMinor(typed);
         if (max !== undefined && next > max) next = max;
 
         // Anchor on digits to the LEFT of the caret, which regrouping cannot
@@ -242,12 +268,12 @@ const MoneyField = React.forwardRef<HTMLInputElement, MoneyFieldProps>(
           typed.length < display.length && digitsLeft === digitsBefore(display, caret + 1);
         if (deletedSeparator && digitsLeft > 0) digitsLeft -= 1;
 
-        const nextDisplay = formatMinor(next, currency, locale);
+        const nextDisplay = formatMinor(next, digits, locale);
         pendingCaretRef.current = offsetAfterDigits(nextDisplay, digitsLeft);
 
         commit(next);
       },
-      [commit, currency, display, locale, max],
+      [commit, digits, display, locale, max],
     );
 
     return (