custom-card-helpers 2.0.0 → 2.1.0

package/src/turn-on-off-entity.ts

@@ -23,3 +23,13 @@ export const turnOnOffEntity = (
 
   return hass.callService(serviceDomain, service, { entity_id: entityId });
 };
+
+export const turnOnEntity = (
+  hass: HomeAssistant,
+  entityId: string
+): Promise<void> => turnOnOffEntity(hass, entityId, true);
+
+export const turnOffEntity = (
+  hass: HomeAssistant,
+  entityId: string
+): Promise<void> => turnOnOffEntity(hass, entityId, false);

package/src/types.ts

@@ -1,5 +1,6 @@
 import {
   HassEntities,
+  HassEntity,
   HassConfig,
   Auth,
   Connection,
@@ -8,6 +9,37 @@ import {
   HassServiceTarget,
 } from "home-assistant-js-websocket";
 import { HapticType } from "./haptic";
+
+export interface DeviceRegistryEntry {
+  id: string;
+  name: string | null;
+  name_by_user: string | null;
+  area_id: string | null;
+  /** Set when this device is a sub-device of another. @since Home Assistant 2026.4 */
+  parent_device_id?: string | null;
+}
+
+export interface AreaRegistryEntry {
+  area_id: string;
+  name: string;
+  floor_id: string | null;
+}
+
+export interface FloorRegistryEntry {
+  floor_id: string;
+  name: string;
+  level: number | null;
+}
+
+/** One part of a composed entity name, as accepted by `formatEntityName`. */
+export type EntityNameItem =
+  | { type: "entity" | "device" | "area" | "floor" }
+  | { type: "text"; text: string };
+
+export interface EntityNameOptions {
+  /** Joins the resolved parts. Defaults to a single space. */
+  separator?: string;
+}
 import { HASSDomEvent } from "./fire-event";
 
 export interface ToggleMenuActionConfig extends BaseActionConfig {
@@ -21,7 +53,7 @@ export interface ToggleActionConfig extends BaseActionConfig {
 export interface CallServiceActionConfig extends BaseActionConfig {
   action: "call-service";
   service: string;
-  service_data?: {
+  data?: {
     entity_id?: string | [string];
     [key: string]: any;
   };
@@ -54,6 +86,16 @@ export interface CustomActionConfig extends BaseActionConfig {
   action: "fire-dom-event";
 }
 
+export interface TurnOnActionConfig extends BaseActionConfig {
+  action: "turn_on";
+  entity?: string;
+}
+
+export interface TurnOffActionConfig extends BaseActionConfig {
+  action: "turn_off";
+  entity?: string;
+}
+
 /**
  * `repeat` and `haptic` are specifically for use in custom cards like the Button-Card
  */
@@ -81,7 +123,18 @@ export type ActionConfig =
   | MoreInfoActionConfig
   | NoActionConfig
   | CustomActionConfig
-  | ToggleMenuActionConfig;
+  | ToggleMenuActionConfig
+  | TurnOnActionConfig
+  | TurnOffActionConfig;
+
+export interface HuiRootElement extends HTMLElement {
+  lovelace: {
+    config: LovelaceConfig;
+    current_view: number;
+    [key: string]: any;
+  };
+  ___curView: number;
+}
 
 export interface Window {
   // Custom panel entry point url
@@ -187,6 +240,21 @@ export interface ServiceCallRequest {
   target?: HassServiceTarget;
 }
 
+// Entry of the entity registry as exposed by the HA frontend in `hass.entities`.
+export interface EntityRegistryDisplayEntry {
+  entity_id: string;
+  name?: string;
+  icon?: string;
+  device_id?: string;
+  area_id?: string;
+  labels: string[];
+  hidden?: boolean;
+  entity_category?: "config" | "diagnostic";
+  translation_key?: string;
+  platform?: string;
+  display_precision?: number;
+}
+
 export interface HomeAssistant {
   auth: Auth;
   connection: Connection;
@@ -218,6 +286,47 @@ export interface HomeAssistant {
     };
   };
 
+  // Registry data. Populated over the websocket connection after connect, and
+  // needed to resolve an entity's naming context. All optional: `floors` only
+  // exists from HA 2024.4, and marking the rest optional keeps this interface
+  // safe to construct in tests and mocks.
+  /** Entity registry keyed by entity_id. */
+  entities?: Record<string, EntityRegistryDisplayEntry>;
+  devices?: Record<string, DeviceRegistryEntry>;
+  areas?: Record<string, AreaRegistryEntry>;
+  floors?: Record<string, FloorRegistryEntry>;
+
+  // Display formatters, which apply the user's locale, precision and naming
+  // preferences the same way the built-in cards do. Optional because each was
+  // added in a specific Home Assistant version - check before calling, or gate
+  // on `hass.config.version`.
+  /** @since Home Assistant 2024.4 */
+  formatEntityState?: (stateObj: HassEntity, state?: string) => string;
+  /** @since Home Assistant 2024.4 */
+  formatEntityAttributeName?: (stateObj: HassEntity, attribute: string) => string;
+  /** @since Home Assistant 2024.4 */
+  formatEntityAttributeValue?: (
+    stateObj: HassEntity,
+    attribute: string,
+    value?: unknown
+  ) => string;
+  /**
+   * Formats an entity's display name from its registry context.
+   *
+   * Accepts a plain string (returned as-is), a single name item, an array of
+   * items joined with the separator, or `undefined` for the default name.
+   *
+   * @since Home Assistant 2026.4 in this shape. The helper exists from 2025.10,
+   * but took bare type strings then, and only accepted `EntityNameItem`s
+   * between 2025.11 and 2026.3 - so feature detection is not sufficient, check
+   * `hass.config.version` before calling with a card's `name` option.
+   */
+  formatEntityName?: (
+    stateObj: HassEntity,
+    name?: string | EntityNameItem | EntityNameItem[],
+    options?: EntityNameOptions
+  ) => string;
+
   dockedSidebar: boolean;
   moreInfoEntityId: string;
   user: CurrentUser;
@@ -238,6 +347,7 @@ export interface HomeAssistant {
   ) => Promise<Response>;
   sendWS: (msg: MessageBase) => Promise<void>;
   callWS: <T>(msg: MessageBase) => Promise<T>;
+  hassUrl: (path?: string) => string;
 }
 
 export enum NumberFormat {
@@ -256,10 +366,37 @@ export enum TimeFormat {
   twenty_four = "24",
 }
 
+export enum TimeZone {
+  local = "local",
+  server = "server",
+}
+
+export enum DateFormat {
+  language = "language",
+  system = "system",
+  DMY = "DMY",
+  MDY = "MDY",
+  YMD = "YMD",
+}
+
+export enum FirstWeekday {
+  language = "language",
+  monday = "monday",
+  tuesday = "tuesday",
+  wednesday = "wednesday",
+  thursday = "thursday",
+  friday = "friday",
+  saturday = "saturday",
+  sunday = "sunday",
+}
+
 export interface FrontendLocaleData {
   language: string;
   number_format: NumberFormat;
   time_format: TimeFormat;
+  date_format: DateFormat;
+  first_weekday: FirstWeekday;
+  time_zone: TimeZone;
 }
 
 export interface LovelaceCardConfig {
@@ -283,6 +420,69 @@ export interface LovelaceCardEditor extends HTMLElement {
   setConfig(config: LovelaceCardConfig): void;
 }
 
+export interface LovelaceCardFeatureConfig {
+  type: string;
+  [key: string]: any;
+}
+
+export type LovelaceCardFeaturePosition = "bottom" | "inline";
+
+export interface LovelaceCardFeatureContext {
+  entity_id?: string;
+  area_id?: string;
+}
+
+export interface LovelaceCardFeature extends HTMLElement {
+  hass?: HomeAssistant;
+  /** @deprecated Use `context` instead */
+  stateObj?: HassEntity;
+  context?: LovelaceCardFeatureContext;
+  setConfig(config: LovelaceCardFeatureConfig): void;
+  color?: string;
+  position?: LovelaceCardFeaturePosition;
+}
+
+export interface LovelaceCardFeatureEditor extends HTMLElement {
+  hass?: HomeAssistant;
+  lovelace?: LovelaceConfig;
+  context?: LovelaceCardFeatureContext;
+  setConfig(config: LovelaceCardFeatureConfig): void;
+}
+
+// Loose description of a ha-form schema item
+export interface HaFormSchema {
+  name?: string;
+  type?: string;
+  [key: string]: any;
+}
+
+// Static side of a card feature class, e.g. `MyFeature satisfies LovelaceCardFeatureConstructor`
+export interface LovelaceCardFeatureConstructor {
+  new (...args: any[]): LovelaceCardFeature;
+  getStubConfig?: (
+    hass: HomeAssistant,
+    context?: LovelaceCardFeatureContext
+  ) => LovelaceCardFeatureConfig;
+  getConfigElement?: () => LovelaceCardFeatureEditor;
+  getConfigForm?: () => {
+    schema: HaFormSchema[];
+    assertConfig?: (config: LovelaceCardConfig) => void;
+  };
+}
+
+// Entry for `window.customCardFeatures`, shown in the card feature picker
+export interface CustomCardFeatureEntry {
+  type: string;
+  name?: string;
+  configurable?: boolean;
+  isSupported?: (
+    hass: HomeAssistant,
+    context: LovelaceCardFeatureContext
+  ) => boolean;
+  /** @deprecated Use `isSupported` instead */
+  supported?: (stateObj: HassEntity) => boolean;
+}
+
 export interface LovelaceConfig {
   title?: string;
   views: LovelaceViewConfig[];
@@ -339,7 +539,7 @@ export interface EntitiesCardEntityConfig extends EntityConfig {
     | "brightness";
   action_name?: string;
   service?: string;
-  service_data?: Record<string, unknown>;
+  data?: Record<string, unknown>;
   url?: string;
   tap_action?: ActionConfig;
   hold_action?: ActionConfig;

package/test/datetime.test.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import durationToSeconds from "../src/datetime/duration_to_seconds";
-import secondsToDuration from "../src/datetime/seconds_to_duration";
+import { durationToSeconds } from "../src/datetime/duration_to_seconds";
+import { secondsToDuration } from "../src/datetime/seconds_to_duration";
 import { timerTimeRemaining } from "../src/datetime/timer_time_remaining";
 import { useAmPm } from "../src/datetime/use_am_pm";
 import { TimeFormat } from "../src/types";

package/test/icons.test.ts

@@ -4,6 +4,7 @@ import { coverIcon } from "../src/cover_icon";
 import { domainIcon } from "../src/domain_icons";
 import { inputDateTimeIcon } from "../src/input_datetime_icon";
 import { sensorIcon } from "../src/sensor_icon";
+import { stateIcon } from "../src/state_icon";
 
 describe("domainIcon", () => {
   it("returns fixed icons and state-based icons", () => {
@@ -54,6 +55,36 @@ describe("coverIcon", () => {
       coverIcon({ state: "closed", attributes: { device_class: "garage" } } as any)
     ).toBe("mdi:garage");
   });
+
+  const icon = (state: string, device_class?: string) =>
+    coverIcon({ state, attributes: { device_class } } as any);
+
+  it("returns transitional icons while opening and closing", () => {
+    expect(icon("opening", "garage")).toBe("mdi:arrow-up-box");
+    expect(icon("closing", "garage")).toBe("mdi:arrow-down-box");
+    expect(icon("opening", "gate")).toBe("mdi:gate-arrow-right");
+    expect(icon("opening", "curtain")).toBe("mdi:arrow-split-vertical");
+    expect(icon("closing", "curtain")).toBe("mdi:arrow-collapse-horizontal");
+    expect(icon("opening", "shade")).toBe("mdi:arrow-up-box");
+  });
+
+  it("returns closed and open icons for newly supported classes", () => {
+    expect(icon("closed", "gate")).toBe("mdi:gate");
+    expect(icon("open", "gate")).toBe("mdi:gate-open");
+    expect(icon("closed", "shutter")).toBe("mdi:window-shutter");
+    expect(icon("open", "curtain")).toBe("mdi:curtains");
+    expect(icon("closed", "curtain")).toBe("mdi:curtains-closed");
+    expect(icon("closed", "blind")).toBe("mdi:blinds");
+    expect(icon("open", "damper")).toBe("mdi:circle");
+    expect(icon("closed", "damper")).toBe("mdi:circle-slice-8");
+  });
+
+  it("falls back to window icons for unknown device classes", () => {
+    expect(icon("closed")).toBe("mdi:window-closed");
+    expect(icon("open")).toBe("mdi:window-open");
+    expect(icon("opening")).toBe("mdi:arrow-up-box");
+    expect(icon("closing")).toBe("mdi:arrow-down-box");
+  });
 });
 
 describe("inputDateTimeIcon", () => {
@@ -69,3 +100,23 @@ describe("inputDateTimeIcon", () => {
     );
   });
 });
+
+describe("stateIcon", () => {
+  it("returns correct icon for binary_sensor with device_class", () => {
+    const stateObj = {
+      entity_id: "binary_sensor.door",
+      state: "off",
+      attributes: { device_class: "door" },
+    } as any;
+    expect(stateIcon(stateObj)).toBe("mdi:door-closed");
+  });
+
+  it("returns correct icon for binary_sensor on state", () => {
+    const stateObj = {
+      entity_id: "binary_sensor.door",
+      state: "on",
+      attributes: { device_class: "door" },
+    } as any;
+    expect(stateIcon(stateObj)).toBe("mdi:door-open");
+  });
+});

package/test/service-actions.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { toggleEntity } from "../src/toggle-entity";
 import { turnOnOffEntities } from "../src/turn-on-off-entities";
-import { turnOnOffEntity } from "../src/turn-on-off-entity";
+import { turnOnOffEntity, turnOnEntity, turnOffEntity } from "../src/turn-on-off-entity";
 
 describe("turnOnOffEntity", () => {
   it("uses domain-specific lock and cover services", async () => {
@@ -46,6 +46,24 @@ describe("toggleEntity", () => {
   });
 });
 
+describe("turnOnEntity / turnOffEntity", () => {
+  it("turnOnEntity calls turn_on service", async () => {
+    const callService = vi.fn().mockResolvedValue(undefined);
+    await turnOnEntity({ callService } as any, "scene.movie_night");
+    expect(callService).toHaveBeenCalledWith("scene", "turn_on", {
+      entity_id: "scene.movie_night",
+    });
+  });
+
+  it("turnOffEntity calls turn_off service", async () => {
+    const callService = vi.fn().mockResolvedValue(undefined);
+    await turnOffEntity({ callService } as any, "switch.kitchen");
+    expect(callService).toHaveBeenCalledWith("switch", "turn_off", {
+      entity_id: "switch.kitchen",
+    });
+  });
+});
+
 describe("turnOnOffEntities", () => {
   it("batches service calls by service domain", () => {
     const callService = vi.fn();