Persian DatePicker Component (Svelte 5)

🌟 Live Demo 🌟

A highly customizable and feature-rich date picker component built with Svelte 5, supporting Persian (Jalali), Gregorian, and Arabic calendars. This component is inspired by and converted from Alireza's Vue3 Persian DatePicker.

✨ Features

📅 Selection Modes

• Single Date: Select one date
• Date Range: Select from one date to another
• Multiple Dates: Select multiple individual dates (click to toggle)
• Time Only: Select time without date
• DateTime: Select both date and time
• DateTime Range: Select from one datetime to another datetime

🌍 Localization & Calendar Support

• Persian (Jalali): Full support for Persian calendar
• Gregorian: Standard international calendar
• Arabic: Arabic calendar support
• RTL/LTR: Automatic direction support based on locale

🎨 Customization

• Colors: Multiple color themes (blue, red, pink, orange, green, purple, gray)
• Formats: Customizable display formats, input formats
• Styles: Full CSS customization support
• Icons: Custom icon support
• Shortcuts: Predefined shortcuts for quick selections

💡 User Experience

• Clearable Input: Option to clear selected dates
• Auto Submit: Automatic submission on selection
• Keyboard Navigation: Full keyboard support
• Modal Mode: Can be displayed as modal
• Dual Input: Separate inputs for range selection
• Validation: Built-in date validation and disable rules

🚀 Installation

npm install @hamedf/svelte-persian-datepicker
# or
pnpm install @hamedf/svelte-persian-datepicker
# or
yarn add @hamedf/svelte-persian-datepicker

📖 Basic Usage

<script>
  import DatePicker from '@hamedf/svelte-persian-datepicker';
  
  let selectedDate = '';
  
  function handleSubmit(date) {
    console.log('Selected date:', date);
  }
</script>

<DatePicker
  bind:model={selectedDate}
  mode="single"
  type="date"
  submit={handleSubmit}
  color="blue"
  clearable={true}
/>

🎯 Usage Examples

Single Date Selection

<DatePicker
  bind:model={singleDate}
  mode="single"
  type="date"
  submit={handleSingleDate}
  color="blue"
/>

Date Range Selection

<DatePicker
  bind:model={dateRange}
  mode="range"
  type="date"
  submit={handleDateRange}
  color="green"
/>

Multiple Date Selection

<DatePicker
  bind:model={multipleDates}
  mode="multiple"
  type="date"
  submit={handleMultipleDates}
  color="purple"
  auto_submit={false}
/>

Time Selection

<DatePicker
  bind:model={selectedTime}
  mode="single"
  type="time"
  input_format="HH:mm"
  submit={handleTime}
  color="orange"
/>

DateTime Selection

<DatePicker
  bind:model={selectedDateTime}
  mode="single"
  type="datetime"
  input_format="YYYY-MM-DD HH:mm"
  submit={handleDateTime}
  color="red"
/>

DateTime Range Selection

<DatePicker
  bind:model={dateTimeRange}
  mode="range"
  type="datetime"
  input_format="YYYY-MM-DD HH:mm"
  submit={handleDateTimeRange}
  color="pink"
/>

⚙️ Props

🎨 Events

🎨 Styling

The component supports full CSS customization. You can override the default styles by targeting the component classes:

/* Custom styling for multiple selection */
:global(.pdp-multiple .pdp-day.selected) {
  background-color: #8b5cf6 !important;
  color: white !important;
  border-radius: 4px;
  font-weight: 600;
}

/* Custom range styling */
:global(.pdp-range .pdp-day.start-range) {
  background-color: your-color;
}

🔧 Development

Prerequisites

• Node.js 18+
• pnpm

Setup

# Clone the repository
git clone https://github.com/hamedf62/svelte-persian-datepicker

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Run tests
pnpm test

# Build for production
pnpm build

📂 Project Structure

src/
├── lib/
│   ├── DatePicker.svelte          # Main component
│   ├── components/                # Sub-components
│   │   ├── PDPArrow.svelte
│   │   ├── PDPIcon.svelte
│   │   └── PDPAlt.svelte
│   ├── modules/
│   │   ├── core.ts               # Core logic
│   │   └── types.ts              # TypeScript types
│   └── assets/sass/              # Styles
└── routes/
    └── +page.svelte              # Demo page

🧪 Testing

The component includes comprehensive tests using Cypress:

# Run component tests
pnpm test:component

# Run e2e tests
pnpm test:e2e

# Open Cypress UI
pnpm cypress:open

📄 Documentation

For detailed documentation and API reference, visit Alireza's Documentation as this component maintains compatibility with the original Vue3 version.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Alireza-ab for the original Vue3 Persian DatePicker
• Persian calendar calculations and localization support
• Svelte community for the amazing framework

📊 Features Comparison

🤖 AI/LLM Integration Guide

This component has been optimized for AI coding assistants and LLMs. Here's how to work with it effectively:

📋 Quick Reference for AI Agents

// COMPONENT SIGNATURE FOR AI REFERENCE
/**
 * @component PersianDatePicker
 * @description A comprehensive Svelte 5 Persian/Jalali DateTime picker
 * @props {Object} Props - See interface below for all available props
 * @bindable model - The selected date(s) value
 * @example
 * // Single date selection
 * <DatePicker bind:model={selectedDate} />
 * 
 * // Range selection  
 * <DatePicker mode="range" bind:model={dateRange} />
 * 
 * // Multiple dates
 * <DatePicker mode="multiple" bind:model={multipleDates} />
 * 
 * // With custom validation
 * <DatePicker 
 *   bind:model={date}
 *   from="1400/01/01" 
 *   to="1405/12/29"
 *   disable={['1403/01/01', '1403/05/15']}
 * />
 */

🎯 Common AI Prompts & Solutions

For Setting Up Basic Date Selection:

// AI: "Create a basic Persian date picker"
let selectedDate: string;

<DatePicker 
  bind:model={selectedDate}
  locale="fa"
  type="date"
  mode="single"
/>

For Range Selection:

// AI: "Create a date range picker for Persian calendar"
let dateRange: string[];

<DatePicker
  bind:model={dateRange}
  mode="range"
  locale="fa"
  dual_input={true}
/>

For Time Selection:

// AI: "Add time picker functionality"
let selectedTime: string;

<DatePicker
  bind:model={selectedTime}
  type="time"
  from="08:00"
  to="20:00"
/>

For Multi-Calendar Support:

// AI: "Support both Persian and Gregorian calendars"
let date: string;

<DatePicker
  bind:model={date}
  locale="fa,en"
  input_calendar="auto"
/>

🔧 Props Reference for AI

Essential Props for Common Use Cases:

• bind:model - The selected date value(s) - ALWAYS BINDABLE
• mode - Selection type: "single" | "range" | "multiple"
• type - Picker type: "date" | "time" | "datetime"
• locale - Language/calendar: "fa" | "en" | "ar" | "fa,en"
• from/to - Date boundaries (e.g., "1400/01/01", "1405/12/29")
• disable - Disabled dates/times (array, function, or regex)

Styling & UI Props:

• color - Theme: "blue" | "red" | "pink" | "orange" | "green" | "purple" | "gray"
• dual_input - Separate inputs for range mode
• modal - Show as modal overlay
• clearable - Show clear button

Advanced Props:

• format - Model data format (always Gregorian)
• input_format - Input parsing format
• display_format - UI display format
• input_calendar - Calendar for input: "auto" | "jalali" | "gregorian"

💡 AI Best Practices

1. Always use bind:model for data binding
2. Check mode prop for selection behavior
3. Use from/to props for date boundaries
4. Use disable prop for validation rules
5. Set locale appropriately for language/calendar
6. Consider dual_input for better range UX