feat(#327): add energy_collection_key option and improve collection auto-detection

Support explicit energy collection binding via energy_collection_key config.
Improve default behavior by trying panel-specific key (_energy_<panelUrl>)
first, fixing wrong collection binding when navigating between dashboards
on HA 2026.4+.

Author: MindFreeze

README.md

@@ -27,6 +27,7 @@ Install through [HACS](https://hacs.xyz/)
 | sections          | list    |                     | Section-level configuration (sorting, min_width). See [sections object](#sections-object)
 | layout            | string  | auto                | Valid options are: 'horizontal' - flow left to right, 'vertical' - flow top to bottom & 'auto' - determine based on available space (based on the section->`min_witdh` option, which defaults to 150)
 | energy_date_selection | boolean | false           | Integrate with the Energy Dashboard. Filters data based on the [energy-date-selection](https://www.home-assistant.io/dashboards/energy/) card. Use this only for accumulated data sensors (energy/water/gas) and with a `type:energy-date-selection` card. You still need to specify all your entities as HA doesn't know exactly how to connect them but you can use the general kWh entities that you have in the energy dashboard. In the future we may use areas to auto configure the chart. Not compatible with `time_period`
+| energy_collection_key | string |                   | Key of the energy collection to bind to. Auto-detected by default. Set this if you have multiple energy dashboards and the chart binds to the wrong one. The key follows the pattern `_energy_<dashboard_url>`, e.g. `_energy_energy-dashboard`
 | title             | string  |                     | Optional header title for the card
 | unit_prefix       | string  |                     | Metric prefix for the unit of measurment. See <https://en.wikipedia.org/wiki/Unit_prefix> . Supported values are m, k, M, G, T, and 'auto'. When 'auto' is used, the appropriate prefix is chosen automatically for each value based on its magnitude (m for values <1, k for values >=1000, etc.)
 | round             | number  | 0                   | Round the value to at most N decimal places. May not apply to near zero values, see issue [#29](https://github.com/MindFreeze/ha-sankey-chart/issues/29)

__tests__/energy.test.ts

@@ -0,0 +1,74 @@
+import { HomeAssistant } from 'custom-card-helpers';
+import { getEnergyDataCollection } from '../src/energy';
+
+const mockCollection = () => ({ subscribe: jest.fn() });
+
+const createHass = (connectionKeys: Record<string, any>, panelUrl = 'energy') =>
+  ({
+    connection: connectionKeys,
+    panelUrl,
+  } as unknown as HomeAssistant);
+
+describe('getEnergyDataCollection', () => {
+  it('returns panel-specific collection by default (HA 2026.4+)', () => {
+    const collection = mockCollection();
+    const hass = createHass({ '_energy_energy': collection }, 'energy');
+    expect(getEnergyDataCollection(hass)).toBe(collection);
+  });
+
+  it('prefers panel-specific key over other _energy* keys', () => {
+    const correct = mockCollection();
+    const wrong = mockCollection();
+    const hass = createHass({
+      '_energy_other-dashboard': wrong,
+      '_energy_my-dashboard': correct,
+    }, 'my-dashboard');
+    expect(getEnergyDataCollection(hass)).toBe(correct);
+  });
+
+  it('falls back to legacy _energy key', () => {
+    const collection = mockCollection();
+    const hass = createHass({ '_energy': collection }, 'energy');
+    expect(getEnergyDataCollection(hass)).toBe(collection);
+  });
+
+  it('falls back to prefix scan when panel and legacy keys miss', () => {
+    const collection = mockCollection();
+    const hass = createHass({ '_energy_some-other-panel': collection }, 'different-panel');
+    expect(getEnergyDataCollection(hass)).toBe(collection);
+  });
+
+  it('returns null when no collection exists', () => {
+    const hass = createHass({}, 'energy');
+    expect(getEnergyDataCollection(hass)).toBeNull();
+  });
+
+  it('returns explicit collectionKey when found', () => {
+    const collection = mockCollection();
+    const hass = createHass({ '_energy_my-dashboard': collection }, 'energy');
+    expect(getEnergyDataCollection(hass, '_energy_my-dashboard')).toBe(collection);
+  });
+
+  it('returns null when explicit collectionKey is not found', () => {
+    const hass = createHass({ '_energy_other': mockCollection() }, 'energy');
+    expect(getEnergyDataCollection(hass, '_energy_missing')).toBeNull();
+  });
+
+  it('explicit collectionKey bypasses auto-detection', () => {
+    const panelCollection = mockCollection();
+    const explicitCollection = mockCollection();
+    const hass = createHass({
+      '_energy_energy': panelCollection,
+      '_energy_custom': explicitCollection,
+    }, 'energy');
+    expect(getEnergyDataCollection(hass, '_energy_custom')).toBe(explicitCollection);
+  });
+
+  it('skips objects without subscribe method', () => {
+    const hass = createHass({
+      '_energy_energy': { notSubscribe: jest.fn() },
+      '_energy': { data: 'something' },
+    }, 'energy');
+    expect(getEnergyDataCollection(hass)).toBeNull();
+  });
+});

src/energy.ts

@@ -99,15 +99,34 @@ export interface EnergyCollection extends Collection<EnergyData> {
 
 export const getEnergyDataCollection = (
   hass: HomeAssistant,
+  collectionKey?: string,
 ): EnergyCollection | null => {
-  if ((hass.connection as any)['_energy']) {
-    return (hass.connection as any)['_energy'];
+  const conn = hass.connection as any;
+  const isCollection = (obj: any) => obj && typeof obj.subscribe === 'function';
+
+  // If an explicit key is provided, use only that key
+  if (collectionKey) {
+    return isCollection(conn[collectionKey]) ? conn[collectionKey] : null;
+  }
+
+  // Smart auto-detection: try panel-specific key first (HA 2026.4+)
+  const panelKey = `_energy_${hass.panelUrl}`;
+  if (isCollection(conn[panelKey])) {
+    return conn[panelKey];
   }
-  for (const key of Object.keys(hass.connection)) {
-    if (key.startsWith('_energy') && typeof (hass.connection as any)[key]?.subscribe === 'function') {
-      return (hass.connection as any)[key];
+
+  // Legacy key (HA < 2026.4)
+  if (isCollection(conn['_energy'])) {
+    return conn['_energy'];
+  }
+
+  // Fallback: prefix scan for any _energy* collection
+  for (const key of Object.keys(conn)) {
+    if (key.startsWith('_energy') && isCollection(conn[key])) {
+      return conn[key];
     }
   }
+
   // HA has not initialized the collection yet and we don't want to interfere with that if energy_date_selection is enabled
   return null;
 };

src/ha-sankey-chart.ts

@@ -76,11 +76,11 @@ class SankeyChart extends SubscribeMixin(LitElement) {
         resolve: (value: EnergyCollection | PromiseLike<EnergyCollection>) => void,
         reject: (reason?: any) => void,
       ) => {
-        const energyCollection = getEnergyDataCollection(this.hass);
+        const energyCollection = getEnergyDataCollection(this.hass, this.config.energy_collection_key);
         if (energyCollection) {
           resolve(energyCollection);
         } else if (Date.now() - start > ENERGY_DATA_TIMEOUT) {
-          console.debug(getEnergyDataCollection(this.hass));
+          console.debug(getEnergyDataCollection(this.hass, this.config.energy_collection_key));
           reject(
             new Error('No energy data received. Make sure to add a `type: energy-date-selection` card to this screen.'),
           );
@@ -92,7 +92,7 @@ class SankeyChart extends SubscribeMixin(LitElement) {
       setTimeout(() => {
         if (!this.error && !Object.keys(this.states).length) {
           this.error = new Error('Something went wrong. No energy data received.');
-          console.debug(getEnergyDataCollection(this.hass));
+          console.debug(getEnergyDataCollection(this.hass, this.config.energy_collection_key));
         }
       }, ENERGY_DATA_TIMEOUT * 2);
       energyPromise.catch(err => {

src/types.ts

@@ -53,6 +53,7 @@ export interface SankeyChartConfig extends LovelaceCardConfig {
   show_states?: boolean;
   show_units?: boolean;
   energy_date_selection?: boolean;
+  energy_collection_key?: string;
   min_box_size?: number;
   min_box_distance?: number;
   throttle?: number;