@urbicon-ui/blocks 6.19.0 → 6.19.1

package/dist/i18n/index.d.ts

@@ -52,6 +52,8 @@ declare const blocksTranslations: {
             readonly last: "Last";
             readonly page: "Page";
             readonly previous: "Previous";
+            readonly pageInfo: "{{label}} {{current}} of {{total}}";
+            readonly rangeInfo: "{{start}}–{{end}} of {{total}}";
         };
         readonly calendar: {
             readonly recurring: "Recurring event";
@@ -73,8 +75,6 @@ declare const blocksTranslations: {
             readonly legend: "Legend";
             readonly yearView: "Year overview";
             readonly weekView: "Week view";
-            readonly dayView: "Day view";
-            readonly monthView: "Month view";
             readonly viewMonth: "Month";
             readonly viewYear: "Year";
             readonly viewWeek: "Week";
@@ -93,7 +93,6 @@ declare const blocksTranslations: {
             readonly nextRange: "Next range";
             readonly today: "Today";
             readonly grid: "Planner";
-            readonly weekNumber: "Week number";
             readonly itemCount: "{{count}} items";
         };
         readonly commandPalette: {
@@ -145,7 +144,6 @@ declare const blocksTranslations: {
         readonly datepicker: {
             readonly placeholder: "Select a date...";
             readonly rangePlaceholder: "Select a date range...";
-            readonly clear: "Clear selection";
             readonly openCalendar: "Open calendar";
             readonly invalidDate: "Invalid date";
             readonly outOfRange: "Date is outside the allowed range";
@@ -177,9 +175,15 @@ declare const blocksTranslations: {
             readonly darkMode: "Dark mode";
             readonly systemTheme: "System theme";
         };
-        readonly time: {
-            readonly ago: "{{value}} {{unit}} ago";
-            readonly now: "now";
+        readonly chart: {
+            readonly category: "Category";
+            readonly series: "Series {{index}}";
+            readonly segment: "Segment";
+            readonly value: "Value";
+            readonly share: "Share";
+        };
+        readonly stepper: {
+            readonly optional: "Optional";
         };
     };
     de: {
@@ -234,6 +238,8 @@ declare const blocksTranslations: {
             readonly last: "Letzte";
             readonly page: "Seite";
             readonly previous: "Vorherige";
+            readonly pageInfo: "{{label}} {{current}} von {{total}}";
+            readonly rangeInfo: "{{start}}–{{end}} von {{total}}";
         };
         readonly calendar: {
             readonly recurring: "Wiederkehrender Termin";
@@ -255,8 +261,6 @@ declare const blocksTranslations: {
             readonly legend: "Legende";
             readonly yearView: "Jahresübersicht";
             readonly weekView: "Wochenansicht";
-            readonly dayView: "Tagesansicht";
-            readonly monthView: "Monatsansicht";
             readonly viewMonth: "Monat";
             readonly viewYear: "Jahr";
             readonly viewWeek: "Woche";
@@ -275,7 +279,6 @@ declare const blocksTranslations: {
             readonly nextRange: "Nächster Zeitraum";
             readonly today: "Heute";
             readonly grid: "Planer";
-            readonly weekNumber: "Kalenderwoche";
             readonly itemCount: "{{count}} Einträge";
         };
         readonly commandPalette: {
@@ -327,7 +330,6 @@ declare const blocksTranslations: {
         readonly datepicker: {
             readonly placeholder: "Datum wählen...";
             readonly rangePlaceholder: "Zeitraum wählen...";
-            readonly clear: "Auswahl löschen";
             readonly openCalendar: "Kalender öffnen";
             readonly invalidDate: "Ungültiges Datum";
             readonly outOfRange: "Datum liegt außerhalb des zulässigen Bereichs";
@@ -359,194 +361,19 @@ declare const blocksTranslations: {
             readonly darkMode: "Dunkler Modus";
             readonly systemTheme: "Systemdesign";
         };
-        readonly time: {
-            readonly ago: "vor {{value}} {{unit}}";
-            readonly now: "jetzt";
-        };
-    };
-};
-export declare const blocksI18n: import("@urbicon-ui/i18n").PackageI18n<{
-    readonly accessibility: {
-        readonly avatar: "Avatar";
-        readonly clearInput: "Clear input";
-        readonly clearSearch: "Clear search";
-        readonly clearSelection: "Clear selection";
-        readonly closeDialog: "Close dialog";
-        readonly closeDrawer: "Close drawer";
-        readonly dismiss: "Dismiss";
-        readonly fileUpload: "File upload";
-        readonly loading: "Loading";
-        readonly maximum: "Maximum";
-        readonly minimum: "Minimum";
-        readonly pagination: "Page navigation";
-        readonly progress: "Progress";
-        readonly slider: "Slider";
-        readonly toggle: "Toggle";
-        readonly toggleOptions: "Toggle options";
-        readonly removableBadge: "Removable badge";
-        readonly removeBadge: "Remove badge";
-        readonly removeFile: "Remove {{name}}";
-    };
-    readonly button: {
-        readonly close: "Close";
-        readonly apply: "Apply";
-        readonly cancel: "Cancel";
-        readonly confirm: "Confirm";
-    };
-    readonly menu: {
-        readonly placeholder: "Select an option...";
-    };
-    readonly common: {
-        readonly loading: "Loading...";
-    };
-    readonly languages: {
-        readonly de: "Deutsch";
-        readonly en: "English";
-        readonly es: "Español";
-        readonly fr: "Français";
-        readonly it: "Italiano";
-        readonly nl: "Nederlands";
-    };
-    readonly localeSwitcher: {
-        readonly ariaLabel: "Language selection";
-        readonly placeholder: "Select language...";
-    };
-    readonly pagination: {
-        readonly next: "Next";
-        readonly first: "First";
-        readonly last: "Last";
-        readonly page: "Page";
-        readonly previous: "Previous";
-    };
-    readonly calendar: {
-        readonly recurring: "Recurring event";
-        readonly previousMonth: "Previous month";
-        readonly nextMonth: "Next month";
-        readonly previousWeek: "Previous week";
-        readonly nextWeek: "Next week";
-        readonly previousDay: "Previous day";
-        readonly nextDay: "Next day";
-        readonly previousYear: "Previous year";
-        readonly nextYear: "Next year";
-        readonly today: "Today";
-        readonly calendarGrid: "Calendar";
-        readonly weekdays: "Weekdays";
-        readonly weekNumber: "Week number";
-        readonly events: "Events";
-        readonly noEvents: "No events";
-        readonly showMore: "{{count}} more";
-        readonly legend: "Legend";
-        readonly yearView: "Year overview";
-        readonly weekView: "Week view";
-        readonly dayView: "Day view";
-        readonly monthView: "Month view";
-        readonly viewMonth: "Month";
-        readonly viewYear: "Year";
-        readonly viewWeek: "Week";
-        readonly viewDay: "Day";
-        readonly multiDayLabel: "Day {{current}} of {{total}}";
-        readonly agendaView: "Agenda view";
-        readonly viewAgenda: "Agenda";
-        readonly viewSwitcher: "View mode";
-    };
-    readonly planner: {
-        readonly previousWeek: "Previous week";
-        readonly nextWeek: "Next week";
-        readonly previousMonth: "Previous month";
-        readonly nextMonth: "Next month";
-        readonly previousRange: "Previous range";
-        readonly nextRange: "Next range";
-        readonly today: "Today";
-        readonly grid: "Planner";
-        readonly weekNumber: "Week number";
-        readonly itemCount: "{{count}} items";
-    };
-    readonly commandPalette: {
-        readonly noResults: "No results found.";
-        readonly search: "Search...";
-        readonly hints: {
-            readonly navigate: "Navigate";
-            readonly select: "Select";
-            readonly close: "Close";
-        };
-    };
-    readonly compositionBar: {
-        readonly total: "Total";
-        readonly summary: "Composition: {{total}} ({{count}} shares) — {{parts}}";
-        readonly share: "Share";
-        readonly value: "Value";
-        readonly percent: "Percent";
-        readonly remaining: "remaining";
-    };
-    readonly guide: {
-        readonly next: "Next";
-        readonly previous: "Back";
-        readonly skip: "Skip tour";
-        readonly done: "Done";
-        readonly step: "Step {{current}} of {{total}}";
-        readonly tour: "Guided tour";
-        readonly close: "Close";
-        readonly openHelp: "Help";
-        readonly backToList: "All topics";
-        readonly info: "More information";
-        readonly infoAbout: "More information about {{label}}";
-        readonly dismiss: "Dismiss hint";
-        readonly startTour: "Start the guided tour";
-        readonly actionRequired: "Complete the highlighted action to continue";
-        readonly filterPlaceholder: "Filter topics…";
-        readonly noResults: "No matching topics";
-    };
-    readonly journeyTimeline: {
-        readonly label: "Journey";
-        readonly status: {
-            readonly complete: "Completed";
-            readonly active: "In progress";
-            readonly pending: "Pending";
-            readonly attention: "Needs attention";
-            readonly blocked: "Blocked";
-            readonly skipped: "Skipped";
+        readonly chart: {
+            readonly category: "Kategorie";
+            readonly series: "Datenreihe {{index}}";
+            readonly segment: "Segment";
+            readonly value: "Wert";
+            readonly share: "Anteil";
         };
-    };
-    readonly datepicker: {
-        readonly placeholder: "Select a date...";
-        readonly rangePlaceholder: "Select a date range...";
-        readonly clear: "Clear selection";
-        readonly openCalendar: "Open calendar";
-        readonly invalidDate: "Invalid date";
-        readonly outOfRange: "Date is outside the allowed range";
-        readonly invalidRange: "Invalid date range";
-    };
-    readonly fileUpload: {
-        readonly exists: "File already added";
-        readonly invalidType: "File type {{type}} is not allowed";
-        readonly tooLarge: "File exceeds {{size}} limit";
-        readonly tooMany: "Maximum {{count}} files allowed";
-        readonly tooSmall: "File must be at least {{size}}";
-    };
-    readonly sankey: {
-        readonly summary: "Sankey diagram: {{nodes}} nodes, {{links}} links — {{flows}}";
-        readonly source: "Source";
-        readonly target: "Target";
-        readonly value: "Value";
-    };
-    readonly slider: {
-        readonly rangeStatus: {
-            readonly insideRecommended: "In recommended range";
-            readonly insideValid: "In valid range";
-            readonly insideValidOnly: "Outside recommended range, but valid";
-            readonly outsideValid: "Outside valid range";
+        readonly stepper: {
+            readonly optional: "Optional";
         };
     };
-    readonly themeSwitcher: {
-        readonly lightMode: "Light mode";
-        readonly darkMode: "Dark mode";
-        readonly systemTheme: "System theme";
-    };
-    readonly time: {
-        readonly ago: "{{value}} {{unit}} ago";
-        readonly now: "now";
-    };
-}>;
+};
+export declare const blocksI18n: import("@urbicon-ui/i18n").PackageI18n<import("@urbicon-ui/i18n").Translations>;
 /**
  * Context-scoped translation hook for the blocks package. Call during component
  * initialisation, then use the returned `t` (conventionally aliased `bt`):
@@ -559,188 +386,7 @@ export declare const blocksI18n: import("@urbicon-ui/i18n").PackageI18n<{
  * Resolves against the nearest `<I18nProvider>`'s locale (or the base locale
  * when none is mounted) and re-renders reactively on locale change.
  */
-export declare const useBlocksI18n: () => import("@urbicon-ui/i18n").TypedTranslationFunction<{
-    readonly accessibility: {
-        readonly avatar: "Avatar";
-        readonly clearInput: "Clear input";
-        readonly clearSearch: "Clear search";
-        readonly clearSelection: "Clear selection";
-        readonly closeDialog: "Close dialog";
-        readonly closeDrawer: "Close drawer";
-        readonly dismiss: "Dismiss";
-        readonly fileUpload: "File upload";
-        readonly loading: "Loading";
-        readonly maximum: "Maximum";
-        readonly minimum: "Minimum";
-        readonly pagination: "Page navigation";
-        readonly progress: "Progress";
-        readonly slider: "Slider";
-        readonly toggle: "Toggle";
-        readonly toggleOptions: "Toggle options";
-        readonly removableBadge: "Removable badge";
-        readonly removeBadge: "Remove badge";
-        readonly removeFile: "Remove {{name}}";
-    };
-    readonly button: {
-        readonly close: "Close";
-        readonly apply: "Apply";
-        readonly cancel: "Cancel";
-        readonly confirm: "Confirm";
-    };
-    readonly menu: {
-        readonly placeholder: "Select an option...";
-    };
-    readonly common: {
-        readonly loading: "Loading...";
-    };
-    readonly languages: {
-        readonly de: "Deutsch";
-        readonly en: "English";
-        readonly es: "Español";
-        readonly fr: "Français";
-        readonly it: "Italiano";
-        readonly nl: "Nederlands";
-    };
-    readonly localeSwitcher: {
-        readonly ariaLabel: "Language selection";
-        readonly placeholder: "Select language...";
-    };
-    readonly pagination: {
-        readonly next: "Next";
-        readonly first: "First";
-        readonly last: "Last";
-        readonly page: "Page";
-        readonly previous: "Previous";
-    };
-    readonly calendar: {
-        readonly recurring: "Recurring event";
-        readonly previousMonth: "Previous month";
-        readonly nextMonth: "Next month";
-        readonly previousWeek: "Previous week";
-        readonly nextWeek: "Next week";
-        readonly previousDay: "Previous day";
-        readonly nextDay: "Next day";
-        readonly previousYear: "Previous year";
-        readonly nextYear: "Next year";
-        readonly today: "Today";
-        readonly calendarGrid: "Calendar";
-        readonly weekdays: "Weekdays";
-        readonly weekNumber: "Week number";
-        readonly events: "Events";
-        readonly noEvents: "No events";
-        readonly showMore: "{{count}} more";
-        readonly legend: "Legend";
-        readonly yearView: "Year overview";
-        readonly weekView: "Week view";
-        readonly dayView: "Day view";
-        readonly monthView: "Month view";
-        readonly viewMonth: "Month";
-        readonly viewYear: "Year";
-        readonly viewWeek: "Week";
-        readonly viewDay: "Day";
-        readonly multiDayLabel: "Day {{current}} of {{total}}";
-        readonly agendaView: "Agenda view";
-        readonly viewAgenda: "Agenda";
-        readonly viewSwitcher: "View mode";
-    };
-    readonly planner: {
-        readonly previousWeek: "Previous week";
-        readonly nextWeek: "Next week";
-        readonly previousMonth: "Previous month";
-        readonly nextMonth: "Next month";
-        readonly previousRange: "Previous range";
-        readonly nextRange: "Next range";
-        readonly today: "Today";
-        readonly grid: "Planner";
-        readonly weekNumber: "Week number";
-        readonly itemCount: "{{count}} items";
-    };
-    readonly commandPalette: {
-        readonly noResults: "No results found.";
-        readonly search: "Search...";
-        readonly hints: {
-            readonly navigate: "Navigate";
-            readonly select: "Select";
-            readonly close: "Close";
-        };
-    };
-    readonly compositionBar: {
-        readonly total: "Total";
-        readonly summary: "Composition: {{total}} ({{count}} shares) — {{parts}}";
-        readonly share: "Share";
-        readonly value: "Value";
-        readonly percent: "Percent";
-        readonly remaining: "remaining";
-    };
-    readonly guide: {
-        readonly next: "Next";
-        readonly previous: "Back";
-        readonly skip: "Skip tour";
-        readonly done: "Done";
-        readonly step: "Step {{current}} of {{total}}";
-        readonly tour: "Guided tour";
-        readonly close: "Close";
-        readonly openHelp: "Help";
-        readonly backToList: "All topics";
-        readonly info: "More information";
-        readonly infoAbout: "More information about {{label}}";
-        readonly dismiss: "Dismiss hint";
-        readonly startTour: "Start the guided tour";
-        readonly actionRequired: "Complete the highlighted action to continue";
-        readonly filterPlaceholder: "Filter topics…";
-        readonly noResults: "No matching topics";
-    };
-    readonly journeyTimeline: {
-        readonly label: "Journey";
-        readonly status: {
-            readonly complete: "Completed";
-            readonly active: "In progress";
-            readonly pending: "Pending";
-            readonly attention: "Needs attention";
-            readonly blocked: "Blocked";
-            readonly skipped: "Skipped";
-        };
-    };
-    readonly datepicker: {
-        readonly placeholder: "Select a date...";
-        readonly rangePlaceholder: "Select a date range...";
-        readonly clear: "Clear selection";
-        readonly openCalendar: "Open calendar";
-        readonly invalidDate: "Invalid date";
-        readonly outOfRange: "Date is outside the allowed range";
-        readonly invalidRange: "Invalid date range";
-    };
-    readonly fileUpload: {
-        readonly exists: "File already added";
-        readonly invalidType: "File type {{type}} is not allowed";
-        readonly tooLarge: "File exceeds {{size}} limit";
-        readonly tooMany: "Maximum {{count}} files allowed";
-        readonly tooSmall: "File must be at least {{size}}";
-    };
-    readonly sankey: {
-        readonly summary: "Sankey diagram: {{nodes}} nodes, {{links}} links — {{flows}}";
-        readonly source: "Source";
-        readonly target: "Target";
-        readonly value: "Value";
-    };
-    readonly slider: {
-        readonly rangeStatus: {
-            readonly insideRecommended: "In recommended range";
-            readonly insideValid: "In valid range";
-            readonly insideValidOnly: "Outside recommended range, but valid";
-            readonly outsideValid: "Outside valid range";
-        };
-    };
-    readonly themeSwitcher: {
-        readonly lightMode: "Light mode";
-        readonly darkMode: "Dark mode";
-        readonly systemTheme: "System theme";
-    };
-    readonly time: {
-        readonly ago: "{{value}} {{unit}} ago";
-        readonly now: "now";
-    };
-}>;
+export declare const useBlocksI18n: any;
 export declare const hasBlocksTranslation: (key: string) => boolean, getBlocksLocales: () => import("@urbicon-ui/i18n").Locale[];
 export type BlocksTranslationKey = keyof typeof enTranslations;
 export { blocksTranslations };

package/dist/internal/date-grid/date-grid.svelte.d.ts

@@ -86,6 +86,12 @@ export declare class DateGridController {
     get title(): string;
     get canGoBack(): boolean;
     get canGoForward(): boolean;
+    /** Whether today lies within `[minDate, maxDate]` and can be navigated to. Drives
+     * the header Today button's disabled state (mirrors the arrow buttons gating on
+     * canGoBack/canGoForward). Day-granular: the button jumps to today's *day*, so a
+     * maxDate earlier this month still disables it once today passes the bound. Reads
+     * the reactive `today`, so it re-evaluates after the midnight refresh. */
+    get canGoToToday(): boolean;
     weekNumberFor(date: Date): number;
     isToday(date: Date): boolean;
     isWeekend(date: Date): boolean;
@@ -103,11 +109,20 @@ export declare class DateGridController {
     /** Step the view by `delta` units (months / weeks / days; range shifts by its
      * own span in weeks). Emits the next reference date and visible range. */
     navigate(delta: number): void;
-    /** Jump to today and focus it. */
+    /** Jump to today and focus it. Clamped to `[minDate, maxDate]`: the header Today
+     * button gates itself on {@link canGoToToday} (a clamped "today" is not today, so
+     * it disables rather than mislead), but a programmatic call still must not seat the
+     * reference on an all-disabled month/week/day past the boundary. Uses `today` — the
+     * controller's source of truth for "today" — so it lands where `isToday` marks. */
     goToToday(): void;
-    /** Jump the reference date to a specific date. */
+    /** Jump the reference date to a specific date, clamped to `[minDate, maxDate]`. */
     goTo(date: Date): void;
-    /** Set the roving focus, navigating the view if the date left the visible window. */
+    /** Set the roving focus, navigating the view if the date left the visible window.
+     * The target is clamped to `[minDate, maxDate]` — arrow/Home/End/Page keys are not
+     * gated by canGoBack/canGoForward, so an unclamped focus could cross the boundary
+     * and drag the view onto an all-disabled window (the same escape the stepping paths
+     * close). Only the hard outer bounds clamp; custom `isDateDisabled` holes *inside*
+     * the range stay focusable, per the ARIA grid pattern. */
     setFocusedDate(date: Date): void;
     /** Move the roving focus by `deltaDays` (keyboard arrows / page keys). */
     moveFocus(deltaDays: number): void;

package/dist/internal/date-grid/date-grid.svelte.js

@@ -13,7 +13,7 @@
  * the source of truth (`bind:value`). Only `focusedDate`, `hoveredDate` and
  * `navDirection` are controller-owned `$state`.
  */
-import { addDays, clampMonth, daysBetween, daysInMonth, endOfWeek, formatDateRange, formatDayTitle, formatMonthYear, formatWeekTitle, getMonthGrid, getWeekDates, getWeekdayNames, getWeekNumber, isInMonth, isInRange, isSameDay, isWeekend, startOfWeek, stripTime, toIso } from '../../date/index.js';
+import { addDays, clampDate, clampMonth, daysBetween, daysInMonth, endOfWeek, formatDateRange, formatDayTitle, formatMonthYear, formatWeekTitle, getMonthGrid, getWeekDates, getWeekdayNames, getWeekNumber, isInMonth, isInRange, isSameDay, isWeekend, startOfWeek, stripTime, toIso } from '../../date/index.js';
 export class DateGridController {
     #opts;
     /** The roving keyboard focus target (local midnight). Controller-owned. */
@@ -27,6 +27,21 @@ export class DateGridController {
     constructor(opts) {
         this.#opts = opts;
         this.focusedDate = stripTime(opts.referenceDate);
+        // Dev-only: surface inverted bounds (a caller passing minDate after
+        // maxDate). `clampDate` resolves every date to minDate in that case, so
+        // navigation gating and today/disabled logic become deterministic-but-
+        // meaningless rather than failing. Checked once at construction — the
+        // realistic mistake is statically swapped props; mirrors the Select/Guide
+        // `import.meta.env?.DEV && console.warn` precedent (no throw: a degraded
+        // grid still renders, and the library never crashes on caller garbage-in).
+        if (import.meta.env?.DEV) {
+            const { minDate, maxDate } = opts;
+            if (minDate && maxDate && stripTime(minDate) > stripTime(maxDate)) {
+                console.warn(`[DateGrid] minDate (${minDate.toLocaleDateString()}) is after maxDate ` +
+                    `(${maxDate.toLocaleDateString()}) — bounds are inverted; every date ` +
+                    `clamps to minDate and navigation is meaningless. Swap the two.`);
+            }
+        }
     }
     // ─── Reflected inputs ────────────────────────────────────────────────────
     get view() {
@@ -112,6 +127,20 @@ export class DateGridController {
     get canGoForward() {
         return this.#navBounds.canGoForward;
     }
+    /** Whether today lies within `[minDate, maxDate]` and can be navigated to. Drives
+     * the header Today button's disabled state (mirrors the arrow buttons gating on
+     * canGoBack/canGoForward). Day-granular: the button jumps to today's *day*, so a
+     * maxDate earlier this month still disables it once today passes the bound. Reads
+     * the reactive `today`, so it re-evaluates after the midnight refresh. */
+    get canGoToToday() {
+        const { minDate, maxDate } = this.#opts;
+        const t = this.today;
+        if (minDate && t < stripTime(minDate))
+            return false;
+        if (maxDate && t > stripTime(maxDate))
+            return false;
+        return true;
+    }
     // ─── Per-day queries ─────────────────────────────────────────────────────
     weekNumberFor(date) {
         return getWeekNumber(date);
@@ -235,39 +264,51 @@ export class DateGridController {
                 // month (1 Mar 2026 is a Sunday → its Monday-week is 23 Feb–1 Mar). Matches
                 // the keyboard PageUp/PageDown month step, which already clamps the day.
                 const day = Math.min(referenceDate.getDate(), daysInMonth(clamped.year, clamped.month));
-                next = new Date(clamped.year, clamped.month, day);
-                // clampMonth bounds the month; clamp the preserved day too so it never lands
-                // before minDate / after maxDate within that boundary month (a week view
-                // would otherwise open on an all-disabled week just outside the range).
-                if (minDate && next < stripTime(minDate))
-                    next = stripTime(minDate);
-                if (maxDate && next > stripTime(maxDate))
-                    next = stripTime(maxDate);
+                // clampMonth bounds the month; clampDate clamps the preserved day too so it
+                // never lands before minDate / after maxDate within that boundary month (a
+                // week view would otherwise open on an all-disabled week just outside range).
+                next = clampDate(new Date(clamped.year, clamped.month, day), minDate, maxDate);
                 break;
             }
+            // Week/day steps carry no month bounds of their own, so clamp the shifted
+            // reference to [minDate, maxDate] too — otherwise a swipe or a day-view arrow
+            // key (neither gated by canGoBack/canGoForward the way the header arrows are)
+            // could step the anchor onto an all-disabled week/day past the boundary.
             case 'week':
-                next = addDays(referenceDate, delta * 7);
+                next = clampDate(addDays(referenceDate, delta * 7), minDate, maxDate);
                 break;
             case 'day':
-                next = addDays(referenceDate, delta);
+                next = clampDate(addDays(referenceDate, delta), minDate, maxDate);
                 break;
         }
         this.#emitNavigate(next);
     }
-    /** Jump to today and focus it. */
+    /** Jump to today and focus it. Clamped to `[minDate, maxDate]`: the header Today
+     * button gates itself on {@link canGoToToday} (a clamped "today" is not today, so
+     * it disables rather than mislead), but a programmatic call still must not seat the
+     * reference on an all-disabled month/week/day past the boundary. Uses `today` — the
+     * controller's source of truth for "today" — so it lands where `isToday` marks. */
     goToToday() {
-        const now = stripTime(new Date());
+        const { minDate, maxDate } = this.#opts;
+        const now = clampDate(this.today, minDate, maxDate);
         this.focusedDate = now;
         this.#emitNavigate(now);
     }
-    /** Jump the reference date to a specific date. */
+    /** Jump the reference date to a specific date, clamped to `[minDate, maxDate]`. */
     goTo(date) {
-        this.#emitNavigate(stripTime(date));
-    }
-    /** Set the roving focus, navigating the view if the date left the visible window. */
+        const { minDate, maxDate } = this.#opts;
+        this.#emitNavigate(clampDate(stripTime(date), minDate, maxDate));
+    }
+    /** Set the roving focus, navigating the view if the date left the visible window.
+     * The target is clamped to `[minDate, maxDate]` — arrow/Home/End/Page keys are not
+     * gated by canGoBack/canGoForward, so an unclamped focus could cross the boundary
+     * and drag the view onto an all-disabled window (the same escape the stepping paths
+     * close). Only the hard outer bounds clamp; custom `isDateDisabled` holes *inside*
+     * the range stay focusable, per the ARIA grid pattern. */
     setFocusedDate(date) {
-        const d = stripTime(date);
-        const reference = stripTime(this.#opts.referenceDate);
+        const { minDate, maxDate, referenceDate } = this.#opts;
+        const d = clampDate(stripTime(date), minDate, maxDate);
+        const reference = stripTime(referenceDate);
         this.focusedDate = d;
         if (this.#needsNavigationToFocus(d)) {
             this.navDirection = d.getTime() >= reference.getTime() ? 'forward' : 'backward';

package/dist/internal/date-grid/index.d.ts

@@ -3,8 +3,8 @@
  *
  * Shared mechanics for cell-based date views: the `DateGridController` state
  * class, its context, the keyboard handler and the `DateGridScaffold` chrome.
- * Consumed by Calendar and Planner; see docs/DATEGRID-PLANNER-PLAN.md (D6) for
- * why it stays internal for now.
+ * Consumed by Calendar and Planner; see docs/ARCHITECTURE.md → "Date & Planning
+ * Infrastructure" for why it stays internal for now.
  */
 export { default as DateGridScaffold } from './DateGridScaffold.svelte';
 export { getDateGridContext, setDateGridContext } from './date-grid.context.js';

package/dist/internal/date-grid/index.js

@@ -3,8 +3,8 @@
  *
  * Shared mechanics for cell-based date views: the `DateGridController` state
  * class, its context, the keyboard handler and the `DateGridScaffold` chrome.
- * Consumed by Calendar and Planner; see docs/DATEGRID-PLANNER-PLAN.md (D6) for
- * why it stays internal for now.
+ * Consumed by Calendar and Planner; see docs/ARCHITECTURE.md → "Date & Planning
+ * Infrastructure" for why it stays internal for now.
  */
 export { default as DateGridScaffold } from './DateGridScaffold.svelte';
 export { getDateGridContext, setDateGridContext } from './date-grid.context.js';