preact-homeassistant 0.2.3 → 0.3.0

package/dist/index.d.ts

@@ -10,6 +10,12 @@ import { HassServices } from 'home-assistant-js-websocket';
 import { JSX } from 'preact';
 import { RefObject } from 'preact';
 
+declare type Cache_2 = Map<string, CacheEntry<unknown>>;
+
+declare interface CacheEntry<T> {
+    data: T;
+}
+
 /**
  * Calendar entity - only exposes the current/next event.
  * Use useCalendarEvents() to fetch a list of events.
@@ -147,11 +153,13 @@ export declare type ForecastType = 'daily' | 'hourly' | 'twice_daily';
  */
 export declare function getAllStyles(): string;
 
-export declare function HAProvider({ hass, subscribeToEntity, children }: HAProviderProps): JSX.Element;
+export declare function HAProvider({ hass, subscribeToEntity, subscribeToHass, cache, children, }: HAProviderProps): JSX.Element;
 
 declare interface HAProviderProps {
     hass: HomeAssistant | undefined;
     subscribeToEntity: (entityId: string, callback: (entity: any) => void) => () => void;
+    subscribeToHass?: SubscribeToHass;
+    cache?: Cache_2;
     children: ComponentChildren;
 }
 
@@ -174,8 +182,6 @@ declare type KnownDomain = keyof DomainEntityMap;
 
 declare type KnownServiceDomain = keyof DomainServiceMap;
 
-export declare function loadFromCache<T>(key: string): T | undefined;
-
 export declare function registerPreactCard<TConfig>(options: RegisterPreactCardOptions<TConfig>): void;
 
 declare interface RegisterPreactCardOptions<TConfig> {
@@ -202,8 +208,6 @@ export declare function registerRawStyles(styles: string): void;
 
 export declare type ResizeCallback = (size: ElementSize) => void;
 
-export declare function saveToCache<T>(key: string, data: T): void;
-
 declare type ServiceCaller<T extends string> = <S extends keyof ServicesForId<T> & string>(service: S, ...args: ServicesForId<T>[S] extends undefined ? [] : Record<string, never> extends Exclude<ServicesForId<T>[S], undefined> ? [data?: ServicesForId<T>[S]] : [data: ServicesForId<T>[S]]) => Promise<void>;
 
 /**
@@ -214,6 +218,8 @@ declare type ServiceCaller<T extends string> = <S extends keyof ServicesForId<T>
  */
 export declare type ServicesForId<T extends string> = T extends `${infer D}.${string}` ? D extends KnownServiceDomain ? DomainServiceMap[D] : Record<string, Record<string, unknown> | undefined> : Record<string, Record<string, unknown> | undefined>;
 
+declare type SubscribeToHass = (callback: () => void) => () => void;
+
 /**
  * Sun entity - provides sunrise/sunset and elevation information.
  */
@@ -247,18 +253,29 @@ declare interface UseCachedFetchResult<T> {
 }
 
 /**
- * Fetch calendar events for a date range from a single calendar.
+ * 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 declare function useCalendarEvents(entityId: `calendar.${string}`, options: {
+export declare function useCalendarEvents(entityIds: `calendar.${string}`[], options: {
     start: Date;
     end: Date;
 }): UseCalendarEventsResult;
 
 declare 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;
 }
 
 /**
@@ -270,6 +287,9 @@ declare interface UseCalendarEventsResult {
  */
 export declare function useCallbackStable<T extends (...args: never[]) => unknown>(callback: T): T;
 
+/** Re-renders when the active theme's dark mode flips. */
+export declare function useDarkMode(): boolean;
+
 /**
  * Subscribe to a specific entity by ID. Re-renders only when that entity changes.
  *
@@ -289,21 +309,17 @@ export declare function useHass(): {
     getHass: () => HomeAssistant | undefined;
 };
 
+/** Re-renders when `hass.config` changes (units, latitude/longitude, etc.). */
+export declare function useHassConfig(): HomeAssistant['config'] | undefined;
+
 /**
- * Fetch events from multiple calendars for a date range, with localStorage
- * caching. Events are tagged with their source calendar ID.
+ * 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 declare function useMultiCalendarEvents(entityIds: `calendar.${string}`[], options: {
-    start: Date;
-    end: Date;
-}): UseMultiCalendarEventsResult;
-
-declare interface UseMultiCalendarEventsResult {
-    events: CalendarEventWithSource[] | undefined;
-    status: FetchStatus;
-    error: Error | undefined;
-    refetch: () => void;
-}
+export declare function useHassValue<T>(selector: (hass: HomeAssistant | undefined) => T, isEqual?: (a: T, b: T) => boolean): T;
 
 /**
  * Observe an element's size via ResizeObserver. The callback fires:

package/dist/index.js

@@ -1,29 +1,11 @@
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { createContext, render } from "preact";
 import { useRef, useMemo, useState, useEffect, useContext } from "preact/hooks";
-const CACHE_PREFIX = "preact-ha:";
-const CACHE_EXPIRY_MS = 24 * 60 * 60 * 1e3;
-function loadFromCache(key) {
-  try {
-    const raw = localStorage.getItem(`${CACHE_PREFIX}${key}`);
-    if (!raw) return void 0;
-    const entry = JSON.parse(raw);
-    if (Date.now() - entry.timestamp > CACHE_EXPIRY_MS) {
-      localStorage.removeItem(`${CACHE_PREFIX}${key}`);
-      return void 0;
-    }
-    return entry.data;
-  } catch {
-    return void 0;
-  }
+function readCache(cache, key) {
+  return cache.get(key)?.data;
 }
-function saveToCache(key, data) {
-  try {
-    const entry = { data, timestamp: Date.now() };
-    localStorage.setItem(`${CACHE_PREFIX}${key}`, JSON.stringify(entry));
-  } catch (e) {
-    console.warn("[preact-homeassistant cache] Failed to save:", e);
-  }
+function writeCache(cache, key, data) {
+  cache.set(key, { data });
 }
 function useCallbackStable(callback) {
   const callbackRef = useRef(callback);
@@ -36,18 +18,30 @@ function useCallbackStable(callback) {
   }
   return stableRef.current;
 }
+const noopSubscribeToHass = () => () => {
+};
 const HAContext = createContext(null);
-function HAProvider({ hass, subscribeToEntity, children }) {
+function HAProvider({
+  hass,
+  subscribeToEntity,
+  subscribeToHass,
+  cache,
+  children
+}) {
   const hassRef = useRef(hass);
   hassRef.current = hass;
   const getHass = useCallbackStable(() => hassRef.current);
+  const cacheRef = useRef();
+  if (!cacheRef.current) cacheRef.current = cache ?? /* @__PURE__ */ new Map();
+  const resolvedSubscribeToHass = subscribeToHass ?? noopSubscribeToHass;
   const store = useMemo(
     () => ({
-      hass: hassRef.current,
       getHass,
-      subscribeToEntity
+      subscribeToEntity,
+      subscribeToHass: resolvedSubscribeToHass,
+      cache: cacheRef.current
     }),
-    [getHass, subscribeToEntity]
+    [getHass, subscribeToEntity, resolvedSubscribeToHass]
   );
   return /* @__PURE__ */ jsx(HAContext.Provider, { value: store, children });
 }
@@ -62,23 +56,45 @@ function useEntity(entityId) {
   const store = useHAStore();
   const cacheKey = `entity:${entityId}`;
   const [entity, setEntity] = useState(() => {
-    const current = store.hass?.states[entityId];
+    const current = store.getHass()?.states[entityId];
     if (current) return current;
-    return loadFromCache(cacheKey);
+    return readCache(store.cache, cacheKey);
   });
   useEffect(() => {
     const unsubscribe = store.subscribeToEntity(entityId, (newEntity) => {
       setEntity(newEntity);
-      saveToCache(cacheKey, newEntity);
+      writeCache(store.cache, cacheKey, newEntity);
     });
     return unsubscribe;
-  }, [entityId, store.subscribeToEntity, cacheKey]);
+  }, [entityId, store.subscribeToEntity, store.cache, cacheKey]);
   return entity;
 }
 function useHass() {
   const store = useHAStore();
   return { getHass: store.getHass };
 }
+function useHassValue(selector, isEqual = Object.is) {
+  const store = useHAStore();
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+  const isEqualRef = useRef(isEqual);
+  isEqualRef.current = isEqual;
+  const [value, setValue] = useState(() => 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;
+}
+function useHassConfig() {
+  return useHassValue((hass) => hass?.config);
+}
+function useDarkMode() {
+  return useHassValue((hass) => hass?.themes?.darkMode ?? false);
+}
 function useService(entityId) {
   const { getHass } = useHass();
   return useCallbackStable(((service, data) => {
@@ -89,10 +105,19 @@ function useService(entityId) {
   }));
 }
 function useCachedFetch(cacheKey, fetcher, deps) {
-  const [data, setData] = useState(() => loadFromCache(cacheKey));
+  const store = useHAStore();
+  const [data, setData] = useState(() => readCache(store.cache, cacheKey));
   const [isFresh, setIsFresh] = useState(false);
   const [isFetching, setIsFetching] = useState(false);
   const [error, setError] = useState(void 0);
+  const dataKeyRef = useRef(cacheKey);
+  if (cacheKey !== dataKeyRef.current) {
+    dataKeyRef.current = cacheKey;
+    setIsFresh(false);
+    setError(void 0);
+    const cached = readCache(store.cache, cacheKey);
+    if (cached !== void 0) setData(cached);
+  }
   const fetchIdRef = useRef(0);
   const doFetch = useCallbackStable(async () => {
     const fetchId = ++fetchIdRef.current;
@@ -103,7 +128,7 @@ function useCachedFetch(cacheKey, fetcher, deps) {
       if (fetchId === fetchIdRef.current) {
         setData(result);
         setIsFresh(true);
-        saveToCache(cacheKey, result);
+        writeCache(store.cache, cacheKey, result);
       }
     } catch (err) {
       if (fetchId === fetchIdRef.current) {
@@ -126,97 +151,62 @@ function useCachedFetch(cacheKey, fetcher, deps) {
   }, [data, isFresh, isFetching]);
   return { data, status, error, refetch: doFetch };
 }
-function useCalendarEvents(entityId, options) {
-  const { getHass } = useHass();
-  const [events, setEvents] = useState(void 0);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState(void 0);
-  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(void 0);
-    try {
-      const result = await hass.connection.sendMessagePromise({
-        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
-      });
-      if (fetchId === fetchIdRef.current) {
-        const entityEvents = result.response?.[entityId]?.events ?? [];
-        setEvents(entityEvents);
-        setLoading(false);
-      }
-    } catch (err) {
-      if (fetchId === fetchIdRef.current) {
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setLoading(false);
+function calendarEventsCacheKey(entityIds, range) {
+  return `events:${entityIds.join(",")}:${range.start.getTime()}-${range.end.getTime()}`;
+}
+async function fetchCalendarRange(hass, entityIds, range) {
+  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({
+          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) => ({ ...event, calendarId: entityId })
+        );
+      } catch (err) {
+        console.error(`Failed to fetch events for ${entityId}:`, err);
+        return [];
       }
-    }
-  });
-  useEffect(() => {
-    fetchEvents();
-  }, [entityId, options.start.getTime(), options.end.getTime(), fetchEvents]);
-  return { events, loading, error, refetch: fetchEvents };
+    })
+  );
+  return results.flat();
 }
-function useMultiCalendarEvents(entityIds, options) {
+function useCalendarEvents(entityIds, options) {
   const store = useHAStore();
   const { getHass } = useHass();
   const debounceTimerRef = useRef(null);
   const entityIdsKey = entityIds.join(",");
   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({
-            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) => ({ ...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,
     status,
     error,
     refetch
   } = useCachedFetch(cacheKey, fetcher, [entityIdsKey, dateRangeKey]);
+  const prefetch = useCallbackStable((range) => {
+    const key = calendarEventsCacheKey(entityIds, range);
+    if (store.cache.has(key)) return;
+    fetchCalendarRange(getHass(), entityIds, range).then((result) => writeCache(store.cache, key, result)).catch(() => {
+    });
+  });
   const debouncedRefetch = useCallbackStable(() => {
     if (debounceTimerRef.current) {
       clearTimeout(debounceTimerRef.current);
@@ -234,7 +224,7 @@ function useMultiCalendarEvents(entityIds, options) {
       }
     };
   }, [entityIdsKey, store.subscribeToEntity, debouncedRefetch]);
-  return { events, status, error, refetch };
+  return { events, status, error, refetch, prefetch };
 }
 function useWeatherForecast(entityId, type) {
   const store = useHAStore();
@@ -313,6 +303,7 @@ function registerRawStyles(styles) {
 function getAllStyles() {
   return styleRegistry.join("\n");
 }
+const TEARDOWN_GRACE_MS = 5e3;
 function registerPreactCard(options) {
   const {
     type,
@@ -323,19 +314,55 @@ function registerPreactCard(options) {
     UnconfiguredComponent,
     getStubConfig
   } = options;
-  class HACard extends HTMLElement {
+  class BaseHACard extends HTMLElement {
     _hass;
     _config;
+    _teardownTimer;
+    _renderUnconfigured() {
+    }
+    connectedCallback() {
+      if (this._teardownTimer !== void 0) {
+        clearTimeout(this._teardownTimer);
+        this._teardownTimer = void 0;
+      }
+      this._maybeRenderOnConnect();
+    }
+    _maybeRenderOnConnect() {
+      if (this._hass && this._config) {
+        this._render();
+      }
+    }
+    disconnectedCallback() {
+      if (this._teardownTimer !== void 0) clearTimeout(this._teardownTimer);
+      this._teardownTimer = setTimeout(() => {
+        render(null, this._getRenderRoot());
+        this._teardownTimer = void 0;
+      }, TEARDOWN_GRACE_MS);
+    }
+    setConfig(config) {
+      this._config = config;
+      if (this._hass && this.isConnected) {
+        this._render();
+      }
+    }
+    _render() {
+      if (!this._config || !this._hass) {
+        this._renderUnconfigured();
+        return;
+      }
+      this._renderTree();
+    }
+  }
+  class HACard extends BaseHACard {
     _shadowRoot;
     _entityChangeListeners = /* @__PURE__ */ new Map();
+    _hassChangeListeners = /* @__PURE__ */ new Set();
     constructor() {
       super();
       this._shadowRoot = this.attachShadow({ mode: "open" });
     }
-    connectedCallback() {
-      if (this._hass && this._config) {
-        this._render();
-      }
+    _getRenderRoot() {
+      return this._shadowRoot;
     }
     set hass(hass) {
       const prevStates = this._hass?.states;
@@ -347,16 +374,11 @@ function registerPreactCard(options) {
           listeners.forEach((listener) => listener(newState));
         }
       }
+      this._hassChangeListeners.forEach((listener) => listener());
       if (!prevStates && this._config && this.isConnected) {
         this._render();
       }
     }
-    setConfig(config) {
-      this._config = config;
-      if (this._hass && this.isConnected) {
-        this._render();
-      }
-    }
     _subscribeToEntity = (entityId, callback) => {
       if (!this._entityChangeListeners.has(entityId)) {
         this._entityChangeListeners.set(entityId, /* @__PURE__ */ new Set());
@@ -372,21 +394,34 @@ function registerPreactCard(options) {
         }
       };
     };
-    _render() {
-      if (!this._config || !this._hass) {
-        if (UnconfiguredComponent) {
-          render(/* @__PURE__ */ jsx(UnconfiguredComponent, {}), this._shadowRoot);
-        }
-        return;
-      }
+    _subscribeToHass = (callback) => {
+      this._hassChangeListeners.add(callback);
+      return () => {
+        this._hassChangeListeners.delete(callback);
+      };
+    };
+    _renderTree() {
       render(
-        /* @__PURE__ */ jsxs(HAProvider, { hass: this._hass, subscribeToEntity: this._subscribeToEntity, children: [
-          /* @__PURE__ */ jsx("style", { children: getAllStyles() }),
-          /* @__PURE__ */ jsx(Component, { config: this._config })
-        ] }),
+        /* @__PURE__ */ jsxs(
+          HAProvider,
+          {
+            hass: this._hass,
+            subscribeToEntity: this._subscribeToEntity,
+            subscribeToHass: this._subscribeToHass,
+            children: [
+              /* @__PURE__ */ jsx("style", { children: getAllStyles() }),
+              /* @__PURE__ */ jsx(Component, { config: this._config })
+            ]
+          }
+        ),
         this._shadowRoot
       );
     }
+    _renderUnconfigured() {
+      if (UnconfiguredComponent) {
+        render(/* @__PURE__ */ jsx(UnconfiguredComponent, {}), this._shadowRoot);
+      }
+    }
     static getConfigElement() {
       if (ConfigComponent) {
         return document.createElement(`${type}-editor`);
@@ -400,13 +435,19 @@ function registerPreactCard(options) {
   customElements.define(type, HACard);
   if (ConfigComponent) {
     const EditorComponent = ConfigComponent;
-    class HACardEditor extends HTMLElement {
-      _hass;
-      _config;
+    class HACardEditor extends BaseHACard {
+      _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) {
         this._hass = hass;
         this._render();
       }
+      // Render whenever config arrives, regardless of connection — HA may set
+      // config/hass before connecting the editor element.
       setConfig(config) {
         this._config = config;
         this._render();
@@ -420,8 +461,8 @@ function registerPreactCard(options) {
           })
         );
       };
-      _render() {
-        if (!this._hass || !this._config) return;
+      // Render to light DOM so HA's custom elements (ha-form etc.) work.
+      _renderTree() {
         render(
           /* @__PURE__ */ jsx(
             EditorComponent,
@@ -488,16 +529,16 @@ export {
   HAProvider,
   css,
   getAllStyles,
-  loadFromCache,
   registerPreactCard,
   registerRawStyles,
-  saveToCache,
   useCachedFetch,
   useCalendarEvents,
   useCallbackStable,
+  useDarkMode,
   useEntity,
   useHass,
-  useMultiCalendarEvents,
+  useHassConfig,
+  useHassValue,
   useResizeObserver,
   useService,
   useWeatherForecast,