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
• Smart Range Selection:
  • Cross-Month Preview: See your selected range highlight even when navigating between months.
  • Dynamic Disabling: Automatically disables dates before the start date during range selection.
  • Easy Reset: Clicking a new date when a range is already selected resets and starts a new selection.
• Reactive Model: Seamlessly syncs with parent state changes, supporting asynchronous data loading.

🚀 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 = $state(''); // Svelte 5 rune

	function handleSubmit(date) {
		console.log('Selected date:', date);
	}
</script>

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

Note: For more advanced examples including range selection, async loading, and disabling dates, check out the demo route in the repository.

🎯 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"
/>

Disable Previous Dates (Select from Today)

<DatePicker
	bind:model={selectedDate}
	from={new Date()}
	color="orange"
	label="Select future date"
/>

🤖 GitHub Copilot Integration

This package includes a specialized instruction file for GitHub Copilot. When you use this package in your project, Copilot will automatically understand the Svelte 5 runes, the Gregorian model requirement, and the various selection modes.

You can find the detailed instructions in .github/copilot-instructions.md.

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

| Prop | Type | Default | Description | | ---------------- | ------------------------------------------------------------------------ | ----------- | -------------------------- | | model | string \| string[] \| PersianDate \| PersianDate[] | undefined | The selected value(s) (Bindable) | | mode | 'single' \| 'range' \| 'multiple' | 'single' | Selection mode | | type | 'date' \| 'time' \| 'datetime' | 'date' | Type of picker | | format | string | undefined | Output format (Gregorian) | | input_format | string | undefined | Input parsing format | | display_format | string | undefined | UI display format | | color | 'blue' \| 'red' \| 'pink' \| 'orange' \| 'green' \| 'purple' \| 'gray' | undefined | Color theme | | locale | string | 'fa' | Locale (fa, en, ar) | | clearable | boolean | true | Show clear button | | auto_submit | boolean | true | Auto submit on selection | | modal | boolean | false | Display as modal | | dual_input | boolean | false | Separate inputs for range | | shortcut | boolean \| object | false | Enable shortcuts | | column | number \| object | 1 | Number of calendar columns | | from | Date \| string | 1921-03-22| Minimum selectable date | | to | Date \| string | 2051-03-21| Maximum selectable date | | disable | string[] \| function \| RegExp | undefined | Custom disable rules |

🎨 Events

| Event | Parameters | Description | | -------- | ------------------------------------ | ---------------------------- | | submit | date: PersianDate \| PersianDate[] | Fired when date is submitted | | select | date: PersianDate | Fired when date is selected | | clear | none | Fired when picker is cleared | | open | none | Fired when picker opens | | close | none | Fired when picker closes |

🎨 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

| Feature | Single | Range | Multiple | Time | DateTime | DateTime Range | | --------------------- | ------ | ----- | -------- | ---- | -------- | -------------- | | Select one date | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | | Select date range | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | | Select multiple dates | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | | Time selection | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | | Persian calendar | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Keyboard navigation | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | Custom validation | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

🤖 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 & REACTIVE
• mode - Selection type: "single" | "range" | "multiple"
• type - Picker type: "date" | "time" | "datetime"
• locale - Language/calendar: "fa" | "en" | "ar" | "fa,en"
• from/to - Date boundaries (supports Date objects or strings)
• 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. The component will automatically sync if the parent updates the value.
2. Range Selection: The component handles the flow (Start -> End). If a range is already selected, the next click resets it.
3. Date Boundaries: Use from={new Date()} to disable all previous dates easily.
4. Model Format: Remember that the model always uses Gregorian format (YYYY-MM-DD) for consistency, regardless of the displayed calendar.
5. Async Data: You can initialize the model with an empty string and update it later (e.g., after a fetch); the component will react accordingly.
6. Use from/to props for date boundaries
7. Use disable prop for validation rules
8. Set locale appropriately for language/calendar
9. Consider dual_input for better range UX