custom-card-helpers 2.0.0 → 2.1.0

package/dist/translations/localize.d.ts

@@ -1,5 +1,4 @@
-import { Resources } from "../types";
-export type LocalizeFunc = (key: string, ...args: any[]) => string;
+import { LocalizeFunc, Resources } from "../types";
 interface FormatType {
     [format: string]: any;
 }

package/dist/turn-on-off-entity.d.ts

@@ -1,2 +1,4 @@
 import { HomeAssistant } from "./types";
 export declare const turnOnOffEntity: (hass: HomeAssistant, entityId: string, turnOn?: boolean) => Promise<void>;
+export declare const turnOnEntity: (hass: HomeAssistant, entityId: string) => Promise<void>;
+export declare const turnOffEntity: (hass: HomeAssistant, entityId: string) => Promise<void>;

package/dist/types.d.ts

@@ -1,5 +1,34 @@
-import { HassEntities, HassConfig, Auth, Connection, MessageBase, HassServices, HassServiceTarget } from "home-assistant-js-websocket";
+import { HassEntities, HassEntity, HassConfig, Auth, Connection, MessageBase, HassServices, 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 {
     action: "toggle-menu";
@@ -10,7 +39,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;
     };
@@ -36,6 +65,14 @@ export interface NoActionConfig extends BaseActionConfig {
 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
  */
@@ -52,7 +89,15 @@ export interface ConfirmationRestrictionConfig {
 export interface RestrictionConfig {
     user: string;
 }
-export type ActionConfig = ToggleActionConfig | CallServiceActionConfig | NavigateActionConfig | UrlActionConfig | MoreInfoActionConfig | NoActionConfig | CustomActionConfig | ToggleMenuActionConfig;
+export type ActionConfig = ToggleActionConfig | CallServiceActionConfig | NavigateActionConfig | UrlActionConfig | MoreInfoActionConfig | NoActionConfig | CustomActionConfig | ToggleMenuActionConfig | TurnOnActionConfig | TurnOffActionConfig;
+export interface HuiRootElement extends HTMLElement {
+    lovelace: {
+        config: LovelaceConfig;
+        current_view: number;
+        [key: string]: any;
+    };
+    ___curView: number;
+}
 export interface Window {
     customPanelJS: string;
     ShadyCSS: {
@@ -147,6 +192,19 @@ export interface ServiceCallRequest {
     serviceData?: Record<string, any>;
     target?: HassServiceTarget;
 }
+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;
@@ -169,6 +227,29 @@ export interface HomeAssistant {
             [lang: string]: Translation;
         };
     };
+    /** Entity registry keyed by entity_id. */
+    entities?: Record<string, EntityRegistryDisplayEntry>;
+    devices?: Record<string, DeviceRegistryEntry>;
+    areas?: Record<string, AreaRegistryEntry>;
+    floors?: Record<string, FloorRegistryEntry>;
+    /** @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;
@@ -181,6 +262,7 @@ export interface HomeAssistant {
     }) => Promise<Response>;
     sendWS: (msg: MessageBase) => Promise<void>;
     callWS: <T>(msg: MessageBase) => Promise<T>;
+    hassUrl: (path?: string) => string;
 }
 export declare enum NumberFormat {
     language = "language",
@@ -196,10 +278,34 @@ export declare enum TimeFormat {
     am_pm = "12",
     twenty_four = "24"
 }
+export declare enum TimeZone {
+    local = "local",
+    server = "server"
+}
+export declare enum DateFormat {
+    language = "language",
+    system = "system",
+    DMY = "DMY",
+    MDY = "MDY",
+    YMD = "YMD"
+}
+export declare 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 {
     index?: number;
@@ -219,6 +325,52 @@ export interface LovelaceCardEditor extends HTMLElement {
     lovelace?: LovelaceConfig;
     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;
+}
+export interface HaFormSchema {
+    name?: string;
+    type?: string;
+    [key: string]: any;
+}
+export interface LovelaceCardFeatureConstructor {
+    new (...args: any[]): LovelaceCardFeature;
+    getStubConfig?: (hass: HomeAssistant, context?: LovelaceCardFeatureContext) => LovelaceCardFeatureConfig;
+    getConfigElement?: () => LovelaceCardFeatureEditor;
+    getConfigForm?: () => {
+        schema: HaFormSchema[];
+        assertConfig?: (config: LovelaceCardConfig) => void;
+    };
+}
+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[];
@@ -261,7 +413,7 @@ export interface EntitiesCardEntityConfig extends EntityConfig {
     secondary_info?: "entity-id" | "last-changed" | "last-triggered" | "last-updated" | "position" | "tilt-position" | "brightness";
     action_name?: string;
     service?: string;
-    service_data?: Record<string, unknown>;
+    data?: Record<string, unknown>;
     url?: string;
     tap_action?: ActionConfig;
     hold_action?: ActionConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "custom-card-helpers",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Set of helpful functions and types for Custom Card creators",
   "main": "dist/index.js",
   "umd:main": "dist/index.umd.js",
@@ -37,9 +37,8 @@
   },
   "homepage": "https://github.com/custom-cards/custom-card-helpers#readme",
   "dependencies": {
-    "@formatjs/intl-utils": "^3.8.4",
     "home-assistant-js-websocket": "^9.6.0",
-    "intl-messageformat": "^11.1.2",
+    "intl-messageformat": "^12.1.5",
     "superstruct": "^2.0.2"
   },
   "peerDependencies": {
@@ -47,12 +46,12 @@
   },
   "devDependencies": {
     "@rollup/plugin-typescript": "^12.1.4",
-    "jsdom": "^26.1.0",
+    "jsdom": "^31.0.0",
     "lit": "^3.3.1",
-    "rollup": "^4.58.0",
+    "rollup": "^4.60.0",
     "tslib": "^2.8.1",
-    "typedoc": "^0.28.17",
+    "typedoc": "^0.28.20",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.0"
   }
-}
+}

package/src/compute-name.ts

@@ -1,4 +1,11 @@
 import { HassEntity } from "home-assistant-js-websocket";
 
+/**
+ * @deprecated Reads `friendly_name`, which Home Assistant is moving away from -
+ * it now always includes the device name, so this duplicates context the
+ * surrounding UI already shows. Prefer `hass.formatEntityName(stateObj, name)`
+ * on HA 2026.4 and later, which resolves the name from the entity's registry
+ * context and lets users choose which parts to include.
+ */
 export const computeName = (stateObj: HassEntity): string =>
   stateObj.attributes.friendly_name || stateObj.entity_id;

package/src/compute-state-display.ts

@@ -2,9 +2,8 @@ import { HassEntity } from "home-assistant-js-websocket";
 import { formatDateTime } from "./datetime/format_date_time";
 import { formatDate } from "./datetime/format_date";
 import { formatTime } from "./datetime/format_time";
-import { LocalizeFunc } from "./translations/localize";
 import { computeStateDomain } from "./compute-state-domain";
-import { FrontendLocaleData } from "./types";
+import { FrontendLocaleData, LocalizeFunc } from "./types";
 import { formatNumber, isNumericState } from "./format-number";
 
 export const computeStateDisplay = (
@@ -126,4 +125,4 @@ export const computeStateDisplay = (
     // We don't know! Return the raw state.
     compareState
   );
-};
+};

package/src/cover_icon.ts

@@ -1,21 +1,89 @@
 /** Return an icon representing a cover state. */
 import { HassEntity } from "home-assistant-js-websocket";
-import { domainIcon } from "./domain_icons";
 
 export const coverIcon = (state: HassEntity): string => {
   const open = state.state !== "closed";
   switch (state.attributes.device_class) {
     case "garage":
-      return open ? "mdi:garage-open" : "mdi:garage";
+      switch (state.state) {
+        case "opening":
+          return "mdi:arrow-up-box";
+        case "closing":
+          return "mdi:arrow-down-box";
+        case "closed":
+          return "mdi:garage";
+        default:
+          return "mdi:garage-open";
+      }
+    case "gate":
+      switch (state.state) {
+        case "opening":
+        case "closing":
+          return "mdi:gate-arrow-right";
+        case "closed":
+          return "mdi:gate";
+        default:
+          return "mdi:gate-open";
+      }
     case "door":
       return open ? "mdi:door-open" : "mdi:door-closed";
+    case "damper":
+      return open ? "mdi:circle" : "mdi:circle-slice-8";
     case "shutter":
-      return open ? "mdi:window-shutter-open" : "mdi:window-shutter";
+      switch (state.state) {
+        case "opening":
+          return "mdi:arrow-up-box";
+        case "closing":
+          return "mdi:arrow-down-box";
+        case "closed":
+          return "mdi:window-shutter";
+        default:
+          return "mdi:window-shutter-open";
+      }
+    case "curtain":
+      switch (state.state) {
+        case "opening":
+          return "mdi:arrow-split-vertical";
+        case "closing":
+          return "mdi:arrow-collapse-horizontal";
+        case "closed":
+          return "mdi:curtains-closed";
+        default:
+          return "mdi:curtains";
+      }
     case "blind":
-      return open ? "mdi:blinds-open" : "mdi:blinds";
+    case "shade":
+      switch (state.state) {
+        case "opening":
+          return "mdi:arrow-up-box";
+        case "closing":
+          return "mdi:arrow-down-box";
+        case "closed":
+          return "mdi:blinds";
+        default:
+          return "mdi:blinds-open";
+      }
     case "window":
-      return open ? "mdi:window-open" : "mdi:window-closed";
+      switch (state.state) {
+        case "opening":
+          return "mdi:arrow-up-box";
+        case "closing":
+          return "mdi:arrow-down-box";
+        case "closed":
+          return "mdi:window-closed";
+        default:
+          return "mdi:window-open";
+      }
     default:
-      return domainIcon("cover", state.state);
+      switch (state.state) {
+        case "opening":
+          return "mdi:arrow-up-box";
+        case "closing":
+          return "mdi:arrow-down-box";
+        case "closed":
+          return "mdi:window-closed";
+        default:
+          return "mdi:window-open";
+      }
   }
 };

package/src/datetime/duration_to_seconds.ts

@@ -3,7 +3,7 @@
  * @param duration hh:mm:ss formated duration
  * @returns duration in seconds
  */
- export default function durationToSeconds(duration: string): number {
+ export function durationToSeconds(duration: string): number {
   const parts = duration.split(":").map(Number);
   return parts[0] * 3600 + parts[1] * 60 + parts[2];
 }

package/src/datetime/relative_time.ts

@@ -1,12 +1,11 @@
 //REF: https://github.com/home-assistant/frontend/blob/dev/src/common/datetime/relative_time.ts
 
-import { selectUnit } from "@formatjs/intl-utils";
 import { FrontendLocaleData } from "../types";
+import { selectUnit } from "./select_unit";
 
  const formatRelTimeMem =
   (locale: FrontendLocaleData) =>
     new Intl.RelativeTimeFormat(locale.language, { numeric: "auto" });
-
 /**
  * Calculate a string representing a date object as relative time from now.
  *

package/src/datetime/seconds_to_duration.ts

@@ -2,7 +2,7 @@
 
 const leftPad = (num: number) => (num < 10 ? `0${num}` : num);
 
-export default function secondsToDuration(d: number) {
+export function secondsToDuration(d: number) {
   const h = Math.floor(d / 3600);
   const m = Math.floor((d % 3600) / 60);
   const s = Math.floor((d % 3600) % 60);

package/src/datetime/select_unit.ts

@@ -0,0 +1,94 @@
+/*
+ * selectUnit() taken from @formatjs/intl-units 3.8.4.
+ *
+ */
+
+export type Unit =
+  | 'second'
+  | 'minute'
+  | 'hour'
+  | 'day'
+  | 'week'
+  | 'month'
+  | 'quarter'
+  | 'year';
+
+const MS_PER_SECOND = 1e3;
+const SECS_PER_MIN = 60;
+const SECS_PER_HOUR = SECS_PER_MIN * 60;
+const SECS_PER_DAY = SECS_PER_HOUR * 24;
+const SECS_PER_WEEK = SECS_PER_DAY * 7;
+
+export function selectUnit(
+  from: Date | number,
+  to: Date | number = Date.now(),
+  thresholds: Partial<Thresholds> = {}
+): {value: number; unit: Unit} {
+  const resolvedThresholds: Thresholds = {
+    ...DEFAULT_THRESHOLDS,
+    ...(thresholds || {}),
+  };
+  const secs = (+from - +to) / MS_PER_SECOND;
+  if (Math.abs(secs) < resolvedThresholds.second) {
+    return {
+      value: Math.round(secs),
+      unit: 'second',
+    };
+  }
+  const mins = secs / SECS_PER_MIN;
+  if (Math.abs(mins) < resolvedThresholds.minute) {
+    return {
+      value: Math.round(mins),
+      unit: 'minute',
+    };
+  }
+  const hours = secs / SECS_PER_HOUR;
+  if (Math.abs(hours) < resolvedThresholds.hour) {
+    return {
+      value: Math.round(hours),
+      unit: 'hour',
+    };
+  }
+
+  const days = secs / SECS_PER_DAY;
+  if (Math.abs(days) < resolvedThresholds.day) {
+    return {
+      value: Math.round(days),
+      unit: 'day',
+    };
+  }
+  const fromDate = new Date(from);
+  const toDate = new Date(to);
+
+  const years = fromDate.getFullYear() - toDate.getFullYear();
+  if (Math.round(Math.abs(years)) > 0) {
+    return {
+      value: Math.round(years),
+      unit: 'year',
+    };
+  }
+
+  const months = years * 12 + fromDate.getMonth() - toDate.getMonth();
+  if (Math.round(Math.abs(months)) > 0) {
+    return {
+      value: Math.round(months),
+      unit: 'month',
+    };
+  }
+  const weeks = secs / SECS_PER_WEEK;
+
+  return {
+    value: Math.round(weeks),
+    unit: 'week',
+  };
+}
+
+type Thresholds = Record<'second' | 'minute' | 'hour' | 'day', number>;
+
+export const DEFAULT_THRESHOLDS: Thresholds = {
+  second: 45, // seconds to minute
+  minute: 45, // minutes to hour
+  hour: 22, // hour to day
+  day: 5, // day to week
+};
+

package/src/datetime/timer_time_remaining.ts

@@ -1,5 +1,5 @@
 import { HassEntity } from "home-assistant-js-websocket";
-import durationToSeconds from "../datetime/duration_to_seconds";
+import { durationToSeconds } from "../datetime/duration_to_seconds";
 
 export function timerTimeRemaining(stateObj: HassEntity) {
   let timeRemaining = durationToSeconds(stateObj.attributes.remaining);

package/src/get-lovelace.ts

@@ -1,17 +1,23 @@
+import { HuiRootElement } from "./types";
+
 export const getLovelace = () => {
-    let root: any = document.querySelector('home-assistant');
-    root = root && root.shadowRoot;
-    root = root && root.querySelector('home-assistant-main');
-    root = root && root.shadowRoot;
-    root = root && root.querySelector('app-drawer-layout partial-panel-resolver');
-    root = root && root.shadowRoot || root;
-    root = root && root.querySelector('ha-panel-lovelace');
-    root = root && root.shadowRoot;
-    root = root && root.querySelector('hui-root');
-    if (root) {
-        const ll = root.lovelace;
-        ll.current_view = root.___curView;
-        return ll;
-    }
-    return null;
-}
+  const root = document
+    .querySelector("home-assistant")
+    ?.shadowRoot?.querySelector("home-assistant-main")?.shadowRoot;
+
+  const resolver =
+    root?.querySelector("ha-drawer partial-panel-resolver") ||
+    root?.querySelector("app-drawer-layout partial-panel-resolver");
+
+  const huiRoot = (resolver?.shadowRoot || resolver)
+    ?.querySelector<HuiRootElement>("ha-panel-lovelace")
+    ?.shadowRoot?.querySelector<HuiRootElement>("hui-root");
+
+  if (huiRoot) {
+    const ll = huiRoot.lovelace;
+    ll.current_view = huiRoot.___curView;
+    return ll;
+  }
+
+  return null;
+};

package/src/handle-action.ts

@@ -1,8 +1,9 @@
-import { HomeAssistant, ActionConfig } from "./types";
+import { HomeAssistant, ActionConfig, TurnOnActionConfig, TurnOffActionConfig } from "./types";
 import { forwardHaptic } from "./haptic";
 import { fireEvent } from "./fire-event";
 import { navigate } from "./navigate";
 import { toggleEntity } from "./toggle-entity";
+import { turnOnOffEntity } from "./turn-on-off-entity";
 
 export const handleActionConfig = (
   node: HTMLElement,
@@ -65,13 +66,29 @@ export const handleActionConfig = (
         forwardHaptic("success");
       }
       break;
+    case "turn_on":
+      turnOnOffEntity(
+        hass,
+        (actionConfig as TurnOnActionConfig).entity || config.entity!,
+        true
+      );
+      forwardHaptic("success");
+      break;
+    case "turn_off":
+      turnOnOffEntity(
+        hass,
+        (actionConfig as TurnOffActionConfig).entity || config.entity!,
+        false
+      );
+      forwardHaptic("success");
+      break;
     case "call-service": {
       if (!actionConfig.service) {
         forwardHaptic("failure");
         return;
       }
       const [domain, service] = actionConfig.service.split(".", 2);
-      hass.callService(domain, service, actionConfig.service_data, actionConfig.target);
+      hass.callService(domain, service, actionConfig.data, actionConfig.target);
       forwardHaptic("success");
       break;
     }

package/src/handle-click.ts

@@ -84,7 +84,7 @@ export const handleClick = (
         return;
       }
       const [domain, service] = actionConfig.service.split(".", 2);
-      const serviceData = { ...actionConfig.service_data };
+      const serviceData = { ...actionConfig.data };
       if (serviceData.entity_id === "entity") {
         serviceData.entity_id = config.entity;
       }

package/src/scroll-to-target.ts

@@ -7,7 +7,7 @@
  * @param {number} top The coordinate to scroll to, along the y-axis.
  * @param {boolean} smooth true if the scroll position should be smoothly adjusted.
  */
-export default function scrollToTarget(element, target) {
+export function scrollToTarget(element, target) {
   // the scroll event will trigger _updateScrollState directly,
   // However, _updateScrollState relies on the previous `scrollTop` to update the states.
   // Calling _updateScrollState will ensure that the states are synced correctly.

package/src/state_icon.ts

@@ -8,7 +8,7 @@ import { inputDateTimeIcon } from "./input_datetime_icon";
 import { domainIcon } from "./domain_icons";
 
 const domainIcons = {
-  binary_sensor: binarySensorIcon,
+  binary_sensor: (stateObj: HassEntity) => binarySensorIcon(stateObj.state, stateObj),
   cover: coverIcon,
   sensor: sensorIcon,
   input_datetime: inputDateTimeIcon,

package/src/translations/localize.ts

@@ -1,9 +1,7 @@
 //REF: https://github.com/home-assistant/frontend/blob/dev/src/common/translations/localize.ts
 
 import IntlMessageFormat from "intl-messageformat";
-import { Resources } from "../types";
-
-export type LocalizeFunc = (key: string, ...args: any[]) => string;
+import { LocalizeFunc, Resources } from "../types";
 
 interface FormatType {
   [format: string]: any;