persian-number-input 4.5.0 → 4.5.1

package/README.fa.md

@@ -42,7 +42,8 @@ English | [فارسی](./README.fa.md)
 - ⚡ **فقط ~۱ کیلوبایت** — بدون هیچ dependency اضافه
 - 🎯 **TypeScript** — تعریف تایپ کامل
 - 🔄 **حفظ موقعیت cursor** — بدون جهش هنگام فرمت‌دهی
-- ✅ **اعتبارسنجی min/max** — کنترل بازه مجاز و دقت اعشاری
+- 📋 **مدیریت هوشمند paste** — محتوای چسبانده شده خودکار پالایش و تبدیل می‌شود
+- ✅ **اعتبارسنجی min/max** — اعتبارسنجی نرم با `aria-invalid` و اعمال خودکار محدودیت در blur
 - ♿ **دسترس‌پذیر** — رعایت استانداردهای WCAG
 
 ---
@@ -203,12 +204,15 @@ function CustomInput() {
       value={value}
       onChange={onChange}
       onBlur={onBlur}
+      onPaste={onPaste}
       dir="rtl"
     />
   );
 }
 ```
 
+Hook همچنین `isInvalid` (boolean) رو وقتی مقدار از `max` بیشتر بشه برمی‌گردونه، و `onPaste` برای مدیریت رویداد paste.
+
 ---
 
 ### ماشین‌حساب وام
@@ -266,11 +270,11 @@ function LoanCalculator() {
 | `suffix`         | `string`                               | `undefined` | پسوند — مثل `تومان`، `ریال`                                     |
 | `maxDecimals`    | `number`                               | `undefined` | حداکثر رقم اعشار مجاز                                            |
 | `min`            | `number`                               | `undefined` | کمترین مقدار مجاز                                                |
-| `max`            | `number`                               | `undefined` | بیشترین مقدار مجاز                                               |
+| `max`            | `number`                               | `undefined` | بیشترین مقدار مجاز — اعتبارسنجی نرم (علامت‌گذاری invalid، اعمال در blur) |
 | `showZero`       | `boolean`                              | `false`     | نمایش صفر وقتی ورودی خالی است                                    |
 | `onValueChange`  | `(value: string \| undefined) => void` | `undefined` | callback هنگام تغییر — همیشه ارقام انگلیسی برمی‌گرداند          |
 
-تمام props استاندارد `<input>` مثل `className`، `style`، `placeholder` و `disabled` هم پشتیبانی می‌شن.
+تمام props استاندارد `<input>` مثل `onChange`، `onKeyDown`، `onPaste`، `className`، `style`، `placeholder`، `dir` و `disabled` هم پشتیبانی می‌شن.
 
 ---
 
@@ -326,6 +330,56 @@ sanitizeNumericInput("۱۲۳abc۴۵۶", 2); // "123456"
 sanitizeNumericInput("12.345.67", 2);  // "12.34"
 ```
 
+#### `stripNonNumeric(str)`
+
+حذف همه کاراکترهای غیرعددی و غیر از نقطه:
+
+```tsx
+import { stripNonNumeric } from "persian-number-input";
+
+stripNonNumeric("12abc34.56xyz"); // "1234.56"
+```
+
+#### `normalizeDecimals(str)`
+
+نگه داشتن فقط اولین نقطه اعشاری:
+
+```tsx
+import { normalizeDecimals } from "persian-number-input";
+
+normalizeDecimals("12.34.56"); // "12.3456"
+```
+
+#### `stripLeadingZeros(str)`
+
+حذف صفرهای اضافه ابتدای عدد:
+
+```tsx
+import { stripLeadingZeros } from "persian-number-input";
+
+stripLeadingZeros("001234.56"); // "1234.56"
+```
+
+#### `applyDecimalPrecision(str, maxDecimals?)`
+
+محدود کردن قسمت اعشار به تعداد رقم مشخص:
+
+```tsx
+import { applyDecimalPrecision } from "persian-number-input";
+
+applyDecimalPrecision("1234.5678", 2); // "1234.56"
+```
+
+#### `roundToDecimals(value, maxDecimals?)`
+
+مشابه `applyDecimalPrecision` — محدود کردن قسمت اعشار:
+
+```tsx
+import { roundToDecimals } from "persian-number-input";
+
+roundToDecimals("1234.5678", 2); // "1234.56"
+```
+
 ---
 
 ## 🎨 استایل‌دهی

package/README.md

@@ -42,7 +42,9 @@ Form receives: "1234567"
 - ⚡ **~1KB gzipped** — zero extra dependencies, pure TypeScript
 - 🎯 **TypeScript** — full type definitions included
 - 🔄 **Cursor-position preservation** — no jump on re-format
-- ✅ **Min/max validation** — built-in range enforcement and decimal precision control
+- 📋 **Smart paste handling** — pasted content is sanitized and auto-converted
+- ✅ **Min/max validation** — soft enforcement with `aria-invalid` and automatic clamp on blur
+
 - ♿ **Accessible** — follows WCAG input best practices
 
 ---
@@ -203,12 +205,15 @@ function CustomInput() {
       value={value}
       onChange={onChange}
       onBlur={onBlur}
+      onPaste={onPaste}
       dir="rtl"
     />
   );
 }
 ```
 
+The hook also returns `isInvalid` (boolean) when the value exceeds `max`, and `onPaste` for paste event handling.
+
 ---
 
 ## 🛠️ API Reference
@@ -225,11 +230,11 @@ function CustomInput() {
 | `suffix`         | `string`                               | `undefined` | Currency or unit suffix (e.g. `تومان`, `ریال`)      |
 | `maxDecimals`    | `number`                               | `undefined` | Maximum allowed decimal places                       |
 | `min`            | `number`                               | `undefined` | Minimum allowed value                                |
-| `max`            | `number`                               | `undefined` | Maximum allowed value                                |
+| `max`            | `number`                               | `undefined` | Maximum allowed value — soft validation (marks invalid, clamps on blur) |
 | `showZero`       | `boolean`                              | `false`     | Display `0` instead of empty when value is zero      |
 | `onValueChange`  | `(value: string \| undefined) => void` | `undefined` | Fires on change — always returns English digits      |
 
-All standard HTML `<input>` props (e.g. `className`, `style`, `placeholder`, `disabled`) are also supported.
+All standard HTML `<input>` props are also supported, including `onChange`, `onKeyDown`, `onPaste`, `className`, `style`, `placeholder`, `dir`, and `disabled`.
 
 ---
 
@@ -285,6 +290,56 @@ sanitizeNumericInput("۱۲۳abc۴۵۶", 2); // "123456"
 sanitizeNumericInput("12.345.67", 2);  // "12.34"
 ```
 
+#### `stripNonNumeric(str)`
+
+Remove all non-digit and non-dot characters.
+
+```tsx
+import { stripNonNumeric } from "persian-number-input";
+
+stripNonNumeric("12abc34.56xyz"); // "1234.56"
+```
+
+#### `normalizeDecimals(str)`
+
+Keep only the first decimal point.
+
+```tsx
+import { normalizeDecimals } from "persian-number-input";
+
+normalizeDecimals("12.34.56"); // "12.3456"
+```
+
+#### `stripLeadingZeros(str)`
+
+Strip leading zeros from a numeric string.
+
+```tsx
+import { stripLeadingZeros } from "persian-number-input";
+
+stripLeadingZeros("001234.56"); // "1234.56"
+```
+
+#### `applyDecimalPrecision(str, maxDecimals?)`
+
+Truncate fractional part to the specified decimal places.
+
+```tsx
+import { applyDecimalPrecision } from "persian-number-input";
+
+applyDecimalPrecision("1234.5678", 2); // "1234.56"
+```
+
+#### `roundToDecimals(value, maxDecimals?)`
+
+Alias for `applyDecimalPrecision` — truncate fractional part.
+
+```tsx
+import { roundToDecimals } from "persian-number-input";
+
+roundToDecimals("1234.5678", 2); // "1234.56"
+```
+
 ---
 
 ## 🎨 Styling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "persian-number-input",
-  "version": "4.5.0",
+  "version": "4.5.1",
   "description": "React component for Persian, Indic, or English localized number input with customizable digit grouping",
   "main": "dist/index.js",
   "module": "dist/index.js",