From a852347cc4ff02ed0cebf306076f0b5251c98727 Mon Sep 17 00:00:00 2001 From: DigiLive Date: Sat, 5 Apr 2025 11:18:24 +0200 Subject: [PATCH] Fix typo in JSDOC --- src/cards/AbstractCard.ts | 58 +++++++++++++++++------------------ src/cards/ControllerCard.ts | 6 ++-- src/localize.ts | 60 +++++++++++++++++++++++++++++++++++++ src/views/AbstractView.ts | 4 +-- src/views/HomeView.ts | 8 ++--- 5 files changed, 98 insertions(+), 38 deletions(-) create mode 100644 src/localize.ts diff --git a/src/cards/AbstractCard.ts b/src/cards/AbstractCard.ts index 606d512..c5524ad 100644 --- a/src/cards/AbstractCard.ts +++ b/src/cards/AbstractCard.ts @@ -1,59 +1,59 @@ -import { Registry } from '../Registry'; -import { LovelaceCardConfig } from '../types/homeassistant/data/lovelace/config/card'; -import { AbstractCardConfig } from '../types/strategy/strategy-cards'; -import { RegistryEntry } from '../types/strategy/strategy-generics'; -import { logMessage, lvlFatal } from '../utilities/debug'; +import {Helper} from "../Helper"; +import {EntityCardConfig} from "../types/lovelace-mushroom/cards/entity-card-config"; +import {cards} from "../types/strategy/cards"; +import {generic} from "../types/strategy/generic"; /** * Abstract Card Class * - * To create a card configuration, this class should be extended by a child class. - * Child classes should override the default configuration so the card correctly reflects the entity. + * To create a new card, extend the new class with this one. * - * @remarks - * Before using this class, the Registry module must be initialized by calling {@link Registry.initialize}. + * @class + * @abstract */ abstract class AbstractCard { - /** The registry entry this card represents. */ - readonly entity: RegistryEntry; + /** + * Entity to create the card for. + * + * @type {generic.RegistryEntry} + */ + entity: generic.RegistryEntry; /** - * The card configuration for this entity. + * Configuration of the card. * - * Child classes should override this property to reflect their own card type and options. + * @type {EntityCardConfig} */ - protected configuration: LovelaceCardConfig = { - type: 'custom:mushroom-entity-card', - icon: 'mdi:help-circle', + config: EntityCardConfig = { + type: "custom:mushroom-entity-card", + icon: "mdi:help-circle", }; /** * Class constructor. * - * @param {RegistryEntry} entity The registry entry to create a card configuration for. - * - * @remarks - * Before this class can be used, the Registry module must be initialized by calling {@link Registry.initialize}. + * @param {generic.RegistryEntry} entity The hass entity to create a card for. + * @throws {Error} If the Helper module isn't initialized. */ - protected constructor(entity: RegistryEntry) { - if (!Registry.initialized) { - logMessage(lvlFatal, 'Registry not initialized!'); + protected constructor(entity: generic.RegistryEntry) { + if (!Helper.isInitialized()) { + throw new Error("The Helper module must be initialized before using this one."); } this.entity = entity; } /** - * Get a card configuration. + * Get a card. * - * The configuration should be set by any of the child classes so the card correctly reflects an entity. + * @returns {cards.AbstractCardConfig} A card object. */ - getCard(): AbstractCardConfig { + getCard(): cards.AbstractCardConfig { return { - ...this.configuration, - entity: 'entity_id' in this.entity ? this.entity.entity_id : undefined, + ...this.config, + entity: "entity_id" in this.entity ? this.entity.entity_id : undefined, }; } } -export default AbstractCard; +export {AbstractCard}; diff --git a/src/cards/ControllerCard.ts b/src/cards/ControllerCard.ts index b33878c..e85aad0 100644 --- a/src/cards/ControllerCard.ts +++ b/src/cards/ControllerCard.ts @@ -1,7 +1,7 @@ -import {cards} from "../types/strategy/cards"; -import {LovelaceCardConfig} from "../types/homeassistant/data/lovelace"; import {HassServiceTarget} from "home-assistant-js-websocket"; +import {LovelaceCardConfig} from "../types/homeassistant/data/lovelace"; import {StackCardConfig} from "../types/homeassistant/panels/lovelace/cards/types"; +import {cards} from "../types/strategy/cards"; /** * Controller Card class. @@ -49,7 +49,7 @@ class ControllerCard { /** * Create a Controller card. * - * @return {StackCardConfig} A Controller card. + * @returns {StackCardConfig} A Controller card. */ createCard(): StackCardConfig { const cards: LovelaceCardConfig[] = [ diff --git a/src/localize.ts b/src/localize.ts new file mode 100644 index 0000000..ccf7471 --- /dev/null +++ b/src/localize.ts @@ -0,0 +1,60 @@ +import * as de from "./translations/de.json"; +import * as en from "./translations/en.json"; +import * as es from "./translations/es.json"; +import * as nl from "./translations/nl.json"; +import {HomeAssistant} from "./types/homeassistant/types"; + +/* Registry of currently supported languages */ +const languages: Record = { + en, + es, + nl, + de, +}; + +/* The fallback language if the user-defined language isn't defined */ +const DEFAULT_LANG = "en"; + +/** + * Get a string by keyword and language. + * + * @param {string} key The keyword to look for in object notation (E.g. generic.home). + * @param {string} lang The language to get the string from (E.g. en). + * + * @returns {string | undefined} The requested string or undefined if the keyword doesn't exist/on error. + */ +function getTranslatedString(key: string, lang: string): string | undefined { + try { + return key + .split(".") + .reduce( + (o, i) => (o as Record)[i], + languages[lang] + ) as string; + } catch (_) { + + return undefined; + } +} + +/** + * Set up the localization. + * + * It reads the user-defined language with a fall-back to english and returns a function to get strings from + * language-files by keyword. + * + * If the keyword is undefined, or on error, the keyword itself is returned. + * + * @param {HomeAssistant} hass The Home Assistant object. + * @returns {(key: string) => string} The function to call for translating strings. + */ +export default function setupCustomLocalize(hass?: HomeAssistant): (key: string) => string { + return function (key: string) { + const lang = hass?.locale.language ?? DEFAULT_LANG; + + let translated = getTranslatedString(key, lang); + if (!translated) translated = getTranslatedString(key, DEFAULT_LANG); + + return translated ?? key; + }; +} diff --git a/src/views/AbstractView.ts b/src/views/AbstractView.ts index a252f81..28e7d13 100644 --- a/src/views/AbstractView.ts +++ b/src/views/AbstractView.ts @@ -68,7 +68,7 @@ abstract class AbstractView { /** * Create the cards to include in the view. * - * @return {Promise<(StackCardConfig | TitleCardConfig)[]>} An array of card objects. + * @returns {Promise<(StackCardConfig | TitleCardConfig)[]>} An array of card objects. */ async createViewCards(): Promise<(StackCardConfig | TitleCardConfig)[]> { if (this.#domain === "home") { @@ -154,7 +154,7 @@ abstract class AbstractView { * Get a target of entity IDs for the given domain. * * @param {string} domain - The target domain to retrieve entity IDs from. - * @return {HassServiceTarget} - A target for a service call. + * @returns {HassServiceTarget} - A target for a service call. */ targetDomain(domain: string): HassServiceTarget { return { diff --git a/src/views/HomeView.ts b/src/views/HomeView.ts index 2106f71..38bf83c 100644 --- a/src/views/HomeView.ts +++ b/src/views/HomeView.ts @@ -49,7 +49,7 @@ class HomeView extends AbstractView { /** * Create the cards to include in the view. * - * @return {Promise<(StackCardConfig | TemplateCardConfig | ChipsCardConfig)[]>} Promise a View Card array. + * @returns {Promise<(StackCardConfig | TemplateCardConfig | ChipsCardConfig)[]>} Promise a View Card array. * @override */ async createViewCards(): Promise<(StackCardConfig | TemplateCardConfig | ChipsCardConfig)[]> { @@ -123,7 +123,7 @@ class HomeView extends AbstractView { /** * Create the chips to include in the view. * - * @return {Promise} Promise a chip array. + * @returns {Promise} Promise a chip array. */ async #createChips(): Promise { if ((Helper.strategyOptions.home_view.hidden as string[]).includes("chips")) { @@ -185,7 +185,7 @@ class HomeView extends AbstractView { /** * Create the person cards to include in the view. * - * @return {PersonCardConfig[]} A Person Card array. + * @returns {PersonCardConfig[]} A Person Card array. */ #createPersonCards(): PersonCardConfig[] { if ((Helper.strategyOptions.home_view.hidden as string[]).includes("persons")) { @@ -214,7 +214,7 @@ class HomeView extends AbstractView { * * Area cards are grouped into two areas per row. * - * @return {Promise<(TitleCardConfig | StackCardConfig)[]>} Promise an Area Card Section. + * @returns {Promise<(TitleCardConfig | StackCardConfig)[]>} Promise an Area Card Section. */ async #createAreaSection(): Promise<(TitleCardConfig | StackCardConfig)[]> { if ((Helper.strategyOptions.home_view.hidden as string[]).includes("areas")) {