@skdx/vue 0.26.0 → 0.28.0

package/dist/calendar/dateMath.d.cts

@@ -1,20 +1,12 @@
+import type { DateInput } from '../utils/dateValue.cjs';
 import type { CalendarDay } from './context.cjs';
 /** Pure date-math helpers for `SkdxCalendar`, built on plain native `Date` — no date-library dependency. */
 /**
- * How many dates a `SkdxCalendar` selects at once, and therefore what shape
- * its `value` takes:
- *
- * | `selectionMode` | `value` type          | empty selection |
- * | --------------- | --------------------- | --------------- |
- * | `'single'`      | `Date \| null`        | `null`          |
- * | `'multiple'`    | `Date[]`              | `[]`            |
- * | `'range'`       | `DateRange \| null`   | `null`          |
+ * Selection count: 'single' (Date | null), 'multiple' (Date[]), or 'range'
+ * ({ start: Date; end: Date | null } | null). Determines the shape of `value`.
  */
 export type CalendarSelectionMode = 'single' | 'multiple' | 'range';
-/**
- * A selected date range. `end` is `null` while the range is *anchored* — the
- * user has picked a start date and the next selection will close the range.
- */
+/** A selected date range. `end` is `null` while the range is anchored, awaiting a second pick. */
 export interface DateRange {
     /** First date of the range (always the earlier of the two once `end` is set). */
     start: Date;
@@ -22,106 +14,96 @@ export interface DateRange {
     end: Date | null;
 }
 /**
- * A `SkdxCalendar`'s selection, whose concrete shape follows
- * {@link CalendarSelectionMode}. One union rather than a discriminated
- * props type, because Angular `@Input`s, Vue props and Web Component
- * properties cannot discriminate on a sibling prop — semantic parity across
- * the five frameworks beats a type trick only two of them could express.
+ * Calendar's selection shape following {@link CalendarSelectionMode}. Union
+ * type (not discriminated props) for semantic parity across frameworks.
  */
 export type CalendarValue = Date | Date[] | DateRange | null;
-/** Where a date sits inside a selected range, for the `data-range-*` styling hooks. */
+/**
+ * Lenient input form of {@link CalendarValue}. Each Date position accepts ISO
+ * strings; the whole selection accepts wire strings ('2026-08-10' single,
+ * '2026-08-10,2026-08-14' set, '2026-08-10/2026-08-14' range, trailing / for
+ * anchored range). Strings read as local-time calendar dates, never UTC.
+ * Component emits the strict `Date` shape.
+ */
+export type CalendarValueInput = DateInput | ReadonlyArray<DateInput> | {
+    start: DateInput;
+    end?: DateInput | null;
+} | null;
+/** Position within a range, for the `data-range-*` styling hooks. */
 export type RangePosition = 'start' | 'middle' | 'end';
-export declare function getDaysInMonth(year: number, month: number): number;
 /**
- * Returns local midnight on the first day of the given date's month.
- *
- * @internal
+ * Navigation button step size: 'visible' pages by the whole displayed span so
+ * pages never overlap; 'single' always moves one month.
  */
+export type CalendarPageBehavior = 'visible' | 'single';
+export declare function getDaysInMonth(year: number, month: number): number;
+/** Local midnight on the first day of the given date's month. @internal */
 export declare function startOfMonth(date: Date): Date;
 /**
- * Moves `date` by `amount` calendar months (negative goes back),
- * clamping the day-of-month to the target month's length: Jan 31 + 1 month is
- * Feb 28 — or Feb 29 in a leap year — not the Mar 2/3 a bare `setMonth` on the
- * 31st would roll into. The shift is applied on the 1st of the source month for
- * exactly that reason, then the day is put back.
- *
- * Returns a fresh `Date` at **local midnight**: unlike {@link addDays} it is
- * built from year/month/day, so any time-of-day on the input is dropped. Never
- * mutates the argument, and `setMonth` carries the year across December.
- *
+ * Adds `amount` calendar months to `date`, clamping the day so it never
+ * overflows into the next month — e.g. Jan 31 + 1 month → Feb 28/29.
  * @internal
  */
 export declare function addMonths(date: Date, amount: number): Date;
-/**
- * Adds `amount` years by delegating to addMonths (amount × 12).
- *
- * @internal
- */
+/** Adds `amount` years by delegating to addMonths (amount × 12). @internal */
 export declare function addYears(date: Date, amount: number): Date;
 /**
- * Moves `date` by `amount` calendar days (negative goes back), rolling
- * across month and year boundaries — Dec 31 + 1 is Jan 1.
- *
- * Calendar arithmetic, not 24-hour arithmetic: `setDate` re-anchors the same
- * wall-clock time on the new local day, so a step across a DST boundary still
- * lands on the next day at the same hour, where adding `86400000` ms would
- * arrive an hour early or late. Copies the input — including its time-of-day,
- * unlike {@link addMonths} — and never mutates it.
- *
+ * Adds `amount` days to `date`, rolling over month and year boundaries naturally.
  * @internal
  */
 export declare function addDays(date: Date, amount: number): Date;
 /**
- * Whether `a` and `b` land on the same **local** calendar day,
- * comparing year, month and day-of-month rather than timestamps — so two dates
- * an hour apart across midnight are different days, and two dates twelve hours
- * apart within one day are the same. The comparison never converts to UTC: the
- * question a calendar grid asks is always "which cell", and cells are local.
- *
- * Both arguments are nullable and a missing one yields `false`, never a throw,
- * so callers can pass an unset selection straight in. That also makes it
- * *not* reflexive over nothing: `isSameDay(null, null)` is `false`.
- *
+ * Whether `a` and `b` fall on the same calendar day (year, month and date),
+ * ignoring the time of day. Returns `false` if either argument is `null` or `undefined`.
  * @internal
  */
 export declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
 /**
- * Whether `a` and `b` fall in the same month **of the same year** —
- * January 2025 and January 2026 are not the same month. Local months, like
- * {@link isSameDay}, and the day-of-month is ignored entirely.
- *
- * This is what marks a cell `outsideMonth` in `getVisibleWeeks`: the 6×7 grid
- * always spills into the neighbouring months, and those filler days are the
- * ones this returns `false` for. Unlike {@link isSameDay} it takes no nulls —
- * a grid always has a month.
+ * Whether `a` and `b` fall in the same month of the same year, ignoring
+ * day-of-month. Marks a cell `outsideMonth` in `getVisibleWeeks`. Unlike
+ * {@link isSameDay} it takes no nulls — a grid always has a month.
  *
  * @internal
  */
 export declare function isSameMonth(a: Date, b: Date): boolean;
-/**
- * Returns the first day of the date's week for the given `weekStartsOn` offset.
- *
- * @internal
- */
+/** The first day of the date's week for the given `weekStartsOn` offset. @internal */
 export declare function startOfWeek(date: Date, weekStartsOn: number): Date;
-/**
- * Returns the last day of the date's week (6 days after its start).
- *
- * @internal
- */
+/** The last day of the date's week (6 days after its start). @internal */
 export declare function endOfWeek(date: Date, weekStartsOn: number): Date;
-/**
- * Returns the date at local midnight, discarding the time component.
- *
- * @internal
- */
+/** The date at local midnight, discarding the time component. @internal */
 export declare function stripTime(date: Date): Date;
+/** Clamps `date` into `[minDate, maxDate]`, date-only. @internal */
+export declare function clampToDateRange(date: Date, minDate: Date | undefined, maxDate: Date | undefined): Date;
+/** True when the date is before minDate, after maxDate, or rejected by disabledFn (date-only). @internal */
+export declare function isDateDisabled(date: Date, minDate: Date | undefined, maxDate: Date | undefined, disabledFn: ((date: Date) => boolean) | undefined): boolean;
+/** The two disabled-ness inputs a Calendar resolves. */
+export interface ResolvedCalendarDisabled {
+    /** Whether the *whole* calendar is disabled. */
+    disabled: boolean;
+    /** The per-date predicate actually in effect. */
+    isDateDisabled?: (date: Date) => boolean;
+}
+/** @internal Resolves disabled and isDateDisabled props. */
+export declare function resolveCalendarDisabled(disabled: boolean | undefined, isDateDisabled: ((date: Date) => boolean) | undefined): ResolvedCalendarDisabled;
+/** @internal Puts {@link warnInstantDate} back to "not yet warned". Only needed by tests. */
+export declare function resetInstantDateWarning(): void;
 /**
- * True when the date is before minDate, after maxDate, or rejected by disabledFn (compared date-only).
+ * Warns once per process when `date` looks like a UTC instant rather than a
+ * local wall-clock day.
  *
- * @internal
+ * `new Date('2024-01-05')` is the trap: the platform reads a bare
+ * `YYYY-MM-DD` as UTC midnight, which is the 4th of January anywhere west of
+ * Greenwich, and the calendar silently renders the wrong day. `new Date(2024,
+ * 0, 5)` — local midnight — is the spelling that means what it says.
+ *
+ * Fires only for a `Date` sitting exactly on UTC midnight whose local day
+ * differs — the signature of `new Date('YYYY-MM-DD')` — so a local midnight
+ * in a positive-offset zone, which is correct, stays silent.
+ *
+ * @param date the `Date` a consumer supplied, or `null`/`undefined` for no value
+ * @param source the prop it arrived on, for the message
  */
-export declare function isDateDisabled(date: Date, minDate: Date | undefined, maxDate: Date | undefined, disabledFn: ((date: Date) => boolean) | undefined): boolean;
+export declare function warnInstantDate(date: Date | null | undefined, source: string): void;
 /**
  * Formats the date as a local `YYYY-MM-DD` string.
  *
@@ -134,64 +116,81 @@ export declare function toISODateString(date: Date): string;
  * @internal
  */
 export declare function clampToMonth(date: Date, targetMonth: Date): Date;
+/**
+ * The ISO-8601 week number of `date` (1–53).
+ *
+ * ISO 8601 numbers weeks from Monday and puts the year's first Thursday in
+ * week 1, so a week belongs to whichever year holds its Thursday — not
+ * `ceil(dayOfYear / 7)` — and it is independent of the calendar's
+ * `weekStartsOn`.
+ *
+ * Transcribed into each framework package rather than imported, since
+ * `@skdx/shared` is dev-only; `assertCalendarISOWeekContract` in
+ * `@skdx/shared/testing` keeps the five copies in agreement.
+ *
+ * @param date - Any day of the week to number; not mutated.
+ * @returns The ISO week number, `1`–`53`.
+ */
+export declare function getISOWeek(date: Date): number;
+/** Which grid a `SkdxCalendar` is showing: day, month, or year. */
+export type CalendarView = 'day' | 'month' | 'year';
+/** The three views, most granular first; every clamp/step is an index move along this array. */
+export declare const CALENDAR_VIEWS: readonly ["day", "month", "year"];
+/** How many years one page of `SkdxCalendarYearGrid` shows, and what its start is aligned to. */
+export declare const CALENDAR_YEAR_PAGE = 20;
+/** @internal Clamps `view` into the `[minView, maxView]` window, raising `maxView` to `minView` if a consumer inverted them. */
+export declare function clampView(view: CalendarView, minView: CalendarView, maxView: CalendarView): CalendarView;
+/** @internal First year of the twenty-year page containing `year` — 2026 falls on the 2020–2039 page. */
+export declare function yearPageStart(year: number): number;
+/**
+ * Whether any day from `from` to `to` inclusive is selectable — what makes a
+ * whole month or year cell refusable. `minDate`/`maxDate` narrow the window
+ * first, so the bounds-only case is two comparisons with no loop; the scan
+ * only runs when a predicate exists, and stops at the first available day.
+ */
+export declare function hasAvailableDate(from: Date, to: Date, minDate: Date | undefined, maxDate: Date | undefined, disabledFn: ((date: Date) => boolean) | undefined): boolean;
+/**
+ * The label for whatever page `view` is showing around `date`. One function
+ * so the heading, grid accessible name, and paging announcement never
+ * disagree about what is on screen.
+ */
+export declare function formatViewPageLabel(date: Date, view: CalendarView, locale?: string): string;
 /** Whether `value` is a {@link DateRange} rather than a single date, a date array, or nothing. */
 export declare function isDateRange(value: CalendarValue): value is DateRange;
 /** The empty selection for `mode`: `[]` for `multiple`, `null` for `single` and `range`. */
 export declare function emptySelection(mode: CalendarSelectionMode): CalendarValue;
-/**
- * Whether `date` is part of `value` — the selected day in `single` mode, a
- * member of the array in `multiple`, or anywhere from `start` to `end`
- * inclusive in `range` (so every cell in a range carries `aria-selected`).
- */
+/** Whether `date` is part of `value`, across all three selection modes. */
 export declare function isDateSelected(value: CalendarValue, date: Date): boolean;
-/**
- * Where `date` sits in `range`: `'start'`, `'end'`, `'middle'`, or `undefined`
- * when it is outside the range. A range still being anchored (`end: null`)
- * only ever reports `'start'`.
- */
+/** Where `date` sits in `range`, or `undefined` outside it. Anchored (`end: null`) only ever reports `'start'`. */
 export declare function rangePositionOf(range: DateRange, date: Date): RangePosition | undefined;
 /**
- * The selection that results from choosing `date` while `current` is selected.
- *
- * - `single` — just `date`.
- * - `multiple` — `date` toggled into/out of the array, kept chronological.
- * - `range` — anchors a new range (`{ start: date, end: null }`) when nothing
- *   is anchored or the previous range was already complete, otherwise closes
- *   the anchored range, ordering `start`/`end` so a backwards drag still
- *   yields `start <= end`.
+ * The selection that results from choosing `date` while `current` is
+ * selected: `single` replaces; `multiple` toggles `date` in/out, chronological;
+ * `range` anchors or closes, ordering `start`/`end` so a backwards drag still
+ * yields `start <= end`.
  */
 export declare function nextSelection(mode: CalendarSelectionMode, current: CalendarValue, date: Date): CalendarValue;
 /**
- * Words the polite live-region message for a selection change, or
- * returns `''` — announce nothing — when the selection already speaks for
- * itself. The default behind `SkdxCalendar`'s `getSelectionAnnouncement`.
+ * Words the polite live-region message for a selection change, or `''` when
+ * the selection already speaks for itself. The default behind
+ * `SkdxCalendar`'s `getSelectionAnnouncement`.
  *
- * Silent in `single` mode, deliberately: the pressed cell is focused and
- * carries `aria-selected`, so the screen reader has already read that date and
- * repeating it doubles the date up. `multiple` announces the running count and
- * not the dates, because re-reading a growing list on every click is unusable.
- * `range` is the case that needs prose in both halves — while `end` is `null`
- * it names the start *and* prompts for an end, so the user knows the range is
- * still open; once closed it reads both endpoints. Dates go through
- * `formatDateLabel`, so `locale` decides the wording of each one.
+ * Silent in `single` mode: the focused cell already carries `aria-selected`,
+ * so a screen reader has read that date already. `multiple` announces a
+ * running count, not the dates. `range` names the start while `end` is
+ * `null`, then reads both endpoints once closed.
  *
  * @internal
  */
 export declare function selectionAnnouncement(value: CalendarValue, locale: string | undefined): string;
 /**
- * Reduces any {@link CalendarValue} shape to the one date a calendar
- * should open on — the month it displays and the cell that holds the roving
- * tab stop — or `null` when nothing is selected.
- *
- * Per mode: `single` is the date itself; `multiple` is `value[0]`, the earliest,
- * since `nextSelection` keeps that array chronological; `range` is `start`,
- * including a range still anchored with `end: null`. An empty array and an
- * empty selection both give `null`.
+ * Reduces any {@link CalendarValue} shape to the one date a calendar should
+ * open on — displayed month and roving-tab-stop cell — or `null` when nothing
+ * is selected. `single` is the date itself; `multiple` is the earliest
+ * (`value[0]`, kept chronological by `nextSelection`); `range` is `start`.
  *
- * Read once, at setup, not on every change — a calendar that re-anchored as the
- * selection moved would yank the month out from under a user browsing away from
- * their own selection. `null` is the caller's cue to fall back: `SkdxCalendar`
- * displays `defaultMonth` or today, and focuses the displayed month.
+ * Read once at setup, not on every change: re-anchoring as the selection
+ * moves would yank the month out from under a user browsing away from it.
  *
  * @internal
  */

package/dist/calendar/dateMath.d.ts

@@ -1,20 +1,12 @@
+import type { DateInput } from '../utils/dateValue.js';
 import type { CalendarDay } from './context.js';
 /** Pure date-math helpers for `SkdxCalendar`, built on plain native `Date` — no date-library dependency. */
 /**
- * How many dates a `SkdxCalendar` selects at once, and therefore what shape
- * its `value` takes:
- *
- * | `selectionMode` | `value` type          | empty selection |
- * | --------------- | --------------------- | --------------- |
- * | `'single'`      | `Date \| null`        | `null`          |
- * | `'multiple'`    | `Date[]`              | `[]`            |
- * | `'range'`       | `DateRange \| null`   | `null`          |
+ * Selection count: 'single' (Date | null), 'multiple' (Date[]), or 'range'
+ * ({ start: Date; end: Date | null } | null). Determines the shape of `value`.
  */
 export type CalendarSelectionMode = 'single' | 'multiple' | 'range';
-/**
- * A selected date range. `end` is `null` while the range is *anchored* — the
- * user has picked a start date and the next selection will close the range.
- */
+/** A selected date range. `end` is `null` while the range is anchored, awaiting a second pick. */
 export interface DateRange {
     /** First date of the range (always the earlier of the two once `end` is set). */
     start: Date;
@@ -22,106 +14,96 @@ export interface DateRange {
     end: Date | null;
 }
 /**
- * A `SkdxCalendar`'s selection, whose concrete shape follows
- * {@link CalendarSelectionMode}. One union rather than a discriminated
- * props type, because Angular `@Input`s, Vue props and Web Component
- * properties cannot discriminate on a sibling prop — semantic parity across
- * the five frameworks beats a type trick only two of them could express.
+ * Calendar's selection shape following {@link CalendarSelectionMode}. Union
+ * type (not discriminated props) for semantic parity across frameworks.
  */
 export type CalendarValue = Date | Date[] | DateRange | null;
-/** Where a date sits inside a selected range, for the `data-range-*` styling hooks. */
+/**
+ * Lenient input form of {@link CalendarValue}. Each Date position accepts ISO
+ * strings; the whole selection accepts wire strings ('2026-08-10' single,
+ * '2026-08-10,2026-08-14' set, '2026-08-10/2026-08-14' range, trailing / for
+ * anchored range). Strings read as local-time calendar dates, never UTC.
+ * Component emits the strict `Date` shape.
+ */
+export type CalendarValueInput = DateInput | ReadonlyArray<DateInput> | {
+    start: DateInput;
+    end?: DateInput | null;
+} | null;
+/** Position within a range, for the `data-range-*` styling hooks. */
 export type RangePosition = 'start' | 'middle' | 'end';
-export declare function getDaysInMonth(year: number, month: number): number;
 /**
- * Returns local midnight on the first day of the given date's month.
- *
- * @internal
+ * Navigation button step size: 'visible' pages by the whole displayed span so
+ * pages never overlap; 'single' always moves one month.
  */
+export type CalendarPageBehavior = 'visible' | 'single';
+export declare function getDaysInMonth(year: number, month: number): number;
+/** Local midnight on the first day of the given date's month. @internal */
 export declare function startOfMonth(date: Date): Date;
 /**
- * Moves `date` by `amount` calendar months (negative goes back),
- * clamping the day-of-month to the target month's length: Jan 31 + 1 month is
- * Feb 28 — or Feb 29 in a leap year — not the Mar 2/3 a bare `setMonth` on the
- * 31st would roll into. The shift is applied on the 1st of the source month for
- * exactly that reason, then the day is put back.
- *
- * Returns a fresh `Date` at **local midnight**: unlike {@link addDays} it is
- * built from year/month/day, so any time-of-day on the input is dropped. Never
- * mutates the argument, and `setMonth` carries the year across December.
- *
+ * Adds `amount` calendar months to `date`, clamping the day so it never
+ * overflows into the next month — e.g. Jan 31 + 1 month → Feb 28/29.
  * @internal
  */
 export declare function addMonths(date: Date, amount: number): Date;
-/**
- * Adds `amount` years by delegating to addMonths (amount × 12).
- *
- * @internal
- */
+/** Adds `amount` years by delegating to addMonths (amount × 12). @internal */
 export declare function addYears(date: Date, amount: number): Date;
 /**
- * Moves `date` by `amount` calendar days (negative goes back), rolling
- * across month and year boundaries — Dec 31 + 1 is Jan 1.
- *
- * Calendar arithmetic, not 24-hour arithmetic: `setDate` re-anchors the same
- * wall-clock time on the new local day, so a step across a DST boundary still
- * lands on the next day at the same hour, where adding `86400000` ms would
- * arrive an hour early or late. Copies the input — including its time-of-day,
- * unlike {@link addMonths} — and never mutates it.
- *
+ * Adds `amount` days to `date`, rolling over month and year boundaries naturally.
  * @internal
  */
 export declare function addDays(date: Date, amount: number): Date;
 /**
- * Whether `a` and `b` land on the same **local** calendar day,
- * comparing year, month and day-of-month rather than timestamps — so two dates
- * an hour apart across midnight are different days, and two dates twelve hours
- * apart within one day are the same. The comparison never converts to UTC: the
- * question a calendar grid asks is always "which cell", and cells are local.
- *
- * Both arguments are nullable and a missing one yields `false`, never a throw,
- * so callers can pass an unset selection straight in. That also makes it
- * *not* reflexive over nothing: `isSameDay(null, null)` is `false`.
- *
+ * Whether `a` and `b` fall on the same calendar day (year, month and date),
+ * ignoring the time of day. Returns `false` if either argument is `null` or `undefined`.
  * @internal
  */
 export declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
 /**
- * Whether `a` and `b` fall in the same month **of the same year** —
- * January 2025 and January 2026 are not the same month. Local months, like
- * {@link isSameDay}, and the day-of-month is ignored entirely.
- *
- * This is what marks a cell `outsideMonth` in `getVisibleWeeks`: the 6×7 grid
- * always spills into the neighbouring months, and those filler days are the
- * ones this returns `false` for. Unlike {@link isSameDay} it takes no nulls —
- * a grid always has a month.
+ * Whether `a` and `b` fall in the same month of the same year, ignoring
+ * day-of-month. Marks a cell `outsideMonth` in `getVisibleWeeks`. Unlike
+ * {@link isSameDay} it takes no nulls — a grid always has a month.
  *
  * @internal
  */
 export declare function isSameMonth(a: Date, b: Date): boolean;
-/**
- * Returns the first day of the date's week for the given `weekStartsOn` offset.
- *
- * @internal
- */
+/** The first day of the date's week for the given `weekStartsOn` offset. @internal */
 export declare function startOfWeek(date: Date, weekStartsOn: number): Date;
-/**
- * Returns the last day of the date's week (6 days after its start).
- *
- * @internal
- */
+/** The last day of the date's week (6 days after its start). @internal */
 export declare function endOfWeek(date: Date, weekStartsOn: number): Date;
-/**
- * Returns the date at local midnight, discarding the time component.
- *
- * @internal
- */
+/** The date at local midnight, discarding the time component. @internal */
 export declare function stripTime(date: Date): Date;
+/** Clamps `date` into `[minDate, maxDate]`, date-only. @internal */
+export declare function clampToDateRange(date: Date, minDate: Date | undefined, maxDate: Date | undefined): Date;
+/** True when the date is before minDate, after maxDate, or rejected by disabledFn (date-only). @internal */
+export declare function isDateDisabled(date: Date, minDate: Date | undefined, maxDate: Date | undefined, disabledFn: ((date: Date) => boolean) | undefined): boolean;
+/** The two disabled-ness inputs a Calendar resolves. */
+export interface ResolvedCalendarDisabled {
+    /** Whether the *whole* calendar is disabled. */
+    disabled: boolean;
+    /** The per-date predicate actually in effect. */
+    isDateDisabled?: (date: Date) => boolean;
+}
+/** @internal Resolves disabled and isDateDisabled props. */
+export declare function resolveCalendarDisabled(disabled: boolean | undefined, isDateDisabled: ((date: Date) => boolean) | undefined): ResolvedCalendarDisabled;
+/** @internal Puts {@link warnInstantDate} back to "not yet warned". Only needed by tests. */
+export declare function resetInstantDateWarning(): void;
 /**
- * True when the date is before minDate, after maxDate, or rejected by disabledFn (compared date-only).
+ * Warns once per process when `date` looks like a UTC instant rather than a
+ * local wall-clock day.
  *
- * @internal
+ * `new Date('2024-01-05')` is the trap: the platform reads a bare
+ * `YYYY-MM-DD` as UTC midnight, which is the 4th of January anywhere west of
+ * Greenwich, and the calendar silently renders the wrong day. `new Date(2024,
+ * 0, 5)` — local midnight — is the spelling that means what it says.
+ *
+ * Fires only for a `Date` sitting exactly on UTC midnight whose local day
+ * differs — the signature of `new Date('YYYY-MM-DD')` — so a local midnight
+ * in a positive-offset zone, which is correct, stays silent.
+ *
+ * @param date the `Date` a consumer supplied, or `null`/`undefined` for no value
+ * @param source the prop it arrived on, for the message
  */
-export declare function isDateDisabled(date: Date, minDate: Date | undefined, maxDate: Date | undefined, disabledFn: ((date: Date) => boolean) | undefined): boolean;
+export declare function warnInstantDate(date: Date | null | undefined, source: string): void;
 /**
  * Formats the date as a local `YYYY-MM-DD` string.
  *
@@ -134,64 +116,81 @@ export declare function toISODateString(date: Date): string;
  * @internal
  */
 export declare function clampToMonth(date: Date, targetMonth: Date): Date;
+/**
+ * The ISO-8601 week number of `date` (1–53).
+ *
+ * ISO 8601 numbers weeks from Monday and puts the year's first Thursday in
+ * week 1, so a week belongs to whichever year holds its Thursday — not
+ * `ceil(dayOfYear / 7)` — and it is independent of the calendar's
+ * `weekStartsOn`.
+ *
+ * Transcribed into each framework package rather than imported, since
+ * `@skdx/shared` is dev-only; `assertCalendarISOWeekContract` in
+ * `@skdx/shared/testing` keeps the five copies in agreement.
+ *
+ * @param date - Any day of the week to number; not mutated.
+ * @returns The ISO week number, `1`–`53`.
+ */
+export declare function getISOWeek(date: Date): number;
+/** Which grid a `SkdxCalendar` is showing: day, month, or year. */
+export type CalendarView = 'day' | 'month' | 'year';
+/** The three views, most granular first; every clamp/step is an index move along this array. */
+export declare const CALENDAR_VIEWS: readonly ["day", "month", "year"];
+/** How many years one page of `SkdxCalendarYearGrid` shows, and what its start is aligned to. */
+export declare const CALENDAR_YEAR_PAGE = 20;
+/** @internal Clamps `view` into the `[minView, maxView]` window, raising `maxView` to `minView` if a consumer inverted them. */
+export declare function clampView(view: CalendarView, minView: CalendarView, maxView: CalendarView): CalendarView;
+/** @internal First year of the twenty-year page containing `year` — 2026 falls on the 2020–2039 page. */
+export declare function yearPageStart(year: number): number;
+/**
+ * Whether any day from `from` to `to` inclusive is selectable — what makes a
+ * whole month or year cell refusable. `minDate`/`maxDate` narrow the window
+ * first, so the bounds-only case is two comparisons with no loop; the scan
+ * only runs when a predicate exists, and stops at the first available day.
+ */
+export declare function hasAvailableDate(from: Date, to: Date, minDate: Date | undefined, maxDate: Date | undefined, disabledFn: ((date: Date) => boolean) | undefined): boolean;
+/**
+ * The label for whatever page `view` is showing around `date`. One function
+ * so the heading, grid accessible name, and paging announcement never
+ * disagree about what is on screen.
+ */
+export declare function formatViewPageLabel(date: Date, view: CalendarView, locale?: string): string;
 /** Whether `value` is a {@link DateRange} rather than a single date, a date array, or nothing. */
 export declare function isDateRange(value: CalendarValue): value is DateRange;
 /** The empty selection for `mode`: `[]` for `multiple`, `null` for `single` and `range`. */
 export declare function emptySelection(mode: CalendarSelectionMode): CalendarValue;
-/**
- * Whether `date` is part of `value` — the selected day in `single` mode, a
- * member of the array in `multiple`, or anywhere from `start` to `end`
- * inclusive in `range` (so every cell in a range carries `aria-selected`).
- */
+/** Whether `date` is part of `value`, across all three selection modes. */
 export declare function isDateSelected(value: CalendarValue, date: Date): boolean;
-/**
- * Where `date` sits in `range`: `'start'`, `'end'`, `'middle'`, or `undefined`
- * when it is outside the range. A range still being anchored (`end: null`)
- * only ever reports `'start'`.
- */
+/** Where `date` sits in `range`, or `undefined` outside it. Anchored (`end: null`) only ever reports `'start'`. */
 export declare function rangePositionOf(range: DateRange, date: Date): RangePosition | undefined;
 /**
- * The selection that results from choosing `date` while `current` is selected.
- *
- * - `single` — just `date`.
- * - `multiple` — `date` toggled into/out of the array, kept chronological.
- * - `range` — anchors a new range (`{ start: date, end: null }`) when nothing
- *   is anchored or the previous range was already complete, otherwise closes
- *   the anchored range, ordering `start`/`end` so a backwards drag still
- *   yields `start <= end`.
+ * The selection that results from choosing `date` while `current` is
+ * selected: `single` replaces; `multiple` toggles `date` in/out, chronological;
+ * `range` anchors or closes, ordering `start`/`end` so a backwards drag still
+ * yields `start <= end`.
  */
 export declare function nextSelection(mode: CalendarSelectionMode, current: CalendarValue, date: Date): CalendarValue;
 /**
- * Words the polite live-region message for a selection change, or
- * returns `''` — announce nothing — when the selection already speaks for
- * itself. The default behind `SkdxCalendar`'s `getSelectionAnnouncement`.
+ * Words the polite live-region message for a selection change, or `''` when
+ * the selection already speaks for itself. The default behind
+ * `SkdxCalendar`'s `getSelectionAnnouncement`.
  *
- * Silent in `single` mode, deliberately: the pressed cell is focused and
- * carries `aria-selected`, so the screen reader has already read that date and
- * repeating it doubles the date up. `multiple` announces the running count and
- * not the dates, because re-reading a growing list on every click is unusable.
- * `range` is the case that needs prose in both halves — while `end` is `null`
- * it names the start *and* prompts for an end, so the user knows the range is
- * still open; once closed it reads both endpoints. Dates go through
- * `formatDateLabel`, so `locale` decides the wording of each one.
+ * Silent in `single` mode: the focused cell already carries `aria-selected`,
+ * so a screen reader has read that date already. `multiple` announces a
+ * running count, not the dates. `range` names the start while `end` is
+ * `null`, then reads both endpoints once closed.
  *
  * @internal
  */
 export declare function selectionAnnouncement(value: CalendarValue, locale: string | undefined): string;
 /**
- * Reduces any {@link CalendarValue} shape to the one date a calendar
- * should open on — the month it displays and the cell that holds the roving
- * tab stop — or `null` when nothing is selected.
- *
- * Per mode: `single` is the date itself; `multiple` is `value[0]`, the earliest,
- * since `nextSelection` keeps that array chronological; `range` is `start`,
- * including a range still anchored with `end: null`. An empty array and an
- * empty selection both give `null`.
+ * Reduces any {@link CalendarValue} shape to the one date a calendar should
+ * open on — displayed month and roving-tab-stop cell — or `null` when nothing
+ * is selected. `single` is the date itself; `multiple` is the earliest
+ * (`value[0]`, kept chronological by `nextSelection`); `range` is `start`.
  *
- * Read once, at setup, not on every change — a calendar that re-anchored as the
- * selection moved would yank the month out from under a user browsing away from
- * their own selection. `null` is the caller's cue to fall back: `SkdxCalendar`
- * displays `defaultMonth` or today, and focuses the displayed month.
+ * Read once at setup, not on every change: re-anchoring as the selection
+ * moves would yank the month out from under a user browsing away from it.
  *
  * @internal
  */