From b068486aebd6c5dc756856797c45a6b1462ad124 Mon Sep 17 00:00:00 2001 From: DigiLive Date: Wed, 23 Apr 2025 07:09:33 +0200 Subject: [PATCH] Refactor types and interfaces. - Update third party types and interfaces to their latest versions. - Strategy types and interface removed from namespace and split into separate files. - Update Strategy types, interfaces and typeguards to be more restrictive and concise. - Add missing docblocks. --- .../common/translations/localize.ts | 15 +- src/types/homeassistant/data/area_registry.ts | 25 +- .../homeassistant/data/device_registry.ts | 60 ++- .../homeassistant/data/entity_registry.ts | 129 ++++-- .../homeassistant/data/floor_registry.ts | 11 +- src/types/homeassistant/data/frontend.ts | 5 + src/types/homeassistant/data/lovelace.ts | 81 ---- .../data/lovelace/config/badge.ts | 12 +- .../data/lovelace/config/card.ts | 19 +- .../data/lovelace/config/section.ts | 39 +- .../data/lovelace/config/strategy.ts | 7 + .../data/lovelace/config/types.ts | 11 +- .../data/lovelace/config/view.ts | 101 +++-- src/types/homeassistant/data/registry.ts | 6 + src/types/homeassistant/data/translations.ts | 117 +++--- src/types/homeassistant/data/ws-themes.ts | 38 +- .../panels/common/validate-condition.ts | 58 ++- .../panels/lovelace/cards/types.ts | 51 +-- .../homeassistant/panels/lovelace/types.ts | 28 +- src/types/homeassistant/types.ts | 306 ++++++++++++--- .../lovelace-mushroom/cards/chips-card.ts | 8 +- .../cards/fan-card-config.ts | 30 +- .../utils/lovelace/chip/types.ts | 16 +- src/types/strategy/cards.ts | 72 ---- src/types/strategy/generic.ts | 367 ------------------ src/types/strategy/strategy-cards.ts | 2 +- src/types/strategy/strategy-generics.ts | 30 +- src/types/strategy/views.ts | 17 - 28 files changed, 818 insertions(+), 843 deletions(-) delete mode 100644 src/types/homeassistant/data/lovelace.ts delete mode 100644 src/types/strategy/cards.ts delete mode 100644 src/types/strategy/generic.ts delete mode 100644 src/types/strategy/views.ts diff --git a/src/types/homeassistant/common/translations/localize.ts b/src/types/homeassistant/common/translations/localize.ts index 96a2a1d..8ad50fb 100644 --- a/src/types/homeassistant/common/translations/localize.ts +++ b/src/types/homeassistant/common/translations/localize.ts @@ -1,10 +1,10 @@ -import type {TranslationDict} from "../../types"; +import type { TranslationDict } from '../../types'; // Exclude some patterns from key type checking for now // These are intended to be removed as errors are fixed // Fixing component category will require tighter definition of types from backend and/or web socket export type LocalizeKeys = - | FlattenObjectKeys> + | FlattenObjectKeys> | `panel.${string}` | `ui.card.alarm_control_panel.${string}` | `ui.card.weather.attributes.${string}` @@ -20,7 +20,7 @@ export type LocalizeKeys = | `ui.dialogs.quick-bar.commands.${string}` | `ui.dialogs.unhealthy.reason.${string}` | `ui.dialogs.unsupported.reason.${string}` - | `ui.panel.config.${string}.${"caption" | "description"}` + | `ui.panel.config.${string}.${'caption' | 'description'}` | `ui.panel.config.dashboard.${string}` | `ui.panel.config.zha.${string}` | `ui.panel.config.zwave_js.${string}` @@ -30,10 +30,7 @@ export type LocalizeKeys = | `component.${string}`; // Tweaked from https://www.raygesualdo.com/posts/flattening-object-keys-with-typescript-types -export type FlattenObjectKeys< - T extends Record, - Key extends keyof T = keyof T, -> = Key extends string +export type FlattenObjectKeys, Key extends keyof T = keyof T> = Key extends string ? T[Key] extends Record ? `${Key}.${FlattenObjectKeys}` : `${Key}` @@ -44,6 +41,6 @@ export type LocalizeFunc = ( key: Keys, values?: Record< string, - string | number | {_$litType$: 1, strings: TemplateStringsArray, values: Array} | null | undefined - > + string | number | { _$litType$: 1; strings: TemplateStringsArray; values: Array } | null | undefined + >, ) => string; diff --git a/src/types/homeassistant/data/area_registry.ts b/src/types/homeassistant/data/area_registry.ts index 211dc3b..a51b4b2 100644 --- a/src/types/homeassistant/data/area_registry.ts +++ b/src/types/homeassistant/data/area_registry.ts @@ -1,17 +1,20 @@ -import {RegistryEntry} from "./registry"; +import { RegistryEntry } from './registry'; /** - * Entry in the Area Registry. + * Represents an entry in the Area Registry in Home Assistant. * - * @property {string[]} aliases Array of aliases of the area. - * @property {string} area_id The id of the area. - * @property {string|null} floor_id The id of the area's floor. - * @property {string|null} humidity_entity_id The id of the area's humidity sensor. - * @property {string|null} icon Icon to show. - * @property {string[]} labels Labels allow grouping elements irrespective of their physical location or type. - * @property {string} name Name of the area. - * @property {string|null} picture URL to a picture that should be used instead of showing the domain icon. - * @property {string|null} temperature_entity_id The id of the area's temperature sensor. + * @property {string[]} aliases - An array of aliases for the area. + * @property {string} area_id - The unique identifier for the area. + * @property {string|null} floor_id - The identifier for the area's floor, or null if not applicable. + * @property {string|null} humidity_entity_id - The identifier for the area's humidity sensor, or null if not + * applicable. + * @property {string|null} icon - The icon to display for the area, or null if not specified. + * @property {string[]} labels - Labels for grouping elements irrespective of their physical location or type. + * @property {string} name - The name of the area. + * @property {string|null} picture - The URL to a picture that should be used instead of the domain icon, or null if + * not specified. + * @property {string|null} temperature_entity_id - The identifier for the area's temperature sensor, or null if not + * applicable. */ export interface AreaRegistryEntry extends RegistryEntry { aliases: string[]; diff --git a/src/types/homeassistant/data/device_registry.ts b/src/types/homeassistant/data/device_registry.ts index 61c510a..99e86d7 100644 --- a/src/types/homeassistant/data/device_registry.ts +++ b/src/types/homeassistant/data/device_registry.ts @@ -1,40 +1,26 @@ /** - * Device Entity. + * Represents a device entity in the of Home Assistant's device registry . * - * @property {string} id Unique ID of a device (generated by Home Assistant). - * @property {string[]} config_entries Config entries that are linked to this device. - * @property {Record} config_entries_subentries - * @property {[string, string][]} connections A set of tuples of (connection_type, connection identifier). - * Connection types are defined in the device registry module. - * Each item in the set uniquely defines a device entry, meaning another - * device can't have the same connection. - * @property {[string, string][]} identifiers Set of (DOMAIN, identifier) tuples. - * Identifiers identify the device in the outside world. - * An example is a serial number. - * Each item in the set uniquely defines a device entry, meaning another - * device can't have the same identifier. - * @property {string | null} manufacturer The manufacturer of the device. - * @property {string | null} model The model name of the device. - * @property {string | null} model_id The model identifier of the device. - * @property {string | null} name Name of this device - * @property {string[]} labels - * @property {string | null} sw_version The firmware version of the device. - * @property {string | null} hw_version The hardware version of the device. - * @property {string | null} serial_number The serial number of the device. - * Unlike a serial number in the identifiers set, this does not need to be - * unique. - * @property {string | null} via_device_id Identifier of a device that routes messages between this device and Home Assistant. - * Examples of such devices are hubs, or parent devices of a sub-device. - * This is used to show device topology in Home Assistant. - * @property {string} area_id The Area which the device is placed in. - * @property {string | null} name_by_user The user configured name of the device. - * @property {string[] | null} entry_type The type of entry. Possible values are None and DeviceEntryType enum members - * (only service). - * @property {string | null} disabled_by Indicates by what this entity is disabled. - * @property {string | null} configuration_url A URL on which the device or service can be configured, - * linking to paths inside the Home Assistant UI can be done by using - * homeassistant://. - * @property {string | null} primary_config_entry + * @property {string} id - Unique identifier of the device (generated by Home Assistant). + * @property {string[]} config_entries - Config entries linked to this device. + * @property {Record} config_entries_subentries - Subentries for the config entries. + * @property {[string, string][]} connections - Tuples of (connection_type, connection identifier). + * @property {[string, string][]} identifiers - Set of (DOMAIN, identifier) tuples identifying the device. + * @property {string | null} manufacturer - The manufacturer of the device. + * @property {string | null} model - The model name of the device. + * @property {string | null} model_id - The model identifier of the device. + * @property {string | null} name - The name of the device. + * @property {string[]} labels - Labels for the device. + * @property {string | null} sw_version - The firmware version of the device. + * @property {string | null} hw_version - The hardware version of the device. + * @property {string | null} serial_number - The serial number of the device. + * @property {string | null} via_device_id - Identifier of a device that routes messages to this device. + * @property {string | null} area_id - The area which the device is placed in. + * @property {string | null} name_by_user - User configured name of the device. + * @property {string[] | null} entry_type - The type of entry (e.g., service). + * @property {string | null} disabled_by - Indicates what disabled this entity. + * @property {string | null} configuration_url - URL for configuring the device. + * @property {string | null} primary_config_entry - Identifier of the primary config entry for the device. */ export interface DeviceRegistryEntry { id: string; @@ -53,8 +39,8 @@ export interface DeviceRegistryEntry { via_device_id: string | null; area_id: string | null; name_by_user: string | null; - entry_type: "service" | null; - disabled_by: "user" | "integration" | "config_entry" | null; + entry_type: 'service' | null; + disabled_by: 'user' | 'integration' | 'config_entry' | null; configuration_url: string | null; primary_config_entry: string | null; } diff --git a/src/types/homeassistant/data/entity_registry.ts b/src/types/homeassistant/data/entity_registry.ts index f856933..7690255 100644 --- a/src/types/homeassistant/data/entity_registry.ts +++ b/src/types/homeassistant/data/entity_registry.ts @@ -1,7 +1,23 @@ -import {LightColor} from "./light"; +import { LightColor } from './light'; -type EntityCategory = "config" | "diagnostic"; +export type EntityCategory = 'config' | 'diagnostic'; +/** + * Represents the display entry for an entity in the entity registry. + * + * @property {string} entity_id - The unique identifier for the entity. + * @property {string} [name] - The name of the entity. + * @property {string} [icon] - The icon associated with the entity. + * @property {string} [device_id] - The ID of the device linked to this entity. + * @property {string} [area_id] - The ID of the area linked to this entity. + * @property {string[]} labels - Labels associated with the entity. + * @property {boolean} [hidden] - Indicates if the entity is hidden. + * @property {EntityCategory} [entity_category] - The category of the entity. + * @property {string} [translation_key] - The translation key for the entity. + * @property {string} [platform] - The platform of the entity. + * @property {number} [display_precision] - The display precision for the entity. + * @property {boolean} [has_entity_name] - Indicates if the entity has a name. + */ export interface EntityRegistryDisplayEntry { entity_id: string; name?: string; @@ -18,41 +34,43 @@ export interface EntityRegistryDisplayEntry { } /** - * Home assistant entity. + * Represents an entity in the entity registry of Home Assistant. * - * @property {string} id - * @property {string} entity_id The id of this entity. - * @property {string} name The name of this entity. - * @property {string | null} icon - * @property {string | null} platform - * @property {string | null} config_entry_id - * @property {string | null} config_subentry_id - * @property {string | null} device_id The id of the device to which this entity is linked. - * @property {string | null} area_id The id of the area to which this entity is linked. - * @property {string[]} labels - * @property {string | null} disabled_by Indicates by what this entity is disabled. - * @property {Object} hidden_by Indicates by what this entity is hidden. - * @property {EntityCategory | null} entity_category - * @property {boolean} has_entity_name - * @property {string} [original_name] - * @property {string} unique_id - * @property {string} [translation_key] - * @property {EntityRegistryOptions | null} options - * @property {Record} categories + * @property {string} id - The unique identifier for the entity. + * @property {string} entity_id - The ID of the entity. + * @property {string | null} name - The name of the entity. + * @property {string | null} icon - The icon associated with the entity. + * @property {string | null} platform - The platform of the entity. + * @property {string | null} config_entry_id - The ID of the config entry associated with the entity. + * @property {string | null} config_subentry_id - The ID of the config subentry associated with the entity. + * @property {string | null} device_id - The ID of the device linked to this entity. + * @property {string | null} area_id - The ID of the area linked to this entity. + * @property {string[]} labels - Labels associated with the entity. + * @property {"user" | "device" | "integration" | "config_entry" | null} disabled_by - Indicates what disabled this + * entity. + * @property {Exclude} hidden_by - Indicates what hidden this + * entity. + * @property {EntityCategory | null} entity_category - The category of the entity. + * @property {boolean} has_entity_name - Indicates if the entity has a name. + * @property {string} [original_name] - The original name of the entity. + * @property {string} unique_id - The unique identifier for the entity. + * @property {string} [translation_key] - The translation key for the entity. + * @property {EntityRegistryOptions | null} options - Additional options for the entity. + * @property {Record} categories - Categories associated with the entity. */ export interface EntityRegistryEntry { id: string; entity_id: string; name: string | null; icon: string | null; - platform: string; + platform: string | null; config_entry_id: string | null; config_subentry_id: string | null; device_id: string | null; area_id: string | null; labels: string[]; - disabled_by: "user" | "device" | "integration" | "config_entry" | null; - hidden_by: Exclude; + disabled_by: 'user' | 'device' | 'integration' | 'config_entry' | null; + hidden_by: Exclude; entity_category: EntityCategory | null; has_entity_name: boolean; original_name?: string; @@ -62,28 +80,64 @@ export interface EntityRegistryEntry { categories: Record; } +/** + * Represents options for a sensor entity in Home Assistant. + * + * @property {number | null} [display_precision] - The display precision for the sensor. + * @property {number | null} [suggested_display_precision] - Suggested display precision for the sensor. + * @property {string | null} [unit_of_measurement] - The unit of measurement for the sensor. + */ export interface SensorEntityOptions { display_precision?: number | null; suggested_display_precision?: number | null; unit_of_measurement?: string | null; } +/** + * Represents options for a light entity in Home Assistant. + * + * @property {LightColor[]} [favorite_colors] - An array of favorite colors for the light. + */ export interface LightEntityOptions { favorite_colors?: LightColor[]; } +/** + * Represents options for a number entity in Home Assistant. + * + * @property {string | null} [unit_of_measurement] - The unit of measurement for the number. + */ export interface NumberEntityOptions { unit_of_measurement?: string | null; } +/** + * Represents options for a lock entity in Home Assistant. + * + * @property {string | null} [default_code] - The default code for the lock. + */ export interface LockEntityOptions { default_code?: string | null; } +/** + * Represents options for an alarm control panel entity in Home Assistant. + * + * @property {string | null} [default_code] - The default code for the alarm control panel. + */ export interface AlarmControlPanelEntityOptions { default_code?: string | null; } +/** + * Represents options for a weather entity in Home Assistant. + * + * @property {string | null} [precipitation_unit] - The unit of measurement for precipitation. + * @property {string | null} [pressure_unit] - The unit of measurement for pressure. + * @property {string | null} [temperature_unit] - The unit of measurement for temperature. + * @property {string | null} [visibility_unit] - The unit of measurement for visibility. + * @property {string | null} [wind_speed_unit] - The unit of measurement for wind speed. + */ export interface WeatherEntityOptions { precipitation_unit?: string | null; pressure_unit?: string | null; @@ -92,11 +146,31 @@ export interface WeatherEntityOptions { wind_speed_unit?: string | null; } +/** + * Represents options for a switch entity in Home Assistant. + * + * @property {string} entity_id - The ID of the entity. + * @property {boolean} invert - Indicates if the switch should be inverted. + */ export interface SwitchAsXEntityOptions { entity_id: string; invert: boolean; } +/** + * Represents options for an entity in the entity registry of Home Assistant. + * + * @property {NumberEntityOptions} [number] - Options for number entities. + * @property {SensorEntityOptions} [sensor] - Options for sensor entities. + * @property {AlarmControlPanelEntityOptions} [alarm_control_panel] - Options for alarm control panel entities. + * @property {LockEntityOptions} [lock] - Options for lock entities. + * @property {WeatherEntityOptions} [weather] - Options for weather entities. + * @property {LightEntityOptions} [light] - Options for light entities. + * @property {SwitchAsXEntityOptions} [switch_as_x] - Options for switch entities. + * @property {Record} [conversation] - Options for conversation entities. + * @property {Record} ["cloud.alexa"] - Options for Alexa cloud integration. + * @property {Record} ["cloud.google_assistant"] - Options for Google Assistant cloud integration. + */ export interface EntityRegistryOptions { number?: NumberEntityOptions; sensor?: SensorEntityOptions; @@ -106,7 +180,6 @@ export interface EntityRegistryOptions { light?: LightEntityOptions; switch_as_x?: SwitchAsXEntityOptions; conversation?: Record; - "cloud.alexa"?: Record; - "cloud.google_assistant"?: Record; + 'cloud.alexa'?: Record; + 'cloud.google_assistant'?: Record; } - diff --git a/src/types/homeassistant/data/floor_registry.ts b/src/types/homeassistant/data/floor_registry.ts index eccbaa5..1387cc3 100644 --- a/src/types/homeassistant/data/floor_registry.ts +++ b/src/types/homeassistant/data/floor_registry.ts @@ -1,5 +1,14 @@ -import {RegistryEntry} from "./registry"; +import { RegistryEntry } from './registry'; +/** + * Represents a floor entry in the Floor Registry of Home Assistant. + * + * @property {string} floor_id - The unique identifier for the floor. + * @property {string} name - The name of the floor. + * @property {number | null} level - The level of the floor (optional). + * @property {string | null} icon - The icon associated with the floor (optional). + * @property {string[]} aliases - An array of aliases for the floor. + */ export interface FloorRegistryEntry extends RegistryEntry { floor_id: string; name: string; diff --git a/src/types/homeassistant/data/frontend.ts b/src/types/homeassistant/data/frontend.ts index 3155312..8c7c77c 100644 --- a/src/types/homeassistant/data/frontend.ts +++ b/src/types/homeassistant/data/frontend.ts @@ -1,3 +1,8 @@ +/** + * Represents user data for the frontend in Home Assistant. + * + * @property {boolean} [showAdvanced] - Indicates whether advanced options should be shown to the user. + */ export interface CoreFrontendUserData { showAdvanced?: boolean; } diff --git a/src/types/homeassistant/data/lovelace.ts b/src/types/homeassistant/data/lovelace.ts deleted file mode 100644 index 6eb3c69..0000000 --- a/src/types/homeassistant/data/lovelace.ts +++ /dev/null @@ -1,81 +0,0 @@ -import {HassServiceTarget} from "home-assistant-js-websocket"; -import {LovelaceGridOptions, LovelaceLayoutOptions} from "../panels/lovelace/types"; -import {Condition} from "../panels/common/validate-condition"; - -export interface LovelaceCardConfig { - index?: number; - view_index?: number; - view_layout?: any; - /** @deprecated Use `grid_options` instead */ - layout_options?: LovelaceLayoutOptions; - grid_options?: LovelaceGridOptions; - type: string; - [key: string]: any; - visibility?: Condition[]; -} - -export interface ToggleActionConfig extends BaseActionConfig { - action: "toggle"; -} - -export interface CallServiceActionConfig extends BaseActionConfig { - action: "call-service"; - service: string; - target?: HassServiceTarget; - // Property "service_data" is kept for backwards compatibility. Replaced by "data". - service_data?: Record; - data?: Record; -} - -export interface NavigateActionConfig extends BaseActionConfig { - action: "navigate"; - navigation_path: string; - navigation_replace?: boolean; -} - -export interface UrlActionConfig extends BaseActionConfig { - action: "url"; - url_path: string; -} - -export interface MoreInfoActionConfig extends BaseActionConfig { - action: "more-info"; -} - -export interface AssistActionConfig extends BaseActionConfig { - action: "assist"; - pipeline_id?: string; - start_listening?: boolean; -} - -export interface NoActionConfig extends BaseActionConfig { - action: "none"; -} - -export interface CustomActionConfig extends BaseActionConfig { - action: "fire-dom-event"; -} - -export interface BaseActionConfig { - action: string; - confirmation?: ConfirmationRestrictionConfig; -} - -export interface ConfirmationRestrictionConfig { - text?: string; - exemptions?: RestrictionConfig[]; -} - -export interface RestrictionConfig { - user: string; -} - -export type ActionConfig = - | ToggleActionConfig - | CallServiceActionConfig - | NavigateActionConfig - | UrlActionConfig - | MoreInfoActionConfig - | AssistActionConfig - | NoActionConfig - | CustomActionConfig; diff --git a/src/types/homeassistant/data/lovelace/config/badge.ts b/src/types/homeassistant/data/lovelace/config/badge.ts index d9e2450..cdc929d 100644 --- a/src/types/homeassistant/data/lovelace/config/badge.ts +++ b/src/types/homeassistant/data/lovelace/config/badge.ts @@ -1,7 +1,15 @@ -import {Condition} from "../../../panels/common/validate-condition"; +import { Condition } from '../../../panels/common/validate-condition'; +/** + * Represents the configuration for a Lovelace badge in Home Assistant. + * + * @property {string} type - The type of the badge. + * @property {Condition[]} [visibility] - An optional array of visibility conditions for the badge. + * @property {any} [key] - Additional properties can be included in the configuration. + */ export interface LovelaceBadgeConfig { type: string; - [key: string]: any; visibility?: Condition[]; + + [key: string]: any; } diff --git a/src/types/homeassistant/data/lovelace/config/card.ts b/src/types/homeassistant/data/lovelace/config/card.ts index b25ce02..4deef03 100644 --- a/src/types/homeassistant/data/lovelace/config/card.ts +++ b/src/types/homeassistant/data/lovelace/config/card.ts @@ -1,6 +1,18 @@ -import {Condition} from "../../../panels/common/validate-condition"; -import {LovelaceGridOptions, LovelaceLayoutOptions} from "../../../panels/lovelace/types"; +import { Condition } from '../../../panels/common/validate-condition'; +import { LovelaceGridOptions, LovelaceLayoutOptions } from '../../../panels/lovelace/types'; +/** + * Represents the configuration for a Lovelace card in Home Assistant. + * + * @property {number} [index] - The index of the card in the view. + * @property {number} [view_index] - The index of the view the card belongs to. + * @property {any} [view_layout] - The layout options for the card view. + * @property {LovelaceLayoutOptions} [layout_options] - Deprecated layout options; use `grid_options` instead. + * @property {LovelaceGridOptions} [grid_options] - The grid options for the card layout. + * @property {string} type - The type of the card. + * @property {Condition[]} [visibility] - An optional array of visibility conditions for the card. + * @property {any} [key] - Additional properties can be included in the configuration. + */ export interface LovelaceCardConfig { index?: number; view_index?: number; @@ -9,6 +21,7 @@ export interface LovelaceCardConfig { layout_options?: LovelaceLayoutOptions; grid_options?: LovelaceGridOptions; type: string; - [key: string]: any; visibility?: Condition[]; + + [key: string]: any; } diff --git a/src/types/homeassistant/data/lovelace/config/section.ts b/src/types/homeassistant/data/lovelace/config/section.ts index 3b5b07e..72ae099 100644 --- a/src/types/homeassistant/data/lovelace/config/section.ts +++ b/src/types/homeassistant/data/lovelace/config/section.ts @@ -1,27 +1,42 @@ -import {LovelaceStrategyConfig} from "./strategy"; -import {LovelaceCardConfig} from "../../lovelace"; -import {Condition} from "../../../panels/common/validate-condition"; +import { Condition } from '../../../panels/common/validate-condition'; +import { LovelaceCardConfig } from './card'; +import { LovelaceStrategyConfig } from './strategy'; +/** + * Represents the base configuration for a Lovelace section in Home Assistant. + * + * @property {Condition[]} [visibility] - An optional array of visibility conditions for the section. + * @property {number} [column_span] - The number of columns the section spans. + * @property {number} [row_span] - The number of rows the section spans. + * @property {string} [title] - The title of the section (deprecated; use heading card instead). + */ export interface LovelaceBaseSectionConfig { visibility?: Condition[]; column_span?: number; row_span?: number; - /** - * @deprecated Use heading card instead. - */ + /** @deprecated Use heading card instead. */ title?: string; } -export interface LovelaceSectionConfig extends LovelaceBaseSectionConfig { +export interface LovelaceSectionConfig /** + * Represents the configuration for a Lovelace section in Home Assistant. + * + * @property {string} [type] - The type of the section. + * @property {LovelaceCardConfig[]} [cards] - An optional array of cards contained within the section. + */ + extends LovelaceBaseSectionConfig { type?: string; cards?: LovelaceCardConfig[]; } -export interface LovelaceStrategySectionConfig - extends LovelaceBaseSectionConfig { +/** + * Represents the configuration for a Lovelace strategy section in Home Assistant. + * + * @property {LovelaceStrategyConfig} strategy - The strategy configuration for the section. + */ +export interface LovelaceStrategySectionConfig extends LovelaceBaseSectionConfig { strategy: LovelaceStrategyConfig; } -export type LovelaceSectionRawConfig = - | LovelaceSectionConfig - | LovelaceStrategySectionConfig; +/** Represents the raw configuration for a Lovelace section in Home Assistant. */ +export type LovelaceSectionRawConfig = LovelaceSectionConfig | LovelaceStrategySectionConfig; diff --git a/src/types/homeassistant/data/lovelace/config/strategy.ts b/src/types/homeassistant/data/lovelace/config/strategy.ts index 5c35de4..46107d8 100644 --- a/src/types/homeassistant/data/lovelace/config/strategy.ts +++ b/src/types/homeassistant/data/lovelace/config/strategy.ts @@ -1,4 +1,11 @@ +/** + * Represents the configuration for a Lovelace strategy in Home Assistant. + * + * @property {string} type - The type of the strategy. + * @property {any} [key] - Additional properties can be included in the configuration. + */ export interface LovelaceStrategyConfig { type: string; + [key: string]: any; } diff --git a/src/types/homeassistant/data/lovelace/config/types.ts b/src/types/homeassistant/data/lovelace/config/types.ts index d1b8b53..0a678c0 100644 --- a/src/types/homeassistant/data/lovelace/config/types.ts +++ b/src/types/homeassistant/data/lovelace/config/types.ts @@ -1,10 +1,15 @@ -import {LovelaceViewRawConfig} from "./view"; +import { LovelaceViewRawConfig } from './view'; +/** Represents the base configuration for a Lovelace dashboard in Home Assistant. */ export interface LovelaceDashboardBaseConfig {} +/** + * Represents the configuration for a Lovelace dashboard in Home Assistant. + * + * @property {string} [background] - An optional background image or color for the dashboard. + * @property {LovelaceViewRawConfig[]} views - An array of views contained within the dashboard. + */ export interface LovelaceConfig extends LovelaceDashboardBaseConfig { background?: string; views: LovelaceViewRawConfig[]; } - - diff --git a/src/types/homeassistant/data/lovelace/config/view.ts b/src/types/homeassistant/data/lovelace/config/view.ts index 3173211..508b8b9 100644 --- a/src/types/homeassistant/data/lovelace/config/view.ts +++ b/src/types/homeassistant/data/lovelace/config/view.ts @@ -1,36 +1,76 @@ -import {LovelaceStrategyConfig} from "./strategy"; -import {LovelaceSectionRawConfig} from "./section"; -import {LovelaceCardConfig} from "./card"; -import {LovelaceBadgeConfig} from "./badge"; +import { LovelaceBadgeConfig } from './badge'; +import { LovelaceCardConfig } from './card'; +import { LovelaceSectionRawConfig } from './section'; +import { LovelaceStrategyConfig } from './strategy'; +/** + * Represents the configuration for showing a view in Home Assistant. + * + * @property {string} [user] - The user associated with the view. + */ export interface ShowViewConfig { user?: string; } +/** + * Represents the background configuration for a Lovelace view in Home Assistant. + * + * @property {string} [image] - The background image URL. + * @property {number} [opacity] - The opacity of the background. + * @property {'auto' | 'cover' | 'contain'} [size] - The size of the background image. + * @property {'top left' | 'top center' | 'top right' | 'center left' | 'center' | 'center right' | 'bottom left' | + * 'bottom center' | 'bottom right'} [alignment] - The alignment of the background image. + * @property {'repeat' | 'no-repeat'} [repeat] - The repeat behavior of the background image. + * @property {'scroll' | 'fixed'} [attachment] - The attachment behavior of the background image. + */ export interface LovelaceViewBackgroundConfig { image?: string; opacity?: number; - size?: "auto" | "cover" | "contain"; + size?: 'auto' | 'cover' | 'contain'; alignment?: - | "top left" - | "top center" - | "top right" - | "center left" - | "center" - | "center right" - | "bottom left" - | "bottom center" - | "bottom right"; - repeat?: "repeat" | "no-repeat"; - attachment?: "scroll" | "fixed"; + | 'top left' + | 'top center' + | 'top right' + | 'center left' + | 'center' + | 'center right' + | 'bottom left' + | 'bottom center' + | 'bottom right'; + repeat?: 'repeat' | 'no-repeat'; + attachment?: 'scroll' | 'fixed'; } +/** + * Represents the header configuration for a Lovelace view in Home Assistant. + * + * @property {LovelaceCardConfig} [card] - The card to be displayed in the header. + * @property {'start' | 'center' | 'responsive'} [layout] - The layout of the header. + * @property {'bottom' | 'top'} [badges_position] - The position of badges in the header. + */ export interface LovelaceViewHeaderConfig { card?: LovelaceCardConfig; - layout?: "start" | "center" | "responsive"; - badges_position?: "bottom" | "top"; + layout?: 'start' | 'center' | 'responsive'; + badges_position?: 'bottom' | 'top'; } +/** + * Represents the base configuration for a Lovelace view in Home Assistant. + * + * @property {number} [index] - The index of the view. + * @property {string} [title] - The title of the view. + * @property {string} [path] - The path to the view. + * @property {string} [icon] - The icon for the view. + * @property {string} [theme] - The theme for the view. + * @property {boolean} [panel] - Whether the view is a panel view. + * @property {string | LovelaceViewBackgroundConfig} [background] - The background configuration for the view. + * @property {boolean | ShowViewConfig[]} [visible] - Visibility settings for the view. + * @property {boolean} [subview] - Whether the view is a subview. + * @property {string} [back_path] - The path to go back to the previous view. + * @property {number} [max_columns] - The maximum number of columns in the view. + * @property {boolean} [dense_section_placement] - Whether to place sections densely. + * @property {boolean} [top_margin] - Whether to add top margin to the view. + */ export interface LovelaceBaseViewConfig { index?: number; title?: string; @@ -42,33 +82,36 @@ export interface LovelaceBaseViewConfig { visible?: boolean | ShowViewConfig[]; subview?: boolean; back_path?: string; - // Only used for section view, it should move to a section view config type when the views will have a dedicated editor. max_columns?: number; dense_section_placement?: boolean; top_margin?: boolean; } /** - * View Config. + * Represents the configuration for a Lovelace view in Home Assistant. * - * @see https://www.home-assistant.io/dashboards/views/ + * @property {string} [type] - The type of the view. + * @property {(string | Partial)[]} [badges] - An array of badges for the view. + * @property {LovelaceCardConfig[]} [cards] - An array of cards in the view. + * @property {LovelaceSectionRawConfig[]} [sections] - An array of sections in the view. + * @property {LovelaceViewHeaderConfig} [header] - The header configuration for the view. */ export interface LovelaceViewConfig extends LovelaceBaseViewConfig { type?: string; - badges?: (string | Partial)[]; // Badge can be just an entity_id or without type + badges?: (string | Partial)[]; cards?: LovelaceCardConfig[]; sections?: LovelaceSectionRawConfig[]; header?: LovelaceViewHeaderConfig; } +/** + * Represents the configuration for a Lovelace strategy view in Home Assistant. + * + * @property {LovelaceStrategyConfig} strategy - The strategy configuration for the view. + */ export interface LovelaceStrategyViewConfig extends LovelaceBaseViewConfig { strategy: LovelaceStrategyConfig; } -export interface LovelaceStrategyViewConfig extends LovelaceBaseViewConfig { - strategy: LovelaceStrategyConfig; -} - -export type LovelaceViewRawConfig = - | LovelaceViewConfig - | LovelaceStrategyViewConfig; +/**Represents the raw configuration for a Lovelace view in Home Assistant. */ +export type LovelaceViewRawConfig = LovelaceViewConfig | LovelaceStrategyViewConfig; diff --git a/src/types/homeassistant/data/registry.ts b/src/types/homeassistant/data/registry.ts index 985d66a..7b58173 100644 --- a/src/types/homeassistant/data/registry.ts +++ b/src/types/homeassistant/data/registry.ts @@ -1,3 +1,9 @@ +/** + * Represents a registry entry in Home Assistant. + * + * @property {number} created_at - The timestamp when the entry was created. + * @property {number} modified_at - The timestamp when the entry was last modified. + */ export interface RegistryEntry { created_at: number; modified_at: number; diff --git a/src/types/homeassistant/data/translations.ts b/src/types/homeassistant/data/translations.ts index 45408b0..a417d8f 100644 --- a/src/types/homeassistant/data/translations.ts +++ b/src/types/homeassistant/data/translations.ts @@ -1,47 +1,62 @@ // noinspection JSUnusedGlobalSymbols -import {HomeAssistant} from "../types"; +import { HomeAssistant } from '../types'; +/** Represents the different formats for numbers in Home Assistant. */ export enum NumberFormat { - language = "language", - system = "system", - comma_decimal = "comma_decimal", - decimal_comma = "decimal_comma", - space_comma = "space_comma", - none = "none", + language = 'language', + system = 'system', + comma_decimal = 'comma_decimal', + decimal_comma = 'decimal_comma', + space_comma = 'space_comma', + none = 'none', } +/**Represents the different formats for time in Home Assistant. */ export enum TimeFormat { - language = "language", - system = "system", - am_pm = "12", - twenty_four = "24", + language = 'language', + system = 'system', + am_pm = '12', + twenty_four = '24', } +/** Represents the different time zones in Home Assistant. */ export enum TimeZone { - local = "local", - server = "server", + local = 'local', + server = 'server', } +/** Represents the different formats for dates in Home Assistant. */ export enum DateFormat { - language = "language", - system = "system", - DMY = "DMY", - MDY = "MDY", - YMD = "YMD", + language = 'language', + system = 'system', + DMY = 'DMY', + MDY = 'MDY', + YMD = 'YMD', } +/**Represents the first weekday in Home Assistant. */ export enum FirstWeekday { - language = "language", - monday = "monday", - tuesday = "tuesday", - wednesday = "wednesday", - thursday = "thursday", - friday = "friday", - saturday = "saturday", - sunday = "sunday", + language = 'language', + monday = 'monday', + tuesday = 'tuesday', + wednesday = 'wednesday', + thursday = 'thursday', + friday = 'friday', + saturday = 'saturday', + sunday = 'sunday', } +/** + * Represents the locale data for the frontend in Home Assistant. + * + * @property {string} language - The language of the frontend. + * @property {NumberFormat} number_format - The format for numbers. + * @property {TimeFormat} time_format - The format for time. + * @property {DateFormat} date_format - The format for dates. + * @property {FirstWeekday} first_weekday - The first weekday. + * @property {TimeZone} time_zone - The time zone. + */ export interface FrontendLocaleData { language: string; number_format: NumberFormat; @@ -51,33 +66,47 @@ export interface FrontendLocaleData { time_zone: TimeZone; } +/** Represents a category for translations in Home Assistant. */ export type TranslationCategory = - | "title" - | "state" - | "entity" - | "entity_component" - | "exceptions" - | "config" - | "config_subentries" - | "config_panel" - | "options" - | "device_automation" - | "mfa_setup" - | "system_health" - | "application_credentials" - | "issues" - | "selector" - | "services"; + | 'title' + | 'state' + | 'entity' + | 'entity_component' + | 'exceptions' + | 'config' + | 'config_subentries' + | 'config_panel' + | 'options' + | 'device_automation' + | 'mfa_setup' + | 'system_health' + | 'application_credentials' + | 'issues' + | 'selector' + | 'services'; +/** + * Retrieves the translations for Home Assistant. + * + * @async + * + * @param {HomeAssistant} hass - The Home Assistant instance. + * @param {string} language - The language for translations. + * @param {TranslationCategory} category - The category of translations. + * @param {string | string[]} [integration] - Optional integration name(s). + * @param {boolean} [config_flow] - Optional flag for config flow. + * + * @returns {Promise>} A promise resolving to an object containing translation key-value pairs. + */ export const getHassTranslations = async ( hass: HomeAssistant, language: string, category: TranslationCategory, integration?: string | string[], - config_flow?: boolean + config_flow?: boolean, ): Promise> => { const result = await hass.callWS<{ resources: Record }>({ - type: "frontend/get_translations", + type: 'frontend/get_translations', language, category, integration, diff --git a/src/types/homeassistant/data/ws-themes.ts b/src/types/homeassistant/data/ws-themes.ts index 79ff1d2..f2d353e 100644 --- a/src/types/homeassistant/data/ws-themes.ts +++ b/src/types/homeassistant/data/ws-themes.ts @@ -1,11 +1,26 @@ +/** + * Represents the variables for a theme in Home Assistant. + * + * @property {string} primary-color - The primary color of the theme. + * @property {string} text-primary-color - The primary text color of the theme. + * @property {string} accent-color - The accent color of the theme. + * @property {string} [key] - Additional theme variables as key-value pairs. + */ export interface ThemeVars { // Incomplete - "primary-color": string; - "text-primary-color": string; - "accent-color": string; + 'primary-color': string; + 'text-primary-color': string; + 'accent-color': string; + [key: string]: string; } +/** + * Represents a theme configuration in Home Assistant. + * + * @property {ThemeVars} modes.light - The light mode variables. + * @property {ThemeVars} modes.dark - The dark mode variables. + */ export type Theme = ThemeVars & { modes?: { light?: ThemeVars; @@ -13,14 +28,23 @@ export type Theme = ThemeVars & { }; }; +/** + * Represents the overall themes configuration in Home Assistant. + * + * @property {string} default_theme - The default theme name. + * @property {string | null} default_dark_theme - The default dark theme name or null. + * @property {Record} themes - A record of available themes. + * @property {boolean} darkMode - Currently effective dark mode. + * It Will never be undefined. + * If the user selected "auto" in the theme picker, this property will still contain + * either true or false based on what has been determined via system preferences and + * support for the selected theme. + * @property {string} theme - Currently globally active theme name + */ export interface Themes { default_theme: string; default_dark_theme: string | null; themes: Record; - // Currently effective dark mode. Will never be undefined. If user selected "auto" - // in theme picker, this property will still contain either true or false based on - // what has been determined via system preferences and support for the selected theme. darkMode: boolean; - // Currently globally active theme name theme: string; } diff --git a/src/types/homeassistant/panels/common/validate-condition.ts b/src/types/homeassistant/panels/common/validate-condition.ts index 138abc8..10449ff 100644 --- a/src/types/homeassistant/panels/common/validate-condition.ts +++ b/src/types/homeassistant/panels/common/validate-condition.ts @@ -1,3 +1,4 @@ +/** Represents a condition in Home Assistant. */ export type Condition = | NumericStateCondition | StateCondition @@ -6,40 +7,85 @@ export type Condition = | OrCondition | AndCondition; +/** + * Base interface for all conditions in Home Assistant. + * + * @property {string} condition - The type of condition. + */ interface BaseCondition { condition: string; } +/** + * Represents a numeric state condition in Home Assistant. + * + * @property {'numeric_state'} condition - The condition type. + * @property {string} [entity] - The entity to evaluate. + * @property {string | number} [below] - The threshold value below which the condition is true. + * @property {string | number} [above] - The threshold value above which the condition is true. + */ export interface NumericStateCondition extends BaseCondition { - condition: "numeric_state"; + condition: 'numeric_state'; entity?: string; below?: string | number; above?: string | number; } +/** + * Represents a state condition in Home Assistant. + * + * @property {'state'} condition - The condition type. + * @property {string} [entity] - The entity to evaluate. + * @property {string | string[]} [state] - The expected state of the entity. + * @property {string | string[]} [state_not] - The state that the entity should not be in. + */ export interface StateCondition extends BaseCondition { - condition: "state"; + condition: 'state'; entity?: string; state?: string | string[]; state_not?: string | string[]; } +/** + * Represents a screen condition in Home Assistant. + * + * @property {'screen'} condition - The condition type. + * @property {string} [media_query] - The media query for screen conditions. + */ export interface ScreenCondition extends BaseCondition { - condition: "screen"; + condition: 'screen'; media_query?: string; } +/** + * Represents a user condition in Home Assistant. + * + * @property {'user'} condition - The condition type. + * @property {string[]} [users] - The list of users for the condition. + */ export interface UserCondition extends BaseCondition { - condition: "user"; + condition: 'user'; users?: string[]; } +/** + * Represents an OR condition in Home Assistant. + * + * @property {'or'} condition - The condition type. + * @property {Condition[]} [conditions] - The list of conditions to evaluate. + */ export interface OrCondition extends BaseCondition { - condition: "or"; + condition: 'or'; conditions?: Condition[]; } +/** + * Represents an AND condition in Home Assistant. + * + * @property {'and'} condition - The condition type. + * @property {Condition[]} [conditions] - The list of conditions to evaluate. + */ export interface AndCondition extends BaseCondition { - condition: "and"; + condition: 'and'; conditions?: Condition[]; } diff --git a/src/types/homeassistant/panels/lovelace/cards/types.ts b/src/types/homeassistant/panels/lovelace/cards/types.ts index d7cee82..b0a3462 100644 --- a/src/types/homeassistant/panels/lovelace/cards/types.ts +++ b/src/types/homeassistant/panels/lovelace/cards/types.ts @@ -1,40 +1,41 @@ -import {ActionConfig, LovelaceCardConfig} from "../../../data/lovelace"; +import { ActionConfig } from '../../../data/lovelace/config/action'; +import { LovelaceCardConfig } from '../../../data/lovelace/config/card'; /** * Home Assistant Area Card Config. * + * @property {string} area - The area associated with the card. + * @property {string} [navigation_path] - Optional navigation path for the card. + * @property {boolean} [show_camera] - Whether to show the camera view. + * @property {"live" | "auto"} [camera_view] - The camera view mode. + * @property {string} [aspect_ratio] - The aspect ratio of the card. * @see https://www.home-assistant.io/dashboards/area/ */ export interface AreaCardConfig extends LovelaceCardConfig { area: string; navigation_path?: string; show_camera?: boolean; - camera_view?: "live" | "auto"; + camera_view?: 'live' | 'auto'; aspect_ratio?: string; } /** * Home Assistant Picture Entity Config. * - * @property {string} entity An entity_id used for the picture. - * @property {string} [name] Overwrite entity name. - * @property {string} [image] URL of an image. - * @property {string} [camera_image] Camera entity_id to use. - * (not required if the entity is already a camera-entity). - * @property {string} [camera_view=auto] “live” will show the live view if stream is enabled. - * @property {Record} [state_image] Map entity states to images (state: image URL). - * @property {string[]} [state_filter] State-based CSS filters. - * @property {string} [aspect_ratio] Forces the height of the image to be a ratio of the width. - * Valid formats: Height percentage value (23%) or ratio expressed with colon or “x” - * separator (16:9 or 16x9). - * For a ratio, the second element can be omitted and will default to “1” - * (1.78 equals 1.78:1). - * @property {ActionConfig} [tap_action] Action taken on card tap. - * @property {ActionConfig} [hold_action] Action taken on card tap and hold. - * @property {ActionConfig} [double_tap_action] Action taken on card double tap. - * @property {boolean} [show_name=true] Shows name in footer. - * @property {string} [theme=true] Override the used theme for this card with any loaded theme. - * + * @property {string} entity - An entity_id used for the picture. + * @property {string} [name] - Overwrite entity name. + * @property {string} [image] - URL of an image. + * @property {string} [camera_image] - Camera entity_id to use. + * @property {"live" | "auto"} [camera_view] - The camera view mode. + * @property {Record} [state_image] - Map entity states to images. + * @property {string[]} [state_filter] - State-based CSS filters. + * @property {string} [aspect_ratio] - Forces the height of the image to be a ratio of the width. + * @property {ActionConfig} [tap_action] - Action taken on card tap. + * @property {ActionConfig} [hold_action] - Action taken on card tap and hold. + * @property {ActionConfig} [double_tap_action] - Action taken on card double tap. + * @property {boolean} [show_name=true] - Shows name in footer. + * @property {string} [theme=true] - Override the used theme for this card. + * @property {boolean} [show_state] - Shows state in footer. * @see https://www.home-assistant.io/dashboards/picture-entity/ */ export interface PictureEntityCardConfig extends LovelaceCardConfig { @@ -42,7 +43,7 @@ export interface PictureEntityCardConfig extends LovelaceCardConfig { name?: string; image?: string; camera_image?: string; - camera_view?: "live" | "auto"; + camera_view?: 'live' | 'auto'; state_image?: Record; state_filter?: string[]; aspect_ratio?: string; @@ -57,13 +58,13 @@ export interface PictureEntityCardConfig extends LovelaceCardConfig { /** * Home Assistant Stack Card Config. * - * @property {string} type The stack type. - * @property {Object[]} cards The content of the stack. - * + * @property {string} type - The stack type. + * @property {Object[]} cards - The content of the stack. * @see https://www.home-assistant.io/dashboards/horizontal-stack/ * @see https://www.home-assistant.io/dashboards/vertical-stack/ */ export interface StackCardConfig extends LovelaceCardConfig { + type: string; cards: LovelaceCardConfig[]; title?: string; } diff --git a/src/types/homeassistant/panels/lovelace/types.ts b/src/types/homeassistant/panels/lovelace/types.ts index 6496f32..1bfba97 100644 --- a/src/types/homeassistant/panels/lovelace/types.ts +++ b/src/types/homeassistant/panels/lovelace/types.ts @@ -1,15 +1,35 @@ +/** + * Represents the layout options for Lovelace in Home Assistant. + * + * @property {number | "full"} [grid_columns] - The number of grid columns or "full". + * @property {number | "auto"} [grid_rows] - The number of grid rows or "auto". + * @property {number} [grid_max_columns] - The maximum number of grid columns. + * @property {number} [grid_min_columns] - The minimum number of grid columns. + * @property {number} [grid_min_rows] - The minimum number of grid rows. + * @property {number} [grid_max_rows] - The maximum number of grid rows. + */ export interface LovelaceLayoutOptions { - grid_columns?: number | "full"; - grid_rows?: number | "auto"; + grid_columns?: number | 'full'; + grid_rows?: number | 'auto'; grid_max_columns?: number; grid_min_columns?: number; grid_min_rows?: number; grid_max_rows?: number; } +/** + * Represents the grid options for Lovelace in Home Assistant. + * + * @property {number | "full"} [columns] - The number of columns or "full". + * @property {number | "auto"} [rows] - The number of rows or "auto". + * @property {number} [max_columns] - The maximum number of columns. + * @property {number} [min_columns] - The minimum number of columns. + * @property {number} [min_rows] - The minimum number of rows. + * @property {number} [max_rows] - The maximum number of rows. + */ export interface LovelaceGridOptions { - columns?: number | "full"; - rows?: number | "auto"; + columns?: number | 'full'; + rows?: number | 'auto'; max_columns?: number; min_columns?: number; min_rows?: number; diff --git a/src/types/homeassistant/types.ts b/src/types/homeassistant/types.ts index e61eb32..ffb05d4 100644 --- a/src/types/homeassistant/types.ts +++ b/src/types/homeassistant/types.ts @@ -7,27 +7,50 @@ import { HassServices, HassServiceTarget, MessageBase, -} from "home-assistant-js-websocket"; -import {AreaRegistryEntry} from "./data/area_registry"; -import {DeviceRegistryEntry} from "./data/device_registry"; -import {EntityRegistryDisplayEntry} from "./data/entity_registry"; -import {FloorRegistryEntry} from "./data/floor_registry"; -import {Themes} from "./data/ws-themes"; -import {FrontendLocaleData, getHassTranslations} from "./data/translations"; -import {LocalizeFunc} from "./common/translations/localize"; -import {CoreFrontendUserData} from "./data/frontend"; +} from 'home-assistant-js-websocket'; +import { LocalizeFunc } from './common/translations/localize'; +import { AreaRegistryEntry } from './data/area_registry'; +import { DeviceRegistryEntry } from './data/device_registry'; +import { EntityRegistryDisplayEntry } from './data/entity_registry'; +import { FloorRegistryEntry } from './data/floor_registry'; +import { CoreFrontendUserData } from './data/frontend'; +import { FrontendLocaleData, getHassTranslations } from './data/translations'; +import { Themes } from './data/ws-themes'; +/** + * Represents the credentials for a user in Home Assistant. + * + * @property {string} auth_provider_type - The type of authentication provider. + * @property {string} auth_provider_id - The ID of the authentication provider. + */ export interface Credential { auth_provider_type: string; auth_provider_id: string; } +/** + * Represents a multifactor authentication module in Home Assistant. + * + * @property {string} id - The unique identifier for the MFA module. + * @property {string} name - The name of the MFA module. + * @property {boolean} enabled - Whether the MFA module is enabled. + */ export interface MFAModule { id: string; name: string; enabled: boolean; } +/** + * Represents the current user in Home Assistant. + * + * @property {string} id - The unique identifier for the user. + * @property {boolean} is_owner - Indicates if the user is an owner. + * @property {boolean} is_admin - Indicates if the user is an admin. + * @property {string} name - The name of the user. + * @property {Credential[]} credentials - The credentials associated with the user. + * @property {MFAModule[]} mfa_modules - The MFA modules associated with the user. + */ export interface CurrentUser { id: string; is_owner: boolean; @@ -37,6 +60,18 @@ export interface CurrentUser { mfa_modules: MFAModule[]; } +/** + * Represents information about a panel in Home Assistant. + * + * @template T The type of the configuration object for the panel. + * + * @property {string} component_name - The name of the component for the panel. + * @property {T} config - The configuration for the panel. + * @property {string | null} icon - The icon for the panel. + * @property {string | null} title - The title of the panel. + * @property {string} url_path - The URL path for the panel. + * @property {string} [config_panel_domain] - The domain for the configuration panel. + */ export interface PanelInfo | null> { component_name: string; config: T; @@ -46,39 +81,108 @@ export interface PanelInfo | null> { config_panel_domain?: string; } -export type Panels = Record; +/** + * Represents the panels in Home Assistant. + * + * @property {Record} panels - The panel configurations. + */ +export interface Panels { + panels: Record; +} +/** + * Represents a translation in Home Assistant. + * + * @property {string} nativeName - The native name of the language. + * @property {boolean} isRTL - Indicates if the language is written right-to-left. + * @property {string} hash - The hash for the translation. + */ export interface Translation { nativeName: string; isRTL: boolean; hash: string; } +/** + * Represents metadata for translations in Home Assistant. + * + * @property {string[]} fragments - The fragments of the translation. + * @property {Record} translations - The translations mapped by language. + */ export interface TranslationMetadata { fragments: string[]; translations: Record; } -export type TranslationDict = {[key: string]: string}; +/** + * Represents a dictionary of translations in Home Assistant. + * + * @property {Record} translations - The translations mapped by a key. + */ +export interface TranslationDict { + translations: Record; +} -export type Resources = Record>; +/** + * Represents resources in Home Assistant. + * + * @property {Record>} resources - The resources mapped by a key. + */ +export interface Resources { + resources: Record>; +} -// Currently selected theme and its settings. These are the values stored in local storage. -// Note: These values are not meant to be used at runtime to check whether dark mode is active -// or which theme name to use, as this interface represents the config data for the theme picker. -// The actually active dark mode and theme name can be read from hass.themes. +/** + * Represents the settings for themes in Home Assistant. + * + * @property {string} theme - The name of the selected theme. + * @property {boolean} [dark] - Indicates if the theme is dark. + * @property {string} [primaryColor] - The primary color of the theme. + * @property {string} [accentColor] - The accent color of the theme. + */ export interface ThemeSettings { theme: string; - // Radio box selection for theme picker. Do not use in Lovelace rendering as - // it can be undefined == auto. - // Property hass.themes.darkMode carries effective current mode. dark?: boolean; primaryColor?: string; accentColor?: string; } +/** + * Represents the main Home Assistant object. + * + * @interface HomeAssistant + * @property {Auth} auth - The authentication object. + * @property {Connection} connection - The connection object. + * @property {boolean} connected - Indicates if the connection is active. + * @property {HassEntities} states - The current states of entities. + * @property {Record} entities - The entities in the registry. + * @property {Record} devices - The devices in the registry. + * @property {Record} areas - The areas in the registry. + * @property {Record} floors - The floors in the registry. + * @property {HassServices} services - The services available in Home Assistant. + * @property {HassConfig} config - The configuration for Home Assistant. + * @property {Themes} themes - The available themes. + * @property {ThemeSettings | null} selectedTheme - The currently selected theme. + * @property {Panels} panels - The panel configurations. + * @property {string} panelUrl - The URL for the panel. + * @property {string} language - The current language. + * @property {string | null} selectedLanguage - The selected language. + * @property {FrontendLocaleData} locale - The locale data. + * @property {Resources} resources - The resources available. + * @property {LocalizeFunc} localize - The localization function. + * @property {TranslationMetadata} translationMetadata - The translation metadata. + * @property {boolean} suspendWhenHidden - Indicates if the frontend should suspend when hidden. + * @property {boolean} enableShortcuts - Indicates if shortcuts are enabled. + * @property {boolean} vibrate - Indicates if vibration feedback is enabled. + * @property {boolean} debugConnection - Indicates if debug mode is enabled for the connection. + * @property {'docked' | 'always_hidden' | 'auto'} dockedSidebar - The sidebar visibility setting. + * @property {string} defaultPanel - The default panel to show. + * @property {string | null} moreInfoEntityId - The entity ID for more info. + * @property {CurrentUser} [user] - The current user object. + * @property {CoreFrontendUserData | null} [userData] - The frontend user data. + */ export interface HomeAssistant { - auth: Auth & { external?: {[key: string]: any;} }; + auth: Auth & { external?: { [key: string]: any } }; connection: Connection; connected: boolean; states: HassEntities; @@ -92,14 +196,7 @@ export interface HomeAssistant { selectedTheme: ThemeSettings | null; panels: Panels; panelUrl: string; - // i18n - // current effective language in that order: - // - backend saved user selected language - // - language in local app storage - // - browser language - // - english (en) language: string; - // local stored language, keep that name for backward compatibility selectedLanguage: string | null; locale: FrontendLocaleData; resources: Resources; @@ -109,57 +206,166 @@ export interface HomeAssistant { enableShortcuts: boolean; vibrate: boolean; debugConnection: boolean; - dockedSidebar: "docked" | "always_hidden" | "auto"; + dockedSidebar: 'docked' | 'always_hidden' | 'auto'; defaultPanel: string; moreInfoEntityId: string | null; user?: CurrentUser; userData?: CoreFrontendUserData | null; + + /** + * Returns the URL for the Home Assistant instance. + * + * @param {any} path - Optional path to append to the base URL. + */ hassUrl(path?: any): string; + + /** + * Calls a service in Home Assistant. + * + * @param {ServiceCallRequest['domain']} domain - The domain of the service. + * @param {ServiceCallRequest['service']} service - The name of the service to call. + * @param {ServiceCallRequest['serviceData']} [serviceData] - Optional data to send with the service call. + * @param {ServiceCallRequest['target']} [target] - Optional target for the service call. + * @param {boolean} [notifyOnError] - Whether to notify on error. + * @param {boolean} [returnResponse] - Whether to return the response. + */ callService( - domain: ServiceCallRequest["domain"], - service: ServiceCallRequest["service"], - serviceData?: ServiceCallRequest["serviceData"], - target?: ServiceCallRequest["target"], + domain: ServiceCallRequest['domain'], + service: ServiceCallRequest['service'], + serviceData?: ServiceCallRequest['serviceData'], + target?: ServiceCallRequest['target'], notifyOnError?: boolean, - returnResponse?: boolean + returnResponse?: boolean, ): Promise; + + /** + * Calls the Home Assistant API. + * + * @template T The expected response type. + * + * @param {'GET' | 'POST' | 'PUT' | 'DELETE'} method - The HTTP method to use. + * @param {string} path - The API endpoint path. + * @param {Record} [parameters] - Optional parameters to send with the request. + * @param {Record} [headers] - Optional headers to include in the request. + */ callApi( - method: "GET" | "POST" | "PUT" | "DELETE", - path: string, - parameters?: Record, - headers?: Record - ): Promise; - callApiRaw( // introduced in 2024.11 - method: "GET" | "POST" | "PUT" | "DELETE", + method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, parameters?: Record, headers?: Record, - signal?: AbortSignal + ): Promise; + + /** + * Calls the Home Assistant API with raw response. + * + * @param {'GET' | 'POST' | 'PUT' | 'DELETE'} method - The HTTP method to use. + * @param {string} path - The API endpoint path. + * @param {Record} [parameters] - Optional parameters to send with the request. + * @param {Record} [headers] - Optional headers to include in the request. + * @param {AbortSignal} [signal] - Optional signal to abort the request. + */ + callApiRaw( + method: 'GET' | 'POST' | 'PUT' | 'DELETE', + path: string, + parameters?: Record, + headers?: Record, + signal?: AbortSignal, ): Promise; + + /** + * Fetches a resource with authentication. + * + * @param {string} path - The resource path to fetch. + * @param {Record} [init] - Optional fetch options. + */ fetchWithAuth(path: string, init?: Record): Promise; + + /** + * Sends a WebSocket message. + * + * @param {MessageBase} msg - The message to send. + */ sendWS(msg: MessageBase): void; + + /** + * Calls a WebSocket service. + * + * @template T The expected response type. + * + * @param {MessageBase} msg - The message to send. + */ callWS(msg: MessageBase): Promise; + + /** + * Load backend translation. + * + * @param {Parameters[2]} category - The category of translations. + * @param {Parameters[3]} [integrations] - Optional integrations to include. + * @param {Parameters[4]} [configFlow] - Optional config flow. + * + * @returns {Promise} The localization function. + */ loadBackendTranslation( category: Parameters[2], integrations?: Parameters[3], - configFlow?: Parameters[4] + configFlow?: Parameters[4], ): Promise; + + /** + * Load fragment translation. + * + * @param {string} fragment - The fragment to load. + * @returns {Promise} The localization function or undefined. + */ loadFragmentTranslation(fragment: string): Promise; + + /** + * Formats the state of an entity. + * + * @param {HassEntity} stateObj - The state object of the entity. + * @param {string} [state] - Optional state to format. + */ formatEntityState(stateObj: HassEntity, state?: string): string; - formatEntityAttributeValue( - stateObj: HassEntity, - attribute: string, - value?: any - ): string; + + /** + * Formats the value of an entity attribute. + * + * @param {HassEntity} stateObj - The state object of the entity. + * @param {string} attribute - The attribute to format. + * @param {any} [value] - Optional value to format. + */ + formatEntityAttributeValue(stateObj: HassEntity, attribute: string, value?: any): string; + + /** + * Formats the name of an entity attribute. + * + * @param {HassEntity} stateObj - The state object of the entity. + * @param {string} attribute - The attribute to format. + */ formatEntityAttributeName(stateObj: HassEntity, attribute: string): string; } +/** + * Represents the context of a service call. + * + * @property {string} id - The unique identifier for the context. + * @property {string} [parent_id] - The optional parent ID of the context. + * @property {string | null} [user_id] - The optional user ID associated with the context. + */ export interface Context { id: string; parent_id?: string; user_id?: string | null; } +/** + * Represents a service call request in Home Assistant. + * + * @property {string} domain - The domain of the service to call. + * @property {string} service - The name of the service to call. + * @property {Record} [serviceData] - Optional data to send with the service call. + * @property {HassServiceTarget} [target] - Optional target for the service call. + */ export interface ServiceCallRequest { domain: string; service: string; @@ -167,6 +373,12 @@ export interface ServiceCallRequest { target?: HassServiceTarget; } +/** + * Represents the response from a service call in Home Assistant. + * + * @property {Context} context - The context of the service call. + * @property {any} [response] - The optional response data from the service call. + */ export interface ServiceCallResponse { context: Context; response?: any; diff --git a/src/types/lovelace-mushroom/cards/chips-card.ts b/src/types/lovelace-mushroom/cards/chips-card.ts index 55bf341..5e42c67 100644 --- a/src/types/lovelace-mushroom/cards/chips-card.ts +++ b/src/types/lovelace-mushroom/cards/chips-card.ts @@ -1,11 +1,11 @@ -import {LovelaceCardConfig} from "../../homeassistant/data/lovelace"; -import {LovelaceChipConfig} from "../utils/lovelace/chip/types"; +import { LovelaceCardConfig } from '../../homeassistant/data/lovelace/config/card'; +import { LovelaceChipConfig } from '../utils/lovelace/chip/types'; /** * Chips Card Configuration * - * @param {LovelaceChipConfig[]} chips Chips Array - * @param {string} [alignment=start] Chips alignment (start,end, center, justify), when empty default behavior is start. + * @property {LovelaceChipConfig[]} chips - Array of chips to display. + * @property {string} [alignment] - Chips alignment (start, end, center, justify). Defaults to 'start'. * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/chips.md */ diff --git a/src/types/lovelace-mushroom/cards/fan-card-config.ts b/src/types/lovelace-mushroom/cards/fan-card-config.ts index cf792a7..761dbce 100644 --- a/src/types/lovelace-mushroom/cards/fan-card-config.ts +++ b/src/types/lovelace-mushroom/cards/fan-card-config.ts @@ -1,16 +1,15 @@ -import {ActionsSharedConfig} from "../shared/config/actions-config"; -import {LovelaceCardConfig} from "../../homeassistant/data/lovelace"; -import {EntitySharedConfig} from "../shared/config/entity-config"; -import {AppearanceSharedConfig} from "../shared/config/appearance-config"; +import { LovelaceCardConfig } from '../../homeassistant/data/lovelace/config/card'; +import { ActionsSharedConfig } from '../shared/config/actions-config'; +import { AppearanceSharedConfig } from '../shared/config/appearance-config'; +import { EntitySharedConfig } from '../shared/config/entity-config'; /** - * Fan Card Config. + * Fan Card Configuration * - * @property {boolean} [icon_animation=false] Animate the icon when fan is on. - * @property {boolean} [show_percentage_control=false] Show a slider to control speed. - * @property {boolean} [show_oscillate_control=false] Show a button to control oscillation. - * @property {boolean} [show_direction_control=false] Show a button to control the direction. - * @property {boolean} [icon_animation=false] Animate the icon when fan is on. + * @property {boolean} [icon_animation] - Animate the icon when the fan is on. Defaults to false. + * @property {boolean} [show_percentage_control] - Show a slider to control speed. Defaults to false. + * @property {boolean} [show_oscillate_control] - Show a button to control oscillation. Defaults to false. + * @property {boolean} [show_direction_control] - Show a button to control the direction. Defaults to false. * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/fan.md */ @@ -18,9 +17,8 @@ export type FanCardConfig = LovelaceCardConfig & EntitySharedConfig & AppearanceSharedConfig & ActionsSharedConfig & { - icon_animation?: boolean; - show_percentage_control?: boolean; - show_oscillate_control?: boolean; - show_direction_control?: boolean; - collapsible_controls?: boolean; -}; + icon_animation?: boolean; + show_percentage_control?: boolean; + show_oscillate_control?: boolean; + show_direction_control?: boolean; + }; diff --git a/src/types/lovelace-mushroom/utils/lovelace/chip/types.ts b/src/types/lovelace-mushroom/utils/lovelace/chip/types.ts index 4dc3a0f..6d807ee 100644 --- a/src/types/lovelace-mushroom/utils/lovelace/chip/types.ts +++ b/src/types/lovelace-mushroom/utils/lovelace/chip/types.ts @@ -189,7 +189,21 @@ export type SpacerChipConfig = { type: 'spacer'; }; -/** Lovelace Chip Config */ +/** + * Lovelace Chip Config + * + * A Lovelace chip configuration can be one of the following types: + * - Action chip configuration + * - Alarm control panel chip configuration + * - Back chip configuration + * - Entity chip configuration + * - Menu chip configuration + * - Weather chip configuration + * - Template chip configuration + * - Conditional chip configuration + * - Light chip configuration + * - Spacer chip configuration + */ export type LovelaceChipConfig = | ActionChipConfig | AlarmControlPanelChipConfig diff --git a/src/types/strategy/cards.ts b/src/types/strategy/cards.ts deleted file mode 100644 index 20eacfc..0000000 --- a/src/types/strategy/cards.ts +++ /dev/null @@ -1,72 +0,0 @@ -import {LovelaceCardConfig} from "../homeassistant/data/lovelace"; -import {TitleCardConfig} from "../lovelace-mushroom/cards/title-card-config"; -import {EntitySharedConfig} from "../lovelace-mushroom/shared/config/entity-config"; -import {AppearanceSharedConfig} from "../lovelace-mushroom/shared/config/appearance-config"; -import {ActionsSharedConfig} from "../lovelace-mushroom/shared/config/actions-config"; -import {TemplateCardConfig} from "../lovelace-mushroom/cards/template-card-config"; -import {EntityCardConfig} from "../lovelace-mushroom/cards/entity-card-config"; -import {AreaCardConfig, PictureEntityCardConfig} from "../homeassistant/panels/lovelace/cards/types"; -import {ClimateCardConfig} from "../lovelace-mushroom/cards/climate-card-config"; -import {CoverCardConfig} from "../lovelace-mushroom/cards/cover-card-config"; -import {FanCardConfig} from "../lovelace-mushroom/cards/fan-card-config"; -import {LightCardConfig} from "../lovelace-mushroom/cards/light-card-config"; -import {LockCardConfig} from "../lovelace-mushroom/cards/lock-card-config"; -import {MediaPlayerCardConfig} from "../lovelace-mushroom/cards/media-player-card-config"; -import {NumberCardConfig} from "../lovelace-mushroom/cards/number-card-config"; -import {PersonCardConfig} from "../lovelace-mushroom/cards/person-card-config"; -import {VacuumCardConfig} from "../lovelace-mushroom/cards/vacuum-card-config"; -import {SelectCardConfig} from '../lovelace-mushroom/cards/select-card-config'; - -export namespace cards { - /** - * Abstract Card Config. - */ - export type AbstractCardConfig = LovelaceCardConfig & - EntitySharedConfig & - AppearanceSharedConfig & - ActionsSharedConfig; - - /** - * Controller Card Config. - * - * @property {boolean} [showControls=true] False to hide controls. - * @property {string} [iconOn] Icon to show for switching entities from off state. - * @property {string} [iconOff] Icon to show for switching entities to off state. - * @property {string} [onService=none] Service to call for switching entities from off state. - * @property {string} [offService=none] Service to call for switching entities to off state. - */ - export interface ControllerCardConfig extends TitleCardConfig { - type: "mushroom-title-card", - showControls?: boolean; - iconOn?: string; - iconOff?: string; - onService?: string; - offService?: string; - } - - export type AreaCardOptions = Omit; - export type ClimateCardOptions = Omit; - export type ControllerCardOptions = Omit; - export type CoverCardOptions = Omit; - export type EntityCardOptions = Omit; - export type FanCardOptions = Omit; - export type LightCardOptions = Omit; - export type LockCardOptions = Omit; - export type MediaPlayerCardOptions = Omit; - export type NumberCardOptions = Omit; - export type PersonCardOptions = Omit; - export type PictureEntityCardOptions = Omit; - export type TemplateCardOptions = Omit; - export type VacuumCardOptions = Omit; - export type SelectCardOptions = Omit; - export type InputSelectCardOptions = Omit; -} - - - - - - - - - diff --git a/src/types/strategy/generic.ts b/src/types/strategy/generic.ts deleted file mode 100644 index 7ced83d..0000000 --- a/src/types/strategy/generic.ts +++ /dev/null @@ -1,367 +0,0 @@ -import {CallServiceActionConfig, LovelaceCardConfig,} from "../homeassistant/data/lovelace"; -import {HomeAssistant} from "../homeassistant/types"; -import {AreaRegistryEntry} from "../homeassistant/data/area_registry"; -import {cards} from "./cards"; -import {EntityRegistryEntry} from "../homeassistant/data/entity_registry"; -import {LovelaceChipConfig} from "../lovelace-mushroom/utils/lovelace/chip/types"; -import {HassServiceTarget} from "home-assistant-js-websocket"; -import {LovelaceViewConfig, LovelaceViewRawConfig} from "../homeassistant/data/lovelace/config/view"; -import {LovelaceConfig} from "../homeassistant/data/lovelace/config/types"; - -/** - * List of supported domains. - * - * This constant array defines the domains that are supported by the strategy. - * Each domain represents a specific type of entity within the Home Assistant ecosystem. - * - * _ refers to all domains. - * default refers to the miscellanea domain. - * - * @readonly - * @constant - */ -const SUPPORTED_DOMAINS = [ - "_", - "binary_sensor", - "camera", - "climate", - "cover", - "default", - "fan", - "input_select", - "light", - "lock", - "media_player", - "number", - "scene", - "select", - "sensor", - "switch", - "vacuum", -] as const; - -/** - * List of supported views. - * - * This constant array defines the views that are supported by the strategy. - * - * @readonly - * @constant - */ -const SUPPORTED_VIEWS = [ - "camera", - "climate", - "cover", - "fan", - "home", - "light", - "scene", - "switch", - "vacuum", -] as const; - -const SUPPORTED_CHIPS = [ - "light", - "fan", - "cover", - "switch", - "climate", - "weather", -] as const; - -/** - * List of home view sections. - * - * This constant array defines the sections that are present in the home view. - * - * @readonly - * @constant - */ -const HOME_VIEW_SECTIONS = [ - "areas", - "areasTitle", - "chips", - "greeting", - "persons", -] as const; - -export namespace generic { - export type SupportedDomains = typeof SUPPORTED_DOMAINS[number]; - export type SupportedViews = typeof SUPPORTED_VIEWS[number]; - export type SupportedChips = typeof SUPPORTED_CHIPS[number]; - export type HomeViewSections = typeof HOME_VIEW_SECTIONS[number]; - - /** - * An entry of a Home Assistant Register. - */ - export type RegistryEntry = - | AreaRegistryEntry - | DataTransfer - | EntityRegistryEntry - - /** - * View Configuration of the strategy. - * - * @interface StrategyViewConfig - * @extends LovelaceViewConfig - * - * @property {boolean} [hidden] If True, the view is hidden from the dashboard. - * @property {number} [order] Ordering position of the views at the top of the dashboard. - */ - export interface StrategyViewConfig extends LovelaceViewConfig { - hidden: boolean; - order: number; - } - - /** - * All Domains Configuration. - * - * @interface AllDomainsConfig - * - * @property {boolean} [hide_config_entities] If True, all configuration entities are hidden from the dashboard. - * @property {boolean} [hide_diagnostic_entities] If True, all diagnostic entities are hidden from the dashboard. - */ - export interface AllDomainsConfig { - hide_config_entities: boolean; - hide_diagnostic_entities: boolean; - } - - /** - * Single Domain Configuration. - * - * @interface SingleDomainConfig - * @extends Partial - * - * @property {boolean} [hidden] If True, all entities of the domain are hidden from the dashboard. - * @property {number} [order] Ordering position of the domains in a views. - */ - export interface SingleDomainConfig extends Partial { - hidden: boolean; - order?: number; - } - - /** - * Dashboard Info Object. - * - * Home Assistant passes this object to the Dashboard Generator method. - * - * @interface DashboardInfo - * - * @property {LovelaceConfig} config Dashboard configuration. - * @property {HomeAssistant} hass The Home Assistant object. - * - * @see https://developers.home-assistant.io/docs/frontend/custom-ui/custom-strategy/#dashboard-strategies - */ - export interface DashboardInfo { - config: LovelaceViewRawConfig & { - strategy: { - options?: StrategyConfig & { area: StrategyArea } - } - }; - hass: HomeAssistant; - } - - /** - * View Info Object. - * - * Home Assistant passes this object to the View Generator method. - * - * @interface ViewInfo - * - * @property {LovelaceConfig} config Dashboard configuration. - * @property {HomeAssistant} hass The Home Assistant object. - * @property {LovelaceViewConfig} view View configuration. - * - * @see https://developers.home-assistant.io/docs/frontend/custom-ui/custom-strategy/#view-strategies - */ - export interface ViewInfo { - config: LovelaceConfig; - hass: HomeAssistant; - view: LovelaceViewRawConfig & { - strategy: { - options?: StrategyConfig & { area: StrategyArea } - } - }; - } - - /** - * Strategy Configuration. - * - * @interface StrategyConfig - * - * @property {Object.} areas List of areas. - * @property {Object.} card_options Card options for entities. - * @property {Partial} chips The configuration of chips in the Home view. - * @property {boolean} debug If True, the strategy outputs more verbose debug information in the console. - * @property {Object.} domains List of domains. - * @property {LovelaceCardConfig[]} extra_cards List of cards to show below room cards. - * @property {StrategyViewConfig[]} extra_views List of custom-defined views to add to the dashboard. - * @property {{ hidden: HomeViewSections[] | [] }} home_view List of views to add to the dashboard. - * @property {Object.} views The configurations of views. - * @property {LovelaceCardConfig[]} quick_access_cards List of custom-defined cards to show between the welcome card - * and rooms cards. - */ - export interface StrategyConfig { - areas: { [S: string]: StrategyArea }; - card_options: { [S: string]: CustomCardConfig }; - chips: Partial; - debug: boolean; - domains: { [K in SupportedDomains]: K extends "_" ? AllDomainsConfig : SingleDomainConfig; }; - extra_cards: LovelaceCardConfig[]; - extra_views: StrategyViewConfig[]; - home_view: { - hidden: HomeViewSections[] | []; - } - views: Record; - quick_access_cards: LovelaceCardConfig[]; - } - - /** - * Represents the default configuration for a strategy. - * - * @interface StrategyDefaults - */ - export interface StrategyDefaults extends StrategyConfig { - areas: { "undisclosed": StrategyArea } & { [S: string]: StrategyArea }; - } - - /** - * Strategy Area. - * - * @interface StrategyArea - * - * @property {boolean} [hidden] True if the entity should be hidden from the dashboard. - * @property {object[]} [extra_cards] An array of card configurations. - * The configured cards are added to the dashboard. - * @property {number} [order] Ordering position of the area in the list of available areas. - * @property {string} [type] The type of area card. - */ - export interface StrategyArea extends AreaRegistryEntry { - extra_cards?: LovelaceCardConfig[]; - hidden?: boolean; - order?: number; - type?: string; - } - - /** - * A list of chips to show in the Home view. - * - * @interface ChipConfiguration - * - * @property {boolean} climate_count Chip to display the number of climates which are not off. - * @property {boolean} cover_count Chip to display the number of unclosed covers. - * @property {boolean} fan_count Chip to display the number of fans on. - * @property {boolean} light_count Chip to display the number of lights on. - * @property {boolean} switch_count Chip to display the number of switches on. - * @property {string} weather_entity Entity ID for the weather chip to use, accepts `weather.` only. - * @property {object[]} extra_chips List of extra chips. - */ - export interface ChipConfiguration { - climate_count: boolean; - cover_count: boolean; - extra_chips: LovelaceChipConfig[]; - fan_count: boolean; - light_count: boolean; - switch_count: boolean; - weather_entity: string; - } - - /** - * Custom Card Configuration for an entity. - * - * @interface CustomCardConfig - * @extends LovelaceCardConfig - * - * @property {boolean} hidden If True, the card is hidden from the dashboard. - */ - export interface CustomCardConfig extends LovelaceCardConfig { - hidden?: boolean; - } - - /** - * Area Filter Context. - * - * @interface AreaFilterContext - * - * @property {AreaRegistryEntry} area Area Entry. - * @property {string[]} areaDeviceIds The id of devices which are linked to the area. - * @property {string} [domain] Domain of an entity. - * Example: `light`. - */ - export interface AreaFilterContext { - area: AreaRegistryEntry; - areaDeviceIds: string[]; - domain?: string; - } - - /** - * Checks if the given object is an instance of CallServiceActionConfig. - * - * @param {any} obj - The object to be checked. - * @returns {boolean} - Returns true if the object is an instance of CallServiceActionConfig, otherwise false. - */ - export function isCallServiceActionConfig(obj: any): obj is CallServiceActionConfig { - return obj && obj.action === "call-service" && ["action", "service"].every(key => key in obj); - } - - /** - * Checks if the given object is an instance of HassServiceTarget. - * - * @param {any} obj - The object to check. - * @returns {boolean} - True if the object is an instance of HassServiceTarget, false otherwise. - */ - export function isCallServiceActionTarget(obj: any): obj is HassServiceTarget { - return obj && ["entity_id", "device_id", "area_id"].some(key => key in obj); - } - - interface SortableBase { - order: number; - } - - type SortableWithTitle = SortableBase & { title: string; name?: never }; - type SortableWithName = SortableBase & { name: string; title?: never }; - - - /** - * The union type of SortableWithTitle and SortableWithName. - * - * @remarks - * This type is used to sort objects by title or by name. - * The `order` property is used to sort the objects. - * The `title` and `name` properties are used to display the object in the UI. - */ - export type Sortable = SortableWithTitle | SortableWithName; - - - /** - * Checks if the given object is of a sortable type. - * - * Sortable types are objects that have a `title` or a `name` property and an `order` property. - * - * @param {any} obj - The object to check. - * @returns {boolean} - True if the object is an instance of Sortable, false otherwise. - */ - export function isSortable(obj: any): obj is Sortable { - return obj && 'order' in obj && ('title' in obj || 'name' in obj); - } - - /** - * Checks if the given view id is a supported view. - * - * @param {string} id - The view id to check. - * @returns {boolean} - Returns true if the view id is a supported view, otherwise false. - */ - export function isSupportedView(id: string): id is SupportedViews { - return SUPPORTED_VIEWS.includes(id as SupportedViews); - } - - /** - * Checks if the given domain id is a supported domain. - * - * @param {string} id - The domain id to check. - * @returns {boolean} - Returns true if the domain id is a supported domain, otherwise false. - */ - export function isSupportedDomain(id: string): id is SupportedDomains { - return SUPPORTED_DOMAINS.includes(id as SupportedDomains); - } -} diff --git a/src/types/strategy/strategy-cards.ts b/src/types/strategy/strategy-cards.ts index 2650738..46c5a42 100644 --- a/src/types/strategy/strategy-cards.ts +++ b/src/types/strategy/strategy-cards.ts @@ -19,7 +19,7 @@ export type AbstractCardConfig = LovelaceCardConfig & EntitySharedConfig & Appea * @property {string} [offService=none] - Service to call for switching entities to the off state. */ export interface StrategyHeaderCardConfig extends MushroomTitleCardConfig { - type: 'custom:mushroom-title-card'; + type: 'mushroom-title-card'; showControls?: boolean; iconOn?: string; iconOff?: string; diff --git a/src/types/strategy/strategy-generics.ts b/src/types/strategy/strategy-generics.ts index 7b05ac1..3f340df 100644 --- a/src/types/strategy/strategy-generics.ts +++ b/src/types/strategy/strategy-generics.ts @@ -1,3 +1,4 @@ +import { HassServiceTarget } from 'home-assistant-js-websocket'; import { AreaRegistryEntry } from '../homeassistant/data/area_registry'; import { DeviceRegistryEntry } from '../homeassistant/data/device_registry'; import { EntityRegistryEntry } from '../homeassistant/data/entity_registry'; @@ -44,18 +45,7 @@ const SUPPORTED_DOMAINS = [ * * This constant array defines the views that are supported by the strategy. */ -const SUPPORTED_VIEWS = [ - 'camera', - 'climate', - 'cover', - 'fan', - 'home', - 'light', - 'lock', - 'scene', - 'switch', - 'vacuum', -] as const; +const SUPPORTED_VIEWS = ['camera', 'climate', 'cover', 'fan', 'home', 'light', 'scene', 'switch', 'vacuum'] as const; /** * List of supported chips. @@ -255,7 +245,7 @@ export interface StrategyArea extends AreaRegistryEntry { * @property {boolean} fan_count - Chip to display the number of fans on. * @property {boolean} light_count - Chip to display the number of lights on. * @property {boolean} switch_count - Chip to display the number of switches on. - * @property {'auto' | `weather.${string}`} weather_entity - Entity id for the weather chip to use. + * @property {"auto" | `weather.${string}`} weather_entity - Entity id for the weather chip to use. * Accepts `weather.` ids or `auto` only. */ export interface ChipConfiguration { @@ -296,9 +286,17 @@ export function isSortable(object: object): object is Sortable { * @returns {boolean} - True if the object represents a valid service action configuration. */ export function isCallServiceActionConfig(object?: ActionConfig): object is CallServiceActionConfig { - return ( - !!object && (object.action === 'perform-action' || object.action === 'call-service') && 'perform_action' in object - ); + return !!object && object.action === 'call-service' && ['action', 'service'].every((key) => key in object); +} + +/** + * Type guard to check if an object matches the HassServiceTarget interface. + * + * @param {any} [object] - The object to check. + * @returns {boolean} - True if the object represents a valid service action target. + */ +export function isCallServiceActionTarget(object?: HassServiceTarget): object is HassServiceTarget { + return !!object && ['entity_id', 'device_id', 'area_id'].some((key) => key in object); } /** diff --git a/src/types/strategy/views.ts b/src/types/strategy/views.ts deleted file mode 100644 index 17442e5..0000000 --- a/src/types/strategy/views.ts +++ /dev/null @@ -1,17 +0,0 @@ -import {cards} from "./cards"; -import {LovelaceViewConfig} from "../homeassistant/data/lovelace/config/view"; - -export namespace views { - /** - * Options for the extended View class. - * - * @property {cards.ControllerCardConfig} [controllerCardOptions] Options for the Controller card. - */ - export interface ViewConfig extends LovelaceViewConfig { - controllerCardOptions?: cards.ControllerCardOptions; - } -} - - - -