@kalyx/core 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,21 +1,21 @@
 /**
- * @kalyx/core 타입 정의
+ * @kalyx/core type definitions.
  *
- * 모든 날짜 값은 ISO 8601 UTC string으로 표현한다.
- * native Date 객체는 사용하지 않는다.
+ * All date values are represented as ISO 8601 UTC strings.
+ * Native Date objects are not used.
  */
-/** ISO 8601 UTC 날짜 문자열. 예: "2026-01-15T00:00:00.000Z" */
+/** 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' }, // 1월 1일 이전 비활성화
- *   { after: '2026-12-31T00:00:00.000Z' },  // 12월 31일 이후 비활성화
- *   { date: '2026-06-15T00:00:00.000Z' },   // 특정 날짜 비활성화
- *   { dayOfWeek: [0, 6] },                   // 주말 비활성화
+ *   { 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
  * ];
  * ```
  */
@@ -28,46 +28,46 @@ type DisabledRule = {
 } | {
     dayOfWeek: number[];
 };
-/** 날짜 범위 (RangePicker) */
+/** 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;
-    /** 날짜 숫자 (1-31) */
+    /** 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;
 }
-/** 캘린더 그리드: 주(week) 배열 → 일(day) 배열 */
+/** Calendar grid: array of weeks, each week is an array of days */
 type CalendarWeek = CalendarDay[];
 type CalendarGrid = CalendarWeek[];
 /**
- * 날짜 라이브러리 어댑터 인터페이스.
- * 모든 날짜 연산을 추상화하여 다른 라이브러리(Temporal API 등)로 교체 가능.
- * 기본 구현체: {@link DateFnsAdapter}
+ * 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 {
-    /** 어떤 형식이든 → ISO 8601 UTC string */
+    /** Any format → ISO 8601 UTC string */
     parse(value: string, format?: string): string;
-    /** ISO 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;
@@ -89,24 +89,24 @@ interface DateAdapter {
     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[];
-    /** 선택된 범위 (RangePicker) */
+    /** Selected range (RangePicker) */
     range?: DateRange | null;
-    /** 호버 중인 날짜 (RangePicker 미리보기용) */
+    /** Currently hovered date (for RangePicker preview) */
     rangeHover?: ISODateString | null;
 }
 
 /**
- * date-fns 기반 DateAdapter 구현체.
- * 모든 연산은 UTC 기준으로 동작하여 timezone 간섭을 방지한다.
+ * DateAdapter implementation backed by date-fns.
+ * All operations run in UTC to avoid timezone interference.
  *
  * @example
  * ```ts
@@ -120,13 +120,13 @@ interface CalendarOptions {
 declare const DateFnsAdapter: DateAdapter;
 
 /**
- * 특정 월의 캘린더 그리드를 생성한다.
- * 주(week) 단위로 구분된 2차원 배열(`CalendarGrid`)을 반환한다.
+ * Builds the calendar grid for the given month.
+ * Returns a 2D array (`CalendarGrid`) organized by week.
  *
- * @param monthISO - 표시할 월을 포함하는 ISO datetime
- * @param adapter - 날짜 연산 어댑터 ({@link DateFnsAdapter})
- * @param options - 주 시작 요일, 선택된 날짜, 비활성화 규칙, 범위 등
- * @returns 4~6주의 캘린더 그리드. 각 주는 7개의 {@link CalendarDay} 배열.
+ * @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
@@ -135,122 +135,214 @@ declare const DateFnsAdapter: DateAdapter;
  *   selected: '2026-01-15T00:00:00.000Z',
  *   disabled: [{ dayOfWeek: [0, 6] }],
  * });
- * // grid[0] = 첫째 주 (CalendarDay[7])
- * // grid[0][0].dayNumber = 28 (이전 달)
+ * // 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;
 
 /**
- * 날짜 문자열을 ISO 8601 UTC 형식으로 정규화한다.
+ * 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;
 /**
- * 사용자 입력 텍스트를 ISO string으로 파싱한다.
- * 실패 시 null을 반환한다.
+ * Parses user input text into an ISO string.
+ * Returns null on failure.
  */
-declare function parseInputValue(input: string, format: string, adapter: DateAdapter): string | null;
+declare function parseInputValue(input: string, adapter: DateAdapter): string | null;
 
-/** 시간 표현 (24시간제 기준) */
+/** Time-of-day value (24-hour clock) */
 interface TimeValue {
     hours: number;
     minutes: number;
     seconds: number;
 }
 /**
- * ISO datetime의 시간 부분을 변경한다.
- * UTC 기준으로 동작한다.
+ * Replaces the time portion of an ISO datetime.
+ * Operates in UTC.
  */
 declare function setTime(iso: ISODateString, time: Partial<TimeValue>): ISODateString;
 /**
- * ISO datetime에서 시간 부분만 추출한다.
+ * Extracts the time portion of an ISO datetime.
  */
 declare function getTime(iso: ISODateString): TimeValue;
 /**
- * "HH:MM" 또는 "HH:MM:SS" 문자열을 TimeValue로 파싱한다.
- * 잘못된 형식이면 null 반환.
+ * Parses an "HH:MM" or "HH:MM:SS" string into a TimeValue.
+ * Returns null on invalid input.
  */
 declare function parseTimeString(input: string): TimeValue | null;
 /**
- * TimeValue를 "HH:MM" 또는 "HH:MM:SS" 문자열로 포맷팅한다.
+ * Formats a TimeValue as "HH:MM" or "HH:MM:SS".
  */
 declare function formatTimeString(time: TimeValue, withSeconds?: boolean): string;
 /**
- * 24시간제 → 12시간제 변환.
- * 0시 → 12 AM, 12시 → 12 PM
+ * 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';
 };
 /**
- * 12시간제 → 24시간제 변환.
+ * Converts a 12-hour value to 24-hour form.
  */
 declare function to24Hour(hours12: number, period: 'AM' | 'PM'): number;
 /**
- * 시 리스트 생성 (0-23 또는 1-12)
+ * Builds an hours list (0-23 or 1-12).
  */
 declare function generateHours(format?: '12h' | '24h'): number[];
 /**
- * 분 리스트 생성 (step 단위)
+ * 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[];
 /**
- * 두 TimeValue가 동일한지 비교 (시·분·초 모두).
+ * Checks whether two TimeValues are identical (hours, minutes, and seconds).
  */
 declare function isSameTime(a: TimeValue, b: TimeValue): boolean;
 /**
- * ISO datetime을 시간 문자열로 포맷팅 (UTC 기준).
- * 어댑터를 받아서 일관성 유지.
+ * 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', _adapter?: DateAdapter): string;
+declare function formatTimeFromISO(iso: ISODateString, format: 'HH:mm' | 'HH:mm:ss' | 'h:mm a' | 'h:mm:ss a'): string;
 
 interface WeekdayInfo {
-    /** 짧은 이름 (예: "Su", "일") */
+    /** Short name (e.g. "Su", "일") */
     short: string;
-    /** 전체 이름 (예: "Sunday", "일요일") */
+    /** Full name (e.g. "Sunday", "일요일") */
     full: string;
 }
 /**
- * Intl.DateTimeFormat으로 월 이름을 반환한다.
+ * Returns a localized month name via Intl.DateTimeFormat.
  * @param month 0-indexed (0 = January)
- * @param year 표시에만 사용 (일부 locale은 년 포함)
- * @param locale BCP 47 locale string (예: "en-US", "ko-KR", "ja-JP")
+ * @param locale BCP 47 locale string (e.g. "en-US", "ko-KR", "ja-JP")
  */
 declare function getMonthName(month: number, locale?: string): string;
 /**
- * "2026년 1월" 또는 "January 2026" 같은 월+년 문자열을 반환한다.
+ * Returns a month+year string like "January 2026" or "2026년 1월".
  */
 declare function formatMonthYear(year: number, month: number, locale?: string): string;
 /**
- * Intl.DateTimeFormat으로 주의 요일 이름 배열을 반환한다.
- * weekStartsOn에 맞춰 정렬.
+ * Returns localized weekday names via Intl.DateTimeFormat.
+ * Ordered according to weekStartsOn.
  *
  * @param locale BCP 47 locale string
  * @param weekStartsOn 0 = Sunday, 1 = Monday
- * @returns 7개의 WeekdayInfo 배열
+ * @returns Array of 7 WeekdayInfo entries
  */
 declare function getWeekdayNames(locale?: string, weekStartsOn?: WeekStartsOn): WeekdayInfo[];
 /**
- * Intl.DateTimeFormat으로 날짜의 전체 텍스트를 반환한다 (스크린리더용).
- * 예: "2026년 1월 15일 목요일"
+ * 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;
 
-export { type CalendarDay, type CalendarGrid, type CalendarOptions, type CalendarWeek, type DateAdapter, DateFnsAdapter, type DateRange, type DisabledRule, type ISODateString, type TimeValue, type WeekStartsOn, type WeekdayInfo, formatFullDate, formatMonthYear, formatTimeFromISO, formatTimeString, generateHours, generateMinutes, getCalendarDays, getMonthName, getTime, getWeekdayNames, isDateDisabled, isSameTime, maxDate, minDate, normalizeISO, parseInputValue, parseTimeString, setTime, to12Hour, to24Hour };
+/**
+ * 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 };