react-bigint-input 1.0.0

package/README.md

@@ -0,0 +1,157 @@
+<p align="center">
+  <h1 align="center">🔢 react-bigint-input</h1>
+  <p align="center">
+    A precision numeric input for BigInt values. Built for DeFi.
+    <br />
+    <strong>Zero dependencies · TypeScript · Locale-aware</strong>
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/react-bigint-input"><img src="https://img.shields.io/npm/v/react-bigint-input?color=904bff&label=npm" alt="npm" /></a>
+  <a href="https://bundlephobia.com/package/react-bigint-input"><img src="https://img.shields.io/bundlephobia/minzip/react-bigint-input?color=904bff&label=size" alt="bundle size" /></a>
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero deps" />
+  <img src="https://img.shields.io/badge/react-%3E%3D17-61dafb" alt="react >=17" />
+</p>
+
+---
+
+## ✨ Features
+
+- 🧮 **True BigInt** — no floating point, no precision loss
+- 🌍 **Locale-aware formatting** — `1,000.50` or `1.000,50` or `1,00,000` — auto-detects or configure per-locale
+- 🔢 **Configurable decimals** — set 18 for ETH, 6 for USDC, or any token precision
+- 📋 **Paste handling** — sanitizes pasted values
+- 🎯 **Min/max clamping** — enforced on every keystroke
+- 📦 **Zero dependencies** — no ethers or viem required
+- 🏗️ **Works everywhere** — React 17, 18, and 19
+
+## 📦 Install
+
+```bash
+npm install react-bigint-input
+```
+
+## 🚀 Quick Start
+
+```tsx
+import { useState } from 'react'
+import { BigIntInput } from 'react-bigint-input'
+
+function SwapForm() {
+    const [amount, setAmount] = useState(0n)
+
+    return (
+        <BigIntInput
+            value={amount}
+            decimals={18}
+            onChange={setAmount}
+        />
+    )
+}
+```
+
+## 🌍 Formatting
+
+By default, numbers are formatted US-style (`1,000.50`). Most crypto users are familiar with this format regardless of locale.
+
+> ⚠️ Changing the format can confuse users who expect US formatting. Use at your own risk.
+
+```tsx
+// Default (US): 1,000.50 — recommended for most crypto apps
+<BigIntInput value={amount} decimals={18} onChange={setAmount} />
+
+// Auto (browser locale)
+<BigIntInput value={amount} decimals={18} onChange={setAmount} format="auto" />
+
+// Specific locale (Indian: 1,00,000 / German: 1.000,50)
+<BigIntInput value={amount} decimals={18} onChange={setAmount} format={{ locale: 'en-IN' }} />
+<BigIntInput value={amount} decimals={18} onChange={setAmount} format={{ locale: 'de-DE' }} />
+
+// Custom separators
+<BigIntInput value={amount} decimals={18} onChange={setAmount} format={{ thousand: '.', decimal: ',' }} />
+
+// No formatting (raw digits): 1000.50
+<BigIntInput value={amount} decimals={18} onChange={setAmount} format="none" />
+```
+
+## 🎯 Min / Max
+
+```tsx
+<BigIntInput
+    value={amount}
+    decimals={6}
+    onChange={setAmount}
+    max={100000000n}  // 100 USDC
+    min={1000000n}    // 1 USDC
+/>
+```
+
+Values are clamped on every keystroke — no invalid states.
+
+## 📐 Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `bigint` | — | Current value in smallest unit (e.g. wei) |
+| `decimals` | `number` | — | Token decimals (18 for ETH, 6 for USDC) |
+| `onChange` | `(v: bigint) => void` | — | Fires when value changes |
+| `max` | `bigint` | — | Clamp to maximum |
+| `min` | `bigint` | — | Clamp to minimum |
+| `format` | `FormatConfig \| "auto" \| "none"` | `{ thousand: ",", decimal: "." }` | Number formatting |
+| `allowNegative` | `boolean` | `false` | Allow negative values |
+| `showZero` | `boolean` | `false` | Show "0" instead of empty |
+| `placeholder` | `string` | `"0"` | Placeholder text |
+| `disabled` | `boolean` | `false` | Disable input |
+| `readOnly` | `boolean` | `false` | Read-only mode |
+| `className` | `string` | — | CSS class |
+| `style` | `CSSProperties` | — | Inline styles |
+
+Plus: `name`, `id`, `autoFocus`, `onFocus`, `onBlur`.
+
+### FormatConfig
+
+```ts
+interface FormatConfig {
+    locale?: string   // Use Intl.NumberFormat with this locale (e.g. 'de-DE', 'en-IN')
+    thousand?: string // Thousands separator (default: ',')
+    decimal?: string  // Decimal separator (default: '.')
+}
+```
+
+When `locale` is set, grouping uses `Intl.NumberFormat` (handles Indian lakh/crore, etc.). `thousand` and `decimal` can override the detected separators.
+
+## 🧰 Utilities
+
+Format and parse BigInt values outside the input:
+
+```ts
+import { formatValue, parseValue } from 'react-bigint-input'
+
+// Format for display
+formatValue(1234567890n, 6)                        // "1,234.56789"
+formatValue(1234567890n, 6, { locale: 'de-DE' })   // "1.234,56789"
+formatValue(1234567890n, 6, 'none')                 // "1234.56789"
+
+// Parse back to BigInt
+parseValue('1,234.56789', 6)                        // 1234567890n
+parseValue('1.234,56789', 6, { locale: 'de-DE' })   // 1234567890n
+```
+
+Same `format` config as the component prop.
+
+## 🤔 Why?
+
+Every crypto project builds a BigInt input from scratch. Most have bugs:
+
+- 💥 Crash when switching token decimals mid-input
+- 🔢 Floating point precision errors (`0.1 + 0.2 ≠ 0.3`)
+- 📋 Can't handle paste or edge cases
+- 📚 Depend on ethers/viem just for `formatUnits`
+- 🔤 No separator support or cursor jumps around
+
+This package does one thing well.
+
+## 📄 License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,117 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { Component } from 'react';
+
+interface FormatConfig {
+    /** Use Intl.NumberFormat with this locale for grouping (e.g. 'de-DE', 'en-IN') */
+    locale?: string;
+    /** Thousands grouping character (e.g. ',' → 1,000) */
+    thousand?: string;
+    /** Decimal point character (e.g. '.' → 1.5) */
+    decimal?: string;
+}
+interface BigIntInputProps {
+    /** Current value as BigInt in smallest unit (e.g. wei) */
+    value: bigint;
+    /** Token decimals (e.g. 18 for ETH, 6 for USDC) */
+    decimals: number;
+    /** Fires when the BigInt value changes */
+    onChange: (value: bigint) => void;
+    /** Maximum allowed value (clamped on input) */
+    max?: bigint;
+    /** Minimum allowed value (clamped on input) */
+    min?: bigint;
+    /** Number formatting — "auto" (browser locale), "none" (raw digits), or a config object */
+    format?: FormatConfig | 'auto' | 'none';
+    /** Allow negative values (default: false) */
+    allowNegative?: boolean;
+    /** Render "0" instead of empty when value is 0n */
+    showZero?: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Disable the input */
+    disabled?: boolean;
+    /** Read-only mode */
+    readOnly?: boolean;
+    /** CSS class name */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+    /** HTML name attribute */
+    name?: string;
+    /** HTML id attribute */
+    id?: string;
+    /** Auto-focus on mount */
+    autoFocus?: boolean;
+    /** Focus callback */
+    onFocus?: (e: React.FocusEvent<HTMLInputElement>) => void;
+    /** Blur callback */
+    onBlur?: (e: React.FocusEvent<HTMLInputElement>) => void;
+}
+interface BigIntInputState {
+    display: string;
+    focused: boolean;
+}
+declare class BigIntInput extends Component<BigIntInputProps, BigIntInputState> {
+    private inputRef;
+    private _resolvedFormat;
+    private _intlFormatter;
+    private _prevFormatProp;
+    private pendingCursor;
+    static defaultProps: {
+        showZero: boolean;
+        placeholder: string;
+        format: {
+            thousand: string;
+            decimal: string;
+        };
+        allowNegative: boolean;
+    };
+    constructor(props: BigIntInputProps);
+    private get fmt();
+    private formatChanged;
+    private addThousands;
+    private removeThousands;
+    private digitIndex;
+    private cursorFromDigitIndex;
+    private valueToDisplay;
+    private sanitize;
+    componentDidUpdate(prevProps: BigIntInputProps, _prevState: BigIntInputState): void;
+    private handleChange;
+    private handleKeyDown;
+    private handleFocus;
+    private handleBlur;
+    private handlePaste;
+    focus(): void;
+    blur(): void;
+    select(): void;
+    render(): react_jsx_runtime.JSX.Element;
+}
+
+/**
+ * Format a BigInt value with thousands/decimal separators.
+ *
+ * formatValue(1500000n, 6)                        → "1.5"
+ * formatValue(1234567890n, 6)                      → "1,234.56789"
+ * formatValue(1234567890n, 6, { locale: 'de-DE' }) → "1.234,56789"
+ * formatValue(1234567890n, 6, 'none')              → "1234.56789"
+ */
+declare function formatValue(value: bigint, decimals: number, format?: {
+    locale?: string;
+    thousand?: string;
+    decimal?: string;
+} | 'auto' | 'none'): string;
+/**
+ * Parse a formatted string back into a BigInt value.
+ *
+ * parseValue("1,500.50", 6)                        → 1500500000n
+ * parseValue("1.500,50", 6, { locale: 'de-DE' })   → 1500500000n
+ * parseValue("1500", 6, 'none')                     → 1500000000n
+ * parseValue("1,00,000", 6, { locale: 'en-IN' })   → 100000000000n
+ */
+declare function parseValue(value: string, decimals: number, format?: {
+    locale?: string;
+    thousand?: string;
+    decimal?: string;
+} | 'auto' | 'none'): bigint;
+
+export { BigIntInput, type BigIntInputProps, type FormatConfig, formatValue, parseValue };

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { Component } from 'react';
+
+interface FormatConfig {
+    /** Use Intl.NumberFormat with this locale for grouping (e.g. 'de-DE', 'en-IN') */
+    locale?: string;
+    /** Thousands grouping character (e.g. ',' → 1,000) */
+    thousand?: string;
+    /** Decimal point character (e.g. '.' → 1.5) */
+    decimal?: string;
+}
+interface BigIntInputProps {
+    /** Current value as BigInt in smallest unit (e.g. wei) */
+    value: bigint;
+    /** Token decimals (e.g. 18 for ETH, 6 for USDC) */
+    decimals: number;
+    /** Fires when the BigInt value changes */
+    onChange: (value: bigint) => void;
+    /** Maximum allowed value (clamped on input) */
+    max?: bigint;
+    /** Minimum allowed value (clamped on input) */
+    min?: bigint;
+    /** Number formatting — "auto" (browser locale), "none" (raw digits), or a config object */
+    format?: FormatConfig | 'auto' | 'none';
+    /** Allow negative values (default: false) */
+    allowNegative?: boolean;
+    /** Render "0" instead of empty when value is 0n */
+    showZero?: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Disable the input */
+    disabled?: boolean;
+    /** Read-only mode */
+    readOnly?: boolean;
+    /** CSS class name */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+    /** HTML name attribute */
+    name?: string;
+    /** HTML id attribute */
+    id?: string;
+    /** Auto-focus on mount */
+    autoFocus?: boolean;
+    /** Focus callback */
+    onFocus?: (e: React.FocusEvent<HTMLInputElement>) => void;
+    /** Blur callback */
+    onBlur?: (e: React.FocusEvent<HTMLInputElement>) => void;
+}
+interface BigIntInputState {
+    display: string;
+    focused: boolean;
+}
+declare class BigIntInput extends Component<BigIntInputProps, BigIntInputState> {
+    private inputRef;
+    private _resolvedFormat;
+    private _intlFormatter;
+    private _prevFormatProp;
+    private pendingCursor;
+    static defaultProps: {
+        showZero: boolean;
+        placeholder: string;
+        format: {
+            thousand: string;
+            decimal: string;
+        };
+        allowNegative: boolean;
+    };
+    constructor(props: BigIntInputProps);
+    private get fmt();
+    private formatChanged;
+    private addThousands;
+    private removeThousands;
+    private digitIndex;
+    private cursorFromDigitIndex;
+    private valueToDisplay;
+    private sanitize;
+    componentDidUpdate(prevProps: BigIntInputProps, _prevState: BigIntInputState): void;
+    private handleChange;
+    private handleKeyDown;
+    private handleFocus;
+    private handleBlur;
+    private handlePaste;
+    focus(): void;
+    blur(): void;
+    select(): void;
+    render(): react_jsx_runtime.JSX.Element;
+}
+
+/**
+ * Format a BigInt value with thousands/decimal separators.
+ *
+ * formatValue(1500000n, 6)                        → "1.5"
+ * formatValue(1234567890n, 6)                      → "1,234.56789"
+ * formatValue(1234567890n, 6, { locale: 'de-DE' }) → "1.234,56789"
+ * formatValue(1234567890n, 6, 'none')              → "1234.56789"
+ */
+declare function formatValue(value: bigint, decimals: number, format?: {
+    locale?: string;
+    thousand?: string;
+    decimal?: string;
+} | 'auto' | 'none'): string;
+/**
+ * Parse a formatted string back into a BigInt value.
+ *
+ * parseValue("1,500.50", 6)                        → 1500500000n
+ * parseValue("1.500,50", 6, { locale: 'de-DE' })   → 1500500000n
+ * parseValue("1500", 6, 'none')                     → 1500000000n
+ * parseValue("1,00,000", 6, { locale: 'en-IN' })   → 100000000000n
+ */
+declare function parseValue(value: string, decimals: number, format?: {
+    locale?: string;
+    thousand?: string;
+    decimal?: string;
+} | 'auto' | 'none'): bigint;
+
+export { BigIntInput, type BigIntInputProps, type FormatConfig, formatValue, parseValue };