persian-date-kit 0.0.8 → 0.0.10

package/README.md

@@ -129,20 +129,125 @@ export function RHFExample() {
 }
 ```
 
-## API notes
+## Props reference
+
+All values you receive in `onChange` are **Gregorian** (`Date | null`). Jalali is only used for display/input.
 
 ### `PersianDatePicker`
-- **`value`**: `Date | null`
-- **`onChange`**: `(date: Date | null) => void`
-- **`minDate` / `maxDate`**: limit selectable dates (Gregorian dates)
-- **`mode`**: `'popover' | 'inline'`
-- **`monthLabels`**: 12 strings (no hardcoded locale in the library)
-- **`weekdays`**: 7 strings
+
+#### Required props
+- **`value`**: `Date | null` — controlled value (Gregorian)
+- **`onChange`**: `(date: Date | null) => void` — controlled change handler
+
+#### Extra props (single picker)
+- **`placeholder?`**: `string` — input placeholder (popover mode)
+- **`classes?`**: `PersianDatePickerClasses` — per-slot class overrides
 
 ### `PersianDateRangePicker`
-- **`value`**: `{ start: Date | null; end: Date | null }`
-- **`onChange`**: `(range) => void`
-- **`inputVariant`**: `'two' | 'single'`
+
+#### Required props
+- **`value`**: `{ start: Date | null; end: Date | null }` — controlled range (Gregorian)
+- **`onChange`**: `(range: { start: Date | null; end: Date | null }) => void`
+
+#### Extra props (range picker)
+- **`inputVariant?`**: `'two' | 'single'` — two inputs (default) or one combined input
+- **`placeholder?`**: `string` — used for single-input mode
+- **`rangeSeparator?`**: `string` — separator for single-input text (default: `" - "`)
+- **`placeholderStart?` / `placeholderEnd?`**: `string` — used for two-input mode
+- **`classes?`**: `PersianDateRangePickerClasses` — per-slot class overrides
+
+### Shared props (`BasePickerProps`)
+
+These props exist on both pickers:
+
+- **`minDate?` / `maxDate?`**: `Date` — limits selectable days (Gregorian)
+- **`disabled?`**: `boolean`
+- **`mode?`**: `'popover' | 'inline'` — default is `'popover'`
+- **`open?` / `onOpenChange?`**: control popover open state (only meaningful in popover mode)
+- **`popover?`**: `PopoverConfig` — positioning options (popover mode)
+- **`formatValue?`**: `(date: Date) => string` — formats input text (default: numeric Jalali `YYYY/MM/DD`)
+- **`parseValue?`**: `(text: string) => Date | null` — parses input text into Gregorian (default: numeric Jalali `YYYY/MM/DD`)
+- **`weekdays?`**: `string[]` — 7 labels for weekday header (if omitted, the picker uses numeric labels)
+- **`monthLabels?`**: `string[]` — 12 labels (index 0 => month 1). If omitted, month numbers are shown.
+- **`renderMonthLabel?`**: `(jy: number, jm: number) => React.ReactNode` — custom header label
+- **`prevIcon?` / `nextIcon?`**: `React.ReactNode` — customize navigation icons
+- **`className?`**: `string` — extra class on root
+
+### `PopoverConfig`
+
+- **`portal?`**: `boolean` (default: `true`) — recommended inside modals / overflow containers
+- **`gutter?`**: `number` (default: `8`) — gap between anchor and popover
+- **`padding?`**: `number` (default: `8`) — minimum distance from viewport edges (clamping)
+- **`strategy?`**: `'fixed' | 'absolute'` (default: `'fixed'`)
+- **`placements?`**: `Array<'bottom' | 'top' | 'left' | 'right'>` (default: `['bottom','top','left','right']`)
+- **`align?`**: `'start' | 'center' | 'end'` (default: `'end'`)
+
+### Styling slots (`classes`)
+
+You can override the class names per slot:
+
+- **Base slots** (`BasePickerClasses`):
+  - `root`, `input`, `button`, `popover`, `header`, `navButton`, `monthLabel`, `grid`, `weekday`
+  - `day`, `dayOutside`, `dayDisabled`, `dayToday`
+- **Single picker extra slots** (`PersianDatePickerClasses`):
+  - `daySelected`
+- **Range picker extra slots** (`PersianDateRangePickerClasses`):
+  - `dayRangeStart`, `dayRangeEnd`, `dayInRange`
+
+## Styling / Theming
+
+### 1) Use the default styles (recommended)
+
+```ts
+import 'persian-date-kit/styles.css'
+```
+
+The default CSS is built around **CSS variables**, so it’s easy to theme.
+
+### 2) Theme via CSS variables (quickest)
+
+These variables control most of the look:
+
+- `--dvx-pdp-bg`
+- `--dvx-pdp-fg`
+- `--dvx-pdp-muted`
+- `--dvx-pdp-border`
+- `--dvx-pdp-shadow`
+- `--dvx-pdp-accent`
+- `--dvx-pdp-accentFg`
+- `--dvx-pdp-ring`
+- `--dvx-pdp-dayHover`
+
+Example:
+
+```css
+:root {
+  --dvx-pdp-accent: #16a34a;
+  --dvx-pdp-ring: rgba(22, 163, 74, 0.25);
+}
+```
+
+### 3) Override per-slot classes (`classes` prop)
+
+If you use Tailwind (or your own utility classes), pass overrides:
+
+```tsx
+<PersianDatePicker
+  value={value}
+  onChange={setValue}
+  classes={{
+    input: 'w-full rounded-xl border border-slate-300 bg-white px-3 py-2',
+    popover: 'z-[9999]',
+    daySelected: '!bg-emerald-600 !text-white',
+  }}
+/>
+```
+
+### 4) Fully custom CSS (no default stylesheet)
+
+If you **don’t** import `styles.css`, you should provide your own CSS for the
+component class hooks (ex: `.dvx-pdp`, `.dvx-pdp__input`, `.dvx-pdp__day`, ...),
+or rely entirely on `classes` and your own styles.
 
 ## Development (this repo)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "persian-date-kit",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Production-ready Persian (Jalali) date pickers for React with Gregorian-only values.",
   "keywords": [
     "react",