@skdx/vue 0.27.0 → 0.29.0

package/dist/calendar/context.d.cts

@@ -1,5 +1,5 @@
 import type { InjectionKey, Ref } from 'vue';
-import type { CalendarSelectionMode, CalendarValue } from './dateMath.cjs';
+import type { CalendarSelectionMode, CalendarValue, CalendarView } from './dateMath.cjs';
 /** One cell in a `SkdxCalendar` grid week, as produced by `getVisibleWeeks`. */
 export interface CalendarDay {
     date: Date;
@@ -14,20 +14,44 @@ export interface CalendarContext {
     /** Every displayed month, `numberOfMonths` long, starting at `month`. */
     months: Readonly<Ref<Date[]>>;
     focusedDate: Readonly<Ref<Date>>;
+    /** Date treated as today; read once or supplied. */
+    today: Readonly<Ref<Date>>;
     weekStartsOn: number;
-    locale?: string;
+    /** Whether the grid labels each week row with its ISO-8601 week number. */
+    weekNumbers: boolean;
+    locale?: string | undefined;
     /** Weekday names for `locale`, rotated to start at `weekStartsOn`, as `{ short, long }` pairs. */
     weekDayNames: Readonly<Ref<Array<{
         short: string;
         long: string;
     }>>>;
-    minDate?: Date;
-    maxDate?: Date;
-    disabled?: (date: Date) => boolean;
-    isDateUnavailable?: (isoDate: string) => boolean;
+    minDate?: Date | undefined;
+    maxDate?: Date | undefined;
+    /** Whether the calendar refuses selection changes while staying fully focusable. */
+    readOnly: boolean;
+    /** Whether the whole calendar is disabled — every cell natively disabled, no tab stop anywhere. */
+    disabled: boolean;
+    /** Whether a day rendered from an adjacent month is pickable rather than natively disabled. */
+    outsideDaySelectable: boolean;
+    isDateDisabled?: ((date: Date) => boolean) | undefined;
+    isDateUnavailable?: ((date: Date) => boolean) | undefined;
     onValueChange(date: Date): void;
     onMonthChange(month: Date): void;
+    /** Page back/forward, announcing change. Step size by view. */
+    pageMonths(direction: -1 | 1): void;
     setFocusedDate(date: Date): void;
+    /** Grid being shown (each part renders for own view). */
+    view: CalendarView;
+    /** The most granular view the calendar steps down to. */
+    minView: CalendarView;
+    /** Least granular view; `SkdxCalendarHeading` goes to this. */
+    maxView: CalendarView;
+    /** Sets view clamped to minView/maxView; unchanged reports nothing. */
+    setView(view: CalendarView): void;
+    /** Moves cursor to date, pages month, steps view down. */
+    navigateToUnit(date: Date): void;
+    /** This Calendar's own root element, so focus restoration can scope its cell lookup to it. */
+    rootRef: Readonly<Ref<HTMLElement | null>>;
 }
 /** @internal Injection key a Calendar provides so its grid/cells can read selected/focused-date state and drive selection and navigation. */
 export declare const CALENDAR_CONTEXT: InjectionKey<CalendarContext>;

package/dist/calendar/context.d.ts

@@ -1,5 +1,5 @@
 import type { InjectionKey, Ref } from 'vue';
-import type { CalendarSelectionMode, CalendarValue } from './dateMath.js';
+import type { CalendarSelectionMode, CalendarValue, CalendarView } from './dateMath.js';
 /** One cell in a `SkdxCalendar` grid week, as produced by `getVisibleWeeks`. */
 export interface CalendarDay {
     date: Date;
@@ -14,20 +14,44 @@ export interface CalendarContext {
     /** Every displayed month, `numberOfMonths` long, starting at `month`. */
     months: Readonly<Ref<Date[]>>;
     focusedDate: Readonly<Ref<Date>>;
+    /** Date treated as today; read once or supplied. */
+    today: Readonly<Ref<Date>>;
     weekStartsOn: number;
-    locale?: string;
+    /** Whether the grid labels each week row with its ISO-8601 week number. */
+    weekNumbers: boolean;
+    locale?: string | undefined;
     /** Weekday names for `locale`, rotated to start at `weekStartsOn`, as `{ short, long }` pairs. */
     weekDayNames: Readonly<Ref<Array<{
         short: string;
         long: string;
     }>>>;
-    minDate?: Date;
-    maxDate?: Date;
-    disabled?: (date: Date) => boolean;
-    isDateUnavailable?: (isoDate: string) => boolean;
+    minDate?: Date | undefined;
+    maxDate?: Date | undefined;
+    /** Whether the calendar refuses selection changes while staying fully focusable. */
+    readOnly: boolean;
+    /** Whether the whole calendar is disabled — every cell natively disabled, no tab stop anywhere. */
+    disabled: boolean;
+    /** Whether a day rendered from an adjacent month is pickable rather than natively disabled. */
+    outsideDaySelectable: boolean;
+    isDateDisabled?: ((date: Date) => boolean) | undefined;
+    isDateUnavailable?: ((date: Date) => boolean) | undefined;
     onValueChange(date: Date): void;
     onMonthChange(month: Date): void;
+    /** Page back/forward, announcing change. Step size by view. */
+    pageMonths(direction: -1 | 1): void;
     setFocusedDate(date: Date): void;
+    /** Grid being shown (each part renders for own view). */
+    view: CalendarView;
+    /** The most granular view the calendar steps down to. */
+    minView: CalendarView;
+    /** Least granular view; `SkdxCalendarHeading` goes to this. */
+    maxView: CalendarView;
+    /** Sets view clamped to minView/maxView; unchanged reports nothing. */
+    setView(view: CalendarView): void;
+    /** Moves cursor to date, pages month, steps view down. */
+    navigateToUnit(date: Date): void;
+    /** This Calendar's own root element, so focus restoration can scope its cell lookup to it. */
+    rootRef: Readonly<Ref<HTMLElement | null>>;
 }
 /** @internal Injection key a Calendar provides so its grid/cells can read selected/focused-date state and drive selection and navigation. */
 export declare const CALENDAR_CONTEXT: InjectionKey<CalendarContext>;

package/dist/calendar/dateMath.cjs

@@ -1 +1 @@
-const g=require("./locale.cjs");function c(t,e){return new Date(t,e+1,0).getDate()}function m(t){return new Date(t.getFullYear(),t.getMonth(),1)}function M(t,e){const n=t.getDate(),r=new Date(t.getFullYear(),t.getMonth(),1);r.setMonth(r.getMonth()+e);const i=c(r.getFullYear(),r.getMonth());return r.setDate(Math.min(n,i)),r}function S(t,e){return M(t,e*12)}function D(t,e){const n=new Date(t);return n.setDate(n.getDate()+e),n}function l(t,e){return!t||!e?!1:t.getFullYear()===e.getFullYear()&&t.getMonth()===e.getMonth()&&t.getDate()===e.getDate()}function d(t,e){return t.getFullYear()===e.getFullYear()&&t.getMonth()===e.getMonth()}function h(t,e){const n=new Date(t.getFullYear(),t.getMonth(),t.getDate()),r=(n.getDay()-e+7)%7;return n.setDate(n.getDate()-r),n}function T(t,e){return D(h(t,e),6)}function s(t){return new Date(t.getFullYear(),t.getMonth(),t.getDate())}function Y(t,e,n,r){const i=s(t).getTime();return!!(e&&i<s(e).getTime()||n&&i>s(n).getTime()||r?.(t))}function p(t){return`${t.getFullYear()}-${String(t.getMonth()+1).padStart(2,"0")}-${String(t.getDate()).padStart(2,"0")}`}function A(t,e){if(d(t,e))return t;const n=c(e.getFullYear(),e.getMonth());return new Date(e.getFullYear(),e.getMonth(),Math.min(t.getDate(),n))}function u(t){return t!==null&&!Array.isArray(t)&&!(t instanceof Date)}function F(t){return t==="multiple"?[]:null}function O(t,e){return t===null?!1:Array.isArray(t)?t.some(n=>l(n,e)):u(t)?y(t,e)!==void 0:l(t,e)}function y(t,e){const n=s(e).getTime(),r=s(t.start).getTime();if(t.end===null)return n===r?"start":void 0;const i=s(t.end).getTime();if(!(n<r||n>i))return n===r?"start":n===i?"end":"middle"}function w(t,e,n){if(t==="single")return n;if(t==="multiple"){const i=Array.isArray(e)?e:[],a=i.filter(o=>!l(o,n));return a.length!==i.length?a:[...i,n].sort((o,f)=>o.getTime()-f.getTime())}const r=u(e)&&e.end===null?e:void 0;return r?s(n).getTime()<s(r.start).getTime()?{start:n,end:r.start}:{start:r.start,end:n}:{start:n,end:null}}function k(t,e){return u(t)?t.end===null?`${g.formatDateLabel(t.start,e)} selected as the range start. Select an end date.`:`Range selected, ${g.formatDateLabel(t.start,e)} to ${g.formatDateLabel(t.end,e)}.`:Array.isArray(t)?`${t.length} ${t.length===1?"date":"dates"} selected.`:""}function $(t){return t===null?null:Array.isArray(t)?t[0]??null:u(t)?t.start:t}function I(t,e=0){const n=h(m(t),e),r=[];let i=n;for(let a=0;a<6;a++){const o=[];for(let f=0;f<7;f++)o.push({date:i,outsideMonth:!d(i,t)}),i=D(i,1);r.push(o)}return r}exports.addDays=D;exports.addMonths=M;exports.addYears=S;exports.anchorOf=$;exports.clampToMonth=A;exports.emptySelection=F;exports.endOfWeek=T;exports.getDaysInMonth=c;exports.getVisibleWeeks=I;exports.isDateDisabled=Y;exports.isDateRange=u;exports.isDateSelected=O;exports.isSameDay=l;exports.isSameMonth=d;exports.nextSelection=w;exports.rangePositionOf=y;exports.selectionAnnouncement=k;exports.startOfMonth=m;exports.startOfWeek=h;exports.stripTime=s;exports.toISODateString=p;
+const Y=require("../utils/dev-mode.cjs"),g=require("../utils/calendar-locale.cjs");function D(t,e){return new Date(t,e+1,0).getDate()}function y(t){return new Date(t.getFullYear(),t.getMonth(),1)}function T(t,e){const n=t.getDate(),r=new Date(t.getFullYear(),t.getMonth(),1);r.setMonth(r.getMonth()+e);const i=D(r.getFullYear(),r.getMonth());return r.setDate(Math.min(n,i)),r}function w(t,e){return T(t,e*12)}function h(t,e){const n=new Date(t);return n.setDate(n.getDate()+e),n}function c(t,e){return!t||!e?!1:t.getFullYear()===e.getFullYear()&&t.getMonth()===e.getMonth()&&t.getDate()===e.getDate()}function d(t,e){return t.getFullYear()===e.getFullYear()&&t.getMonth()===e.getMonth()}function m(t,e){const n=new Date(t.getFullYear(),t.getMonth(),t.getDate()),r=(n.getDay()-e+7)%7;return n.setDate(n.getDate()-r),n}function p(t,e){return h(m(t,e),6)}function a(t){return new Date(t.getFullYear(),t.getMonth(),t.getDate())}function O(t,e,n){return e&&a(t).getTime()<a(e).getTime()?e:n&&a(t).getTime()>a(n).getTime()?n:t}function F(t,e,n,r){const i=a(t).getTime();return!!(e&&i<a(e).getTime()||n&&i>a(n).getTime()||r?.(t))}function C(t,e){return{disabled:t??!1,isDateDisabled:e}}var M=!1;function I(t,e){!t||M||t.getUTCHours()===0&&t.getUTCMinutes()===0&&t.getUTCSeconds()===0&&t.getUTCMilliseconds()===0&&(t.getDate()===t.getUTCDate()&&t.getMonth()===t.getUTCMonth()||(M=!0,Y.isDevMode()&&console.warn(`[skdx] Calendar: \`${e}\` was given ${t.toISOString()}, which is midnight UTC and therefore ${t.getFullYear()}-${String(t.getMonth()+1).padStart(2,"0")}-${String(t.getDate()).padStart(2,"0")} in this time zone — a different day from the one the string says. A selection here is a local wall-clock date, never an instant: build it as \`new Date(year, monthIndex, day)\` rather than \`new Date('YYYY-MM-DD')\`, which the platform reads as UTC.`)))}function $(t){return`${t.getFullYear()}-${String(t.getMonth()+1).padStart(2,"0")}-${String(t.getDate()).padStart(2,"0")}`}function k(t,e){if(d(t,e))return t;const n=D(e.getFullYear(),e.getMonth());return new Date(e.getFullYear(),e.getMonth(),Math.min(t.getDate(),n))}function R(t){const e=new Date(t.getFullYear(),t.getMonth(),t.getDate());e.setDate(e.getDate()-(e.getDay()+6)%7+3);const n=new Date(e.getFullYear(),0,4);return n.setDate(n.getDate()-(n.getDay()+6)%7+3),1+Math.round((e.getTime()-n.getTime())/(10080*60*1e3))}var l=["day","month","year"],b=20;function E(t,e,n){const r=l.indexOf(e),i=Math.max(r,l.indexOf(n));return l[Math.min(Math.max(l.indexOf(t),r),i)]}function S(t){return Math.floor(t/20)*20}function L(t,e,n,r,i){const u=n&&a(n)>a(t)?a(n):a(t),s=r&&a(r)<a(e)?a(r):a(e);if(u.getTime()>s.getTime())return!1;if(!i)return!0;for(let o=u;o.getTime()<=s.getTime();o=h(o,1))if(!i(o))return!0;return!1}function W(t,e,n){if(e==="day")return g.formatMonthLabel(t,n);if(e==="month")return g.formatYear(t.getFullYear(),n);const r=S(t.getFullYear());return g.formatYearRange(r,r+20-1,n)}function f(t){return t!==null&&!Array.isArray(t)&&!(t instanceof Date)}function _(t){return t==="multiple"?[]:null}function P(t,e){return t===null?!1:Array.isArray(t)?t.some(n=>c(n,e)):f(t)?A(t,e)!==void 0:c(t,e)}function A(t,e){const n=a(e).getTime(),r=a(t.start).getTime();if(t.end===null)return n===r?"start":void 0;const i=a(t.end).getTime();if(!(n<r||n>i))return n===r?"start":n===i?"end":"middle"}function U(t,e,n){if(t==="single")return n;if(t==="multiple"){const i=Array.isArray(e)?e:[],u=i.filter(s=>!c(s,n));return u.length!==i.length?u:[...i,n].sort((s,o)=>s.getTime()-o.getTime())}const r=f(e)&&e.end===null?e:void 0;return r?a(n).getTime()<a(r.start).getTime()?{start:n,end:r.start}:{start:r.start,end:n}:{start:n,end:null}}function V(t,e){return f(t)?t.end===null?`${g.formatDateLabel(t.start,e)} selected as the range start. Select an end date.`:`Range selected, ${g.formatDateLabel(t.start,e)} to ${g.formatDateLabel(t.end,e)}.`:Array.isArray(t)?`${t.length} ${t.length===1?"date":"dates"} selected.`:""}function x(t){return t===null?null:Array.isArray(t)?t[0]??null:f(t)?t.start:t}function q(t,e=0){const n=m(y(t),e),r=[];let i=n;for(let u=0;u<6;u++){const s=[];for(let o=0;o<7;o++)s.push({date:i,outsideMonth:!d(i,t)}),i=h(i,1);r.push(s)}return r}exports.CALENDAR_VIEWS=l;exports.CALENDAR_YEAR_PAGE=b;exports.addDays=h;exports.addMonths=T;exports.addYears=w;exports.anchorOf=x;exports.clampToDateRange=O;exports.clampToMonth=k;exports.clampView=E;exports.emptySelection=_;exports.endOfWeek=p;exports.formatViewPageLabel=W;exports.getDaysInMonth=D;exports.getISOWeek=R;exports.getVisibleWeeks=q;exports.hasAvailableDate=L;exports.isDateDisabled=F;exports.isDateRange=f;exports.isDateSelected=P;exports.isSameDay=c;exports.isSameMonth=d;exports.nextSelection=U;exports.rangePositionOf=A;exports.resolveCalendarDisabled=C;exports.selectionAnnouncement=V;exports.startOfMonth=y;exports.startOfWeek=m;exports.stripTime=a;exports.toISODateString=$;exports.warnInstantDate=I;exports.yearPageStart=S;

package/dist/calendar/dateMath.d.cts

@@ -1,200 +1,120 @@
+import type { DateInput } from '../utils/date-value.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 mode: 'single' (Date | null), 'multiple' (Date[]), or 'range' ({start,end}|null) — determines value's shape. */
 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;
     /** Last date of the range, or `null` while only the anchor has been picked. */
     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}. */
 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}; accepts ISO date strings, read as local-time calendar dates. */
+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`.
- *
- * @internal
- */
+/** @internal Whether a and b fall on the same calendar day, ignoring time; false if either is null/undefined. */
 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.
- *
- * @internal
- */
+/** @internal Whether a and b fall in the same month of the same year, ignoring day-of-month. */
 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;
-/**
- * True when the date is before minDate, after maxDate, or rejected by disabledFn (compared date-only).
- *
- * @internal
- */
+/** 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) | undefined;
+}
+/** @internal Resolves disabled and isDateDisabled props. */
+export declare function resolveCalendarDisabled(disabled: boolean | undefined, isDateDisabled: ((date: Date) => boolean) | undefined): ResolvedCalendarDisabled;
+/** @internal Resets {@link warnInstantDate}'s once-per-process flag. */
+export declare function resetInstantDateWarning(): void;
 /**
- * Formats the date as a local `YYYY-MM-DD` string.
+ * Warns once per process when `date` looks like a UTC instant rather than a local wall-clock day.
  *
- * @internal
+ * @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 warnInstantDate(date: Date | null | undefined, source: string): void;
+/** @internal Formats the date as a local YYYY-MM-DD string. */
 export declare function toISODateString(date: Date): string;
-/**
- * Returns the same day-of-month within targetMonth, clamping to that month's length.
- *
- * @internal
- */
+/** @internal Returns the same day-of-month within targetMonth, clamping to that month's length. */
 export declare function clampToMonth(date: Date, targetMonth: Date): Date;
+/**
+ * The ISO-8601 week number of `date` (1–53).
+ *
+ * @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. */
+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. */
+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`.
- *
- * 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.
- *
- * @internal
- */
+/** @internal Words the polite live-region message for a selection change, or '' when the selection already speaks for itself. */
 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`.
- *
- * 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.
- *
- * @internal
- */
+/** @internal Reduces any {@link CalendarValue} shape to the one date a calendar should open on, or null when nothing is selected. */
 export declare function anchorOf(value: CalendarValue): Date | null;
 /** Always returns a 6x7 (weeks x weekdays) grid, including adjacent-month filler days. */
 export declare function getVisibleWeeks(month: Date, weekStartsOn?: number): CalendarDay[][];