@hamedf/svelte-persian-datepicker
Version:
A comprehensive Svelte 5 Persian/Jalali DateTime picker component with multi-calendar support (Jalali, Gregorian, Hijri), multiple selection modes (single, range, multiple), and extensive customization options
198 lines (197 loc) • 6.9 kB
TypeScript
import { PersianDate } from './modules/core';
export { PersianDate };
import type { HTMLInputAttributes } from 'svelte/elements';
import type { Langs, RecursivePartial, Styles, Disable, Shortcuts } from './modules/types';
/**
* Props interface for the Persian DatePicker component
* This component supports Jalali (Persian), Gregorian, and Hijri calendars
* with various selection modes and customization options.
*/
export interface DatePickerProps {
/**
* Callback fired when a date is selected (but not necessarily submitted)
* @example <DatePicker select={(date) => console.log('Selected:', date.toString())} />
*/
select?: (date: PersianDate) => void;
/**
* Callback fired when date selection is submitted/confirmed
* @example <DatePicker submit={(dates) => console.log('Submitted:', dates)} />
*/
submit?: (date: PersianDate | PersianDate[]) => void;
/**
* Callback fired when the input is cleared
* @example <DatePicker clear={() => console.log('Input cleared')} />
*/
clear?: () => void;
/**
* Callback fired when the datepicker opens
* @example <DatePicker open={() => setIsOpen(true)} />
*/
open?: () => void;
/**
* Callback fired when the datepicker closes
* @example <DatePicker close={() => setIsOpen(false)} />
*/
close?: () => void;
/**
* The datepicker model value - bindable prop that holds selected date(s)
* @bindable - This prop is bindable and will update parent component
* @example
* // Single date
* <DatePicker bind:model={selectedDate} />
* // Multiple dates
* <DatePicker mode="multiple" bind:model={selectedDates} />
*/
model?: PersianDate | PersianDate[] | string | string[];
/**
* Date format for the model value (always stored in Gregorian)
* @default 'YYYY-MM-DD' for date, 'YYYY-MM-DD HH:mm' for datetime, 'HH:mm' for time
* @example format="YYYY/MM/DD"
*/
format?: string;
/**
* Format for user input parsing - determined by input_calendar setting
* @default Auto-determined based on input_calendar and locale
* @example input_format="jYYYY/jMM/jDD" for Jalali calendar
*/
input_format?: string;
/**
* Format for displaying dates in the UI
* @default Auto-determined based on locale and calendar
* @example display_format="?jD ?jMMMM ?jYYYY" for Persian display
*/
display_format?: string;
/**
* Calendar system to use for input display and parsing
* @default 'auto' - uses locale's default calendar
* - 'auto': Automatically determined by locale
* - 'jalali': Persian/Jalali calendar
* - 'gregorian': Gregorian calendar
*/
input_calendar?: 'auto' | 'jalali' | 'gregorian';
/**
* Type of date/time picker to display
* @default 'date'
* - 'date': Date selection only
* - 'time': Time selection only
* - 'datetime': Both date and time selection
*/
type?: 'date' | 'time' | 'datetime';
/**
* Minimum selectable date/time
* @default new Date() set to year 1921 for date/datetime, undefined for time
* @example from={new Date('2024-01-01')} or leave undefined for time
*/
from?: Date;
/**
* Maximum selectable date/time
* @default new Date() set to year 2051 for date/datetime, undefined for time
* @example to={new Date('2030-12-31')} or leave undefined for time
*/
to?: Date;
/**
* Controls whether the datepicker is initially visible
* @default false
*/
show?: boolean;
/**
* Defines which elements can trigger the datepicker to open
* @default 'all'
* - 'all': Click on input or icon
* - 'input': Click only on input field
* - 'icon': Click only on calendar icon
* - 'none': No click interaction (programmatic only)
*/
click_on?: 'all' | 'input' | 'icon' | 'none';
/**
* Whether to show datepicker as a modal overlay
* @default false
*/
modal?: boolean;
/**
* Label text to display above the input
* @example label="Select Date"
*/
label?: string;
/**
* Number of calendar columns to display or responsive breakpoints
* @default 1
* @example column={2} or column={{768: 1, 1024: 2}} for responsive
*/
column?: number | Record<number, number>;
/**
* Whether to automatically submit when selection is complete
* @default true
* - true: Auto-submit on single/range completion
* - false: Requires manual submit button click
*/
auto_submit?: boolean;
/**
* Date selection mode
* @default 'single'
* - 'single': Select one date
* - 'range': Select a date range (start and end)
* - 'multiple': Select multiple individual dates
*/
mode?: 'single' | 'range' | 'multiple';
/**
* Locale for language and calendar system
* @default 'fa' (Persian/Farsi)
* @example locale="en" for English, locale="ar" for Arabic
* Multiple locales: locale="fa,en" (user can toggle)
*/
locale?: string;
/**
* Whether to show a clear button for the input
* @default true
*/
clearable?: boolean;
/**
* Disable specific dates, date ranges, or patterns
* @example
* // Disable specific dates
* disable={['1403/01/01', '1403/01/02']}
* // Disable with function
* disable={(date) => date.day() === 6} // Disable Fridays
*/
disable?: Disable;
/**
* Custom locale configuration to override defaults
* @example locale_config={{fa: {months: ['Jan', 'Feb', ...]}}}
*/
locale_config?: RecursivePartial<Langs>;
/**
* Custom CSS styles to apply to the component
* @example styles={{input: {backgroundColor: '#f0f0f0'}}}
*/
styles?: Styles;
/**
* Pre-defined color theme for the datepicker
* @default undefined (uses default theme)
*/
color?: 'primary' | 'blue' | 'red' | 'pink' | 'orange' | 'green' | 'purple' | 'gray';
/**
* Use separate input fields for range selection (from/to inputs)
* @default false
* Only applicable when mode="range"
*/
dual_input?: boolean;
/**
* Position the calendar icon inside the input field
* @default false
*/
icon_inside?: boolean;
/**
* Enable shortcut buttons for quick date selection
* @default false
* @example
* shortcut={true} // Use default shortcuts
* shortcut={{'Today': [new PersianDate()], 'Yesterday': [new PersianDate().subDay()]}}
*/
shortcut?: boolean | Shortcuts;
}
type Props = DatePickerProps;
type $$ComponentProps = Props & HTMLInputAttributes;
declare const DatePicker: import("svelte").Component<$$ComponentProps, {}, "model">;
type DatePicker = ReturnType<typeof DatePicker>;
export default DatePicker;