@itzsa/nepali-datepicker 0.3.1

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+import * as React from 'react';
+import { ClassValue } from 'clsx';
+
+type Locale = "en" | "ne";
+type DateParts = {
+    year: number;
+    month: number;
+    day: number;
+};
+/** BS civil date + clock time (24h). */
+type DateTimeParts = DateParts & {
+    hour: number;
+    minute: number;
+    /** Optional; included in string only when `withSeconds` is used. */
+    second?: number;
+};
+type DatePattern = "YYYY-MM-DD" | "YYYY/MM/DD" | "DD-MM-YYYY" | "DD/MM/YYYY";
+
+/**
+ * Optional CSS variable overrides applied on the root / popover.
+ * Prefer these over forking styles.css.
+ */
+type NepaliDatePickerVars = {
+    accent?: string;
+    accentForeground?: string;
+    background?: string;
+    foreground?: string;
+    muted?: string;
+    border?: string;
+    surface?: string;
+    radius?: string;
+    font?: string;
+};
+type NepaliDatePickerClassNames = {
+    root?: string;
+    field?: string;
+    input?: string;
+    trigger?: string;
+    popover?: string;
+    day?: string;
+    daySelected?: string;
+    footer?: string;
+};
+type NepaliDateRangeClassNames = NepaliDatePickerClassNames & {
+    rangeTrigger?: string;
+    rangeLabel?: string;
+    rangeMonths?: string;
+};
+
+type BsDateRange = {
+    from?: string;
+    to?: string;
+};
+type NepaliDateRangePickerProps = {
+    value?: BsDateRange;
+    defaultValue?: BsDateRange;
+    onChange?: (range: BsDateRange) => void;
+    locale?: Locale;
+    valueLocale?: Locale;
+    minDate?: string;
+    maxDate?: string;
+    minYear?: number;
+    maxYear?: number;
+    /** Show one or two months. Default `2`. */
+    numberOfMonths?: 1 | 2;
+    /** Close after both ends are selected. Default `true`. */
+    closeOnSelect?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    className?: string;
+    triggerClassName?: string;
+    popoverClassName?: string;
+    classNames?: NepaliDateRangeClassNames;
+    vars?: NepaliDatePickerVars;
+    style?: React.CSSProperties;
+    popoverStyle?: React.CSSProperties;
+    id?: string;
+    "aria-label"?: string;
+};
+declare function NepaliDateRangePicker({ value: valueProp, defaultValue, onChange, locale, valueLocale, minDate, maxDate, minYear, maxYear, numberOfMonths, closeOnSelect, placeholder, disabled, className, triggerClassName, popoverClassName, classNames, vars, style, popoverStyle, id, "aria-label": ariaLabel, }: NepaliDateRangePickerProps): React.JSX.Element;
+
+/**
+ * BS month lengths (Baisakh	o Chaitra), years 2000–2100.
+ * Community-verified Nepal Panchanga tables (same range used by common BS libraries).
+ */
+declare const BS_MONTH_DAYS: Record<number, readonly number[]>;
+declare const BS_MIN_YEAR = 2000;
+declare const BS_MAX_YEAR = 2100;
+/** BS 2000-01-01 corresponds to AD 1943-04-14 (civil date). */
+declare const BS_EPOCH_AD: {
+    readonly year: 1943;
+    readonly month: 4;
+    readonly day: 14;
+};
+
+/** Days in a BS month (1–12). */
+declare function getDaysInBsMonth(year: number, month: number): number;
+/** Total days in a BS year. */
+declare function getDaysInBsYear(year: number): number;
+declare function isValidBsDate(year: number, month: number, day: number): boolean;
+/**
+ * Convert Bikram Sambat → Anno Domini (civil calendar).
+ * Month is 1–12 (Baisakh = 1).
+ */
+declare function bsToAd(year: number, month: number, day: number): DateParts;
+/**
+ * Convert Anno Domini → Bikram Sambat.
+ * Month is 1–12.
+ */
+declare function adToBs(year: number, month: number, day: number): DateParts;
+/** Today's date in BS (local timezone civil date → BS). */
+declare function todayBs(): DateParts;
+/** Today + current local clock as BS datetime. */
+declare function todayBsDateTime(): DateTimeParts;
+/** Weekday for a BS date: 0 = Sunday … 6 = Saturday (UTC civil). */
+declare function getBsWeekday(year: number, month: number, day: number): number;
+/** Compare two date parts: -1 / 0 / 1. */
+declare function compareDateParts(a: DateParts, b: DateParts): number;
+declare function clampBsDate(parts: DateParts, min?: DateParts | null, max?: DateParts | null): DateParts;
+declare function addBsMonths(year: number, month: number, delta: number): {
+    year: number;
+    month: number;
+};
+/** Signed day difference: `b − a` (same calendar day → 0). */
+declare function diffBsDays(a: DateParts, b: DateParts): number;
+/** Add (or subtract) days on the BS calendar via AD civil arithmetic. */
+declare function addBsDays(parts: DateParts, delta: number): DateParts;
+
+/**
+ * Parse `YYYY-MM-DD HH:mm`, `YYYY-MM-DDTHH:mm`, or with `:ss`.
+ * Date-only strings get `00:00:00`.
+ */
+declare function parseDateTimeString(value: string): DateTimeParts | null;
+declare function toDateTimeString(parts: DateTimeParts, opts?: {
+    withSeconds?: boolean;
+}): string;
+declare function dateTimeToDateParts(dt: DateTimeParts): DateParts;
+declare function compareDateTimeParts(a: DateTimeParts, b: DateTimeParts): number;
+declare function clampDateTime(parts: DateTimeParts, min?: DateTimeParts | null, max?: DateTimeParts | null): DateTimeParts;
+/** Bound string may be date-only (`YYYY-MM-DD`) or full datetime. */
+declare function parseDateTimeBound(value: string | undefined, edge: "min" | "max"): DateTimeParts | null;
+declare function isCompleteBsDateTime(value: string, opts?: {
+    requireSeconds?: boolean;
+}): boolean;
+/** Round minute down to step (e.g. 15 → 0,15,30,45). */
+declare function snapMinute(minute: number, step: number): number;
+
+/** Parse `YYYY-MM-DD` or `YYYY/MM/DD` (ASCII) into parts. Returns null if invalid. */
+declare function parseDateString(value: string): DateParts | null;
+/**
+ * Mask typed digits into `YYYY-MM-DD` as the user types (max 8 digits).
+ * Does not validate calendar correctness — only formatting.
+ */
+declare function formatTypedBsDate(raw: string): string;
+/** True when the string is a complete, calendar-valid BS date. */
+declare function isCompleteBsDate(value: string): boolean;
+/** Format parts as ASCII `YYYY-MM-DD` (canonical value format). */
+declare function toDateString(parts: DateParts): string;
+declare function formatDateParts(parts: DateParts, pattern?: DatePattern, locale?: Locale): string;
+/** Human-readable label, e.g. `15 Magh 2082` / `१५ माघ २०८२`. */
+declare function formatBsLabel(parts: DateParts, locale?: Locale): string;
+/** e.g. `15 Magh 2082, 14:30` */
+declare function formatBsDateTimeLabel(parts: DateTimeParts, locale?: Locale, opts?: {
+    withSeconds?: boolean;
+}): string;
+
+declare const NEPALI_MONTH_NAMES_EN: readonly ["Baisakh", "Jestha", "Ashar", "Shrawan", "Bhadra", "Ashwin", "Kartik", "Mangsir", "Poush", "Magh", "Falgun", "Chaitra"];
+declare const NEPALI_MONTH_NAMES_NE: readonly ["बैशाख", "जेठ", "असार", "साउन", "भदौ", "असोज", "कार्तिक", "मंसिर", "पुष", "माघ", "फाल्गुन", "चैत"];
+declare const WEEKDAY_NAMES_EN: readonly ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+declare const WEEKDAY_NAMES_NE: readonly ["आइत", "सोम", "मंगल", "बुध", "बिही", "शुक्र", "शनि"];
+declare function getMonthName(month: number, locale?: Locale): string;
+declare function getWeekdayNames(locale?: Locale): readonly string[];
+/** Map ASCII digits to Devanagari when locale is `ne`. */
+declare function localizeDigits(value: string | number, locale: Locale): string;
+
+type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: ValidationCode;
+    message: string;
+};
+type ValidationCode = "required" | "type" | "year_range" | "month_range" | "day_range" | "invalid_date";
+/** Assert BS year is an integer in the supported table range. */
+declare function assertBsYear(year: number): void;
+declare function assertBsMonth(month: number): void;
+declare function assertBsDay(day: number): void;
+/**
+ * Soft validation (no throw). Use in forms before submit.
+ * Equivalent purpose to the jQuery plugin checks — without its compressed calendar codec.
+ */
+declare function validateBsDate(year: number, month: number, day: number): ValidationResult;
+declare function validateBsDateParts(parts: DateParts): ValidationResult;
+/** Throw if invalid — mirrors jQuery plugin hard checks. */
+declare function assertValidBsDate(year: number, month: number, day: number): void;
+
+type NepaliDatePickerProps = {
+    /** Controlled BS date as `YYYY-MM-DD` (ASCII). Empty string = no selection. */
+    value?: string;
+    /** Uncontrolled initial value. */
+    defaultValue?: string;
+    /** Called with canonical `YYYY-MM-DD` BS string (or `""` when cleared). */
+    onChange?: (value: string) => void;
+    /** Fired when a day is clicked (before close). */
+    onSelect?: (value: string) => void;
+    /** Calendar UI locale (month/weekday names + digits). Default `"ne"`. */
+    locale?: Locale;
+    /** Digits/locale for the input display. Default matches `locale`. */
+    valueLocale?: Locale;
+    /** Minimum selectable BS date `YYYY-MM-DD`. */
+    minDate?: string;
+    /** Maximum selectable BS date `YYYY-MM-DD`. */
+    maxDate?: string;
+    /** Inclusive year bounds (defaults to supported calendar range). */
+    minYear?: number;
+    maxYear?: number;
+    /** Close popover after picking a day. Default `true`. */
+    closeOnSelect?: boolean;
+    /** If value is empty, show today as the initial calendar month. Default `true`. */
+    todayIfEmpty?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    id?: string;
+    name?: string;
+    required?: boolean;
+    className?: string;
+    inputClassName?: string;
+    popoverClassName?: string;
+    /** Per-part class overrides (merged with defaults). */
+    classNames?: NepaliDatePickerClassNames;
+    /** Theme tokens as CSS variables (`accent`, `border`, `radius`, …). */
+    vars?: NepaliDatePickerVars;
+    /** Inline styles on the root (merged with `vars`). */
+    style?: React.CSSProperties;
+    /** Inline styles on the popover panel. */
+    popoverStyle?: React.CSSProperties;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+};
+declare const NepaliDatePicker: React.ForwardRefExoticComponent<NepaliDatePickerProps & React.RefAttributes<HTMLInputElement>>;
+
+type EditableNepaliDatePickerProps = {
+    /** Controlled value — may be partial while typing (`2082-0`, `2082-04-1`, …). */
+    value?: string;
+    defaultValue?: string;
+    /**
+     * Fires on every keystroke with masked `YYYY-MM-DD` digits,
+     * and when a calendar day is picked (always complete & valid).
+     */
+    onChange?: (value: string) => void;
+    onSelect?: (value: string) => void;
+    locale?: Locale;
+    minDate?: string;
+    maxDate?: string;
+    minYear?: number;
+    maxYear?: number;
+    closeOnSelect?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    id?: string;
+    name?: string;
+    required?: boolean;
+    className?: string;
+    inputClassName?: string;
+    popoverClassName?: string;
+    classNames?: NepaliDatePickerClassNames;
+    vars?: NepaliDatePickerVars;
+    style?: React.CSSProperties;
+    popoverStyle?: React.CSSProperties;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+};
+declare const EditableNepaliDatePicker: React.ForwardRefExoticComponent<EditableNepaliDatePickerProps & React.RefAttributes<HTMLInputElement>>;
+
+type NepaliDateTimePickerProps = {
+    /** Controlled BS datetime `YYYY-MM-DD HH:mm` (ASCII). Empty = none. */
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    onSelect?: (value: string) => void;
+    locale?: Locale;
+    valueLocale?: Locale;
+    /**
+     * Minimum — date-only (`YYYY-MM-DD` → start of day) or full
+     * `YYYY-MM-DD HH:mm`.
+     */
+    minDateTime?: string;
+    /** Alias of `minDateTime` (date-only or datetime). */
+    minDate?: string;
+    /**
+     * Maximum — date-only (`YYYY-MM-DD` → end of day) or full datetime.
+     */
+    maxDateTime?: string;
+    /** Alias of `maxDateTime`. */
+    maxDate?: string;
+    minYear?: number;
+    maxYear?: number;
+    /** Minute increment. Default `5`. */
+    minuteStep?: number;
+    /** Include seconds in value / UI. Default `false`. */
+    withSeconds?: boolean;
+    /** Close after Confirm. Default `true`. */
+    closeOnSelect?: boolean;
+    todayIfEmpty?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    id?: string;
+    name?: string;
+    required?: boolean;
+    className?: string;
+    inputClassName?: string;
+    popoverClassName?: string;
+    classNames?: NepaliDatePickerClassNames;
+    vars?: NepaliDatePickerVars;
+    style?: React.CSSProperties;
+    popoverStyle?: React.CSSProperties;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+};
+declare const NepaliDateTimePicker: React.ForwardRefExoticComponent<NepaliDateTimePickerProps & React.RefAttributes<HTMLInputElement>>;
+
+declare function cn(...inputs: ClassValue[]): string;
+declare function mergeRefs<T>(...refs: Array<React.Ref<T> | undefined | null>): React.RefCallback<T>;
+
+export { BS_EPOCH_AD, BS_MAX_YEAR, BS_MIN_YEAR, BS_MONTH_DAYS, type BsDateRange, type DateParts, type DatePattern, type DateTimeParts, EditableNepaliDatePicker, type EditableNepaliDatePickerProps, type Locale, NEPALI_MONTH_NAMES_EN, NEPALI_MONTH_NAMES_NE, NepaliDatePicker, type NepaliDatePickerClassNames, type NepaliDatePickerProps, type NepaliDatePickerVars, type NepaliDateRangeClassNames, NepaliDateRangePicker, type NepaliDateRangePickerProps, NepaliDateTimePicker, type NepaliDateTimePickerProps, type ValidationCode, type ValidationResult, WEEKDAY_NAMES_EN, WEEKDAY_NAMES_NE, adToBs, addBsDays, addBsMonths, assertBsDay, assertBsMonth, assertBsYear, assertValidBsDate, bsToAd, clampBsDate, clampDateTime, cn, compareDateParts, compareDateTimeParts, dateTimeToDateParts, diffBsDays, formatBsDateTimeLabel, formatBsLabel, formatDateParts, formatTypedBsDate, getBsWeekday, getDaysInBsMonth, getDaysInBsYear, getMonthName, getWeekdayNames, isCompleteBsDate, isCompleteBsDateTime, isValidBsDate, localizeDigits, mergeRefs, parseDateString, parseDateTimeBound, parseDateTimeString, snapMinute, toDateString, toDateTimeString, todayBs, todayBsDateTime, validateBsDate, validateBsDateParts };