@kalyx/core 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,9 +1,348 @@
-export type { ISODateString, DisabledRule, DateRange, CalendarDay, CalendarWeek, CalendarGrid, CalendarOptions, DateAdapter, WeekStartsOn, } from './types.js';
-export { DateFnsAdapter } from './adapters/date-fns.js';
-export { getCalendarDays, isDateDisabled, minDate, maxDate } from './utils/calendar.js';
-export { normalizeISO, parseInputValue } from './utils/date.js';
-export { setTime, getTime, parseTimeString, formatTimeString, formatTimeFromISO, to12Hour, to24Hour, generateHours, generateMinutes, isSameTime, } from './utils/time.js';
-export type { TimeValue } from './utils/time.js';
-export { getMonthName, formatMonthYear, getWeekdayNames, formatFullDate, } from './utils/locale.js';
-export type { WeekdayInfo } from './utils/locale.js';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * @kalyx/core type definitions.
+ *
+ * All date values are represented as ISO 8601 UTC strings.
+ * Native Date objects are not used.
+ */
+/** ISO 8601 UTC date string. e.g. "2026-01-15T00:00:00.000Z" */
+type ISODateString = string;
+/**
+ * Date-disable rules. Multiple rules can be combined in an array.
+ *
+ * @example
+ * ```ts
+ * const rules: DisabledRule[] = [
+ *   { before: '2026-01-01T00:00:00.000Z' }, // disable before Jan 1
+ *   { after: '2026-12-31T00:00:00.000Z' },  // disable after Dec 31
+ *   { date: '2026-06-15T00:00:00.000Z' },   // disable a specific date
+ *   { dayOfWeek: [0, 6] },                   // disable weekends
+ * ];
+ * ```
+ */
+type DisabledRule = {
+    date: ISODateString;
+} | {
+    before: ISODateString;
+} | {
+    after: ISODateString;
+} | {
+    dayOfWeek: number[];
+};
+/** Date range (RangePicker) */
+interface DateRange {
+    start: ISODateString | null;
+    end: ISODateString | null;
+}
+/** Represents a single day in the calendar grid */
+interface CalendarDay {
+    /** ISO 8601 UTC string */
+    isoString: ISODateString;
+    /** Day of month (1-31) */
+    dayNumber: number;
+    /** Whether this day belongs to the currently displayed month */
+    isCurrentMonth: boolean;
+    /** Whether this day is today */
+    isToday: boolean;
+    /** Whether this day is the selected date (single selection) */
+    isSelected: boolean;
+    /** Whether this day is disabled */
+    isDisabled: boolean;
+    /** Whether this day is focused */
+    isFocused: boolean;
+    /** Whether this day is the start of a range */
+    isRangeStart: boolean;
+    /** Whether this day is the end of a range */
+    isRangeEnd: boolean;
+    /** Whether this day is inside a range (between start and end) */
+    isInRange: boolean;
+}
+/** Calendar grid: array of weeks, each week is an array of days */
+type CalendarWeek = CalendarDay[];
+type CalendarGrid = CalendarWeek[];
+/**
+ * Date library adapter interface.
+ * Abstracts all date operations so the underlying library (e.g. Temporal API) can be swapped.
+ * Default implementation: {@link DateFnsAdapter}
+ */
+interface DateAdapter {
+    /** Any format → ISO 8601 UTC string */
+    parse(value: string, format?: string): string;
+    /** ISO string → display string */
+    format(iso: string, formatStr: string, timezone?: string): string;
+    addDays(iso: string, n: number): string;
+    addMonths(iso: string, n: number): string;
+    addYears(iso: string, n: number): string;
+    isBefore(a: string, b: string): boolean;
+    isAfter(a: string, b: string): boolean;
+    isSameDay(a: string, b: string, timezone?: string): boolean;
+    isSameMonth(a: string, b: string): boolean;
+    startOfDay(iso: string, timezone?: string): string;
+    startOfMonth(iso: string): string;
+    endOfMonth(iso: string): string;
+    startOfWeek(iso: string, weekStartsOn?: 0 | 1): string;
+    endOfWeek(iso: string, weekStartsOn?: 0 | 1): string;
+    now(): string;
+    today(timezone?: string): string;
+    isValid(value: string): boolean;
+    getYear(iso: string): number;
+    getMonth(iso: string): number;
+    getDate(iso: string): number;
+    getDay(iso: string): number;
+}
+/** First day of the week */
+type WeekStartsOn = 0 | 1;
+/** Options for generating a calendar grid */
+interface CalendarOptions {
+    weekStartsOn?: WeekStartsOn;
+    today?: ISODateString;
+    selected?: ISODateString | null;
+    focusedDate?: ISODateString;
+    disabled?: DisabledRule[];
+    /** Selected range (RangePicker) */
+    range?: DateRange | null;
+    /** Currently hovered date (for RangePicker preview) */
+    rangeHover?: ISODateString | null;
+}
+
+/**
+ * DateAdapter implementation backed by date-fns.
+ * All operations run in UTC to avoid timezone interference.
+ *
+ * @example
+ * ```ts
+ * import { DateFnsAdapter } from '@kalyx/core';
+ *
+ * DateFnsAdapter.format('2026-01-15T00:00:00.000Z', 'yyyy-MM-dd'); // "2026-01-15"
+ * DateFnsAdapter.addDays('2026-01-15T00:00:00.000Z', 7);           // "2026-01-22T..."
+ * DateFnsAdapter.isSameDay('2026-01-15T00:00:00.000Z', '2026-01-15T23:59:59.000Z'); // true
+ * ```
+ */
+declare const DateFnsAdapter: DateAdapter;
+
+/**
+ * Builds the calendar grid for the given month.
+ * Returns a 2D array (`CalendarGrid`) organized by week.
+ *
+ * @param monthISO - ISO datetime containing the month to display
+ * @param adapter - Date operation adapter ({@link DateFnsAdapter})
+ * @param options - Week start day, selected date, disabled rules, range, etc.
+ * @returns A calendar grid of 4-6 weeks. Each week is an array of 7 {@link CalendarDay}.
+ *
+ * @example
+ * ```ts
+ * const grid = getCalendarDays('2026-01-01T00:00:00.000Z', DateFnsAdapter, {
+ *   weekStartsOn: 0,
+ *   selected: '2026-01-15T00:00:00.000Z',
+ *   disabled: [{ dayOfWeek: [0, 6] }],
+ * });
+ * // grid[0] = first week (CalendarDay[7])
+ * // grid[0][0].dayNumber = 28 (previous month)
+ * ```
+ */
+declare function getCalendarDays(monthISO: string, adapter: DateAdapter, options?: CalendarOptions): CalendarGrid;
+/**
+ * Checks whether the given date matches any disable rule.
+ */
+declare function isDateDisabled(iso: string, rules: DisabledRule[], adapter: DateAdapter): boolean;
+/**
+ * Returns the earlier of two dates.
+ */
+declare function minDate(a: ISODateString, b: ISODateString, adapter: DateAdapter): ISODateString;
+/**
+ * Returns the later of two dates.
+ */
+declare function maxDate(a: ISODateString, b: ISODateString, adapter: DateAdapter): ISODateString;
+
+/**
+ * Normalizes a date string to ISO 8601 UTC form.
+ * "2026-01-15" → "2026-01-15T00:00:00.000Z"
+ *
+ * Full datetime strings must include a timezone suffix (Z or ±HH:MM).
+ * Strings without a timezone suffix are treated as-is (not matched as datetime).
+ */
+declare function normalizeISO(value: string): string;
+/**
+ * Parses user input text into an ISO string.
+ * Returns null on failure.
+ */
+declare function parseInputValue(input: string, adapter: DateAdapter): string | null;
+
+/** Time-of-day value (24-hour clock) */
+interface TimeValue {
+    hours: number;
+    minutes: number;
+    seconds: number;
+}
+/**
+ * Replaces the time portion of an ISO datetime.
+ * Operates in UTC.
+ */
+declare function setTime(iso: ISODateString, time: Partial<TimeValue>): ISODateString;
+/**
+ * Extracts the time portion of an ISO datetime.
+ */
+declare function getTime(iso: ISODateString): TimeValue;
+/**
+ * Parses an "HH:MM" or "HH:MM:SS" string into a TimeValue.
+ * Returns null on invalid input.
+ */
+declare function parseTimeString(input: string): TimeValue | null;
+/**
+ * Formats a TimeValue as "HH:MM" or "HH:MM:SS".
+ */
+declare function formatTimeString(time: TimeValue, withSeconds?: boolean): string;
+/**
+ * Converts a 24-hour value to 12-hour form.
+ * 0 → 12 AM, 12 → 12 PM
+ */
+declare function to12Hour(hours24: number): {
+    hours12: number;
+    period: 'AM' | 'PM';
+};
+/**
+ * Converts a 12-hour value to 24-hour form.
+ */
+declare function to24Hour(hours12: number, period: 'AM' | 'PM'): number;
+/**
+ * Builds an hours list (0-23 or 1-12).
+ */
+declare function generateHours(format?: '12h' | '24h'): number[];
+/**
+ * Builds a minutes list at the given step.
+ * step=1 → [0, 1, 2, ..., 59]
+ * step=15 → [0, 15, 30, 45]
+ * step=5 → [0, 5, 10, ..., 55]
+ */
+declare function generateMinutes(step?: number): number[];
+/**
+ * Checks whether two TimeValues are identical (hours, minutes, and seconds).
+ */
+declare function isSameTime(a: TimeValue, b: TimeValue): boolean;
+/**
+ * Formats an ISO datetime as a time string (UTC based).
+ * Accepts an adapter for API consistency.
+ */
+declare function formatTimeFromISO(iso: ISODateString, format: 'HH:mm' | 'HH:mm:ss' | 'h:mm a' | 'h:mm:ss a'): string;
+
+interface WeekdayInfo {
+    /** Short name (e.g. "Su", "일") */
+    short: string;
+    /** Full name (e.g. "Sunday", "일요일") */
+    full: string;
+}
+/**
+ * Returns a localized month name via Intl.DateTimeFormat.
+ * @param month 0-indexed (0 = January)
+ * @param locale BCP 47 locale string (e.g. "en-US", "ko-KR", "ja-JP")
+ */
+declare function getMonthName(month: number, locale?: string): string;
+/**
+ * Returns a month+year string like "January 2026" or "2026년 1월".
+ */
+declare function formatMonthYear(year: number, month: number, locale?: string): string;
+/**
+ * Returns localized weekday names via Intl.DateTimeFormat.
+ * Ordered according to weekStartsOn.
+ *
+ * @param locale BCP 47 locale string
+ * @param weekStartsOn 0 = Sunday, 1 = Monday
+ * @returns Array of 7 WeekdayInfo entries
+ */
+declare function getWeekdayNames(locale?: string, weekStartsOn?: WeekStartsOn): WeekdayInfo[];
+/**
+ * Returns a fully formatted date string via Intl.DateTimeFormat (for screen readers).
+ * e.g. "Thursday, January 15, 2026"
+ */
+declare function formatFullDate(iso: string, locale?: string): string;
+
+/**
+ * Format a UTC ISO string for display in a specific IANA timezone.
+ * Handles DST transitions correctly. Supports a small set of tokens: `yyyy MM dd HH mm ss`.
+ *
+ * @param iso - UTC ISO 8601 string
+ * @param formatStr - token string (e.g. `"yyyy-MM-dd HH:mm"`)
+ * @param timeZone - IANA zone (e.g. `"America/New_York"`)
+ *
+ * @example
+ * formatInTimezone('2026-03-08T07:30:00.000Z', 'yyyy-MM-dd HH:mm', 'America/New_York');
+ * // → '2026-03-08 03:30'   (post spring-forward EDT)
+ */
+declare function formatInTimezone(iso: ISODateString, formatStr: string, timeZone: string): string;
+/**
+ * UTC offset (minutes east of UTC) at a given UTC instant, as applied by the given timezone.
+ * The offset may differ on either side of a DST transition.
+ *
+ * @example
+ * getTimezoneOffsetMinutes('2026-03-08T06:00:00.000Z', 'America/New_York'); // -300 (EST, UTC-5)
+ * getTimezoneOffsetMinutes('2026-03-08T07:00:00.000Z', 'America/New_York'); // -240 (EDT, UTC-4)
+ * getTimezoneOffsetMinutes('2026-01-15T12:00:00.000Z', 'Asia/Seoul');       //  540 (UTC+9)
+ */
+declare function getTimezoneOffsetMinutes(iso: ISODateString, timeZone: string): number;
+/**
+ * Midnight of the civil date (as observed in `timeZone`) returned as a UTC ISO string.
+ *
+ * Across DST transitions this is the correct way to compute "start of day" — the offset
+ * changes, so the UTC instant of midnight differs before and after the transition.
+ *
+ * @example
+ * startOfDayInTimezone('2026-03-08T12:00:00.000Z', 'America/New_York'); // '2026-03-08T05:00:00.000Z' (EST)
+ * startOfDayInTimezone('2026-03-09T12:00:00.000Z', 'America/New_York'); // '2026-03-09T04:00:00.000Z' (EDT)
+ */
+declare function startOfDayInTimezone(iso: ISODateString, timeZone: string): ISODateString;
+/**
+ * Whether two UTC instants fall on the same civil day in the given timezone.
+ * Timezone-safe alternative to comparing `iso.slice(0, 10)`.
+ *
+ * @example
+ * // Seoul is UTC+9, so 03:00 UTC and 14:00 UTC are both on 2026-01-15 KST
+ * isSameDayInTimezone('2026-01-15T03:00:00.000Z', '2026-01-15T14:00:00.000Z', 'Asia/Seoul'); // true
+ * // But 17:00 UTC is 02:00 KST on 2026-01-16
+ * isSameDayInTimezone('2026-01-15T03:00:00.000Z', '2026-01-15T17:00:00.000Z', 'Asia/Seoul'); // false
+ */
+declare function isSameDayInTimezone(a: ISODateString, b: ISODateString, timeZone: string): boolean;
+/**
+ * "Today" in the given timezone, returned as the UTC ISO string representing that day's midnight.
+ * Prefer this over `new Date()` when the notion of "today" should follow the user's displayed
+ * timezone rather than the server's local clock.
+ */
+declare function todayInTimezone(timeZone: string): ISODateString;
+
+/**
+ * Default English labels for ARIA attributes and accessible text.
+ * Override via the `labels` prop on Root components.
+ */
+interface DatePickerLabels {
+    triggerOpen: string;
+    triggerClose: string;
+    popoverLabel: string;
+    prevMonth: string;
+    nextMonth: string;
+    prevYear: string;
+    nextYear: string;
+    prevDecade: string;
+    nextDecade: string;
+    /** Used by DateTimePicker.Input (present only when DatePickerContext is provided by DateTimePickerRoot) */
+    dateTimeInput?: string;
+}
+interface RangePickerLabels extends DatePickerLabels {
+    startInput: string;
+    endInput: string;
+    presetsGroup: string;
+}
+interface TimePickerLabels {
+    timeInput: string;
+    hourList: string;
+    minuteList: string;
+    amPmToggle: string;
+    hourOption: (hour: number) => string;
+    minuteOption: (minute: number) => string;
+}
+interface DateTimePickerLabels extends DatePickerLabels, TimePickerLabels {
+    dateTimeInput: string;
+}
+declare const DEFAULT_DATEPICKER_LABELS: DatePickerLabels;
+declare const DEFAULT_RANGEPICKER_LABELS: RangePickerLabels;
+declare const DEFAULT_TIMEPICKER_LABELS: TimePickerLabels;
+declare const DEFAULT_DATETIMEPICKER_LABELS: DateTimePickerLabels;
+
+export { type CalendarDay, type CalendarGrid, type CalendarOptions, type CalendarWeek, DEFAULT_DATEPICKER_LABELS, DEFAULT_DATETIMEPICKER_LABELS, DEFAULT_RANGEPICKER_LABELS, DEFAULT_TIMEPICKER_LABELS, type DateAdapter, DateFnsAdapter, type DatePickerLabels, type DateRange, type DateTimePickerLabels, type DisabledRule, type ISODateString, type RangePickerLabels, type TimePickerLabels, type TimeValue, type WeekStartsOn, type WeekdayInfo, formatFullDate, formatInTimezone, formatMonthYear, formatTimeFromISO, formatTimeString, generateHours, generateMinutes, getCalendarDays, getMonthName, getTime, getTimezoneOffsetMinutes, getWeekdayNames, isDateDisabled, isSameDayInTimezone, isSameTime, maxDate, minDate, normalizeISO, parseInputValue, parseTimeString, setTime, startOfDayInTimezone, to12Hour, to24Hour, todayInTimezone };