homebridge-plugin-utils 1.0.0 → 1.2.0

package/dist/ui/webUi.mjs

@@ -4,22 +4,43 @@
  */
 "use strict";
 
+import { webUiFeatureOptions } from "./webUi-featureoptions.mjs";
+
 export class webUi {
 
   // Feature options class instance.
-  #featureOptions;
+  featureOptions;
 
-  // Homebridge class instance.
-  #homebridge;
+  // First run webUI callback endpoints for customization.
+  #firstRun;
 
   // Plugin name.
   #name;
 
-  constructor({ name, featureOptions, homebridge } = {}) {
-
-    this.homebridge = homebridge;
-    this.featureOptions = featureOptions;
+  /**
+   * featureOptions - parameters to webUiFeatureOptions.
+   * firstRun - first run handlers:
+   *   isRequired - do we need to run the first run UI workflow?
+   *   onStart - initialization for the first run webUI to populate forms and other startup tasks.
+   *   onSubmit - execute the first run workflow, typically a login or configuration validation of some sort.
+   * name - plugin name.
+   */
+  constructor({ featureOptions, firstRun = {}, name } = {}) {
+
+    // Defaults for our first run handlers.
+    this.firstRun = { isRequired: () => false, onStart: () => true, onSubmit: () => true };
+
+    // Figure out the options passed in to us.
+    this.featureOptions = new webUiFeatureOptions(featureOptions);
+    this.firstRun = Object.assign({}, this.firstRun, firstRun);
     this.name = name;
+  }
+
+  /**
+   * Render the webUI.
+   */
+  // Render the UI.
+  show() {
 
     // Fire off our UI, catching errors along the way.
     try {
@@ -28,11 +49,11 @@ export class webUi {
     } catch(err) {
 
       // If we had an error instantiating or updating the UI, notify the user.
-      this.homebridge.toast.error(err.message, "Error");
+      homebridge.toast.error(err.message, "Error");
     } finally {
 
       // Always leave the UI in a usable place for the end user.
-      this.homebridge.hideSpinner();
+      homebridge.hideSpinner();
     }
   }
 
@@ -41,31 +62,31 @@ export class webUi {
 
     const buttonFirstRun = document.getElementById("firstRun");
 
+    // Run a custom initialization handler the user may have provided.
+    if(!(await this.#processHandler(this.firstRun.onStart))) {
+
+      return;
+    }
+
     // First run user experience.
     buttonFirstRun.addEventListener("click", async () => {
 
       // Show the beachball while we setup.
-      this.homebridge.showSpinner();
-
-      // Get the list of devices the plugin knows about.
-      const devices = await this.homebridge.getCachedAccessories();
+      homebridge.showSpinner();
 
-      // Sort it for posterity.
-      devices?.sort((a, b) => {
+      // Run a custom submit handler the user may have provided.
+      if(!(await this.#processHandler(this.firstRun.onSubmit))) {
 
-        const aCase = (a.displayName ?? "").toLowerCase();
-        const bCase = (b.displayName ?? "").toLowerCase();
-
-        return aCase > bCase ? 1 : (bCase > aCase ? -1 : 0);
-      });
+        return;
+      }
 
       // Create our UI.
       document.getElementById("pageFirstRun").style.display = "none";
       document.getElementById("menuWrapper").style.display = "inline-flex";
-      this.featureOptions.showUI();
+      this.featureOptions.show();
 
       // All done. Let the user interact with us, although in practice, we shouldn't get here.
-      // this.homebridge.hideSpinner();
+      // homebridge.hideSpinner();
     });
 
     document.getElementById("pageFirstRun").style.display = "block";
@@ -75,81 +96,89 @@ export class webUi {
   #showSettings() {
 
     // Show the beachball while we setup.
-    this.homebridge.showSpinner();
+    homebridge.showSpinner();
 
-    // Create our UI.
-    document.getElementById("menuHome").classList.remove("btn-elegant");
-    document.getElementById("menuHome").classList.add("btn-primary");
-    document.getElementById("menuFeatureOptions").classList.remove("btn-elegant");
-    document.getElementById("menuFeatureOptions").classList.add("btn-primary");
-    document.getElementById("menuSettings").classList.add("btn-elegant");
-    document.getElementById("menuSettings").classList.remove("btn-primary");
+    // Highlight the tab in our UI.
+    this.#toggleClasses("menuHome", "btn-elegant", "btn-primary");
+    this.#toggleClasses("menuFeatureOptions", "btn-elegant", "btn-primary");
+    this.#toggleClasses("menuSettings", "btn-primary", "btn-elegant");
 
     document.getElementById("pageSupport").style.display = "none";
     document.getElementById("pageFeatureOptions").style.display = "none";
 
-    this.homebridge.showSchemaForm();
+    homebridge.showSchemaForm();
 
     // All done. Let the user interact with us.
-    this.homebridge.hideSpinner();
+    homebridge.hideSpinner();
   }
 
   // Show the support tab.
   #showSupport() {
 
     // Show the beachball while we setup.
-    this.homebridge.showSpinner();
-    this.homebridge.hideSchemaForm();
+    homebridge.showSpinner();
+    homebridge.hideSchemaForm();
 
-    // Create our UI.
-    document.getElementById("menuHome").classList.add("btn-elegant");
-    document.getElementById("menuHome").classList.remove("btn-primary");
-    document.getElementById("menuFeatureOptions").classList.remove("btn-elegant");
-    document.getElementById("menuFeatureOptions").classList.add("btn-primary");
-    document.getElementById("menuSettings").classList.remove("btn-elegant");
-    document.getElementById("menuSettings").classList.add("btn-primary");
+    // Highlight the tab in our UI.
+    this.#toggleClasses("menuHome", "btn-primary", "btn-elegant");
+    this.#toggleClasses("menuFeatureOptions", "btn-elegant", "btn-primary");
+    this.#toggleClasses("menuSettings", "btn-elegant", "btn-primary");
 
     document.getElementById("pageSupport").style.display = "block";
     document.getElementById("pageFeatureOptions").style.display = "none";
 
     // All done. Let the user interact with us.
-    this.homebridge.hideSpinner();
+    homebridge.hideSpinner();
   }
 
   // Launch our webUI.
   async #launchWebUI() {
 
     // Retrieve the current plugin configuration.
-    this.featureOptions.currentConfig = await this.homebridge.getPluginConfig();
+    this.featureOptions.currentConfig = await homebridge.getPluginConfig();
 
     // Add our event listeners to animate the UI.
     document.getElementById("menuHome").addEventListener("click", () => this.#showSupport());
-    document.getElementById("menuFeatureOptions").addEventListener("click", () => this.featureOptions.showUI());
+    document.getElementById("menuFeatureOptions").addEventListener("click", () => this.featureOptions.show());
     document.getElementById("menuSettings").addEventListener("click", () => this.#showSettings());
 
     // Get the list of devices the plugin knows about.
-    const devices = await this.homebridge.getCachedAccessories();
+    const devices = await homebridge.getCachedAccessories();
 
     // If we've got devices detected, we launch our feature option UI. Otherwise, we launch our first run UI.
-    if(this.featureOptions.currentConfig.length && devices?.length) {
+    if(this.featureOptions.currentConfig.length && devices?.length && !(await this.#processHandler(this.firstRun.isRequired))) {
 
       document.getElementById("menuWrapper").style.display = "inline-flex";
-      this.featureOptions.showUI();
+      this.featureOptions.show();
+
       return;
     }
 
-    // If we have no configuration, let's create one.
-    if(!this.featureOptions.currentConfig.length) {
+    // If we have the name property set for the plugin configuration yet, let's do so now. If we don't have a configuration, let's initialize it as well.
+    (this.featureOptions.currentConfig[0] ??= { name: this.name }).name ??= this.name;
 
-      this.featureOptions.currentConfig.push({ name: this.name });
-    } else if(!("name" in this.featureOptions.currentConfig[0])) {
+    // Update the plugin configuration and launch the first run UI.
+    await homebridge.updatePluginConfig(this.featureOptions.currentConfig);
+    this.#showFirstRun();
+  }
 
-      // If we haven't set the name, let's do so now.
-      this.featureOptions.currentConfig[0].name = this.name;
+  // Utility to process user-provided custom handlers that can handle both synchronous and asynchronous handlers.
+  async #processHandler(handler) {
+
+    if(((typeof handler === "function") && !(await handler())) || ((typeof handler !== "function") && !handler)) {
+
+      return false;
     }
 
-    // Update the plugin configuration and launch the first run UI.
-    await this.homebridge.updatePluginConfig(this.featureOptions.currentConfig);
-    this.#showFirstRun();
+    return true;
+  }
+
+  // Utility to toggle our classes.
+  #toggleClasses(id, removeClass, addClass) {
+
+    const element = document.getElementById(id);
+
+    element.classList.remove(removeClass);
+    element.classList.add(addClass);
   }
 }

package/dist/utils.d.ts

@@ -1,4 +1,26 @@
 /// <reference types="node" />
+/**
+ * @internal
+ *
+ * A utility type that recursively makes all properties of an object, including nested objects, optional. This should only be used on JSON objects only. Otherwise,
+ * you're going to end up with class methods marked as optional as well. Credit for this belongs to: https://github.com/joonhocho/tsdef.
+ *
+ * @template T - The type to make recursively partial.
+ */
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends Array<infer I> ? Array<DeepPartial<I>> : DeepPartial<T[P]>;
+};
+/**
+ * @internal
+ *
+ * A utility type that recursively makes all properties of an object, including nested objects, optional. This should only be used on JSON objects only. Otherwise,
+ * you're going to end up with class methods marked as optional as well. Credit for this belongs to: https://github.com/joonhocho/tsdef.
+ *
+ * @template T - The type to make recursively partial.
+ */
+export type DeepReadonly<T> = {
+    readonly [P in keyof T]: T[P] extends Array<infer I> ? Array<DeepReadonly<I>> : DeepReadonly<T[P]>;
+};
 export interface HomebridgePluginLogging {
     debug: (message: string, ...parameters: unknown[]) => void;
     error: (message: string, ...parameters: unknown[]) => void;

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,4BAA4B;AAC5B,MAAM,UAAU,KAAK,CAAC,UAAkB;IAEtC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,6CAA6C;AAC7C,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,SAAiC,EAAE,aAAqB;IAElF,wCAAwC;IACxC,IAAG,CAAC,CAAC,MAAM,SAAS,EAAE,CAAC,EAAE,CAAC;QAExB,4FAA4F;QAC5F,MAAM,KAAK,CAAC,aAAa,CAAC,CAAC;QAC3B,OAAO,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACzC,CAAC;IAED,mCAAmC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4CH,4BAA4B;AAC5B,MAAM,UAAU,KAAK,CAAC,UAAkB;IAEtC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,6CAA6C;AAC7C,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,SAAiC,EAAE,aAAqB;IAElF,wCAAwC;IACxC,IAAG,CAAC,CAAC,MAAM,SAAS,EAAE,CAAC,EAAE,CAAC;QAExB,4FAA4F;QAC5F,MAAM,KAAK,CAAC,aAAa,CAAC,CAAC;QAE3B,OAAO,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACzC,CAAC;IAED,mCAAmC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-plugin-utils",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "displayName": "Homebridge Plugin Utilities",
   "description": "Opinionated utilities to provide common capabilities and create rich configuration webUI experiences for Homebridge plugins.",
   "author": {
@@ -40,13 +40,13 @@
   "main": "dist/index.js",
   "devDependencies": {
     "@stylistic/eslint-plugin": "2.1.0",
-    "@types/node": "20.12.12",
+    "@types/node": "20.13.0",
     "eslint": "8.57.0",
     "shx": "^0.3.4",
     "typescript": "5.4.5",
-    "typescript-eslint": "^7.9.0"
+    "typescript-eslint": "^7.11.0"
   },
   "dependencies": {
-    "mqtt": "^5.6.1"
+    "mqtt": "^5.7.0"
   }
 }