preact-homeassistant 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -8,6 +8,13 @@ import { HassEntityAttributeBase } from 'home-assistant-js-websocket';
 import { HassEntityBase } from 'home-assistant-js-websocket';
 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.
@@ -74,6 +81,11 @@ export declare interface DomainServiceMap {
     fan: FanServices;
 }
 
+export declare interface ElementSize {
+    width: number;
+    height: number;
+}
+
 /**
  * Infers the strict entity type from an entity ID literal type.
  *
@@ -141,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;
 }
 
@@ -168,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> {
@@ -194,7 +206,7 @@ declare interface RegisterPreactCardOptions<TConfig> {
  */
 export declare function registerRawStyles(styles: string): void;
 
-export declare function saveToCache<T>(key: string, data: T): void;
+export declare type ResizeCallback = (size: ElementSize) => 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>;
 
@@ -206,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.
  */
@@ -239,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;
 }
 
 /**
@@ -262,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.
  *
@@ -281,21 +309,50 @@ 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;
+export declare function useHassValue<T>(selector: (hass: HomeAssistant | undefined) => T, isEqual?: (a: T, b: T) => boolean): T;
 
-declare interface UseMultiCalendarEventsResult {
-    events: CalendarEventWithSource[] | undefined;
-    status: FetchStatus;
-    error: Error | undefined;
-    refetch: () => void;
-}
+/**
+ * Observe an element's size via ResizeObserver. The callback fires:
+ *
+ *   1. Once after mount, with the element's current size.
+ *   2. Whenever the element's size changes.
+ *   3. Whenever `deps` change, re-firing with the current size — so callers
+ *      can re-run draws when their inputs change without re-creating the
+ *      observer.
+ *
+ * The callback is suppressed only while the element is detached from the
+ * document. Zero width/height is delivered to the callback as-is — consumers
+ * that need to skip degenerate sizes (e.g. canvas painters where a 0-sized
+ * drawImage throws InvalidStateError) should add their own early return.
+ *
+ * Sizes are read from `offsetWidth` / `offsetHeight` (CSS pixels, includes
+ * padding + border). The callback is held in a ref, so passing a fresh
+ * function each render is safe — it never re-creates the observer.
+ *
+ * @example
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const canvasRef = useRef<HTMLCanvasElement>(null);
+ *
+ * useResizeObserver(
+ *   containerRef,
+ *   ({ width, height }) => {
+ *     if (width === 0 || height === 0) return; // optional, consumer's call
+ *     drawChart(canvasRef.current, forecast, width, height);
+ *   },
+ *   [forecast],
+ * );
+ */
+export declare function useResizeObserver<T extends HTMLElement>(ref: RefObject<T>, callback: ResizeCallback, deps?: unknown[]): void;
 
 /**
  * Returns a stable function that calls services on a specific HA entity.
@@ -323,6 +380,33 @@ declare interface UseWeatherForecastResult {
     refetch: () => void;
 }
 
+/**
+ * Track the current width of a referenced element in CSS pixels.
+ *
+ * Returns `undefined` until the first non-zero measurement is observed, then
+ * a positive number that updates as the element resizes. Once a real width
+ * is captured the hook will never report `undefined` or `0` again, even
+ * during HA layout transitions (dashboard switch, edit-mode toggle) — the
+ * underlying ResizeObserver firings are silently dropped while the element
+ * is detached or transiently zero-width, so the component renders with the
+ * last good value instead of flashing through a degenerate state.
+ *
+ * Use this when you need a width value in JSX (responsive layout, prop to a
+ * sized child). If you only need the value imperatively inside a draw
+ * callback, prefer `useResizeObserver` directly — it doesn't allocate
+ * component state or cause re-renders.
+ *
+ * @example
+ * const ref = useRef<HTMLDivElement>(null);
+ * const width = useWidth(ref);
+ * return (
+ *   <div ref={ref}>
+ *     {width !== undefined && <Chart width={width} />}
+ *   </div>
+ * );
+ */
+export declare function useWidth<T extends HTMLElement>(ref: RefObject<T>): number | undefined;
+
 /**
  * Weather entity - current conditions only.
  * Use useWeatherForecast() to fetch forecast data.