From 3568049a0668364902b6198af49403ac4f76c0e2 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 +- src/types/homeassistant/data/climate.ts | 12 +- .../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/light.ts | 20 +- src/types/homeassistant/data/lovelace.ts | 81 ---- .../data/lovelace/config/action.ts | 145 +++++++ .../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/climate-card-config.ts | 27 +- .../cards/cover-card-config.ts | 25 +- .../cards/entity-card-config.ts | 16 +- .../cards/fan-card-config.ts | 30 +- .../cards/light-card-config.ts | 39 +- .../cards/lock-card-config.ts | 15 +- .../cards/media-player-card-config.ts | 60 +-- .../cards/number-card-config.ts | 22 +- .../cards/person-card-config.ts | 15 +- .../cards/select-card-config.ts | 16 +- .../cards/template-card-config.ts | 53 ++- .../cards/title-card-config.ts | 18 +- .../cards/vacuum-card-config.ts | 35 +- .../shared/config/actions-config.ts | 9 +- .../shared/config/appearance-config.ts | 25 +- .../shared/config/entity-config.ts | 18 +- .../shared/config/utils/info.ts | 4 +- .../shared/config/utils/layout.ts | 4 +- src/types/lovelace-mushroom/utils/info.ts | 2 +- .../utils/lovelace/chip/types.ts | 161 ++++---- src/types/strategy/cards.ts | 72 ---- src/types/strategy/chips.ts | 6 - src/types/strategy/generic.ts | 367 ------------------ src/types/strategy/strategy-cards.ts | 31 ++ src/types/strategy/strategy-generics.ts | 349 +++++++++++++++++ src/types/strategy/strategy-views.ts | 21 + src/types/strategy/views.ts | 17 - 51 files changed, 1659 insertions(+), 1102 deletions(-) delete mode 100644 src/types/homeassistant/data/lovelace.ts create mode 100644 src/types/homeassistant/data/lovelace/config/action.ts delete mode 100644 src/types/strategy/cards.ts delete mode 100644 src/types/strategy/chips.ts delete mode 100644 src/types/strategy/generic.ts create mode 100644 src/types/strategy/strategy-cards.ts create mode 100644 src/types/strategy/strategy-generics.ts create mode 100644 src/types/strategy/strategy-views.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/climate.ts b/src/types/homeassistant/data/climate.ts index e24784d..b27fe90 100644 --- a/src/types/homeassistant/data/climate.ts +++ b/src/types/homeassistant/data/climate.ts @@ -1,11 +1,5 @@ -export const HVAC_MODES = [ - "auto", - "heat_cool", - "heat", - "cool", - "dry", - "fan_only", - "off", -] as const; +/** Represents the available HVAC modes for climate control in Home Assistant. */ +export const HVAC_MODES = ['auto', 'heat_cool', 'heat', 'cool', 'dry', 'fan_only', 'off'] as const; +/** Represents a type for HVAC modes in Home Assistant. */ export type HvacMode = (typeof HVAC_MODES)[number]; 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/light.ts b/src/types/homeassistant/data/light.ts index 35186fb..1dee753 100644 --- a/src/types/homeassistant/data/light.ts +++ b/src/types/homeassistant/data/light.ts @@ -1,6 +1,16 @@ +/** + * Represents the color options for a light entity in Home Assistant. + * + * @property {number} [color_temp_kelvin] - The color temperature in Kelvin. + * @property {[number, number]} [hs_color] - The hue and saturation values. + * @property {[number, number, number]} [rgb_color] - The red, green, and blue color values. + * @property {[number, number, number, number]} [rgbw_color] - The red, green, blue, and white color values. + * @property {[number, number, number, number, number]} [rgbww_color] - The red, green, blue, white, and warm white + * color values. + */ export type LightColor = - | { color_temp_kelvin: number; } - | { hs_color: [number, number]; } - | { rgb_color: [number, number, number]; } - | { rgbw_color: [number, number, number, number]; } - | { rgbww_color: [number, number, number, number, number]; }; + | { color_temp_kelvin: number } + | { hs_color: [number, number] } + | { rgb_color: [number, number, number] } + | { rgbw_color: [number, number, number, number] } + | { rgbww_color: [number, number, number, number, number] }; 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/action.ts b/src/types/homeassistant/data/lovelace/config/action.ts new file mode 100644 index 0000000..4c3bdcb --- /dev/null +++ b/src/types/homeassistant/data/lovelace/config/action.ts @@ -0,0 +1,145 @@ +import { HassServiceTarget } from 'home-assistant-js-websocket'; + +/** + * Represents the configuration for a toggle action in Home Assistant. + * + * @property {'toggle'} action - The action type, which is "toggle". + */ +export interface ToggleActionConfig extends BaseActionConfig { + action: 'toggle'; +} + +/** + * Represents the configuration for a call service action in Home Assistant. + * + * @property {'call-service' | 'perform-action'} action - The action type, which can be "call-service" or + * "perform-action". + * @property {string} [service] - Deprecated; service name for backward compatibility. + * @property {string} perform_action - The action to perform. + * @property {HassServiceTarget} [target] - The target for the service call. + * @property {Record} [service_data] - Deprecated; service data for backward compatibility. + * @property {Record} [data] - The data to send with the service call. + */ +export interface CallServiceActionConfig extends BaseActionConfig { + action: 'call-service' | 'perform-action'; + /** @deprecated "service" is kept for backwards compatibility. Replaced by "perform_action". */ + service?: string; + perform_action: string; + target?: HassServiceTarget; + /** @deprecated "service_data" is kept for backwards compatibility. Replaced by "data". */ + service_data?: Record; + data?: Record; +} + +/** + * Represents the configuration for a navigate action in Home Assistant. + * + * @property {'navigate'} action - The action type, which is "navigate". + * @property {string} navigation_path - The path to navigate to. + * @property {boolean} [navigation_replace] - Whether to replace the current history entry. + */ +export interface NavigateActionConfig extends BaseActionConfig { + action: 'navigate'; + navigation_path: string; + navigation_replace?: boolean; +} + +/** + * Represents the configuration for a URL action in Home Assistant. + * + * @property {'url'} action - The action type, which is "url". + * @property {string} url_path - The URL path to navigate to. + */ +export interface UrlActionConfig extends BaseActionConfig { + action: 'url'; + url_path: string; +} + +/** + * Represents the configuration for a more info action in Home Assistant. + * + * @property {'more-info'} action - The action type, which is "more-info". + * @property {string} [entity] - The entity to show more information about. + */ +export interface MoreInfoActionConfig extends BaseActionConfig { + action: 'more-info'; + entity?: string; +} + +/** + * Represents the configuration for an assist action in Home Assistant. + * + * @property {'assist'} action - The action type, which is "assist". + * @property {string} [pipeline_id] - The ID of the pipeline to use for the assist action. + * @property {boolean} [start_listening] - Whether to start listening for user input. + */ +export interface AssistActionConfig extends BaseActionConfig { + action: 'assist'; + pipeline_id?: string; + start_listening?: boolean; +} + +/** + * Represents the configuration for a no action in Home Assistant. + * + * @property {'none'} action - The action type, which is "none". + */ +export interface NoActionConfig extends BaseActionConfig { + action: 'none'; +} + +/** + * Represents the configuration for a custom action in Home Assistant. + * + * @property {'fire-dom-event'} action - The action type, which is "fire-dom-event". + */ +export interface CustomActionConfig extends BaseActionConfig { + action: 'fire-dom-event'; +} + +/** + * Represents the base configuration for an action in Home Assistant. + * + * @property {string} action - The type of action to perform. + * @property {ConfirmationRestrictionConfig} [confirmation] - Optional confirmation settings for the action. + */ +export interface BaseActionConfig { + action: string; + confirmation?: ConfirmationRestrictionConfig; +} + +/** + * Represents the confirmation restriction configuration for an action in Home Assistant. + * + * @property {string} [text] - The confirmation text. + * @property {RestrictionConfig[]} [exemptions] - List of exemptions for the confirmation. + */ +export interface ConfirmationRestrictionConfig { + text?: string; + exemptions?: RestrictionConfig[]; +} + +/** + * Represents a restriction configuration in Home Assistant. + * + * @property {string} user - The user associated with the restriction. + */ +export interface RestrictionConfig { + user: string; +} + +/** + * Represents the overall action configuration in Home Assistant. + * + * A union type representing different action-configurations available in Home Assistant. + * Each action type can have its own specific configuration. + */ +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/climate-card-config.ts b/src/types/lovelace-mushroom/cards/climate-card-config.ts index f7299da..2432028 100644 --- a/src/types/lovelace-mushroom/cards/climate-card-config.ts +++ b/src/types/lovelace-mushroom/cards/climate-card-config.ts @@ -1,15 +1,16 @@ -import {HvacMode} from "../../homeassistant/data/climate"; -import {LovelaceCardConfig} from "../../homeassistant/data/lovelace"; -import {EntitySharedConfig} from "../shared/config/entity-config"; -import {AppearanceSharedConfig} from "../shared/config/appearance-config"; -import {ActionsSharedConfig} from "../shared/config/actions-config"; +import { HvacMode } from '../../homeassistant/data/climate'; +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'; /** - * Climate Card Config. + * Climate Card Configuration * - * @property {boolean} [show_temperature_control=false] Show buttons to control target temperature. - * @property {HvacMode[]} [hvac_modes] List of hvac modes to display (auto, heat_cool, heat, cool, dry, fan_only, off). - * @property {boolean} [collapsible_controls] Collapse controls when off. + * @property {boolean} [show_temperature_control] - Show buttons to control target temperature. Defaults to false. + * @property {HvacMode[]} [hvac_modes] - List of HVAC modes to display. + * (auto, heat_cool, heat, cool, dry, fan_only, off). + * @property {boolean} [collapsible_controls] - Collapse controls when off. * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/climate.md */ @@ -17,7 +18,7 @@ export type ClimateCardConfig = LovelaceCardConfig & EntitySharedConfig & AppearanceSharedConfig & ActionsSharedConfig & { - show_temperature_control?: boolean; - hvac_modes?: HvacMode[]; - collapsible_controls?: boolean; -}; + show_temperature_control?: boolean; + hvac_modes?: HvacMode[]; + collapsible_controls?: boolean; + }; diff --git a/src/types/lovelace-mushroom/cards/cover-card-config.ts b/src/types/lovelace-mushroom/cards/cover-card-config.ts index 209ba59..6fadf3c 100644 --- a/src/types/lovelace-mushroom/cards/cover-card-config.ts +++ b/src/types/lovelace-mushroom/cards/cover-card-config.ts @@ -1,14 +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'; /** - * Cover Card Config. + * Cover Card Configuration * - * @property {boolean} [show_buttons_control=false] Show buttons to open, close and stop cover. - * @property {boolean} [show_position_control=false] Show a slider to control position of the cover. - * @property {boolean} [show_tilt_position_control=false] Show a slider to control tilt position of the cover. + * @property {boolean} [show_buttons_control] - Show buttons to open, close, and stop the cover. Defaults to false. + * @property {boolean} [show_position_control] - Show a slider to control the position of the cover. Defaults to false. + * @property {boolean} [show_tilt_position_control] - Show a slider to control the tilt position of the cover. Defaults + * to false. * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/cover.md */ @@ -16,7 +17,7 @@ export type CoverCardConfig = LovelaceCardConfig & EntitySharedConfig & AppearanceSharedConfig & ActionsSharedConfig & { - show_buttons_control?: boolean; - show_position_control?: boolean; - show_tilt_position_control?: boolean; -}; + show_buttons_control?: boolean; + show_position_control?: boolean; + show_tilt_position_control?: boolean; + }; diff --git a/src/types/lovelace-mushroom/cards/entity-card-config.ts b/src/types/lovelace-mushroom/cards/entity-card-config.ts index 83c520d..0c91fc4 100644 --- a/src/types/lovelace-mushroom/cards/entity-card-config.ts +++ b/src/types/lovelace-mushroom/cards/entity-card-config.ts @@ -1,12 +1,12 @@ -import {LovelaceCardConfig} from "../../homeassistant/data/lovelace"; -import {AppearanceSharedConfig} from "../shared/config/appearance-config"; -import {EntitySharedConfig} from "../shared/config/entity-config"; -import {ActionsSharedConfig} from "../shared/config/actions-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'; /** - * Entity Card Config. + * Entity Card Configuration * - * @property {string} [icon_color=blue] Custom color for icon when entity is state is active. + * @property {string} [icon_color] - Custom color for the icon when the entity's state is active. Defaults to 'blue'. * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/entity.md */ @@ -14,5 +14,5 @@ export type EntityCardConfig = LovelaceCardConfig & EntitySharedConfig & AppearanceSharedConfig & ActionsSharedConfig & { - icon_color?: string; -}; + icon_color?: string; + }; 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/cards/light-card-config.ts b/src/types/lovelace-mushroom/cards/light-card-config.ts index 35c745e..f243173 100644 --- a/src/types/lovelace-mushroom/cards/light-card-config.ts +++ b/src/types/lovelace-mushroom/cards/light-card-config.ts @@ -1,18 +1,19 @@ -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'; /** - * Light Card Config. + * Light Card Configuration * - * @property {string} [icon_color=blue] Custom color for icon and brightness bar when the lights are on and - * use_light_color is false. - * @property {boolean} [show_brightness_control=false] Show a slider to control brightness. - * @property {boolean} [show_color_temp_control=false] Show a slider to control temperature color. - * @property {boolean} [show_color_control=false] Show a slider to control RGB color. - * @property {boolean} [collapsible_controls=false] Collapse controls when off. - * @property {boolean} [use_light_color=false] Colorize the icon and slider according light temperature or color. + * @property {string} [icon_color] - Custom color for icon and brightness bar when the lights are on and + * `use_light_color` is false; Defaults to 'blue'. + * @property {boolean} [show_brightness_control] - Show a slider to control brightness. Defaults to false. + * @property {boolean} [show_color_temp_control] - Show a slider to control temperature color; Defaults to false. + * @property {boolean} [show_color_control] - Show a slider to control RGB color. Defaults to false. + * @property {boolean} [collapsible_controls] - Collapse controls when off; Defaults to false. + * @property {boolean} [use_light_color] - Colorize the icon and slider according to light temperature or color. + * Defaults to false. * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/light.md */ @@ -20,10 +21,10 @@ export type LightCardConfig = LovelaceCardConfig & EntitySharedConfig & AppearanceSharedConfig & ActionsSharedConfig & { - icon_color?: string; - show_brightness_control?: boolean; - show_color_temp_control?: boolean; - show_color_control?: boolean; - collapsible_controls?: boolean; - use_light_color?: boolean; -}; + icon_color?: string; + show_brightness_control?: boolean; + show_color_temp_control?: boolean; + show_color_control?: boolean; + collapsible_controls?: boolean; + use_light_color?: boolean; + }; diff --git a/src/types/lovelace-mushroom/cards/lock-card-config.ts b/src/types/lovelace-mushroom/cards/lock-card-config.ts index 86df397..eed2521 100644 --- a/src/types/lovelace-mushroom/cards/lock-card-config.ts +++ b/src/types/lovelace-mushroom/cards/lock-card-config.ts @@ -1,14 +1,11 @@ -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'; /** - * Lock Card Config. + * Lock Card Configuration * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/lock.md */ -export type LockCardConfig = LovelaceCardConfig & - EntitySharedConfig & - AppearanceSharedConfig & - ActionsSharedConfig; +export type LockCardConfig = LovelaceCardConfig & EntitySharedConfig & AppearanceSharedConfig & ActionsSharedConfig; diff --git a/src/types/lovelace-mushroom/cards/media-player-card-config.ts b/src/types/lovelace-mushroom/cards/media-player-card-config.ts index 388a647..3026424 100644 --- a/src/types/lovelace-mushroom/cards/media-player-card-config.ts +++ b/src/types/lovelace-mushroom/cards/media-player-card-config.ts @@ -1,35 +1,37 @@ -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'; +/** List of available media controls. */ export const MEDIA_LAYER_MEDIA_CONTROLS = [ - "on_off", - "shuffle", - "previous", - "play_pause_stop", - "next", - "repeat", + 'on_off', + 'shuffle', + 'previous', + 'play_pause_stop', + 'next', + 'repeat', ] as const; +/** Represents a single media control option. */ export type MediaPlayerMediaControl = (typeof MEDIA_LAYER_MEDIA_CONTROLS)[number]; - -export const MEDIA_PLAYER_VOLUME_CONTROLS = [ - "volume_mute", - "volume_set", - "volume_buttons", -] as const; - +/** List of available volume controls. */ +export const MEDIA_PLAYER_VOLUME_CONTROLS = ['volume_mute', 'volume_set', 'volume_buttons'] as const; +/** Represents a single volume control option. */ export type MediaPlayerVolumeControl = (typeof MEDIA_PLAYER_VOLUME_CONTROLS)[number]; /** - * Media Player Card Config. + * Media Player Card Configuration. * - * @property {boolean} [use_media_info=false] Use media info instead of name, state, and icon when media is playing. - * @property {boolean} [show_volume_level=false] Show volume level next to media state when media is playing. - * @property {MediaPlayerVolumeControl[]} [volume_controls] List of controls to display (volume_mute, volume_set, volume_buttons) - * @property {MediaPlayerMediaControl[]} [media_controls] List of controls to display (on_off, shuffle, previous, play_pause_stop, next, repeat) - * @property {boolean} [collapsible_controls=false] Collapse controls when off + * @property {boolean} [use_media_info] - Use media info instead of name, state, and icon when media is playing. + * Defaults to false. + * @property {boolean} [show_volume_level] - Show volume level next to media state when media is playing. + * Defaults to false. + * @property {MediaPlayerVolumeControl[]} [volume_controls] - List of controls to display. + * (volume_mute, volume_set, volume_buttons) + * @property {MediaPlayerMediaControl[]} [media_controls] - List of controls to display + * (on_off, shuffle, previous, play_pause_stop, next, repeat) + * @property {boolean} [collapsible_controls] - Collapse controls when off; Defaults to false. * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/media-player.md */ @@ -37,9 +39,9 @@ export type MediaPlayerCardConfig = LovelaceCardConfig & EntitySharedConfig & AppearanceSharedConfig & ActionsSharedConfig & { - use_media_info?: boolean; - show_volume_level?: boolean; - volume_controls?: MediaPlayerVolumeControl[]; - media_controls?: MediaPlayerMediaControl[]; - collapsible_controls?: boolean; -}; + use_media_info?: boolean; + show_volume_level?: boolean; + volume_controls?: MediaPlayerVolumeControl[]; + media_controls?: MediaPlayerMediaControl[]; + collapsible_controls?: boolean; + }; diff --git a/src/types/lovelace-mushroom/cards/number-card-config.ts b/src/types/lovelace-mushroom/cards/number-card-config.ts index 9239f4b..2b87ccc 100644 --- a/src/types/lovelace-mushroom/cards/number-card-config.ts +++ b/src/types/lovelace-mushroom/cards/number-card-config.ts @@ -1,17 +1,17 @@ -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'; -export const DISPLAY_MODES = ["slider", "buttons"] as const; +export const DISPLAY_MODES = ['slider', 'buttons'] as const; type DisplayMode = (typeof DISPLAY_MODES)[number]; /** - * Number Card Config. + * Number Card Configuration * - * @property {string} [icon_color=blue] Custom color for icon when entity state is active. - * @property {DisplayMode} [display_mode=slider] Slider or Button controls. + * @property {string} [icon_color] - Custom color for the icon when the entity state is active. Defaults to 'blue'. + * @property {DisplayMode} [display_mode] - Slider or Button controls. Defaults to 'slider'. * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/number.md */ @@ -19,6 +19,6 @@ export type NumberCardConfig = LovelaceCardConfig & EntitySharedConfig & AppearanceSharedConfig & ActionsSharedConfig & { - icon_color?: string; - display_mode?: DisplayMode; -}; + icon_color?: string; + display_mode?: DisplayMode; + }; diff --git a/src/types/lovelace-mushroom/cards/person-card-config.ts b/src/types/lovelace-mushroom/cards/person-card-config.ts index 869b74f..b15c7bd 100644 --- a/src/types/lovelace-mushroom/cards/person-card-config.ts +++ b/src/types/lovelace-mushroom/cards/person-card-config.ts @@ -1,14 +1,11 @@ -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'; /** - * Person Card Config. + * Person Card Configuration * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/person.md */ -export type PersonCardConfig = LovelaceCardConfig & - EntitySharedConfig & - AppearanceSharedConfig & - ActionsSharedConfig; +export type PersonCardConfig = LovelaceCardConfig & EntitySharedConfig & AppearanceSharedConfig & ActionsSharedConfig; diff --git a/src/types/lovelace-mushroom/cards/select-card-config.ts b/src/types/lovelace-mushroom/cards/select-card-config.ts index 2a7361b..12fa3f1 100644 --- a/src/types/lovelace-mushroom/cards/select-card-config.ts +++ b/src/types/lovelace-mushroom/cards/select-card-config.ts @@ -1,12 +1,10 @@ -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'; /** - * Select Card Config. - * - * @property {string} [icon_color=blue] Custom color for icon when entity state is active. + * Select Card Configuration * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/select.md */ @@ -14,5 +12,5 @@ export type SelectCardConfig = LovelaceCardConfig & EntitySharedConfig & AppearanceSharedConfig & ActionsSharedConfig & { - icon_color?: string; -}; + icon_color?: string; + }; diff --git a/src/types/lovelace-mushroom/cards/template-card-config.ts b/src/types/lovelace-mushroom/cards/template-card-config.ts index b71ae31..459f5f6 100644 --- a/src/types/lovelace-mushroom/cards/template-card-config.ts +++ b/src/types/lovelace-mushroom/cards/template-card-config.ts @@ -1,36 +1,35 @@ -import {ActionsSharedConfig} from "../shared/config/actions-config"; -import {LovelaceCardConfig} from "../../homeassistant/data/lovelace"; -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'; /** - * Template Card Config. + * Template Card Configuration * - * @property {string} [entity] - * @property {string} [icon] Icon to render. May contain templates. - * @property {string} [icon_color] Icon color to render. May contain templates. - * @property {string} [primary] Primary info to render. May contain templates. - * @property {string} [secondary] Secondary info to render. May contain templates. - * @property {string} [badge_icon] Badge icon to render. May contain templates. - * @property {string} [badge_color] Badge icon color to render. May contain templates. - * @property {string} [picture] Picture to render. May contain templates. - * @property {boolean} [multiline_secondary] Enables support for multiline text for the secondary info. - * @property {string | string[]} [entity_id] Only reacts to the state changes of these entities. - * This can be used if the automatic analysis fails to find all relevant - * entities. + * @property {string} [entity] - Entity associated with the card. + * @property {string} [icon] - Icon to render. May contain templates. + * @property {string} [icon_color] - Icon color to render. May contain templates. + * @property {string} [primary] - Primary info to render. May contain templates. + * @property {string} [secondary] - Secondary info to render. May contain templates. + * @property {string} [badge_icon] - Badge icon to render. May contain templates. + * @property {string} [badge_color] - Badge icon color to render. May contain templates. + * @property {string} [picture] - The picture to render. May contain templates. + * @property {boolean} [multiline_secondary] - Enables support for multiline text for the secondary info. + * @property {string | string[]} [entity_id] - Only reacts to the state changes of these entities. This can be used if + * the automatic analysis fails to find all relevant entities. * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/template.md */ export type TemplateCardConfig = LovelaceCardConfig & AppearanceSharedConfig & ActionsSharedConfig & { - entity?: string; - icon?: string; - icon_color?: string; - primary?: string; - secondary?: string; - badge_icon?: string; - badge_color?: string; - picture?: string; - multiline_secondary?: boolean; - entity_id?: string | string[]; -}; + entity?: string; + icon?: string; + icon_color?: string; + primary?: string; + secondary?: string; + badge_icon?: string; + badge_color?: string; + picture?: string; + multiline_secondary?: boolean; + entity_id?: string | string[]; + }; diff --git a/src/types/lovelace-mushroom/cards/title-card-config.ts b/src/types/lovelace-mushroom/cards/title-card-config.ts index db3f379..efe2209 100644 --- a/src/types/lovelace-mushroom/cards/title-card-config.ts +++ b/src/types/lovelace-mushroom/cards/title-card-config.ts @@ -1,12 +1,16 @@ -import {ActionConfig, LovelaceCardConfig} from "../../homeassistant/data/lovelace"; +import { ActionConfig } from '../../homeassistant/data/lovelace/config/action'; +import { LovelaceCardConfig } from '../../homeassistant/data/lovelace/config/card'; /** - * Title Card Config. + * Title Card Configuration * - * @property {string} [title] Title to render. May contain templates. - * @property {string} [subtitle] Subtitle to render. May contain templates. - * @property {ActionConfig} [title_tap_action=none] Home assistant action to perform on title tap. - * @property {ActionConfig} [subtitle_tap_action=none] Home assistant action to perform on subtitle tap. + * @property {string} [title] - Title to render. + * This May contain templates. + * @property {string} [subtitle] - Subtitle to render. + * This May contain templates. + * @property {ActionConfig} [title_tap_action] - Home assistant action to perform on title tap. + * @property {ActionConfig} [subtitle_tap_action] - Home assistant action to perform on subtitle tap. + * @property {string} [alignment] - Alignment of the title and subtitle. * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/title.md */ @@ -17,5 +21,3 @@ export interface TitleCardConfig extends LovelaceCardConfig { title_tap_action?: ActionConfig; subtitle_tap_action?: ActionConfig; } - - diff --git a/src/types/lovelace-mushroom/cards/vacuum-card-config.ts b/src/types/lovelace-mushroom/cards/vacuum-card-config.ts index f08307f..c4bdb4a 100644 --- a/src/types/lovelace-mushroom/cards/vacuum-card-config.ts +++ b/src/types/lovelace-mushroom/cards/vacuum-card-config.ts @@ -1,31 +1,26 @@ -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'; -export const VACUUM_COMMANDS = [ - "on_off", - "start_pause", - "stop", - "locate", - "clean_spot", - "return_home", -] as const; +export const VACUUM_COMMANDS = ['on_off', 'start_pause', 'stop', 'locate', 'clean_spot', 'return_home'] as const; export type VacuumCommand = (typeof VACUUM_COMMANDS)[number]; /** - * Vacuum Card Config. + * Vacuum Card Configuration * - * @param {boolean} icon_animation Animate the icon when vacuum is cleaning. - * @param {VacuumCommand[]} commands List of commands to display (start_pause, stop, locate, clean_spot, return_home). + * @property {boolean} [icon_animation] - Animate the icon when vacuum is cleaning. + * @property {VacuumCommand[]} [commands] - List of commands to display. + * (on_off, start_pause, stop, locate, clean_spot, return_home). * * @see https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/vacuum.md */ -export type VacuumCardConfig = LovelaceCardConfig & - EntitySharedConfig & - AppearanceSharedConfig & - ActionsSharedConfig & { +export interface VacuumCardConfig + extends LovelaceCardConfig, + EntitySharedConfig, + AppearanceSharedConfig, + ActionsSharedConfig { icon_animation?: boolean; commands?: VacuumCommand[]; -}; +} diff --git a/src/types/lovelace-mushroom/shared/config/actions-config.ts b/src/types/lovelace-mushroom/shared/config/actions-config.ts index a864df8..b8c9d0b 100644 --- a/src/types/lovelace-mushroom/shared/config/actions-config.ts +++ b/src/types/lovelace-mushroom/shared/config/actions-config.ts @@ -1,5 +1,12 @@ -import {ActionConfig} from "../../../homeassistant/data/lovelace"; +import { ActionConfig } from '../../../homeassistant/data/lovelace/config/action'; +/** + * Actions Shared Configuration + * + * @property {ActionConfig} [tap_action] - Action to perform on tap. + * @property {ActionConfig} [hold_action] - Action to perform on hold. + * @property {ActionConfig} [double_tap_action] - Action to perform on double tap. + */ export type ActionsSharedConfig = { tap_action?: ActionConfig; hold_action?: ActionConfig; diff --git a/src/types/lovelace-mushroom/shared/config/appearance-config.ts b/src/types/lovelace-mushroom/shared/config/appearance-config.ts index 1a586d3..18502e8 100644 --- a/src/types/lovelace-mushroom/shared/config/appearance-config.ts +++ b/src/types/lovelace-mushroom/shared/config/appearance-config.ts @@ -1,7 +1,17 @@ -import {boolean, enums, Infer, object, optional} from "superstruct"; -import {layoutStruct} from "./utils/layout"; -import {ICON_TYPES, INFOS} from "./utils/info"; +import { boolean, enums, Infer, object, optional } from 'superstruct'; +import { ICON_TYPES, INFOS } from './utils/info'; +import { layoutStruct } from './utils/layout'; +/** + * Schema for validating the shared appearance configuration of Mushroom cards. + * + * Properties: + * - `layout`: Optional layout configuration (see `layoutStruct`). + * - `fill_container`: Optional boolean indicating whether the card should fill its container. + * - `primary_info`: Optional primary information to display (must be one of `INFOS`). + * - `secondary_info`: Optional secondary information to display (must be one of `INFOS`). + * - `icon_type`: Optional icon type to use (must be one of `ICON_TYPES`). + */ export const appearanceSharedConfigStruct = object({ layout: optional(layoutStruct), fill_container: optional(boolean()), @@ -10,4 +20,13 @@ export const appearanceSharedConfigStruct = object({ icon_type: optional(enums(ICON_TYPES)), }); +/** + * Appearance Shared Configuration + * + * @property {string} [layout] - Layout type (horizontal, vertical, default). + * @property {boolean} [fill_container] - Whether to fill the container. + * @property {string} [primary_info] - Primary information to display. + * @property {string} [secondary_info] - Secondary information to display. + * @property {string} [icon_type] - Type of icon to display. + */ export type AppearanceSharedConfig = Infer; diff --git a/src/types/lovelace-mushroom/shared/config/entity-config.ts b/src/types/lovelace-mushroom/shared/config/entity-config.ts index 4703cd1..f0dde9b 100644 --- a/src/types/lovelace-mushroom/shared/config/entity-config.ts +++ b/src/types/lovelace-mushroom/shared/config/entity-config.ts @@ -1,9 +1,25 @@ -import {Infer, object, optional, string} from "superstruct"; +import { Infer, object, optional, string } from 'superstruct'; +/** + * Schema for validating the shared entity configuration of Mushroom cards. + * + * Properties: + * - `entity`: Optional entity ID to associate with the card. + * - `name`: Optional custom name to display for the entity. + * - `icon`: Optional custom icon to display for the entity. + */ export const entitySharedConfigStruct = object({ entity: optional(string()), name: optional(string()), icon: optional(string()), }); +/** + * Entity Shared Configuration + * + * @type EntitySharedConfig + * @property {string} [entity] - The entity ID associated with the configuration. + * @property {string} [name] - The display name for the entity. + * @property {string} [icon] - The icon to display for the entity. + */ export type EntitySharedConfig = Infer; diff --git a/src/types/lovelace-mushroom/shared/config/utils/info.ts b/src/types/lovelace-mushroom/shared/config/utils/info.ts index 8ee680e..a6f9dd8 100644 --- a/src/types/lovelace-mushroom/shared/config/utils/info.ts +++ b/src/types/lovelace-mushroom/shared/config/utils/info.ts @@ -1,2 +1,2 @@ -export const INFOS = ["name", "state", "last-changed", "last-updated", "none"] as const; -export const ICON_TYPES = ["icon", "entity-picture", "none"] as const; +export const INFOS = ['name', 'state', 'last-changed', 'last-updated', 'none'] as const; +export const ICON_TYPES = ['icon', 'entity-picture', 'none'] as const; diff --git a/src/types/lovelace-mushroom/shared/config/utils/layout.ts b/src/types/lovelace-mushroom/shared/config/utils/layout.ts index 6a47661..a590553 100644 --- a/src/types/lovelace-mushroom/shared/config/utils/layout.ts +++ b/src/types/lovelace-mushroom/shared/config/utils/layout.ts @@ -1,3 +1,3 @@ -import {literal, union} from "superstruct"; +import { literal, union } from 'superstruct'; -export const layoutStruct = union([literal("horizontal"), literal("vertical"), literal("default")]); +export const layoutStruct = union([literal('horizontal'), literal('vertical'), literal('default')]); diff --git a/src/types/lovelace-mushroom/utils/info.ts b/src/types/lovelace-mushroom/utils/info.ts index e3fd13c..15df79f 100644 --- a/src/types/lovelace-mushroom/utils/info.ts +++ b/src/types/lovelace-mushroom/utils/info.ts @@ -1,2 +1,2 @@ -export const INFOS = ["name", "state", "last-changed", "last-updated", "none"] as const; +export const INFOS = ['name', 'state', 'last-changed', 'last-updated', 'none'] as const; export type Info = (typeof INFOS)[number]; diff --git a/src/types/lovelace-mushroom/utils/lovelace/chip/types.ts b/src/types/lovelace-mushroom/utils/lovelace/chip/types.ts index 7769b99..6d807ee 100644 --- a/src/types/lovelace-mushroom/utils/lovelace/chip/types.ts +++ b/src/types/lovelace-mushroom/utils/lovelace/chip/types.ts @@ -1,18 +1,18 @@ -import {ActionConfig} from "../../../../homeassistant/data/lovelace"; -import {Info} from "../../info"; +import { ActionConfig } from '../../../../homeassistant/data/lovelace/config/action'; +import { Info } from '../../info'; /** * Action Chip Config * - * @property {"action"} type Type of the chip. - * @property {string} [icon] Custom icon. - * @property {string} [icon_color] Custom color for icon. - * @property {ActionConfig} [tap_action] Home assistant action to perform on tap. - * @property {ActionConfig} [hold_action] Home assistant action to perform on hold. - * @property {ActionConfig} [double_tap_action] Home assistant action to perform on double_tap. + * @property {"action"} type - Type of the chip. + * @property {string} [icon] - Custom icon for the chip. + * @property {string} [icon_color] - Custom color for the icon. + * @property {ActionConfig} [tap_action] - Home Assistant action to perform on tap. + * @property {ActionConfig} [hold_action] - Home Assistant action to perform on hold. + * @property {ActionConfig} [double_tap_action] - Home Assistant action to perform on double tap. */ export type ActionChipConfig = { - type: "action"; + type: 'action'; icon?: string; icon_color?: string; tap_action?: ActionConfig; @@ -23,18 +23,18 @@ export type ActionChipConfig = { /** * Alarm Control Panel Chip Config * - * @property {"alarm-control-panel"} type Type of the chip. - * @property {string} [entity] Entity. - * @property {string} [name] Custom name. - * @property {string} [content_info] Custom content. - * @property {string} [icon] Custom icon. - * @property {string} [icon_color] Custom color for icon. - * @property {ActionConfig} [tap_action] Home assistant action to perform on tap. - * @property {ActionConfig} [hold_action] Home assistant action to perform on hold. - * @property {ActionConfig} [double_tap_action] Home assistant action to perform on double_tap. + * @property {"alarm-control-panel"} type - Type of the chip. + * @property {string} [entity] - The entity ID associated with the chip. + * @property {string} [name] - Custom name for the chip. + * @property {Info} [content_info] - Custom content information. + * @property {string} [icon] - Custom icon for the chip. + * @property {string} [icon_color] - Custom color for the icon. + * @property {ActionConfig} [tap_action] - Home Assistant action to perform on tap. + * @property {ActionConfig} [hold_action] - Home Assistant action to perform on hold. + * @property {ActionConfig} [double_tap_action] - Home Assistant action to perform on double tap. */ export type AlarmControlPanelChipConfig = { - type: "alarm-control-panel"; + type: 'alarm-control-panel'; entity?: string; name?: string; content_info?: Info; @@ -48,30 +48,30 @@ export type AlarmControlPanelChipConfig = { /** * Back Chip Config * - * @property {"back"} type Type of the chip. - * @property {string} [icon] Custom icon. + * @property {"back"} type - Type of the chip. + * @property {string} [icon] - Custom icon for the chip. */ export type BackChipConfig = { - type: "back"; + type: 'back'; icon?: string; }; /** * Entity Chip Config * - * @property {"entity"} type Type of the chip. - * @property {string} [entity] Entity. - * @property {string} [name] Custom name. - * @property {string} [content_info] Custom content. - * @property {string} [icon] Custom icon. - * @property {string} [icon_color] Custom color for icon. - * @property {boolean} [use_entity_picture] - * @property {ActionConfig} [tap_action] Home assistant action to perform on tap. - * @property {ActionConfig} [hold_action] Home assistant action to perform on hold. - * @property {ActionConfig} [double_tap_action] Home assistant action to perform on double_tap. + * @property {"entity"} type - Type of the chip. + * @property {string} [entity] - The entity ID associated with the chip. + * @property {string} [name] - Custom name for the chip. + * @property {Info} [content_info] - Custom content information. + * @property {string} [icon] - Custom icon for the chip. + * @property {string} [icon_color] - Custom color for the icon. + * @property {boolean} [use_entity_picture] - Whether to use the entity picture. + * @property {ActionConfig} [tap_action] - Action to perform on tap. + * @property {ActionConfig} [hold_action] - Action to perform on hold. + * @property {ActionConfig} [double_tap_action] - Action to perform on double tap. */ export type EntityChipConfig = { - type: "entity"; + type: 'entity'; entity?: string; name?: string; content_info?: Info; @@ -86,27 +86,27 @@ export type EntityChipConfig = { /** * Menu Chip Config * - * @property {"menu"} type Type of the chip. - * @property {string} [icon] Custom icon. + * @property {"menu"} type - Type of the chip. + * @property {string} [icon] - Custom icon for the chip. */ export type MenuChipConfig = { - type: "menu"; + type: 'menu'; icon?: string; }; /** * Weather Chip Config * - * @property {"weather"} type Type of the chip. - * @property {string} [entity] Entity. - * @property {ActionConfig} [tap_action] Home assistant action to perform on tap. - * @property {ActionConfig} [hold_action] Home assistant action to perform on hold. - * @property {ActionConfig} [double_tap_action] Home assistant action to perform on double_tap. - * @property {boolean} [show_temperature] Show the temperature. - * @property {boolean} [show_conditions] Show the conditions. + * @property {"weather"} type - Type of the chip. + * @property {string} [entity] - The entity ID associated with the chip. + * @property {ActionConfig} [tap_action] - Home Assistant action to perform on tap. + * @property {ActionConfig} [hold_action] - Home Assistant action to perform on hold. + * @property {ActionConfig} [double_tap_action] - Home Assistant action to perform on double tap. + * @property {boolean} [show_temperature] - Show the temperature. + * @property {boolean} [show_conditions] - Show the conditions. */ export type WeatherChipConfig = { - type: "weather"; + type: 'weather'; entity?: string; tap_action?: ActionConfig; hold_action?: ActionConfig; @@ -118,19 +118,19 @@ export type WeatherChipConfig = { /** * Template Chip Config * - * @property {"template"} type Type of the chip. - * @property {string} [entity] Entity. - * @property {ActionConfig} [tap_action] Home assistant action to perform on tap. - * @property {ActionConfig} [hold_action] Home assistant action to perform on hold. - * @property {ActionConfig} [double_tap_action] Home assistant action to perform on double_tap. - * @property {string} [content] - * @property {string} [icon] Custom icon. - * @property {string} [icon_color] Custom color for icon. - * @property {string} [picture] - * @property {string | string[]} [entity_id] + * @property {"template"} type - Type of the chip. + * @property {string} [entity] - The entity ID associated with the chip. + * @property {ActionConfig} [tap_action] - Home Assistant action to perform on tap. + * @property {ActionConfig} [hold_action] - Home Assistant action to perform on hold. + * @property {ActionConfig} [double_tap_action] - Home Assistant action to perform on double tap. + * @property {string} [content] - Custom content for the chip. + * @property {string} [icon] - Custom icon for the chip. + * @property {string} [icon_color] - Custom color for the icon. + * @property {string} [picture] - Custom picture for the chip. + * @property {string | string[]} [entity_id] - Associated entity ID(s). */ export type TemplateChipConfig = { - type: "template"; + type: 'template'; entity?: string; hold_action?: ActionConfig; tap_action?: ActionConfig; @@ -145,31 +145,31 @@ export type TemplateChipConfig = { /** * Conditional Chip Config * - * @property {"conditional"} type Type of the chip. - * @property {LovelaceChipConfig} [chip] A chip configuration. - * @property {[]} conditions + * @property {"conditional"} type - Type of the chip. + * @property {LovelaceChipConfig} [chip] - A chip configuration. + * @property {[]} conditions - Conditions for the chip. */ -export interface ConditionalChipConfig { - type: "conditional"; +export type ConditionalChipConfig = { + type: 'conditional'; chip?: LovelaceChipConfig; conditions: any[]; -} +}; /** * Light Chip Config * - * @property {"light"} type Type of the chip. - * @property {string} [entity] Entity. - * @property {string} [name] - * @property {Info} [content_info] - * @property {string} [icon] Custom icon. - * @property {boolean} [use_light_color] Colorize the icon and slider according light temperature or color. - * @property {ActionConfig} [tap_action] Home assistant action to perform on tap. - * @property {ActionConfig} [hold_action] Home assistant action to perform on hold. - * @property {ActionConfig} [double_tap_action] Home assistant action to perform on double_tap. + * @property {"light"} type - Type of the chip. + * @property {string} [entity] - The entity ID associated with the chip. + * @property {string} [name] - Custom name for the chip. + * @property {Info} [content_info] - Custom content information. + * @property {string} [icon] - Custom icon for the chip. + * @property {boolean} [use_light_color] - Colorize the icon and slider according to light temperature or color. + * @property {ActionConfig} [tap_action] - Home Assistant action to perform on tap. + * @property {ActionConfig} [hold_action] - Home Assistant action to perform on hold. + * @property {ActionConfig} [double_tap_action] - Home Assistant action to perform on double tap. */ export type LightChipConfig = { - type: "light"; + type: 'light'; entity?: string; name?: string; content_info?: Info; @@ -183,12 +183,27 @@ export type LightChipConfig = { /** * Spacer Chip Config * - * @property {"spacer"} type Type of the chip. + * @property {"spacer"} type - Type of the chip. */ export type SpacerChipConfig = { - type: "spacer"; + type: 'spacer'; }; +/** + * 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/chips.ts b/src/types/strategy/chips.ts deleted file mode 100644 index d9eace7..0000000 --- a/src/types/strategy/chips.ts +++ /dev/null @@ -1,6 +0,0 @@ -import {TemplateChipConfig, WeatherChipConfig} from "../lovelace-mushroom/utils/lovelace/chip/types"; - -export namespace chips { - export type TemplateChipOptions = Omit; - export type WeatherChipOptions = 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 new file mode 100644 index 0000000..46c5a42 --- /dev/null +++ b/src/types/strategy/strategy-cards.ts @@ -0,0 +1,31 @@ +import { LovelaceCardConfig } from '../homeassistant/data/lovelace/config/card'; +import { TitleCardConfig as MushroomTitleCardConfig } from '../lovelace-mushroom/cards/title-card-config'; +import { ActionsSharedConfig } from '../lovelace-mushroom/shared/config/actions-config'; +import { AppearanceSharedConfig } from '../lovelace-mushroom/shared/config/appearance-config'; +import { EntitySharedConfig } from '../lovelace-mushroom/shared/config/entity-config'; + +/** + * Abstract Card Config. + */ +export type AbstractCardConfig = LovelaceCardConfig & EntitySharedConfig & AppearanceSharedConfig & ActionsSharedConfig; + +/** + * Header Card Config. + * + * @property {boolean} [showControls=true] - False to hide controls. + * @property {string} [iconOn] - Icon to show for switching entities from the off state. + * @property {string} [iconOff] - Icon to show for switching entities to the off state. + * @property {string} [onService=none] - Service to call for switching entities from the off state. + * @property {string} [offService=none] - Service to call for switching entities to the off state. + */ +export interface StrategyHeaderCardConfig extends MushroomTitleCardConfig { + type: 'mushroom-title-card'; + showControls?: boolean; + iconOn?: string; + iconOff?: string; + onService?: string; + offService?: string; +} + +/** Custom Configuration of a Strategy Header Card. */ +export type CustomHeaderCardConfig = Omit; diff --git a/src/types/strategy/strategy-generics.ts b/src/types/strategy/strategy-generics.ts new file mode 100644 index 0000000..3f340df --- /dev/null +++ b/src/types/strategy/strategy-generics.ts @@ -0,0 +1,349 @@ +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'; +import { ActionConfig, CallServiceActionConfig } from '../homeassistant/data/lovelace/config/action'; +import { LovelaceCardConfig } from '../homeassistant/data/lovelace/config/card'; +import { LovelaceConfig } from '../homeassistant/data/lovelace/config/types'; +import { LovelaceViewConfig, LovelaceViewRawConfig } from '../homeassistant/data/lovelace/config/view'; +import { HomeAssistant } from '../homeassistant/types'; +import { LovelaceChipConfig } from '../lovelace-mushroom/utils/lovelace/chip/types'; +import { StrategyHeaderCardConfig } from './strategy-cards'; + +/** + * 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. + * + * @remarks + * - `_` refers to all domains. + * - `default` refers to the miscellaneous domain. + */ +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. + */ +const SUPPORTED_VIEWS = ['camera', 'climate', 'cover', 'fan', 'home', 'light', 'scene', 'switch', 'vacuum'] as const; + +/** + * List of supported chips. + * + * This constant array defines the chips that are supported by the strategy. + */ +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. + */ +const HOME_VIEW_SECTIONS = ['areas', 'areasTitle', 'chips', 'greeting', 'persons'] as const; + +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]; + +/** + * Base interface for sortable items. + * + * @property {number} order - Numeric value used for sorting items + */ +interface SortableBase { + order: number; +} + +/** + * Sortable item that uses a title for identification. + * Mutually exclusive with SortableWithName. + * + * @property {string} title - Display title of the item + * @property {never} [name] - Prevents using name property + */ +type SortableWithTitle = SortableBase & { title: string; name?: never }; + +/** + * Sortable item that uses a name for identification. + * Mutually exclusive with SortableWithTitle. + * + * @property {string} name - Identifier name of the item + * @property {never} [title] - Prevents using title property + */ +type SortableWithName = SortableBase & { name: string; title?: never }; + +/** + * Union type for items that can be sorted. + * Items must have either a title or a name property, but not both. + * + * @remarks + * This type is used to sort objects by title or by name. + * The `order` property is used to sort the items. + */ +export type Sortable = SortableWithTitle | SortableWithName; + +/** + * An entry of a Home Assistant Registry. + */ +export type RegistryEntry = StrategyArea | DeviceRegistryEntry | EntityRegistryEntry; + +/** + * View Configuration of the strategy. + * + * @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; +} + +/** + * Dashboard Info Object. + * + * Home Assistant passes this object to the Dashboard Generator method. + * + * @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. + * + * @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 }; + }; + }; +} + +/** + * All-Domains Configuration. + * + * @property {boolean | undefined} hide_config_entities - If True, all configuration entities are hidden from the + * dashboard. + * @property {boolean | undefined} hide_diagnostic_entities - If True, all diagnostic entities are hidden from the + * dashboard. + */ +export interface AllDomainsConfig { + hide_config_entities: boolean | undefined; + hide_diagnostic_entities: boolean | undefined; +} + +/** + * Single Domain Configuration. + * + * @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 view. + */ +export interface SingleDomainConfig extends Partial { + hidden: boolean; + order?: number; +} + +/** + * Strategy Configuration. + * + * @property {Object.} areas - List of areas. + * @property {Object.} card_options - Card options for entities. + * @property {ChipConfiguration} 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 {Record} 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: ChipConfiguration; + 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. + */ +export interface StrategyDefaults extends StrategyConfig { + areas: { undisclosed: StrategyArea } & { [S: string]: StrategyArea }; +} + +/** + * Strategy Area. + * + * @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. + * + * @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 {LovelaceChipConfig[] | []} extra_chips - List of extra chips. + * @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. + * Accepts `weather.` ids or `auto` only. + */ +export interface ChipConfiguration { + climate_count: boolean; + cover_count: boolean; + extra_chips: LovelaceChipConfig[] | []; + fan_count: boolean; + light_count: boolean; + switch_count: boolean; + weather_entity: 'auto' | `weather.${string}`; +} + +/** + * Custom Card Configuration for an entity. + * + * @property {boolean} hidden - If True, the card is hidden from the dashboard. + */ +export interface CustomCardConfig extends LovelaceCardConfig { + hidden?: boolean; +} + +/** + * Checks if the given object is of a sortable type. + * + * Sortable types are objects that have an `order`, `title` or `name` property. + * + * @param {object} object - The object to check. + * @returns {boolean} - True if the object is an instance of Sortable, false otherwise. + */ +export function isSortable(object: object): object is Sortable { + return object && ('order' in object || 'title' in object || 'name' in object); +} + +/** + * Type guard to check if an object matches the CallServiceActionConfig interface. + * + * @param {ActionConfig} [object] - The object to check. + * @returns {boolean} - True if the object represents a valid service action configuration. + */ +export function isCallServiceActionConfig(object?: ActionConfig): object is CallServiceActionConfig { + 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); +} + +/** + * Type guard to check if a given identifier exists in a list of supported identifiers. + * + * + * @param id The identifier to check + * @param supportedList The list of valid identifiers + * @returns True if the identifier exists in the supported list + * + * @typeParam T - The type of supported identifiers + */ +function isInSupportedList(id: string, supportedList: readonly T[]): id is T { + return supportedList.includes(id as T); +} + +/** + * Type guard to check if the strategy supports a given view identifier. + * + * @param {string} id - The view identifier to check (e.g., "light", "climate", "home"). + * @returns {boolean} - True if the identifier represents a supported view type + */ +export function isSupportedView(id: string): id is SupportedViews { + return isInSupportedList(id, SUPPORTED_VIEWS); +} + +/** + * Type guard to check if the strategy supports a given domain identifier. + * + * @param {string} id - The domain identifier to check (e.g., "light", "climate", "sensor"). + * @returns {boolean} - True if the identifier represents a supported domain. + * + * @remarks + * Special domains: + * - "_" represents all domains + * - "default" represents the miscellaneous domain + */ +export function isSupportedDomain(id: string): id is SupportedDomains { + return isInSupportedList(id, SUPPORTED_DOMAINS); +} + +/** + * Type guard to check if the strategy supports a given chip identifier. + * + * @param {string} id - The chip identifier to check (e.g., "light", "climate", "weather"). + * @returns {boolean} - True if the identifier represents a supported chip type. + */ +export function isSupportedChip(id: string): id is SupportedChips { + return isInSupportedList(id, SUPPORTED_CHIPS); +} diff --git a/src/types/strategy/strategy-views.ts b/src/types/strategy/strategy-views.ts new file mode 100644 index 0000000..23f9103 --- /dev/null +++ b/src/types/strategy/strategy-views.ts @@ -0,0 +1,21 @@ +import { LovelaceViewConfig } from '../homeassistant/data/lovelace/config/view'; +import { CustomHeaderCardConfig } from './strategy-cards'; +import { SupportedDomains } from './strategy-generics'; + +/** + * Options for the extended View class. + * + * @property {StrategyHeaderCardConfig} [headerCardConfiguration] - Options for the Header card. + */ +export interface ViewConfig extends LovelaceViewConfig { + headerCardConfiguration?: CustomHeaderCardConfig; +} + +/** + * Interface for constructors of AbstractView subclasses that are expected to define a static domain property. + * + * @property {SupportedDomains | "home"} domain - The domain which the view is representing. + */ +export interface ViewConstructor { + domain: SupportedDomains | 'home'; +} 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; - } -} - - - -