homebridge-ratgdo 2.2.0 → 2.2.2

package/homebridge-ui/public/lib/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/homebridge-ui/public/ui.mjs

@@ -0,0 +1,17 @@
+/* Copyright(C) 2017-2024, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * ui.mjs: Homebridge Ratgdo webUI.
+ */
+
+"use strict";
+
+import { webUi } from "./lib/webUi.mjs";
+
+// Parameters for our feature options webUI.
+const featureOptionsParams = { hasControllers: false, sidebar: { deviceLabel: "Ratgdo Devices" } };
+
+// Instantiate the webUI.
+const ui = new webUi({ featureOptions: featureOptionsParams, name: "Ratgdo" });
+
+// Display the webUI.
+ui.show();

package/homebridge-ui/server.js

@@ -10,6 +10,7 @@ import { HomebridgePluginUiServer } from "@homebridge/plugin-ui-utils";
 class PluginUiServer extends HomebridgePluginUiServer {
 
   constructor() {
+
     super();
 
     // Register getOptions() with the Homebridge server API.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-ratgdo",
   "displayName": "Homebridge Ratgdo",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "HomeKit integration for LiftMaster and Chamberlain garage door openers, without requiring myQ.",
   "license": "ISC",
   "repository": {
@@ -14,13 +14,15 @@
   "type": "module",
   "engines": {
     "node": ">=18.0",
-    "homebridge": ">1.2.0"
+    "homebridge": ">=1.8.0"
   },
   "main": "dist/index.js",
   "scripts": {
-    "build": "npm run clean && tsc",
-    "build-ui": "shx mkdir -p homebridge-ui/public/lib && shx cp \"node_modules/homebridge-plugin-utils/dist/ui/**/*.@(js|mjs)\" homebridge-ui/public/lib",
-    "clean": "shx rm -rf dist homebridge-ui/public/lib && npm run build-ui",
+    "prebuild": "npm run clean && npm run build-ui",
+    "build": "tsc",
+    "build-ui": "shx mkdir -p homebridge-ui/public/lib && shx cp \"node_modules/homebridge-plugin-utils/dist/ui/**/*.@(js|mjs){,.map}\" homebridge-ui/public/lib",
+    "clean": "shx rm -rf dist homebridge-ui/public/lib",
+    "prelint": "npm run build-ui",
     "lint": "eslint eslint.config.mjs src/**.ts homebridge-ui/*.js homebridge-ui/public/**/*.mjs",
     "postpublish": "npm run clean",
     "prepublishOnly": "npm run lint && npm run build"
@@ -31,18 +33,18 @@
   "devDependencies": {
     "@stylistic/eslint-plugin": "^2.1.0",
     "@types/eventsource": "^1.1.15",
-    "@types/node": "^20.12.12",
+    "@types/node": "^20.14.2",
     "eslint": "8.57.0",
     "homebridge": "^1.8.2",
     "shx": "^0.3.4",
     "typescript": "^5.4.5",
-    "typescript-eslint": "^7.9.0"
+    "typescript-eslint": "^7.12.0"
   },
   "dependencies": {
-    "@adobe/fetch": "^4.1.2",
+    "@adobe/fetch": "^4.1.4",
     "@homebridge/plugin-ui-utils": "^1.0.3",
     "bonjour-service": "^1.2.1",
     "eventsource": "^2.0.2",
-    "homebridge-plugin-utils": "^1.0.0"
+    "homebridge-plugin-utils": "^1.4.0"
   }
 }