Fix wrong month in date picker calendar header

.agents/skills/ha-frontend-components/SKILL.md

@@ -7,8 +7,6 @@ description: Home Assistant frontend component patterns. Use when implementing o
 
 Use this skill when creating or reviewing Home Assistant UI components and common interaction patterns.
 
-Cross-load `ha-frontend-events` when component work includes event listener typing, custom event dispatch, or event-map declarations.
-
 ## Dialogs
 
 Open dialogs through the fire-event pattern:

.agents/skills/ha-frontend-events/SKILL.md

@@ -1,105 +0,0 @@
----
-name: ha-frontend-events
-description: Home Assistant frontend event patterns. Use when typing event handlers, using HASSDomEvent types, dispatching with fireEvent, or declaring HASSDomEvents and event maps.
----
-
-# HA Frontend Events
-
-Use this skill when implementing or reviewing event listeners and custom event contracts. Cross-load `ha-frontend-components` when the work also involves dialogs, forms, alerts, shortcuts, tooltips, panels, Lovelace cards, or buttons.
-
-## Event Handling
-
-Use the event types from `src/common/dom/fire_event.ts` instead of plain `Event`, generic `CustomEvent`, or element casts when they express the handler contract:
-
-- Use `HASSDomCurrentTargetEvent<T>` to read the element on which the listener was registered through `ev.currentTarget`.
-- Use `HASSDomTargetEvent<T>` only to read the element that originated the event through `ev.target`.
-- Use `HASSDomEvent<T>` to read a custom event payload through `ev.detail`.
-- Use `ValueChangedEvent<T>` from `src/types.ts` for the standard `value-changed` event.
-- Prefer an event type exported by the component being listened to, such as `HaSelectSelectEvent<T, Clearable>` or `HaDropdownSelectEvent<TValue, TData>`, over reconstructing its detail type.
-- Use `ActionHandlerEvent` from `src/data/lovelace/action_handler.ts` for Lovelace tap, hold, and double-tap handlers.
-
-Import event and element types with `import type`:
-
-```ts
-import type {
-  HASSDomCurrentTargetEvent,
-  HASSDomEvent,
-  HASSDomTargetEvent,
-} from "../common/dom/fire_event";
-import type { HaCheckbox } from "../components/ha-checkbox";
-import type { HaEntityPicker } from "../components/entity/ha-entity-picker";
-import type { HaRadioGroup } from "../components/radio/ha-radio-group";
-import type { ValueChangedEvent } from "../types";
-```
-
-Type the handler so the selected property can be read directly. Do not cast `ev.currentTarget` or assign it to a single-use variable:
-
-```ts
-private _scopeChanged(ev: HASSDomCurrentTargetEvent<HaRadioGroup>): void {
-  this._scope = ev.currentTarget.value;
-}
-
-private _checkedChanged(ev: HASSDomTargetEvent<HaCheckbox>): void {
-  this._checked = ev.target.checked;
-}
-
-private _valueChanged(ev: ValueChangedEvent<string>): void {
-  this._value = ev.detail.value;
-}
-
-private _itemSelected(ev: HASSDomEvent<{ id: string }>): void {
-  this._selectedId = ev.detail.id;
-}
-```
-
-Use intersections when a handler needs more than one facet of an event. Keep the native event type when the handler reads native fields such as `key`, modifier keys, `dataTransfer`, or focus relationships:
-
-```ts
-private _entityChanged(
-  ev: ValueChangedEvent<string> & HASSDomCurrentTargetEvent<HaEntityPicker>
-): void {
-  ev.currentTarget.value = ev.detail.value;
-}
-
-private _keyDown(
-  ev: KeyboardEvent & HASSDomCurrentTargetEvent<HTMLInputElement>
-): void {
-  if (ev.key === "Enter") {
-    this._submit(ev.currentTarget.value);
-  }
-}
-```
-
-Dispatch Home Assistant component events with `fireEvent()` instead of constructing `Event` or `CustomEvent` directly. Register the event name and detail type by augmenting `HASSDomEvents`; use `undefined` when an event has no detail. `fireEvent()` constrains event names and supplied detail, and events bubble and cross shadow boundaries by default:
-
-```ts
-fireEvent(this, "item-selected", { id: item.id });
-fireEvent(this, "refresh-requested");
-```
-
-When an event is already registered, derive handler and listener types from its registration rather than repeating the payload shape:
-
-```ts
-private _itemSelected(
-  ev: HASSDomEvent<HASSDomEvents["item-selected"]>
-): void {
-  this._selectedId = ev.detail.id;
-}
-```
-
-`HASSDomEvents` types `fireEvent()` calls. Augment `HTMLElementEventMap` for typed listeners on HTML elements, or `GlobalEventHandlersEventMap` when the event is handled on global event targets.
-
-In component files, prefer placing global event declarations after the class at the bottom of the file. Preserve the existing placement when editing established files; foundational type, helper, and mixin files commonly keep declarations near the top before their consumers.
-
-```ts
-declare global {
-  interface HASSDomEvents {
-    "item-selected": { id: string };
-    "refresh-requested": undefined;
-  }
-
-  interface HTMLElementEventMap {
-    "item-selected": HASSDomEvent<HASSDomEvents["item-selected"]>;
-  }
-}
-```

.agents/skills/ha-frontend-review/SKILL.md

@@ -70,4 +70,4 @@ Configuration and props:
 - Identify behavioral regressions, bugs, accessibility issues, and missing tests first.
 - Keep style-only comments secondary unless they affect maintainability or user experience.
 - Prefer small, direct fixes over large refactors during review follow-up.
-- Cross-load `ha-frontend-contexts`, `ha-frontend-components`, `ha-frontend-events`, `ha-frontend-styling`, `ha-frontend-testing`, or `ha-frontend-user-facing-text` when a finding falls in that area.
+- Cross-load `ha-frontend-contexts`, `ha-frontend-components`, `ha-frontend-styling`, `ha-frontend-testing`, or `ha-frontend-user-facing-text` when a finding falls in that area.

AGENTS.md

@@ -40,7 +40,6 @@ Detailed guidance lives in project skills under `.agents/skills/`. Load the matc
 
 - `ha-frontend-contexts`: Lit contexts, `hass` migration, and rerender-sensitive state access.
 - `ha-frontend-components`: dialogs, forms, alerts, shortcuts, tooltips, panels, and Lovelace cards.
-- `ha-frontend-events`: event handler typing, custom event dispatch, and event-map declarations.
 - `ha-frontend-styling`: theme variables, spacing tokens, responsive layout, RTL, and view transitions.
 - `ha-frontend-testing`: lint, typecheck, Vitest, Playwright e2e dev servers, and benchmarks.
 - `ha-frontend-user-facing-text`: localization, terminology, sentence case, and Home Assistant text style.

package.json

@@ -196,7 +196,7 @@
     "jsdom": "30.0.1",
     "jszip": "3.10.1",
     "license-checker-rseidelsohn": "5.0.1",
-    "lint-staged": "17.3.0",
+    "lint-staged": "17.2.0",
     "lit-analyzer": "2.0.3",
     "lodash.merge": "4.6.2",
     "lodash.template": "4.18.1",

src/common/datetime/format_date.ts

@@ -294,3 +294,26 @@ export const formatCallyDateRange = (
 
   return `${startDate}/${endDate}`;
 };
+
+/**
+ * August 2021, for calendar days coming out of cally.
+ *
+ * cally hands out calendar days as `Date` objects anchored to UTC midnight, and
+ * formats its own headings in UTC too. Anything derived from a cally event has
+ * to be formatted the same way: the resolved time zone shifts the day back for
+ * negative UTC offsets, which becomes a wrong month — and in January a wrong
+ * year — whenever the day is the 1st.
+ */
+export const formatCallyMonthYear = (
+  dateObj: Date,
+  locale: FrontendLocaleData
+) => formatCallyMonthYearMem(locale.language).format(dateObj);
+
+const formatCallyMonthYearMem = memoizeOne(
+  (language: string) =>
+    new Intl.DateTimeFormat(language, {
+      month: "long",
+      year: "numeric",
+      timeZone: "UTC",
+    })
+);

src/components/date-picker/date-range-picker.ts

@@ -9,8 +9,8 @@ import { customElement, property, queryAll, state } from "lit/decorators";
 import { firstWeekdayIndex } from "../../common/datetime/first_weekday";
 import {
   formatCallyDateRange,
-  formatDateMonth,
-  formatDateYear,
+  formatCallyMonthYear,
+  formatDateMonthYear,
   formatISODateOnly,
 } from "../../common/datetime/format_date";
 import { transform } from "../../common/decorators/transform";
@@ -56,13 +56,16 @@ export class DateRangePicker extends MobileAwareMixin(LitElement) {
   })
   private _hassConfig!: HassConfig;
 
-  /** used to show month in calendar-range header */
-  @state() private _pickerMonth?: string;
+  /** used to show month and year in calendar-range header */
+  @state() private _pickerMonthYear?: string;
 
-  /** used to show year in calendar-date header */
-  @state() private _pickerYear?: string;
-
-  /** used for today to navigate focus in calendar-range  */
+  /**
+   * used for today to navigate focus in calendar-range
+   *
+   * Always mirrors the day calendar-range has focused, never cleared: once this
+   * has held a date, rendering `undefined` over it makes cally fall back to the
+   * selected range and page the calendar away from where the user is.
+   */
   @state() private _focusDate?: string;
 
   @state() private _dateValue?: string;
@@ -88,12 +91,7 @@ export class DateRangePicker extends MobileAwareMixin(LitElement) {
             this._hassConfig
           )
         : undefined;
-    this._pickerMonth = formatDateMonth(
-      date,
-      this._i18n.locale,
-      this._hassConfig
-    );
-    this._pickerYear = formatDateYear(
+    this._pickerMonthYear = formatDateMonthYear(
       date,
       this._i18n.locale,
       this._hassConfig
@@ -163,9 +161,7 @@ export class DateRangePicker extends MobileAwareMixin(LitElement) {
               slot="previous"
             ></ha-icon-button-prev>
             <div class="heading" slot="heading">
-              <span class="month-year"
-                >${this._pickerMonth} ${this._pickerYear}</span
-              >
+              <span class="month-year">${this._pickerMonthYear}</span>
               <ha-icon-button
                 @click=${this._focusToday}
                 .path=${mdiCalendarToday}
@@ -229,12 +225,7 @@ export class DateRangePicker extends MobileAwareMixin(LitElement) {
       this._i18n.locale,
       this._hassConfig
     );
-    this._pickerMonth = formatDateMonth(
-      date,
-      this._i18n.locale,
-      this._hassConfig
-    );
-    this._pickerYear = formatDateYear(
+    this._pickerMonthYear = formatDateMonthYear(
       date,
       this._i18n.locale,
       this._hassConfig
@@ -308,24 +299,15 @@ export class DateRangePicker extends MobileAwareMixin(LitElement) {
   }
 
   private _focusChanged(ev: CustomEvent<Date>) {
-    const date = ev.detail;
-    this._pickerMonth = formatDateMonth(
-      date,
-      this._i18n.locale,
-      this._hassConfig
-    );
-    this._pickerYear = formatDateYear(
-      date,
-      this._i18n.locale,
-      this._hassConfig
-    );
-    this._focusDate = undefined;
+    const dateElement = ev.target as HTMLElementTagNameMap["calendar-range"];
+    this._pickerMonthYear = formatCallyMonthYear(ev.detail, this._i18n.locale);
+    this._focusDate = dateElement.focusedDate;
   }
 
   private _handleChange(ev: CustomEvent) {
     const dateElement = ev.target as HTMLElementTagNameMap["calendar-range"];
     this._dateValue = dateElement.value;
-    this._focusDate = undefined;
+    this._focusDate = dateElement.focusedDate;
   }
 
   private _clickDateRangeChip(ev: Event) {

src/components/date-picker/ha-dialog-date-picker.ts

@@ -6,7 +6,8 @@ import type { HassConfig } from "home-assistant-js-websocket/dist/types";
 import { css, html, LitElement, nothing } from "lit";
 import { customElement, state } from "lit/decorators";
 import {
-  formatDateMonth,
+  formatCallyMonthYear,
+  formatDateMonthYear,
   formatDateShort,
   formatDateYear,
   formatISODateOnly,
@@ -56,13 +57,16 @@ export class HaDialogDatePicker extends DialogMixin<DatePickerDialogParams>(
     dateString: string;
   };
 
-  /** used to show month in calendar-date header */
-  @state() private _pickerMonth?: string;
+  /** used to show month and year in calendar-date header */
+  @state() private _pickerMonthYear?: string;
 
-  /** used to show year in calendar-date header */
-  @state() private _pickerYear?: string;
-
-  /** used for today to navigate focus in cally-calendar-date  */
+  /**
+   * used for today to navigate focus in cally-calendar-date
+   *
+   * Always mirrors the day calendar-date has focused, never cleared: once this
+   * has held a date, rendering `undefined` over it makes cally fall back to the
+   * selected value and page the calendar away from where the user is.
+   */
   @state() private _focusDate?: string;
 
   public connectedCallback() {
@@ -71,12 +75,7 @@ export class HaDialogDatePicker extends DialogMixin<DatePickerDialogParams>(
     if (this.params) {
       const date = valueToDate(this.params.value);
 
-      this._pickerYear = formatDateYear(
-        date,
-        this._i18n.locale,
-        this._hassConfig
-      );
-      this._pickerMonth = formatDateMonth(
+      this._pickerMonthYear = formatDateMonthYear(
         date,
         this._i18n.locale,
         this._hassConfig
@@ -84,7 +83,7 @@ export class HaDialogDatePicker extends DialogMixin<DatePickerDialogParams>(
 
       this._value = this.params.value
         ? {
-            year: this._pickerYear,
+            year: formatDateYear(date, this._i18n.locale, this._hassConfig),
             title: formatDateShort(date, this._i18n.locale, this._hassConfig),
             dateString: formatISODateOnly(
               date,
@@ -140,9 +139,7 @@ export class HaDialogDatePicker extends DialogMixin<DatePickerDialogParams>(
           slot="previous"
         ></ha-icon-button-prev>
         <div class="heading" slot="heading">
-          <span class="month-year"
-            >${this._pickerMonth} ${this._pickerYear}</span
-          >
+          <span class="month-year">${this._pickerMonthYear}</span>
           <ha-icon-button
             @click=${this._setToday}
             .path=${mdiCalendarToday}
@@ -185,12 +182,7 @@ export class HaDialogDatePicker extends DialogMixin<DatePickerDialogParams>(
 
     if (setFocusDay) {
       this._focusDate = this._value.dateString;
-      this._pickerMonth = formatDateMonth(
-        date,
-        this._i18n.locale,
-        this._hassConfig
-      );
-      this._pickerYear = formatDateYear(
+      this._pickerMonthYear = formatDateMonthYear(
         date,
         this._i18n.locale,
         this._hassConfig
@@ -199,18 +191,9 @@ export class HaDialogDatePicker extends DialogMixin<DatePickerDialogParams>(
   }
 
   private _focusChanged(ev: CustomEvent<Date>) {
-    const date = ev.detail;
-    this._pickerMonth = formatDateMonth(
-      date,
-      this._i18n.locale,
-      this._hassConfig
-    );
-    this._pickerYear = formatDateYear(
-      date,
-      this._i18n.locale,
-      this._hassConfig
-    );
-    this._focusDate = undefined;
+    const dateElement = ev.target as CalendarDate;
+    this._pickerMonthYear = formatCallyMonthYear(ev.detail, this._i18n.locale);
+    this._focusDate = dateElement.focusedDate;
   }
 
   private _clear() {

test/common/datetime/format_date.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
+  formatCallyMonthYear,
   formatDate,
   formatDateWeekdayDay,
   formatDateShort,
@@ -263,4 +264,43 @@ describe("formatDate", () => {
       ).toBe("Sat");
     });
   });
+
+  describe("formatCallyMonthYear", () => {
+    // How cally hands out a calendar day: a Date anchored to UTC midnight
+    const julyFirst = new Date(Date.UTC(2026, 6, 1));
+    const januaryFirst = new Date(Date.UTC(2026, 0, 1));
+
+    // demoConfig.time_zone is America/Los_Angeles, so this resolves to a
+    // negative UTC offset whatever zone the tests run in
+    const locale = {
+      language: "en",
+      number_format: NumberFormat.language,
+      time_format: TimeFormat.language,
+      date_format: DateFormat.language,
+      time_zone: TimeZone.server,
+      first_weekday: FirstWeekday.language,
+    };
+
+    it("Formats in UTC rather than the resolved time zone", () => {
+      // A time zone aware formatter reads UTC midnight on the 1st as the
+      // previous month, which desyncs the header from the calendar grid
+      expect(formatDateMonthYear(julyFirst, locale, demoConfig)).toBe(
+        "June 2026"
+      );
+      expect(formatCallyMonthYear(julyFirst, locale)).toBe("July 2026");
+    });
+
+    it("Keeps the year on a January page", () => {
+      expect(formatDateMonthYear(januaryFirst, locale, demoConfig)).toBe(
+        "December 2025"
+      );
+      expect(formatCallyMonthYear(januaryFirst, locale)).toBe("January 2026");
+    });
+
+    it("Orders month and year by locale", () => {
+      expect(
+        formatCallyMonthYear(julyFirst, { ...locale, language: "ja" })
+      ).toBe("2026年7月");
+    });
+  });
 });

yarn.lock

@@ -10015,7 +10015,7 @@ __metadata:
     leaflet-draw: "patch:leaflet-draw@npm%3A1.0.4#./.yarn/patches/leaflet-draw-npm-1.0.4-0ca0ebcf65.patch"
     leaflet.markercluster: "npm:1.5.3"
     license-checker-rseidelsohn: "npm:5.0.1"
-    lint-staged: "npm:17.3.0"
+    lint-staged: "npm:17.2.0"
     lit: "npm:3.3.3"
     lit-analyzer: "npm:2.0.3"
     lit-html: "npm:3.3.3"
@@ -11408,9 +11408,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"lint-staged@npm:17.3.0":
-  version: 17.3.0
-  resolution: "lint-staged@npm:17.3.0"
+"lint-staged@npm:17.2.0":
+  version: 17.2.0
+  resolution: "lint-staged@npm:17.2.0"
   dependencies:
     picomatch: "npm:^4.0.5"
     string-argv: "npm:^0.3.2"
@@ -11421,7 +11421,7 @@ __metadata:
       optional: true
   bin:
     lint-staged: bin/lint-staged.js
-  checksum: 10/52510d48c6b4aabeb61f84ad77f785f3af17fbfa517be8881de45144723df873996d767d9a7cf3bee4057037960ea5236fe3ac47a5d60fa9538078061b254445
+  checksum: 10/7c26129d6dd27f20d8fc8d70b13252f15baf569124721d7f5e9ed289e054ed43f5cc2a35de4129b65a7c7f1ad4a5900859a7488f8a1f0b96428b995b29ec2ba8
   languageName: node
   linkType: hard