preact-homeassistant 0.2.2 → 0.3.0

package/src/HAContext.tsx

@@ -2,7 +2,7 @@ import { createContext } from 'preact';
 import type { ComponentChildren } from 'preact';
 import { useContext, useEffect, useMemo, useRef, useState } from 'preact/hooks';
 
-import { loadFromCache, saveToCache } from './cacheUtils';
+import { type Cache, readCache, writeCache } from './cacheUtils';
 import type {
   CalendarEvent,
   CalendarEventWithSource,
@@ -15,10 +15,19 @@ import type {
 } from './types';
 import { useCallbackStable } from './useCallbackStable';
 
+type SubscribeToHass = (callback: () => void) => () => void;
+
+// Default for providers that don't wire up hass-value notifications (Storybook,
+// tests). useHassValue then simply returns its initial value and never updates.
+const noopSubscribeToHass: SubscribeToHass = () => () => {};
+
 interface HAStore {
-  hass: HomeAssistant | undefined;
   getHass: () => HomeAssistant | undefined;
   subscribeToEntity: (entityId: string, callback: (entity: any) => void) => () => void;
+  subscribeToHass: SubscribeToHass;
+  // Per-card cache (events, forecasts, entities). Owned by the provider so its
+  // lifetime is the card's — GC'd with the store when the card is torn down.
+  cache: Cache;
 }
 
 const HAContext = createContext<HAStore | null>(null);
@@ -26,22 +35,38 @@ const HAContext = createContext<HAStore | null>(null);
 interface HAProviderProps {
   hass: HomeAssistant | undefined;
   subscribeToEntity: (entityId: string, callback: (entity: any) => void) => () => void;
+  subscribeToHass?: SubscribeToHass;
+  // Optional injected cache (tests seed/inspect it); defaults to a fresh
+  // per-provider Map held stable across re-renders.
+  cache?: Cache;
   children: ComponentChildren;
 }
 
-export function HAProvider({ hass, subscribeToEntity, children }: HAProviderProps) {
+export function HAProvider({
+  hass,
+  subscribeToEntity,
+  subscribeToHass,
+  cache,
+  children,
+}: HAProviderProps) {
   const hassRef = useRef(hass);
   hassRef.current = hass;
 
   const getHass = useCallbackStable(() => hassRef.current);
 
+  const cacheRef = useRef<Cache>();
+  if (!cacheRef.current) cacheRef.current = cache ?? new Map();
+
+  const resolvedSubscribeToHass = subscribeToHass ?? noopSubscribeToHass;
+
   const store = useMemo<HAStore>(
     () => ({
-      hass: hassRef.current,
       getHass,
       subscribeToEntity,
+      subscribeToHass: resolvedSubscribeToHass,
+      cache: cacheRef.current!,
     }),
-    [getHass, subscribeToEntity],
+    [getHass, subscribeToEntity, resolvedSubscribeToHass],
   );
 
   return <HAContext.Provider value={store}>{children}</HAContext.Provider>;
@@ -69,18 +94,18 @@ export function useEntity<T extends string>(entityId: T): EntityForId<T> | undef
   const cacheKey = `entity:${entityId}`;
 
   const [entity, setEntity] = useState<EntityForId<T> | undefined>(() => {
-    const current = store.hass?.states[entityId] as EntityForId<T> | undefined;
+    const current = store.getHass()?.states[entityId] as EntityForId<T> | undefined;
     if (current) return current;
-    return loadFromCache<EntityForId<T>>(cacheKey);
+    return readCache<EntityForId<T>>(store.cache, cacheKey);
   });
 
   useEffect(() => {
     const unsubscribe = store.subscribeToEntity(entityId, (newEntity) => {
       setEntity(newEntity as EntityForId<T>);
-      saveToCache(cacheKey, newEntity);
+      writeCache(store.cache, cacheKey, newEntity);
     });
     return unsubscribe;
-  }, [entityId, store.subscribeToEntity, cacheKey]);
+  }, [entityId, store.subscribeToEntity, store.cache, cacheKey]);
 
   return entity;
 }
@@ -94,6 +119,47 @@ export function useHass(): { getHass: () => HomeAssistant | undefined } {
   return { getHass: store.getHass };
 }
 
+/**
+ * Subscribe to a derived slice of the `hass` object (e.g. config, themes) and
+ * re-render only when that slice changes. Use this for non-entity values —
+ * entity state goes through `useEntity`. The selector runs on every hass update
+ * but only re-renders the consumer when `isEqual` reports a change, so it's
+ * cheap for rarely-changing values like config/themes.
+ */
+export function useHassValue<T>(
+  selector: (hass: HomeAssistant | undefined) => T,
+  isEqual: (a: T, b: T) => boolean = Object.is,
+): T {
+  const store = useHAStore();
+
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+  const isEqualRef = useRef(isEqual);
+  isEqualRef.current = isEqual;
+
+  const [value, setValue] = useState<T>(() => selectorRef.current(store.getHass()));
+
+  useEffect(() => {
+    const unsubscribe = store.subscribeToHass(() => {
+      const next = selectorRef.current(store.getHass());
+      setValue((prev) => (isEqualRef.current(prev, next) ? prev : next));
+    });
+    return unsubscribe;
+  }, [store.subscribeToHass, store.getHass]);
+
+  return value;
+}
+
+/** Re-renders when `hass.config` changes (units, latitude/longitude, etc.). */
+export function useHassConfig(): HomeAssistant['config'] | undefined {
+  return useHassValue((hass) => hass?.config);
+}
+
+/** Re-renders when the active theme's dark mode flips. */
+export function useDarkMode(): boolean {
+  return useHassValue((hass) => hass?.themes?.darkMode ?? false);
+}
+
 type ServiceCaller<T extends string> = <S extends keyof ServicesForId<T> & string>(
   service: S,
   ...args: ServicesForId<T>[S] extends undefined
@@ -140,11 +206,27 @@ export function useCachedFetch<T>(
   fetcher: () => Promise<T>,
   deps: unknown[],
 ): UseCachedFetchResult<T> {
-  const [data, setData] = useState<T | undefined>(() => loadFromCache<T>(cacheKey));
+  const store = useHAStore();
+  const [data, setData] = useState<T | undefined>(() => readCache<T>(store.cache, cacheKey));
   const [isFresh, setIsFresh] = useState(false);
   const [isFetching, setIsFetching] = useState(false);
   const [error, setError] = useState<Error | undefined>(undefined);
 
+  // Stale-while-revalidate, key-change aware. When `cacheKey` changes we swap to
+  // the new key's cached value synchronously (SWR hit) or keep the previously
+  // rendered data (keep-previous-data on a cold key) — never blanking to a
+  // loading state. The `deps` effect below issues the background refetch; the
+  // only `'loading'` state is a true cold start (nothing cached, nothing fetched).
+  const dataKeyRef = useRef(cacheKey);
+  if (cacheKey !== dataKeyRef.current) {
+    dataKeyRef.current = cacheKey;
+    setIsFresh(false);
+    setError(undefined);
+    const cached = readCache<T>(store.cache, cacheKey);
+    if (cached !== undefined) setData(cached);
+    // cache miss: leave `data` as-is (keep-previous-data)
+  }
+
   const fetchIdRef = useRef(0);
 
   const doFetch = useCallbackStable(async () => {
@@ -157,7 +239,7 @@ export function useCachedFetch<T>(
       if (fetchId === fetchIdRef.current) {
         setData(result);
         setIsFresh(true);
-        saveToCache(cacheKey, result);
+        writeCache(store.cache, cacheKey, result);
       }
     } catch (err) {
       if (fetchId === fetchIdRef.current) {
@@ -172,7 +254,6 @@ export function useCachedFetch<T>(
 
   useEffect(() => {
     doFetch();
-    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, deps);
 
   const status: FetchStatus = useMemo(() => {
@@ -186,87 +267,77 @@ export function useCachedFetch<T>(
 }
 
 interface UseCalendarEventsResult {
-  events: CalendarEvent[] | undefined;
-  loading: boolean;
+  events: CalendarEventWithSource[] | undefined;
+  status: FetchStatus;
   error: Error | undefined;
   refetch: () => void;
+  /**
+   * Warm the cache for an arbitrary range (e.g. adjacent months) without
+   * touching component state. Best-effort: skips ranges already cached and
+   * swallows failures.
+   */
+  prefetch: (range: { start: Date; end: Date }) => void;
 }
 
-/**
- * Fetch calendar events for a date range from a single calendar.
- */
-export function useCalendarEvents(
-  entityId: `calendar.${string}`,
-  options: { start: Date; end: Date },
-): UseCalendarEventsResult {
-  const { getHass } = useHass();
-  const [events, setEvents] = useState<CalendarEvent[] | undefined>(undefined);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<Error | undefined>(undefined);
-
-  const fetchIdRef = useRef(0);
-
-  const fetchEvents = useCallbackStable(async () => {
-    const hass = getHass();
-    if (!hass?.connection) {
-      setError(new Error('Home Assistant connection not available'));
-      return;
-    }
-
-    const fetchId = ++fetchIdRef.current;
-    setLoading(true);
-    setError(undefined);
+function calendarEventsCacheKey(
+  entityIds: `calendar.${string}`[],
+  range: { start: Date; end: Date },
+): string {
+  return `events:${entityIds.join(',')}:${range.start.getTime()}-${range.end.getTime()}`;
+}
 
-    try {
-      const result = await hass.connection.sendMessagePromise<{
-        response: { [entityId: string]: { events: CalendarEvent[] } };
-      }>({
-        type: 'call_service',
-        domain: 'calendar',
-        service: 'get_events',
-        service_data: {
-          start_date_time: options.start.toISOString(),
-          end_date_time: options.end.toISOString(),
-        },
-        target: { entity_id: entityId },
-        return_response: true,
-      });
+async function fetchCalendarRange(
+  hass: HomeAssistant | undefined,
+  entityIds: `calendar.${string}`[],
+  range: { start: Date; end: Date },
+): Promise<CalendarEventWithSource[]> {
+  if (!hass?.connection) {
+    throw new Error('Home Assistant connection not available');
+  }
+  if (entityIds.length === 0) {
+    return [];
+  }
 
-      if (fetchId === fetchIdRef.current) {
-        const entityEvents = result.response?.[entityId]?.events ?? [];
-        setEvents(entityEvents);
-        setLoading(false);
+  const results = await Promise.all(
+    entityIds.map(async (entityId) => {
+      try {
+        const result = await hass.connection.sendMessagePromise<{
+          response: { [key: string]: { events: CalendarEvent[] } };
+        }>({
+          type: 'call_service',
+          domain: 'calendar',
+          service: 'get_events',
+          service_data: {
+            start_date_time: range.start.toISOString(),
+            end_date_time: range.end.toISOString(),
+          },
+          target: { entity_id: entityId },
+          return_response: true,
+        });
+
+        const calendarEvents = result.response?.[entityId]?.events ?? [];
+        return calendarEvents.map(
+          (event): CalendarEventWithSource => ({ ...event, calendarId: entityId }),
+        );
+      } catch (err) {
+        console.error(`Failed to fetch events for ${entityId}:`, err);
+        return [];
       }
-    } catch (err) {
-      if (fetchId === fetchIdRef.current) {
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setLoading(false);
-      }
-    }
-  });
-
-  useEffect(() => {
-    fetchEvents();
-  }, [entityId, options.start.getTime(), options.end.getTime(), fetchEvents]);
+    }),
+  );
 
-  return { events, loading, error, refetch: fetchEvents };
-}
-
-interface UseMultiCalendarEventsResult {
-  events: CalendarEventWithSource[] | undefined;
-  status: FetchStatus;
-  error: Error | undefined;
-  refetch: () => void;
+  return results.flat();
 }
 
 /**
- * Fetch events from multiple calendars for a date range, with localStorage
- * caching. Events are tagged with their source calendar ID.
+ * Fetch events from one or more calendars for a date range, with in-memory
+ * (per-card) caching and stale-while-revalidate behavior. Events are tagged
+ * with their source calendar ID. Returns `prefetch` to warm adjacent ranges.
  */
-export function useMultiCalendarEvents(
+export function useCalendarEvents(
   entityIds: `calendar.${string}`[],
   options: { start: Date; end: Date },
-): UseMultiCalendarEventsResult {
+): UseCalendarEventsResult {
   const store = useHAStore();
   const { getHass } = useHass();
 
@@ -276,46 +347,7 @@ export function useMultiCalendarEvents(
   const dateRangeKey = `${options.start.getTime()}-${options.end.getTime()}`;
   const cacheKey = `events:${entityIdsKey}:${dateRangeKey}`;
 
-  const fetcher = useCallbackStable(async () => {
-    const hass = getHass();
-    if (!hass?.connection) {
-      throw new Error('Home Assistant connection not available');
-    }
-
-    if (entityIds.length === 0) {
-      return [];
-    }
-
-    const results = await Promise.all(
-      entityIds.map(async (entityId) => {
-        try {
-          const result = await hass.connection.sendMessagePromise<{
-            response: { [key: string]: { events: CalendarEvent[] } };
-          }>({
-            type: 'call_service',
-            domain: 'calendar',
-            service: 'get_events',
-            service_data: {
-              start_date_time: options.start.toISOString(),
-              end_date_time: options.end.toISOString(),
-            },
-            target: { entity_id: entityId },
-            return_response: true,
-          });
-
-          const calendarEvents = result.response?.[entityId]?.events ?? [];
-          return calendarEvents.map(
-            (event): CalendarEventWithSource => ({ ...event, calendarId: entityId }),
-          );
-        } catch (err) {
-          console.error(`Failed to fetch events for ${entityId}:`, err);
-          return [];
-        }
-      }),
-    );
-
-    return results.flat();
-  });
+  const fetcher = useCallbackStable(() => fetchCalendarRange(getHass(), entityIds, options));
 
   const {
     data: events,
@@ -324,6 +356,16 @@ export function useMultiCalendarEvents(
     refetch,
   } = useCachedFetch(cacheKey, fetcher, [entityIdsKey, dateRangeKey]);
 
+  const prefetch = useCallbackStable((range: { start: Date; end: Date }) => {
+    const key = calendarEventsCacheKey(entityIds, range);
+    if (store.cache.has(key)) return; // already warm
+    fetchCalendarRange(getHass(), entityIds, range)
+      .then((result) => writeCache(store.cache, key, result))
+      .catch(() => {
+        // best-effort prefetch; ignore failures
+      });
+  });
+
   const debouncedRefetch = useCallbackStable(() => {
     if (debounceTimerRef.current) {
       clearTimeout(debounceTimerRef.current);
@@ -343,7 +385,7 @@ export function useMultiCalendarEvents(
     };
   }, [entityIdsKey, store.subscribeToEntity, debouncedRefetch]);
 
-  return { events, status, error, refetch };
+  return { events, status, error, refetch, prefetch };
 }
 
 interface UseWeatherForecastResult {

package/src/__tests__/cacheUtils.test.ts

@@ -1,61 +1,36 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { loadFromCache, saveToCache } from '../cacheUtils';
+import { describe, expect, it } from 'vitest';
+import { type Cache, readCache, writeCache } from '../cacheUtils';
 
 describe('cacheUtils', () => {
-  beforeEach(() => {
-    localStorage.clear();
-  });
-
-  it('round-trips data through save and load', () => {
-    saveToCache('test-key', { foo: 'bar' });
-    expect(loadFromCache('test-key')).toEqual({ foo: 'bar' });
+  it('round-trips data through write and read', () => {
+    const cache: Cache = new Map();
+    writeCache(cache, 'test-key', { foo: 'bar' });
+    expect(readCache(cache, 'test-key')).toEqual({ foo: 'bar' });
   });
 
   it('returns undefined for missing keys', () => {
-    expect(loadFromCache('nonexistent')).toBeUndefined();
-  });
-
-  it('returns undefined for expired entries', () => {
-    saveToCache('old', 'data');
-
-    // Patch the stored timestamp to 25 hours ago
-    const raw = localStorage.getItem('preact-ha:old')!;
-    const entry = JSON.parse(raw);
-    entry.timestamp = Date.now() - 25 * 60 * 60 * 1000;
-    localStorage.setItem('preact-ha:old', JSON.stringify(entry));
-
-    expect(loadFromCache('old')).toBeUndefined();
+    const cache: Cache = new Map();
+    expect(readCache(cache, 'nonexistent')).toBeUndefined();
   });
 
-  it('removes expired entries from localStorage', () => {
-    saveToCache('old', 'data');
-
-    const raw = localStorage.getItem('preact-ha:old')!;
-    const entry = JSON.parse(raw);
-    entry.timestamp = Date.now() - 25 * 60 * 60 * 1000;
-    localStorage.setItem('preact-ha:old', JSON.stringify(entry));
-
-    loadFromCache('old');
-    expect(localStorage.getItem('preact-ha:old')).toBeNull();
+  it('overwrites an existing entry', () => {
+    const cache: Cache = new Map();
+    writeCache(cache, 'k', 1);
+    writeCache(cache, 'k', 2);
+    expect(readCache(cache, 'k')).toBe(2);
   });
 
-  it('returns undefined for corrupted JSON', () => {
-    localStorage.setItem('preact-ha:bad', 'not json');
-    expect(loadFromCache('bad')).toBeUndefined();
+  it('isolates entries between separate cache maps', () => {
+    const a: Cache = new Map();
+    const b: Cache = new Map();
+    writeCache(a, 'k', 'a-value');
+    expect(readCache(b, 'k')).toBeUndefined();
   });
 
-  it('handles localStorage write failures gracefully', () => {
-    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const originalSetItem = localStorage.setItem;
-    localStorage.setItem = () => {
-      throw new Error('QuotaExceededError');
-    };
-
-    // Should not throw
-    saveToCache('key', 'value');
-    expect(warnSpy).toHaveBeenCalled();
-
-    localStorage.setItem = originalSetItem;
-    vi.restoreAllMocks();
+  it('stores undefined data without conflating it with a missing key', () => {
+    const cache: Cache = new Map();
+    writeCache(cache, 'k', undefined);
+    expect(cache.has('k')).toBe(true);
+    expect(readCache(cache, 'k')).toBeUndefined();
   });
 });

package/src/__tests__/registerPreactCard.test.tsx

@@ -216,4 +216,79 @@ describe('registerPreactCard', () => {
     const CardClass = customElements.get(type) as any;
     expect(CardClass.getStubConfig()).toEqual({ entities: [] });
   });
+
+  it('tears down the Preact tree after the grace period when removed', () => {
+    vi.useFakeTimers();
+    const type = uniqueType();
+    registerPreactCard({ type, name: 'Test', description: 'Test', Component: TestComponent });
+
+    const card = document.createElement(type) as any;
+    document.body.appendChild(card);
+    card.setConfig({ entities: ['sensor.temp'] });
+    card.hass = makeHass({ 'sensor.temp': { state: '72' } });
+    expect(card.shadowRoot.textContent).toContain('test');
+
+    document.body.removeChild(card);
+
+    // Within the grace window: still mounted.
+    vi.advanceTimersByTime(4000);
+    expect(card.shadowRoot.textContent).toContain('test');
+
+    // Past the grace window: torn down (render(null) clears the shadow root).
+    vi.advanceTimersByTime(2000);
+    expect(card.shadowRoot.textContent).toBe('');
+
+    vi.useRealTimers();
+  });
+
+  it('cancels teardown when reconnected within the grace period', () => {
+    vi.useFakeTimers();
+    const type = uniqueType();
+    registerPreactCard({ type, name: 'Test', description: 'Test', Component: TestComponent });
+
+    const card = document.createElement(type) as any;
+    document.body.appendChild(card);
+    card.setConfig({ entities: ['sensor.temp'] });
+    card.hass = makeHass({ 'sensor.temp': { state: '72' } });
+
+    document.body.removeChild(card);
+    vi.advanceTimersByTime(4000); // still within grace
+    document.body.appendChild(card); // reconnect cancels the scheduled teardown
+
+    vi.advanceTimersByTime(4000); // 8000ms total since removal — would have torn down
+    expect(card.shadowRoot.textContent).toContain('test');
+
+    vi.useRealTimers();
+  });
+
+  it('re-renders the editor on every hass update', () => {
+    const type = uniqueType();
+    let editorRenders = 0;
+    function TestEditor() {
+      editorRenders++;
+      return <div>editor</div>;
+    }
+
+    registerPreactCard({
+      type,
+      name: 'Test',
+      description: 'Test',
+      Component: TestComponent,
+      ConfigComponent: TestEditor,
+    });
+
+    const editor = document.createElement(`${type}-editor`) as any;
+    document.body.appendChild(editor);
+    editor.setConfig({ entities: [] });
+
+    editor.hass = makeHass({});
+    const afterFirstHass = editorRenders;
+    expect(afterFirstHass).toBeGreaterThan(0);
+
+    editor.hass = makeHass({ 'sensor.x': { state: '1' } });
+    expect(editorRenders).toBeGreaterThan(afterFirstHass);
+
+    editor.hass = makeHass({ 'sensor.x': { state: '2' } });
+    expect(editorRenders).toBeGreaterThan(afterFirstHass + 1);
+  });
 });

package/src/__tests__/testHelpers.tsx

@@ -49,18 +49,28 @@ export function createMockSubscribe() {
 interface RenderWithHAOptions extends Omit<RenderOptions, 'wrapper'> {
   hass?: HomeAssistant;
   subscribeFn?: MockSubscribeFn;
+  subscribeToHass?: (cb: () => void) => () => void;
+  // Inject a per-card cache so tests can seed/inspect it.
+  cache?: Map<string, { data: unknown }>;
 }
 
 export function renderWithHA(ui: ComponentChildren, options: RenderWithHAOptions = {}) {
   const {
     hass = makeHass(),
     subscribeFn = createMockSubscribe().subscribe,
+    subscribeToHass,
+    cache,
     ...renderOptions
   } = options;
 
   function Wrapper({ children }: { children: ComponentChildren }) {
     return (
-      <HAProvider hass={hass} subscribeToEntity={subscribeFn}>
+      <HAProvider
+        hass={hass}
+        subscribeToEntity={subscribeFn}
+        subscribeToHass={subscribeToHass}
+        cache={cache}
+      >
         {children}
       </HAProvider>
     );