npm package: @ranjbar.amir/persian-datetime-picker
Description: Modern Persian (Jalali) DateTime Picker for Vue 3
Latest version: 1.1.0

# Persian DateTime Picker (Vue 3)

یک Date & Time Picker شمسی (Jalali) مدرن، سبک و حرفه‌ای برای Vue 3  
ساخته‌شده با Day.js + Jalaliday  
طراحی‌شده با UI سطح Figma و پشتیبانی از Dark Mode

---

## ✨ امکانات

- تقویم کامل شمسی (Jalali)
- انتخاب تاریخ یا بازه تاریخ (Range)
- انتخاب ساعت و دقیقه (Time Picker)
- انتخاب سریع ماه و سال
- دکمه‌های میان‌بُر (امروز، فردا، هفته بعد، پاک کردن)
- پشتیبانی کامل از کیبورد
- انیمیشن‌های نرم (Fade + Slide)
- طراحی حرفه‌ای و قابل سفارشی‌سازی
- سازگار با Vue 3 و Nuxt 3
- بدون وابستگی‌های سنگین (Moment.js ندارد)
- پشتیبانی از TailwindCSS

---

## 📦 نصب

```bash
npm install @ranjbar.amir/persian-datetime-picker
```

یا

```bash
yarn add @ranjbar.amir/persian-datetime-picker
```

---

## 🚀 استفاده در Vue 3

### 1) ایمپورت کامپوننت و استایل‌ها

```vue
<script setup>
import { ref } from "vue"
import DatePicker from "@ranjbar.amir/persian-datetime-picker"
import "@ranjbar.amir/persian-datetime-picker/dist/style.css"

const date = ref("")
</script>

<template>
  <DatePicker v-model="date" />
</template>
```

---

## 🌗 فعال‌سازی Dark Mode

اگر پروژه شما Tailwind دارد:

```html
<html class="dark">
```

یا داینامیک:

```js
document.documentElement.classList.toggle("dark")
```

---

## 📅 انتخاب بازه تاریخ (Range Picker)

```vue
<script setup>
import { ref } from "vue"
import DatePicker from "@ranjbar.amir/persian-datetime-picker"
import "@ranjbar.amir/persian-datetime-picker/dist/style.css"

const range = ref({ start: null, end: null })
</script>

<template>
  <DatePicker v-model="range" range />
</template>
```

---

## ⏱️ انتخاب ساعت (Time Picker)

```vue
<DatePicker v-model="date" enableTime />
```

خروجی:

```
1402/12/10 14:35
```

---

## ⚡ دکمه‌های میان‌بُر (Shortcuts)

```vue
<DatePicker v-model="date" shortcuts />
```

میان‌بُرهای پیش‌فرض:

- امروز  
- فردا  
- هفته بعد  
- پاک کردن  

---

## 🗓️ انتخاب ماه و سال

```vue
<DatePicker
  v-model="date"
  showMonthSelector
  showYearSelector
/>
```

---

## 📘 API کامل

### Props

| نام | نوع | پیش‌فرض | توضیح |
|-----|------|----------|--------|
| `modelValue` | String / Object | `""` | مقدار انتخاب‌شده |
| `range` | Boolean | `false` | فعال‌سازی انتخاب بازه |
| `enableTime` | Boolean | `false` | فعال‌سازی انتخاب ساعت |
| `shortcuts` | Boolean | `false` | نمایش دکمه‌های میان‌بُر |
| `showMonthSelector` | Boolean | `false` | انتخاب سریع ماه |
| `showYearSelector` | Boolean | `false` | انتخاب سریع سال |
| `placeholder` | String | `"انتخاب تاریخ"` | متن ورودی |
| `disabled` | Boolean | `false` | غیرفعال |
| `clearable` | Boolean | `false` | نمایش دکمه پاک‌کردن |

---

### Events

| رویداد | توضیح |
|--------|--------|
| `update:modelValue` | خروجی تاریخ یا بازه |
| `open` | باز شدن پنل |
| `close` | بسته شدن پنل |

---

## 🧩 خروجی Range

```json
{
  "start": "1402/12/01",
  "end": "1402/12/10"
}
```

---

## 🧱 استفاده در Nuxt 3

### 1) ساخت پلاگین

`plugins/datetime-picker.client.ts`

```ts
import DatePicker from "@ranjbar.amir/persian-datetime-picker"
import "@ranjbar.amir/persian-datetime-picker/dist/style.css"

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.component("DatePicker", DatePicker)
})
```

### 2) استفاده

```vue
<DatePicker v-model="date" />
```

---

## 🎨 سفارشی‌سازی UI

تمام استایل‌ها در این فایل‌ها هستند:

```
styles/base.css
styles/theme.css
styles/animations.css
```

می‌توانید override کنید:

```css
:root {
  --dp-primary: #10b981; /* سبز */
}
```

---

## 🛠️ توسعه‌دهندگان

### Build

```bash
npm run build
```

### انتشار در npm

```bash
npm publish --access public
```

---

## 📄 لایسنس

MIT — استفاده آزاد برای همه.