Merge branch 'dev' into add-solar-power-badge

Author: TurboJonte

.github/copilot-instructions.md

@@ -2,12 +2,13 @@
 
 You are an assistant helping with development of the Home Assistant frontend. The frontend is built using Lit-based Web Components and TypeScript, providing a responsive and performant interface for home automation control.
 
-**Note**: This file contains high-level guidelines and references to implementation patterns. For detailed component documentation, API references, and usage examples, refer to the `gallery/` directory.
+**Note**: This file contains high-level guidelines and references to implementation patterns. For gallery-specific documentation, demos, page structure, and usage examples, see [`gallery/AGENTS.md`](gallery/AGENTS.md).
 
 ## Table of Contents
 
 - [Quick Reference](#quick-reference)
 - [Core Architecture](#core-architecture)
+- [State Access: Contexts Instead of `hass`](#state-access-contexts-instead-of-hass)
 - [Development Standards](#development-standards)
 - [Component Library](#component-library)
 - [Common Patterns](#common-patterns)
@@ -52,6 +53,57 @@ The Home Assistant frontend is a modern web application that:
 - Communicates with the backend via WebSocket API
 - Provides comprehensive theming and internationalization
 
+## State Access: Contexts Instead of `hass`
+
+Every component used to take the whole `hass: HomeAssistant` object — a god-object that re-renders on any unrelated `hass` change, forces tests to mock everything, and hides what a component actually reads. We're moving leaf components to **fine-grained [Lit context](https://lit.dev/docs/data/context/)**: consume only the slice you need and re-render only when it changes.
+
+For new code, consume the matching context instead of adding a `hass` property. `hass` stays for container components that own it and feed the providers; the canonical migration is [`hui-button-card.ts`](src/panels/lovelace/cards/hui-button-card.ts). Infrastructure: contexts in [`src/data/context/index.ts`](src/data/context/index.ts), the `consume…` helpers in [`src/common/decorators/consume-context-entry.ts`](src/common/decorators/consume-context-entry.ts), and `@transform` in [`src/common/decorators/transform.ts`](src/common/decorators/transform.ts). Providers are wired automatically by `contextMixin` on `HassBaseEl` — you only consume.
+
+### Contexts
+
+Consume the narrowest context that covers your reads:
+
+| Context                                                                 | Replaces                                                                                  |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `statesContext`                                                         | `hass.states`                                                                             |
+| `entitiesContext` / `devicesContext` / `areasContext` / `floorsContext` | `hass.entities` / `.devices` / `.areas` / `.floors` (or `registriesContext` for all four) |
+| `servicesContext`                                                       | `hass.services`                                                                           |
+| `internationalizationContext`                                           | `hass.localize`, `hass.locale`, `hass.language`                                           |
+| `formattersContext`                                                     | `hass.formatEntityName`, `hass.formatEntityState`, `hass.formatEntityAttributeName`, …    |
+| `configContext`                                                         | `hass.config`, `hass.user`, `hass.auth`, `hass.userData`                                  |
+| `connectionContext`                                                     | `hass.connection`, `hass.connected`, `hass.hassUrl`                                       |
+| `apiContext`                                                            | `hass.callService`, `hass.callApi`, `hass.callWS`, `hass.sendWS`, `hass.fetchWithAuth`    |
+| `uiContext`                                                             | `hass.themes`, `hass.selectedTheme`, `hass.panels`, `hass.dockedSidebar`, …               |
+| `narrowViewportContext`                                                 | narrow-layout boolean                                                                     |
+
+Lazy contexts (subscribe on first consumer, tear down after the last): `labelsContext`, `fullEntitiesContext`, `configEntriesContext`, `manifestsContext`. The single-field contexts (`localizeContext`, `themesContext`, `userContext`, …) are **deprecated** — use the grouped ones above.
+
+### Consuming
+
+Use the `consume…` helpers for entity-scoped and `localize` reads. `entityIdPath` is resolved against `this`, so these watch `this._config.entity`:
+
+```ts
+@state() @consumeEntityState({ entityIdPath: ["_config", "entity"] })
+private _stateObj?: HassEntity; // consumeEntityStates(...) for a record of several
+
+@state() @consumeEntityRegistryEntry({ entityIdPath: ["_config", "entity"] })
+private _entity?: EntityRegistryDisplayEntry;
+
+@state() @consumeLocalize()
+private _localize!: LocalizeFunc;
+```
+
+For any other single field, pair `@consume` with `@transform`:
+
+```ts
+@state()
+@consume({ context: uiContext, subscribe: true })
+@transform<HomeAssistantUI, Themes>({ transformer: ({ themes }) => themes })
+private _themes!: Themes;
+```
+
+`@transform`'s `watch` option re-runs the transformer when a host prop changes — needed when an entity id is computed, since `consumeEntityState` only watches the first path segment. To consume a whole group untransformed, drop `@transform` and type it `ContextType<typeof statesContext>`.
+
 ## Development Standards
 
 ### Code Quality Requirements
@@ -136,6 +188,7 @@ export class HaMyComponent extends LitElement {
 ### Data Management
 
 - **Use WebSocket API**: All backend communication via home-assistant-js-websocket
+- **Prefer contexts over `hass`**: For state reads, consume the relevant Lit context instead of taking the whole `hass` object — see [State Access: Contexts Instead of `hass`](#state-access-contexts-instead-of-hass)
 - **Cache appropriately**: Use collections and caching for frequently accessed data
 - **Handle errors gracefully**: All API calls should have error handling
 - **Update real-time**: Subscribe to state changes for live updates
@@ -285,11 +338,6 @@ Common patterns:
 - **Destructive actions**: `variant="danger"` for delete/remove operations (the generic confirmation dialog uses `variant="danger"` for its confirm button — see `src/dialogs/generic/dialog-box.ts`)
 - Always place primary action in `slot="primaryAction"` and secondary in `slot="secondaryAction"` within `ha-dialog-footer`
 
-**Gallery Documentation:**
-
-- `gallery/src/pages/components/ha-dialog.markdown`
-- `gallery/src/pages/components/ha-dialogs.markdown`
-
 ### Form Component (ha-form)
 
 - Schema-driven using `HaFormSchema[]`
@@ -308,10 +356,6 @@ Common patterns:
 ></ha-form>
 ```
 
-**Gallery Documentation:**
-
-- `gallery/src/pages/components/ha-form.markdown`
-
 ### Alert Component (ha-alert)
 
 - Types: `error`, `warning`, `info`, `success`
@@ -325,10 +369,6 @@ Common patterns:
 <ha-alert alert-type="success" dismissable>Success message</ha-alert>
 ```
 
-**Gallery Documentation:**
-
-- `gallery/src/pages/components/ha-alert.markdown`
-
 ### Keyboard Shortcuts (ShortcutManager)
 
 The `ShortcutManager` class provides a unified way to register keyboard shortcuts with automatic input field protection.
@@ -352,7 +392,6 @@ The `ha-tooltip` component wraps Web Awesome tooltip with Home Assistant theming
 
 - **Component definition**: `src/components/ha-tooltip.ts`
 - **Usage example**: `src/components/ha-label.ts`
-- **Gallery documentation**: `gallery/src/pages/components/ha-tooltip.markdown`
 
 ## Common Patterns
 
@@ -382,7 +421,7 @@ export class HaPanelMyFeature extends SubscribeMixin(LitElement) {
 
 #### Creating a Lovelace Card
 
-**Purpose**: Cards allow users to tell different stories about their house (based on gallery)
+**Purpose**: Cards allow users to tell different stories about their house.
 
 ```typescript
 @customElement("hui-my-card")
@@ -455,6 +494,10 @@ this.hass.localize("ui.panel.config.updates.update_available", {
 4. **Test**: `yarn test` - Add and run tests
 5. **Build**: `script/build_frontend` - Test production build
 
+### Gallery
+
+For Gallery-specific structure, page/demo naming, sidebar behavior, content standards, and commands, see [`gallery/AGENTS.md`](gallery/AGENTS.md).
+
 ### Common Pitfalls to Avoid
 
 - Don't manually query the DOM with `querySelector` - use the `@query`/`@queryAll` decorators or component properties
@@ -485,7 +528,7 @@ When creating a pull request, you **must** use the PR template located at `.gith
 
 #### Terminology Standards
 
-**Delete vs Remove** (Based on gallery/src/pages/Text/remove-delete-add-create.markdown)
+**Delete vs Remove**
 
 - **Use "Remove"** for actions that can be restored or reapplied:
   - Removing a user's permission

.github/workflows/blocking-labels.yaml

@@ -0,0 +1,50 @@
+name: Blocking labels
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - labeled
+      - unlabeled
+    branches:
+      - dev
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Check for labels which block the Pull Request from being merged
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for blocking labels
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const blockingLabels = [
+              "wait for backend",
+              "Needs UX",
+              "Do Not Review",
+              "Blocked",
+              "has-parent",
+            ];
+            const prLabels = context.payload.pull_request.labels.map(
+              (l) => l.name
+            );
+            const found = blockingLabels.filter((bl) => prLabels.includes(bl));
+            if (found.length > 0) {
+              const message = `This Pull Request is blocked by label${found.length > 1 ? "s" : ""}: ${found.join(", ")}`;
+              await core.summary
+                .addHeading(":no_entry_sign: Pull Request is blocked", 2)
+                .addRaw(message)
+                .write();
+              core.setFailed(message);
+            } else {
+              await core.summary
+                .addHeading(":white_check_mark: Pull Request is clear to merge after review", 2)
+                .addRaw("This Pull Request is not blocked by any labels which prevent it from being merged.")
+                .write();
+            }

.github/workflows/release-drafter.yaml

@@ -18,6 +18,6 @@ jobs:
       pull-requests: read
     runs-on: ubuntu-latest
     steps:
-      - uses: release-drafter/release-drafter@c2e2804cc59f45f57076a99af580d0fedb697927 # v7.3.0
+      - uses: release-drafter/release-drafter@693d20e7c1ce1a81d3a41962f85914253b518449 # v7.3.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.yarn/patches/tinykeys-npm-4.0.0-a6ca3fd771.patch

@@ -0,0 +1,86 @@
+diff --git a/dist/tinykeys.cjs b/dist/tinykeys.cjs
+index 08c98b6eff3b8fb4b727fe8e6b096951d6ef6347..9c44f14862f582766ea1733b6dc0e97f962800d8 100644
+--- a/dist/tinykeys.cjs
++++ b/dist/tinykeys.cjs
+@@ -61,6 +61,18 @@ function defaultKeybindingsHandlerIgnore(event) {
+ function getModifierState(event, mod) {
+ 	return typeof event.getModifierState === "function" ? event.getModifierState(mod) || ALT_GRAPH_ALIASES.includes(mod) && event.getModifierState("AltGraph") : false;
+ }
++function splitKeybindingPress(press) {
++	let parts = [];
++	let start = 0;
++	for (let index = 0; index < press.length; index++) {
++		if (press[index] === "+" && /[\w\]]/.test(press[index - 1] || "")) {
++			parts.push(press.slice(start, index));
++			start = index + 1;
++		}
++	}
++	parts.push(press.slice(start));
++	return parts;
++}
+ /**
+ * Parses a keybinding string into its parts.
+ *
+@@ -76,10 +88,10 @@ function getModifierState(event, mod) {
+ */
+ function parseKeybinding(str) {
+ 	return str.trim().split(" ").map((press) => {
+-		let parts = press.split(/(?<=\w|\])\+/);
++		let parts = splitKeybindingPress(press);
+ 		let last = parts.pop();
+ 		let regex = last.match(/^\((.+)\)$/);
+-		let key = regex ? new RegExp(`^(?:${regex[1]})$`, "iv") : last;
++		let key = regex ? new RegExp(`^(?:${regex[1]})$`, "i") : last;
+ 		let requiredModifiers = [];
+ 		let optionalModifiers = [];
+ 		for (const part of parts) {
+@@ -201,5 +213,3 @@ exports.defaultKeybindingsHandlerIgnore = defaultKeybindingsHandlerIgnore;
+ exports.matchKeybindingPress = matchKeybindingPress;
+ exports.parseKeybinding = parseKeybinding;
+ exports.tinykeys = tinykeys;
+-
+-//# sourceMappingURL=tinykeys.cjs.map
+\ No newline at end of file
+diff --git a/dist/tinykeys.mjs b/dist/tinykeys.mjs
+index c289972d2728e03d9b272268c38fd3392e8845bf..e22897b00aae6cdb0dbbb971445227c07be52918 100644
+--- a/dist/tinykeys.mjs
++++ b/dist/tinykeys.mjs
+@@ -60,6 +60,18 @@ function defaultKeybindingsHandlerIgnore(event) {
+ function getModifierState(event, mod) {
+ 	return typeof event.getModifierState === "function" ? event.getModifierState(mod) || ALT_GRAPH_ALIASES.includes(mod) && event.getModifierState("AltGraph") : false;
+ }
++function splitKeybindingPress(press) {
++	let parts = [];
++	let start = 0;
++	for (let index = 0; index < press.length; index++) {
++		if (press[index] === "+" && /[\w\]]/.test(press[index - 1] || "")) {
++			parts.push(press.slice(start, index));
++			start = index + 1;
++		}
++	}
++	parts.push(press.slice(start));
++	return parts;
++}
+ /**
+ * Parses a keybinding string into its parts.
+ *
+@@ -75,10 +87,10 @@ function getModifierState(event, mod) {
+ */
+ function parseKeybinding(str) {
+ 	return str.trim().split(" ").map((press) => {
+-		let parts = press.split(/(?<=\w|\])\+/);
++		let parts = splitKeybindingPress(press);
+ 		let last = parts.pop();
+ 		let regex = last.match(/^\((.+)\)$/);
+-		let key = regex ? new RegExp(`^(?:${regex[1]})$`, "iv") : last;
++		let key = regex ? new RegExp(`^(?:${regex[1]})$`, "i") : last;
+ 		let requiredModifiers = [];
+ 		let optionalModifiers = [];
+ 		for (const part of parts) {
+@@ -196,5 +208,3 @@ function tinykeys(target, keybindingMap, options = {}) {
+ }
+ //#endregion
+ export { createKeybindingsHandler, defaultKeybindingsHandlerIgnore, matchKeybindingPress, parseKeybinding, tinykeys };
+-
+-//# sourceMappingURL=tinykeys.mjs.map
+\ No newline at end of file