Framework7 casing and Webpack comments/documentation update (#1298)

* fix casing for framework7 class

* docs and eslint for webpack config

* remove path from pages array

* remove debug code

* more doc

* more doc

src/Scripts/framework7.ts

@@ -5,4 +5,5 @@ import "framework7";
 // So we do a naked import and then export it from here so the rest of our code can treat
 // it as a regular module.
 // @ts-expect-error Framework doesn't exist, but it does - just do it
-export const framework7 = window.Framework7;
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const Framework7 = window.Framework7;

src/Scripts/ui/newMobilePaneIosFrame.ts

@@ -6,7 +6,7 @@ import dayjs from "dayjs";
 import utc from "dayjs/plugin/utc";
 import $ from "jquery";
 
-import { framework7 } from "../framework7";
+import { Framework7 } from "../framework7";
 import { HeaderModel } from "../HeaderModel";
 import { mhaStrings } from "../mhaStrings";
 import { Poster } from "../Poster";
@@ -18,7 +18,7 @@ import { SummaryRow } from "../row/SummaryRow";
 // This is the "new-mobile" UI rendered in newMobilePaneIosFrame.html
 
 // Framework7 app object
-let myApp: typeof framework7 = null;
+let myApp: typeof Framework7 = null;
 
 dayjs.extend(utc);
 
@@ -27,7 +27,7 @@ function postError(error: unknown, message: string): void {
 }
 
 function initializeFramework7(): void {
-    myApp = new framework7();
+    myApp = new Framework7();
 
     myApp.addView("#summary-view");
     myApp.addView("#received-view");

webpack.config.js

@@ -1,13 +1,51 @@
+/**
+ * Webpack configuration file for the MHA project.
+ *
+ * This configuration file sets up various plugins and settings for building the project,
+ * including handling TypeScript files, CSS extraction, HTML template generation, and more.
+ *
+ * Plugins used:
+ * - FileManagerPlugin: Manages file operations like copying resources.
+ * - ForkTsCheckerWebpackPlugin: Runs TypeScript type checking in a separate process.
+ * - HtmlWebpackPlugin: Generates HTML files for each page.
+ * - MiniCssExtractPlugin: Extracts CSS into separate files.
+ * - webpack.DefinePlugin: Defines global constants.
+ *
+ * Functions:
+ * - getHttpsOptions: Asynchronously retrieves HTTPS options for the development server.
+ * - getHash: Generates a short hash from a given string.
+ * - generateEntry: Generates an entry object for webpack configuration.
+ * - generateHtmlWebpackPlugins: Generates an array of HtmlWebpackPlugin instances for each page.
+ *
+ * Environment Variables:
+ * - SCM_COMMIT_ID: The commit ID used to generate a version hash.
+ * - APPINSIGHTS_INSTRUMENTATIONKEY: Application Insights instrumentation key.
+ * - npm_package_config_dev_server_port: Port for the development server.
+ *
+ * @param {Object} env - Environment variables passed to the webpack configuration.
+ * @param {Object} options - Options passed to the webpack configuration.
+ * @returns {Promise<Object>} The webpack configuration object.
+ */
+
 /* eslint-disable @typescript-eslint/no-require-imports */
 const path = require("path");
 
-const FileManagerPlugin = require("filemanager-webpack-plugin");
-const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
-const HtmlWebpackPlugin = require("html-webpack-plugin");
-const MiniCssExtractPlugin = require("mini-css-extract-plugin");
+const FileManagerPlugin = require("filemanager-webpack-plugin"); // eslint-disable-line @typescript-eslint/naming-convention
+const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin"); // eslint-disable-line @typescript-eslint/naming-convention
+const HtmlWebpackPlugin = require("html-webpack-plugin"); // eslint-disable-line @typescript-eslint/naming-convention
+const MiniCssExtractPlugin = require("mini-css-extract-plugin"); // eslint-disable-line @typescript-eslint/naming-convention
 const devCerts = require("office-addin-dev-certs");
 const webpack = require("webpack");
 
+/**
+ * Asynchronously retrieves HTTPS server options.
+ *
+ * This function attempts to get HTTPS server options using the `devCerts` library.
+ * If successful, it returns an object containing the certificate authority (CA),
+ * key, and certificate. If an error occurs, it logs the error and returns an empty object.
+ *
+ * @returns {Promise<{ca: string, key: string, cert: string} | {}>} A promise that resolves to an object with HTTPS options or an empty object if an error occurs.
+ */
 async function getHttpsOptions() {
     try {
         const httpsOptions = await devCerts.getHttpsServerOptions();
@@ -18,7 +56,13 @@ async function getHttpsOptions() {
     }
 }
 
-// Simple hash function to reduce commit ID to something short
+/**
+ * Generates a hash for a given string.
+ * Used to reduce commit ID to something short.
+ *
+ * @param {string} str - The input string to hash.
+ * @returns {string} The hexadecimal representation of the hash.
+ */
 const getHash = (str) => {
     let hash = 42;
     if (str.length) {
@@ -41,12 +85,12 @@ const buildTime = new Date().toUTCString();
 console.log("buildTime:", buildTime);
 
 const pages = [
-    { name: "mha", script: "ui/mha" },
-    { name: "uitoggle", script: "ui/uiToggle" },
-    { name: "newDesktopFrame", script: "ui/newDesktopFrame" },
-    { name: "classicDesktopFrame", script: "ui/classicDesktopFrame" },
-    { name: "newMobilePaneIosFrame", script: "ui/newMobilePaneIosFrame" },
-    { name: "privacy", script: "ui/privacy" },
+    { name: "mha", script: "mha" },
+    { name: "uitoggle", script: "uiToggle" },
+    { name: "newDesktopFrame", script: "newDesktopFrame" },
+    { name: "classicDesktopFrame", script: "classicDesktopFrame" },
+    { name: "newMobilePaneIosFrame", script: "newMobilePaneIosFrame" },
+    { name: "privacy", script: "privacy" },
     // Redirection/static pages
     { name: "Default" }, // uitoggle.html?default=classic
     { name: "DefaultPhone" }, // uitoggle.html?default=classic
@@ -56,15 +100,44 @@ const pages = [
     { name: "Functions" },
 ];
 
+/**
+ * Generates an entry object for webpack configuration.
+ *
+ * This function iterates over a list of pages and constructs an entry object
+ * where each key is the name of a script and the value is the path to the
+ * corresponding TypeScript file.
+ * Entry object looks like this:
+ * {
+ * 'mha': './src/Scripts/ui/mha.ts',
+ * 'uiToggle': './src/Scripts/ui/uiToggle.ts',
+ * ...
+ * }
+ *
+ * @returns {Object} An object representing the entry points for webpack.
+ */
 function generateEntry() {
     return pages.reduce((config, page) => {
         if (page.script) {
-            config[page.script] = `./src/Scripts/${page.script}.ts`;
+            config[page.script] = `./src/Scripts/ui/${page.script}.ts`;
         }
         return config;
     }, {});
 }
 
+/**
+ * Generates an array of HtmlWebpackPlugin instances for each page.
+ * One looks like this:
+ * new HtmlWebpackPlugin ({
+ *  inject: true,
+ *  template: './src/Pages/mha.html',
+ *  filename: 'mha.html',
+ *  chunks: [ 'mha' ]
+ * })
+ *
+ * This is how our actual html files are generated, with includes for the appropriate scripts and CSS.
+ *
+ * @returns {HtmlWebpackPlugin[]} An array of HtmlWebpackPlugin instances.
+ */
 function generateHtmlWebpackPlugins() {
     return pages.map((page) => new HtmlWebpackPlugin({
         inject: true,
@@ -80,9 +153,9 @@ module.exports = async (env, options) => {
         plugins: [
             new MiniCssExtractPlugin({ filename: `${version}/[name].css` }),
             new webpack.DefinePlugin({
-                __VERSION__: JSON.stringify(version),
-                __AIKEY__: JSON.stringify(aikey),
-                __BUILDTIME__: JSON.stringify(buildTime),
+                __VERSION__: JSON.stringify(version), // eslint-disable-line @typescript-eslint/naming-convention
+                __AIKEY__: JSON.stringify(aikey), // eslint-disable-line @typescript-eslint/naming-convention
+                __BUILDTIME__: JSON.stringify(buildTime), // eslint-disable-line @typescript-eslint/naming-convention
             }),
             new FileManagerPlugin({
                 events: {
@@ -130,7 +203,7 @@ module.exports = async (env, options) => {
             clean: true,
         },
         devServer: {
-            headers: { "Access-Control-Allow-Origin": "*" },
+            headers: { "Access-Control-Allow-Origin": "*" }, // eslint-disable-line @typescript-eslint/naming-convention
             static: __dirname,
             server: {
                 type: "https",