@kalyx/core 1.0.0-rc.7 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,251 @@
 # @kalyx/core
 
+## 1.0.0
+
+### Major Changes
+
+- 5b6c37f: Extract `@kalyx/adapter-date-fns` and make `@kalyx/core` neutral
+
+  Step 1 + 2 of the four-step adapter-extraction plan (see `.claude/skills/adapter-extraction.md`). After this change, `@kalyx/core` no longer depends on `date-fns` or `date-fns-tz`; it ships only the platform-agnostic date logic (`getCalendarDays`, `isDateDisabled`, timezone helpers, labels, the `DateAdapter` contract). The DateFnsAdapter implementation now lives in its own publishable package so dayjs / luxon / Temporal adapters can be added later without forcing every Kalyx user to bundle two date libraries.
+
+  ### What changed
+  - **`@kalyx/core`** — `DateFnsAdapter` is no longer exported and `date-fns` / `date-fns-tz` are no longer listed as dependencies. `utils/timezone.ts` was the lone leak and uses native `new Date(string)` now (every caller already routes through `normalizeISO` or `DateAdapter.parse`, so the input subset is fully spec-defined).
+  - **`@kalyx/adapter-date-fns`** — new package with the full `DateFnsAdapter` implementation moved verbatim. Same UTC semantics, same timezone-aware paths, same 35 adapter tests.
+  - **`@kalyx/react`** — imports `DateFnsAdapter` from `@kalyx/adapter-date-fns` now. The default adapter is still wired up automatically — anyone using `import { DatePicker } from '@kalyx/react'` keeps the previous behaviour with zero changes. The adapter package is a direct dependency so consumers installing just `@kalyx/react` continue to get a working default.
+
+  ### Migration
+
+  If you imported `DateFnsAdapter` directly from `@kalyx/core`:
+
+  ```diff
+  - import { DateFnsAdapter } from '@kalyx/core';
+  + import { DateFnsAdapter } from '@kalyx/adapter-date-fns';
+  ```
+
+  `@kalyx/react` consumers don't need to change anything — the adapter is still re-exported from `@kalyx/react`.
+
+  ### Next (separate PR)
+
+  The `/headless` entry point (`@kalyx/react/headless`) that lets dayjs/luxon users tree-shake date-fns out is a follow-up. The component Roots still default to the date-fns adapter inline; the entry split requires moving that fallback out of each Root and into the entry boundary.
+
+- ca7180e: chore: v1.0 milestone — API freeze.
+
+  Kalyx v1.0 declares the public API stable. This is a milestone release bundling the v0.5 surface additions (MonthPicker, YearPicker, WeekPicker, DatePicker.Presets, `onOpenChange`/`onCalendarNavigate` event callbacks) with an explicit commitment to semantic versioning going forward.
+
+  ### What v1.0 commits to
+  - **Public API surface** — exports from `@kalyx/react` and `@kalyx/core` listed in their `index.ts` files. Any breaking change requires a major bump.
+  - **Compositional structure** — Root + subcomponent names (`DatePicker.Input`, `DatePicker.Calendar`, …) are stable. Removal or renaming requires a major bump.
+  - **Value semantics** — ISO 8601 UTC strings for single dates, `DateRange` `{start, end}` for ranges. `displayTimezone` behavior (civil-midnight-in-tz for date selection) is stable.
+  - **Accessibility contracts** — role/aria-\* attributes emitted by each component are stable.
+
+  ### What v1.0 does NOT freeze
+  - Internal implementation details (non-exported functions, component file layout).
+  - CSS class name strings on elements — no classes are applied by default; only when a consumer passes them via `classNames` props.
+  - Error message text.
+  - Peer dependency version ranges (may expand to cover new React majors).
+
+  ### Breaking changes vs 0.4.x
+
+  None. v1.0 is API-compatible with 0.4.x — existing code continues to work. The major bump communicates stability commitment, not breakage.
+
+### Minor Changes
+
+- 0eca2e8: Two new `DatePicker.Calendar` / `RangePicker.Calendar` props plus an ISO-week utility:
+  - **`showWeekNumber`** — render an ISO 8601 week-number column (1–53) on the left of the grid. The column uses `<th scope="row" aria-hidden="true">` so it doesn't participate in the WAI-ARIA grid data region; keyboard navigation across date cells is unchanged. New className slots: `weekNumberHeader`, `weekNumber`.
+  - **`fixedWeeks`** — when true, always render 6 rows (42 cells) regardless of the month. Useful for popover layouts that need a stable height across month navigation.
+
+  Both also accepted on `CalendarOptions` (the `getCalendarDays` core util gains `fixedWeeks`).
+
+  New core export: **`getISOWeekNumber(iso)`** — pure UTC computation, no date-fns dep. Anchored to the Thursday of the week (so the same week always returns the same number regardless of `weekStartsOn`).
+
+  ```tsx
+  <DatePicker value={date} onChange={setDate}>
+    <DatePicker.Input />
+    <DatePicker.Popover>
+      <DatePicker.Calendar showWeekNumber fixedWeeks />
+    </DatePicker.Popover>
+  </DatePicker>
+  ```
+
+  Bundle impact: +0.46 KB ESM gzip (13.96 → 14.42 KB). Still well under the 15 KB ceiling.
+
+- d62c84e: `DisabledRule` gains a programmatic `filter` variant — pass any predicate `(iso: ISODateString) => boolean` to disable arbitrary days that don't fit the declarative `before` / `after` / `dayOfWeek` / `date` rules.
+
+  ```tsx
+  const holidays = new Set(['2026-01-01T00:00:00.000Z', '2026-12-25T00:00:00.000Z']);
+
+  <DatePicker
+    disabled={[
+      { dayOfWeek: [0, 6] }, // weekends
+      { filter: (iso) => holidays.has(iso) }, // holidays
+    ]}
+  >
+    …
+  </DatePicker>;
+  ```
+
+  The new variant slots into the existing `isDateDisabled` evaluation (short-circuits on first match) and works with keyboard-navigation disabled-skip in `DatePicker.Calendar` / `RangePicker.Calendar` with no further changes. Equivalent to `react-datepicker`'s `filterDate` prop and MUI X DatePicker's `shouldDisableDate`. Bundle impact: 0 KB (still 13.96 KB ESM gzip).
+
+- 4629384: chore(oss): unify node engines to >=20 and add public repository metadata
+  - `@kalyx/react` and `@kalyx/core` now require Node `>=20`, matching the root workspace and CI. This was the de-facto requirement; only the published manifests still claimed `>=18`.
+  - Root `package.json` now exposes `homepage`, `repository`, and `bugs` so `npm info` and the npm registry page link back to the GitHub repo.
+  - `.github/PULL_REQUEST_TEMPLATE.md` bundle ceiling updated `15KB → 16 KB` to match the post-rc.8 limit advertised in README and CI.
+  - `.gitignore` ignores `.codegraph/`, `.serena/`, and `.tmp-*/` (MCP server caches and worktree scratchpads).
+
+- c8a6609: fix(rangepicker): announce next selection target and final range to screen readers
+
+  `<RangePicker.Calendar>` now announces context-aware messages through its existing `role="status"` live region:
+  - After the first click (start), it announces `<formatted-date>. Now select end date.` so screen-reader users know the next click commits the other endpoint.
+  - After the second click (end), it announces `Range selected: <start> – <end>` instead of just the bare date — matching the swap-if-before behaviour so the announcement always reflects what was committed.
+  - Week-mode commits now share the same `Range selected: ...` prefix for consistency.
+
+  The two new strings are wired through `RangePickerLabels.selectingEnd` and `RangePickerLabels.rangeSelected` with English defaults, and they are fully overridable via the existing `labels` prop for i18n. `@kalyx/core` gets a `minor` bump because `RangePickerLabels` gained required fields (with defaults supplied by `DEFAULT_RANGEPICKER_LABELS`); any consumer constructing a literal `RangePickerLabels` from scratch will need to add the two keys.
+
+### Patch Changes
+
+- 19ac1c0: fix(core): allow `generateMinutes` step values up to 60
+
+  `generateMinutes(step)` rejected any step above 30, which prevented legitimate cases like `step=45` (quarter-and-three-quarters past the hour) and `step=60` (on-the-hour only). The slot-generation loop already works for any 1–60 integer, so the upper bound is now 60 with the same error message format. Steps `0`, `61+`, and negative values still throw. No callers in `@kalyx/react` relied on the previous narrower bound.
+
+- 3587b13: Remove unused English-hardcoded weekday utilities from `utils/date.ts`:
+  - `WEEKDAY_LABELS` (constant)
+  - `getOrderedWeekdays()` (function)
+
+  Both were internal exports (never exposed via `@kalyx/core` public `index.ts`) and had no consumers anywhere in the workspace. They were superseded by the locale-aware `getWeekdayNames(locale, weekStartsOn)` in `utils/locale.ts`, which uses `Intl.DateTimeFormat` to produce the same shape with multi-language support.
+
+  No public API surface changed.
+
+- abc56ac: Security: pin transitive `fast-uri` to `>=3.1.2` and `@babel/plugin-transform-modules-systemjs` to `>=7.29.4` via `pnpm.overrides`.
+
+  Resolves three Code Scanning alerts on `pnpm-lock.yaml`:
+  - `fast-uri@3.1.0` — [GHSA-v39h-62p7-jpjc](https://osv.dev/GHSA-v39h-62p7-jpjc) (CVE-2026-6322), first patched in `3.1.2`.
+  - `fast-uri@3.1.0` — [GHSA-q3j6-qgpj-74h6](https://osv.dev/GHSA-q3j6-qgpj-74h6) (CVE-2026-6321), first patched in `3.1.1`.
+  - `@babel/plugin-transform-modules-systemjs@7.29.0` — [GHSA-fv7c-fp4j-7gwp](https://osv.dev/GHSA-fv7c-fp4j-7gwp) (CVE-2026-44728), first patched in `7.29.4` on the 7.x line.
+
+  All three packages are transitive build-time dependencies (ajv → fast-uri, Babel preset-env → systemjs plugin); no public API impact.
+
+- aadb512: Security: pin transitive `postcss` to `>=8.5.10` via `pnpm.overrides`.
+
+  Two `postcss` versions in `pnpm-lock.yaml` (`8.4.31` from a `postcss-load-config` chain and `8.5.9` from the `tsup` chain) were affected by [GHSA-qx2v-qp2m-jg93](https://osv.dev/GHSA-qx2v-qp2m-jg93) (CVSS 6.1 — improper newline handling that lets crafted input bypass quote escapes). Both are now resolved to `8.5.10`+. The OSV scanner workflow (which auto-creates issues #23 / #24 / #27) now reports zero advisories.
+
+- 0556886: fix(core): validate inputs to `to12Hour` and `to24Hour`
+
+  `to12Hour(hours24)` and `to24Hour(hours12, period)` are public exports from `@kalyx/core` but had no input validation. The previous silent arithmetic mapped invalid inputs onto plausible-looking but wrong outputs and hid caller bugs:
+  - `to12Hour(24)` returned `{ hours12: 12, period: 'PM' }` (because `24 % 12 = 0` → mapped to 12)
+  - `to12Hour(-1)` returned `{ hours12: -1, period: 'AM' }`
+  - `to24Hour(13, 'PM')` returned `25`
+  - `to24Hour(0, 'AM')` returned `0` (but `0` is not a valid 12-hour clock value — midnight is `12 AM`)
+
+  Both functions now throw `RangeError` with a clear message when the input is outside its valid integer range (`[0, 23]` for `to12Hour`, `[1, 12]` for `to24Hour`). `Number.isInteger` guards non-integers and `NaN`. No `@kalyx/react` callers ever passed invalid values, so the internal contracts are unchanged; only direct `@kalyx/core` users who relied on the silent-wrong behaviour see the new exception.
+
+- df97687: P1 audit follow-ups for v1.0-rc:
+  - **SSR hydration safety in 4 commit/drilldown grids** — `DatePicker.MonthGrid`, `DatePicker.YearGrid`, `MonthPicker.Grid`, and `YearPicker.Grid` previously called `adapter.today()` directly inside their render bodies, producing a server/client clock-mismatch hydration warning across day boundaries (and intermittently wrong "today" highlights in tz-different SSR setups). Today is now snapshotted via `useState(null)` + post-mount `useEffect`, so the server output and the first client render agree, and the highlight settles on the first effect tick.
+  - **`AmPmToggle` now follows the WAI-ARIA radiogroup pattern** — Arrow / Home / End / Space / Enter move and commit selection between AM and PM, and `tabIndex` is roving (only the checked radio is in the tab order). Previously both buttons were tabbable and arrow keys were ignored.
+  - **`DatePicker.Preset` / `RangePicker.Preset` now use `aria-pressed`** instead of `role="option"` + `aria-selected`. `role="option"` is invalid outside `role="listbox"` / `role="combobox"`, so axe was flagging the previous markup. Active state still appears on `data-active` for CSS targeting.
+  - **`RangePicker.Calendar` no longer advertises `aria-multiselectable="true"`** — a date range is one selection (two endpoints), not a multi-select grid.
+  - **Test stability** — `useRangePicker` `respects disabled rules` test pinned to April 2026 via `defaultValue` so the calendar grid contains the expected weekend day regardless of the system clock (was failing once the clock crossed into May).
+  - **`labels.ts` test coverage** — first unit tests for the default-label exports.
+
+  Behavioral notes for users (none of these are breaking for code that follows the documented `data-*` styling contract):
+  - If you targeted Preset buttons via `[aria-selected="true"]` in CSS, switch to `[aria-pressed="true"]` or `[data-active]`.
+  - If you targeted the range grid via `[aria-multiselectable]`, that attribute is gone; use `[role="grid"]` on the calendar root instead.
+
+- 21f3c1f: Resolve v1.0-rc release-blocking defects (P0):
+  - **`"use client"` directive** — bundle is now marked as a React Server Component client boundary via tsup banner. Next.js App Router consumers no longer have to wrap each import.
+  - **Stable `today()`/`now()` initialization** — `viewMonth`/`focusedDate` `useState` calls in `DatePicker`/`RangePicker`/`DateTimePicker` Roots now use lazy initializers, so the adapter isn't called on every render.
+  - **`@kalyx/core` version sync** — bumped from `1.0.0-rc.0` to `1.0.0-rc.1` to match `@kalyx/react`.
+  - **`@kalyx/core` package contents** — `LICENSE` and `CHANGELOG.md` are now included in the npm tarball (`files` field).
+  - **Form auto-submit blocked when calendar open** — pressing Enter inside `DatePicker.Input`/`RangePicker.Input`/`DateTimePicker.Input` while the popover is open no longer submits the surrounding `<form>`.
+  - **`aria-haspopup="dialog"` on Trigger** — completes the WAI-ARIA combobox/dialog pattern.
+  - **Disabled cells skipped during keyboard navigation** — Calendar arrow keys / PageUp/Down / Home / End now step over disabled days and stop only when no enabled day is reachable.
+
+- 3228533: P1 v1.0-rc API/a11y/docs improvements:
+  - **Popover focus-out close** — `usePopover` now closes the popover when focus leaves the floating layer and the reference element (Tab through). Matches the Radix/Ark dismissable layer pattern.
+  - **`name` prop + hidden form input** — `DatePicker.Input` accepts a `name` prop. When set, a hidden `<input type="hidden">` is rendered alongside the visible input so the value participates in native form submission and integrates with `react-hook-form` Controller-less flows.
+  - **IME composition handling** — `DatePicker.Input` now defers parsing during IME composition (`compositionstart` / `compositionend`). Previously, partial Korean / Japanese / Chinese input was repeatedly re-parsed and the user's text disappeared.
+  - **README parity** — Korean README now has the "Styling with Tailwind CSS" and "Using data attributes" sections that were missing. Version table and bundle-size claim corrected to `v1.0.0-rc.1` / `11.57 KB`.
+  - **Package metadata** — `peerDependenciesMeta`, `engines.node`, and `publishConfig.provenance` added to both `@kalyx/react` and `@kalyx/core`.
+  - **`@kalyx/react` description** — corrected from "under 10 KB gzipped" (false claim) to "≤12 KB gzipped".
+
+- b6129ed: P2 polish for v1.0-rc:
+  - **Calendar grid `aria-rowindex` / `aria-colindex` / `aria-rowcount` / `aria-colcount`** — `DatePicker.Calendar` and `RangePicker.Calendar` now expose grid coordinates so screenreaders announce position ("row 3 of 6, column 4 of 7") during keyboard navigation.
+  - **`displayName` on all `forwardRef` components** — `DatePicker.Input`, `DatePicker.Trigger`, `RangePicker.Input`, `TimePicker.Input`, `DateTimePicker.Input` now render with their public dot-notation name in React DevTools.
+  - **JSDoc on `DatePicker.Input` and `DatePicker.Trigger`** — public API surface for the most-used components has explanatory docstrings.
+  - **`addYears` leap-day regression tests** — locked the date-fns clamp behavior (2024-02-29 + 1y → 2025-02-28, not March 1).
+  - **DST fall-back ambiguous-hour regression test** — captures the current behavior of `setTimeInTimezone` for 2026-11-01 01:30 America/New_York so silent drift surfaces as a test failure.
+  - **Test count claim corrected** — root and core `CLAUDE.md` previously claimed "1,000+ unit tests"; actual count is ~140 in core, 374 across the workspace.
+
+## 1.0.0-rc.13
+
+### Major Changes
+
+- 5b6c37f: Extract `@kalyx/adapter-date-fns` and make `@kalyx/core` neutral
+
+  Step 1 + 2 of the four-step adapter-extraction plan (see `.claude/skills/adapter-extraction.md`). After this change, `@kalyx/core` no longer depends on `date-fns` or `date-fns-tz`; it ships only the platform-agnostic date logic (`getCalendarDays`, `isDateDisabled`, timezone helpers, labels, the `DateAdapter` contract). The DateFnsAdapter implementation now lives in its own publishable package so dayjs / luxon / Temporal adapters can be added later without forcing every Kalyx user to bundle two date libraries.
+
+  ### What changed
+  - **`@kalyx/core`** — `DateFnsAdapter` is no longer exported and `date-fns` / `date-fns-tz` are no longer listed as dependencies. `utils/timezone.ts` was the lone leak and uses native `new Date(string)` now (every caller already routes through `normalizeISO` or `DateAdapter.parse`, so the input subset is fully spec-defined).
+  - **`@kalyx/adapter-date-fns`** — new package with the full `DateFnsAdapter` implementation moved verbatim. Same UTC semantics, same timezone-aware paths, same 35 adapter tests.
+  - **`@kalyx/react`** — imports `DateFnsAdapter` from `@kalyx/adapter-date-fns` now. The default adapter is still wired up automatically — anyone using `import { DatePicker } from '@kalyx/react'` keeps the previous behaviour with zero changes. The adapter package is a direct dependency so consumers installing just `@kalyx/react` continue to get a working default.
+
+  ### Migration
+
+  If you imported `DateFnsAdapter` directly from `@kalyx/core`:
+
+  ```diff
+  - import { DateFnsAdapter } from '@kalyx/core';
+  + import { DateFnsAdapter } from '@kalyx/adapter-date-fns';
+  ```
+
+  `@kalyx/react` consumers don't need to change anything — the adapter is still re-exported from `@kalyx/react`.
+
+  ### Next (separate PR)
+
+  The `/headless` entry point (`@kalyx/react/headless`) that lets dayjs/luxon users tree-shake date-fns out is a follow-up. The component Roots still default to the date-fns adapter inline; the entry split requires moving that fallback out of each Root and into the entry boundary.
+
+## 1.0.0-rc.12
+
+### Patch Changes
+
+- 0556886: fix(core): validate inputs to `to12Hour` and `to24Hour`
+
+  `to12Hour(hours24)` and `to24Hour(hours12, period)` are public exports from `@kalyx/core` but had no input validation. The previous silent arithmetic mapped invalid inputs onto plausible-looking but wrong outputs and hid caller bugs:
+  - `to12Hour(24)` returned `{ hours12: 12, period: 'PM' }` (because `24 % 12 = 0` → mapped to 12)
+  - `to12Hour(-1)` returned `{ hours12: -1, period: 'AM' }`
+  - `to24Hour(13, 'PM')` returned `25`
+  - `to24Hour(0, 'AM')` returned `0` (but `0` is not a valid 12-hour clock value — midnight is `12 AM`)
+
+  Both functions now throw `RangeError` with a clear message when the input is outside its valid integer range (`[0, 23]` for `to12Hour`, `[1, 12]` for `to24Hour`). `Number.isInteger` guards non-integers and `NaN`. No `@kalyx/react` callers ever passed invalid values, so the internal contracts are unchanged; only direct `@kalyx/core` users who relied on the silent-wrong behaviour see the new exception.
+
+## 1.0.0-rc.11
+
+### Minor Changes
+
+- c8a6609: fix(rangepicker): announce next selection target and final range to screen readers
+
+  `<RangePicker.Calendar>` now announces context-aware messages through its existing `role="status"` live region:
+  - After the first click (start), it announces `<formatted-date>. Now select end date.` so screen-reader users know the next click commits the other endpoint.
+  - After the second click (end), it announces `Range selected: <start> – <end>` instead of just the bare date — matching the swap-if-before behaviour so the announcement always reflects what was committed.
+  - Week-mode commits now share the same `Range selected: ...` prefix for consistency.
+
+  The two new strings are wired through `RangePickerLabels.selectingEnd` and `RangePickerLabels.rangeSelected` with English defaults, and they are fully overridable via the existing `labels` prop for i18n. `@kalyx/core` gets a `minor` bump because `RangePickerLabels` gained required fields (with defaults supplied by `DEFAULT_RANGEPICKER_LABELS`); any consumer constructing a literal `RangePickerLabels` from scratch will need to add the two keys.
+
+### Patch Changes
+
+- 19ac1c0: fix(core): allow `generateMinutes` step values up to 60
+
+  `generateMinutes(step)` rejected any step above 30, which prevented legitimate cases like `step=45` (quarter-and-three-quarters past the hour) and `step=60` (on-the-hour only). The slot-generation loop already works for any 1–60 integer, so the upper bound is now 60 with the same error message format. Steps `0`, `61+`, and negative values still throw. No callers in `@kalyx/react` relied on the previous narrower bound.
+
+## 1.0.0-rc.10
+
+### Minor Changes
+
+- 4629384: chore(oss): unify node engines to >=20 and add public repository metadata
+  - `@kalyx/react` and `@kalyx/core` now require Node `>=20`, matching the root workspace and CI. This was the de-facto requirement; only the published manifests still claimed `>=18`.
+  - Root `package.json` now exposes `homepage`, `repository`, and `bugs` so `npm info` and the npm registry page link back to the GitHub repo.
+  - `.github/PULL_REQUEST_TEMPLATE.md` bundle ceiling updated `15KB → 16 KB` to match the post-rc.8 limit advertised in README and CI.
+  - `.gitignore` ignores `.codegraph/`, `.serena/`, and `.tmp-*/` (MCP server caches and worktree scratchpads).
+
 ## 1.0.0-rc.7
 
 ### Minor Changes

package/README.md

@@ -35,11 +35,15 @@ import type {
 
 ### Adapter
 
+`@kalyx/core` defines the `DateAdapter` interface but ships no implementation — the package is date-library-agnostic. Install a separate adapter package:
+
 ```ts
-import { DateFnsAdapter } from '@kalyx/core';
-// UTC-safe default adapter, built on date-fns v4.
+import { DateFnsAdapter } from '@kalyx/adapter-date-fns';
+// UTC-safe adapter built on date-fns v4.
 ```
 
+Bring your own adapter by implementing the `DateAdapter` interface from `@kalyx/core` against any date library (dayjs, luxon, Temporal, etc.).
+
 ### Calendar utilities
 
 ```ts

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,
@@ -57,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 {
@@ -477,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;
   }
@@ -495,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) {
@@ -522,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;
 }
@@ -573,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",
@@ -590,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",
@@ -611,7 +479,6 @@ var DEFAULT_DATETIMEPICKER_LABELS = {
   DEFAULT_DATETIMEPICKER_LABELS,
   DEFAULT_RANGEPICKER_LABELS,
   DEFAULT_TIMEPICKER_LABELS,
-  DateFnsAdapter,
   civilMidnightFromUtcDay,
   formatFullDate,
   formatInTimezone,

package/dist/index.d.cts

@@ -119,21 +119,6 @@ interface CalendarOptions {
     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.
@@ -218,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;
@@ -226,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;
 /**
@@ -234,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[];
 /**
@@ -399,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;
@@ -416,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, getISOWeekNumber, 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 };

package/dist/index.d.ts

@@ -119,21 +119,6 @@ interface CalendarOptions {
     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.
@@ -218,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;
@@ -226,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;
 /**
@@ -234,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[];
 /**
@@ -399,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;
@@ -416,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, getISOWeekNumber, 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 };

package/dist/index.js

@@ -1,254 +1,3 @@
-// src/adapters/date-fns.ts
-import {
-  parseISO as parseISO2,
-  addDays as dfAddDays,
-  addMonths as dfAddMonths,
-  addYears as dfAddYears,
-  isBefore as dfIsBefore,
-  isAfter as dfIsAfter,
-  isValid as dfIsValid
-} from "date-fns";
-
-// src/utils/timezone.ts
-import { parseISO } from "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(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 = 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 = 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(parseISO(a), timeZone);
-  const pb = partsInTimezone(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 = 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(parseISO(iso), timeZone);
-  return { hours: p.hour, minutes: p.minute, seconds: p.second };
-}
-function setTimeInTimezone(iso, partial, timeZone) {
-  const p = partsInTimezone(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 parseISO2(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(dfAddDays(toDate(iso), n));
-  },
-  addMonths(iso, n) {
-    return toISO(dfAddMonths(toDate(iso), n));
-  },
-  addYears(iso, n) {
-    return toISO(dfAddYears(toDate(iso), n));
-  },
-  isBefore(a, b) {
-    return dfIsBefore(toDate(a), toDate(b));
-  },
-  isAfter(a, b) {
-    return dfIsAfter(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 = parseISO2(normalized);
-    return dfIsValid(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 {
@@ -426,12 +175,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;
   }
@@ -444,8 +199,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) {
@@ -471,13 +226,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;
 }
@@ -522,6 +277,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",
@@ -539,7 +398,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",
@@ -559,7 +420,6 @@ export {
   DEFAULT_DATETIMEPICKER_LABELS,
   DEFAULT_RANGEPICKER_LABELS,
   DEFAULT_TIMEPICKER_LABELS,
-  DateFnsAdapter,
   civilMidnightFromUtcDay,
   formatFullDate,
   formatInTimezone,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kalyx/core",
-  "version": "1.0.0-rc.7",
+  "version": "1.0.0",
   "description": "Kalyx core — platform-agnostic date logic, IANA timezone helpers, and the DateAdapter contract used by @kalyx/react",
   "license": "MIT",
   "author": "jiji-hoon96",
@@ -22,7 +22,7 @@
     "dst",
     "iso8601",
     "utc",
-    "date-fns"
+    "adapter"
   ],
   "type": "module",
   "sideEffects": false,
@@ -46,12 +46,11 @@
     "CHANGELOG.md",
     "LICENSE"
   ],
-  "dependencies": {
-    "date-fns": "^4.0.0",
-    "date-fns-tz": "^3.0.0"
+  "devDependencies": {
+    "@kalyx/adapter-date-fns": "1.0.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "publishConfig": {
     "access": "public",