@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.1

package/state/calendar.js

@@ -0,0 +1,755 @@
+// Ported from react-stately (react-spectrum, Apache-2.0, © Adobe): calendar/useCalendarState.ts,
+// calendar/useRangeCalendarState.ts and calendar/utils.ts.
+//
+// Rivet shape: the state is plain signals + JSON (resumable); every method of React Stately's
+// CalendarState / RangeCalendarState is an exported function taking the state first
+// (`state.focusNextDay()` → `focusNextDay(state)`). Dates live in the signals as strings
+// (`@rivetjs/cdk/date` `stringifyDateValue`), read back as `CalendarDate` objects by the accessors
+// (`focusedDate(state)`, `calendarValue(state)`, `visibleRange(state)` …). React Stately's
+// render-time corrections (focus outside the visible range moves the range, focus outside
+// [min, max] is constrained) run after every write and again on read, so controlled `focusedValue`
+// signals written from outside behave the same.
+import { signal, untrack } from "@rivetjs/reactivity";
+import { CalendarDate, DateFormatter, GregorianCalendar, createCalendar as createAnyCalendar, endOfMonth, endOfWeek, getDayOfWeek, getWeeksInMonth as weeksIn, isSameDay, maxDate, minDate, startOfMonth, startOfWeek, startOfYear, toCalendar, toCalendarDate, today, } from "@rivetjs/cdk/date";
+import { parseDateValue, stringifyDateValue, toDateValueString } from "@rivetjs/cdk/date";
+import { createId } from "@rivetjs/cdk/id";
+import { formatString, getStringsForLocale, resolveLocale } from "@rivetjs/cdk/i18n";
+import { calendarMessages } from "../calendar/intl.js";
+// `Signal<any>`: Signal is invariant, so a `Signal<unknown>` guard would not narrow `X | Signal<Y>`.
+const isSignal = (value) => typeof value === "function";
+const isWritable = (cell) => typeof cell.set === "function";
+// ---------------------------------------------------------------------------------------------
+// utils.ts
+export function isInvalid(date, minValue, maxValue) {
+    return (minValue != null && date.compare(minValue) < 0) || (maxValue != null && date.compare(maxValue) > 0);
+}
+export function alignCenter(date, duration, locale, minValue, maxValue) {
+    const halfDuration = {};
+    for (const key in duration) {
+        const k = key;
+        halfDuration[k] = Math.floor(duration[k] / 2);
+        if (halfDuration[k] > 0 && duration[k] % 2 === 0)
+            halfDuration[k]--;
+    }
+    const aligned = alignStart(date, duration, locale).subtract(halfDuration);
+    return constrainStart(date, aligned, duration, locale, minValue, maxValue);
+}
+export function alignStart(date, duration, locale, minValue, maxValue) {
+    // align to the start of the largest unit
+    let aligned = date;
+    if (duration.years)
+        aligned = startOfYear(date);
+    else if (duration.months)
+        aligned = startOfMonth(date);
+    else if (duration.weeks || (duration.days && duration.days > 7))
+        aligned = startOfWeek(date, locale);
+    return constrainStart(date, aligned, duration, locale, minValue, maxValue);
+}
+export function alignEnd(date, duration, locale, minValue, maxValue) {
+    const d = { ...duration };
+    // subtract 1 from the smallest unit
+    if (d.days)
+        d.days--;
+    else if (d.weeks)
+        d.weeks--;
+    else if (d.months)
+        d.months--;
+    else if (d.years)
+        d.years--;
+    const aligned = alignStart(date, duration, locale).subtract(d);
+    return constrainStart(date, aligned, duration, locale, minValue, maxValue);
+}
+export function constrainStart(date, aligned, duration, locale, minValue, maxValue) {
+    if (minValue && date.compare(minValue) >= 0) {
+        const newDate = maxDate(aligned, alignStart(toCalendarDate(minValue), duration, locale));
+        if (newDate)
+            aligned = newDate;
+    }
+    if (maxValue && date.compare(maxValue) <= 0) {
+        const newDate = minDate(aligned, alignEnd(toCalendarDate(maxValue), duration, locale));
+        if (newDate)
+            aligned = newDate;
+    }
+    return aligned;
+}
+export function constrainValue(date, minValue, maxValue) {
+    if (minValue) {
+        const newDate = maxDate(date, toCalendarDate(minValue));
+        if (newDate)
+            date = newDate;
+    }
+    if (maxValue) {
+        const newDate = minDate(date, toCalendarDate(maxValue));
+        if (newDate)
+            date = newDate;
+    }
+    return date;
+}
+export function previousAvailableDate(date, minValue, isDateUnavailable) {
+    if (!isDateUnavailable)
+        return date;
+    while (date.compare(minValue) >= 0 && isDateUnavailable(date))
+        date = date.subtract({ days: 1 });
+    return date.compare(minValue) >= 0 ? date : null;
+}
+export function isEqualDuration(a, b) {
+    if (a === b)
+        return true;
+    return a.days === b.days && a.weeks === b.weeks && a.months === b.months && a.years === b.years;
+}
+function unitDuration(duration) {
+    const unit = { ...duration };
+    for (const key in duration)
+        unit[key] = 1;
+    return unit;
+}
+// ---------------------------------------------------------------------------------------------
+// Construction
+function displayCalendar(locale, createCalendar) {
+    const resolved = new DateFormatter(locale).resolvedOptions();
+    const id = (createCalendar ?? createAnyCalendar)(resolved.calendar).identifier;
+    return { id, timeZone: resolved.timeZone };
+}
+/** The display calendar of `state`. */
+export function getCalendar(state) {
+    return (state.createCalendar ?? createAnyCalendar)(state.calendar);
+}
+const toDisplay = (state, value) => {
+    const date = toCalendarDate(value);
+    return date.calendar.identifier === state.calendar && !state.createCalendar ? date : toCalendar(date, getCalendar(state));
+};
+/** Parse a display-calendar date string of the state. */
+export function readDate(state, text) {
+    return toDisplay(state, parseDateValue(text));
+}
+const writeDate = (date) => stringifyDateValue(toCalendar(date, new GregorianCalendar()));
+const parseInput = (value) => value == null ? null : typeof value === "string" ? parseDateValue(value) : value;
+function baseState(options, first, alignment, effectiveMin, effectiveMax) {
+    const locale = resolveLocale(options.locale);
+    const { id: calendar, timeZone: runtimeZone } = displayCalendar(locale, options.createCalendar);
+    const visibleDuration = options.visibleDuration ?? { months: 1 };
+    const timeZone = first && "timeZone" in first ? first.timeZone : runtimeZone;
+    const ctx = { calendar, createCalendar: options.createCalendar };
+    const minValue = toDateValueString(options.minValue), maxValue = toDateValueString(options.maxValue);
+    const focusedProp = options.focusedValue;
+    const { isDisabled: disabled, isReadOnly: readOnly, isInvalid: invalid } = options;
+    const defaultFocused = parseInput(isSignal(focusedProp) ? untrack(focusedProp) : (focusedProp ?? options.defaultFocusedValue));
+    const focusedDate = constrainValue(defaultFocused ? toDisplay(ctx, defaultFocused) : first ? toDisplay(ctx, first) : toCalendar(today(timeZone), getCalendar(ctx)), effectiveMin, effectiveMax);
+    const startDate = alignment === "start"
+        ? alignStart(focusedDate, visibleDuration, locale, effectiveMin, effectiveMax)
+        : alignment === "end"
+            ? alignEnd(focusedDate, visibleDuration, locale, effectiveMin, effectiveMax)
+            : alignCenter(focusedDate, visibleDuration, locale, effectiveMin, effectiveMax);
+    return {
+        id: options.id ?? createId(),
+        locale,
+        calendar,
+        ...(options.createCalendar ? { createCalendar: options.createCalendar } : {}),
+        timeZone,
+        visibleDuration,
+        pageBehavior: options.pageBehavior ?? "visible",
+        ...(options.firstDayOfWeek ? { firstDayOfWeek: options.firstDayOfWeek } : {}),
+        ...(options.weeksInMonth ? { weeksInMonth: options.weeksInMonth } : {}),
+        isDisabled: typeof disabled === "function" ? !!untrack(disabled) : (disabled ?? false),
+        isReadOnly: typeof readOnly === "function" ? !!untrack(readOnly) : (readOnly ?? false),
+        ...(typeof disabled === "function" ? { disabled } : {}),
+        ...(typeof readOnly === "function" ? { readOnly } : {}),
+        ...(typeof invalid === "function" ? { invalid } : {}),
+        invalidProp: (typeof invalid !== "function" && !!invalid) || options.validationState === "invalid",
+        minValue,
+        maxValue,
+        ...(options.onFocusChange ? { onFocusChange: options.onFocusChange } : {}),
+        isFocused: signal(options.autoFocus ?? false),
+        hoveredCell: signal(null),
+        pressedCell: signal(null),
+        focusVisibleCell: signal(null),
+        strings: getStringsForLocale(calendarMessages, locale),
+        focusedDate,
+        startDate,
+    };
+}
+/** `useCalendarState`: state of a Calendar (single or multiple selection). */
+export function createCalendarState(options = {}) {
+    const selectionMode = options.selectionMode ?? "single";
+    const valueProp = options.value;
+    const toText = (input) => Array.isArray(input) ? input.map((v) => toDateValueString(v)) : toDateValueString(input);
+    // A plain controlled value is the state's starting value (Rivet: the signal form is two-way).
+    const initial = isSignal(valueProp) ? untrack(valueProp) : valueProp !== undefined ? toText(valueProp) : toText(options.defaultValue);
+    const value = (isSignal(valueProp) ? valueProp : signal(initial ?? (selectionMode === "multiple" ? [] : null)));
+    const firstString = Array.isArray(initial) ? initial[0] : initial;
+    const first = firstString ? parseDateValue(firstString) : null;
+    const min = parseInput(options.minValue), max = parseInput(options.maxValue);
+    const { focusedDate, startDate, ...base } = baseState(options, first, options.selectionAlignment, min, max);
+    const state = {
+        ...base,
+        mode: "single",
+        selectionMode,
+        value,
+        focused: isSignal(options.focusedValue) ? options.focusedValue : signal(writeDate(focusedDate)),
+        start: signal(writeDate(startDate)),
+        focusControlled: isSignal(options.focusedValue),
+        ...(options.isDateUnavailable ? { isDateUnavailable: options.isDateUnavailable } : {}),
+        ...(options.onChange ? { onChange: options.onChange } : {}),
+    };
+    return state;
+}
+/** `useRangeCalendarState`: state of a RangeCalendar. */
+export function createRangeCalendarState(options = {}) {
+    const valueProp = options.value;
+    const toText = (range) => range ? { start: toDateValueString(range.start), end: toDateValueString(range.end) } : null;
+    // A plain controlled value is the state's starting value (Rivet: the signal form is two-way).
+    const initial = isSignal(valueProp) ? untrack(valueProp) : toText((valueProp !== undefined ? valueProp : options.defaultValue));
+    const value = isSignal(valueProp) ? valueProp : signal(initial);
+    const locale = resolveLocale(options.locale);
+    const visibleDuration = options.visibleDuration ?? { months: 1 };
+    const min = parseInput(options.minValue), max = parseInput(options.maxValue);
+    let alignment = "center";
+    if (initial && initial.start && initial.end) {
+        const start = alignCenter(toCalendarDate(parseDateValue(initial.start)), visibleDuration, locale, min, max);
+        const end = start.add(visibleDuration).subtract({ days: 1 });
+        if (parseDateValue(initial.end).compare(end) > 0)
+            alignment = "start";
+    }
+    const first = initial?.start ? parseDateValue(initial.start) : null;
+    const { focusedDate, startDate, ...base } = baseState({ ...options, locale }, first, options.selectionAlignment ?? alignment, min, max);
+    return {
+        ...base,
+        mode: "range",
+        value,
+        anchor: signal(null),
+        dragging: signal(false),
+        allowsNonContiguousRanges: options.allowsNonContiguousRanges ?? false,
+        focused: isSignal(options.focusedValue) ? options.focusedValue : signal(writeDate(focusedDate)),
+        start: signal(writeDate(startDate)),
+        focusControlled: isSignal(options.focusedValue),
+        ...(options.isDateUnavailable ? { rangeUnavailable: options.isDateUnavailable } : {}),
+        ...(options.onChange ? { onChange: options.onChange } : {}),
+    };
+}
+// ---------------------------------------------------------------------------------------------
+// Derived values (reactive reads)
+/** Props-level min (string → value). */
+export const minValueOf = (state) => (state.minValue ? parseDateValue(state.minValue) : null);
+export const maxValueOf = (state) => (state.maxValue ? parseDateValue(state.maxValue) : null);
+/** Range calendar: the anchor date. Reads `anchor`. */
+export function anchorDate(state) {
+    if (state.mode !== "range")
+        return null;
+    const anchor = state.anchor();
+    return anchor ? readDate(state, anchor) : null;
+}
+/** `isDateUnavailable` as the inner calendar sees it (range: bound to the anchor). Reads `anchor`. */
+export function unavailablePredicate(state) {
+    if (state.mode === "single")
+        return state.isDateUnavailable;
+    const fn = state.rangeUnavailable;
+    if (!fn)
+        return undefined;
+    const anchor = anchorDate(state);
+    return (date) => fn(date, anchor);
+}
+function nextUnavailableDate(anchor, isDateUnavailable, visibleDuration, dir) {
+    let nextDate = anchor.add({ days: dir });
+    const lo = anchor.subtract(visibleDuration), hi = anchor.add(visibleDuration);
+    while ((dir < 0 ? nextDate.compare(lo) >= 0 : nextDate.compare(hi) <= 0) && !isDateUnavailable(nextDate))
+        nextDate = nextDate.add({ days: dir });
+    if (isDateUnavailable(nextDate))
+        return nextDate.add({ days: -dir });
+    return undefined;
+}
+function availableRangeFor(state, anchor) {
+    const fn = state.rangeUnavailable;
+    if (anchor && fn && !state.allowsNonContiguousRanges) {
+        const isUnavailable = (date) => fn(date, anchor);
+        return {
+            start: nextUnavailableDate(anchor, isUnavailable, state.visibleDuration, -1),
+            end: nextUnavailableDate(anchor, isUnavailable, state.visibleDuration, 1),
+        };
+    }
+    return null;
+}
+/**
+ * Range calendar: the range available around the anchor. Reads `anchor` only when it can narrow
+ * anything (`isDateUnavailable` without `allowsNonContiguousRanges`): Rivet (resume) — a page button
+ * or grid reading it would otherwise be re-created on the first anchor change of a resumed page.
+ */
+export function availableRange(state) {
+    if (state.mode !== "range" || !state.rangeUnavailable || state.allowsNonContiguousRanges)
+        return null;
+    return availableRangeFor(state, anchorDate(state));
+}
+/** Effective min (range: narrowed to the available range). Reads `anchor`. */
+export function effectiveMin(state) {
+    const min = minValueOf(state);
+    if (state.mode !== "range")
+        return min;
+    return maxDate(min, availableRange(state)?.start) ?? null;
+}
+/** Effective max. Reads `anchor`. */
+export function effectiveMax(state) {
+    const max = maxValueOf(state);
+    if (state.mode !== "range")
+        return max;
+    return minDate(max, availableRange(state)?.end) ?? null;
+}
+/** The currently focused date (constrained to min / max). Reads `focused` (+ `anchor`). */
+export function focusedDate(state) {
+    return constrainValue(readDate(state, state.focused()), effectiveMin(state), effectiveMax(state));
+}
+function endFor(state, start) {
+    const duration = { ...state.visibleDuration };
+    if (duration.days)
+        duration.days--;
+    else
+        duration.days = -1;
+    return start.add(duration);
+}
+/** First visible date, corrected so the focused date is visible (React Stately's render-time correction). Reads `start`, `focused`. */
+function correctedStart(state) {
+    const start = readDate(state, state.start());
+    const focused = focusedDate(state);
+    const min = effectiveMin(state), max = effectiveMax(state);
+    if (focused.compare(start) < 0)
+        return alignEnd(focused, state.visibleDuration, state.locale, min, max);
+    if (focused.compare(endFor(state, start)) > 0)
+        return alignStart(focused, state.visibleDuration, state.locale, min, max);
+    return start;
+}
+/**
+ * First visible date. Rivet (resume): every focus write inside the calendar keeps `start` corrected
+ * (`syncStart`), so an uncontrolled focus reads `start` only; a `focusedValue` signal may be written from
+ * outside, so it reads the corrected start (`start`, `focused`). On a resumed page a binding wakes on the
+ * first change of any signal it read on the server (not the computed it read through): the grid rows,
+ * weekday header and page buttons depending on `focused` would be re-created on the first focus move /
+ * range anchor, replacing the focused cell.
+ */
+export function visibleStart(state) {
+    return state.focusControlled ? correctedStart(state) : readDate(state, state.start());
+}
+/** The date range that is currently visible. Reads `start` (+ `focused` when focus is controlled). */
+export function visibleRange(state) {
+    const start = visibleStart(state);
+    return { start, end: endFor(state, start) };
+}
+/** Selected value in the display calendar (single: date or null; multiple: dates; range: `{start, end}` of the value). Reads `value`. */
+export function calendarValue(state) {
+    const value = state.value();
+    if (Array.isArray(value))
+        return value.map((v) => toDisplay(state, parseDateValue(v)));
+    return value ? toDisplay(state, parseDateValue(value)) : null;
+}
+/** Range value in the display calendar. Reads `value`. */
+export function rangeValue(state) {
+    const value = state.value();
+    return value && value.start && value.end
+        ? { start: toDisplay(state, parseDateValue(value.start)), end: toDisplay(state, parseDateValue(value.end)) }
+        : null;
+}
+/** Range value as the original date values (calendar + time kept). Reads `value`. */
+export function rangeDateValue(state) {
+    const value = state.value();
+    return value && value.start && value.end ? { start: parseDateValue(value.start), end: parseDateValue(value.end) } : null;
+}
+function makeRange(start, end) {
+    if (!start || !end)
+        return null;
+    if (end.compare(start) < 0)
+        [start, end] = [end, start];
+    return { start: toCalendarDate(start), end: toCalendarDate(end) };
+}
+/** Range calendar: the highlighted range (anchor → focused while selecting, else the value). Reads `anchor`, `focused`, `value`. */
+export function highlightedRange(state) {
+    if (state.mode !== "range")
+        return null;
+    const anchor = anchorDate(state);
+    if (anchor)
+        return makeRange(anchor, focusedDate(state));
+    const value = rangeValue(state);
+    return value && makeRange(value.start, value.end);
+}
+/** Whether the calendar is disabled now (its live `isDisabled` accessor, else the creation value). Reads. */
+export const isCalendarDisabled = (state) => (state.disabled ? !!state.disabled() : state.isDisabled);
+/** Whether the calendar is read-only now. Reads. */
+export const isCalendarReadOnly = (state) => (state.readOnly ? !!state.readOnly() : state.isReadOnly);
+/** Whether the selection is invalid (unavailable / outside min-max, or `isInvalid`). */
+export function isValueInvalid(state) {
+    if (state.invalidProp || (state.invalid && state.invalid()))
+        return true;
+    const min = minValueOf(state), max = maxValueOf(state);
+    if (state.mode === "range") {
+        const value = rangeValue(state);
+        if (!value || hasAnchor(state))
+            return false;
+        const fn = unavailablePredicate(state);
+        if (fn && (fn(value.start) || fn(value.end)))
+            return true;
+        return isInvalid(value.start, min, max) || isInvalid(value.end, min, max);
+    }
+    const value = calendarValue(state);
+    if (!value)
+        return false;
+    const fn = state.isDateUnavailable;
+    if (Array.isArray(value))
+        return value.some((date) => fn?.(date) || isInvalid(date, min, max));
+    return !!fn?.(value) || isInvalid(value, min, max);
+}
+const hasAnchor = (state) => state.anchor() != null;
+/** Deprecated `validationState`. */
+export const validationState = (state) => (isValueInvalid(state) ? "invalid" : null);
+// ---------------------------------------------------------------------------------------------
+// Focus movement
+const peek = (fn) => untrack(fn);
+/** Write the focused date (+ the corrections React Stately applies on the next render). */
+function writeFocused(state, date) {
+    const previous = peek(() => readDate(state, state.focused()));
+    if (!isSameDay(previous, date) || previous.calendar.identifier !== date.calendar.identifier) {
+        state.focused.set(writeDate(date));
+        state.onFocusChange?.(date);
+    }
+    syncStart(state);
+}
+/** Keep `start` covering the focused date (React Stately's render-time correction). */
+function syncStart(state) {
+    const corrected = peek(() => writeDate(correctedStart(state)));
+    if (corrected !== peek(state.start))
+        state.start.set(corrected);
+}
+function focusCell(state, date) {
+    writeFocused(state, constrainValue(date, peek(() => effectiveMin(state)), peek(() => effectiveMax(state))));
+}
+/** Sets the focused date. */
+export const setFocusedDate = (state, date) => focusCell(state, date);
+/** Sets whether focus is within the calendar. */
+export const setFocused = (state, value) => {
+    state.isFocused.set(value);
+};
+/** Moves focus to the next calendar date. */
+export function focusNextDay(state) {
+    focusCell(state, peek(() => focusedDate(state)).add({ days: 1 }));
+}
+/** Moves focus to the previous calendar date. */
+export function focusPreviousDay(state) {
+    focusCell(state, peek(() => focusedDate(state)).subtract({ days: 1 }));
+}
+/** Moves focus to the next row of dates, e.g. the next week. */
+export function focusNextRow(state) {
+    const d = state.visibleDuration;
+    if (d.days)
+        focusNextPage(state);
+    else if (d.weeks || d.months || d.years)
+        focusCell(state, peek(() => focusedDate(state)).add({ weeks: 1 }));
+}
+/** Moves focus to the previous row of dates. */
+export function focusPreviousRow(state) {
+    const d = state.visibleDuration;
+    if (d.days)
+        focusPreviousPage(state);
+    else if (d.weeks || d.months || d.years)
+        focusCell(state, peek(() => focusedDate(state)).subtract({ weeks: 1 }));
+}
+const pageDuration = (state) => state.pageBehavior === "visible" ? state.visibleDuration : unitDuration(state.visibleDuration);
+function page(state, dir) {
+    const duration = pageDuration(state);
+    const { focused, startDate, min, max } = peek(() => ({
+        focused: focusedDate(state),
+        startDate: visibleStart(state),
+        min: effectiveMin(state),
+        max: effectiveMax(state),
+    }));
+    const start = dir > 0 ? startDate.add(duration) : startDate.subtract(duration);
+    const nextFocused = constrainValue(dir > 0 ? focused.add(duration) : focused.subtract(duration), min, max);
+    state.start.set(writeDate(alignStart(constrainStart(focused, start, duration, state.locale, min, max), duration, state.locale)));
+    writeFocused(state, nextFocused);
+}
+/** Moves focus to the next page of dates, e.g. the next month if one month is visible. */
+export const focusNextPage = (state) => page(state, 1);
+/** Moves focus to the previous page of dates. */
+export const focusPreviousPage = (state) => page(state, -1);
+/** Moves focus to the start of the current section of dates, e.g. the start of the current month. */
+export function focusSectionStart(state) {
+    const d = state.visibleDuration, focused = peek(() => focusedDate(state));
+    if (d.days)
+        focusCell(state, peek(() => visibleStart(state)));
+    else if (d.weeks)
+        focusCell(state, startOfWeek(focused, state.locale));
+    else if (d.months || d.years)
+        focusCell(state, startOfMonth(focused));
+}
+/** Moves focus to the end of the current section of dates. */
+export function focusSectionEnd(state) {
+    const d = state.visibleDuration, focused = peek(() => focusedDate(state));
+    if (d.days)
+        focusCell(state, peek(() => visibleRange(state).end));
+    else if (d.weeks)
+        focusCell(state, endOfWeek(focused, state.locale));
+    else if (d.months || d.years)
+        focusCell(state, endOfMonth(focused));
+}
+/** Moves focus to the next section (one displayed unit, or the next larger unit with `larger`). */
+export function focusNextSection(state, larger) {
+    const d = state.visibleDuration, focused = peek(() => focusedDate(state));
+    if (!larger && !d.days)
+        return focusCell(state, focused.add(unitDuration(d)));
+    if (d.days)
+        focusNextPage(state);
+    else if (d.weeks)
+        focusCell(state, focused.add({ months: 1 }));
+    else if (d.months || d.years)
+        focusCell(state, focused.add({ years: 1 }));
+}
+/** Moves focus to the previous section. */
+export function focusPreviousSection(state, larger) {
+    const d = state.visibleDuration, focused = peek(() => focusedDate(state));
+    if (!larger && !d.days)
+        return focusCell(state, focused.subtract(unitDuration(d)));
+    if (d.days)
+        focusPreviousPage(state);
+    else if (d.weeks)
+        focusCell(state, focused.subtract({ months: 1 }));
+    else if (d.months || d.years)
+        focusCell(state, focused.subtract({ years: 1 }));
+}
+// ---------------------------------------------------------------------------------------------
+// Selection
+function originalCalendarOf(state) {
+    const raw = peek(state.value);
+    const first = Array.isArray(raw) ? raw[0] : raw;
+    return first ? parseDateValue(first) : null;
+}
+/** Emit `date` in the calendar of the original value (default Gregorian), keeping its time. */
+function convertValue(date, oldValue) {
+    const converted = toCalendar(date, oldValue?.calendar || new GregorianCalendar());
+    if (oldValue && "hour" in oldValue)
+        return oldValue.set(converted);
+    return converted;
+}
+function normalizeValue(state, newValue) {
+    const { min, max, startDate } = peek(() => ({ min: effectiveMin(state), max: effectiveMax(state), startDate: visibleStart(state) }));
+    const constrained = constrainValue(newValue, min, max);
+    const lowerBound = min ?? minDate(constrained, startDate);
+    const prev = previousAvailableDate(constrained, lowerBound, state.isDateUnavailable);
+    if (!prev)
+        return null;
+    return convertValue(prev, originalCalendarOf(state));
+}
+function emit(state, next) {
+    const before = peek(state.value);
+    const text = Array.isArray(next) ? next.map((v) => stringifyDateValue(v)) : stringifyDateValue(next);
+    if (next === null && (before === null || (Array.isArray(before) && before.length === 0 && Array.isArray(text))))
+        return;
+    // A read-only accessor (live controlled `value`, string form) is never written: only `onChange` reports.
+    if (isWritable(state.value))
+        state.value.set(text);
+    state.onChange?.(next);
+}
+/** Sets the selected value (React Stately `setValue`). */
+export function setValue(state, newValue) {
+    if (isCalendarDisabled(state) || isCalendarReadOnly(state))
+        return;
+    if (newValue === null)
+        return emit(state, state.selectionMode === "multiple" ? [] : null);
+    if (Array.isArray(newValue))
+        emit(state, newValue.map((d) => normalizeValue(state, d)).filter((v) => !!v));
+    else {
+        const local = normalizeValue(state, newValue);
+        if (local)
+            emit(state, local);
+    }
+}
+/** Selects the given date (range: anchors or completes the range). */
+export function selectDate(state, date) {
+    if (state.mode === "range")
+        return selectRangeDate(state, date);
+    if (isCalendarDisabled(state) || isCalendarReadOnly(state))
+        return;
+    if (state.selectionMode === "multiple" && date != null) {
+        const newDate = normalizeValue(state, date);
+        if (!newDate)
+            return;
+        const raw = peek(state.value);
+        const base = Array.isArray(raw) ? raw.map((v) => parseDateValue(v)) : raw != null ? [parseDateValue(raw)] : [];
+        const index = base.findIndex((value) => isSameDay(value, newDate));
+        emit(state, index >= 0 ? base.slice(0, index).concat(base.slice(index + 1)) : [...base, newDate]);
+    }
+    else
+        setValue(state, date);
+}
+/** Selects the currently focused date (unless unavailable). */
+export function selectFocusedDate(state) {
+    const focused = peek(() => focusedDate(state));
+    if (state.mode === "range") {
+        if (!peek(() => isCellUnavailable(state, focused)))
+            selectRangeDate(state, focused);
+        return;
+    }
+    if (!(state.isDateUnavailable && state.isDateUnavailable(focused)))
+        selectDate(state, focused);
+}
+// Range selection ------------------------------------------------------------------------------
+function selectRangeDate(state, date) {
+    if (isCalendarReadOnly(state))
+        return;
+    const { min, max, startDate, unavailable, anchor } = peek(() => ({
+        min: effectiveMin(state),
+        max: effectiveMax(state),
+        startDate: visibleStart(state),
+        unavailable: unavailablePredicate(state),
+        anchor: anchorDate(state),
+    }));
+    const constrainedDate = constrainValue(date, min, max);
+    const previous = previousAvailableDate(constrainedDate, startDate, unavailable);
+    if (!previous)
+        return;
+    if (!anchor)
+        setAnchorDate(state, previous);
+    else {
+        const range = makeRange(anchor, previous);
+        if (range) {
+            const old = peek(() => rangeDateValue(state));
+            const next = { start: convertValue(range.start, old?.start), end: convertValue(range.end, old?.end) };
+            if (isWritable(state.value))
+                state.value.set({ start: stringifyDateValue(next.start), end: stringifyDateValue(next.end) });
+            state.onChange?.(next);
+        }
+        setAnchorDate(state, null);
+    }
+}
+/** Sets the range selection anchor. */
+export function setAnchorDate(state, date) {
+    if (state.mode !== "range")
+        return;
+    state.anchor.set(date ? writeDate(date) : null);
+    // Effective min / max follow the anchor: re-apply the focus constraints.
+    const focused = peek(() => focusedDate(state));
+    writeFocused(state, focused);
+}
+/** Range: sets the value (React Stately `setValue`). */
+export function setRangeValue(state, value) {
+    if (isWritable(state.value))
+        state.value.set(value ? { start: stringifyDateValue(value.start), end: stringifyDateValue(value.end) } : null);
+    state.onChange?.(value);
+}
+/** Highlights the given date during range selection (hover / drag). */
+export function highlightDate(state, date) {
+    if (state.mode === "range" && peek(state.anchor))
+        setFocusedDate(state, date);
+}
+/** Commits the current selection (selects the focused date). */
+export function commitSelection(state) {
+    if (state.mode === "range")
+        selectRangeDate(state, peek(() => focusedDate(state)));
+}
+/** Clears the current selection. */
+export function clearSelection(state) {
+    if (state.mode !== "range")
+        return;
+    setAnchorDate(state, null);
+    setRangeValue(state, null);
+}
+/** Sets whether the user is dragging over the calendar. */
+export function setDragging(state, value) {
+    if (state.mode === "range")
+        state.dragging.set(value);
+}
+/** Focuses the next available day before or after `anchor`. */
+export function focusNearestAvailableDate(state, anchor) {
+    if (state.mode !== "range")
+        return;
+    const range = availableRangeFor(state, anchor);
+    const isDateInvalid = (date) => peek(() => isInvalidDate(state, date)) || isInvalid(date, range?.start, range?.end);
+    let nextDay = anchor.add({ days: 1 });
+    if (isDateInvalid(nextDay))
+        nextDay = anchor.subtract({ days: 1 });
+    if (!isDateInvalid(nextDay)) {
+        setFocusedDate(state, nextDay);
+        setFocused(state, true);
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Cell queries (reactive reads)
+/** Whether the date is outside min / max (range: also outside the available range). */
+export function isInvalidDate(state, date) {
+    const invalid = isInvalid(date, effectiveMin(state), effectiveMax(state));
+    if (state.mode !== "range")
+        return invalid;
+    const range = availableRange(state);
+    return invalid || isInvalid(date, range?.start, range?.end);
+}
+/** Whether the date is currently selected. */
+export function isSelected(state, date) {
+    if (state.mode === "range") {
+        const range = highlightedRange(state);
+        return Boolean(range && date.compare(range.start) >= 0 && date.compare(range.end) <= 0 && !isCellDisabled(state, date) && !isCellUnavailable(state, date));
+    }
+    const value = calendarValue(state);
+    if (!value || isCellDisabled(state, date) || isCellUnavailable(state, date))
+        return false;
+    return Array.isArray(value) ? value.some((v) => isSameDay(v, date)) : isSameDay(date, value);
+}
+/** Whether the date is focused (focus within the grid). */
+export function isCellFocused(state, date) {
+    return state.isFocused() && isSameDay(date, focusedDate(state));
+}
+/** Whether the date is disabled (min / max, outside the visible range, or `isDisabled`). */
+export function isCellDisabled(state, date) {
+    const range = visibleRange(state);
+    // The range calendar's base cells use the base `isInvalid` (min / max narrowed by the anchor).
+    const invalid = isInvalid(date, effectiveMin(state), effectiveMax(state));
+    return isCalendarDisabled(state) || date.compare(range.start) < 0 || date.compare(range.end) > 0 || invalid;
+}
+/** Whether the date is unavailable (`isDateUnavailable`). */
+export function isCellUnavailable(state, date) {
+    const fn = unavailablePredicate(state);
+    return fn ? fn(date) : false;
+}
+/** Whether the previous visible range is out of bounds. */
+export function isPreviousVisibleRangeInvalid(state) {
+    const start = visibleRange(state).start;
+    const prev = start.subtract({ days: 1 });
+    return isSameDay(prev, start) || isInvalidDate(state, prev);
+}
+/** Whether the next visible range is out of bounds. */
+export function isNextVisibleRangeInvalid(state) {
+    const end = visibleRange(state).end;
+    // Adding may return the same date if we reached the end of time (e.g. 9999-12-31).
+    const next = end.add({ days: 1 });
+    return isSameDay(next, end) || isInvalidDate(state, next);
+}
+/** Dates in week `weekIndex` from `from` (default: the first visible date); null where the calendar system has no date. */
+export function getDatesInWeek(state, weekIndex, from) {
+    let date = (from ?? visibleStart(state)).add({ weeks: weekIndex });
+    const dates = [];
+    const d = state.visibleDuration;
+    const days = d.days && d.days < 7 ? d.days : 7;
+    if (days === 7) {
+        date = startOfWeek(date, state.locale, state.firstDayOfWeek);
+        // startOfWeek clamps within the calendar system's range, which may start mid-week.
+        const dayOfWeek = getDayOfWeek(date, state.locale, state.firstDayOfWeek);
+        for (let i = 0; i < dayOfWeek; i++)
+            dates.push(null);
+    }
+    while (dates.length < days) {
+        dates.push(date);
+        const nextDate = date.add({ days: 1 });
+        if (isSameDay(date, nextDate))
+            break; // end of the calendar system
+        date = nextDate;
+    }
+    while (dates.length < days)
+        dates.push(null);
+    return dates;
+}
+/** Number of weeks displayed for the month of `from` (default: the first visible date). */
+export function getWeeksInMonth(state, from) {
+    let weeks = state.weeksInMonth || weeksIn(from ?? visibleStart(state), state.locale, state.firstDayOfWeek);
+    const d = state.visibleDuration;
+    if (d.weeks || d.days) {
+        weeks = d.weeks ?? 0;
+        if (d.days)
+            weeks += Math.ceil(d.days / 7);
+    }
+    return weeks;
+}
+/** Format a localized string of the calendar. */
+export const message = (state, key, variables) => formatString(state.strings[key], variables);
+export { CalendarDate };