preact-homeassistant 0.2.3 → 0.4.0

package/README.md

@@ -15,7 +15,7 @@ pnpm add preact preact-homeassistant
 ## Quick start
 
 ```tsx
-import { registerPreactCard, useEntity, css } from 'preact-homeassistant';
+import { registerPreactCard, HACard, useEntity, css } from 'preact-homeassistant';
 
 css`
   .my-card { padding: 16px; }
@@ -26,11 +26,11 @@ function MyCardContent({ config }: { config: { entity: string } }) {
   const weather = useEntity(config.entity);
 
   return (
-    <ha-card>
+    <HACard>
       <div class="card-content my-card">
         <span class="temperature">{weather?.state ?? '...'}</span>
       </div>
-    </ha-card>
+    </HACard>
   );
 }
 
@@ -87,6 +87,33 @@ prop and uses hooks for everything else.
 The card renders into a Shadow DOM root. The editor renders into the light DOM
 (required for HA's own custom elements like `<ha-select>` to work).
 
+## `<HACard>`
+
+Use `HACard` as the root of your card instead of a raw `<ha-card>`. It makes the
+card fill the height Home Assistant assigns it.
+
+In HA's **sections (grid)** layout, when a card is resized (e.g. to 3 rows) HA
+gives the card's host element a definite height. A plain `<ha-card>` collapses to
+its natural content height and renders slightly short, leaving a gap. `HACard`
+sets the host and the `ha-card` to fill that height, so the card matches the slot
+exactly. In layouts with no fixed height (masonry, auto rows) it safely collapses
+back to natural height, so it's a drop-in replacement everywhere.
+
+```tsx
+<HACard class="size-large" align="space-between">
+  <div class="card-content my-card">…</div>
+</HACard>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `align` | `HACardAlign` | `'top'` | How content is distributed vertically when the slot is taller than the content. Friendly aliases `top` / `center` / `bottom`, or any flex `justify-content` value (`space-between`, `space-around`, `space-evenly`, `flex-start`, `flex-end`). |
+| `class` | `string` | — | Class applied to the underlying `ha-card`. |
+| `children` | `ComponentChildren` | — | Card contents. |
+
+`align` only positions content as a block. To make an inner section *stretch* to
+absorb the extra height, give it `flex: 1` in your card's CSS.
+
 ## Hooks
 
 ### `useEntity(entityId)`

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ComponentChildren } from 'preact';
 import { ComponentType } from 'preact';
 import { Connection } from 'home-assistant-js-websocket';
+import { createElement } from 'preact';
 import { HassConfig } from 'home-assistant-js-websocket';
 import { HassEntities } from 'home-assistant-js-websocket';
 import { HassEntity } from 'home-assistant-js-websocket';
@@ -10,6 +11,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 +154,23 @@ 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 HACard({ align, class: className, children }: HACardProps): createElement.JSX.Element;
+
+export declare type HACardAlign = 'top' | 'center' | 'bottom' | 'flex-start' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly';
+
+declare interface HACardProps {
+    align?: HACardAlign;
+    class?: string;
+    children?: ComponentChildren;
+}
+
+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 +193,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 +219,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 +229,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 +264,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 +298,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 +320,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: