@nepdatejs/datepicker 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,420 @@
+import { AdDate, BsDate, CalendarDate, CalendarSystem, DateFormatPattern, LocaleCode, TimeOfDay, Weekday } from "@nepdatejs/core";
+import { CalendarState, CalendarStore, EventMarker, HolidayInput, HolidayLookup } from "@nepdatejs/calendar";
+//#region src/presets.d.ts
+/** Built-in shortcuts for a single date. */
+type SinglePresetId = "today" | "yesterday" | "tomorrow";
+/** Built-in shortcuts for a range. Weeks, months and years count in the calendar on screen. */
+type RangePresetId = "today" | "yesterday" | "thisWeek" | "lastWeek" | "last7Days" | "last30Days" | "thisMonth" | "lastMonth" | "thisYear" | "thisFiscalYear" | "lastFiscalYear";
+/** What a preset gets to work out its date: today (in the configured zone), the calendar on screen, the week start. */
+interface PresetContext {
+  readonly today: AdDate;
+  readonly calendar: CalendarSystem;
+  readonly weekStartsOn: Weekday;
+}
+interface PresetRange {
+  readonly start: CalendarDate;
+  readonly end: CalendarDate;
+}
+/** An app-defined shortcut, e.g. { id: 'admission', label: 'Admission day', resolve: () => bsDate(2083, 1, 15) }. */
+interface CustomPreset<R> {
+  readonly id: string;
+  readonly label: string;
+  readonly resolve: (context: PresetContext) => R;
+}
+type SinglePreset = SinglePresetId | CustomPreset<CalendarDate>;
+type RangePreset = RangePresetId | CustomPreset<PresetRange>;
+/** One shortcut as the panel shows it. */
+interface PresetState {
+  readonly id: string;
+  readonly label: string;
+  /** The current value is exactly this preset's date or range. */
+  readonly isActive: boolean;
+  /** Outside min/max, too short/long, or outside the BS table. */
+  readonly isDisabled: boolean;
+}
+/** The date a built-in single preset stands for. */
+export declare function resolveSinglePreset(id: SinglePresetId, context: PresetContext): CalendarDate;
+/** The range a built-in range preset stands for, in the calendar on screen. */
+export declare function resolveRangePreset(id: RangePresetId, context: PresetContext): PresetRange;
+//#endregion
+//#region src/types.d.ts
+/** The same day in both calendars, sent with every change. */
+interface DateDetail {
+  readonly ad: AdDate;
+  readonly bs: BsDate;
+}
+type DateErrorCode = "format" | "range" | "disabled" | "tooShort" | "tooLong" | "tooMany";
+interface DateError {
+  readonly code: DateErrorCode;
+  /** Already translated for the picker's locale. */
+  readonly message: string;
+}
+/** Options both pickers share. Dates in options are AD "YYYY-MM-DD" strings (docs/plan D-003). */
+interface PickerBaseOptions {
+  /** Show and type dates in this calendar only, and hide the BS/AD switch. */
+  readonly calendar?: CalendarSystem | undefined;
+  /** The calendar shown first when switching is allowed. Default 'BS'. */
+  readonly defaultCalendar?: CalendarSystem | undefined;
+  /** Called when the user switches BS/AD (adapters may remember it). */
+  readonly onCalendarChange?: ((calendar: CalendarSystem) => void) | undefined;
+  /** Earliest and latest allowed days, as AD "YYYY-MM-DD". */
+  readonly min?: string | undefined;
+  readonly max?: string | undefined;
+  readonly isDateDisabled?: ((date: CalendarDate) => boolean) | undefined;
+  readonly locale?: LocaleCode | undefined;
+  /** How the input shows a date. Default 'iso' (YYYY-MM-DD), which can be typed back. */
+  readonly displayFormat?: DateFormatPattern | undefined;
+  /** Close the panel after a pick. Default true. */
+  readonly closeOnSelect?: boolean | undefined;
+  /** Show the calendar in the page, always open, instead of in a popover. Default false. */
+  readonly inline?: boolean | undefined;
+  /** Add the dashes of YYYY-MM-DD while the user types digits. Default true. */
+  readonly mask?: boolean | undefined;
+  readonly holidays?: readonly HolidayInput[] | HolidayLookup | undefined;
+  readonly events?: ((date: CalendarDate) => readonly EventMarker[]) | undefined;
+  readonly showOtherCalendar?: boolean | undefined;
+  readonly weekStartsOn?: Weekday | undefined;
+  readonly weekendDays?: readonly Weekday[] | undefined;
+  /** Override "today" (tests, server rendering). */
+  readonly today?: CalendarDate | undefined;
+}
+interface DatePickerOptions extends PickerBaseOptions {
+  /** AD "YYYY-MM-DD" or "". Passing it again through setOptions replaces the value. */
+  readonly value?: string | undefined;
+  /** The starting value when the picker keeps its own state. */
+  readonly defaultValue?: string | undefined;
+  readonly onChange?: ((value: string, detail: DateDetail | null) => void) | undefined;
+  /** Shortcuts shown in the panel: 'today', 'yesterday', 'tomorrow' or your own. */
+  readonly presets?: readonly SinglePreset[] | undefined;
+}
+interface DatePickerState {
+  /** AD "YYYY-MM-DD", or "" when empty or invalid. Never a BS date. */
+  readonly value: string;
+  readonly date: DateDetail | null;
+  /** What the input shows. */
+  readonly text: string;
+  /** The calendar the input and panel use. */
+  readonly calendar: CalendarSystem;
+  readonly canSwitchCalendar: boolean;
+  /** The panel is showing. Always true for an inline picker. */
+  readonly open: boolean;
+  /** The calendar sits in the page and never closes (option `inline`). */
+  readonly inline: boolean;
+  readonly error: DateError | null;
+  /** The same day in the other calendar, e.g. "10 October 2026 AD". */
+  readonly equivalentText: string | null;
+  /** "YYYY-MM-DD (BS)" */
+  readonly placeholder: string;
+  readonly presets: readonly PresetState[];
+  readonly calendarState: CalendarState;
+}
+interface DatePickerActions {
+  /** The user typed. Updates the value when the text is a valid, allowed date. */
+  type(text: string): void;
+  /** Tidy the text ("2083/6/4" → "2083-06-04") unless it has an error. */
+  blur(): void;
+  clear(): void;
+  /** Set the value from outside; does not call onChange. */
+  setValue(value: string): void;
+  open(): void;
+  close(): void;
+  toggle(): void;
+  /** Show BS or AD. The value does not change. Ignored when the calendar is fixed. */
+  switchCalendar(calendar: CalendarSystem): void;
+  /** Pick a day (e.g. from the panel). Returns false when the day is disabled. */
+  select(date: CalendarDate): boolean;
+  /** Returns false when today is not allowed. */
+  selectToday(): boolean;
+  /** Back to defaultValue (form reset). */
+  reset(): void;
+  /** Apply a shortcut by id. Returns false when it is disabled or unknown. */
+  applyPreset(id: string): boolean;
+}
+interface DatePickerStore {
+  getState(): DatePickerState;
+  subscribe(listener: () => void): () => void;
+  setOptions(changes: Partial<DatePickerOptions>): void;
+  readonly actions: DatePickerActions;
+  /** The panel's calendar store, for adapters (keyboard moves, views, hover). */
+  readonly calendar: CalendarStore;
+  destroy(): void;
+}
+interface RangeValue {
+  readonly start: string;
+  readonly end: string;
+}
+interface RangeDetail {
+  readonly start: DateDetail | null;
+  readonly end: DateDetail | null;
+}
+interface DateRangePickerOptions extends PickerBaseOptions {
+  readonly value?: RangeValue | undefined;
+  readonly defaultValue?: RangeValue | undefined;
+  readonly onChange?: ((value: RangeValue, detail: RangeDetail) => void) | undefined;
+  /** Shortest and longest allowed range, in days, counting both ends. */
+  readonly minDays?: number | undefined;
+  readonly maxDays?: number | undefined;
+  /** Shortcuts: 'last7Days', 'thisMonth', 'thisFiscalYear', … or your own. */
+  readonly presets?: readonly RangePreset[] | undefined;
+}
+type RangeField = "start" | "end";
+interface DateRangePickerState {
+  readonly value: RangeValue;
+  readonly date: RangeDetail;
+  readonly startText: string;
+  readonly endText: string;
+  readonly calendar: CalendarSystem;
+  readonly canSwitchCalendar: boolean;
+  /** The panel is showing. Always true for an inline picker. */
+  readonly open: boolean;
+  /** The calendar sits in the page and never closes (option `inline`). */
+  readonly inline: boolean;
+  /** The first problem, and which field it belongs to ('range' for length problems). */
+  readonly error: (DateError & {
+    readonly field: RangeField | "range";
+  }) | null;
+  readonly equivalentText: {
+    readonly start: string | null;
+    readonly end: string | null;
+  };
+  readonly placeholder: string;
+  readonly presets: readonly PresetState[];
+  readonly calendarState: CalendarState;
+}
+interface DateRangePickerActions {
+  type(field: RangeField, text: string): void;
+  blur(field: RangeField): void;
+  clear(): void;
+  setValue(value: RangeValue): void;
+  open(): void;
+  close(): void;
+  toggle(): void;
+  switchCalendar(calendar: CalendarSystem): void;
+  /** A click in the panel: first sets the start, second the end. */
+  select(date: CalendarDate): boolean;
+  reset(): void;
+  /** Apply a shortcut by id. Returns false when it is disabled or unknown. */
+  applyPreset(id: string): boolean;
+}
+interface DateRangePickerStore {
+  getState(): DateRangePickerState;
+  subscribe(listener: () => void): () => void;
+  setOptions(changes: Partial<DateRangePickerOptions>): void;
+  readonly actions: DateRangePickerActions;
+  readonly calendar: CalendarStore;
+  destroy(): void;
+}
+interface MultiDatePickerOptions extends PickerBaseOptions {
+  /** AD "YYYY-MM-DD" days. Passing it again through setOptions replaces the value. */
+  readonly value?: readonly string[] | undefined;
+  readonly defaultValue?: readonly string[] | undefined;
+  readonly onChange?: ((value: readonly string[], dates: readonly DateDetail[]) => void) | undefined;
+  /** The most days that may be chosen. */
+  readonly maxDates?: number | undefined;
+}
+interface MultiDatePickerState {
+  /** AD "YYYY-MM-DD" days, sorted, no repeats. Never BS dates. */
+  readonly value: readonly string[];
+  readonly dates: readonly DateDetail[];
+  /** What the input shows: the days as YYYY-MM-DD, separated by ", ". */
+  readonly text: string;
+  readonly calendar: CalendarSystem;
+  readonly canSwitchCalendar: boolean;
+  /** The panel is showing. Always true for an inline picker. */
+  readonly open: boolean;
+  readonly inline: boolean;
+  readonly error: DateError | null;
+  readonly placeholder: string;
+  readonly calendarState: CalendarState;
+}
+interface MultiDatePickerActions {
+  /** The user typed days separated by commas or spaces. */
+  type(text: string): void;
+  /** Tidy the text unless it has an error. */
+  blur(): void;
+  clear(): void;
+  /** Set the value from outside; does not call onChange. */
+  setValue(value: readonly string[]): void;
+  open(): void;
+  close(): void;
+  toggle(): void;
+  switchCalendar(calendar: CalendarSystem): void;
+  /** Add the day, or remove it when chosen. Returns false when disabled or over maxDates. */
+  select(date: CalendarDate): boolean;
+  /** Remove one day, by its AD "YYYY-MM-DD" value. */
+  remove(value: string): void;
+  /** Back to defaultValue (form reset). */
+  reset(): void;
+}
+interface MultiDatePickerStore {
+  getState(): MultiDatePickerState;
+  subscribe(listener: () => void): () => void;
+  setOptions(changes: Partial<MultiDatePickerOptions>): void;
+  readonly actions: MultiDatePickerActions;
+  readonly calendar: CalendarStore;
+  destroy(): void;
+}
+//#endregion
+//#region src/picker.d.ts
+/**
+ * A BS/AD date picker without UI: typed text ⇄ value, validation, the BS/AD
+ * switch and open/close, plus the panel's calendar store. The value is always
+ * an AD "YYYY-MM-DD" string (docs/plan D-003); all date work goes through core.
+ *
+ * Like the calendar, the picker keeps its own value; passing `value` through
+ * setOptions replaces it (controlled use). Passing back the value the user just
+ * typed leaves their text alone, so the cursor does not jump.
+ */
+export declare function createDatePicker(initial?: DatePickerOptions): DatePickerStore;
+//#endregion
+//#region src/range.d.ts
+/**
+ * A BS/AD date range picker without UI: two typed fields (start, end), a panel
+ * calendar in range mode, minDays/maxDays checks and the BS/AD switch. Values
+ * are AD "YYYY-MM-DD" strings; an unfinished or invalid end is "".
+ */
+export declare function createDateRangePicker(initial?: DateRangePickerOptions): DateRangePickerStore;
+//#endregion
+//#region src/mask.d.ts
+/**
+ * Add the dashes of YYYY-MM-DD while the user types digits: "2083" becomes
+ * "2083-", "208306" becomes "2083-06-" and a pasted "20830624" becomes
+ * "2083-06-24". ASCII and Devanagari digits keep their script, and a
+ * separator typed straight after a dash is dropped, so typing the dashes
+ * yourself works too. Only text that grew at the end (typing, or a paste into
+ * an empty field) is touched: deleting, editing in the middle and other
+ * separators ("2083/6/4") are left as the user wrote them. Pure.
+ */
+export declare function maskDateText(next: string, previous?: string): string;
+//#endregion
+//#region src/multi.d.ts
+/**
+ * A picker for several separate days (PICK-001). The value is a sorted list of
+ * AD "YYYY-MM-DD" strings; the input lists the days in the calendar on screen,
+ * separated by ", ", and clicking a day in the panel adds or removes it. The
+ * list is always written as YYYY-MM-DD so it can be typed back.
+ */
+export declare function createMultiDatePicker(initial?: MultiDatePickerOptions): MultiDatePickerStore;
+//#endregion
+//#region src/datetime.d.ts
+interface DateTimeDetail {
+  readonly ad: AdDate;
+  readonly bs: BsDate;
+  readonly time: TimeOfDay;
+  /** The same instant as the value. */
+  readonly iso: string;
+}
+interface DateTimePickerOptions extends PickerBaseOptions {
+  /** An ISO timestamp with offset ("2026-10-18T14:30:00+05:45"), a local "YYYY-MM-DDTHH:MM", or "". */
+  readonly value?: string | undefined;
+  readonly defaultValue?: string | undefined;
+  readonly onChange?: ((value: string, detail: DateTimeDetail | null) => void) | undefined;
+  /** The zone the date and time are read in, and whose offset the value carries. Default: core config (Nepal). */
+  readonly timeZone?: string | undefined;
+  /** Show 12-hour times (2:30 PM). Default false (14:30). */
+  readonly hour12?: boolean | undefined;
+  /** Minutes offered in the column: 1–30. Default 5. Any minute can still be typed. */
+  readonly minuteStep?: number | undefined;
+  /** The time used when a date is picked before any time. Default "00:00". */
+  readonly defaultTime?: string | undefined;
+  readonly presets?: readonly SinglePreset[] | undefined;
+}
+/** One hour or minute in the time columns (Figma "Time Item"). */
+interface TimeCell {
+  readonly value: number;
+  readonly label: string;
+  readonly isSelected: boolean;
+}
+interface DateTimePickerState {
+  /** ISO timestamp with the zone's offset, or "" until both date and time are valid. */
+  readonly value: string;
+  readonly detail: DateTimeDetail | null;
+  readonly dateText: string;
+  readonly timeText: string;
+  readonly time: TimeOfDay | null;
+  readonly calendar: CalendarSystem;
+  readonly canSwitchCalendar: boolean;
+  /** The panel is showing. Always true for an inline picker. */
+  readonly open: boolean;
+  /** The calendar sits in the page and never closes (option `inline`). */
+  readonly inline: boolean;
+  readonly error: (DateError & {
+    readonly field: "date" | "time";
+  }) | null;
+  readonly equivalentText: string | null;
+  readonly placeholder: string;
+  readonly timePlaceholder: string;
+  readonly hours: readonly TimeCell[];
+  readonly minutes: readonly TimeCell[];
+  readonly presets: readonly PresetState[];
+  readonly calendarState: CalendarState;
+}
+interface DateTimePickerActions {
+  typeDate(text: string): void;
+  typeTime(text: string): void;
+  blurDate(): void;
+  blurTime(): void;
+  /** Pick a day; the time stays (or becomes defaultTime). Returns false when disabled. */
+  selectDate(date: CalendarDate): boolean;
+  selectHour(hour: number): void;
+  selectMinute(minute: number): void;
+  /** Today and the current time in the zone. Returns false when today is not allowed. */
+  selectNow(): boolean;
+  applyPreset(id: string): boolean;
+  open(): void;
+  close(): void;
+  toggle(): void;
+  clear(): void;
+  setValue(value: string): void;
+  switchCalendar(calendar: CalendarSystem): void;
+  reset(): void;
+}
+interface DateTimePickerStore {
+  getState(): DateTimePickerState;
+  subscribe(listener: () => void): () => void;
+  setOptions(changes: Partial<DateTimePickerOptions>): void;
+  readonly actions: DateTimePickerActions;
+  readonly calendar: CalendarStore;
+  destroy(): void;
+}
+/**
+ * A BS/AD date and time picker without UI. The date half is a regular date
+ * picker; the value is the instant as an ISO timestamp carrying the zone's
+ * offset, so servers store one unambiguous moment.
+ */
+export declare function createDateTimePicker(initial?: DateTimePickerOptions): DateTimePickerStore;
+//#endregion
+//#region src/input.d.ts
+/** What a picker allows, in any calendar. */
+interface InputLimits {
+  readonly min: CalendarDate;
+  readonly max: CalendarDate;
+  /** Whether the app set min/max (else they are the edges of the BS table). Picks the message. */
+  readonly hasMin?: boolean;
+  readonly hasMax?: boolean;
+  readonly isDateDisabled?: ((date: CalendarDate) => boolean) | undefined;
+}
+type ParseResult = {
+  readonly kind: "empty";
+} | {
+  readonly kind: "date";
+  readonly date: AdDate;
+} | {
+  readonly kind: "error";
+  readonly error: DateError;
+};
+/**
+ * Read what the user typed: year first, ASCII or Devanagari digits, in the
+ * calendar on screen. All date work is done by core (docs/plan D-005).
+ */
+export declare function parseInput(text: string, calendar: CalendarSystem, limits: InputLimits, locale: LocaleCode, format?: DateFormatPattern): ParseResult;
+/** Null when the day is allowed; otherwise a translated error. */
+export declare function checkDate(date: CalendarDate, calendar: CalendarSystem, limits: InputLimits, locale: LocaleCode, format?: DateFormatPattern): DateError | null;
+/** How the input shows a date: in the calendar on screen, with the locale's digits. */
+export declare function formatInput(date: CalendarDate | null, calendar: CalendarSystem, format: DateFormatPattern, locale: LocaleCode): string;
+/** "10 October 2026 AD": the same day in the other calendar. */
+export declare function equivalentText(date: CalendarDate | null, calendar: CalendarSystem, locale: LocaleCode): string | null;
+export declare function placeholderText(calendar: CalendarSystem, locale: LocaleCode): string;
+//#endregion
+export type { CustomPreset, DateDetail, DateError, DateErrorCode, DatePickerActions, DatePickerOptions, DatePickerState, DatePickerStore, DateRangePickerActions, DateRangePickerOptions, DateRangePickerState, DateRangePickerStore, DateTimeDetail, DateTimePickerActions, DateTimePickerOptions, DateTimePickerState, DateTimePickerStore, InputLimits, MultiDatePickerActions, MultiDatePickerOptions, MultiDatePickerState, MultiDatePickerStore, ParseResult, PickerBaseOptions, PresetContext, PresetRange, PresetState, RangeDetail, RangeField, RangePreset, RangePresetId, RangeValue, SinglePreset, SinglePresetId, TimeCell };
+//# sourceMappingURL=index.d.ts.map