@kalyx/core 1.0.0-rc.6 → 1.0.0

package/dist/index.cjs

@@ -24,7 +24,6 @@ __export(index_exports, {
   DEFAULT_DATETIMEPICKER_LABELS: () => DEFAULT_DATETIMEPICKER_LABELS,
   DEFAULT_RANGEPICKER_LABELS: () => DEFAULT_RANGEPICKER_LABELS,
   DEFAULT_TIMEPICKER_LABELS: () => DEFAULT_TIMEPICKER_LABELS,
-  DateFnsAdapter: () => DateFnsAdapter,
   civilMidnightFromUtcDay: () => civilMidnightFromUtcDay,
   formatFullDate: () => formatFullDate,
   formatInTimezone: () => formatInTimezone,
@@ -34,6 +33,7 @@ __export(index_exports, {
   generateHours: () => generateHours,
   generateMinutes: () => generateMinutes,
   getCalendarDays: () => getCalendarDays,
+  getISOWeekNumber: () => getISOWeekNumber,
   getMonthName: () => getMonthName,
   getTime: () => getTime,
   getTimeInTimezone: () => getTimeInTimezone,
@@ -56,249 +56,6 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/adapters/date-fns.ts
-var import_date_fns2 = require("date-fns");
-
-// src/utils/timezone.ts
-var import_date_fns = require("date-fns");
-var formatterCache = /* @__PURE__ */ new Map();
-function getCachedPartsFormatter(timeZone) {
-  const key = `parts:${timeZone}`;
-  let fmt = formatterCache.get(key);
-  if (!fmt) {
-    fmt = new Intl.DateTimeFormat("en-US", {
-      timeZone,
-      year: "numeric",
-      month: "2-digit",
-      day: "2-digit",
-      hour: "2-digit",
-      minute: "2-digit",
-      second: "2-digit",
-      hourCycle: "h23"
-    });
-    formatterCache.set(key, fmt);
-  }
-  return fmt;
-}
-function partsInTimezone(utc, timeZone) {
-  const dtf = getCachedPartsFormatter(timeZone);
-  const parts = Object.fromEntries(dtf.formatToParts(utc).map((p) => [p.type, p.value]));
-  return {
-    year: Number(parts.year),
-    month: Number(parts.month),
-    day: Number(parts.day),
-    // Some locales/engines return '24' instead of '0' at midnight
-    hour: parts.hour === "24" ? 0 : Number(parts.hour),
-    minute: Number(parts.minute),
-    second: Number(parts.second)
-  };
-}
-function formatInTimezone(iso, formatStr, timeZone) {
-  const p = partsInTimezone((0, import_date_fns.parseISO)(iso), timeZone);
-  const tokens = {
-    yyyy: String(p.year),
-    MM: String(p.month).padStart(2, "0"),
-    dd: String(p.day).padStart(2, "0"),
-    HH: String(p.hour).padStart(2, "0"),
-    mm: String(p.minute).padStart(2, "0"),
-    ss: String(p.second).padStart(2, "0")
-  };
-  let result = formatStr;
-  for (const [token, value] of Object.entries(tokens).sort((a, b) => b[0].length - a[0].length)) {
-    result = result.split(token).join(value);
-  }
-  return result;
-}
-function getTimezoneOffsetMinutes(iso, timeZone) {
-  const utc = (0, import_date_fns.parseISO)(iso);
-  const p = partsInTimezone(utc, timeZone);
-  const asUtcEpoch = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
-  return Math.round((asUtcEpoch - utc.getTime()) / 6e4);
-}
-function startOfDayInTimezone(iso, timeZone) {
-  const utc = (0, import_date_fns.parseISO)(iso);
-  const p = partsInTimezone(utc, timeZone);
-  const civilMidnightUtc = Date.UTC(p.year, p.month - 1, p.day, 0, 0, 0);
-  const midnightProbe = new Date(civilMidnightUtc).toISOString();
-  const offsetMinutes = getTimezoneOffsetMinutes(midnightProbe, timeZone);
-  return new Date(civilMidnightUtc - offsetMinutes * 6e4).toISOString();
-}
-function isSameDayInTimezone(a, b, timeZone) {
-  const pa = partsInTimezone((0, import_date_fns.parseISO)(a), timeZone);
-  const pb = partsInTimezone((0, import_date_fns.parseISO)(b), timeZone);
-  return pa.year === pb.year && pa.month === pb.month && pa.day === pb.day;
-}
-function todayInTimezone(timeZone) {
-  return startOfDayInTimezone((/* @__PURE__ */ new Date()).toISOString(), timeZone);
-}
-function civilMidnightFromUtcDay(gridUtcIso, timeZone) {
-  const utc = (0, import_date_fns.parseISO)(gridUtcIso);
-  const probe = new Date(
-    Date.UTC(utc.getUTCFullYear(), utc.getUTCMonth(), utc.getUTCDate(), 12, 0, 0)
-  ).toISOString();
-  return startOfDayInTimezone(probe, timeZone);
-}
-function getTimeInTimezone(iso, timeZone) {
-  const p = partsInTimezone((0, import_date_fns.parseISO)(iso), timeZone);
-  return { hours: p.hour, minutes: p.minute, seconds: p.second };
-}
-function setTimeInTimezone(iso, partial, timeZone) {
-  const p = partsInTimezone((0, import_date_fns.parseISO)(iso), timeZone);
-  const targetHours = partial.hours ?? p.hour;
-  const targetMinutes = partial.minutes ?? p.minute;
-  const targetSeconds = partial.seconds ?? p.second;
-  const civilEpoch = Date.UTC(
-    p.year,
-    p.month - 1,
-    p.day,
-    targetHours,
-    targetMinutes,
-    targetSeconds
-  );
-  const probe1 = new Date(civilEpoch).toISOString();
-  const offset1 = getTimezoneOffsetMinutes(probe1, timeZone);
-  const realEpoch1 = civilEpoch - offset1 * 6e4;
-  const probe2 = new Date(realEpoch1).toISOString();
-  const offset2 = getTimezoneOffsetMinutes(probe2, timeZone);
-  const realEpoch2 = civilEpoch - offset2 * 6e4;
-  return new Date(realEpoch2).toISOString();
-}
-
-// src/adapters/date-fns.ts
-function toDate(iso) {
-  return (0, import_date_fns2.parseISO)(iso);
-}
-function toISO(date) {
-  return date.toISOString();
-}
-function normalize(value) {
-  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
-    return `${value}T00:00:00.000Z`;
-  }
-  return value;
-}
-function utcStartOfDay(d) {
-  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
-}
-function utcStartOfMonth(d) {
-  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1));
-}
-function utcEndOfMonth(d) {
-  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 0, 23, 59, 59, 999));
-}
-function utcStartOfWeek(d, weekStartsOn) {
-  const day = d.getUTCDay();
-  const diff = (day - weekStartsOn + 7) % 7;
-  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() - diff));
-}
-function utcEndOfWeek(d, weekStartsOn) {
-  const start = utcStartOfWeek(d, weekStartsOn);
-  return new Date(
-    Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), start.getUTCDate() + 6, 23, 59, 59, 999)
-  );
-}
-var DateFnsAdapter = {
-  parse(value) {
-    if (!value) return "";
-    return normalize(value);
-  },
-  format(iso, formatStr, timezone) {
-    if (timezone) {
-      return formatInTimezone(iso, formatStr, timezone);
-    }
-    const d = toDate(iso);
-    const tokens = {
-      yyyy: String(d.getUTCFullYear()),
-      MM: String(d.getUTCMonth() + 1).padStart(2, "0"),
-      dd: String(d.getUTCDate()).padStart(2, "0"),
-      HH: String(d.getUTCHours()).padStart(2, "0"),
-      mm: String(d.getUTCMinutes()).padStart(2, "0"),
-      ss: String(d.getUTCSeconds()).padStart(2, "0"),
-      M: String(d.getUTCMonth() + 1),
-      d: String(d.getUTCDate())
-    };
-    let result = formatStr;
-    for (const [token, value] of Object.entries(tokens).sort((a, b) => b[0].length - a[0].length)) {
-      result = result.split(token).join(value);
-    }
-    return result;
-  },
-  addDays(iso, n) {
-    return toISO((0, import_date_fns2.addDays)(toDate(iso), n));
-  },
-  addMonths(iso, n) {
-    return toISO((0, import_date_fns2.addMonths)(toDate(iso), n));
-  },
-  addYears(iso, n) {
-    return toISO((0, import_date_fns2.addYears)(toDate(iso), n));
-  },
-  isBefore(a, b) {
-    return (0, import_date_fns2.isBefore)(toDate(a), toDate(b));
-  },
-  isAfter(a, b) {
-    return (0, import_date_fns2.isAfter)(toDate(a), toDate(b));
-  },
-  isSameDay(a, b, timezone) {
-    if (!a || !b) return false;
-    if (timezone) {
-      return isSameDayInTimezone(a, b, timezone);
-    }
-    const da = toDate(a);
-    const db = toDate(b);
-    return da.getUTCFullYear() === db.getUTCFullYear() && da.getUTCMonth() === db.getUTCMonth() && da.getUTCDate() === db.getUTCDate();
-  },
-  isSameMonth(a, b) {
-    const da = toDate(a);
-    const db = toDate(b);
-    return da.getUTCFullYear() === db.getUTCFullYear() && da.getUTCMonth() === db.getUTCMonth();
-  },
-  startOfDay(iso, timezone) {
-    if (timezone) {
-      return startOfDayInTimezone(iso, timezone);
-    }
-    return toISO(utcStartOfDay(toDate(iso)));
-  },
-  startOfMonth(iso) {
-    return toISO(utcStartOfMonth(toDate(iso)));
-  },
-  endOfMonth(iso) {
-    return toISO(utcEndOfMonth(toDate(iso)));
-  },
-  startOfWeek(iso, weekStartsOn = 0) {
-    return toISO(utcStartOfWeek(toDate(iso), weekStartsOn));
-  },
-  endOfWeek(iso, weekStartsOn = 0) {
-    return toISO(utcEndOfWeek(toDate(iso), weekStartsOn));
-  },
-  now() {
-    return (/* @__PURE__ */ new Date()).toISOString();
-  },
-  today(timezone) {
-    if (timezone) {
-      return todayInTimezone(timezone);
-    }
-    return toISO(utcStartOfDay(/* @__PURE__ */ new Date()));
-  },
-  isValid(value) {
-    if (!value) return false;
-    const normalized = normalize(value);
-    const date = (0, import_date_fns2.parseISO)(normalized);
-    return (0, import_date_fns2.isValid)(date);
-  },
-  getYear(iso) {
-    return toDate(iso).getUTCFullYear();
-  },
-  getMonth(iso) {
-    return toDate(iso).getUTCMonth();
-  },
-  getDate(iso) {
-    return toDate(iso).getUTCDate();
-  },
-  getDay(iso) {
-    return toDate(iso).getUTCDay();
-  }
-};
-
 // src/utils/calendar.ts
 function getCalendarDays(monthISO, adapter, options = {}) {
   const {
@@ -309,7 +66,8 @@ function getCalendarDays(monthISO, adapter, options = {}) {
     disabled = [],
     range,
     rangeHover,
-    timezone
+    timezone,
+    fixedWeeks = false
   } = options;
   const todayISO = today ?? adapter.today(timezone);
   const monthStart = adapter.startOfMonth(monthISO);
@@ -339,12 +97,20 @@ function getCalendarDays(monthISO, adapter, options = {}) {
       current = adapter.addDays(current, 1);
     }
     weeks.push(days);
-    if (!adapter.isSameMonth(current, monthISO) && week >= 3) {
+    if (!fixedWeeks && !adapter.isSameMonth(current, monthISO) && week >= 3) {
       break;
     }
   }
   return weeks;
 }
+function getISOWeekNumber(iso) {
+  const d = new Date(iso);
+  const utc = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+  const isoDay = utc.getUTCDay() || 7;
+  utc.setUTCDate(utc.getUTCDate() + 4 - isoDay);
+  const yearStart = new Date(Date.UTC(utc.getUTCFullYear(), 0, 1));
+  return Math.ceil(((utc.getTime() - yearStart.getTime()) / 864e5 + 1) / 7);
+}
 function normalizeRangeForDisplay(range, hover, adapter, _timezone) {
   if (!range) return { start: null, end: null };
   const { start, end } = range;
@@ -388,6 +154,8 @@ function isDateDisabled(iso, rules, adapter) {
       if (adapter.isAfter(iso, rule.after)) return true;
     } else if ("dayOfWeek" in rule) {
       if (rule.dayOfWeek.includes(adapter.getDay(iso))) return true;
+    } else if ("filter" in rule) {
+      if (rule.filter(iso)) return true;
     }
   }
   return false;
@@ -465,12 +233,18 @@ function formatTimeString(time, withSeconds = false) {
   return `${hh}:${mm}`;
 }
 function to12Hour(hours24) {
+  if (!Number.isInteger(hours24) || hours24 < 0 || hours24 > 23) {
+    throw new RangeError(`[to12Hour] hours24 must be an integer in [0, 23], got ${hours24}`);
+  }
   const period = hours24 >= 12 ? "PM" : "AM";
   let hours12 = hours24 % 12;
   if (hours12 === 0) hours12 = 12;
   return { hours12, period };
 }
 function to24Hour(hours12, period) {
+  if (!Number.isInteger(hours12) || hours12 < 1 || hours12 > 12) {
+    throw new RangeError(`[to24Hour] hours12 must be an integer in [1, 12], got ${hours12}`);
+  }
   if (period === "AM") {
     return hours12 === 12 ? 0 : hours12;
   }
@@ -483,8 +257,8 @@ function generateHours(format = "24h") {
   return Array.from({ length: 24 }, (_, i) => i);
 }
 function generateMinutes(step = 1) {
-  if (step < 1 || step > 30) {
-    throw new Error(`[generateMinutes] step must be between 1 and 30, got ${step}`);
+  if (step < 1 || step > 60) {
+    throw new Error(`[generateMinutes] step must be between 1 and 60, got ${step}`);
   }
   const result = [];
   for (let i = 0; i < 60; i += step) {
@@ -510,13 +284,13 @@ function formatTimeFromISO(iso, format) {
 }
 
 // src/utils/locale.ts
-var formatterCache2 = /* @__PURE__ */ new Map();
+var formatterCache = /* @__PURE__ */ new Map();
 function getCachedFormatter(locale, options) {
   const key = `${locale}:${JSON.stringify(options)}`;
-  let fmt = formatterCache2.get(key);
+  let fmt = formatterCache.get(key);
   if (!fmt) {
     fmt = new Intl.DateTimeFormat(locale, options);
-    formatterCache2.set(key, fmt);
+    formatterCache.set(key, fmt);
   }
   return fmt;
 }
@@ -561,6 +335,110 @@ function formatFullDate(iso, locale = "en-US") {
   }).format(date);
 }
 
+// src/utils/timezone.ts
+var formatterCache2 = /* @__PURE__ */ new Map();
+function getCachedPartsFormatter(timeZone) {
+  const key = `parts:${timeZone}`;
+  let fmt = formatterCache2.get(key);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hourCycle: "h23"
+    });
+    formatterCache2.set(key, fmt);
+  }
+  return fmt;
+}
+function partsInTimezone(utc, timeZone) {
+  const dtf = getCachedPartsFormatter(timeZone);
+  const parts = Object.fromEntries(dtf.formatToParts(utc).map((p) => [p.type, p.value]));
+  return {
+    year: Number(parts.year),
+    month: Number(parts.month),
+    day: Number(parts.day),
+    // Some locales/engines return '24' instead of '0' at midnight
+    hour: parts.hour === "24" ? 0 : Number(parts.hour),
+    minute: Number(parts.minute),
+    second: Number(parts.second)
+  };
+}
+function formatInTimezone(iso, formatStr, timeZone) {
+  const p = partsInTimezone(new Date(iso), timeZone);
+  const tokens = {
+    yyyy: String(p.year),
+    MM: String(p.month).padStart(2, "0"),
+    dd: String(p.day).padStart(2, "0"),
+    HH: String(p.hour).padStart(2, "0"),
+    mm: String(p.minute).padStart(2, "0"),
+    ss: String(p.second).padStart(2, "0")
+  };
+  let result = formatStr;
+  for (const [token, value] of Object.entries(tokens).sort((a, b) => b[0].length - a[0].length)) {
+    result = result.split(token).join(value);
+  }
+  return result;
+}
+function getTimezoneOffsetMinutes(iso, timeZone) {
+  const utc = new Date(iso);
+  const p = partsInTimezone(utc, timeZone);
+  const asUtcEpoch = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
+  return Math.round((asUtcEpoch - utc.getTime()) / 6e4);
+}
+function startOfDayInTimezone(iso, timeZone) {
+  const utc = new Date(iso);
+  const p = partsInTimezone(utc, timeZone);
+  const civilMidnightUtc = Date.UTC(p.year, p.month - 1, p.day, 0, 0, 0);
+  const midnightProbe = new Date(civilMidnightUtc).toISOString();
+  const offsetMinutes = getTimezoneOffsetMinutes(midnightProbe, timeZone);
+  return new Date(civilMidnightUtc - offsetMinutes * 6e4).toISOString();
+}
+function isSameDayInTimezone(a, b, timeZone) {
+  const pa = partsInTimezone(new Date(a), timeZone);
+  const pb = partsInTimezone(new Date(b), timeZone);
+  return pa.year === pb.year && pa.month === pb.month && pa.day === pb.day;
+}
+function todayInTimezone(timeZone) {
+  return startOfDayInTimezone((/* @__PURE__ */ new Date()).toISOString(), timeZone);
+}
+function civilMidnightFromUtcDay(gridUtcIso, timeZone) {
+  const utc = new Date(gridUtcIso);
+  const probe = new Date(
+    Date.UTC(utc.getUTCFullYear(), utc.getUTCMonth(), utc.getUTCDate(), 12, 0, 0)
+  ).toISOString();
+  return startOfDayInTimezone(probe, timeZone);
+}
+function getTimeInTimezone(iso, timeZone) {
+  const p = partsInTimezone(new Date(iso), timeZone);
+  return { hours: p.hour, minutes: p.minute, seconds: p.second };
+}
+function setTimeInTimezone(iso, partial, timeZone) {
+  const p = partsInTimezone(new Date(iso), timeZone);
+  const targetHours = partial.hours ?? p.hour;
+  const targetMinutes = partial.minutes ?? p.minute;
+  const targetSeconds = partial.seconds ?? p.second;
+  const civilEpoch = Date.UTC(
+    p.year,
+    p.month - 1,
+    p.day,
+    targetHours,
+    targetMinutes,
+    targetSeconds
+  );
+  const probe1 = new Date(civilEpoch).toISOString();
+  const offset1 = getTimezoneOffsetMinutes(probe1, timeZone);
+  const realEpoch1 = civilEpoch - offset1 * 6e4;
+  const probe2 = new Date(realEpoch1).toISOString();
+  const offset2 = getTimezoneOffsetMinutes(probe2, timeZone);
+  const realEpoch2 = civilEpoch - offset2 * 6e4;
+  return new Date(realEpoch2).toISOString();
+}
+
 // src/utils/labels.ts
 var DEFAULT_DATEPICKER_LABELS = {
   triggerOpen: "Open calendar",
@@ -578,7 +456,9 @@ var DEFAULT_RANGEPICKER_LABELS = {
   popoverLabel: "Choose date range",
   startInput: "Start date",
   endInput: "End date",
-  presetsGroup: "Date range presets"
+  presetsGroup: "Date range presets",
+  selectingEnd: "Now select end date",
+  rangeSelected: "Range selected"
 };
 var DEFAULT_TIMEPICKER_LABELS = {
   timeInput: "Time",
@@ -599,7 +479,6 @@ var DEFAULT_DATETIMEPICKER_LABELS = {
   DEFAULT_DATETIMEPICKER_LABELS,
   DEFAULT_RANGEPICKER_LABELS,
   DEFAULT_TIMEPICKER_LABELS,
-  DateFnsAdapter,
   civilMidnightFromUtcDay,
   formatFullDate,
   formatInTimezone,
@@ -609,6 +488,7 @@ var DEFAULT_DATETIMEPICKER_LABELS = {
   generateHours,
   generateMinutes,
   getCalendarDays,
+  getISOWeekNumber,
   getMonthName,
   getTime,
   getTimeInTimezone,

package/dist/index.d.cts

@@ -15,7 +15,8 @@ type ISODateString = string;
  *   { 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
+ *   { dayOfWeek: [0, 6] },                  // disable weekends
+ *   { filter: (iso) => holidays.has(iso) }, // programmatic filter
  * ];
  * ```
  */
@@ -27,6 +28,8 @@ type DisabledRule = {
     after: ISODateString;
 } | {
     dayOfWeek: number[];
+} | {
+    filter: (iso: ISODateString) => boolean;
 };
 /** Date range (RangePicker) */
 interface DateRange {
@@ -108,23 +111,14 @@ interface CalendarOptions {
      * midnight form while the grid iterates in UTC.
      */
     timezone?: string;
+    /**
+     * Always emit exactly six weeks (42 days). The default (`false`) emits 4–6 weeks
+     * depending on the month, breaking after the last week containing a current-month day.
+     * Setting `true` is useful for layouts that need a fixed-height grid.
+     */
+    fixedWeeks?: boolean;
 }
 
-/**
- * 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.
@@ -146,6 +140,16 @@ declare const DateFnsAdapter: DateAdapter;
  * ```
  */
 declare function getCalendarDays(monthISO: string, adapter: DateAdapter, options?: CalendarOptions): CalendarGrid;
+/**
+ * Returns the ISO 8601 week number (1-53) of the given date. ISO weeks start on Monday;
+ * week 1 is the week containing the year's first Thursday. The computation works in UTC
+ * to match the calendar grid's iteration semantics.
+ *
+ * @example
+ * getISOWeekNumber('2026-01-01T00:00:00.000Z'); // 1 (Jan 1 2026 is a Thursday → ISO week 1)
+ * getISOWeekNumber('2026-12-31T00:00:00.000Z'); // 53
+ */
+declare function getISOWeekNumber(iso: ISODateString): number;
 /**
  * Checks whether the given date matches any disable rule.
  */
@@ -199,7 +203,13 @@ declare function parseTimeString(input: string): TimeValue | null;
 declare function formatTimeString(time: TimeValue, withSeconds?: boolean): string;
 /**
  * Converts a 24-hour value to 12-hour form.
- * 0 → 12 AM, 12 → 12 PM
+ *
+ * - `0` → `{ hours12: 12, period: 'AM' }` (midnight)
+ * - `12` → `{ hours12: 12, period: 'PM' }` (noon)
+ *
+ * Throws if `hours24` isn't an integer in `[0, 23]`. The previous silent
+ * modulo behaviour mapped invalid inputs (e.g. `24`, `25`, `-1`) onto
+ * arbitrary valid-looking outputs, which masked caller bugs.
  */
 declare function to12Hour(hours24: number): {
     hours12: number;
@@ -207,6 +217,10 @@ declare function to12Hour(hours24: number): {
 };
 /**
  * Converts a 12-hour value to 24-hour form.
+ *
+ * Throws if `hours12` isn't an integer in `[1, 12]`. The previous silent
+ * arithmetic produced out-of-range outputs (e.g. `to24Hour(13, 'PM')` → `25`).
+ * `period` is constrained at the type level to `'AM' | 'PM'`.
  */
 declare function to24Hour(hours12: number, period: 'AM' | 'PM'): number;
 /**
@@ -215,9 +229,15 @@ declare function to24Hour(hours12: number, period: 'AM' | 'PM'): number;
 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]
+ *
+ * - `step=1` → `[0, 1, 2, ..., 59]`
+ * - `step=15` → `[0, 15, 30, 45]`
+ * - `step=5` → `[0, 5, 10, ..., 55]`
+ * - `step=45` → `[0, 45]`
+ * - `step=60` → `[0]` (on-the-hour only)
+ *
+ * Steps above 60 are rejected because they always collapse to `[0]` — useful UX
+ * is impossible past that point.
  */
 declare function generateMinutes(step?: number): number[];
 /**
@@ -380,6 +400,16 @@ interface RangePickerLabels extends DatePickerLabels {
     startInput: string;
     endInput: string;
     presetsGroup: string;
+    /**
+     * Screen-reader prompt appended after the start date is picked, telling the user
+     * the next click commits the end of the range.
+     */
+    selectingEnd: string;
+    /**
+     * Screen-reader prefix announced when both endpoints are committed, e.g.
+     * `"Range selected: Jan 5, 2026 – Jan 12, 2026"`.
+     */
+    rangeSelected: string;
 }
 interface TimePickerLabels {
     timeInput: string;
@@ -397,4 +427,4 @@ 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, civilMidnightFromUtcDay, formatFullDate, formatInTimezone, formatMonthYear, formatTimeFromISO, formatTimeString, generateHours, generateMinutes, getCalendarDays, getMonthName, getTime, getTimeInTimezone, getTimezoneOffsetMinutes, getWeekdayNames, isDateDisabled, isSameDayInTimezone, isSameTime, maxDate, minDate, normalizeISO, parseInputValue, parseTimeString, setTime, setTimeInTimezone, startOfDayInTimezone, to12Hour, to24Hour, todayInTimezone };
+export { type CalendarDay, type CalendarGrid, type CalendarOptions, type CalendarWeek, DEFAULT_DATEPICKER_LABELS, DEFAULT_DATETIMEPICKER_LABELS, DEFAULT_RANGEPICKER_LABELS, DEFAULT_TIMEPICKER_LABELS, type DateAdapter, type DatePickerLabels, type DateRange, type DateTimePickerLabels, type DisabledRule, type ISODateString, type RangePickerLabels, type TimePickerLabels, type TimeValue, type WeekStartsOn, type WeekdayInfo, civilMidnightFromUtcDay, formatFullDate, formatInTimezone, formatMonthYear, formatTimeFromISO, formatTimeString, generateHours, generateMinutes, getCalendarDays, getISOWeekNumber, getMonthName, getTime, getTimeInTimezone, getTimezoneOffsetMinutes, getWeekdayNames, isDateDisabled, isSameDayInTimezone, isSameTime, maxDate, minDate, normalizeISO, parseInputValue, parseTimeString, setTime, setTimeInTimezone, startOfDayInTimezone, to12Hour, to24Hour, todayInTimezone };