persian-date-kit 0.0.1 → 0.0.2

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 +135 -60
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,73 +1,148 @@
1
- # React + TypeScript + Vite
1
+ # @darvix/persian-date-kit
2
2
 
3
- This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
3
+ Production-ready Persian (Jalali) date pickers for React.
4
4
 
5
- Currently, two official plugins are available:
5
+ ## Key principles
6
+ - **Gregorian-only internally**: component values are always `Date | null` (Gregorian). Jalali is only for display/input.
7
+ - **Controlled components**: you own the state (`value` + `onChange`).
8
+ - **Logic separated from UI**: calendar grid/conversions are reusable utilities.
9
+ - **SSR-safe**: no `window` usage during render.
10
+ - **RTL-first**: `dir="rtl"` by default.
11
+ - **Optional styles**: ship CSS variables + minimal classes; you can override everything.
6
12
 
7
- - [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
8
- - [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
13
+ ## Install
9
14
 
10
- ## React Compiler
15
+ ```bash
16
+ npm i @darvix/persian-date-kit
17
+ ```
18
+
19
+ ## Styles (optional)
20
+ If you want the default look, import the stylesheet:
21
+
22
+ ```ts
23
+ import '@darvix/persian-date-kit/styles.css'
24
+ ```
25
+
26
+ If you skip it, you can style via your own CSS + the `classes` prop.
27
+
28
+ ## Usage
29
+
30
+ ### Single date picker
31
+
32
+ ```tsx
33
+ import { useState } from 'react'
34
+ import { PersianDatePicker } from '@darvix/persian-date-kit'
35
+ import '@darvix/persian-date-kit/styles.css'
36
+
37
+ const monthLabels = [
38
+ 'فروردین',
39
+ 'اردیبهشت',
40
+ 'خرداد',
41
+ 'تیر',
42
+ 'مرداد',
43
+ 'شهریور',
44
+ 'مهر',
45
+ 'آبان',
46
+ 'آذر',
47
+ 'دی',
48
+ 'بهمن',
49
+ 'اسفند',
50
+ ]
51
+
52
+ export function Example() {
53
+ const [value, setValue] = useState<Date | null>(new Date())
54
+
55
+ return (
56
+ <PersianDatePicker
57
+ value={value}
58
+ onChange={setValue}
59
+ placeholder="YYYY/MM/DD"
60
+ monthLabels={monthLabels}
61
+ weekdays={['ش', 'ی', 'د', 'س', 'چ', 'پ', 'ج']}
62
+ minDate={new Date(2020, 0, 1)}
63
+ maxDate={new Date(2030, 11, 31)}
64
+ />
65
+ )
66
+ }
67
+ ```
68
+
69
+ ### Inline calendar (no input)
11
70
 
12
- The React Compiler is currently not compatible with SWC. See [this issue](https://github.com/vitejs/vite-plugin-react/issues/428) for tracking the progress.
71
+ ```tsx
72
+ import { useState } from 'react'
73
+ import { PersianDatePicker } from '@darvix/persian-date-kit'
13
74
 
14
- ## Expanding the ESLint configuration
75
+ export function InlineCalendar() {
76
+ const [value, setValue] = useState<Date | null>(new Date())
77
+ return <PersianDatePicker mode="inline" value={value} onChange={setValue} />
78
+ }
79
+ ```
80
+
81
+ ### Range picker (start/end)
15
82
 
16
- If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
83
+ ```tsx
84
+ import { useState } from 'react'
85
+ import { PersianDateRangePicker, type PersianDateRange } from '@darvix/persian-date-kit'
17
86
 
18
- ```js
19
- export default defineConfig([
20
- globalIgnores(['dist']),
21
- {
22
- files: ['**/*.{ts,tsx}'],
23
- extends: [
24
- // Other configs...
87
+ export function RangeExample() {
88
+ const [range, setRange] = useState<PersianDateRange>({ start: null, end: null })
89
+
90
+ return (
91
+ <PersianDateRangePicker
92
+ value={range}
93
+ onChange={setRange}
94
+ // inputVariant="two" (default) => two inputs
95
+ inputVariant="single"
96
+ placeholder="بازه (YYYY/MM/DD - YYYY/MM/DD)"
97
+ />
98
+ )
99
+ }
100
+ ```
25
101
 
26
- // Remove tseslint.configs.recommended and replace with this
27
- tseslint.configs.recommendedTypeChecked,
28
- // Alternatively, use this for stricter rules
29
- tseslint.configs.strictTypeChecked,
30
- // Optionally, add this for stylistic rules
31
- tseslint.configs.stylisticTypeChecked,
102
+ ## React Hook Form (optional adapter)
103
+ The core package has **no required** form dependency.
104
+ If you want React Hook Form integration, import from the subpath:
32
105
 
33
- // Other configs...
34
- ],
35
- languageOptions: {
36
- parserOptions: {
37
- project: ['./tsconfig.node.json', './tsconfig.app.json'],
38
- tsconfigRootDir: import.meta.dirname,
39
- },
40
- // other options...
41
- },
42
- },
43
- ])
106
+ ```bash
107
+ npm i react-hook-form
44
108
  ```
45
109
 
46
- You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
47
-
48
- ```js
49
- // eslint.config.js
50
- import reactX from 'eslint-plugin-react-x'
51
- import reactDom from 'eslint-plugin-react-dom'
52
-
53
- export default defineConfig([
54
- globalIgnores(['dist']),
55
- {
56
- files: ['**/*.{ts,tsx}'],
57
- extends: [
58
- // Other configs...
59
- // Enable lint rules for React
60
- reactX.configs['recommended-typescript'],
61
- // Enable lint rules for React DOM
62
- reactDom.configs.recommended,
63
- ],
64
- languageOptions: {
65
- parserOptions: {
66
- project: ['./tsconfig.node.json', './tsconfig.app.json'],
67
- tsconfigRootDir: import.meta.dirname,
68
- },
69
- // other options...
70
- },
71
- },
72
- ])
110
+ ```tsx
111
+ import { useForm } from 'react-hook-form'
112
+ import { RHF_PersianDatePicker } from '@darvix/persian-date-kit/react-hook-form'
113
+
114
+ type FormValues = { birthDate: Date | null }
115
+
116
+ export function RHFExample() {
117
+ const { control, handleSubmit } = useForm<FormValues>({ defaultValues: { birthDate: null } })
118
+
119
+ return (
120
+ <form onSubmit={handleSubmit(console.log)}>
121
+ <RHF_PersianDatePicker name="birthDate" control={control} placeholder="YYYY/MM/DD" />
122
+ <button type="submit">Submit</button>
123
+ </form>
124
+ )
125
+ }
126
+ ```
127
+
128
+ ## API notes
129
+
130
+ ### `PersianDatePicker`
131
+ - **`value`**: `Date | null`
132
+ - **`onChange`**: `(date: Date | null) => void`
133
+ - **`minDate` / `maxDate`**: limit selectable dates (Gregorian dates)
134
+ - **`mode`**: `'popover' | 'inline'`
135
+ - **`monthLabels`**: 12 strings (no hardcoded locale in the library)
136
+ - **`weekdays`**: 7 strings
137
+
138
+ ### `PersianDateRangePicker`
139
+ - **`value`**: `{ start: Date | null; end: Date | null }`
140
+ - **`onChange`**: `(range) => void`
141
+ - **`inputVariant`**: `'two' | 'single'`
142
+
143
+ ## Development (this repo)
144
+
145
+ ```bash
146
+ npm run dev
147
+ npm run build
73
148
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "persian-date-kit",
3
- "version": "0.0.1",
3
+ "version": "0.0.2",
4
4
  "type": "module",
5
5
  "main": "./dist/index.cjs",
6
6
  "module": "./dist/index.mjs",