react-intl-number-input 0.8.6 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-13
+
+### Added
+
+- Opt-in `controlled` mode that keeps the parent's `value` authoritative when edits are rejected. The default preserves historical optimistic editing.
+- Optional `readOnly` information for custom controls and formatted `aria-valuetext`.
+- Regression tests, library/demo type checking, installed npm tarball checks for CJS, ESM, types, SSR and DOM interactions, and a React 16.8–19 CI compatibility matrix.
+
+### Fixed
+
+- Keep numeric state, formatted text, custom controls and accessibility attributes synchronized when values, bounds, locale or precision change.
+- Avoid rescaling existing numeric state on blur after a precision change.
+- Parse Han decimal and supplementary-plane digits and preserve localized caret positions.
+- Preserve amounts when editing numeric prefixes or suffixes.
+- Enforce `readOnly` for built-in and custom controls.
+- Avoid decimal stepping accumulation within JavaScript's safe integer range.
+- Supply actual input elements and consistent event methods in programmatic change callbacks.
+- Build artifacts during `prepack` and validate the package before publication.
+- Correct README examples, Node.js requirements and the demo's currency hint and accessible input names.
+
+### Changed
+
+- Extract pure numeric helpers while retaining public callback signatures, scaled step units, implied-decimal string values, zero-on-clear behavior and existing element layout.
+- Use `gh-pages` 6.1.1 to avoid the development-only `braces` vulnerability in the newer dependency chain; the demo deployment command is unchanged.
+- Add `npm run release` and a GitHub Actions workflow that publishes with provenance.
+
+## [0.8.7] - 2026-10-01
+
+### Fixed
+
+- Initialize the internal numeric value within `minValue` and `maxValue` bounds so the displayed value, accessibility attributes, and custom controls agree on the first render.
+- Ignore digits in configured prefixes and suffixes when parsing edits.
+- Parse locale-specific digits such as Arabic-Indic numerals.
+- Prevent custom `setValue` controls from changing disabled inputs or accepting non-finite values.
+
+### Added
+
+- Keyboard stepping with Arrow Up and Arrow Down; hold Shift to adjust by ten steps.
+
 ## [0.8.6] - 2026-09-23
 
 This is a maintainer/toolchain release. The published component API is unchanged.

package/CONTRIBUTING.md

@@ -7,7 +7,7 @@ Thank you for your interest in contributing to `react-intl-number-input`.
 - Node.js 20+ (recommended: current Active LTS)
 - npm 10+
 
-These versions are required to build and test the library. Consumers of the published npm package are not constrained by this.
+The package declares Node.js 20+ in `engines`. The runtime component executes in browsers; Node.js is used for installation, builds, tests and publication.
 
 ## Getting started
 
@@ -33,6 +33,9 @@ Open [http://localhost:3001](http://localhost:3001). The demo lives in `example/
 | --- | --- |
 | `npm start` | esbuild dev server for the demo |
 | `npm test` | Run unit tests with Jest |
+| `npm run typecheck` | Check library and demo types |
+| `npm run check` | Tests, type checking, library builds and installed-tarball validation |
+| `npm run check:package` | Validate the built npm tarball: CJS, ESM, types, SSR and DOM interactions |
 | `npm run build:lib` | Compile `src/` to CommonJS, ESM, and types in `dist/` |
 | `npm run build` | Build the demo bundle in `example/dist` |
 | `npm run publish-demo` | Build and deploy the demo to GitHub Pages |
@@ -52,10 +55,10 @@ The npm package ships `dist/`, `README.md`, `LICENSE`, `CHANGELOG.md`, and `CONT
 Run the full test suite before opening a pull request:
 
 ```bash
-npm test
+npm run check
 ```
 
-Tests live alongside the source in `src/index.test.tsx`.
+Tests live alongside the source in `src/index.test.tsx` and `src/regressions.test.tsx`. CI also checks the installed package with React 16.8, 17, 18 and 19, and runs the full checks on Node.js 20 and 24.
 
 ## Building the library
 
@@ -73,36 +76,58 @@ This generates:
 
 ## Publishing to npm
 
-### Prerequisites
+### Ownership & Accounts
 
-- npm account with publish access to `react-intl-number-input`
-- logged in: `npm login`
+The package is published under the npm account **`wipmob`** (`nandorip@live.com`).
 
-### Release checklist
+> **Tip (Co-Maintainer):** To allow publishing from the `nandorip` account as well, add it via npm CLI or web interface:
+> ```bash
+> npm owner add nandorip react-intl-number-input
+> ```
+> Or manage collaborators at [npmjs.com/package/react-intl-number-input/access](https://www.npmjs.com/package/react-intl-number-input/access).
 
-1. Update `CHANGELOG.md` with the new version and changes.
-2. Bump the version in `package.json` following [semver](https://semver.org/):
+### Method 1: Automated Release via GitHub Actions (Recommended)
+
+This repository includes an automated workflow ([`.github/workflows/publish.yml`](.github/workflows/publish.yml)) with npm provenance attestations. This avoids local 2FA prompts and terminal issues.
+
+1. **One-time setup:**
+   - In your npm account (**`wipmob`**), generate an **Automation Token** or **Granular Access Token** with *Read and write* permissions for `react-intl-number-input`.
+   - In GitHub, go to **Settings > Secrets and variables > Actions** and add `NPM_TOKEN` with your token.
+2. **Publishing a release:**
+   - Create a new Release on GitHub (e.g. `v0.9.0`), or trigger the workflow manually under **Actions > Publish to npm > Run workflow**.
+   - GitHub Actions will run all checks, build, verify the tarball, and publish with `--provenance` automatically.
+
+### Method 2: Local CLI Release (`npm run release`)
+
+A release helper script is available to validate requirements, run the test suite, and publish:
+
+1. **Verify login:**
    ```bash
-   npm version patch   # 0.7.0 → 0.7.1
-   npm version minor   # 0.7.0 → 0.8.0
-   npm version major   # 0.7.0 → 1.0.0
+   npm whoami   # Should return 'wipmob' (or 'nandorip' if added as owner)
    ```
-3. Publish:
+   If not logged in: `npm login`.
+2. **Bump version (if not already done):**
    ```bash
-   npm publish
+   npm version patch   # or minor / major
+   ```
+3. **Execute release:**
+   ```bash
+   npm run release
+   ```
+   If your account requires 2FA and you are in a non-interactive shell, pass the OTP directly:
+   ```bash
+   npm run release -- --otp=123456
    ```
 
-The `prepublishOnly` script runs automatically before publish:
-
-```
-npm test → npm run build:lib
-```
-
-Do not commit `dist/` — it is built during publish and excluded via `.gitignore`.
+The script automatically:
+- Confirms the active npm user.
+- Runs `npm run check` (Jest tests, TypeScript, library builds, tarball verification).
+- Runs `npm publish`.
+- Creates and pushes the git tag `v<version>`.
 
 ### Deploying the demo
 
-To update the live demo on GitHub Pages:
+To update the live demo on GitHub Pages independently:
 
 ```bash
 npm run publish-demo
@@ -112,9 +137,9 @@ npm run publish-demo
 
 1. Fork the repository and create a feature branch.
 2. Make your changes with tests where applicable.
-3. Run `npm test` and ensure it passes.
+3. Run `npm run check` and ensure it passes.
 4. Open a pull request with a clear description of the change.
 
 ## Reporting issues
 
-Open an issue at [github.com/nandorip/react-intl-number-input/issues](https://github.com/nandorip/react-intl-number-input/issues).
+Open an issue at [github.com/nandorip/react-intl-number-input/issues](https://github.com/nandorip/react-intl-number-input/issues).

package/README.md

@@ -1,12 +1,13 @@
 # react-intl-number-input
 
-A React component for masked and formatted number input with `Intl.NumberFormat` locale support.
+A React number input with implied decimal places and locale formatting through `Intl.NumberFormat`. For money-style entry, typing `1234` with two decimal places produces `12.34`.
 
-[Demo](https://nandorip.github.io/react-intl-number-input/example/dist/)
+[Interactive demo](https://nandorip.github.io/react-intl-number-input/)
 
 ## Requirements
 
 - React: `>=16.8.0 <20`
+- Node.js: `>=20` for installation and local development (declared in the npm package's `engines` field). The component runs in the browser.
 
 ## Install
 
@@ -55,7 +56,7 @@ function App() {
     console.log('Numeric:', val, 'Masked:', masked);
   };
 
-  return <IntlNumberInput value={value} onChange={handleChange} locale="pt-BR" />;
+  return <IntlNumberInput controlled value={value} onChange={handleChange} locale="pt-BR" />;
 }
 ```
 
@@ -80,7 +81,8 @@ ReactDOM.render(<App />, document.getElementById('root'));
 
 | Name | Type | Default | Description |
 | --- | --- | :---: | --- |
-| value | `number` \| `string` | `0` | Controlled numeric value |
+| value | `number` \| `string` | `0` | Initial/synchronized value; numbers use numeric units, strings use implied-decimal parsing |
+| controlled | `boolean` | `false` | Keep `value` authoritative, including when the parent rejects an edit |
 | locale | `string` | `'en-US'` | BCP 47 language tag ([Intl locales](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation)) |
 | prefix | `string` | `''` | Prefix shown in the masked value |
 | suffix | `string` | `''` | Suffix shown in the masked value |
@@ -93,7 +95,7 @@ ReactDOM.render(<App />, document.getElementById('root'));
 | maxValue | `number` | — | Maximum allowed value |
 | showStepButtons | `boolean` | `false` | Renders built-in +/- step buttons (ignored when `renderControls` is set) |
 | renderControls | `function` | — | `(props: ControlsRenderProps) => ReactNode` — custom stepper UI |
-| step | `number` | `1` | Step increment in display units (e.g. `1` with `precision={2}` adds `0.01`) |
+| step | `number` | `1` | Step in scaled digit units: the increment is `step / 10 ** precision` (e.g. `1` with `precision={2}` adds `0.01`) |
 | inputMode | `'numeric'` \| `'decimal'` | auto | Overrides mobile keyboard mode |
 | className | `string` | — | Input CSS class |
 | style | `object` | — | Input inline styles |
@@ -106,13 +108,37 @@ ReactDOM.render(<App />, document.getElementById('root'));
 
 The component also accepts standard `<input>` attributes such as `ref`, `onFocus`, `onKeyDown`, `aria-*`, `data-*`, and `autoComplete`. Custom `onChange` and `onBlur` callbacks receive the clamped numeric value and the formatted masked string.
 
+### Value modes and compatibility
+
+By default, the component preserves its historical behavior: `value` initializes the field and a changed `value` updates it, while local edits remain visible if the parent leaves `value` unchanged. Without `value`, the component manages its own numeric state.
+
+For strict controlled behavior, use `controlled` and update `value` from `onChange`. Rejected edits emit the proposed numeric value and mask, but the input and custom controls retain the parent's value:
+
+```jsx
+<IntlNumberInput
+  controlled
+  value={value}
+  onChange={(_event, nextValue) => setValue(nextValue)}
+/>
+```
+
+The default remains compatible with existing integrations, including those that use a fixed `value` as an initial amount. `controlled` requires no changes to callback signatures.
+
+String values use the same implied-decimal parser as typing: with `precision={2}`, `value="1234"` means `12.34`, while `value={1234}` means `1,234.00`. Prefer numbers for programmatic values. Changing precision reformats existing internal numeric state without rescaling it; rounding for display does not discard hidden fraction digits.
+
+Typing forwards the original React change event. Buttons and custom setters deliver a programmatic change event whose `target` and `currentTarget` are the actual input element, containing the proposed mask during the callback. Use the second and third callback arguments for numeric and formatted values consistently across both kinds of changes. These programmatic callbacks do not dispatch an additional DOM change event.
+
 ## Accessibility (a11y)
 
-The component is built with accessibility in mind:
-- Uses `role="spinbutton"` to identify as a numeric input.
-- Provides `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` attributes.
-- Support for `forwardRef` allows linking labels and managing focus programmatically.
-- Built-in step buttons have descriptive `aria-label` attributes.
+The component is built with accessibility in mind:
+- Uses `role="spinbutton"` to identify as a numeric input.
+- Provides `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` attributes.
+- Provides the formatted value as `aria-valuetext`, including any prefix and suffix.
+- Supports Arrow Up and Arrow Down to adjust by one step; Shift plus an arrow adjusts by ten steps. Your `onKeyDown` handler runs first and can prevent the adjustment.
+- Support for `forwardRef` allows linking labels and managing focus programmatically.
+- Built-in step buttons have descriptive `aria-label` attributes.
+
+Associate each input with a visible `<label htmlFor="...">`, `aria-labelledby`, or `aria-label`. `readOnly` prevents changes from typing, arrow keys, built-in buttons and custom setters; custom controls also receive `readOnly`.
 
 ## Examples
 
@@ -120,32 +146,32 @@ The component is built with accessibility in mind:
 
 ```javascript
 // maskedValue: 1,234,567.89
-<IntlNumberInput />
+<IntlNumberInput value={1234567.89} />
 ```
 
 ```javascript
 // maskedValue: 12,345.6789
-<IntlNumberInput precision={4} />
+<IntlNumberInput value={12345.6789} precision={4} />
 ```
 
 ```javascript
 // maskedValue: $1,234,567.89
-<IntlNumberInput prefix="$" />
+<IntlNumberInput value={1234567.89} prefix="$" />
 ```
 
 ```javascript
 // maskedValue: 1,234%
-<IntlNumberInput suffix="%" precision={0} />
+<IntlNumberInput value={1234} suffix="%" precision={0} />
 ```
 
 ```javascript
 // maskedValue: 12.50% — type digits only; decimal is implied by precision
-<IntlNumberInput suffix="%" precision={2} />
+<IntlNumberInput value={12.5} suffix="%" precision={2} />
 ```
 
 ```javascript
 // maskedValue: R$ 1.234.567,89
-<IntlNumberInput locale="pt-BR" prefix="R$ " precision={2} />
+<IntlNumberInput value={1234567.89} locale="pt-BR" prefix="R$ " precision={2} />
 ```
 
 ```javascript
@@ -171,12 +197,12 @@ The component is built with accessibility in mind:
     minValue={0}
     maxValue={100}
     onChange={(event, value) => console.log(value)}
-    renderControls={({ increment, decrement, setValue, value, formattedValue, min, max, disabled }) => (
+    renderControls={({ increment, decrement, setValue, value, formattedValue, min, max, disabled, readOnly }) => (
       <div className="amount-controls">
-        <button type="button" onClick={() => decrement()} disabled={disabled}>-</button>
+        <button type="button" onClick={() => decrement()} disabled={disabled || readOnly}>-</button>
         <span>{formattedValue}</span>
-        <button type="button" onClick={() => increment()} disabled={disabled}>+</button>
-        <button type="button" onClick={() => setValue(max ?? value)} disabled={disabled}>
+        <button type="button" onClick={() => increment()} disabled={disabled || readOnly}>+</button>
+        <button type="button" onClick={() => setValue(max ?? value)} disabled={disabled || readOnly}>
           Max
         </button>
       </div>
@@ -211,12 +237,18 @@ function FocusExample() {
 
 Users type digits; the component applies locale formatting and optional prefix/suffix. For `precision={2}`, typing `1234` becomes `12.34`. Negative values are supported when `-` is present in the input.
 
+ASCII digits and the locale's digits are accepted, including Arabic-Indic, Han decimal and supplementary-plane digits. Edits confined to the configured prefix or suffix preserve the amount and restore the affix. Prefixes and suffixes are display adornments; a `%` suffix does not multiply or divide the numeric value.
+
+For compatibility, clearing the input produces zero (or the nearest allowed bound). Empty and missing values are not represented separately: `required` cannot detect a missing amount and `placeholder` is normally hidden. Validate absence separately in your form if needed. Bounds apply immediately; typing an intermediate value below the minimum may therefore clamp it before typing is complete.
+
+The numeric API uses JavaScript `number`. Precision controls formatting, not arbitrary-precision arithmetic. Stepping avoids floating-point accumulation when the scaled operands fit safe integers; very large values or high precision retain the limitations of JavaScript numbers.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and publishing instructions.
 
-Local development requires Node.js 20+. The published package has no Node.js version constraint for consumers.
+Before publishing, run `npm run check`. It verifies tests, the demo's types, both builds and an installed npm tarball, including its type declarations and runtime entry points.
 
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md) for release history.
+See [CHANGELOG.md](CHANGELOG.md) for release history.

package/dist/esm/index.d.ts

@@ -0,0 +1,34 @@
+import React from 'react';
+export interface ControlsRenderProps {
+    increment: (multiplier?: number) => void;
+    decrement: (multiplier?: number) => void;
+    setValue: (value: number) => void;
+    value: number;
+    min?: number;
+    max?: number;
+    disabled: boolean;
+    readOnly?: boolean;
+    step: number;
+    precision: number;
+    formattedValue: string;
+}
+type IntlNumberInputOwnProps = {
+    locale?: string;
+    prefix?: string;
+    suffix?: string;
+    precision?: number;
+    value?: number | string;
+    /** Opt in to keeping value authoritative when the parent rejects an edit. */
+    controlled?: boolean;
+    showStepButtons?: boolean;
+    step?: number;
+    minValue?: number;
+    maxValue?: number;
+    inputMode?: 'numeric' | 'decimal';
+    onChange?: (event: React.ChangeEvent<HTMLInputElement>, value: number, maskedValue: string) => void;
+    onBlur?: (event: React.FocusEvent<HTMLInputElement>, value: number, maskedValue: string) => void;
+    renderControls?: (props: ControlsRenderProps) => React.ReactNode;
+};
+export type IntlNumberInputProps = IntlNumberInputOwnProps & Omit<React.ComponentPropsWithoutRef<'input'>, keyof IntlNumberInputOwnProps | 'value' | 'type' | 'defaultValue' | 'children'>;
+declare const _default: React.NamedExoticComponent<IntlNumberInputOwnProps & Omit<Omit<React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "children" | "defaultValue" | "type" | keyof IntlNumberInputOwnProps> & React.RefAttributes<HTMLInputElement>>;
+export default _default;