preact-homeassistant 0.1.0

package/src/__tests__/useWeatherForecast.test.tsx

@@ -0,0 +1,197 @@
+import { act, screen, waitFor } from '@testing-library/preact';
+import { render } from '@testing-library/preact';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { useWeatherForecast } from '../HAContext';
+import { HAProvider } from '../HAContext';
+import type { FetchStatus } from '../types';
+import { createMockSubscribe, makeHass } from './testHelpers';
+
+function ForecastDisplay({
+  entityId,
+  type,
+}: {
+  entityId: `weather.${string}`;
+  type: 'daily' | 'hourly' | 'twice_daily';
+}) {
+  const { forecast, status, error } = useWeatherForecast(entityId, type);
+  return (
+    <div>
+      <span data-testid="count">{forecast?.length ?? 'loading'}</span>
+      <span data-testid="status">{status}</span>
+      <span data-testid="error">{error?.message ?? 'none'}</span>
+      <span data-testid="conditions">{forecast?.map((f) => f.condition).join(',') ?? ''}</span>
+    </div>
+  );
+}
+
+describe('useWeatherForecast', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    vi.restoreAllMocks();
+  });
+
+  it('fetches forecast data', async () => {
+    const sendMessagePromise = vi.fn().mockResolvedValue({
+      response: {
+        'weather.home': {
+          forecast: [
+            { datetime: '2025-01-01T00:00:00Z', condition: 'sunny', temperature: 72 },
+            { datetime: '2025-01-02T00:00:00Z', condition: 'cloudy', temperature: 65 },
+          ],
+        },
+      },
+    });
+
+    const hass = makeHass(
+      {},
+      {
+        connection: { sendMessagePromise } as any,
+      },
+    );
+    const { subscribe } = createMockSubscribe();
+
+    render(
+      <HAProvider hass={hass} subscribeToEntity={subscribe}>
+        <ForecastDisplay entityId="weather.home" type="daily" />
+      </HAProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('status').textContent).toBe('ready');
+    });
+
+    expect(screen.getByTestId('count').textContent).toBe('2');
+    expect(screen.getByTestId('conditions').textContent).toBe('sunny,cloudy');
+  });
+
+  it('sends the correct service call', async () => {
+    const sendMessagePromise = vi.fn().mockResolvedValue({
+      response: { 'weather.home': { forecast: [] } },
+    });
+
+    const hass = makeHass(
+      {},
+      {
+        connection: { sendMessagePromise } as any,
+      },
+    );
+    const { subscribe } = createMockSubscribe();
+
+    render(
+      <HAProvider hass={hass} subscribeToEntity={subscribe}>
+        <ForecastDisplay entityId="weather.home" type="hourly" />
+      </HAProvider>,
+    );
+
+    await waitFor(() => {
+      expect(sendMessagePromise).toHaveBeenCalled();
+    });
+
+    expect(sendMessagePromise).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'call_service',
+        domain: 'weather',
+        service: 'get_forecasts',
+        service_data: { type: 'hourly' },
+        target: { entity_id: 'weather.home' },
+        return_response: true,
+      }),
+    );
+  });
+
+  it('refetches when entity changes (debounced)', async () => {
+    vi.useFakeTimers();
+
+    const sendMessagePromise = vi.fn().mockResolvedValue({
+      response: { 'weather.home': { forecast: [] } },
+    });
+
+    const hass = makeHass(
+      {},
+      {
+        connection: { sendMessagePromise } as any,
+      },
+    );
+    const { subscribe, notify } = createMockSubscribe();
+
+    render(
+      <HAProvider hass={hass} subscribeToEntity={subscribe}>
+        <ForecastDisplay entityId="weather.home" type="daily" />
+      </HAProvider>,
+    );
+
+    // Let initial fetch + timer scheduling settle
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(100);
+    });
+
+    const initialCallCount = sendMessagePromise.mock.calls.length;
+
+    // Simulate entity change
+    act(() => {
+      notify('weather.home', { state: 'cloudy' });
+    });
+
+    // Advance past debounce (500ms)
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(600);
+    });
+
+    expect(sendMessagePromise.mock.calls.length).toBeGreaterThan(initialCallCount);
+
+    vi.useRealTimers();
+  });
+
+  it('handles missing connection', async () => {
+    const hass = makeHass({}, { connection: undefined as any });
+    const { subscribe } = createMockSubscribe();
+
+    render(
+      <HAProvider hass={hass} subscribeToEntity={subscribe}>
+        <ForecastDisplay entityId="weather.home" type="daily" />
+      </HAProvider>,
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId('error').textContent).toContain('connection');
+    });
+  });
+
+  it('schedules hourly refetch', async () => {
+    vi.useFakeTimers();
+
+    const sendMessagePromise = vi.fn().mockResolvedValue({
+      response: { 'weather.home': { forecast: [] } },
+    });
+
+    const hass = makeHass(
+      {},
+      {
+        connection: { sendMessagePromise } as any,
+      },
+    );
+    const { subscribe } = createMockSubscribe();
+
+    render(
+      <HAProvider hass={hass} subscribeToEntity={subscribe}>
+        <ForecastDisplay entityId="weather.home" type="hourly" />
+      </HAProvider>,
+    );
+
+    // Let initial fetch settle
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(100);
+    });
+
+    const callsAfterInit = sendMessagePromise.mock.calls.length;
+
+    // Advance to next hour
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(61 * 60 * 1000);
+    });
+
+    expect(sendMessagePromise.mock.calls.length).toBeGreaterThan(callsAfterInit);
+
+    vi.useRealTimers();
+  });
+});

package/src/cacheUtils.ts

@@ -0,0 +1,32 @@
+const CACHE_PREFIX = 'preact-ha:';
+const CACHE_EXPIRY_MS = 24 * 60 * 60 * 1000;
+
+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;
+
+    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 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);
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export { registerPreactCard } from './registerPreactCard';
+export {
+  HAProvider,
+  useEntity,
+  useHass,
+  useCachedFetch,
+  useCalendarEvents,
+  useMultiCalendarEvents,
+  useWeatherForecast,
+} from './HAContext';
+export { useCallbackStable } from './useCallbackStable';
+export { css, registerRawStyles, getAllStyles } from './styleRegistry';
+export { loadFromCache, saveToCache } from './cacheUtils';
+
+export type {
+  HomeAssistant,
+  FetchStatus,
+  CalendarEntity,
+  CalendarEvent,
+  CalendarEventWithSource,
+  WeatherEntity,
+  WeatherForecast,
+  ForecastType,
+  SunEntity,
+  EntityForId,
+  DomainEntityMap,
+} from './types';

package/src/registerPreactCard.tsx

@@ -0,0 +1,191 @@
+import { type ComponentType, render } from 'preact';
+import { HAProvider } from './HAContext';
+import { getAllStyles } from './styleRegistry';
+import type { HomeAssistant } from './types';
+
+interface RegisterPreactCardOptions<TConfig> {
+  type: string;
+  name: string;
+  description: string;
+  Component: ComponentType<{ config: TConfig }>;
+  ConfigComponent?: ComponentType<{
+    hass: HomeAssistant;
+    config: TConfig;
+    onConfigChanged: (config: TConfig) => void;
+  }>;
+  UnconfiguredComponent?: ComponentType<{}>;
+  getStubConfig?: () => Partial<TConfig>;
+}
+
+declare global {
+  interface Window {
+    customCards?: Array<{ type: string; name: string; description: string }>;
+  }
+}
+
+export function registerPreactCard<TConfig>(options: RegisterPreactCardOptions<TConfig>) {
+  const {
+    type,
+    name,
+    description,
+    Component,
+    ConfigComponent,
+    UnconfiguredComponent,
+    getStubConfig,
+  } = options;
+
+  class HACard extends HTMLElement {
+    private _hass?: HomeAssistant;
+    private _config?: TConfig;
+    private _shadowRoot: ShadowRoot;
+    private _hasRendered = false;
+    private _entityChangeListeners = new Map<string, Set<(entity: any) => void>>();
+
+    constructor() {
+      super();
+      this._shadowRoot = this.attachShadow({ mode: 'open' });
+    }
+
+    connectedCallback() {
+      // HA disconnects + reconnects the element during edit-mode toggling.
+      // Re-rendering on each connect causes Preact to lose its diff anchor and
+      // append a duplicate tree, so only render once per attachment cycle.
+      if (this._hass && this._config && !this._hasRendered) {
+        this._render();
+      }
+    }
+
+    disconnectedCallback() {
+      this._entityChangeListeners.clear();
+    }
+
+    set hass(hass: HomeAssistant) {
+      const prevStates = this._hass?.states;
+      this._hass = hass;
+
+      for (const [entityId, listeners] of this._entityChangeListeners) {
+        const newState = hass.states[entityId];
+        const oldState = prevStates?.[entityId];
+        if (newState !== oldState) {
+          listeners.forEach((listener) => listener(newState));
+        }
+      }
+
+      // Render only when attached. HA may set hass/config before insertion;
+      // rendering into a detached shadow root then again on connect duplicates
+      // the tree. connectedCallback handles the detached-first-render case.
+      if (!prevStates && this._config && this.isConnected) {
+        this._render();
+      }
+    }
+
+    setConfig(config: TConfig) {
+      this._config = config;
+      if (this._hass && this.isConnected) {
+        this._render();
+      }
+    }
+
+    private _subscribeToEntity = (entityId: string, callback: (entity: any) => void) => {
+      if (!this._entityChangeListeners.has(entityId)) {
+        this._entityChangeListeners.set(entityId, new Set());
+      }
+      this._entityChangeListeners.get(entityId)!.add(callback);
+
+      return () => {
+        const listeners = this._entityChangeListeners.get(entityId);
+        if (listeners) {
+          listeners.delete(callback);
+          if (listeners.size === 0) {
+            this._entityChangeListeners.delete(entityId);
+          }
+        }
+      };
+    };
+
+    private _render() {
+      if (!this._config || !this._hass) {
+        if (UnconfiguredComponent) {
+          render(<UnconfiguredComponent />, this._shadowRoot);
+        }
+        return;
+      }
+
+      render(
+        <HAProvider hass={this._hass} subscribeToEntity={this._subscribeToEntity}>
+          <style>{getAllStyles()}</style>
+          <Component config={this._config} />
+        </HAProvider>,
+        this._shadowRoot,
+      );
+      this._hasRendered = true;
+    }
+
+    static getConfigElement() {
+      if (ConfigComponent) {
+        return document.createElement(`${type}-editor`);
+      }
+      return undefined;
+    }
+
+    static getStubConfig() {
+      return getStubConfig?.() ?? {};
+    }
+  }
+
+  customElements.define(type, HACard);
+
+  if (ConfigComponent) {
+    const EditorComponent = ConfigComponent;
+
+    class HACardEditor extends HTMLElement {
+      private _hass?: HomeAssistant;
+      private _config?: TConfig;
+
+      set hass(hass: HomeAssistant) {
+        this._hass = hass;
+        this._render();
+      }
+
+      setConfig(config: TConfig) {
+        this._config = config;
+        this._render();
+      }
+
+      private _fireConfigChanged = (config: TConfig) => {
+        this.dispatchEvent(
+          new CustomEvent('config-changed', {
+            detail: { config },
+            bubbles: true,
+            composed: true,
+          }),
+        );
+      };
+
+      private _render() {
+        if (!this._hass || !this._config) return;
+
+        // Render to light DOM so HA's custom elements (ha-select etc.) work.
+        render(
+          <EditorComponent
+            hass={this._hass}
+            config={this._config}
+            onConfigChanged={this._fireConfigChanged}
+          />,
+          this,
+        );
+      }
+    }
+
+    customElements.define(`${type}-editor`, HACardEditor);
+  }
+
+  window.customCards = window.customCards || [];
+  window.customCards.push({ type, name, description });
+
+  console.info(
+    `%c ${name.toUpperCase()} %c loaded `,
+    'background: #3b82f6; color: white; font-weight: bold',
+    '',
+  );
+}

package/src/styleRegistry.ts

@@ -0,0 +1,31 @@
+// Style registry for Shadow DOM injection
+// Each .styles.ts file uses css`` which auto-registers
+
+const styleRegistry: string[] = [];
+
+/**
+ * CSS tagged template literal for syntax highlighting.
+ * Automatically registers the styles with the global registry.
+ */
+export const css = (strings: TemplateStringsArray, ...values: unknown[]): string => {
+  const result = strings.reduce((acc, str, i) => acc + str + (values[i] ?? ''), '');
+  styleRegistry.push(result);
+  return result;
+};
+
+/**
+ * Register raw CSS string (e.g., from ?inline imports).
+ * Only registers if not already present.
+ */
+export function registerRawStyles(styles: string): void {
+  if (!styleRegistry.includes(styles)) {
+    styleRegistry.push(styles);
+  }
+}
+
+/**
+ * Get all registered styles for Shadow DOM injection.
+ */
+export function getAllStyles(): string {
+  return styleRegistry.join('\n');
+}

package/src/types/calendar.ts

@@ -0,0 +1,40 @@
+import type { HassEntityAttributeBase, HassEntityBase } from 'home-assistant-js-websocket';
+
+/**
+ * Calendar entity - only exposes the current/next event.
+ * Use useCalendarEvents() to fetch a list of events.
+ */
+export interface CalendarEntity extends HassEntityBase {
+  entity_id: `calendar.${string}`;
+  state: 'on' | 'off' | 'unavailable' | 'unknown';
+  attributes: HassEntityAttributeBase & {
+    message?: string;
+    description?: string;
+    start_time?: string;
+    end_time?: string;
+    location?: string;
+    all_day?: boolean;
+  };
+}
+
+/**
+ * Calendar event returned by the calendar/get_events websocket call.
+ */
+export interface CalendarEvent {
+  start: string;
+  end: string;
+  summary: string;
+  description?: string;
+  location?: string;
+  uid?: string;
+  recurrence_id?: string;
+  rrule?: string;
+}
+
+/**
+ * Calendar event with its source calendar entity ID attached. Used by
+ * useMultiCalendarEvents() to disambiguate events from multiple calendars.
+ */
+export interface CalendarEventWithSource extends CalendarEvent {
+  calendarId: string;
+}

package/src/types/common.ts

@@ -0,0 +1,23 @@
+import type {
+  Connection,
+  HassConfig,
+  HassEntities,
+  HassServices,
+} from 'home-assistant-js-websocket';
+
+/**
+ * Subset of the Home Assistant `hass` object passed to custom cards.
+ */
+export interface HomeAssistant {
+  states: HassEntities;
+  config: HassConfig;
+  services: HassServices;
+  connection: Connection;
+  callService: (domain: string, service: string, data?: object) => Promise<void>;
+  themes?: {
+    darkMode?: boolean;
+    theme?: string;
+  };
+}
+
+export type FetchStatus = 'loading' | 'cached' | 'ready' | 'refreshing';

package/src/types/index.ts

@@ -0,0 +1,38 @@
+import type { HassEntity } from 'home-assistant-js-websocket';
+import type { CalendarEntity } from './calendar';
+import type { SunEntity } from './sun';
+import type { WeatherEntity } from './weather';
+
+export type { HomeAssistant, FetchStatus } from './common';
+export type {
+  CalendarEntity,
+  CalendarEvent,
+  CalendarEventWithSource,
+} from './calendar';
+export type { WeatherEntity, WeatherForecast, ForecastType } from './weather';
+export type { SunEntity } from './sun';
+
+/**
+ * Map of known HA domains to their strict entity types. Contributors adding
+ * new domain types should add a new file under `src/types/` and extend this map.
+ */
+export interface DomainEntityMap {
+  calendar: CalendarEntity;
+  weather: WeatherEntity;
+  sun: SunEntity;
+}
+
+type KnownDomain = keyof DomainEntityMap;
+
+/**
+ * Infers the strict entity type from an entity ID literal type.
+ *
+ *   EntityForId<'calendar.family'> -> CalendarEntity
+ *   EntityForId<'weather.home'>    -> WeatherEntity
+ *   EntityForId<'sensor.foo'>      -> HassEntity  (fallback)
+ */
+export type EntityForId<T extends string> = T extends `${infer D}.${string}`
+  ? D extends KnownDomain
+    ? DomainEntityMap[D]
+    : HassEntity
+  : HassEntity;

package/src/types/sun.ts

@@ -0,0 +1,20 @@
+import type { HassEntityAttributeBase, HassEntityBase } from 'home-assistant-js-websocket';
+
+/**
+ * Sun entity - provides sunrise/sunset and elevation information.
+ */
+export interface SunEntity extends HassEntityBase {
+  entity_id: 'sun.sun';
+  state: 'above_horizon' | 'below_horizon';
+  attributes: HassEntityAttributeBase & {
+    next_dawn?: string;
+    next_dusk?: string;
+    next_midnight?: string;
+    next_noon?: string;
+    next_rising?: string;
+    next_setting?: string;
+    elevation?: number;
+    azimuth?: number;
+    rising?: boolean;
+  };
+}

package/src/types/weather.ts

@@ -0,0 +1,42 @@
+import type { HassEntityAttributeBase, HassEntityBase } from 'home-assistant-js-websocket';
+
+/**
+ * Weather entity - current conditions only.
+ * Use useWeatherForecast() to fetch forecast data.
+ */
+export interface WeatherEntity extends HassEntityBase {
+  entity_id: `weather.${string}`;
+  state: string;
+  attributes: HassEntityAttributeBase & {
+    temperature?: number;
+    apparent_temperature?: number;
+    dew_point?: number;
+    humidity?: number;
+    pressure?: number;
+    wind_speed?: number;
+    wind_gust_speed?: number;
+    wind_bearing?: number;
+    visibility?: number;
+    supported_features?: number;
+  };
+}
+
+/**
+ * Weather forecast item returned by the weather/get_forecasts websocket call.
+ */
+export interface WeatherForecast {
+  datetime: string;
+  condition?: string;
+  temperature?: number;
+  templow?: number;
+  precipitation_probability?: number;
+  precipitation?: number;
+  humidity?: number;
+  wind_speed?: number;
+  wind_bearing?: number;
+  cloud_coverage?: number;
+  uv_index?: number;
+  is_daytime?: boolean;
+}
+
+export type ForecastType = 'daily' | 'hourly' | 'twice_daily';

package/src/useCallbackStable.ts

@@ -0,0 +1,24 @@
+import { useRef } from 'preact/hooks';
+
+/**
+ * Creates a stable callback reference that always calls the latest version of the callback.
+ * Unlike useCallback, this never changes identity, so it won't cause re-renders in children.
+ *
+ * @param callback The callback function to stabilize
+ * @returns A stable function reference that always calls the latest callback
+ */
+export function useCallbackStable<T extends (...args: never[]) => unknown>(callback: T): T {
+  const callbackRef = useRef<T>(callback);
+
+  callbackRef.current = callback;
+
+  // Create a stable function reference once
+  const stableRef = useRef<T | null>(null);
+  if (stableRef.current === null) {
+    stableRef.current = ((...args: Parameters<T>) => {
+      return callbackRef.current(...args);
+    }) as T;
+  }
+
+  return stableRef.current;
+}