feat: native Intl currency and percent formatting via a format prop

[Amanfromearth]

Discussed first in #3, as CONTRIBUTING.md asks for API changes. Happy to close this if the
direction is wrong for the library.

Adds an Intl.NumberFormatOptions-shaped format prop, resolved by each platform's own formatter:
NumberFormatter on iOS, android.icu on Android, Intl on web. The string is produced where it
is drawn, because the renderers animate the structure of a formatted number rather than a string
handed to them ready-made.

<NumericText value={total} currency="USD" />                    // $1,234.50
<NumericText value={total} locale="de-DE" currency="EUR" />     // 1.234,50 €
<NumericText value={rate} format={{ style: 'percent' }} />      // 42%
<NumericText value={-1234.5} format={{ style: 'currency', currency: 'USD', currencySign: 'accounting' }} />
// ($1,234.50)

API

format carries style (decimal/currency/percent), currency, currencyDisplay
(symbol/code/name), currencySign (standard/accounting), useGrouping, minimumIntegerDigits,
and the fraction and significant digit bounds. currency is a top-level shorthand for the common
case. The existing useGrouping, minimumFractionDigits and maximumFractionDigits props stay as
shorthands, so nothing breaks; this is additive.

The shape is borrowed from number-flow by Maxwell
Barvian, credited in the README's Origin section, beside the prop, and in the type's doc comment.

Deliberately not supported, each with a stated reason in the type's doc comment:

Option	Reason
notation: 'compact'	The two platforms carry different CLDR vintages and would disagree on the string for the same input.
signDisplay, narrowSymbol, unit, roundingIncrement	Below one platform's floor (Android's NumberFormatter is API 30; minSdk here is 24).

Two behaviour changes worth reviewing

Digit bounds now follow ECMA-402 exactly, implemented identically in JS, Kotlin and Swift.
Android previously clamped minimumFractionDigits={4} down to 3 while iOS honoured it, because
java.text.NumberFormat pulls the minimum down to meet a lower maximum.

Rounding is pinned to half-away-from-zero, which is Intl's default and neither platform's.
2.5 at zero decimals previously read 3 on web, 2 on iOS and 2 on Android; it now reads 3
everywhere. Not exposed as an option: two renderers disagreeing about the number they draw seemed
like a bug rather than a preference, but this is the change most worth your veto.

Two latent defects this had to close first

Neither is reachable today, because a plain grouped decimal only ever produces digits, group and
decimal marks, and a sign. Both become reachable with currency.

1. Affix keying (fix(android): key affixes by distance from the digits). A token outside the
   number was keyed by its string offset (O$i), so $999 → $1,000 killed the $ at offset 0
   and created a new one at offset 0: a born/died cycle instead of a slide. Keys are now counted
   outward from the nearest end of the number, P0 before the first digit and X0 after the last.
   6 new cases in TransitionLogicTest.

2. Font coverage (chore(android): add currency and latin glyphs...). The bundled subset had
   no $, no € and no letters at all, so a currency format would have driven canRender into
   falling the whole line back to the platform font. Regenerated with .agent/tools/subset_font.sh.
   Cost: 46 → 144 glyphs, ~97 KB → ~300 KB for the nine weights. Digit and separator advances
   are unchanged to four decimals (Regular: 0 = 0.5953, 8 = 0.6057, . = 0.2541), so the
   calibration constants in src/measureBox.ts still hold. This is the other call that is yours:
   dropping A-Z a-z would roughly halve the increase at the cost of currencyDisplay: 'code' and
   'name' losing the rounded face.

Android additionally reads the locale's monetary decimal mark for a currency format, and
re-checks the bundled typeface against the characters the current format will actually draw rather
than against the locale's digits alone.

Verification

Per CONTRIBUTING.md, linters and tests pass on this branch:

• 39 JS tests (src/__tests__/numberFormat.test.ts is new), yarn typecheck, yarn lint
• 25 Kotlin tests, compileDebugKotlin (codegen accepted the new prop spec)
• swiftc -typecheck in both configurations; a full xcodebuild of the example, 0 errors
• Both renderers driven by hand on a simulator through every format: currency symbol, ISO code,
  currency name, accounting brackets, percent, de-DE trailing symbol, integer padding, significant
  digits
• yarn check && yarn prepare && npm pack --dry-run

Not verified against a ground-truth recording. No .agent run has been taken with a currency
format, so the affix's motion during a carry is reasoned-about rather than measured. I know that is
not the bar .agent/AGENTS.md sets ("Measure, then claim"), so I have said so in .agent/NEXT.md
rather than letting it pass silently. Tell me if you would rather that file were left alone
entirely; it is your research log and I am happy to drop that hunk.

Deliberately not included

• No version bump. release-it owns versioning per CONTRIBUTING.md.
• No unrelated tooling changes. I have a one-line eslint fix (**/build/ in the ignores, so a
  local gradlew run does not make yarn lint read Gradle's own test report as source) but left it
  out to keep this focused on one change. Happy to send it separately if useful.

[Amanfromearth]

@AmatoGiulio pls check this

[Amanfromearth]

Pushed one more commit, from a real amount field hitting the case.

value is a number and a number cannot hold 7., so someone typing 7 . 5 produces the values 7, 7, 7.5 and the mark they typed has nowhere to live between the second and third keystroke. The workaround people reach for is a sibling <Text> holding a ., which cannot be made to line up: the view reserves half an em of headroom for the transition's overspill and centres the number inside it, so the distance from the last digit to the right edge is not fixed and moves with both the value and the font.

Measured on an emulator at fontSize 44: the number occupied x 0.391-0.578 of the screen and the sibling dot sat at 0.577-0.608, on a different baseline.

trailingDecimalSeparator makes it a real DEC column instead, so the same state renders as one view whose accessibility label reads $0. rather than $0. It goes after the last digit rather than at the end of the string, so de-DE gives 1.234, €, and it is a no-op once a fraction digit arrives.

Verified before/after on a device, plus 7 new JS cases (46 JS + 25 Kotlin tests green, compileDebugKotlin and swiftc -typecheck clean). Say the word if you would rather this were a separate PR.

[AmatoGiulio]

Thanks for putting this together, this is definitely a direction I wanted the library to cover, and I’m glad you took the time to work through it properly.

The API direction makes sense to me, especially keeping the current props as shorthands and using a native formatter on each platform.

Before merging though, I want to run the full validation pass on my side: visual behavior, interruption/retargeting, locale/currency edge cases, accessibility, and especially the affix motion against a recorded ground truth on iOS/Android.

I also want to look carefully at the font subset size increase and the rounding behavior, since those become part of the library’s long-term contract.

"trailingDecimalSeparator" is interesting too, I’d like to test it separately because it expands the use case a bit toward amount/input flows.

Really appreciate the level of detail here. I’ll start going through the PR properly and report back with anything I find.

[AmatoGiulio]

Thanks @Amanfromearth — the format API direction from this PR was kept and then validated/reworked against the SwiftUI ground truth on Android. The integration-ready successor is #5.

#5 explicitly credits this contribution and keeps the original upstream/intl-formatting branch untouched. I’m closing this PR as superseded so there is a single merge target, while retaining this discussion and branch as the origin of the feature.

[AmatoGiulio]

One final update now that the validation work is complete: #5 has been merged into main.

Thanks again @Amanfromearth — your contribution is what started the currency/percent formatting work in this library. The core API direction from #4 (format plus the currency shorthand, resolved natively per platform) is now part of the shipped implementation, after the additional ground-truth work on affix motion, bidi layout, retargeting/reversals, clipping, accessibility and the final contract cleanup.

A couple of pieces from the original proposal — currencyDisplay: 'name' and trailingDecimalSeparator — were deliberately deferred after validation rather than merged as partially specified behavior.

I’m also adding a permanent acknowledgement in the README so the origin of the feature remains visible beyond the PR history. Really appreciate the work and the level of detail you brought to #4.