persian-number-input 4.0.0 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +190 -57
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -10,14 +10,14 @@ English 🇺🇸 | فارسی 🇮🇷
10
10
 
11
11
  ## English
12
12
 
13
- **Persian Number Input** - A powerful React component for formatting and handling numbers in Persian, English, or other localized digit systems. Perfect for multilingual applications requiring numeric inputs with customizable formatting.
13
+ **Persian Number Input** - A powerful React component and utility for formatting and handling numbers in Persian, English, or other localized digit systems. Perfect for multilingual applications requiring numeric inputs with customizable formatting, including decimal support.
14
14
 
15
15
  ✅ **Key Features:**
16
16
 
17
17
  - Supports Persian, English, and other digit localization (e.g., Indic)
18
18
  - Customizable digit grouping (e.g., thousands separator)
19
- - Handles decimal numbers with configurable precision
20
- - Min/max value constraints for input validation
19
+ - Handles decimal numbers with configurable precision using ``
20
+ - Min/max value constraints for input validation, including decimals
21
21
  - Converts localized digits to standard English digits for processing
22
22
  - Lightweight and compatible with React 16 to 19
23
23
  - TypeScript support for robust development
@@ -27,13 +27,14 @@ English 🇺🇸 | فارسی 🇮🇷
27
27
  Install the package via npm or yarn:
28
28
 
29
29
  ```bash
30
- npm install persian-number-input
30
+ npm install persian-number-input
31
31
  ```
32
32
 
33
+ ### 💻 Usage Examples
33
34
 
34
- ### 💻 Usage Example
35
+ #### 1. Using `PersianNumberInput` Component
35
36
 
36
- Here’s a simple example demonstrating the component with min/max constraints and decimal support:
37
+ This component is ideal for form inputs requiring localized number formatting.
37
38
 
38
39
  ```jsx
39
40
  import React, { useState } from "react";
@@ -49,8 +50,8 @@ const App = () => {
49
50
  separatorChar=","
50
51
  locale="fa"
51
52
  maxDecimals={2}
52
- min={0}
53
- max={1000000}
53
+ min={0.5}
54
+ max={1000000.999}
54
55
  showZero={true}
55
56
  onValueChange={(val) => setNumber(val || "")}
56
57
  placeholder="Enter a number"
@@ -62,65 +63,134 @@ const App = () => {
62
63
  export default App;
63
64
  ```
64
65
 
65
- ### 🔥 Output Example
66
-
66
+ **Output**:
67
67
  ```
68
68
  Input: 123456.78
69
69
  Displayed Output: ۱۲۳,۴۵۶٫۷۸
70
70
  English Output: 123456.78
71
71
  ```
72
72
 
73
+ #### 2. Using `usePersianNumberInput` Hook
74
+
75
+ The `usePersianNumberInput` hook provides fine-grained control for custom input handling.
76
+
77
+ ```jsx
78
+ import React from "react";
79
+ import { usePersianNumberInput } from "persian-number-input";
80
+
81
+ const CustomInput = () => {
82
+ const { value, onChange, rawValue } = usePersianNumberInput({
83
+ initialValue: "5000.25",
84
+ separatorCount: 3,
85
+ separatorChar: ",",
86
+ locale: "fa",
87
+ maxDecimals: 2,
88
+ min: 0.5,
89
+ max: 10000.999,
90
+ showZero: true,
91
+ });
92
+
93
+ return (
94
+ <div>
95
+ <input
96
+ type="text"
97
+ inputMode="decimal"
98
+ value={value}
99
+ onChange={onChange}
100
+ placeholder="Enter a number"
101
+ />
102
+ <p>Raw Value: {rawValue || "N/A"}</p>
103
+ </div>
104
+ );
105
+ };
106
+
107
+ export default CustomInput;
108
+ ```
109
+
110
+ **Explanation**:
111
+ - The hook manages the input state and formatting, returning `value` (formatted for display) and `rawValue` (English digits).
112
+ - Use this for custom input components or non-standard form controls.
113
+ - **Output**:
114
+ ```
115
+ Displayed Input:ავ۰٫۲۵
116
+ Raw Value: 5000.25
117
+ ```
118
+
119
+ #### 3. Using `transformNumber` Utility
120
+
121
+ The `transformNumber` function formats numbers without requiring a React component, ideal for display-only scenarios.
122
+
123
+ ```javascript
124
+ import { transformNumber } from "persian-number-input";
125
+
126
+ const number = 123456.789;
127
+ const formatted = transformNumber(number, {
128
+ separatorCount: 3,
129
+ separatorChar: ",",
130
+ locale: "fa",
131
+ maxDecimals: 2,
132
+ showZero: true,
133
+ });
134
+
135
+ console.log(formatted); // Output: ۱۲۳,۴۵۶٫۷۹
136
+ ```
137
+
138
+ **Explanation**:
139
+ - Use `transformNumber` to format numbers for display in tables, labels, or other non-input contexts.
140
+ - Supports the same options as `PersianNumberInput` (`separatorCount`, `locale`, etc.).
141
+ - Returns a string with localized digits and formatting.
142
+
73
143
  ### 📚 Props Reference
74
144
 
75
145
  | Name | Type | Default | Description |
76
146
  | --- | --- | --- | --- |
77
- | `initialValue` | \`string | number\` | `""` |
147
+ | `initialValue` | `string | number` | `""` | Initial value of the input |
78
148
  | `separatorCount` | `number` | `3` | Number of digits per group (e.g., 3 for thousands) |
79
149
  | `separatorChar` | `string` | `","` | Character used for grouping digits (e.g., `,` or `.`) |
80
150
  | `locale` | `string` | `"fa"` | Language for digit localization (e.g., `fa`, `en`) |
81
151
  | `maxDecimals` | `number` | `0` | Maximum number of decimal places allowed |
82
152
  | `showZero` | `boolean` | `false` | If `true`, displays `0` when the input is empty or zero |
83
- | `min` | `number` | \- | Minimum allowed value (inclusive) |
84
- | `max` | `number` | \- | Maximum allowed value (inclusive) |
85
- | `onValueChange` | \`(value: string | undefined) =&gt; void\` | \- |
86
- | `...rest` | `InputHTMLAttributes` | \- | Standard HTML input attributes (e.g., `className`, `placeholder`, `style`) |
153
+ | `min` | `number` | - | Minimum allowed value (supports decimals, e.g., `0.5`) |
154
+ | `max` | `number` | - | Maximum allowed value (supports decimals, e.g., `1000.201`) |
155
+ | `onValueChange` | `(value: string | undefined) => void` | - | Callback for value changes |
156
+ | `...rest` | `InputHTMLAttributes` | - | Standard HTML input attributes (e.g., `className`, `placeholder`, `style`) |
87
157
 
88
158
  ### 🌟 Why Use Persian Number Input?
89
159
 
90
160
  - **Multilingual Support**: Seamlessly handle Persian, English, or other localized digits.
91
161
  - **Customizable Formatting**: Control separators, decimals, and zero display.
92
- - **Robust Validation**: Enforce min/max constraints for reliable inputs.
162
+ - **Robust Validation**: Enforce min/max constraints with decimal precision using ``.
93
163
  - **Developer-Friendly**: TypeScript support and a simple API for quick integration.
94
- - **Lightweight**: Minimal bundle size for fast performance.
164
+ - **Lightweight**: Optimized for performance with minimal dependencies.
95
165
 
96
166
  ### ❓ FAQ (Frequently Asked Questions)
97
167
 
98
- **Does this package support React 19?**\
168
+ **Does this package support React 19?**
99
169
  Yes, it is fully compatible with React 16 through 19.
100
170
 
101
- **Can I use decimal numbers?**\
171
+ **Can I use decimal numbers?**
102
172
  Yes, set `maxDecimals` to the desired number of decimal places (e.g., `maxDecimals={2}`).
103
173
 
104
- **How do I enforce minimum and maximum values?**\
105
- Use the `min` and `max` props to restrict the input range (e.g., `min={0}` and `max={1000}`).
174
+ **How do I enforce minimum and maximum values?**
175
+ Use the `min` and `max` props, which support decimals (e.g., `min={0.5}`, `max={1000.201}`).
106
176
 
107
- **How can I style the input?**\
177
+ **How can I style the input?**
108
178
  Pass `className` or `style` props to customize the input’s appearance.
109
179
 
110
- **What happens if the user enters an invalid number?**\
180
+ **What happens if the user enters an invalid number?**
111
181
  The component sanitizes inputs, ensuring only valid numbers are processed, and respects min/max constraints.
112
182
 
113
183
  ### 🌟 Support the Project
114
184
 
115
185
  If you find this package useful, **please give it a star ⭐ on GitHub** to support further development.
116
186
 
117
- 👉 **GitHub Repository**
187
+ 👉 **[GitHub Repository](https://github.com/javadSharifi/persian-number-input)**
118
188
 
119
189
  Thank you for your support! ❤️🚀
120
190
 
121
191
  ### 📈 SEO Keywords
122
192
 
123
- `Persian Number Input`, `React Persian input`, `React number formatting`, `localized numeric input`, `Persian digits`, `React numeric input`, `number formatter`, `TypeScript React component`, `multilingual input`
193
+ `Persian Number Input`, `React Persian input`, `React number formatting`, `localized numeric input`, `Persian digits`, `React numeric input`, `number formatter`, `TypeScript React component`, `multilingual input`, `React number formatting hook`, `Persian number utility`
124
194
 
125
195
  ### 📄 License
126
196
 
@@ -132,14 +202,14 @@ MIT License
132
202
 
133
203
  ## فارسی
134
204
 
135
- **کامپوننت ورودی اعداد فارسی** - یک کامپوننت قدرتمند React برای مدیریت و فرمت‌بندی اعداد به صورت فارسی، انگلیسی یا سایر سیستم‌های ارقام محلی. ایده‌آل برای برنامه‌های چندزبانه که نیاز به ورودی‌های عددی با فرمت سفارشی دارند.
205
+ **کامپوننت ورودی اعداد فارسی** - یک کامپوننت و ابزار قدرتمند React برای مدیریت و فرمت‌بندی اعداد به صورت فارسی، انگلیسی یا سایر سیستم‌های ارقام محلی. ایده‌آل برای برنامه‌های چندزبانه که نیاز به ورودی‌های عددی با فرمت سفارشی و پشتیبانی از اعشار دارند.
136
206
 
137
207
  ✅ **امکانات کلیدی:**
138
208
 
139
209
  - پشتیبانی از ارقام فارسی، انگلیسی و سایر زبان‌ها (مانند هندی)
140
210
  - قابلیت تنظیم جداکننده ارقام (مثل هزارگان)
141
- - مدیریت اعداد اعشاری با دقت قابل تنظیم
142
- - اعمال محدودیت‌های حداقل و حداکثر برای اعتبارسنجی
211
+
212
+ - اعمال محدودیت‌های حداقل و حداکثر با پشتیبانی از اعشار
143
213
  - تبدیل خودکار ارقام محلی به ارقام انگلیسی برای پردازش
144
214
  - سبک و سازگار با React 16 تا 19
145
215
  - پشتیبانی از TypeScript برای توسعه امن
@@ -149,18 +219,14 @@ MIT License
149
219
  پکیج را از طریق npm یا yarn نصب کنید:
150
220
 
151
221
  ```bash
152
- npm install persian-number-input
222
+ npm install persian-number-input
153
223
  ```
154
224
 
155
- یا
225
+ ### 💻 مثال‌های استفاده
156
226
 
157
- ```bash
158
- yarn add persian-number-input
159
- ```
227
+ #### ۱. استفاده از کامپوننت `PersianNumberInput`
160
228
 
161
- ### 💻 مثال استفاده
162
-
163
- مثالی ساده با پشتیبانی از اعشار و محدودیت‌های حداقل/حداکثر:
229
+ این کامپوننت برای ورودی‌های فرم با فرمت‌بندی محلی مناسب است.
164
230
 
165
231
  ```jsx
166
232
  import React, { useState } from "react";
@@ -176,8 +242,8 @@ const App = () => {
176
242
  separatorChar=","
177
243
  locale="fa"
178
244
  maxDecimals={2}
179
- min={0}
180
- max={1000000}
245
+ min={0.5}
246
+ max={1000000.999}
181
247
  showZero={true}
182
248
  onValueChange={(val) => setNumber(val || "")}
183
249
  placeholder="یک عدد وارد کنید"
@@ -189,68 +255,135 @@ const App = () => {
189
255
  export default App;
190
256
  ```
191
257
 
192
- ### 🔥 مثال خروجی
193
-
258
+ **خروجی**:
194
259
  ```
195
260
  ورودی: 123456.78
196
261
  خروجی نمایشی: ۱۲۳,۴۵۶٫۷۸
197
262
  خروجی انگلیسی: 123456.78
198
263
  ```
199
264
 
265
+ #### ۲. استفاده از هوک `usePersianNumberInput`
266
+
267
+ هوک `usePersianNumberInput` برای کنترل دقیق ورودی‌های سفارشی استفاده می‌شود.
268
+
269
+ ```jsx
270
+ import React from "react";
271
+ import { usePersianNumberInput } from "persian-number-input";
272
+
273
+ const CustomInput = () => {
274
+ const { value, onChange, rawValue } = usePersianNumberInput({
275
+ initialValue: "5000.25",
276
+ separatorCount: 3,
277
+ separatorChar: ",",
278
+ locale: "fa",
279
+ maxDecimals: 2,
280
+ min: 0.5,
281
+ max: 10000.999,
282
+ showZero: true,
283
+ });
284
+
285
+ return (
286
+ <div>
287
+ <input
288
+ type="text"
289
+ inputMode="decimal"
290
+ value={value}
291
+ onChange={onChange}
292
+ placeholder="یک عدد وارد کنید"
293
+ />
294
+ <p>مقدار خام: {rawValue || "بدون مقدار"}</p>
295
+ </div>
296
+ );
297
+ };
298
+
299
+ export default CustomInput;
300
+ ```
301
+
302
+ **توضیح**:
303
+ - این هوک وضعیت ورودی و فرمت‌بندی را مدیریت می‌کند و `value` (برای نمایش) و `rawValue` (ارقام انگلیسی) را برمی‌گرداند.
304
+ - برای کامپوننت‌های ورودی سفارشی یا فرم‌های غیراستاندارد مناسب است.
305
+ - **خروجی**:
306
+ ```
307
+ ورودی نمایشی: ۵,۰۰۰٫۲۵
308
+ مقدار خام: 5000.25
309
+ ```
310
+
311
+ #### ۳. استفاده از ابزار `transformNumber`
312
+
313
+ تابع `transformNumber` برای فرمت‌بندی اعداد بدون نیاز به کامپوننت React مناسب است.
314
+
315
+ ```javascript
316
+ import { transformNumber } from "persian-number-input";
317
+
318
+ const number = 123456.789;
319
+ const formatted = transformNumber(number, {
320
+ separatorCount: 3,
321
+ separatorChar: ",",
322
+ locale: "fa",
323
+ maxDecimals: 2,
324
+ showZero: true,
325
+ });
326
+
327
+ console.log(formatted); // خروجی: ۱۲۳,۴۵۶٫۷۹
328
+ ```
329
+
330
+ **توضیح**:
331
+ - از `transformNumber` برای فرمت‌بندی اعداد در جداول، برچسب‌ها یا سایر موارد غیرورودی استفاده کنید.
332
+ - همان گزینه‌های `PersianNumberInput` (مانند `separatorCount` و `locale`) را پشتیبانی می‌کند.
333
+ - یک رشته با ارقام محلی و فرمت‌بندی مناسب برمی‌گرداند.
334
+
200
335
  ### 📚 مرجع مشخصات (Props)
201
336
 
202
337
  | نام | نوع | پیش‌فرض | توضیح |
203
338
  | --- | --- | --- | --- |
204
- | `initialValue` | \`string | number\` | `""` |
339
+ | `initialValue` | `string | number` | `""` | مقدار اولیه ورودی |
205
340
  | `separatorCount` | `number` | `3` | تعداد ارقام در هر گروه (مثلاً ۳ برای هزارگان) |
206
341
  | `separatorChar` | `string` | `","` | کاراکتر جداکننده گروه‌ها (مثلاً `,` یا `.`) |
207
342
  | `locale` | `string` | `"fa"` | زبان برای محلی‌سازی ارقام (مثلاً `fa` یا `en`) |
208
343
  | `maxDecimals` | `number` | `0` | حداکثر تعداد ارقام اعشاری مجاز |
209
344
  | `showZero` | `boolean` | `false` | اگر `true` باشد، عدد `0` را در ورودی خالی یا صفر نمایش می‌دهد |
210
- | `min` | `number` | \- | حداقل مقدار مجاز (شامل) |
211
- | `max` | `number` | \- | حداکثر مقدار مجاز (شامل) |
212
- | `onValueChange` | \`(value: string | undefined) =&gt; void\` | \- |
213
- | `...rest` | `InputHTMLAttributes` | \- | ویژگی‌های استاندارد ورودی HTML (مثل `className`، `placeholder`، `style`) |
345
+ | `min` | `number` | - | حداقل مقدار مجاز (پشتیبانی از اعشار، مثلاً `0.5`) |
346
+ | `max` | `number` | - | حداکثر مقدار مجاز (پشتیبانی از اعشار، مثلاً `1000.201`) |
347
+ | `onValueChange` | `(value: string | undefined) => void` | - | فراخوانی در تغییر مقدار |
348
+ | `...rest` | `InputHTMLAttributes` | - | ویژگی‌های استاندارد ورودی HTML (مثل `className`، `placeholder`، `style`) |
214
349
 
215
350
  ### 🌟 چرا از این کامپوننت استفاده کنیم؟
216
351
 
217
352
  - **پشتیبانی چندزبانه**: مدیریت آسان ارقام فارسی، انگلیسی یا سایر زبان‌ها.
218
353
  - **فرمت‌بندی انعطاف‌پذیر**: کنترل جداکننده‌ها، اعشار و نمایش صفر.
219
- - **اعتبارسنجی قوی**: اعمال محدودیت‌های حداقل و حداکثر برای ورودی‌های مطمئن.
354
+ - **اعتبارسنجی قوی**: اعمال محدودیت‌های حداقل و حداکثر با دقت اعشاری با ``.
220
355
  - **مناسب توسعه‌دهندگان**: پشتیبانی از TypeScript و API ساده برای ادغام سریع.
221
- - **سبک و سریع**: حجم کم برای عملکرد بهینه.
356
+ - **سبک و سریع**: بهینه‌شده برای عملکرد با حداقل وابستگی‌ها.
222
357
 
223
358
  ### ❓ سوالات متداول
224
359
 
225
- **آیا این پکیج از React 19 پشتیبانی می‌کند؟**\
360
+ **آیا این پکیج از React 19 پشتیبانی می‌کند؟**
226
361
  بله، کاملاً با React 16 تا 19 سازگار است.
227
362
 
228
- **آیا می‌توان از اعداد اعشاری استفاده کرد؟**\
363
+ **آیا می‌توان از اعداد اعشاری استفاده کرد؟**
229
364
  بله، با تنظیم `maxDecimals` می‌توانید تعداد ارقام اعشاری را مشخص کنید (مثلاً `maxDecimals={2}`).
230
365
 
231
- **چگونه می‌توان حداقل و حداکثر مقدار را اعمال کرد؟**\
232
- از پراپ‌های `min` و `max` استفاده کنید (مثلاً `min={0}` و `max={1000}`).
366
+ **چگونه می‌توان حداقل و حداکثر مقدار را اعمال کرد؟**
367
+ از پراپ‌های `min` و `max` استفاده کنید که از اعشار پشتیبانی می‌کنند (مثلاً `min={0.5}` و `max={1000.201}`).
233
368
 
234
- **چگونه ظاهر ورودی را سفارشی کنم؟**\
369
+ **چگونه ظاهر ورودی را سفارشی کنم؟**
235
370
  با پراپ‌های `className` یا `style` می‌توانید ظاهر ورودی را تغییر دهید.
236
371
 
237
- **اگر کاربر عدد نامعتبری وارد کند چه می‌شود؟**\
372
+ **اگر کاربر عدد نامعتبری وارد کند چه می‌شود؟**
238
373
  کامپوننت ورودی‌ها را پاکسازی می‌کند و فقط اعداد معتبر را پردازش می‌کند، ضمن رعایت محدودیت‌های min/max.
239
374
 
240
375
  ### 🌟 حمایت از پروژه
241
376
 
242
377
  اگر این پکیج برای شما مفید بود، **لطفاً یک ستاره ⭐ به مخزن GitHub بدهید** تا توسعه بیشتر آن را تشویق کنید.
243
378
 
244
- 👉 **مخزن GitHub**
379
+ 👉 **[مخزن GitHub](https://github.com/javadSharifi/persian-number-input)**
245
380
 
246
381
  از حمایت شما سپاسگزاریم! ❤️🚀
247
382
 
248
383
  ### 📈 کلمات کلیدی برای جستجو
249
384
 
250
- `ورودی اعداد فارسی`, `کامپوننت React فارسی`, `فرمت‌بندی اعداد در React`, `ورودی عددی محلی‌سازی‌شده`, `ارقام فارسی`, `ورودی عددی React`, `فرمت‌کننده اعداد`, `کامپوننت TypeScript React`, `ورودی چندزبانه`
385
+ `ورودی اعداد فارسی`, `کامپوننت React فارسی`, `فرمت‌بندی اعداد در React`, `ورودی عددی محلی‌سازی‌شده`, `ارقام فارسی`, `ورودی عددی React`, `فرمت‌کننده اعداد`, `کامپوننت TypeScript React`, `ورودی چندزبانه`, `هوک فرمت‌بندی اعداد`, `ابزار اعداد فارسی`
251
386
 
252
387
  ### 📄 مجوز
253
388
 
254
389
  MIT License
255
-
256
- © ۱۴۰۴ جواد شریفی. تمامی حقوق محفوظ است.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "persian-number-input",
3
- "version": "4.0.0",
3
+ "version": "4.0.1",
4
4
  "description": "React component for Persian, Indic, or English localized number input with customizable digit grouping",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.js",