@urbicon-ui/blocks 6.1.4

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

@@ -0,0 +1,61 @@
+/**
+ * Keyboard handler for the date grid (ARIA `grid` roving-tabindex pattern).
+ *
+ * Arrow keys move the roving focus by day/week; Home/End jump to the week edges;
+ * PageUp/PageDown step a month (Shift = a year); Enter/Space select. All moves
+ * go through the controller, which pulls the focus back into view by navigating
+ * when it crosses the visible window.
+ */
+import { endOfWeek, startOfWeek } from '../../date';
+/** Add whole months to a date, clamping the day to the target month's length. */
+function addMonths(date, delta) {
+    const targetDay = date.getDate();
+    const firstOfTarget = new Date(date.getFullYear(), date.getMonth() + delta, 1);
+    const daysInTarget = new Date(firstOfTarget.getFullYear(), firstOfTarget.getMonth() + 1, 0).getDate();
+    firstOfTarget.setDate(Math.min(targetDay, daysInTarget));
+    return firstOfTarget;
+}
+/**
+ * Handle a keydown on the grid. Returns `true` if the key was consumed (and
+ * `preventDefault` was called), `false` to let it bubble.
+ */
+export function handleDateGridKeydown(event, target) {
+    if (target.disabled)
+        return false;
+    const focused = target.focusedDate;
+    const weekStartsOn = target.weekStartsOn;
+    switch (event.key) {
+        case 'ArrowLeft':
+            target.moveFocus(-1);
+            break;
+        case 'ArrowRight':
+            target.moveFocus(1);
+            break;
+        case 'ArrowUp':
+            target.moveFocus(-7);
+            break;
+        case 'ArrowDown':
+            target.moveFocus(7);
+            break;
+        case 'Home':
+            target.setFocusedDate(startOfWeek(focused, weekStartsOn));
+            break;
+        case 'End':
+            target.setFocusedDate(endOfWeek(focused, weekStartsOn));
+            break;
+        case 'PageUp':
+            target.setFocusedDate(addMonths(focused, event.shiftKey ? -12 : -1));
+            break;
+        case 'PageDown':
+            target.setFocusedDate(addMonths(focused, event.shiftKey ? 12 : 1));
+            break;
+        case 'Enter':
+        case ' ':
+            target.selectDate(focused);
+            break;
+        default:
+            return false;
+    }
+    event.preventDefault();
+    return true;
+}

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

@@ -0,0 +1,119 @@
+/**
+ * Headless controller for date-grid views (month / week / range / day).
+ *
+ * Owns the *invisible mechanics* shared by Calendar and Planner: grid geometry,
+ * navigation, roving focus, hover and selection. It holds no event/item concept
+ * and renders nothing — view components read it through `dateGridContext` and
+ * `DateGridScaffold`.
+ *
+ * `referenceDate`, `view`, `selection` and the bounds are **controlled inputs**
+ * supplied as reactive getters (role model: `utils/overlay-stack.svelte.ts` —
+ * a `$state` class fed by getter options). Navigation and selection never mutate
+ * those inputs directly; they call `onNavigate` / `onSelect` so the wrapper owns
+ * the source of truth (`bind:value`). Only `focusedDate`, `hoveredDate` and
+ * `navDirection` are controller-owned `$state`.
+ */
+import type { DateGridRange, DateGridSelection, DateGridSelectionMode, DateGridView, DayCellInfo, NavDirection } from './date-grid.types';
+/**
+ * Reactive inputs for a {@link DateGridController}. Value fields are getters so
+ * the controller tracks them through `$derived`; callbacks are plain optional
+ * methods invoked at action time.
+ */
+export interface DateGridOptions {
+    /** The date the grid is anchored on (controlled). */
+    get referenceDate(): Date;
+    /** Active view mode. */
+    get view(): DateGridView;
+    /** Day the week starts on (0=Sun … 6=Sat). */
+    get weekStartsOn(): number;
+    /** BCP 47 locale tag for titles and weekday names. */
+    get locale(): string;
+    /** Selection cardinality. */
+    get selectionMode(): DateGridSelectionMode;
+    /** Current selection value (controlled), shaped by `selectionMode`. */
+    get selection(): DateGridSelection | undefined;
+    /** Start of the explicit range for `view="range"`. */
+    get rangeStart(): Date | undefined;
+    /** End of the explicit range for `view="range"`. */
+    get rangeEnd(): Date | undefined;
+    /** Earliest navigable/selectable date. */
+    get minDate(): Date | undefined;
+    /** Latest navigable/selectable date. */
+    get maxDate(): Date | undefined;
+    /** Whether the whole grid is disabled. */
+    get disabled(): boolean;
+    /** Extra per-date disable predicate (on top of min/max). */
+    isDateDisabled?: (date: Date) => boolean;
+    /** Called when navigation wants a new reference date; the wrapper materialises it. */
+    onNavigate?: (date: Date, range: DateGridRange) => void;
+    /** Called with the next selection value and the date that triggered it; the
+     * wrapper materialises the selection. The trigger date lets consumers run
+     * per-click side effects (Calendar's `onDateClick` / spill-day navigation,
+     * Planner's `onDateSelect`) that the computed selection alone can't express. */
+    onSelect?: (selection: DateGridSelection, date: Date) => void;
+}
+export declare class DateGridController {
+    #private;
+    /** The roving keyboard focus target (local midnight). Controller-owned. */
+    focusedDate: Date;
+    /** The hovered date, for range-selection preview. Controller-owned. */
+    hoveredDate: Date | null;
+    /** Direction of the last navigation, for enter/exit transitions. */
+    navDirection: NavDirection;
+    /** Today (local midnight). Refreshed via {@link refreshToday}. */
+    today: Date;
+    constructor(opts: DateGridOptions);
+    get view(): DateGridView;
+    get referenceDate(): Date;
+    get weekStartsOn(): number;
+    get locale(): string;
+    get disabled(): boolean;
+    get selectionMode(): DateGridSelectionMode;
+    /** Cell rows for the current view. The single source of truth for geometry:
+     * month → 4–6 week rows; week/day → one row; range → chunked week rows. */
+    get cells(): Date[][];
+    /** The 7 dates of the week containing `referenceDate`. */
+    get weekDates(): Date[];
+    /** Localized short weekday names, ordered from `weekStartsOn`. */
+    get weekdayNames(): string[];
+    /** Localized narrow weekday names, ordered from `weekStartsOn`. */
+    get weekdayNamesNarrow(): string[];
+    /** First visible date (top-left cell) — the visible-range start. */
+    get rangeStart(): Date;
+    /** Last visible date (bottom-right cell) — the visible-range end. */
+    get rangeEnd(): Date;
+    /** Localized header title for the current view. */
+    get title(): string;
+    get canGoBack(): boolean;
+    get canGoForward(): boolean;
+    weekNumberFor(date: Date): number;
+    isToday(date: Date): boolean;
+    isWeekend(date: Date): boolean;
+    /** Outside the focused month (month view) or the requested range (range view). */
+    isOutside(date: Date): boolean;
+    isDisabled(date: Date): boolean;
+    isFocused(date: Date): boolean;
+    /** Assemble the shared per-day context for a cell. */
+    dayCellInfo(date: Date): DayCellInfo;
+    isSelected(date: Date): boolean;
+    isRangeStart(date: Date): boolean;
+    isRangeEnd(date: Date): boolean;
+    isInSelectedRange(date: Date): boolean;
+    isInPreviewRange(date: Date): boolean;
+    /** 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. */
+    goToToday(): void;
+    /** Jump the reference date to a specific date. */
+    goTo(date: Date): void;
+    /** Set the roving focus, navigating the view if the date left the visible window. */
+    setFocusedDate(date: Date): void;
+    /** Move the roving focus by `deltaDays` (keyboard arrows / page keys). */
+    moveFocus(deltaDays: number): void;
+    setHoveredDate(date: Date | null): void;
+    /** Recompute `today` (call from a midnight timer in the wrapper). */
+    refreshToday(): void;
+    /** Compute and emit the next selection value for `date` per `selectionMode`. */
+    selectDate(date: Date): void;
+}

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

@@ -0,0 +1,379 @@
+/**
+ * Headless controller for date-grid views (month / week / range / day).
+ *
+ * Owns the *invisible mechanics* shared by Calendar and Planner: grid geometry,
+ * navigation, roving focus, hover and selection. It holds no event/item concept
+ * and renders nothing — view components read it through `dateGridContext` and
+ * `DateGridScaffold`.
+ *
+ * `referenceDate`, `view`, `selection` and the bounds are **controlled inputs**
+ * supplied as reactive getters (role model: `utils/overlay-stack.svelte.ts` —
+ * a `$state` class fed by getter options). Navigation and selection never mutate
+ * those inputs directly; they call `onNavigate` / `onSelect` so the wrapper owns
+ * the source of truth (`bind:value`). Only `focusedDate`, `hoveredDate` and
+ * `navDirection` are controller-owned `$state`.
+ */
+import { addDays, clampMonth, daysBetween, endOfWeek, formatDateRange, formatDayTitle, formatMonthYear, formatWeekTitle, getMonthGrid, getWeekDates, getWeekdayNames, getWeekNumber, isInMonth, isInRange, isSameDay, isWeekend, startOfWeek, stripTime, toIso } from '../../date';
+export class DateGridController {
+    #opts;
+    /** The roving keyboard focus target (local midnight). Controller-owned. */
+    focusedDate = $state(new Date());
+    /** The hovered date, for range-selection preview. Controller-owned. */
+    hoveredDate = $state(null);
+    /** Direction of the last navigation, for enter/exit transitions. */
+    navDirection = $state(null);
+    /** Today (local midnight). Refreshed via {@link refreshToday}. */
+    today = $state(stripTime(new Date()));
+    constructor(opts) {
+        this.#opts = opts;
+        this.focusedDate = stripTime(opts.referenceDate);
+    }
+    // ─── Reflected inputs ────────────────────────────────────────────────────
+    get view() {
+        return this.#opts.view;
+    }
+    get referenceDate() {
+        return this.#opts.referenceDate;
+    }
+    get weekStartsOn() {
+        return this.#opts.weekStartsOn;
+    }
+    get locale() {
+        return this.#opts.locale;
+    }
+    get disabled() {
+        return this.#opts.disabled;
+    }
+    get selectionMode() {
+        return this.#opts.selectionMode;
+    }
+    // ─── Derived geometry ────────────────────────────────────────────────────
+    //
+    // Exposed as getters (not `$derived` fields): a field initializer would read
+    // `this.#opts` before the constructor assigns it. Getters read the reactive
+    // option getters lazily, so they are tracked correctly when consumed inside a
+    // component's `$derived`/effect — the same shape the legacy CalendarContext
+    // used. Geometry math (getMonthGrid etc.) is cheap; wrappers can memoise hot
+    // reads in their own `$derived` if a profile ever calls for it.
+    /** Cell rows for the current view. The single source of truth for geometry:
+     * month → 4–6 week rows; week/day → one row; range → chunked week rows. */
+    get cells() {
+        return this.#cellsFor(this.#opts.referenceDate);
+    }
+    /** The 7 dates of the week containing `referenceDate`. */
+    get weekDates() {
+        return getWeekDates(this.#opts.referenceDate, this.#opts.weekStartsOn);
+    }
+    /** Localized short weekday names, ordered from `weekStartsOn`. */
+    get weekdayNames() {
+        return getWeekdayNames(this.#opts.locale, this.#opts.weekStartsOn, 'short');
+    }
+    /** Localized narrow weekday names, ordered from `weekStartsOn`. */
+    get weekdayNamesNarrow() {
+        return getWeekdayNames(this.#opts.locale, this.#opts.weekStartsOn, 'narrow');
+    }
+    /** First visible date (top-left cell) — the visible-range start. */
+    get rangeStart() {
+        return this.cells[0][0];
+    }
+    /** Last visible date (bottom-right cell) — the visible-range end. */
+    get rangeEnd() {
+        const lastRow = this.cells[this.cells.length - 1];
+        return lastRow[lastRow.length - 1];
+    }
+    /** Localized header title for the current view. */
+    get title() {
+        const ref = this.#opts.referenceDate;
+        const locale = this.#opts.locale;
+        const view = this.#opts.view;
+        if (view === 'month')
+            return formatMonthYear(ref.getFullYear(), ref.getMonth(), locale);
+        if (view === 'week')
+            return formatWeekTitle(ref, this.#opts.weekStartsOn, locale);
+        if (view === 'day')
+            return formatDayTitle(ref, locale);
+        return formatDateRange(this.rangeStart, this.rangeEnd, locale); // range
+    }
+    get #navBounds() {
+        const { view, referenceDate, minDate, maxDate } = this.#opts;
+        if (view === 'month') {
+            // Month-granular bounds, matching the legacy Calendar behaviour.
+            const { canGoBack, canGoForward } = clampMonth(referenceDate.getMonth(), referenceDate.getFullYear(), minDate, maxDate);
+            return { canGoBack, canGoForward };
+        }
+        // week/day/range: day-granular bounds against the visible edges.
+        const canGoBack = !minDate || stripTime(this.rangeStart) > stripTime(minDate);
+        const canGoForward = !maxDate || stripTime(this.rangeEnd) < stripTime(maxDate);
+        return { canGoBack, canGoForward };
+    }
+    get canGoBack() {
+        return this.#navBounds.canGoBack;
+    }
+    get canGoForward() {
+        return this.#navBounds.canGoForward;
+    }
+    // ─── Per-day queries ─────────────────────────────────────────────────────
+    weekNumberFor(date) {
+        return getWeekNumber(date);
+    }
+    isToday(date) {
+        return isSameDay(date, this.today);
+    }
+    isWeekend(date) {
+        return isWeekend(date);
+    }
+    /** Outside the focused month (month view) or the requested range (range view). */
+    isOutside(date) {
+        const { view, referenceDate } = this.#opts;
+        if (view === 'month') {
+            return !isInMonth(date, referenceDate.getMonth(), referenceDate.getFullYear());
+        }
+        if (view === 'range') {
+            const rs = this.#opts.rangeStart;
+            const re = this.#opts.rangeEnd;
+            if (rs && re)
+                return !isInRange(date, rs, re);
+        }
+        return false;
+    }
+    isDisabled(date) {
+        const { disabled, minDate, maxDate, isDateDisabled } = this.#opts;
+        if (disabled)
+            return true;
+        if (isDateDisabled?.(date))
+            return true;
+        if (minDate && stripTime(date) < stripTime(minDate))
+            return true;
+        if (maxDate && stripTime(date) > stripTime(maxDate))
+            return true;
+        return false;
+    }
+    isFocused(date) {
+        return isSameDay(date, this.focusedDate);
+    }
+    /** Assemble the shared per-day context for a cell. */
+    dayCellInfo(date) {
+        return {
+            date,
+            isoDate: toIso(date),
+            isToday: this.isToday(date),
+            isWeekend: this.isWeekend(date),
+            isOutside: this.isOutside(date),
+            isFocused: this.isFocused(date),
+            isDisabled: this.isDisabled(date),
+            weekNumber: this.weekNumberFor(date)
+        };
+    }
+    // ─── Selection queries ───────────────────────────────────────────────────
+    isSelected(date) {
+        const sel = this.#opts.selection;
+        if (!sel)
+            return false;
+        if (sel instanceof Date)
+            return isSameDay(sel, date);
+        if (Array.isArray(sel))
+            return sel.some((d) => isSameDay(d, date));
+        return isSameDay(sel.start, date) || isSameDay(sel.end, date);
+    }
+    isRangeStart(date) {
+        const range = this.#asRange();
+        return range ? isSameDay(range.start, date) : false;
+    }
+    isRangeEnd(date) {
+        const range = this.#asRange();
+        if (!range)
+            return false;
+        return !isSameDay(range.start, range.end) && isSameDay(range.end, date);
+    }
+    isInSelectedRange(date) {
+        const range = this.#asRange();
+        if (!range)
+            return false;
+        return (isInRange(date, range.start, range.end) &&
+            !isSameDay(date, range.start) &&
+            !isSameDay(date, range.end));
+    }
+    isInPreviewRange(date) {
+        const range = this.#asRange();
+        if (!range || !this.hoveredDate)
+            return false;
+        // Preview only while a range start is set but not yet completed.
+        if (!isSameDay(range.start, range.end))
+            return false;
+        return isInRange(date, range.start, this.hoveredDate) && !isSameDay(date, range.start);
+    }
+    // ─── Actions ─────────────────────────────────────────────────────────────
+    /** 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) {
+        if (delta === 0)
+            return;
+        const { view, referenceDate, minDate, maxDate } = this.#opts;
+        this.navDirection = delta > 0 ? 'forward' : 'backward';
+        if (view === 'range') {
+            // The range geometry follows the explicit rangeStart/rangeEnd inputs, not
+            // referenceDate, so navigation shifts that window by its own span and emits
+            // the shifted range — the wrapper rebinds rangeStart/rangeEnd from it.
+            const { start, end } = this.#orderedRange(referenceDate);
+            const spanDays = daysBetween(start, end) + 1;
+            const shiftedStart = addDays(start, delta * spanDays);
+            const shiftedEnd = addDays(end, delta * spanDays);
+            this.#opts.onNavigate?.(shiftedStart, { start: shiftedStart, end: shiftedEnd });
+            return;
+        }
+        let next;
+        switch (view) {
+            case 'month': {
+                const total = referenceDate.getFullYear() * 12 + referenceDate.getMonth() + delta;
+                const targetYear = Math.floor(total / 12);
+                const targetMonth = ((total % 12) + 12) % 12;
+                const clamped = clampMonth(targetMonth, targetYear, minDate, maxDate);
+                next = new Date(clamped.year, clamped.month, 1);
+                break;
+            }
+            case 'week':
+                next = addDays(referenceDate, delta * 7);
+                break;
+            case 'day':
+                next = addDays(referenceDate, delta);
+                break;
+        }
+        this.#emitNavigate(next);
+    }
+    /** Jump to today and focus it. */
+    goToToday() {
+        const now = stripTime(new Date());
+        this.focusedDate = now;
+        this.#emitNavigate(now);
+    }
+    /** Jump the reference date to a specific date. */
+    goTo(date) {
+        this.#emitNavigate(stripTime(date));
+    }
+    /** Set the roving focus, navigating the view if the date left the visible window. */
+    setFocusedDate(date) {
+        const d = stripTime(date);
+        const reference = stripTime(this.#opts.referenceDate);
+        this.focusedDate = d;
+        if (this.#needsNavigationToFocus(d)) {
+            this.navDirection = d.getTime() >= reference.getTime() ? 'forward' : 'backward';
+            this.#emitNavigate(d);
+        }
+    }
+    /** Move the roving focus by `deltaDays` (keyboard arrows / page keys). */
+    moveFocus(deltaDays) {
+        this.setFocusedDate(addDays(this.focusedDate, deltaDays));
+    }
+    setHoveredDate(date) {
+        this.hoveredDate = date;
+    }
+    /** Recompute `today` (call from a midnight timer in the wrapper). */
+    refreshToday() {
+        this.today = stripTime(new Date());
+    }
+    /** Compute and emit the next selection value for `date` per `selectionMode`. */
+    selectDate(date) {
+        if (this.isDisabled(date))
+            return;
+        const { selectionMode, selection } = this.#opts;
+        let next;
+        switch (selectionMode) {
+            case 'single':
+                next = date;
+                break;
+            case 'multiple': {
+                const current = Array.isArray(selection) ? selection : [];
+                const existingIdx = current.findIndex((d) => isSameDay(d, date));
+                next = existingIdx >= 0 ? current.filter((_, i) => i !== existingIdx) : [...current, date];
+                break;
+            }
+            case 'range': {
+                const current = this.#asRange();
+                const hasCompleteRange = current && !isSameDay(current.start, current.end);
+                if (!current || hasCompleteRange) {
+                    next = { start: date, end: date };
+                }
+                else {
+                    next =
+                        date < current.start
+                            ? { start: date, end: current.start }
+                            : { start: current.start, end: date };
+                }
+                break;
+            }
+        }
+        this.#opts.onSelect?.(next, date);
+    }
+    // ─── Internals ───────────────────────────────────────────────────────────
+    /** The explicit range bounds ordered low→high (tolerating an inverted input),
+     * each defaulting to `reference` when the consumer omits them. Keeps range
+     * geometry non-empty so the rangeStart/rangeEnd/title getters never throw. */
+    #orderedRange(reference) {
+        const rs = stripTime(this.#opts.rangeStart ?? reference);
+        const re = stripTime(this.#opts.rangeEnd ?? reference);
+        return rs.getTime() <= re.getTime() ? { start: rs, end: re } : { start: re, end: rs };
+    }
+    /** Pure cell geometry for an arbitrary reference date (no side effects). */
+    #cellsFor(reference) {
+        const wso = this.#opts.weekStartsOn;
+        switch (this.#opts.view) {
+            case 'month':
+                return getMonthGrid(reference.getFullYear(), reference.getMonth(), wso);
+            case 'week':
+                return [getWeekDates(reference, wso)];
+            case 'day':
+                return [[stripTime(reference)]];
+            case 'range': {
+                const { start, end } = this.#orderedRange(reference);
+                return chunkIntoWeeks(startOfWeek(start, wso), endOfWeek(end, wso));
+            }
+        }
+    }
+    /** Visible range for an arbitrary reference date, derived from its cells. */
+    #rangeFor(reference) {
+        const cells = this.#cellsFor(reference);
+        const lastRow = cells[cells.length - 1];
+        return { start: cells[0][0], end: lastRow[lastRow.length - 1] };
+    }
+    #emitNavigate(next) {
+        this.#opts.onNavigate?.(next, this.#rangeFor(next));
+    }
+    /** Whether focusing `date` requires navigating the view to reveal it. */
+    #needsNavigationToFocus(date) {
+        const { view, referenceDate } = this.#opts;
+        switch (view) {
+            case 'month':
+                return !isInMonth(date, referenceDate.getMonth(), referenceDate.getFullYear());
+            case 'week':
+                return !this.weekDates.some((d) => isSameDay(d, date));
+            case 'day':
+                return !isSameDay(date, referenceDate);
+            case 'range':
+                return !this.cells.some((week) => week.some((d) => isSameDay(d, date)));
+        }
+    }
+    /** The selection as a range, or null when it is not a (range-mode) range value. */
+    #asRange() {
+        const sel = this.#opts.selection;
+        if (this.#opts.selectionMode !== 'range')
+            return null;
+        if (!sel || sel instanceof Date || Array.isArray(sel))
+            return null;
+        return sel;
+    }
+}
+/** Chunk an inclusive [start, end] span of full weeks into rows of 7 days. */
+function chunkIntoWeeks(start, end) {
+    const rows = [];
+    let cursor = stripTime(start);
+    const last = stripTime(end).getTime();
+    while (cursor.getTime() <= last) {
+        const row = [];
+        for (let i = 0; i < 7; i++) {
+            row.push(cursor);
+            cursor = addDays(cursor, 1);
+        }
+        rows.push(row);
+    }
+    return rows;
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Shared types for the headless date-grid core (`lib/internal/date-grid`).
+ *
+ * This layer knows only about dates, cells, navigation, focus and selection —
+ * never about events or domain items. Calendar and Planner build their visible
+ * markup on top of it.
+ */
+/** View modes the grid can lay out. Cell-based views (month/week/range) render
+ * through `DateGridScaffold`; `day` is a navigation/geometry mode whose visible
+ * markup (time grid) stays Calendar-specific. */
+export type DateGridView = 'month' | 'week' | 'range' | 'day';
+/** Selection cardinality. Planner uses only `single`; Calendar uses all three. */
+export type DateGridSelectionMode = 'single' | 'range' | 'multiple';
+/** An inclusive start/end date pair. */
+export interface DateGridRange {
+    start: Date;
+    end: Date;
+}
+/** The current selection value, shaped by the active `DateGridSelectionMode`. */
+export type DateGridSelection = Date | Date[] | DateGridRange;
+/** Direction of the most recent navigation, for enter/exit transitions. */
+export type NavDirection = 'forward' | 'backward' | null;
+/**
+ * Per-day context shared by every cell-based view. Calendar and Planner enrich
+ * this with their own fields (events / bucketed items) before handing it to
+ * their cell snippet.
+ */
+export interface DayCellInfo {
+    /** The cell's date (local midnight). */
+    date: Date;
+    /** `YYYY-MM-DD` local key for this date. */
+    isoDate: string;
+    /** Whether this date is today. */
+    isToday: boolean;
+    /** Whether this date is a Saturday or Sunday. */
+    isWeekend: boolean;
+    /** Whether this date falls outside the focused month (month view) or the
+     * requested range (range view). Always false for week/day. */
+    isOutside: boolean;
+    /** Whether this date currently holds the roving keyboard focus. */
+    isFocused: boolean;
+    /** Whether this date is disabled (min/max bounds or `isDateDisabled`). */
+    isDisabled: boolean;
+    /** ISO 8601 week number of this date. */
+    weekNumber: number;
+}
+/** Per-column context for the weekday header row. */
+export interface DayHeaderInfo {
+    /** Localized weekday name in the requested short format (e.g. "Mo"). */
+    weekday: string;
+    /** Localized narrow weekday name (e.g. "M"). */
+    weekdayNarrow: string;
+    /** Column index, 0–6, counted from `weekStartsOn`. */
+    index: number;
+    /** Whether this column is a weekend column. */
+    isWeekend: boolean;
+    /** The concrete date for this column in single-week views (week/day);
+     * `undefined` in month/range views where a column spans many dates. */
+    date?: Date;
+}
+/**
+ * The reactive surface a `DateGridController` exposes through context. Mirrors
+ * the controller's public getters/methods so sub-components (Scaffold, view
+ * grids, headers) can consume it without holding the instance directly.
+ */
+export interface DateGridContext {
+    readonly view: DateGridView;
+    readonly referenceDate: Date;
+    readonly weekStartsOn: number;
+    readonly locale: string;
+    readonly today: Date;
+    readonly disabled: boolean;
+    readonly cells: Date[][];
+    readonly weekDates: Date[];
+    readonly weekdayNames: string[];
+    readonly weekdayNamesNarrow: string[];
+    readonly title: string;
+    readonly rangeStart: Date;
+    readonly rangeEnd: Date;
+    readonly canGoBack: boolean;
+    readonly canGoForward: boolean;
+    readonly focusedDate: Date;
+    readonly hoveredDate: Date | null;
+    readonly navDirection: NavDirection;
+    readonly selectionMode: DateGridSelectionMode;
+    weekNumberFor(date: Date): number;
+    dayCellInfo(date: Date): DayCellInfo;
+    isToday(date: Date): boolean;
+    isWeekend(date: Date): boolean;
+    isOutside(date: Date): boolean;
+    isDisabled(date: Date): boolean;
+    isFocused(date: Date): boolean;
+    isSelected(date: Date): boolean;
+    isRangeStart(date: Date): boolean;
+    isRangeEnd(date: Date): boolean;
+    isInSelectedRange(date: Date): boolean;
+    isInPreviewRange(date: Date): boolean;
+    navigate(delta: number): void;
+    goToToday(): void;
+    goTo(date: Date): void;
+    selectDate(date: Date): void;
+    setFocusedDate(date: Date): void;
+    moveFocus(deltaDays: number): void;
+    setHoveredDate(date: Date | null): void;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Shared types for the headless date-grid core (`lib/internal/date-grid`).
+ *
+ * This layer knows only about dates, cells, navigation, focus and selection —
+ * never about events or domain items. Calendar and Planner build their visible
+ * markup on top of it.
+ */
+export {};