@marianmeres/stuic 3.170.0 → 3.172.0

package/dist/components/Calendar/index.css

@@ -0,0 +1,307 @@
+/* ============================================================================
+   CALENDAR COMPONENT TOKENS
+   Override globally: :root { --stuic-calendar-day-size: 3rem; }
+   Override locally:  <Calendar style="--stuic-calendar-day-radius: 9999px;">
+   ============================================================================ */
+
+/* prettier-ignore */
+:root {
+	--stuic-calendar-bg: transparent;
+	--stuic-calendar-text: var(--stuic-color-foreground);
+	--stuic-calendar-font-family: var(--font-sans);
+
+	/* Layout */
+	--stuic-calendar-gap: 1.5rem;             /* between months (`months > 1`) */
+	--stuic-calendar-header-gap: 0.25rem;
+	--stuic-calendar-header-margin-bottom: 0.5rem;
+	--stuic-calendar-footer-gap: 0.5rem;
+	--stuic-calendar-footer-margin-top: 0.5rem;
+
+	/* Day cell (min 44px on touch, see below) */
+	--stuic-calendar-day-size: 2.5rem;
+	--stuic-calendar-day-font-size: var(--text-sm);
+	--stuic-calendar-day-font-weight: var(--font-weight-normal);
+	--stuic-calendar-day-text: var(--stuic-color-foreground);
+	--stuic-calendar-day-bg-hover: var(--stuic-color-muted);
+	--stuic-calendar-day-text-outside: var(--stuic-color-muted-foreground);
+	--stuic-calendar-day-opacity-outside: 0.6;
+	--stuic-calendar-day-opacity-disabled: 0.35;
+
+	/* Selection */
+	--stuic-calendar-day-bg-selected: var(--stuic-color-primary);
+	--stuic-calendar-day-text-selected: var(--stuic-color-primary-foreground);
+	--stuic-calendar-day-bg-selected-hover: var(--stuic-color-primary-hover, var(--stuic-color-primary));
+	--stuic-calendar-day-bg-range: color-mix(in oklab, var(--stuic-color-primary) 15%, transparent);
+	--stuic-calendar-day-text-range: var(--stuic-color-foreground);
+	--stuic-calendar-day-bg-preview: color-mix(in oklab, var(--stuic-color-primary) 8%, transparent);
+
+	/* Today */
+	--stuic-calendar-today-text: var(--stuic-color-primary);
+	--stuic-calendar-today-font-weight: var(--font-weight-semibold);
+
+	/* Weekday header row + week-number column */
+	--stuic-calendar-weekday-text: var(--stuic-color-muted-foreground);
+	--stuic-calendar-weekday-font-size: var(--text-xs);
+	--stuic-calendar-weekday-font-weight: var(--font-weight-medium);
+	--stuic-calendar-week-number-text: var(--stuic-color-muted-foreground);
+	--stuic-calendar-week-number-font-size: var(--text-xs);
+
+	/* Caption (month + year) */
+	--stuic-calendar-caption-text: var(--stuic-color-foreground);
+	--stuic-calendar-caption-font-size: var(--text-base);
+	--stuic-calendar-caption-font-weight: var(--font-weight-semibold);
+
+	/* Caption dropdowns (`captionLayout="dropdown"`) */
+	--stuic-calendar-select-bg: var(--stuic-color-input, transparent);
+	--stuic-calendar-select-text: var(--stuic-color-foreground);
+	--stuic-calendar-select-border: var(--stuic-color-border);
+
+	/* Focus ring */
+	--stuic-calendar-ring-width: 2px;
+	--stuic-calendar-ring-color: var(--stuic-color-ring);
+}
+
+/* Touch: keep every day a comfortable 44px target */
+@media (pointer: coarse) {
+	:root {
+		--stuic-calendar-day-size: 2.75rem;
+	}
+}
+
+@layer components {
+	/* ============================================================================
+	   ROOT
+	   ============================================================================ */
+
+	.stuic-calendar {
+		display: inline-flex;
+		flex-direction: column;
+		max-width: 100%;
+		background: var(--stuic-calendar-bg);
+		color: var(--stuic-calendar-text);
+		font-family: var(--stuic-calendar-font-family);
+		user-select: none;
+		-webkit-user-select: none;
+	}
+
+	.stuic-calendar[data-disabled] {
+		opacity: 0.6;
+		cursor: not-allowed;
+	}
+
+	.stuic-calendar-months {
+		display: flex;
+		flex-wrap: wrap;
+		gap: var(--stuic-calendar-gap);
+		max-width: 100%;
+	}
+
+	.stuic-calendar-month {
+		display: flex;
+		flex-direction: column;
+		max-width: 100%;
+	}
+
+	/* ============================================================================
+	   HEADER (prev | caption | next)
+	   ============================================================================ */
+
+	.stuic-calendar-header {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: var(--stuic-calendar-header-gap);
+		margin-bottom: var(--stuic-calendar-header-margin-bottom);
+	}
+
+	.stuic-calendar-caption {
+		flex: 1;
+		min-width: 0;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		gap: 0.25rem;
+		text-align: center;
+		color: var(--stuic-calendar-caption-text);
+		font-size: var(--stuic-calendar-caption-font-size);
+		font-weight: var(--stuic-calendar-caption-font-weight);
+		line-height: 1.25;
+	}
+
+	/* keeps the caption centered on months without a prev/next button */
+	.stuic-calendar-nav-placeholder {
+		display: inline-block;
+		width: 2.75rem;
+		flex-shrink: 0;
+	}
+
+	.stuic-calendar-select {
+		appearance: auto;
+		font: inherit;
+		font-size: var(--text-sm);
+		font-weight: var(--stuic-calendar-caption-font-weight);
+		color: var(--stuic-calendar-select-text);
+		background: var(--stuic-calendar-select-bg);
+		border: var(--stuic-calendar-border-width, var(--stuic-border-width)) solid
+			var(--stuic-calendar-select-border);
+		border-radius: var(--stuic-calendar-select-radius, var(--stuic-radius));
+		padding: 0.25rem 0.5rem;
+		max-width: 100%;
+		min-width: 0;
+		cursor: pointer;
+	}
+
+	.stuic-calendar-select:focus-visible {
+		outline: var(--stuic-calendar-ring-width) solid var(--stuic-calendar-ring-color);
+		outline-offset: 1px;
+	}
+
+	/* ============================================================================
+	   GRID
+	   ============================================================================ */
+
+	.stuic-calendar-grid {
+		border-collapse: separate;
+		border-spacing: 0;
+		table-layout: fixed;
+		width: auto;
+	}
+
+	.stuic-calendar-weekday {
+		width: var(--stuic-calendar-day-size);
+		padding: 0 0 0.25rem;
+		text-align: center;
+		color: var(--stuic-calendar-weekday-text);
+		font-size: var(--stuic-calendar-weekday-font-size);
+		font-weight: var(--stuic-calendar-weekday-font-weight);
+		text-transform: none;
+	}
+
+	.stuic-calendar-week-number {
+		width: var(--stuic-calendar-day-size);
+		padding: 0 0.25rem 0 0;
+		text-align: center;
+		vertical-align: middle;
+		color: var(--stuic-calendar-week-number-text);
+		font-size: var(--stuic-calendar-week-number-font-size);
+		font-variant-numeric: tabular-nums;
+	}
+
+	.stuic-calendar-cell {
+		width: var(--stuic-calendar-day-size);
+		height: var(--stuic-calendar-day-size);
+		padding: 0;
+		text-align: center;
+		vertical-align: middle;
+	}
+
+	/* Range band: painted on the CELL so it runs edge to edge between days */
+	.stuic-calendar-cell[data-in-range] {
+		background: var(--stuic-calendar-day-bg-range);
+	}
+
+	.stuic-calendar-cell[data-preview]:not([data-in-range]) {
+		background: var(--stuic-calendar-day-bg-preview);
+	}
+
+	.stuic-calendar-cell[data-range-start] {
+		border-start-start-radius: var(--stuic-calendar-day-radius, var(--stuic-radius));
+		border-end-start-radius: var(--stuic-calendar-day-radius, var(--stuic-radius));
+	}
+
+	.stuic-calendar-cell[data-range-end] {
+		border-start-end-radius: var(--stuic-calendar-day-radius, var(--stuic-radius));
+		border-end-end-radius: var(--stuic-calendar-day-radius, var(--stuic-radius));
+	}
+
+	/* ============================================================================
+	   DAY BUTTON
+	   ============================================================================ */
+
+	.stuic-calendar-day {
+		position: relative;
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 100%;
+		height: var(--stuic-calendar-day-size);
+		margin: 0;
+		padding: 0;
+		border: 0;
+		background: transparent;
+		color: var(--stuic-calendar-day-text);
+		font: inherit;
+		font-size: var(--stuic-calendar-day-font-size);
+		font-weight: var(--stuic-calendar-day-font-weight);
+		font-variant-numeric: tabular-nums;
+		line-height: 1;
+		border-radius: var(--stuic-calendar-day-radius, var(--stuic-radius));
+		cursor: pointer;
+		-webkit-tap-highlight-color: transparent;
+		transition:
+			background var(--stuic-calendar-transition, var(--stuic-transition)),
+			color var(--stuic-calendar-transition, var(--stuic-transition));
+	}
+
+	.stuic-calendar-day:hover:not([aria-disabled="true"]):not([data-selected]) {
+		background: var(--stuic-calendar-day-bg-hover);
+	}
+
+	.stuic-calendar-day:focus-visible {
+		outline: var(--stuic-calendar-ring-width) solid var(--stuic-calendar-ring-color);
+		outline-offset: -1px;
+		z-index: 1;
+	}
+
+	.stuic-calendar-day[data-outside] {
+		color: var(--stuic-calendar-day-text-outside);
+		opacity: var(--stuic-calendar-day-opacity-outside);
+	}
+
+	.stuic-calendar-day[data-weekend] {
+		color: var(--stuic-calendar-day-text-weekend, var(--stuic-calendar-day-text));
+	}
+
+	.stuic-calendar-day[data-today] {
+		color: var(--stuic-calendar-today-text);
+		font-weight: var(--stuic-calendar-today-font-weight);
+	}
+
+	.stuic-calendar-day[data-in-range] {
+		color: var(--stuic-calendar-day-text-range);
+	}
+
+	.stuic-calendar-day[data-selected] {
+		background: var(--stuic-calendar-day-bg-selected);
+		color: var(--stuic-calendar-day-text-selected);
+		opacity: 1;
+	}
+
+	.stuic-calendar-day[data-selected]:hover:not([aria-disabled="true"]) {
+		background: var(--stuic-calendar-day-bg-selected-hover);
+	}
+
+	.stuic-calendar-day[aria-disabled="true"] {
+		opacity: var(--stuic-calendar-day-opacity-disabled);
+		cursor: not-allowed;
+	}
+
+	/* ============================================================================
+	   FOOTER
+	   ============================================================================ */
+
+	.stuic-calendar-footer {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		flex-wrap: wrap;
+		gap: var(--stuic-calendar-footer-gap);
+		margin-top: var(--stuic-calendar-footer-margin-top);
+	}
+
+	.stuic-calendar-footer-actions {
+		display: flex;
+		align-items: center;
+		gap: var(--stuic-calendar-footer-gap);
+	}
+}

package/dist/components/Calendar/index.d.ts

@@ -0,0 +1,5 @@
+export { default as Calendar, type Props as CalendarProps, type CalendarMode, type CalendarCaptionLayout, type CalendarDayState, type CalendarRangeChange, } from "./Calendar.svelte";
+export { createCalendarT, CALENDAR_MESSAGES_EN, type CalendarMessageKey, type CalendarMessages, } from "./calendar-i18n.js";
+export { CALENDAR_MESSAGES_SK } from "./calendar-i18n-sk.js";
+export { type IsoDate, type IsoDateParts, type YearMonth, isIsoDate, parseIsoDate, normalizeIsoDate, toIsoDate, todayIso, addDaysIso, addMonthsIso, compareIso, daysBetweenIso, rangeLengthIso, formatIsoDate, formatIsoDateRange, DEFAULT_DATE_FORMAT, } from "./iso-date.js";
+export type { DayCell as CalendarDayCell, Weekday as CalendarWeekday, } from "@marianmeres/calendar-utils";

package/dist/components/Calendar/index.js

@@ -0,0 +1,5 @@
+export { default as Calendar, } from "./Calendar.svelte";
+export { createCalendarT, CALENDAR_MESSAGES_EN, } from "./calendar-i18n.js";
+// Opt-in locale: only bundled when imported (the components never reference it).
+export { CALENDAR_MESSAGES_SK } from "./calendar-i18n-sk.js";
+export { isIsoDate, parseIsoDate, normalizeIsoDate, toIsoDate, todayIso, addDaysIso, addMonthsIso, compareIso, daysBetweenIso, rangeLengthIso, formatIsoDate, formatIsoDateRange, DEFAULT_DATE_FORMAT, } from "./iso-date.js";

package/dist/components/Calendar/iso-date.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Pure `YYYY-MM-DD` helpers shared by `Calendar`, `FieldDate` and `FieldDateRange`.
+ *
+ * Every date value these components bind, emit and submit is a calendar date in
+ * ISO `YYYY-MM-DD` form — zone-independent, lexicographically sortable, and what
+ * `<input type="date">` and most APIs already speak. The day arithmetic goes
+ * through `@marianmeres/calendar-utils` (DST-safe, any year); the formatting
+ * through `Intl`.
+ */
+import { type DayCell, type GridConfig, type Weekday } from "@marianmeres/calendar-utils";
+/** A calendar date as `YYYY-MM-DD` — the value type of every date component in stuic. */
+export type IsoDate = string;
+/** A `{ year, month }` pair, month 1–12 (the `view` of a `Calendar`). */
+export interface YearMonth {
+    year: number;
+    month: number;
+}
+/** The three calendar fields of an `IsoDate`. */
+export interface IsoDateParts {
+    year: number;
+    month: number;
+    day: number;
+}
+/** Number of days in `month` (1–12) of `year`, proleptic Gregorian. */
+export declare function daysInMonth(year: number, month: number): number;
+/** Zero-padded `YYYY-MM-DD` from its parts. Does not validate. */
+export declare function toIsoDate(year: number, month: number, day: number): IsoDate;
+/**
+ * Parses a strict `YYYY-MM-DD` string into its parts. Returns `null` for anything
+ * else, including well-formed but impossible dates (`2026-02-30`).
+ */
+export declare function parseIsoDate(iso: unknown): IsoDateParts | null;
+/** `true` for a strict, valid `YYYY-MM-DD`. */
+export declare function isIsoDate(v: unknown): v is IsoDate;
+/**
+ * Coerces the loose inputs a consumer may hand to a date field into a strict
+ * `IsoDate`, or `null` when that is not possible:
+ *
+ * - `"2026-09-02"` → as is
+ * - `"2026-09-02T10:00:00Z"` / `"2026-09-02 10:00"` → the date portion **as written**
+ *   (never shifted through a zone — a date field has no time-of-day to shift)
+ * - `Date` → its **local** calendar date
+ * - Luxon `DateTime` → its calendar date in its own zone
+ * - `null` / `undefined` / `""` / anything unparseable → `null`
+ */
+export declare function normalizeIsoDate(v: unknown): IsoDate | null;
+/** Today's calendar date in `zone` (IANA, default local). */
+export declare function todayIso(zone?: string): IsoDate;
+/** `iso + days` calendar days (negative allowed). DST-immune. */
+export declare function addDaysIso(iso: IsoDate, days: number): IsoDate;
+/** `iso + months`; the day of month is clamped (Jan 31 + 1 → Feb 28/29). */
+export declare function addMonthsIso(iso: IsoDate, months: number): IsoDate;
+/** Sort comparator for `IsoDate`s (`-1`, `0`, `1`). */
+export declare function compareIso(a: IsoDate, b: IsoDate): number;
+/** Whole calendar days from `a` to `b` (positive when `b` is later). */
+export declare function daysBetweenIso(a: IsoDate, b: IsoDate): number;
+/** The two dates in chronological order. */
+export declare function orderedRange(a: IsoDate, b: IsoDate): [IsoDate, IsoDate];
+/** Inclusive day count of a range (`1` for a single-day range). */
+export declare function rangeLengthIso(start: IsoDate, end: IsoDate): number;
+/** Inclusive `start <= iso <= end`. */
+export declare function isWithinRange(iso: IsoDate, start: IsoDate, end: IsoDate): boolean;
+/** `min <= iso <= max`, each bound optional. */
+export declare function isWithinBounds(iso: IsoDate, min?: IsoDate | null, max?: IsoDate | null): boolean;
+/** `iso` clamped into `[min, max]` (each bound optional). */
+export declare function clampIso(iso: IsoDate, min?: IsoDate | null, max?: IsoDate | null): IsoDate;
+/** The `{ year, month }` an `IsoDate` falls in. */
+export declare function yearMonthOf(iso: IsoDate): YearMonth;
+/** Sort comparator for `YearMonth`s. */
+export declare function compareYearMonth(a: YearMonth, b: YearMonth): number;
+/** `ym + months` (negative allowed, crosses years). */
+export declare function addMonths(ym: YearMonth, months: number): YearMonth;
+/** `YYYY-MM-01` of a `YearMonth`. */
+export declare function firstOfMonth(ym: YearMonth): IsoDate;
+/** Stable string key of a `YearMonth` (`"2026-09"`). */
+export declare function yearMonthKey(ym: YearMonth): string;
+/** Column index (0–6) of `iso` in a week that starts on `weekStartsOn`. */
+export declare function weekdayColumn(iso: IsoDate, weekStartsOn?: Weekday): number;
+/**
+ * The month grid for a `YearMonth` — `createMonthGrid` from calendar-utils (5 or 6
+ * weeks), optionally padded to a fixed 6 weeks so the UI height never jumps while
+ * navigating.
+ */
+export declare function buildMonthGrid(ym: YearMonth, config?: GridConfig, fixedWeeks?: boolean): DayCell[][];
+/** Default `Intl` options of the date fields' display text. */
+export declare const DEFAULT_DATE_FORMAT: Intl.DateTimeFormatOptions;
+/**
+ * Formats an `IsoDate` for display with `Intl.DateTimeFormat` (medium date style by
+ * default). Invalid input renders as `""`.
+ */
+export declare function formatIsoDate(iso: IsoDate | null | undefined, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Formats an inclusive date range — via `Intl.DateTimeFormat#formatRange` where the
+ * runtime has it ("Sep 1 – 5, 2026"), else the two dates joined by `separator`.
+ */
+export declare function formatIsoDateRange(start: IsoDate, end: IsoDate, locale?: string, options?: Intl.DateTimeFormatOptions, separator?: string): string;
+/** "September 2026" (localized) for a `YearMonth`. */
+export declare function formatYearMonth(ym: YearMonth, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+/** The 12 localized month names, January first. */
+export declare function getMonthNames(locale?: string, format?: "long" | "short" | "narrow"): string[];
+/** Full spoken form of a date ("Wednesday, September 2, 2026") — for `aria-label`s. */
+export declare function formatIsoDateLong(iso: IsoDate, locale?: string): string;
+/**
+ * A calendar-utils `DayCell` for a single date — what `isDateDisabled` receives
+ * when the date fields validate a value outside of any rendered grid.
+ */
+export declare function dayCellOf(iso: IsoDate, config?: GridConfig): DayCell;

package/dist/components/Calendar/iso-date.js

@@ -0,0 +1,247 @@
+/**
+ * Pure `YYYY-MM-DD` helpers shared by `Calendar`, `FieldDate` and `FieldDateRange`.
+ *
+ * Every date value these components bind, emit and submit is a calendar date in
+ * ISO `YYYY-MM-DD` form — zone-independent, lexicographically sortable, and what
+ * `<input type="date">` and most APIs already speak. The day arithmetic goes
+ * through `@marianmeres/calendar-utils` (DST-safe, any year); the formatting
+ * through `Intl`.
+ */
+import { DateTime, addDays as addDaysDt, calendarDaysBetween, createDayCell, createMonthGrid, getAdjustedWeekday, } from "@marianmeres/calendar-utils";
+const ISO_DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+// `YYYY-MM-DD` optionally followed by a time part (`T…` / ` …`) — the date portion
+// AS WRITTEN is used (iCalendar `VALUE=DATE` semantics, same as calendar-utils
+// all-day events), never converted through a zone.
+const ISO_DATE_PREFIX_RE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ]|$)/;
+/** Number of days in `month` (1–12) of `year`, proleptic Gregorian. */
+export function daysInMonth(year, month) {
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    return [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] ?? 0;
+}
+/** Zero-padded `YYYY-MM-DD` from its parts. Does not validate. */
+export function toIsoDate(year, month, day) {
+    const y = `${Math.abs(year)}`.padStart(4, "0");
+    return `${year < 0 ? "-" : ""}${y}-${`${month}`.padStart(2, "0")}-${`${day}`.padStart(2, "0")}`;
+}
+/**
+ * Parses a strict `YYYY-MM-DD` string into its parts. Returns `null` for anything
+ * else, including well-formed but impossible dates (`2026-02-30`).
+ */
+export function parseIsoDate(iso) {
+    if (typeof iso !== "string")
+        return null;
+    const m = ISO_DATE_RE.exec(iso);
+    if (!m)
+        return null;
+    const year = Number(m[1]);
+    const month = Number(m[2]);
+    const day = Number(m[3]);
+    if (month < 1 || month > 12)
+        return null;
+    if (day < 1 || day > daysInMonth(year, month))
+        return null;
+    return { year, month, day };
+}
+/** `true` for a strict, valid `YYYY-MM-DD`. */
+export function isIsoDate(v) {
+    return parseIsoDate(v) !== null;
+}
+/**
+ * Coerces the loose inputs a consumer may hand to a date field into a strict
+ * `IsoDate`, or `null` when that is not possible:
+ *
+ * - `"2026-09-02"` → as is
+ * - `"2026-09-02T10:00:00Z"` / `"2026-09-02 10:00"` → the date portion **as written**
+ *   (never shifted through a zone — a date field has no time-of-day to shift)
+ * - `Date` → its **local** calendar date
+ * - Luxon `DateTime` → its calendar date in its own zone
+ * - `null` / `undefined` / `""` / anything unparseable → `null`
+ */
+export function normalizeIsoDate(v) {
+    if (v === null || v === undefined || v === "")
+        return null;
+    if (v instanceof Date) {
+        return Number.isNaN(v.getTime())
+            ? null
+            : toIsoDate(v.getFullYear(), v.getMonth() + 1, v.getDate());
+    }
+    if (DateTime.isDateTime(v))
+        return v.isValid ? v.toISODate() : null;
+    if (typeof v !== "string")
+        return null;
+    const m = ISO_DATE_PREFIX_RE.exec(v.trim());
+    if (!m)
+        return null;
+    const iso = `${m[1]}-${m[2]}-${m[3]}`;
+    return isIsoDate(iso) ? iso : null;
+}
+/** Today's calendar date in `zone` (IANA, default local). */
+export function todayIso(zone = "local") {
+    const now = DateTime.now().setZone(zone);
+    return (now.isValid ? now : DateTime.now()).toISODate();
+}
+// Internal: a DateTime for calendar arithmetic. UTC on purpose — the date has no
+// zone, and UTC has no DST gaps to trip over.
+const dt = (iso) => DateTime.fromISO(iso, { zone: "utc" });
+/** `iso + days` calendar days (negative allowed). DST-immune. */
+export function addDaysIso(iso, days) {
+    return addDaysDt(dt(iso), days).toISODate();
+}
+/** `iso + months`; the day of month is clamped (Jan 31 + 1 → Feb 28/29). */
+export function addMonthsIso(iso, months) {
+    return dt(iso).plus({ months }).toISODate();
+}
+/** Sort comparator for `IsoDate`s (`-1`, `0`, `1`). */
+export function compareIso(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Whole calendar days from `a` to `b` (positive when `b` is later). */
+export function daysBetweenIso(a, b) {
+    return calendarDaysBetween(dt(a), dt(b));
+}
+/** The two dates in chronological order. */
+export function orderedRange(a, b) {
+    return compareIso(a, b) <= 0 ? [a, b] : [b, a];
+}
+/** Inclusive day count of a range (`1` for a single-day range). */
+export function rangeLengthIso(start, end) {
+    return Math.abs(daysBetweenIso(start, end)) + 1;
+}
+/** Inclusive `start <= iso <= end`. */
+export function isWithinRange(iso, start, end) {
+    return compareIso(iso, start) >= 0 && compareIso(iso, end) <= 0;
+}
+/** `min <= iso <= max`, each bound optional. */
+export function isWithinBounds(iso, min, max) {
+    if (min && compareIso(iso, min) < 0)
+        return false;
+    if (max && compareIso(iso, max) > 0)
+        return false;
+    return true;
+}
+/** `iso` clamped into `[min, max]` (each bound optional). */
+export function clampIso(iso, min, max) {
+    if (min && compareIso(iso, min) < 0)
+        return min;
+    if (max && compareIso(iso, max) > 0)
+        return max;
+    return iso;
+}
+/** The `{ year, month }` an `IsoDate` falls in. */
+export function yearMonthOf(iso) {
+    const p = parseIsoDate(iso);
+    if (!p)
+        throw new Error(`yearMonthOf: invalid ISO date: ${iso}`);
+    return { year: p.year, month: p.month };
+}
+/** Sort comparator for `YearMonth`s. */
+export function compareYearMonth(a, b) {
+    return a.year - b.year || a.month - b.month;
+}
+/** `ym + months` (negative allowed, crosses years). */
+export function addMonths(ym, months) {
+    const idx = ym.year * 12 + (ym.month - 1) + months;
+    return { year: Math.floor(idx / 12), month: (((idx % 12) + 12) % 12) + 1 };
+}
+/** `YYYY-MM-01` of a `YearMonth`. */
+export function firstOfMonth(ym) {
+    return toIsoDate(ym.year, ym.month, 1);
+}
+/** Stable string key of a `YearMonth` (`"2026-09"`). */
+export function yearMonthKey(ym) {
+    return `${ym.year}-${`${ym.month}`.padStart(2, "0")}`;
+}
+/** Column index (0–6) of `iso` in a week that starts on `weekStartsOn`. */
+export function weekdayColumn(iso, weekStartsOn = 1) {
+    return getAdjustedWeekday(dt(iso).weekday, weekStartsOn);
+}
+/**
+ * The month grid for a `YearMonth` — `createMonthGrid` from calendar-utils (5 or 6
+ * weeks), optionally padded to a fixed 6 weeks so the UI height never jumps while
+ * navigating.
+ */
+export function buildMonthGrid(ym, config = {}, fixedWeeks = false) {
+    const grid = createMonthGrid(ym.year, ym.month, config);
+    if (!fixedWeeks)
+        return grid;
+    const today = DateTime.now().setZone(config.zone ?? "local");
+    let last = grid[grid.length - 1][6].date;
+    while (grid.length < 6) {
+        const week = [];
+        for (let i = 0; i < 7; i++) {
+            last = addDaysDt(last, 1);
+            week.push(createDayCell(last, ym.month, today, config.weekendDays));
+        }
+        grid.push(week);
+    }
+    return grid;
+}
+// ------------------------------------------------------------------ formatting
+// A local `Date` at noon on the given calendar date. Noon keeps a formatter from
+// ever landing on the previous day around a DST switch, and `setFullYear` avoids
+// the `new Date(y, …)` two-digit-year quirk.
+function toLocalNoon(p) {
+    const d = new Date(2000, 0, 1, 12, 0, 0, 0);
+    d.setFullYear(p.year, p.month - 1, p.day);
+    return d;
+}
+/** Default `Intl` options of the date fields' display text. */
+export const DEFAULT_DATE_FORMAT = { dateStyle: "medium" };
+/**
+ * Formats an `IsoDate` for display with `Intl.DateTimeFormat` (medium date style by
+ * default). Invalid input renders as `""`.
+ */
+export function formatIsoDate(iso, locale, options = DEFAULT_DATE_FORMAT) {
+    const p = iso ? parseIsoDate(iso) : null;
+    if (!p)
+        return "";
+    return new Intl.DateTimeFormat(locale, options).format(toLocalNoon(p));
+}
+/**
+ * Formats an inclusive date range — via `Intl.DateTimeFormat#formatRange` where the
+ * runtime has it ("Sep 1 – 5, 2026"), else the two dates joined by `separator`.
+ */
+export function formatIsoDateRange(start, end, locale, options = DEFAULT_DATE_FORMAT, separator = " – ") {
+    const a = parseIsoDate(start);
+    const b = parseIsoDate(end);
+    if (!a || !b)
+        return "";
+    const f = new Intl.DateTimeFormat(locale, options);
+    const [da, db] = [toLocalNoon(a), toLocalNoon(b)];
+    if (typeof f.formatRange === "function") {
+        try {
+            return f.formatRange(da, db);
+        }
+        catch {
+            // fall through to the plain join
+        }
+    }
+    return `${f.format(da)}${separator}${f.format(db)}`;
+}
+/** "September 2026" (localized) for a `YearMonth`. */
+export function formatYearMonth(ym, locale, options = { month: "long", year: "numeric" }) {
+    return new Intl.DateTimeFormat(locale, options).format(toLocalNoon({ year: ym.year, month: ym.month, day: 1 }));
+}
+/** The 12 localized month names, January first. */
+export function getMonthNames(locale, format = "long") {
+    const f = new Intl.DateTimeFormat(locale, { month: format });
+    return Array.from({ length: 12 }, (_, i) => f.format(toLocalNoon({ year: 2024, month: i + 1, day: 1 })));
+}
+/** Full spoken form of a date ("Wednesday, September 2, 2026") — for `aria-label`s. */
+export function formatIsoDateLong(iso, locale) {
+    return formatIsoDate(iso, locale, {
+        weekday: "long",
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+    });
+}
+/**
+ * A calendar-utils `DayCell` for a single date — what `isDateDisabled` receives
+ * when the date fields validate a value outside of any rendered grid.
+ */
+export function dayCellOf(iso, config = {}) {
+    const zone = config.zone ?? "local";
+    const day = DateTime.fromISO(iso, { zone });
+    return createDayCell(day, null, DateTime.now().setZone(zone), config.weekendDays);
+}

package/dist/components/CommandMenu/CommandMenu.fixture.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	// Conventions escape hatch (docs/component-testing/02-test-conventions.md):
+	// Conventions escape hatch (docs/testing-components.md):
 	// CommandMenu is imperative-only (open()/close() via a ref; it builds on
 	// ModalDialog which has no bindable `visible` prop), so a `.svelte.test.ts`
 	// file can't drive it directly. This fixture holds the `bind:this` ref and