stimeo-ui 0.1.0-alpha.1

package/dist/controllers/bulk_select_controller.d.ts

@@ -0,0 +1,67 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless **bulk select / batch action bar** (no dedicated APG pattern — a
+ * composition of a checkbox group and a toolbar). Mirrors the Gmail/admin UX where
+ * checking one or more rows reveals a sticky action bar with the selected count,
+ * select-all, and clear. Data Grid owns per-row `aria-selected`; this is the
+ * contextual action-bar layer on top.
+ *
+ * Markup contract (identifier: `stimeo--bulk-select`):
+ *   <div data-controller="stimeo--bulk-select"
+ *        data-stimeo--bulk-select-total-count-value="128">
+ *     <input type="checkbox" data-stimeo--bulk-select-target="all">
+ *     <!-- rows (may be added dynamically; handled via event delegation) -->
+ *     <input type="checkbox" data-stimeo--bulk-select-target="item">
+ *     <input type="checkbox" data-stimeo--bulk-select-target="item">
+ *     <div data-stimeo--bulk-select-target="bar" hidden role="toolbar" aria-live="polite">
+ *       <span data-stimeo--bulk-select-target="count"></span> selected
+ *       <button data-stimeo--bulk-select-target="selectAllPages"
+ *               data-action="click->stimeo--bulk-select#selectAllPages">Select all</button>
+ *       <button data-action="click->stimeo--bulk-select#clear">Clear</button>
+ *     </div>
+ *   </div>
+ *
+ * @remarks
+ * Behavior only — it never runs the batch action (that is the consumer's
+ * form/Turbo) nor fetches/pages rows. Selection lives **only** in each checkbox's
+ * `checked` (no module-scope set), so `connect()` recomputes idempotently from the
+ * DOM after a Turbo swap. Row `change` is handled by **delegation** on the
+ * container, so dynamically-added rows work without per-row `data-action`.
+ * Showing the bar never steals focus
+ * (WCAG 2.2 2.4.3); the count rides the bar's own `aria-live` region (WCAG 2.2
+ * 4.1.3) — the bar is revealed *before* the count text is written so the change is
+ * observed and announced. The delegated listener is removed on `disconnect()`.
+ */
+declare class BulkSelectController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        totalCount: {
+            type: NumberConstructor;
+            default: number;
+        };
+        announce: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+    };
+    static actions: readonly ["clear", "selectAllPages"];
+    static events: readonly ["change"];
+    readonly allTarget: HTMLInputElement;
+    readonly barTarget: HTMLElement;
+    readonly countTarget: HTMLElement;
+    readonly hasAllTarget: boolean;
+    readonly hasBarTarget: boolean;
+    readonly hasCountTarget: boolean;
+    totalCountValue: number;
+    announceValue: boolean;
+    connect(): void;
+    disconnect(): void;
+    /** Clears every selection (rows + select-all) and exits all-pages mode. */
+    clear(): void;
+    /** Enters "select all across pages" mode (count shows `totalCount`). */
+    selectAllPages(): void;
+}
+
+export { BulkSelectController };

package/dist/controllers/bulk_select_controller.js

@@ -0,0 +1,104 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/bulk_select_controller.ts
+var BulkSelectController = class extends Controller {
+  static targets = ["all", "item", "bar", "count", "selectAllPages"];
+  static values = {
+    totalCount: { type: Number, default: 0 },
+    announce: { type: Boolean, default: true }
+  };
+  static actions = ["clear", "selectAllPages"];
+  static events = ["change"];
+  /** All-pages mode is a transient UI state; mirrored to `data-all-pages` so it
+   *  survives a Turbo swap and `connect()` can rehydrate it. */
+  #allPagesMode = false;
+  /** Last emitted figures, so a recompute dispatches `change` only on real change. */
+  #lastCount = -1;
+  #lastAllPages = false;
+  /** Delegated `change` handler covering the select-all box and every row. */
+  #onChange = (event) => {
+    const target = event.target;
+    if (!target) return;
+    if (this.hasAllTarget && target === this.allTarget) {
+      this.#applyAll();
+    } else if (target.matches('[data-stimeo--bulk-select-target="item"]')) {
+      this.#exitAllPages();
+      this.#recompute(true);
+    }
+  };
+  connect() {
+    this.#allPagesMode = this.element.dataset.allPages === "true";
+    this.element.addEventListener("change", this.#onChange);
+    this.#recompute(false);
+  }
+  disconnect() {
+    this.element.removeEventListener("change", this.#onChange);
+  }
+  /** Clears every selection (rows + select-all) and exits all-pages mode. */
+  clear() {
+    for (const item of this.#items) item.checked = false;
+    if (this.hasAllTarget) {
+      this.allTarget.checked = false;
+      this.allTarget.indeterminate = false;
+    }
+    this.#exitAllPages();
+    this.#recompute(true);
+  }
+  /** Enters "select all across pages" mode (count shows `totalCount`). */
+  selectAllPages() {
+    this.#allPagesMode = true;
+    this.#recompute(true);
+  }
+  /** Mirrors the select-all box to every row, then recomputes. */
+  #applyAll() {
+    if (!this.hasAllTarget) return;
+    const { checked } = this.allTarget;
+    for (const item of this.#items) item.checked = checked;
+    this.#exitAllPages();
+    this.#recompute(true);
+  }
+  #exitAllPages() {
+    this.#allPagesMode = false;
+  }
+  /**
+   * Recomputes the count, the select-all checked/indeterminate state, and the bar
+   * visibility from the current DOM. Dispatches `change` (when `notify`) only if
+   * the emitted count or all-pages flag actually changed.
+   */
+  #recompute(notify) {
+    const items = this.#items;
+    const total = items.length;
+    const checked = items.filter((item) => item.checked).length;
+    const allPages = this.#allPagesMode;
+    if (this.hasAllTarget) {
+      this.allTarget.checked = total > 0 && checked === total;
+      this.allTarget.indeterminate = checked > 0 && checked < total;
+    }
+    const count = allPages ? this.totalCountValue : checked;
+    const show = allPages || checked > 0;
+    if (this.hasBarTarget) {
+      this.barTarget.hidden = !show;
+      this.barTarget.setAttribute("aria-live", this.announceValue ? "polite" : "off");
+    }
+    if (this.hasCountTarget) this.countTarget.textContent = String(count);
+    this.element.setAttribute("data-selected-count", String(checked));
+    if (allPages) this.element.setAttribute("data-all-pages", "true");
+    else this.element.removeAttribute("data-all-pages");
+    const changed = count !== this.#lastCount || allPages !== this.#lastAllPages;
+    this.#lastCount = count;
+    this.#lastAllPages = allPages;
+    if (notify && changed) {
+      this.dispatch("change", { detail: { count, allPages } });
+    }
+  }
+  /** Live list of row checkboxes, queried from the DOM so dynamic rows count. */
+  get #items() {
+    return Array.from(
+      this.element.querySelectorAll('[data-stimeo--bulk-select-target="item"]')
+    );
+  }
+};
+
+export { BulkSelectController };
+//# sourceMappingURL=bulk_select_controller.js.map
+//# sourceMappingURL=bulk_select_controller.js.map

package/dist/controllers/bulk_select_controller.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/controllers/bulk_select_controller.ts"],"names":[],"mappings":"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","file":"bulk_select_controller.js","sourcesContent":["import { Controller } from \"@hotwired/stimulus\";\n\n/**\n * Headless **bulk select / batch action bar** (no dedicated APG pattern — a\n * composition of a checkbox group and a toolbar). Mirrors the Gmail/admin UX where\n * checking one or more rows reveals a sticky action bar with the selected count,\n * select-all, and clear. Data Grid owns per-row `aria-selected`; this is the\n * contextual action-bar layer on top.\n *\n * Markup contract (identifier: `stimeo--bulk-select`):\n *   <div data-controller=\"stimeo--bulk-select\"\n *        data-stimeo--bulk-select-total-count-value=\"128\">\n *     <input type=\"checkbox\" data-stimeo--bulk-select-target=\"all\">\n *     <!-- rows (may be added dynamically; handled via event delegation) -->\n *     <input type=\"checkbox\" data-stimeo--bulk-select-target=\"item\">\n *     <input type=\"checkbox\" data-stimeo--bulk-select-target=\"item\">\n *     <div data-stimeo--bulk-select-target=\"bar\" hidden role=\"toolbar\" aria-live=\"polite\">\n *       <span data-stimeo--bulk-select-target=\"count\"></span> selected\n *       <button data-stimeo--bulk-select-target=\"selectAllPages\"\n *               data-action=\"click->stimeo--bulk-select#selectAllPages\">Select all</button>\n *       <button data-action=\"click->stimeo--bulk-select#clear\">Clear</button>\n *     </div>\n *   </div>\n *\n * @remarks\n * Behavior only — it never runs the batch action (that is the consumer's\n * form/Turbo) nor fetches/pages rows. Selection lives **only** in each checkbox's\n * `checked` (no module-scope set), so `connect()` recomputes idempotently from the\n * DOM after a Turbo swap. Row `change` is handled by **delegation** on the\n * container, so dynamically-added rows work without per-row `data-action`.\n * Showing the bar never steals focus\n * (WCAG 2.2 2.4.3); the count rides the bar's own `aria-live` region (WCAG 2.2\n * 4.1.3) — the bar is revealed *before* the count text is written so the change is\n * observed and announced. The delegated listener is removed on `disconnect()`.\n */\nexport class BulkSelectController extends Controller<HTMLElement> {\n  static override targets = [\"all\", \"item\", \"bar\", \"count\", \"selectAllPages\"];\n  static override values = {\n    totalCount: { type: Number, default: 0 },\n    announce: { type: Boolean, default: true },\n  };\n  static actions = [\"clear\", \"selectAllPages\"] as const;\n  static events = [\"change\"] as const;\n\n  declare readonly allTarget: HTMLInputElement;\n  declare readonly barTarget: HTMLElement;\n  declare readonly countTarget: HTMLElement;\n  declare readonly hasAllTarget: boolean;\n  declare readonly hasBarTarget: boolean;\n  declare readonly hasCountTarget: boolean;\n\n  declare totalCountValue: number;\n  declare announceValue: boolean;\n\n  /** All-pages mode is a transient UI state; mirrored to `data-all-pages` so it\n   *  survives a Turbo swap and `connect()` can rehydrate it. */\n  #allPagesMode = false;\n  /** Last emitted figures, so a recompute dispatches `change` only on real change. */\n  #lastCount = -1;\n  #lastAllPages = false;\n\n  /** Delegated `change` handler covering the select-all box and every row. */\n  readonly #onChange = (event: Event): void => {\n    const target = event.target as HTMLElement | null;\n    if (!target) return;\n    if (this.hasAllTarget && target === this.allTarget) {\n      this.#applyAll();\n    } else if (target.matches('[data-stimeo--bulk-select-target=\"item\"]')) {\n      this.#exitAllPages();\n      this.#recompute(true);\n    }\n  };\n\n  override connect(): void {\n    this.#allPagesMode = this.element.dataset.allPages === \"true\";\n    this.element.addEventListener(\"change\", this.#onChange);\n    this.#recompute(false);\n  }\n\n  override disconnect(): void {\n    this.element.removeEventListener(\"change\", this.#onChange);\n  }\n\n  /** Clears every selection (rows + select-all) and exits all-pages mode. */\n  clear(): void {\n    for (const item of this.#items) item.checked = false;\n    if (this.hasAllTarget) {\n      this.allTarget.checked = false;\n      this.allTarget.indeterminate = false;\n    }\n    this.#exitAllPages();\n    this.#recompute(true);\n  }\n\n  /** Enters \"select all across pages\" mode (count shows `totalCount`). */\n  selectAllPages(): void {\n    this.#allPagesMode = true;\n    this.#recompute(true);\n  }\n\n  /** Mirrors the select-all box to every row, then recomputes. */\n  #applyAll(): void {\n    if (!this.hasAllTarget) return;\n    const { checked } = this.allTarget;\n    for (const item of this.#items) item.checked = checked;\n    this.#exitAllPages();\n    this.#recompute(true);\n  }\n\n  #exitAllPages(): void {\n    this.#allPagesMode = false;\n  }\n\n  /**\n   * Recomputes the count, the select-all checked/indeterminate state, and the bar\n   * visibility from the current DOM. Dispatches `change` (when `notify`) only if\n   * the emitted count or all-pages flag actually changed.\n   */\n  #recompute(notify: boolean): void {\n    const items = this.#items;\n    const total = items.length;\n    const checked = items.filter((item) => item.checked).length;\n    const allPages = this.#allPagesMode;\n\n    if (this.hasAllTarget) {\n      this.allTarget.checked = total > 0 && checked === total;\n      this.allTarget.indeterminate = checked > 0 && checked < total;\n    }\n\n    const count = allPages ? this.totalCountValue : checked;\n    const show = allPages || checked > 0;\n\n    // Reveal the bar BEFORE writing the count so its aria-live region observes the\n    // text change (a region revealed after its content changed may not announce).\n    if (this.hasBarTarget) {\n      this.barTarget.hidden = !show;\n      this.barTarget.setAttribute(\"aria-live\", this.announceValue ? \"polite\" : \"off\");\n    }\n    if (this.hasCountTarget) this.countTarget.textContent = String(count);\n\n    this.element.setAttribute(\"data-selected-count\", String(checked));\n    if (allPages) this.element.setAttribute(\"data-all-pages\", \"true\");\n    else this.element.removeAttribute(\"data-all-pages\");\n\n    const changed = count !== this.#lastCount || allPages !== this.#lastAllPages;\n    this.#lastCount = count;\n    this.#lastAllPages = allPages;\n    if (notify && changed) {\n      this.dispatch(\"change\", { detail: { count, allPages } });\n    }\n  }\n\n  /** Live list of row checkboxes, queried from the DOM so dynamic rows count. */\n  get #items(): HTMLInputElement[] {\n    return Array.from(\n      this.element.querySelectorAll<HTMLInputElement>('[data-stimeo--bulk-select-target=\"item\"]'),\n    );\n  }\n}\n"]}

package/dist/controllers/calendar_controller.d.ts

@@ -0,0 +1,100 @@
+import { Controller } from '@hotwired/stimulus';
+
+/**
+ * Headless, highly accessible calendar grid behavior.
+ *
+ * Markup contract (identifier: `stimeo--calendar`):
+ *   <div data-controller="stimeo--calendar"
+ *        data-stimeo--calendar-month-value="2026-05"
+ *        data-stimeo--calendar-selected-value="2026-05-31">
+ *     <button data-action="stimeo--calendar#prev">Previous</button>
+ *     <span data-stimeo--calendar-target="label">May 2026</span>
+ *     <button data-action="stimeo--calendar#next">Next</button>
+ *     <table role="grid">
+ *       <tbody data-stimeo--calendar-target="grid"
+ *              data-action="keydown->stimeo--calendar#onKeydown
+ *                           click->stimeo--calendar#selectByClick">
+ *         <!-- Markup must contain exactly 42 day targets (7 days x 6 rows) -->
+ *         <tr role="row">
+ *           <td role="gridcell" data-stimeo--calendar-target="day" tabindex="-1"></td>
+ *         </tr>
+ *       </tbody>
+ *     </table>
+ *   </div>
+ *
+ * Implements the WAI-ARIA APG **Date Picker Dialog** grid navigation pattern:
+ * - Local-aware month/year labels using native `Intl.DateTimeFormat`.
+ * - Roving tabindex focus tracking (exactly one focusable day at any time).
+ * - Full grid keyboard controls (arrows, PageUp/Down, Home/End, Shift+PageUp/Down).
+ * - Automatic month wrapping and date clamping for missing dates (e.g. leap years, 31st to 30th).
+ *
+ * @remarks
+ * Behavior only. The controller updates classes, attributes (aria-selected, data-outside, etc.),
+ * and text contents dynamically on 42 pre-allocated `day` targets.
+ */
+declare class CalendarController extends Controller<HTMLElement> {
+    #private;
+    static targets: string[];
+    static values: {
+        month: {
+            type: StringConstructor;
+            default: string;
+        };
+        selected: {
+            type: StringConstructor;
+            default: string;
+        };
+        min: {
+            type: StringConstructor;
+            default: string;
+        };
+        max: {
+            type: StringConstructor;
+            default: string;
+        };
+        weekStart: {
+            type: NumberConstructor;
+            default: number;
+        };
+    };
+    static actions: readonly ["next", "onKeydown", "prev", "selectByClick"];
+    static events: readonly ["monthchange", "select"];
+    readonly labelTarget: HTMLElement;
+    readonly gridTarget: HTMLElement;
+    readonly dayTargets: HTMLElement[];
+    readonly hasLabelTarget: boolean;
+    readonly hasGridTarget: boolean;
+    monthValue: string;
+    selectedValue: string;
+    minValue: string;
+    maxValue: string;
+    weekStartValue: number;
+    /** The date currently receiving focus in the grid (local time). */
+    focusedDate: Date;
+    connect(): void;
+    /** Cancels any pending deferred focus so it never fires on a detached element. */
+    disconnect(): void;
+    /**
+     * Stimulus lifecycle callback triggered automatically when the monthValue changes.
+     * Forces a re-render of the date grid and updates labels.
+     */
+    monthValueChanged(): void;
+    /**
+     * Stimulus lifecycle callback triggered automatically when the selectedValue changes.
+     * Re-renders grid cells to update `aria-selected` indicators.
+     */
+    selectedValueChanged(): void;
+    /** Navigates to the previous month. */
+    prev(event?: Event): void;
+    /** Navigates to the next month. */
+    next(event?: Event): void;
+    /** Handles day selection when a gridcell is clicked. */
+    selectByClick(event: MouseEvent): void;
+    /** Handles grid cell keyboard navigation and triggers selection. */
+    onKeydown(event: KeyboardEvent): void;
+    /** Renders the grid days and updates the month/year label. */
+    render(): void;
+    selectDayElement(dayElement: HTMLElement): void;
+}
+
+export { CalendarController };

package/dist/controllers/calendar_controller.js

@@ -0,0 +1,394 @@
+import { Controller } from '@hotwired/stimulus';
+
+// src/controllers/calendar_controller.ts
+
+// src/utils/dates.ts
+function toISODateString(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+function parseISODateString(dateStr) {
+  if (!dateStr) return null;
+  const match = dateStr.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (!match) return null;
+  const [, y, m, d] = match;
+  const year = Number(y);
+  const month = Number(m);
+  const day = Number(d);
+  const date = new Date(year, month - 1, day);
+  if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day) {
+    return null;
+  }
+  return date;
+}
+function parseISOMonthString(monthStr) {
+  if (!monthStr) return null;
+  const match = monthStr.match(/^(\d{4})-(\d{2})$/);
+  if (!match) return null;
+  const [, y, m] = match;
+  const month = Number(m);
+  if (month < 1 || month > 12) return null;
+  return { year: Number(y), month };
+}
+
+// src/utils/safe_timeout.ts
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+
+// src/controllers/calendar_controller.ts
+var CalendarController = class extends Controller {
+  static targets = ["label", "grid", "day"];
+  static values = {
+    month: { type: String, default: "" },
+    selected: { type: String, default: "" },
+    min: { type: String, default: "" },
+    max: { type: String, default: "" },
+    weekStart: { type: Number, default: 0 }
+    // 0 = Sunday, 1 = Monday, etc.
+  };
+  static actions = ["next", "onKeydown", "prev", "selectByClick"];
+  static events = ["monthchange", "select"];
+  /** The date currently receiving focus in the grid (local time). */
+  focusedDate = /* @__PURE__ */ new Date();
+  /**
+   * Deferred focus moves scheduled after an asynchronous month transition.
+   * Tracked so {@link disconnect} can cancel any pending move and a detached
+   * controller never steals focus after the element leaves the DOM (Turbo).
+   */
+  #focusTimer = new SafeTimeout();
+  connect() {
+    if (!this.monthValue) {
+      const today = /* @__PURE__ */ new Date();
+      const monthStr = `${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, "0")}`;
+      this.monthValue = monthStr;
+      return;
+    }
+    this.#initializeFocusedDate();
+    this.render();
+  }
+  /** Cancels any pending deferred focus so it never fires on a detached element. */
+  disconnect() {
+    this.#focusTimer.clearAll();
+  }
+  /**
+   * Stimulus lifecycle callback triggered automatically when the monthValue changes.
+   * Forces a re-render of the date grid and updates labels.
+   */
+  monthValueChanged() {
+    if (!this.monthValue) return;
+    this.#syncFocusedDateWithMonth();
+    this.render();
+    this.dispatch("monthchange", { detail: { month: this.monthValue } });
+  }
+  /**
+   * Stimulus lifecycle callback triggered automatically when the selectedValue changes.
+   * Re-renders grid cells to update `aria-selected` indicators.
+   */
+  selectedValueChanged() {
+    if (this.selectedValue) {
+      const selected = parseISODateString(this.selectedValue);
+      if (selected) {
+        this.focusedDate = selected;
+      }
+    }
+    this.render();
+  }
+  /** Navigates to the previous month. */
+  prev(event) {
+    if (event) event.preventDefault();
+    this.#shiftMonth(-1);
+  }
+  /** Navigates to the next month. */
+  next(event) {
+    if (event) event.preventDefault();
+    this.#shiftMonth(1);
+  }
+  /** Handles day selection when a gridcell is clicked. */
+  selectByClick(event) {
+    const target = event.target;
+    if (!target) return;
+    const dayElement = target.closest("[data-stimeo--calendar-target='day']");
+    if (!dayElement) return;
+    this.selectDayElement(dayElement);
+  }
+  /** Handles grid cell keyboard navigation and triggers selection. */
+  onKeydown(event) {
+    const target = event.target;
+    if (!target) return;
+    const dayElement = target.closest("[data-stimeo--calendar-target='day']");
+    if (!dayElement) return;
+    const dateStr = dayElement.getAttribute("data-date");
+    if (!dateStr) return;
+    const date = parseISODateString(dateStr);
+    if (!date) return;
+    let handled = true;
+    let nextDate = new Date(date);
+    switch (event.key) {
+      case "ArrowLeft":
+        nextDate.setDate(nextDate.getDate() - 1);
+        break;
+      case "ArrowRight":
+        nextDate.setDate(nextDate.getDate() + 1);
+        break;
+      case "ArrowUp":
+        nextDate.setDate(nextDate.getDate() - 7);
+        break;
+      case "ArrowDown":
+        nextDate.setDate(nextDate.getDate() + 7);
+        break;
+      case "PageUp":
+        if (event.shiftKey) {
+          nextDate = this.#calculateShiftedYearDate(date, -1);
+        } else {
+          nextDate = this.#calculateShiftedMonthDate(date, -1);
+        }
+        break;
+      case "PageDown":
+        if (event.shiftKey) {
+          nextDate = this.#calculateShiftedYearDate(date, 1);
+        } else {
+          nextDate = this.#calculateShiftedMonthDate(date, 1);
+        }
+        break;
+      case "Home":
+        nextDate = this.#getStartOfWeekDate(date);
+        break;
+      case "End":
+        nextDate = this.#getEndOfWeekDate(date);
+        break;
+      case "t":
+      case "T": {
+        const now = /* @__PURE__ */ new Date();
+        nextDate = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+        break;
+      }
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        this.selectDayElement(dayElement);
+        return;
+      default:
+        handled = false;
+        break;
+    }
+    if (handled) {
+      event.preventDefault();
+      this.#focusAndNavigateToDate(nextDate);
+    }
+  }
+  /** Renders the grid days and updates the month/year label. */
+  render() {
+    const monthInfo = parseISOMonthString(this.monthValue);
+    if (!monthInfo) return;
+    const { year, month } = monthInfo;
+    if (this.hasLabelTarget) {
+      const lang = document.documentElement.lang || "en";
+      const labelDate = new Date(year, month - 1, 1);
+      const formatter = new Intl.DateTimeFormat(lang, { month: "long", year: "numeric" });
+      this.labelTarget.textContent = formatter.format(labelDate);
+    }
+    const days = this.#calculateGridDays(year, month);
+    const dayElements = this.dayTargets;
+    for (let i = 0; i < 42; i++) {
+      const el = dayElements[i];
+      if (!el) continue;
+      const date = days[i];
+      if (!date) continue;
+      const dateStr = toISODateString(date);
+      el.setAttribute("data-date", dateStr);
+      el.textContent = String(date.getDate());
+      const isOutside = date.getFullYear() !== year || date.getMonth() !== month - 1;
+      el.setAttribute("data-outside", String(isOutside));
+      const todayStr = toISODateString(/* @__PURE__ */ new Date());
+      el.setAttribute("data-today", String(dateStr === todayStr));
+      const isSelected = dateStr === this.selectedValue;
+      el.setAttribute("aria-selected", String(isSelected));
+      const isFocused = toISODateString(this.focusedDate) === dateStr;
+      el.setAttribute("tabindex", isFocused ? "0" : "-1");
+      const isDisabled = this.#isDateOutOfBounds(dateStr);
+      if (isDisabled) {
+        el.setAttribute("aria-disabled", "true");
+      } else {
+        el.removeAttribute("aria-disabled");
+      }
+    }
+  }
+  selectDayElement(dayElement) {
+    if (dayElement.getAttribute("aria-disabled") === "true") return;
+    const dateStr = dayElement.getAttribute("data-date");
+    if (!dateStr) return;
+    this.selectedValue = dateStr;
+    const selected = parseISODateString(dateStr);
+    if (selected) this.focusedDate = selected;
+    this.render();
+    this.dispatch("select", { detail: { date: dateStr } });
+  }
+  #focusAndNavigateToDate(date) {
+    this.focusedDate = date;
+    const targetMonthStr = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
+    const isMonthTransition = targetMonthStr !== this.monthValue;
+    if (isMonthTransition) {
+      this.monthValue = targetMonthStr;
+    } else {
+      this.render();
+    }
+    const focusTarget = () => {
+      const dateStr = toISODateString(date);
+      const targetEl = this.dayTargets.find((el) => el.getAttribute("data-date") === dateStr);
+      targetEl?.focus();
+    };
+    if (isMonthTransition) {
+      this.#focusTimer.set(focusTarget, 0);
+    } else {
+      focusTarget();
+    }
+  }
+  #isDateOutOfBounds(dateStr) {
+    if (this.minValue && dateStr < this.minValue) return true;
+    if (this.maxValue && dateStr > this.maxValue) return true;
+    return false;
+  }
+  #shiftMonth(delta) {
+    const monthInfo = parseISOMonthString(this.monthValue);
+    if (!monthInfo) return;
+    const nextMonthDate = new Date(monthInfo.year, monthInfo.month - 1 + delta, 1);
+    this.monthValue = `${nextMonthDate.getFullYear()}-${String(nextMonthDate.getMonth() + 1).padStart(2, "0")}`;
+  }
+  #calculateShiftedMonthDate(baseDate, delta) {
+    const targetDate = new Date(baseDate.getFullYear(), baseDate.getMonth() + delta, 1);
+    const lastDayInTarget = new Date(
+      targetDate.getFullYear(),
+      targetDate.getMonth() + 1,
+      0
+    ).getDate();
+    const clampedDay = Math.min(baseDate.getDate(), lastDayInTarget);
+    targetDate.setDate(clampedDay);
+    return targetDate;
+  }
+  #calculateShiftedYearDate(baseDate, delta) {
+    const targetDate = new Date(baseDate.getFullYear() + delta, baseDate.getMonth(), 1);
+    const lastDayInTarget = new Date(
+      targetDate.getFullYear(),
+      targetDate.getMonth() + 1,
+      0
+    ).getDate();
+    const clampedDay = Math.min(baseDate.getDate(), lastDayInTarget);
+    targetDate.setDate(clampedDay);
+    return targetDate;
+  }
+  #getStartOfWeekDate(date) {
+    const currentDay = date.getDay();
+    const shift = (currentDay - this.weekStartValue + 7) % 7;
+    const target = new Date(date);
+    target.setDate(date.getDate() - shift);
+    return target;
+  }
+  #getEndOfWeekDate(date) {
+    const start = this.#getStartOfWeekDate(date);
+    const target = new Date(start);
+    target.setDate(start.getDate() + 6);
+    return target;
+  }
+  #initializeFocusedDate() {
+    if (this.selectedValue) {
+      const selected = parseISODateString(this.selectedValue);
+      if (selected) {
+        this.focusedDate = selected;
+        return;
+      }
+    }
+    const monthInfo = parseISOMonthString(this.monthValue);
+    if (monthInfo) {
+      const today = /* @__PURE__ */ new Date();
+      if (today.getFullYear() === monthInfo.year && today.getMonth() === monthInfo.month - 1) {
+        this.focusedDate = today;
+      } else {
+        this.focusedDate = new Date(monthInfo.year, monthInfo.month - 1, 1);
+      }
+    }
+  }
+  #syncFocusedDateWithMonth() {
+    const monthInfo = parseISOMonthString(this.monthValue);
+    if (!monthInfo) return;
+    if (this.focusedDate.getFullYear() !== monthInfo.year || this.focusedDate.getMonth() !== monthInfo.month - 1) {
+      const today = /* @__PURE__ */ new Date();
+      if (today.getFullYear() === monthInfo.year && today.getMonth() === monthInfo.month - 1) {
+        this.focusedDate = today;
+      } else {
+        const targetDate = new Date(monthInfo.year, monthInfo.month - 1, 1);
+        const lastDayInTarget = new Date(monthInfo.year, monthInfo.month, 0).getDate();
+        const clampedDay = Math.min(this.focusedDate.getDate(), lastDayInTarget);
+        targetDate.setDate(clampedDay);
+        this.focusedDate = targetDate;
+      }
+    }
+  }
+  #calculateGridDays(year, month) {
+    const firstDay = new Date(year, month - 1, 1);
+    const dayOfWeek = firstDay.getDay();
+    const offset = (dayOfWeek - this.weekStartValue + 7) % 7;
+    const days = [];
+    const current = new Date(firstDay);
+    current.setDate(firstDay.getDate() - offset);
+    for (let i = 0; i < 42; i++) {
+      days.push(new Date(current));
+      current.setDate(current.getDate() + 1);
+    }
+    return days;
+  }
+};
+
+export { CalendarController };
+//# sourceMappingURL=calendar_controller.js.map
+//# sourceMappingURL=calendar_controller.js.map