preact-homeassistant 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stu Kabakoff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# preact-homeassistant
+
+Preact hooks and helpers for building Home Assistant custom cards. Handles the
+web-component lifecycle, Shadow DOM, entity subscriptions, and data fetching so
+you can focus on your card's UI.
+
+## Install
+
+```bash
+pnpm add preact preact-homeassistant
+```
+
+`preact` is a peer dependency.
+
+## Quick start
+
+```tsx
+import { registerPreactCard, useEntity, css } from 'preact-homeassistant';
+
+css`
+  .my-card { padding: 16px; }
+  .my-card .temperature { font-size: 2em; }
+`;
+
+function MyCardContent({ config }: { config: { entity: string } }) {
+  const weather = useEntity(config.entity);
+
+  return (
+    <ha-card>
+      <div class="card-content my-card">
+        <span class="temperature">{weather?.state ?? '...'}</span>
+      </div>
+    </ha-card>
+  );
+}
+
+function MyCardEditor({ hass, config, onConfigChanged }) {
+  const entities = Object.keys(hass.states).filter((e) => e.startsWith('weather.'));
+
+  return (
+    <div style={{ padding: '16px' }}>
+      <ha-select
+        label="Weather entity"
+        value={config.entity}
+        naturalMenuWidth
+        fixedMenuPosition
+        onChange={(e) => onConfigChanged({ ...config, entity: (e.target as HTMLSelectElement).value })}
+        onclosed={(e) => e.stopPropagation()}
+      >
+        {entities.map((id) => (
+          <ha-list-item key={id} value={id}>
+            {hass.states[id]?.attributes?.friendly_name ?? id}
+          </ha-list-item>
+        ))}
+      </ha-select>
+    </div>
+  );
+}
+
+registerPreactCard({
+  type: 'my-weather-card',
+  name: 'My Weather Card',
+  description: 'A simple weather card',
+  Component: MyCardContent,
+  ConfigComponent: MyCardEditor,
+  getStubConfig: () => ({ entity: '' }),
+});
+```
+
+That's it. `registerPreactCard` creates the web component, registers the custom
+element with Home Assistant, sets up Shadow DOM, injects registered styles, and
+wraps your component in the data provider. Your component receives `config` as a
+prop and uses hooks for everything else.
+
+## `registerPreactCard(options)`
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `type` | `string` | Yes | Custom element tag name (e.g. `'my-weather-card'`) |
+| `name` | `string` | Yes | Display name in the HA card picker |
+| `description` | `string` | Yes | Description in the HA card picker |
+| `Component` | `ComponentType<{ config: T }>` | Yes | Main card Preact component |
+| `ConfigComponent` | `ComponentType<{ hass, config, onConfigChanged }>` | No | Visual editor. Receives `hass`, the current `config`, and an `onConfigChanged` callback. Registered as `${type}-editor`. |
+| `UnconfiguredComponent` | `ComponentType<{}>` | No | Shown before config/hass are available |
+| `getStubConfig` | `() => Partial<T>` | No | Default config for the card picker |
+
+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).
+
+## Hooks
+
+### `useEntity(entityId)`
+
+Subscribe to a specific entity. Only re-renders when that entity's state changes.
+
+```tsx
+const sensor = useEntity('sensor.temperature');
+// sensor?.state === '72'
+```
+
+Returns a strict type based on the domain prefix:
+- `'calendar.*'` → `CalendarEntity`
+- `'weather.*'` → `WeatherEntity`
+- `'sun.sun'` → `SunEntity`
+- Other domains → `HassEntity` (the loose type from `home-assistant-js-websocket`)
+
+The mapping comes from the `DomainEntityMap` interface. To add a new domain,
+see the *Contributing types* section below.
+
+### `useHass()`
+
+Access the full `hass` object for calling services or reading config. Does not
+re-render on entity changes.
+
+```tsx
+const { getHass } = useHass();
+await getHass()?.callService('light', 'turn_on', { entity_id: 'light.bedroom' });
+```
+
+### `useCalendarEvents(entityId, { start, end })`
+
+Fetch calendar events for a date range from a single calendar.
+
+### `useMultiCalendarEvents(entityIds, { start, end })`
+
+Fetch events from multiple calendars. Events are returned with `calendarId`
+attached. Caches to localStorage and debounce-refetches when entities change.
+
+```tsx
+const { events, status, error, refetch } = useMultiCalendarEvents(
+  ['calendar.family', 'calendar.work'],
+  { start, end },
+);
+// status: 'loading' | 'cached' | 'ready' | 'refreshing'
+```
+
+### `useWeatherForecast(entityId, type)`
+
+Fetch weather forecast data. Caches to localStorage, debounce-refetches on
+entity changes, and auto-refetches at the top of each hour.
+
+```tsx
+const { forecast, status, error, refetch } = useWeatherForecast('weather.home', 'hourly');
+```
+
+### `useCachedFetch(cacheKey, fetcher, deps)`
+
+Generic hook for fetching data with localStorage caching. The domain-specific
+hooks above are built on this.
+
+## Styles
+
+Styles are registered globally via the `css\`\`` tagged template and
+auto-injected into each card's Shadow DOM by `registerPreactCard`. Use
+`.styles.ts` files imported as side effects.
+
+```tsx
+// MyCard.styles.ts
+import { css } from 'preact-homeassistant';
+
+css`
+  .my-card { padding: 16px; }
+`;
+
+// MyCard.tsx
+import './MyCard.styles'; // registers styles on import
+```
+
+### `registerRawStyles(cssString)`
+
+Register a raw CSS string, e.g. from a Vite `?inline` import.
+
+## Cache utilities
+
+`loadFromCache(key)` / `saveToCache(key, data)` — localStorage wrapper with
+24-hour expiry. Used internally by the data hooks.
+
+## Other utilities
+
+### `useCallbackStable(fn)`
+
+Returns a stable callback ref that always calls the latest `fn`. Avoids effect
+re-runs while keeping the closure current.
+
+## Types
+
+All HA domain types live in [`src/types/`](src/types/):
+
+- [`calendar.ts`](src/types/calendar.ts) — `CalendarEntity`, `CalendarEvent`, `CalendarEventWithSource`
+- [`weather.ts`](src/types/weather.ts) — `WeatherEntity`, `WeatherForecast`, `ForecastType`
+- [`sun.ts`](src/types/sun.ts) — `SunEntity`
+- [`common.ts`](src/types/common.ts) — `HomeAssistant`, `FetchStatus`
+- [`index.ts`](src/types/index.ts) — `DomainEntityMap`, `EntityForId<T>`
+
+Re-exported from the package root:
+
+```ts
+import type {
+  HomeAssistant,
+  CalendarEntity,
+  WeatherEntity,
+  SunEntity,
+  WeatherForecast,
+  EntityForId,
+  /* ... */
+} from 'preact-homeassistant';
+```
+
+## Contributing types
+
+The HA domain types in this package are intentionally minimal — only the
+domains the maintainers have actually needed. If your card needs strict types
+for another domain (light, climate, media_player, cover, etc.), PRs are very
+welcome.
+
+1. Look up the domain in the [Home Assistant frontend repo](https://github.com/home-assistant/frontend/tree/dev/src/data) — most domains have a `data/<domain>.ts` file with TypeScript types.
+2. Add `src/types/<domain>.ts` mirroring the fields your card needs. Extend `HassEntityBase` and `HassEntityAttributeBase` from `home-assistant-js-websocket`.
+3. Add the entity to `DomainEntityMap` in [`src/types/index.ts`](src/types/index.ts) and re-export the types.
+4. Add a quick test under `src/__tests__/` if you're feeling thorough.
+5. PR.
+
+We err toward including only fields that are well-documented; speculative
+attributes can land later.
+
+## Development
+
+```bash
+pnpm install
+pnpm test       # vitest run
+pnpm build      # tsc --noEmit && vite build
+pnpm lint       # biome check
+```
+
+## Publishing
+
+Releases are published to npm manually from a local machine (no CI publish):
+
+```bash
+pnpm test && pnpm build && pnpm typecheck
+git tag v0.X.Y && git push origin v0.X.Y
+pnpm publish --access public --provenance
+```
+
+The `--provenance` flag attaches SLSA build attestation. A GitHub release with
+release notes + the packaged tarball is created automatically when the tag is
+pushed (see [`.github/workflows/release.yml`](.github/workflows/release.yml)).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,276 @@
+import { ComponentChildren } from 'preact';
+import { ComponentType } from 'preact';
+import { Connection } from 'home-assistant-js-websocket';
+import { HassConfig } from 'home-assistant-js-websocket';
+import { HassEntities } from 'home-assistant-js-websocket';
+import { HassEntity } from 'home-assistant-js-websocket';
+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';
+
+/**
+ * Calendar entity - only exposes the current/next event.
+ * Use useCalendarEvents() to fetch a list of events.
+ */
+export declare 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 declare 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 declare interface CalendarEventWithSource extends CalendarEvent {
+    calendarId: string;
+}
+
+/**
+ * CSS tagged template literal for syntax highlighting.
+ * Automatically registers the styles with the global registry.
+ */
+export declare const css: (strings: TemplateStringsArray, ...values: unknown[]) => string;
+
+/**
+ * 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 declare interface DomainEntityMap {
+    calendar: CalendarEntity;
+    weather: WeatherEntity;
+    sun: SunEntity;
+}
+
+/**
+ * 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 declare type EntityForId<T extends string> = T extends `${infer D}.${string}` ? D extends KnownDomain ? DomainEntityMap[D] : HassEntity : HassEntity;
+
+export declare type FetchStatus = 'loading' | 'cached' | 'ready' | 'refreshing';
+
+export declare type ForecastType = 'daily' | 'hourly' | 'twice_daily';
+
+export declare function HAProvider({ hass, subscribeToEntity, children }: HAProviderProps): JSX.Element;
+
+declare interface HAProviderProps {
+    hass: HomeAssistant | undefined;
+    subscribeToEntity: (entityId: string, callback: (entity: any) => void) => () => void;
+    children: ComponentChildren;
+}
+
+/**
+ * Subset of the Home Assistant `hass` object passed to custom cards.
+ */
+export declare interface HomeAssistant {
+    states: HassEntities;
+    config: HassConfig;
+    services: HassServices;
+    connection: Connection;
+    callService: (domain: string, service: string, data?: object) => Promise<void>;
+    themes?: {
+        darkMode?: boolean;
+        theme?: string;
+    };
+}
+
+declare type KnownDomain = keyof DomainEntityMap;
+
+export declare function loadFromCache<T>(key: string): T | undefined;
+
+export declare function registerPreactCard<TConfig>(options: RegisterPreactCardOptions<TConfig>): void;
+
+declare 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>;
+}
+
+/**
+ * Register raw CSS string (e.g., from ?inline imports).
+ * Only registers if not already present.
+ */
+export declare function registerRawStyles(styles: string): void;
+
+export declare function saveToCache<T>(key: string, data: T): void;
+
+/**
+ * Sun entity - provides sunrise/sunset and elevation information.
+ */
+export declare 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;
+    };
+}
+
+/**
+ * Generic hook for fetching data with localStorage caching. Returns a cache-aware
+ * status string to distinguish cached vs fresh data.
+ */
+export declare function useCachedFetch<T>(cacheKey: string, fetcher: () => Promise<T>, deps: unknown[]): UseCachedFetchResult<T>;
+
+declare interface UseCachedFetchResult<T> {
+    data: T | undefined;
+    status: FetchStatus;
+    error: Error | undefined;
+    refetch: () => void;
+}
+
+/**
+ * Fetch calendar events for a date range from a single calendar.
+ */
+export declare function useCalendarEvents(entityId: `calendar.${string}`, options: {
+    start: Date;
+    end: Date;
+}): UseCalendarEventsResult;
+
+declare interface UseCalendarEventsResult {
+    events: CalendarEvent[] | undefined;
+    loading: boolean;
+    error: Error | undefined;
+    refetch: () => void;
+}
+
+/**
+ * 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 declare function useCallbackStable<T extends (...args: never[]) => unknown>(callback: T): T;
+
+/**
+ * Subscribe to a specific entity by ID. Re-renders only when that entity changes.
+ *
+ * Returns a typed entity based on the domain prefix:
+ *   - 'calendar.xyz' -> CalendarEntity
+ *   - 'weather.xyz' -> WeatherEntity
+ *   - 'sun.sun'     -> SunEntity
+ *   - other domains -> HassEntity (fallback)
+ */
+export declare function useEntity<T extends string>(entityId: T): EntityForId<T> | undefined;
+
+/**
+ * Get access to the full hass object for calling services / accessing config.
+ * Does NOT re-render on entity changes. Use useEntity for that.
+ */
+export declare function useHass(): {
+    getHass: () => HomeAssistant | undefined;
+};
+
+/**
+ * Fetch events from multiple calendars for a date range, with localStorage
+ * caching. Events are tagged with their source calendar ID.
+ */
+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;
+}
+
+/**
+ * Fetch weather forecast data with localStorage caching. Auto-refetches at the
+ * top of each hour and when the underlying entity changes (debounced).
+ */
+export declare function useWeatherForecast(entityId: `weather.${string}`, type: ForecastType): UseWeatherForecastResult;
+
+declare interface UseWeatherForecastResult {
+    forecast: WeatherForecast[] | undefined;
+    status: FetchStatus;
+    error: Error | undefined;
+    refetch: () => void;
+}
+
+/**
+ * Weather entity - current conditions only.
+ * Use useWeatherForecast() to fetch forecast data.
+ */
+export declare 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 declare 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 { }