@reachweb/alpine-calendar 0.1.1

package/dist/core/calendar-date.d.ts

@@ -0,0 +1,58 @@
+/**
+ * CalendarDate — a timezone-safe date value object.
+ *
+ * Stores year/month/day as plain integers. No internal `Date` object.
+ * The only place we touch native `Date` / `Intl.DateTimeFormat` is in
+ * `toNativeDate()`, `fromNativeDate()`, `today()`, and `format()`.
+ */
+export declare class CalendarDate {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    constructor(year: number, month: number, day: number);
+    /** Resolve "today" in a given IANA timezone (fallback: browser default). */
+    static today(timezone?: string): CalendarDate;
+    /** Create from a native Date, interpreting it in the given timezone. */
+    static fromNativeDate(date: Date, timezone?: string): CalendarDate;
+    /** Create from an ISO string (YYYY-MM-DD). Returns null for invalid formats or out-of-range values. */
+    static fromISO(iso: string): CalendarDate | null;
+    /** Convert to a native Date (midnight local time). */
+    toNativeDate(): Date;
+    /** Serialize to ISO string YYYY-MM-DD. */
+    toISO(): string;
+    /** Unique string key for use in Sets/Maps. */
+    toKey(): string;
+    isSame(other: CalendarDate): boolean;
+    isBefore(other: CalendarDate): boolean;
+    isAfter(other: CalendarDate): boolean;
+    /** Inclusive range check: start <= this <= end. */
+    isBetween(start: CalendarDate, end: CalendarDate): boolean;
+    /**
+     * Number of days from this date to another.
+     * Positive when `other` is after `this`, negative when before.
+     * Uses UTC to avoid DST issues.
+     */
+    diffDays(other: CalendarDate): number;
+    addDays(days: number): CalendarDate;
+    /** Add months with day clamping (e.g. Jan 31 + 1 month = Feb 28/29). */
+    addMonths(months: number): CalendarDate;
+    addYears(years: number): CalendarDate;
+    startOfMonth(): CalendarDate;
+    endOfMonth(): CalendarDate;
+    /**
+     * Format the date using Intl.DateTimeFormat options.
+     *
+     * @param options - Intl.DateTimeFormat options (e.g. { month: 'long', year: 'numeric' })
+     * @param locale  - BCP 47 locale string (default: browser locale)
+     */
+    format(options: Intl.DateTimeFormatOptions, locale?: string): string;
+}
+/** Return the number of days in a given month (1-12). */
+export declare function daysInMonth(year: number, month: number): number;
+/**
+ * Return the ISO 8601 week number for a given date.
+ *
+ * ISO weeks start on Monday. Week 1 is the week containing the year's first Thursday.
+ * Returns a number between 1 and 53.
+ */
+export declare function getISOWeekNumber(date: CalendarDate): number;

package/dist/core/constraints.d.ts

@@ -0,0 +1,193 @@
+import { CalendarDate } from './calendar-date';
+/**
+ * Constraint properties that can be set globally or overridden per rule.
+ *
+ * All properties are optional — only specified constraints are enforced.
+ */
+export interface DateConstraintProperties {
+    /** Earliest selectable date (inclusive). */
+    minDate?: CalendarDate;
+    /** Latest selectable date (inclusive). */
+    maxDate?: CalendarDate;
+    /** Specific dates to disable (blacklist). */
+    disabledDates?: CalendarDate[];
+    /** Days of the week to disable (0 = Sunday, 1 = Monday, …, 6 = Saturday). */
+    disabledDaysOfWeek?: number[];
+    /** Specific dates to force-enable (overrides disabledDates and disabledDaysOfWeek). */
+    enabledDates?: CalendarDate[];
+    /** Days of the week to enable (whitelist — all other days are disabled). */
+    enabledDaysOfWeek?: number[];
+    /** Specific months to disable (1 = January, …, 12 = December). */
+    disabledMonths?: number[];
+    /** Months to enable (whitelist — all other months are disabled). */
+    enabledMonths?: number[];
+    /** Specific years to disable. */
+    disabledYears?: number[];
+    /** Years to enable (whitelist — all other years are disabled). */
+    enabledYears?: number[];
+    /** Minimum range length in days (inclusive). Only used in range mode. */
+    minRange?: number;
+    /** Maximum range length in days (inclusive). Only used in range mode. */
+    maxRange?: number;
+}
+/**
+ * A period-specific constraint rule that overrides global settings.
+ *
+ * When checking a date, matching rules are resolved by priority (highest wins).
+ * Among rules with equal priority, the first matching rule wins (array order).
+ * Unset properties inherit from the global configuration.
+ *
+ * Rules can match by date range (`from`/`to`) or by recurring months
+ * (`months`). If `months` is set, the rule applies to those months
+ * every year without needing explicit date ranges.
+ */
+export interface DateConstraintRule extends DateConstraintProperties {
+    /** Start of the period this rule applies to (inclusive). */
+    from?: CalendarDate;
+    /** End of the period this rule applies to (inclusive). */
+    to?: CalendarDate;
+    /** Recurring months this rule applies to (1=Jan, …, 12=Dec). Matches every year. */
+    months?: number[];
+    /** Priority for conflict resolution. Higher values win. Default: 0. */
+    priority?: number;
+}
+/**
+ * Full constraint configuration with global defaults and optional period rules.
+ *
+ * Backward compatible: all original properties (minDate, maxDate,
+ * disabledDates, disabledDaysOfWeek) continue to work as before.
+ */
+export interface DateConstraintOptions extends DateConstraintProperties {
+    /** Period-specific constraint overrides. Highest priority matching rule wins; ties broken by array order. */
+    rules?: DateConstraintRule[];
+}
+/**
+ * Create a single `isDateDisabled` function from a set of constraint options.
+ *
+ * The returned function checks all configured constraints (including
+ * period-specific rules) and returns `true` if the date should be
+ * disabled (not selectable).
+ *
+ * @example
+ * ```ts
+ * const isDisabled = createDateConstraint({
+ *   minDate: new CalendarDate(2025, 1, 1),
+ *   maxDate: new CalendarDate(2025, 12, 31),
+ *   disabledDaysOfWeek: [0, 6],
+ *   rules: [{
+ *     from: new CalendarDate(2025, 6, 1),
+ *     to: new CalendarDate(2025, 8, 31),
+ *     enabledDaysOfWeek: [1, 2, 3, 4, 5], // weekdays only in summer
+ *   }],
+ * })
+ * ```
+ */
+export declare function createDateConstraint(options: DateConstraintOptions): (date: CalendarDate) => boolean;
+/**
+ * Create a range validation function.
+ *
+ * Returns a function that checks whether a range [start, end] satisfies
+ * the minRange/maxRange constraints. Rule matching is based on the
+ * start date — the rule that contains the start date determines the
+ * applicable range limits.
+ *
+ * Range length is counted inclusively: a range from Jan 1 to Jan 3 is
+ * 3 days long.
+ *
+ * @example
+ * ```ts
+ * const isValid = createRangeValidator({
+ *   minRange: 3,
+ *   maxRange: 14,
+ *   rules: [{
+ *     from: new CalendarDate(2025, 5, 1),
+ *     to: new CalendarDate(2025, 10, 31),
+ *     minRange: 5, // stricter minimum in summer
+ *   }],
+ * })
+ *
+ * isValid(new CalendarDate(2025, 3, 1), new CalendarDate(2025, 3, 3)) // true (3 >= 3)
+ * isValid(new CalendarDate(2025, 6, 1), new CalendarDate(2025, 6, 3)) // false (3 < 5)
+ * ```
+ */
+export declare function createRangeValidator(options: DateConstraintOptions): (start: CalendarDate, end: CalendarDate) => boolean;
+/**
+ * Create a single `isMonthDisabled` function from constraint options.
+ *
+ * A month is disabled when:
+ * 1. The entire month falls outside [minDate, maxDate].
+ * 2. The year is disabled (via disabledYears or not in enabledYears).
+ * 3. The month number is disabled (via disabledMonths or not in enabledMonths).
+ *
+ * @example
+ * ```ts
+ * const isDisabled = createMonthConstraint({
+ *   minDate: new CalendarDate(2025, 3, 1),
+ *   disabledMonths: [1, 2], // no January or February
+ * })
+ * isDisabled(2025, 1)  // true (January disabled)
+ * isDisabled(2025, 6)  // false
+ * ```
+ */
+export declare function createMonthConstraint(options: DateConstraintOptions): (year: number, month: number) => boolean;
+/**
+ * Create a single `isYearDisabled` function from constraint options.
+ *
+ * A year is disabled when:
+ * 1. The entire year falls outside [minDate, maxDate].
+ * 2. The year is in disabledYears or not in enabledYears.
+ *
+ * @example
+ * ```ts
+ * const isDisabled = createYearConstraint({
+ *   disabledYears: [2020, 2021],
+ * })
+ * isDisabled(2020)  // true
+ * isDisabled(2025)  // false
+ * ```
+ */
+export declare function createYearConstraint(options: DateConstraintOptions): (year: number) => boolean;
+/**
+ * Standalone check: is a date disabled by the given constraints?
+ *
+ * Convenience wrapper around `createDateConstraint` for one-off checks.
+ */
+export declare function isDateDisabled(date: CalendarDate, options: DateConstraintOptions): boolean;
+/**
+ * Custom messages for each constraint reason. All properties are optional —
+ * defaults are used for any omitted keys.
+ */
+export interface ConstraintMessages {
+    beforeMinDate?: string;
+    afterMaxDate?: string;
+    disabledDate?: string;
+    disabledDayOfWeek?: string;
+    disabledMonth?: string;
+    disabledYear?: string;
+    notEnabledDate?: string;
+    notEnabledDayOfWeek?: string;
+    notEnabledMonth?: string;
+    notEnabledYear?: string;
+}
+/**
+ * Create a function that returns human-readable reasons why a date is
+ * disabled. Returns an empty array for enabled dates.
+ *
+ * Uses the same logic as `createDateConstraint` (including period-specific
+ * rules) but produces descriptive messages instead of a boolean.
+ *
+ * @example
+ * ```ts
+ * const getReasons = createDisabledReasons({
+ *   minDate: new CalendarDate(2025, 3, 1),
+ *   disabledDaysOfWeek: [0, 6],
+ * })
+ * getReasons(new CalendarDate(2025, 2, 28))
+ * // → ['Before the earliest available date']
+ * getReasons(new CalendarDate(2025, 3, 1))
+ * // → [] (enabled)
+ * getReasons(new CalendarDate(2025, 3, 2))
+ * // → ['This day of the week is not available'] (Sunday)
+ * ```
+ */
+export declare function createDisabledReasons(options: DateConstraintOptions, messages?: ConstraintMessages): (date: CalendarDate) => string[];

package/dist/core/grid.d.ts

@@ -0,0 +1,81 @@
+import { CalendarDate } from './calendar-date';
+/** Metadata for a single day cell in the calendar grid. */
+export interface DayCell {
+    date: CalendarDate;
+    isCurrentMonth: boolean;
+    isToday: boolean;
+    isDisabled: boolean;
+}
+/** A single month grid: always 6 rows × 7 cols. */
+export interface MonthGrid {
+    year: number;
+    month: number;
+    rows: DayCell[][];
+    /** ISO 8601 week numbers — one per row (6 entries). */
+    weekNumbers: number[];
+}
+/**
+ * Generate a 6×7 calendar grid for a given month.
+ *
+ * @param year           - Full year (e.g. 2025)
+ * @param month          - Month 1-12
+ * @param firstDayOfWeek - 0 = Sunday, 1 = Monday, …, 6 = Saturday
+ * @param today          - Reference date for "isToday" marking (defaults to CalendarDate.today())
+ * @param isDisabled     - Optional callback to mark dates as disabled
+ */
+export declare function generateMonth(year: number, month: number, firstDayOfWeek?: number, today?: CalendarDate, isDisabled?: (date: CalendarDate) => boolean): MonthGrid;
+/** Metadata for a single month cell in the month picker view. */
+export interface MonthCell {
+    /** Month number (1-12). */
+    month: number;
+    /** Year for this cell. */
+    year: number;
+    /** Localized short month label (e.g. "Jan"). */
+    label: string;
+    /** Whether this is the current month (today's month and year). */
+    isCurrentMonth: boolean;
+    /** Whether this entire month is outside the selectable range. */
+    isDisabled: boolean;
+}
+/**
+ * Generate a 3×4 grid of months for the month picker view.
+ *
+ * @param year             - Year to display
+ * @param today            - Reference date for "isCurrentMonth" marking
+ * @param locale           - BCP 47 locale for month labels
+ * @param isMonthDisabled  - Optional callback to check if a month should be disabled
+ */
+export declare function generateMonthGrid(year: number, today?: CalendarDate, locale?: string, isMonthDisabled?: (year: number, month: number) => boolean): MonthCell[][];
+/** Metadata for a single year cell in the year picker view. */
+export interface YearCell {
+    /** Full year number (e.g. 2026). */
+    year: number;
+    /** Year as string label. */
+    label: string;
+    /** Whether this is the current year (today's year). */
+    isCurrentYear: boolean;
+    /** Whether this entire year is outside the selectable range. */
+    isDisabled: boolean;
+}
+/**
+ * Generate a 3×4 grid of years for the year picker view.
+ *
+ * Shows 12 consecutive years in a block aligned to multiples of 12.
+ * For example, if centerYear is 2026, the grid shows 2016–2027.
+ *
+ * @param centerYear      - Year to determine which 12-year block to display
+ * @param today           - Reference date for "isCurrentYear" marking
+ * @param isYearDisabled  - Optional callback to check if a year should be disabled
+ */
+export declare function generateYearGrid(centerYear: number, today?: CalendarDate, isYearDisabled?: (year: number) => boolean): YearCell[][];
+/**
+ * Generate `count` consecutive month grids starting from year/month.
+ *
+ * @param year           - Starting year
+ * @param month          - Starting month (1-12)
+ * @param count          - Number of months to generate (e.g. 1 or 2)
+ * @param firstDayOfWeek - 0 = Sunday, 1 = Monday, …
+ * @param today          - Reference for "isToday"
+ * @param isDisabled     - Optional disabled callback
+ */
+export declare function generateMonths(year: number, month: number, count: number, firstDayOfWeek?: number, today?: CalendarDate, isDisabled?: (date: CalendarDate) => boolean): MonthGrid[];

package/dist/core/presets.d.ts

@@ -0,0 +1,84 @@
+import { CalendarDate } from './calendar-date';
+/**
+ * A predefined date range shortcut (e.g., "Today", "Last 7 Days").
+ *
+ * Re-exported from the component module for convenience — this is the
+ * canonical definition of the interface used by both core and plugin.
+ */
+export interface RangePreset {
+    /** Display label for the preset button. */
+    label: string;
+    /**
+     * Function that returns a `[start, end]` date pair.
+     * Called at click time so "Today", "Last 7 Days", etc. stay current.
+     */
+    value: () => [CalendarDate, CalendarDate];
+}
+/**
+ * Create a "Today" preset — selects today as a single-day range.
+ *
+ * @param label  - Custom label (default: "Today")
+ * @param timezone - IANA timezone for resolving today
+ */
+export declare function presetToday(label?: string, timezone?: string): RangePreset;
+/**
+ * Create a "Yesterday" preset — selects yesterday as a single-day range.
+ *
+ * @param label  - Custom label (default: "Yesterday")
+ * @param timezone - IANA timezone for resolving today
+ */
+export declare function presetYesterday(label?: string, timezone?: string): RangePreset;
+/**
+ * Create a "Last N Days" preset — selects from (today - N + 1) to today.
+ *
+ * @param days     - Number of days (inclusive)
+ * @param label    - Custom label (default: "Last {days} Days")
+ * @param timezone - IANA timezone for resolving today
+ */
+export declare function presetLastNDays(days: number, label?: string, timezone?: string): RangePreset;
+/**
+ * Create a "This Week" preset — selects from the start of the current week to today.
+ * Weeks start on the given `firstDay` (0=Sun, 1=Mon, default: 1).
+ *
+ * @param label    - Custom label (default: "This Week")
+ * @param firstDay - First day of the week (0=Sun, 1=Mon; default: 1)
+ * @param timezone - IANA timezone for resolving today
+ */
+export declare function presetThisWeek(label?: string, firstDay?: number, timezone?: string): RangePreset;
+/**
+ * Create a "Last Week" preset — selects the full 7-day week before the current week.
+ * Weeks start on the given `firstDay` (0=Sun, 1=Mon, default: 1).
+ *
+ * @param label    - Custom label (default: "Last Week")
+ * @param firstDay - First day of the week (0=Sun, 1=Mon; default: 1)
+ * @param timezone - IANA timezone for resolving today
+ */
+export declare function presetLastWeek(label?: string, firstDay?: number, timezone?: string): RangePreset;
+/**
+ * Create a "This Month" preset — selects from the 1st of the current month to today.
+ *
+ * @param label    - Custom label (default: "This Month")
+ * @param timezone - IANA timezone for resolving today
+ */
+export declare function presetThisMonth(label?: string, timezone?: string): RangePreset;
+/**
+ * Create a "Last Month" preset — selects the full previous month.
+ *
+ * @param label    - Custom label (default: "Last Month")
+ * @param timezone - IANA timezone for resolving today
+ */
+export declare function presetLastMonth(label?: string, timezone?: string): RangePreset;
+/**
+ * Create a "This Year" preset — selects from January 1st of the current year to today.
+ *
+ * @param label    - Custom label (default: "This Year")
+ * @param timezone - IANA timezone for resolving today
+ */
+export declare function presetThisYear(label?: string, timezone?: string): RangePreset;
+/**
+ * Create a "Last Year" preset — selects the full previous year (Jan 1 – Dec 31).
+ *
+ * @param label    - Custom label (default: "Last Year")
+ * @param timezone - IANA timezone for resolving today
+ */
+export declare function presetLastYear(label?: string, timezone?: string): RangePreset;

package/dist/core/selection.d.ts

@@ -0,0 +1,88 @@
+import { CalendarDate } from './calendar-date';
+/**
+ * Common interface for all selection models.
+ *
+ * Each model tracks which dates are selected and exposes a uniform API
+ * for querying, toggling, clearing, and serializing the selection.
+ */
+export interface Selection {
+    /** Check if a specific date is selected. */
+    isSelected(date: CalendarDate): boolean;
+    /** Toggle a date's selection state. */
+    toggle(date: CalendarDate): void;
+    /** Clear all selected dates. */
+    clear(): void;
+    /** Return selected dates as an array (sorted chronologically). */
+    toArray(): CalendarDate[];
+    /** Serialize the selection to a string value (for form inputs). */
+    toValue(): string;
+}
+/** Stores zero or one selected date. */
+export declare class SingleSelection implements Selection {
+    private selected;
+    constructor(initial?: CalendarDate | null);
+    isSelected(date: CalendarDate): boolean;
+    /** Toggle: select the date, or deselect if it's already selected. */
+    toggle(date: CalendarDate): void;
+    clear(): void;
+    toArray(): CalendarDate[];
+    /** Returns the ISO string of the selected date, or empty string. */
+    toValue(): string;
+    /** Direct access to the current selection. */
+    getSelected(): CalendarDate | null;
+}
+/** Stores zero or more selected dates via a Set of ISO keys. */
+export declare class MultipleSelection implements Selection {
+    private keys;
+    constructor(initial?: CalendarDate[]);
+    isSelected(date: CalendarDate): boolean;
+    /** Toggle: add the date if absent, remove if present. */
+    toggle(date: CalendarDate): void;
+    clear(): void;
+    /** Returns selected dates sorted chronologically. */
+    toArray(): CalendarDate[];
+    /** Returns comma-separated ISO strings, sorted chronologically. */
+    toValue(): string;
+    /** Number of currently selected dates. */
+    get count(): number;
+}
+/** Stores a date range (start → end), with support for partial state. */
+export declare class RangeSelection implements Selection {
+    private start;
+    private end;
+    constructor(start?: CalendarDate | null, end?: CalendarDate | null);
+    isSelected(date: CalendarDate): boolean;
+    /**
+     * Toggle behavior for range selection:
+     * 1. Nothing selected → set as start
+     * 2. Only start selected → set as end (swap if before start)
+     * 3. Both selected → clear and set as new start
+     */
+    toggle(date: CalendarDate): void;
+    /**
+     * Directly set both start and end of the range.
+     * Useful for programmatic assignment where `toggle()` semantics are undesirable
+     * (e.g., same-day ranges where toggling the same date would deselect).
+     */
+    setRange(start: CalendarDate, end: CalendarDate): void;
+    clear(): void;
+    /** Returns [start, end] if both set, [start] if partial, or [] if empty. */
+    toArray(): CalendarDate[];
+    /** Returns "start – end" ISO strings, or just start, or empty string. */
+    toValue(): string;
+    /**
+     * Check if a date falls within the range (inclusive), with optional
+     * hover preview for visual feedback during range building.
+     *
+     * When only start is selected and the user hovers over a date,
+     * pass that date as `hoverDate` to preview the range.
+     */
+    isInRange(date: CalendarDate, hoverDate?: CalendarDate): boolean;
+    /** Direct access to the range endpoints. */
+    getStart(): CalendarDate | null;
+    getEnd(): CalendarDate | null;
+    /** Whether the range is partially selected (start only, no end). */
+    isPartial(): boolean;
+    /** Whether the range is fully selected (both start and end). */
+    isComplete(): boolean;
+}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import type { Alpine as AlpineType } from 'alpinejs';
+import '../styles/calendar.css';
+import type { CalendarConfig } from './plugin/calendar-component';
+/**
+ * Alpine.js plugin that registers the `calendar` component.
+ *
+ * Usage:
+ * ```ts
+ * import Alpine from 'alpinejs'
+ * import { calendarPlugin } from '@reachgr/alpine-calendar'
+ *
+ * Alpine.plugin(calendarPlugin)
+ * Alpine.start()
+ * ```
+ */
+export declare function calendarPlugin(Alpine: AlpineType): void;
+export declare namespace calendarPlugin {
+    var defaults: (config: Partial<CalendarConfig>) => void;
+    var getDefaults: () => Partial<CalendarConfig>;
+    var resetDefaults: () => void;
+}
+export default calendarPlugin;
+export { createCalendarData } from './plugin/calendar-component';
+export type { CalendarConfig } from './plugin/calendar-component';
+export { CalendarDate, daysInMonth, getISOWeekNumber } from './core/calendar-date';
+export { generateMonth, generateMonths, generateMonthGrid, generateYearGrid } from './core/grid';
+export type { DayCell, MonthGrid, MonthCell, YearCell } from './core/grid';
+export { SingleSelection, MultipleSelection, RangeSelection } from './core/selection';
+export type { Selection } from './core/selection';
+export { createDateConstraint, createRangeValidator, createDisabledReasons, isDateDisabled, } from './core/constraints';
+export type { DateConstraintOptions, DateConstraintProperties, DateConstraintRule, ConstraintMessages, } from './core/constraints';
+export type { CalendarConfigRule, RangePreset } from './plugin/calendar-component';
+export { presetToday, presetYesterday, presetLastNDays, presetThisWeek, presetLastWeek, presetThisMonth, presetLastMonth, presetThisYear, presetLastYear, } from './core/presets';
+export { parseDate, parseDateRange, parseDateMultiple } from './input/parser';
+export { formatDate, formatRange, formatMultiple } from './input/formatter';
+export { createMask, createMaskHandlers, attachMask, parseFormatToSlots } from './input/mask';
+export type { InputMask, MaskEventHandlers, MaskSlot } from './input/mask';
+export { computePosition, autoUpdate } from './positioning/popup';
+export type { Placement, PositionOptions, PositionResult } from './positioning/popup';

package/dist/input/formatter.d.ts

@@ -0,0 +1,36 @@
+import type { CalendarDate } from '../core/calendar-date';
+/**
+ * Format a CalendarDate according to a format string.
+ *
+ * Replaces format tokens with the corresponding date values.
+ * All non-token characters are passed through as literals.
+ *
+ * @param date   - The CalendarDate to format
+ * @param format - The format string (e.g., "DD/MM/YYYY")
+ * @returns Formatted date string (e.g., "15/06/2025")
+ */
+export declare function formatDate(date: CalendarDate, format: string): string;
+/**
+ * Format a date range as a display string.
+ *
+ * Uses en-dash (–) as the range separator.
+ *
+ * @param start  - The range start date
+ * @param end    - The range end date
+ * @param format - The format string for each date
+ * @returns Formatted range string (e.g., "01/06/2025 – 30/06/2025")
+ */
+export declare function formatRange(start: CalendarDate, end: CalendarDate, format: string): string;
+/**
+ * Format multiple dates as a display string.
+ *
+ * When the number of dates exceeds `maxDisplay`, returns a count string
+ * instead of listing all dates (e.g., "3 dates selected").
+ *
+ * @param dates      - Array of CalendarDates to format
+ * @param format     - The format string for each date
+ * @param maxDisplay - Maximum number of dates to show before switching to count
+ *                     (default: no limit — always shows all dates)
+ * @returns Formatted string: comma-separated dates or count string
+ */
+export declare function formatMultiple(dates: readonly CalendarDate[], format: string, maxDisplay?: number): string;

package/dist/input/mask.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Lightweight input mask engine for date format strings.
+ *
+ * Maps format tokens (DD, MM, YYYY, etc.) to digit slots and
+ * auto-inserts separator characters as the user types.
+ * No external dependencies.
+ */
+export interface MaskSlot {
+    type: 'digit' | 'literal';
+    char: string;
+}
+export interface InputMask {
+    /** Apply mask to a raw input string, returning the formatted string */
+    apply(rawInput: string): string;
+    /** The mask pattern, e.g. "99/99/9999" */
+    readonly pattern: string;
+    /** The format string used to create the mask */
+    readonly format: string;
+    /** Total character length of a fully-filled mask */
+    readonly length: number;
+    /** The slot definitions */
+    readonly slots: readonly MaskSlot[];
+    /** Maximum number of digit characters the mask accepts */
+    readonly maxDigits: number;
+}
+export interface MaskEventHandlers {
+    onInput: (e: Event) => void;
+    onKeyDown: (e: KeyboardEvent) => void;
+    onPaste: (e: ClipboardEvent) => void;
+}
+/**
+ * Parse a format string into an array of mask slots.
+ *
+ * Each format token (DD, MM, YYYY, etc.) becomes digit slots,
+ * and all other characters become literal slots.
+ */
+export declare function parseFormatToSlots(format: string): MaskSlot[];
+/**
+ * Create a mask from a date format string.
+ *
+ * @param format - The date format (e.g., "DD/MM/YYYY")
+ * @returns An InputMask object with apply() and metadata
+ */
+export declare function createMask(format: string): InputMask;
+/**
+ * Create event handlers for masking an HTMLInputElement.
+ *
+ * Handles input, keydown (backspace/delete over separators), and paste.
+ *
+ * @param mask - The InputMask to use
+ * @returns Event handlers to attach to the input element
+ */
+export declare function createMaskHandlers(mask: InputMask): MaskEventHandlers;
+/**
+ * Attach mask event handlers to an input element.
+ * Returns a detach function to remove the handlers.
+ *
+ * @param input - The HTML input element
+ * @param format - The date format string (e.g., "DD/MM/YYYY")
+ * @returns Detach function to remove event listeners
+ */
+export declare function attachMask(input: HTMLInputElement, format: string): () => void;

package/dist/input/parser.d.ts

@@ -0,0 +1,30 @@
+import { CalendarDate } from '../core/calendar-date';
+/**
+ * Parse a date string according to the given format.
+ *
+ * Parsing is lenient: single-digit day/month values are accepted even when
+ * the format specifies DD/MM (e.g., `1/3/2025` matches `DD/MM/YYYY`).
+ *
+ * @param input  - The date string to parse (e.g., "15/06/2025")
+ * @param format - The format string (e.g., "DD/MM/YYYY")
+ * @returns The parsed CalendarDate, or null if parsing fails or date is invalid
+ */
+export declare function parseDate(input: string, format: string): CalendarDate | null;
+/**
+ * Parse a range string into two CalendarDates.
+ *
+ * Supported separators between the two dates: ` - `, ` – ` (en-dash), ` — ` (em-dash).
+ *
+ * @param input  - The range string (e.g., "01/01/2025 - 07/01/2025")
+ * @param format - The format for each individual date
+ * @returns Tuple of [start, end], or null if parsing fails
+ */
+export declare function parseDateRange(input: string, format: string): [CalendarDate, CalendarDate] | null;
+/**
+ * Parse a comma-separated list of dates.
+ *
+ * @param input  - The comma-separated string (e.g., "01/06/2025, 15/06/2025, 20/06/2025")
+ * @param format - The format for each individual date
+ * @returns Array of parsed CalendarDates (only valid dates included), or empty array
+ */
+export declare function parseDateMultiple(input: string, format: string): CalendarDate[];