preact-homeassistant 0.2.2 → 0.3.0

package/src/__tests__/useCachedFetch.test.tsx

@@ -2,9 +2,11 @@ import { act, screen, waitFor } from '@testing-library/preact';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { useCachedFetch } from '../HAContext';
 import type { FetchStatus } from '../types';
-import { createMockSubscribe, makeHass, renderWithHA } from './testHelpers';
+import { renderWithHA } from './testHelpers';
 
-let lastStatus: FetchStatus;
+// Every status seen across renders, so we can assert the SWR invariant
+// (never 'loading' when data is available).
+let statuses: FetchStatus[] = [];
 
 function FetchDisplay({
   cacheKey,
@@ -16,7 +18,7 @@ function FetchDisplay({
   deps: unknown[];
 }) {
   const { data, status, error } = useCachedFetch(cacheKey, fetcher, deps);
-  lastStatus = status;
+  statuses.push(status);
   return (
     <div>
       <span data-testid="data">{JSON.stringify(data) ?? 'undefined'}</span>
@@ -28,31 +30,25 @@ function FetchDisplay({
 
 describe('useCachedFetch', () => {
   beforeEach(() => {
-    localStorage.clear();
+    statuses = [];
   });
 
-  it('transitions from loading to ready on successful fetch', async () => {
+  it('transitions from loading to ready on successful fetch (cold start)', async () => {
     const fetcher = vi.fn().mockResolvedValue({ temp: 72 });
-    const { subscribe } = createMockSubscribe();
 
-    renderWithHA(<FetchDisplay cacheKey="test" fetcher={fetcher} deps={[]} />, {
-      subscribeFn: subscribe,
-    });
+    renderWithHA(<FetchDisplay cacheKey="test" fetcher={fetcher} deps={[]} />);
 
     await waitFor(() => {
       expect(screen.getByTestId('status').textContent).toBe('ready');
     });
 
     expect(screen.getByTestId('data').textContent).toBe('{"temp":72}');
+    // Cold start is the only time 'loading' is allowed.
+    expect(statuses).toContain('loading');
   });
 
   it('shows cached data while refreshing', async () => {
-    // Pre-populate cache
-    const entry = {
-      data: { temp: 68 },
-      timestamp: Date.now(),
-    };
-    localStorage.setItem('preact-ha:test', JSON.stringify(entry));
+    const cache = new Map<string, { data: unknown }>([['test', { data: { temp: 68 } }]]);
 
     let resolve: (v: any) => void;
     const fetcher = vi.fn().mockImplementation(
@@ -61,16 +57,13 @@ describe('useCachedFetch', () => {
           resolve = r;
         }),
     );
-    const { subscribe } = createMockSubscribe();
 
-    renderWithHA(<FetchDisplay cacheKey="test" fetcher={fetcher} deps={[]} />, {
-      subscribeFn: subscribe,
-    });
+    renderWithHA(<FetchDisplay cacheKey="test" fetcher={fetcher} deps={[]} />, { cache });
 
-    // Should show cached data
+    // Cached data shown immediately; no loading flash.
     expect(screen.getByTestId('data').textContent).toBe('{"temp":68}');
+    expect(statuses).not.toContain('loading');
 
-    // Resolve the fetch
     await act(async () => {
       resolve!({ temp: 75 });
     });
@@ -84,32 +77,27 @@ describe('useCachedFetch', () => {
 
   it('reports errors from failed fetches', async () => {
     const fetcher = vi.fn().mockRejectedValue(new Error('Network error'));
-    const { subscribe } = createMockSubscribe();
 
-    renderWithHA(<FetchDisplay cacheKey="test" fetcher={fetcher} deps={[]} />, {
-      subscribeFn: subscribe,
-    });
+    renderWithHA(<FetchDisplay cacheKey="test" fetcher={fetcher} deps={[]} />);
 
     await waitFor(() => {
       expect(screen.getByTestId('error').textContent).toBe('Network error');
     });
   });
 
-  it('saves fetched data to cache', async () => {
+  it('writes fetched data to the cache', async () => {
+    const cache = new Map<string, { data: unknown }>();
     const fetcher = vi.fn().mockResolvedValue({ temp: 72 });
-    const { subscribe } = createMockSubscribe();
 
     renderWithHA(<FetchDisplay cacheKey="cache-write-test" fetcher={fetcher} deps={[]} />, {
-      subscribeFn: subscribe,
+      cache,
     });
 
     await waitFor(() => {
       expect(screen.getByTestId('status').textContent).toBe('ready');
     });
 
-    const cached = localStorage.getItem('preact-ha:cache-write-test');
-    expect(cached).toBeTruthy();
-    expect(JSON.parse(cached!).data).toEqual({ temp: 72 });
+    expect(cache.get('cache-write-test')).toEqual({ data: { temp: 72 } });
   });
 
   it('ignores stale fetch results', async () => {
@@ -120,11 +108,9 @@ describe('useCachedFetch', () => {
           resolvers.push(r);
         }),
     );
-    const { subscribe } = createMockSubscribe();
 
     const { rerender } = renderWithHA(
       <FetchDisplay cacheKey="test" fetcher={fetcher} deps={['a']} />,
-      { subscribeFn: subscribe },
     );
 
     // Trigger a second fetch by changing deps
@@ -144,4 +130,42 @@ describe('useCachedFetch', () => {
       expect(screen.getByTestId('data').textContent).toBe('{"temp":"fresh"}');
     });
   });
+
+  it('swaps to the new key cached data instantly on key change, never loading', () => {
+    const cache = new Map<string, { data: unknown }>([
+      ['a', { data: { v: 'A' } }],
+      ['b', { data: { v: 'B' } }],
+    ]);
+    // Fetcher never resolves, so only cache-driven state is observed.
+    const fetcher = vi.fn().mockImplementation(() => new Promise(() => {}));
+
+    const { rerender } = renderWithHA(
+      <FetchDisplay cacheKey="a" fetcher={fetcher} deps={['a']} />,
+      { cache },
+    );
+    expect(screen.getByTestId('data').textContent).toBe('{"v":"A"}');
+
+    rerender(<FetchDisplay cacheKey="b" fetcher={fetcher} deps={['b']} />);
+
+    // Synchronous swap to the new key's cached value, no loading flash.
+    expect(screen.getByTestId('data').textContent).toBe('{"v":"B"}');
+    expect(screen.getByTestId('status').textContent).toBe('cached');
+    expect(statuses).not.toContain('loading');
+  });
+
+  it('keeps the previous data on a cold key change (keep-previous-data)', () => {
+    const cache = new Map<string, { data: unknown }>([['a', { data: { v: 'A' } }]]);
+    const fetcher = vi.fn().mockImplementation(() => new Promise(() => {}));
+
+    const { rerender } = renderWithHA(
+      <FetchDisplay cacheKey="a" fetcher={fetcher} deps={['a']} />,
+      { cache },
+    );
+    expect(screen.getByTestId('data').textContent).toBe('{"v":"A"}');
+
+    // 'b' is not cached → keep showing A while the (pending) fetch runs.
+    rerender(<FetchDisplay cacheKey="b" fetcher={fetcher} deps={['b']} />);
+    expect(screen.getByTestId('data').textContent).toBe('{"v":"A"}');
+    expect(statuses).not.toContain('loading');
+  });
 });

package/src/__tests__/{useMultiCalendarEvents.test.tsx → useCalendarEvents.test.tsx}

@@ -1,7 +1,7 @@
 import { act, screen, waitFor } from '@testing-library/preact';
 import { render } from '@testing-library/preact';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { useMultiCalendarEvents } from '../HAContext';
+import { useCalendarEvents } from '../HAContext';
 import { HAProvider } from '../HAContext';
 import type { FetchStatus } from '../types';
 import type { CalendarEventWithSource } from '../types';
@@ -16,7 +16,7 @@ function CalendarDisplay({
   start: Date;
   end: Date;
 }) {
-  const { events, status, error } = useMultiCalendarEvents(entityIds, {
+  const { events, status, error } = useCalendarEvents(entityIds, {
     start,
     end,
   });
@@ -33,12 +33,11 @@ function CalendarDisplay({
   );
 }
 
-describe('useMultiCalendarEvents', () => {
+describe('useCalendarEvents', () => {
   const start = new Date('2025-01-01');
   const end = new Date('2025-01-31');
 
   beforeEach(() => {
-    localStorage.clear();
     vi.restoreAllMocks();
   });
 

package/src/__tests__/useEntity.test.tsx

@@ -1,6 +1,6 @@
 import { act, screen } from '@testing-library/preact';
 import { useRef } from 'preact/hooks';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { useEntity } from '../HAContext';
 import { createMockSubscribe, makeHass, renderWithHA } from './testHelpers';
 
@@ -18,10 +18,6 @@ function EntityDisplay({ entityId }: { entityId: string }) {
 }
 
 describe('useEntity', () => {
-  beforeEach(() => {
-    localStorage.clear();
-  });
-
   it('returns the initial entity state from hass', () => {
     const hass = makeHass({
       'sensor.temp': { entity_id: 'sensor.temp', state: '72' },
@@ -64,37 +60,35 @@ describe('useEntity', () => {
     expect(screen.getByTestId('state').textContent).toBe('75');
   });
 
-  it('caches entity to localStorage on update', async () => {
+  it('caches the entity to the per-card cache on update', async () => {
+    const cache = new Map<string, { data: unknown }>();
     const { subscribe, notify } = createMockSubscribe();
 
     renderWithHA(<EntityDisplay entityId="sensor.temp" />, {
       hass: makeHass({}),
       subscribeFn: subscribe,
+      cache,
     });
 
     await act(() => {
       notify('sensor.temp', { entity_id: 'sensor.temp', state: '75' });
     });
 
-    const cached = localStorage.getItem('preact-ha:entity:sensor.temp');
-    expect(cached).toBeTruthy();
-    const parsed = JSON.parse(cached!);
-    expect(parsed.data.state).toBe('75');
+    expect(cache.get('entity:sensor.temp')).toEqual({
+      data: { entity_id: 'sensor.temp', state: '75' },
+    });
   });
 
   it('loads from cache when hass has no state', () => {
-    // Pre-populate cache
-    const entry = {
-      data: { entity_id: 'sensor.temp', state: '68' },
-      timestamp: Date.now(),
-    };
-    localStorage.setItem('preact-ha:entity:sensor.temp', JSON.stringify(entry));
-
+    const cache = new Map<string, { data: unknown }>([
+      ['entity:sensor.temp', { data: { entity_id: 'sensor.temp', state: '68' } }],
+    ]);
     const { subscribe } = createMockSubscribe();
 
     renderWithHA(<EntityDisplay entityId="sensor.temp" />, {
       hass: makeHass({}),
       subscribeFn: subscribe,
+      cache,
     });
 
     expect(screen.getByTestId('state').textContent).toBe('68');

package/src/__tests__/useHassValue.test.tsx

@@ -0,0 +1,99 @@
+import { act, render, screen } from '@testing-library/preact';
+import { describe, expect, it } from 'vitest';
+import { HAProvider, useDarkMode } from '../HAContext';
+import type { HomeAssistant } from '../types';
+
+function makeHass(darkMode: boolean): HomeAssistant {
+  return {
+    states: {},
+    config: {} as any,
+    services: {} as any,
+    connection: {} as any,
+    callService: () => {},
+    themes: { darkMode },
+  };
+}
+
+// Controllable hass-change subscription.
+function makeHassSubscription() {
+  const listeners = new Set<() => void>();
+  return {
+    subscribeToHass: (cb: () => void) => {
+      listeners.add(cb);
+      return () => listeners.delete(cb);
+    },
+    notify: () => listeners.forEach((cb) => cb()),
+  };
+}
+
+let renderCount = 0;
+function DarkModeProbe() {
+  renderCount++;
+  const dark = useDarkMode();
+  return <span data-testid="dark">{String(dark)}</span>;
+}
+
+describe('useHassValue / useDarkMode', () => {
+  it('returns the initial selected value', () => {
+    const { subscribeToHass } = makeHassSubscription();
+    render(
+      <HAProvider
+        hass={makeHass(true)}
+        subscribeToEntity={() => () => {}}
+        subscribeToHass={subscribeToHass}
+      >
+        <DarkModeProbe />
+      </HAProvider>,
+    );
+    expect(screen.getByTestId('dark').textContent).toBe('true');
+  });
+
+  it('does not re-render when the selected slice is unchanged', () => {
+    const { subscribeToHass, notify } = makeHassSubscription();
+    renderCount = 0;
+    render(
+      <HAProvider
+        hass={makeHass(false)}
+        subscribeToEntity={() => () => {}}
+        subscribeToHass={subscribeToHass}
+      >
+        <DarkModeProbe />
+      </HAProvider>,
+    );
+    const afterMount = renderCount;
+
+    // hass pushes arrive but darkMode is still false → no re-render.
+    act(() => {
+      notify();
+      notify();
+    });
+
+    expect(renderCount).toBe(afterMount);
+    expect(screen.getByTestId('dark').textContent).toBe('false');
+  });
+
+  it('updates when the selected slice changes', () => {
+    const { subscribeToHass, notify } = makeHassSubscription();
+    let hass = makeHass(false);
+
+    const { rerender } = render(
+      <HAProvider hass={hass} subscribeToEntity={() => () => {}} subscribeToHass={subscribeToHass}>
+        <DarkModeProbe />
+      </HAProvider>,
+    );
+    expect(screen.getByTestId('dark').textContent).toBe('false');
+
+    // New hass with darkMode flipped, then a hass-change notification.
+    hass = makeHass(true);
+    rerender(
+      <HAProvider hass={hass} subscribeToEntity={() => () => {}} subscribeToHass={subscribeToHass}>
+        <DarkModeProbe />
+      </HAProvider>,
+    );
+    act(() => {
+      notify();
+    });
+
+    expect(screen.getByTestId('dark').textContent).toBe('true');
+  });
+});

package/src/cacheUtils.ts

@@ -1,32 +1,20 @@
-const CACHE_PREFIX = 'preact-ha:';
-const CACHE_EXPIRY_MS = 24 * 60 * 60 * 1000;
+// In-memory cache helpers. The cache Map is owned per-card by the HAProvider
+// store (see HAContext), so its lifetime matches the card and it is
+// garbage-collected when the card is torn down. There is intentionally no
+// persistence, TTL, or size cap: freshness comes from entity subscriptions and
+// periodic refetch, not from cache expiry, and growth is bounded by the ranges
+// a single card visits in a session.
 
-interface CacheEntry<T> {
+export interface CacheEntry<T> {
   data: T;
-  timestamp: number;
 }
 
-export function loadFromCache<T>(key: string): T | undefined {
-  try {
-    const raw = localStorage.getItem(`${CACHE_PREFIX}${key}`);
-    if (!raw) return undefined;
+export type Cache = Map<string, CacheEntry<unknown>>;
 
-    const entry: CacheEntry<T> = JSON.parse(raw);
-    if (Date.now() - entry.timestamp > CACHE_EXPIRY_MS) {
-      localStorage.removeItem(`${CACHE_PREFIX}${key}`);
-      return undefined;
-    }
-    return entry.data;
-  } catch {
-    return undefined;
-  }
+export function readCache<T>(cache: Cache, key: string): T | undefined {
+  return (cache.get(key) as CacheEntry<T> | undefined)?.data;
 }
 
-export function saveToCache<T>(key: string, data: T): void {
-  try {
-    const entry: CacheEntry<T> = { data, timestamp: Date.now() };
-    localStorage.setItem(`${CACHE_PREFIX}${key}`, JSON.stringify(entry));
-  } catch (e) {
-    console.warn('[preact-homeassistant cache] Failed to save:', e);
-  }
+export function writeCache<T>(cache: Cache, key: string, data: T): void {
+  cache.set(key, { data });
 }

package/src/index.ts

@@ -3,10 +3,12 @@ export {
   HAProvider,
   useEntity,
   useHass,
+  useHassValue,
+  useHassConfig,
+  useDarkMode,
   useService,
   useCachedFetch,
   useCalendarEvents,
-  useMultiCalendarEvents,
   useWeatherForecast,
 } from './HAContext';
 export { useCallbackStable } from './useCallbackStable';
@@ -17,7 +19,6 @@ export {
 } from './useResizeObserver';
 export { useWidth } from './useWidth';
 export { css, registerRawStyles, getAllStyles } from './styleRegistry';
-export { loadFromCache, saveToCache } from './cacheUtils';
 
 export type {
   HomeAssistant,

package/src/registerPreactCard.tsx

@@ -23,6 +23,13 @@ declare global {
   }
 }
 
+// Grace period before a disconnected card is torn down. HA detaches and
+// re-attaches cards transiently (scroll virtualization, edit mode); only a card
+// that stays gone past this window is genuinely removed, so we defer the
+// Preact unmount — and the effect cleanups it triggers (timers, subscriptions)
+// — until then. A reconnect within the window cancels the teardown.
+const TEARDOWN_GRACE_MS = 5000;
+
 export function registerPreactCard<TConfig>(options: RegisterPreactCardOptions<TConfig>) {
   const {
     type,
@@ -34,21 +41,71 @@ export function registerPreactCard<TConfig>(options: RegisterPreactCardOptions<T
     getStubConfig,
   } = options;
 
-  class HACard extends HTMLElement {
-    private _hass?: HomeAssistant;
-    private _config?: TConfig;
+  // Shared host-element plumbing: config/hass storage, connect/disconnect
+  // lifecycle, deferred teardown, and the render skeleton. Subclasses supply
+  // the render root and the tree to render, and may override hass behavior.
+  abstract class BaseHACard extends HTMLElement {
+    protected _hass?: HomeAssistant;
+    protected _config?: TConfig;
+    private _teardownTimer?: ReturnType<typeof setTimeout>;
+
+    protected abstract _getRenderRoot(): Element | ShadowRoot;
+    protected abstract _renderTree(): void;
+    protected _renderUnconfigured(): void {}
+
+    connectedCallback() {
+      if (this._teardownTimer !== undefined) {
+        clearTimeout(this._teardownTimer);
+        this._teardownTimer = undefined;
+      }
+      this._maybeRenderOnConnect();
+    }
+
+    protected _maybeRenderOnConnect() {
+      if (this._hass && this._config) {
+        this._render();
+      }
+    }
+
+    disconnectedCallback() {
+      if (this._teardownTimer !== undefined) clearTimeout(this._teardownTimer);
+      this._teardownTimer = setTimeout(() => {
+        // Unmount the Preact tree, running effect cleanups (clears timers and
+        // entity subscriptions). Scheduled, never synchronous, so a transient
+        // disconnect+reconnect leaves the tree intact.
+        render(null, this._getRenderRoot());
+        this._teardownTimer = undefined;
+      }, TEARDOWN_GRACE_MS);
+    }
+
+    setConfig(config: TConfig) {
+      this._config = config;
+      if (this._hass && this.isConnected) {
+        this._render();
+      }
+    }
+
+    protected _render() {
+      if (!this._config || !this._hass) {
+        this._renderUnconfigured();
+        return;
+      }
+      this._renderTree();
+    }
+  }
+
+  class HACard extends BaseHACard {
     private _shadowRoot: ShadowRoot;
     private _entityChangeListeners = new Map<string, Set<(entity: any) => void>>();
+    private _hassChangeListeners = new Set<() => void>();
 
     constructor() {
       super();
       this._shadowRoot = this.attachShadow({ mode: 'open' });
     }
 
-    connectedCallback() {
-      if (this._hass && this._config) {
-        this._render();
-      }
+    protected _getRenderRoot() {
+      return this._shadowRoot;
     }
 
     set hass(hass: HomeAssistant) {
@@ -63,14 +120,12 @@ export function registerPreactCard<TConfig>(options: RegisterPreactCardOptions<T
         }
       }
 
-      if (!prevStates && this._config && this.isConnected) {
-        this._render();
-      }
-    }
+      // Notify non-entity (config/themes) subscribers on every update. This does
+      // not re-render the whole card — useHassValue re-renders only its own
+      // consumer, and only when its selected slice actually changes.
+      this._hassChangeListeners.forEach((listener) => listener());
 
-    setConfig(config: TConfig) {
-      this._config = config;
-      if (this._hass && this.isConnected) {
+      if (!prevStates && this._config && this.isConnected) {
         this._render();
       }
     }
@@ -92,23 +147,33 @@ export function registerPreactCard<TConfig>(options: RegisterPreactCardOptions<T
       };
     };
 
-    private _render() {
-      if (!this._config || !this._hass) {
-        if (UnconfiguredComponent) {
-          render(<UnconfiguredComponent />, this._shadowRoot);
-        }
-        return;
-      }
+    private _subscribeToHass = (callback: () => void) => {
+      this._hassChangeListeners.add(callback);
+      return () => {
+        this._hassChangeListeners.delete(callback);
+      };
+    };
 
+    protected _renderTree() {
       render(
-        <HAProvider hass={this._hass} subscribeToEntity={this._subscribeToEntity}>
+        <HAProvider
+          hass={this._hass}
+          subscribeToEntity={this._subscribeToEntity}
+          subscribeToHass={this._subscribeToHass}
+        >
           <style>{getAllStyles()}</style>
-          <Component config={this._config} />
+          <Component config={this._config!} />
         </HAProvider>,
         this._shadowRoot,
       );
     }
 
+    protected _renderUnconfigured() {
+      if (UnconfiguredComponent) {
+        render(<UnconfiguredComponent />, this._shadowRoot);
+      }
+    }
+
     static getConfigElement() {
       if (ConfigComponent) {
         return document.createElement(`${type}-editor`);
@@ -126,15 +191,21 @@ export function registerPreactCard<TConfig>(options: RegisterPreactCardOptions<T
   if (ConfigComponent) {
     const EditorComponent = ConfigComponent;
 
-    class HACardEditor extends HTMLElement {
-      private _hass?: HomeAssistant;
-      private _config?: TConfig;
+    class HACardEditor extends BaseHACard {
+      protected _getRenderRoot() {
+        return this;
+      }
 
+      // The editor re-renders on every hass update: it passes `hass` straight to
+      // HA's <ha-form>/<ha-selector>, whose entity pickers need a fresh hass to
+      // stay current. (Unlike the card, which renders once then subscribes.)
       set hass(hass: HomeAssistant) {
         this._hass = hass;
         this._render();
       }
 
+      // Render whenever config arrives, regardless of connection — HA may set
+      // config/hass before connecting the editor element.
       setConfig(config: TConfig) {
         this._config = config;
         this._render();
@@ -150,14 +221,12 @@ export function registerPreactCard<TConfig>(options: RegisterPreactCardOptions<T
         );
       };
 
-      private _render() {
-        if (!this._hass || !this._config) return;
-
-        // Render to light DOM so HA's custom elements (ha-select etc.) work.
+      // Render to light DOM so HA's custom elements (ha-form etc.) work.
+      protected _renderTree() {
         render(
           <EditorComponent
-            hass={this._hass}
-            config={this._config}
+            hass={this._hass!}
+            config={this._config!}
             onConfigChanged={this._fireConfigChanged}
           />,
           this,