refactor: Added API documentation and abstracted some internal methods

Author: rkaraivanov

src/components/common/i18n/i18n-controller.ts

@@ -12,135 +12,203 @@ import {
   dateRangePickerResourcesMap,
 } from './utils.js';
 
-interface I18nControllerHost extends ReactiveControllerHost, Element {
-  resourceStrings?: any;
+/**
+ * Defines the structure for the host element that will use this controller.
+ * The host must be a Lit element (ReactiveControllerHost) and an HTMLElement.
+ */
+interface I18nControllerHost extends ReactiveControllerHost, HTMLElement {
+  // Properties the host is expected to have/use, though they are managed by the controller.
+  resourceStrings?: unknown;
   locale?: string;
 }
 
-type I18nControllerConfig = {
-  defaultEN: any;
-  onResourceChange?: (evt: CustomEvent<IResourceChangeEventArgs>) => void;
+type ResourceChangeCallback = (
+  event: CustomEvent<IResourceChangeEventArgs>
+) => unknown;
+
+/** Configuration object for the I18nController. */
+type I18nControllerConfig<T extends object> = {
+  /** The full default English resource strings object for the component. */
+  defaultEN: T;
+  /** An optional callback to execute when the global locale changes. */
+  onResourceChange?: ResourceChangeCallback;
 };
 
-export class I18nController<T> implements ReactiveController {
-  /** Set custom locale that overrides the global one. */
-  public set locale(value: string) {
-    this._locale = value;
-    this._defaultResourceStrings = this.getCurrentResourceStrings();
+/**
+ * Manages localization (i18n) for a Lit web component.
+ * It handles the current locale, component-specific resource overrides,
+ * and updates when the global localization state changes.
+ */
+class I18nController<T extends object> implements ReactiveController {
+  //#region Internal properties and state
+
+  private readonly _host: I18nControllerHost;
+  private readonly _defaultEN: T;
+
+  private _resourceChangeCallback?: ResourceChangeCallback;
+  private _defaultResourceStrings: T;
+  private _locale?: string;
+  private _resourceStrings?: T;
+
+  //#endregion
+
+  //#region Public properties
+
+  /**
+   * Sets a custom locale that overrides the global one for this host component instance.
+   * Setting a new locale triggers an update of the resource strings.
+   */
+  public set locale(value: string | undefined) {
+    if (this._locale !== value) {
+      this._locale = value;
+      this._defaultResourceStrings = this._getCurrentResourceStrings();
+      this._host.requestUpdate();
+    }
   }
 
-  /** Get resolved locale for component */
-  public get locale() {
+  /**
+   * Gets the resolved locale for the host component.
+   * This is the component's custom locale if set, otherwise it falls back to the
+   * global locale.
+   */
+  public get locale(): string {
     return this._locale ?? getCurrentI18n();
   }
 
   /**
    * Sets custom resource string for component with this controller.
    * Gets the resolved resource string for component.
    */
-  public set resourceStrings(value: T) {
-    this._resourceStrings = value;
+  public set resourceStrings(value: T | undefined) {
+    if (this._resourceStrings !== value) {
+      this._resourceStrings = value;
+      this._host.requestUpdate();
+    }
   }
 
   /** Get resolved resource strings for component */
   public get resourceStrings(): T {
     return this._resourceStrings ?? this._defaultResourceStrings;
   }
 
-  private readonly _host: I18nControllerHost;
-  private readonly _defaultEN: T;
-  private readonly _resourceChangeHandler = this.onResourceChange.bind(this);
-  private _locale: string | undefined;
-  private _resourceStrings: T | undefined;
-  private _defaultResourceStrings: T;
-  private _resourceChangeCallback;
+  //#endregion
 
-  constructor(host: I18nControllerHost, config: I18nControllerConfig) {
+  //#region Life-cycle hooks and event listener
+
+  constructor(host: I18nControllerHost, config: I18nControllerConfig<T>) {
     this._host = host;
     this._defaultEN = config.defaultEN;
-    this._defaultResourceStrings = this.getCurrentResourceStrings();
-    this.registerResources(this._defaultEN, true);
+    this._resourceChangeCallback = config.onResourceChange;
 
-    if (config?.onResourceChange) {
-      this._resourceChangeCallback = config.onResourceChange;
-    }
+    this._defaultResourceStrings = this._getCurrentResourceStrings();
+    this._registerResources(this._defaultEN);
 
     this._host.addController(this);
   }
 
-  public registerResources(resource: T, isDefault = false) {
-    const convertedResource = convertToCoreResource(resource);
-    getI18nManager().registerI18n(
-      convertedResource,
-      isDefault ? getI18nManager().defaultLocale : this.locale
-    );
-  }
-
   /** @internal */
   public hostConnected(): void {
-    getI18nManager().addEventListener(
-      'onResourceChange',
-      this._resourceChangeHandler
-    );
+    getI18nManager().addEventListener('onResourceChange', this);
   }
 
   /** @internal */
   public hostDisconnected(): void {
-    getI18nManager().removeEventListener(
-      'onResourceChange',
-      this._resourceChangeHandler
-    );
+    getI18nManager().removeEventListener('onResourceChange', this);
   }
 
-  protected onResourceChange(event: CustomEvent<IResourceChangeEventArgs>) {
-    this._defaultResourceStrings = this.getCurrentResourceStrings();
-    if (this._resourceChangeCallback) {
-      this._resourceChangeCallback(event);
-    }
+  /** @internal */
+  public handleEvent(event: CustomEvent<IResourceChangeEventArgs>): void {
+    this._defaultResourceStrings = this._getCurrentResourceStrings();
+    this._resourceChangeCallback?.(event);
     this._host.requestUpdate();
   }
 
-  /** Get current resource strings based on default. Result is truncated result, containing only relevant locale strings. */
-  protected getCurrentResourceStrings() {
-    const normalizedResourceStrings: T = {} as T;
-    const igcResourceStringKeys = Object.keys(this._defaultEN as any);
-    const resourceStrings = getI18nManager().getCurrentResourceStrings(
+  //#endregion
+
+  //#region Internal API
+
+  /** Registers the default English resources with the global i18n manager. */
+  private _registerResources(resource: T): void {
+    const convertedResource = convertToCoreResource(resource);
+    const manager = getI18nManager();
+
+    manager.registerI18n(convertedResource, manager.defaultLocale);
+  }
+
+  /**
+   * Helper to find the correct resource map based on the component's default resources (`#defaultEN`).
+   * This relies on structural checking (the component's key names).
+   */
+  private _getResourceMapForComponent():
+    | Map<string, string | undefined>
+    | undefined {
+    const keys = Object.keys(this._defaultEN);
+
+    if (keys.includes('last7Days')) {
+      return dateRangePickerResourcesMap;
+    }
+
+    if (keys.includes('selectMonth')) {
+      return calendarResourcesMap;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Gets the current, locale-specific resource strings for the component.
+   * The logic maps component keys (from defaultEN) to core library keys
+   * and retrieves the localized string from the i18n manager.
+   *
+   * Result is truncated, containing only relevant locale strings.
+   */
+  private _getCurrentResourceStrings(): T {
+    const coreResourceStrings = getI18nManager().getCurrentResourceStrings(
       this.locale
     );
-    const resourceStringsKeys = Object.keys(resourceStrings);
-
-    for (const igcKey of igcResourceStringKeys) {
-      const coreKey =
-        calendarResourcesMap.get(igcKey) ??
-        dateRangePickerResourcesMap.get(igcKey) ??
-        undefined;
-      if (coreKey && !coreKey.includes('i18n/')) {
-        if (resourceStringsKeys.includes(coreKey)) {
-          normalizedResourceStrings[igcKey as keyof T] = resourceStrings[
-            coreKey as keyof IResourceStrings
-          ] as T[keyof T];
+    const resourceMap = this._getResourceMapForComponent();
+
+    if (!resourceMap) {
+      return coreResourceStrings as T;
+    }
+
+    const normalizedResourceStrings: T = {} as T;
+    const defaultComponentKeys = Object.keys(this._defaultEN) as (keyof T)[];
+
+    for (const igcKey of defaultComponentKeys) {
+      const coreKey = resourceMap.get(igcKey as string);
+      let resolvedValue: T[keyof T] = this._defaultEN[igcKey];
+
+      if (coreKey) {
+        if (coreKey.includes('getWeekLabel')) {
+          resolvedValue = getDisplayNamesFormatter().getWeekLabel(this.locale, {
+            style: 'short',
+          }) as T[keyof T];
         } else {
-          normalizedResourceStrings[igcKey as keyof T] =
-            this._defaultEN[igcKey as keyof T];
+          resolvedValue =
+            coreKey in coreResourceStrings
+              ? (coreResourceStrings[
+                  coreKey as keyof IResourceStrings
+                ] as T[keyof T])
+              : this._defaultEN[igcKey];
         }
-      } else if (coreKey?.includes('getWeekLabel')) {
-        const weekLabel = getDisplayNamesFormatter().getWeekLabel(this.locale, {
-          style: 'short',
-        });
-        normalizedResourceStrings[igcKey as keyof T] = weekLabel as T[keyof T];
-      } else {
-        // No mapped keys, no need to convert the resources then.
-        return resourceStrings as T;
       }
+
+      normalizedResourceStrings[igcKey] = resolvedValue;
     }
 
     return normalizedResourceStrings;
   }
+
+  //#endregion
 }
 
-export function addI18nController<T>(
+/** Factory function to create and attach the I18nController to a host. */
+export function addI18nController<T extends object>(
   host: I18nControllerHost,
-  config: I18nControllerConfig
-) {
+  config: I18nControllerConfig<T>
+): I18nController<T> {
   return new I18nController<T>(host, config);
 }
+
+export type { I18nController };

src/components/common/i18n/i18n.spec.ts

@@ -22,7 +22,7 @@ import {
 } from './EN/date-range-picker.resources.js';
 import { addI18nController, type I18nController } from './i18n-controller.js';
 
-class TestLocalizedClass<T> extends LitElement {
+class TestLocalizedClass<T extends object> extends LitElement {
   public set locale(value: string) {
     this.i18nController.locale = value;
   }