Merge pull request #6129 from influxdata/chore-js-refactor-footer-scripts-modules

Chore js refactor footer scripts modules

Author: jstirnaman

.circleci/config.yml

@@ -1,4 +1,4 @@
-version: 2
+version: 2.1
 jobs:
   build:
     docker:
@@ -41,7 +41,7 @@ jobs:
             - /home/circleci/bin
       - run:
           name: Hugo Build
-          command: npx hugo --logLevel info --minify --destination workspace/public
+          command: yarn hugo --environment production --logLevel info --gc --destination workspace/public
       - persist_to_workspace:
           root: workspace
           paths:
@@ -68,7 +68,6 @@ jobs:
           when: on_success
 
 workflows:
-  version: 2
   build:
     jobs:
       - build

.github/instructions/contributing.instructions.md

@@ -1679,7 +1679,7 @@ The shortcode takes a regular expression for matching placeholder names.
 Use the `code-placeholder-key` shortcode to format the placeholder names in 
 text that describes the placeholder--for example:
 
-```
+```markdown
 {{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}}
 ```sh
 curl --request POST http://localhost:8086/write?db=DATABASE_NAME \
@@ -1703,3 +1703,83 @@ InfluxDB API documentation when documentation is deployed.
 Redoc generates HTML documentation using the InfluxDB `swagger.yml`.
 For more information about generating InfluxDB API documentation, see the
 [API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme).
+
+## JavaScript in the documentation UI
+
+The InfluxData documentation UI uses JavaScript with ES6+ syntax and
+`assets/js/main.js` as the entry point to import modules from
+`assets/js`.
+Only `assets/js/main.js` should be imported in HTML files.
+
+`assets/js/main.js` registers components and initializes them on page load.
+
+If you're adding UI functionality that requires JavaScript, follow these steps:
+
+1. In your HTML file, add a `data-component` attribute to the element that
+   should be initialized by your JavaScript code. For example:
+
+   ```html
+   <div data-component="my-component"></div>
+   ``` 
+
+2. Following the component pattern, create a single-purpose JavaScript module
+   (`assets/js/components/my-component.js`)
+   that exports a single function that receives the component element and initializes it.
+3. In `assets/js/main.js`, import the module and register the component to ensure
+   the component is initialized on page load. 
+
+### Debugging JavaScript
+
+To debug JavaScript code used in the InfluxData documentation UI, choose one of the following methods:
+
+- Use source maps and the Chrome DevTools debugger.
+- Use debug helpers that provide breakpoints and console logging as a workaround or alternative for using source maps and the Chrome DevTools debugger.
+
+#### Using source maps and Chrome DevTools debugger
+
+1. In VS Code, select Run > Start Debugging.
+2. Select the "Debug Docs (source maps)" configuration.
+3. Click the play button to start the debugger.
+5. Set breakpoints in the JavaScript source files--files in the
+   `assets/js/ns-hugo-imp:` namespace-- in the
+   VS Code editor or in the Chrome Developer Tools Sources panel:
+
+   - In the VS Code Debugger panel > "Loaded Scripts" section, find the
+     `assets/js/ns-hugo-imp:` namespace.
+   - In the Chrome Developer Tools Sources panel, expand
+     `js/ns-hugo-imp:/<YOUR_WORKSPACE_ROOT>/assets/js/`.
+
+#### Using debug helpers
+
+1. In your JavaScript module, import debug helpers from `assets/js/utils/debug-helpers.js`.
+   These helpers provide breakpoints and console logging as a workaround or alternative for
+   using source maps and the Chrome DevTools debugger.
+2. Insert debug statements by calling the helper functions in your code--for example:
+   
+   ```js
+   import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js';
+
+   const data = debugInspect(someData, 'Data');
+   debugLog('Processing data', 'myFunction');
+
+   function processData() {
+     // Add a breakpoint that works with DevTools
+     debugBreak();
+     
+     // Your existing code...
+   }
+   ```
+
+3. Start Hugo in development mode--for example:
+
+   ```bash
+   yarn hugo server
+   ```
+
+4. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration.
+
+Your system uses the configuration in `launch.json` to launch the site in Chrome
+and attach the debugger to the Developer Tools console.
+
+Make sure to remove the debug statements before merging your changes.
+The debug helpers are designed to be used in development and should not be used in production.

.gitignore

@@ -21,6 +21,7 @@ node_modules
 test-results.xml
 /influxdb3cli-build-scripts/content
 .vscode/*
+!.vscode/launch.json
 .idea
 **/config.toml
 package-lock.json

.prettierignore

@@ -3,3 +3,4 @@
 **/.svn
 **/.hg
 **/node_modules
+assets/jsconfig.json

.vscode/launch.json

@@ -0,0 +1,47 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug JS (debug-helpers)",
+      "type": "chrome",
+      "request": "launch",
+      "url": "http://localhost:1313",
+      "webRoot": "${workspaceFolder}",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "sourceMaps": false,
+      "trace": true,
+      "smartStep": false
+    },
+    {
+      "name": "Debug JS (source maps)",
+      "type": "chrome",
+      "request": "launch",
+      "url": "http://localhost:1313",
+      "webRoot": "${workspaceFolder}",
+      "sourceMaps": true,
+      "sourceMapPathOverrides": {
+        "*": "${webRoot}/assets/js/*",
+        "main.js": "${webRoot}/assets/js/main.js",
+        "page-context.js": "${webRoot}/assets/js/page-context.js",
+        "ask-ai-trigger.js": "${webRoot}/assets/js/ask-ai-trigger.js",
+        "ask-ai.js": "${webRoot}/assets/js/ask-ai.js",
+        "utils/*": "${webRoot}/assets/js/utils/*",
+        "services/*": "${webRoot}/assets/js/services/*"
+      },
+      "skipFiles": [
+        "<node_internals>/**",
+        "node_modules/**",
+        "chrome-extension://**"
+      ],
+      "trace": true,
+      "smartStep": true,
+      "disableNetworkCache": true,
+      "userDataDir": "${workspaceFolder}/.vscode/chrome-user-data",
+      "runtimeArgs": [
+        "--disable-features=VizDisplayCompositor"
+      ]
+    },
+  ]
+}

CONTRIBUTING.md

@@ -1667,7 +1667,7 @@ The shortcode takes a regular expression for matching placeholder names.
 Use the `code-placeholder-key` shortcode to format the placeholder names in 
 text that describes the placeholder--for example:
 
-```
+```markdown
 {{% code-placeholders "DATABASE_NAME|USERNAME|PASSWORD_OR_TOKEN|API_TOKEN|exampleuser@influxdata.com" %}}
 ```sh
 curl --request POST http://localhost:8086/write?db=DATABASE_NAME \
@@ -1691,3 +1691,83 @@ InfluxDB API documentation when documentation is deployed.
 Redoc generates HTML documentation using the InfluxDB `swagger.yml`.
 For more information about generating InfluxDB API documentation, see the
 [API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme).
+
+## JavaScript in the documentation UI
+
+The InfluxData documentation UI uses JavaScript with ES6+ syntax and
+`assets/js/main.js` as the entry point to import modules from
+`assets/js`.
+Only `assets/js/main.js` should be imported in HTML files.
+
+`assets/js/main.js` registers components and initializes them on page load.
+
+If you're adding UI functionality that requires JavaScript, follow these steps:
+
+1. In your HTML file, add a `data-component` attribute to the element that
+   should be initialized by your JavaScript code. For example:
+
+   ```html
+   <div data-component="my-component"></div>
+   ``` 
+
+2. Following the component pattern, create a single-purpose JavaScript module
+   (`assets/js/components/my-component.js`)
+   that exports a single function that receives the component element and initializes it.
+3. In `assets/js/main.js`, import the module and register the component to ensure
+   the component is initialized on page load. 
+
+### Debugging JavaScript
+
+To debug JavaScript code used in the InfluxData documentation UI, choose one of the following methods:
+
+- Use source maps and the Chrome DevTools debugger.
+- Use debug helpers that provide breakpoints and console logging as a workaround or alternative for using source maps and the Chrome DevTools debugger.
+
+#### Using source maps and Chrome DevTools debugger
+
+1. In VS Code, select Run > Start Debugging.
+2. Select the "Debug Docs (source maps)" configuration.
+3. Click the play button to start the debugger.
+5. Set breakpoints in the JavaScript source files--files in the
+   `assets/js/ns-hugo-imp:` namespace-- in the
+   VS Code editor or in the Chrome Developer Tools Sources panel:
+
+   - In the VS Code Debugger panel > "Loaded Scripts" section, find the
+     `assets/js/ns-hugo-imp:` namespace.
+   - In the Chrome Developer Tools Sources panel, expand
+     `js/ns-hugo-imp:/<YOUR_WORKSPACE_ROOT>/assets/js/`.
+
+#### Using debug helpers
+
+1. In your JavaScript module, import debug helpers from `assets/js/utils/debug-helpers.js`.
+   These helpers provide breakpoints and console logging as a workaround or alternative for
+   using source maps and the Chrome DevTools debugger.
+2. Insert debug statements by calling the helper functions in your code--for example:
+   
+   ```js
+   import { debugLog, debugBreak, debugInspect } from './utils/debug-helpers.js';
+
+   const data = debugInspect(someData, 'Data');
+   debugLog('Processing data', 'myFunction');
+
+   function processData() {
+     // Add a breakpoint that works with DevTools
+     debugBreak();
+     
+     // Your existing code...
+   }
+   ```
+
+3. Start Hugo in development mode--for example:
+
+   ```bash
+   yarn hugo server
+   ```
+
+4. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration.
+
+Your system uses the configuration in `launch.json` to launch the site in Chrome
+and attach the debugger to the Developer Tools console.
+
+Make sure to remove the debug statements before merging your changes.
+The debug helpers are designed to be used in development and should not be used in production.

assets/js/api-libs.js

@@ -2,7 +2,7 @@
 ///////////////// Preferred Client Library programming language  ///////////////
 ////////////////////////////////////////////////////////////////////////////////
 import { activateTabs, updateBtnURLs } from './tabbed-content.js';
-import { getPreference, setPreference } from './local-storage.js';
+import { getPreference, setPreference } from './services/local-storage.js';
 
 function getVisitedApiLib() {
   const path = window.location.pathname.match(

assets/js/ask-ai.js

@@ -8,29 +8,31 @@ function setUser(userid, email) {
   window[NAMESPACE] = {
     user: {
       uniqueClientId: userid,
-      email: email, 
-    }
-  }
+      email: email,
+    },
+  };
 }
 
 // Initialize the chat widget
-function initializeChat({onChatLoad, chatAttributes}) {
-  /* See https://docs.kapa.ai/integrations/website-widget/configuration for 
+function initializeChat({ onChatLoad, chatAttributes }) {
+  /* See https://docs.kapa.ai/integrations/website-widget/configuration for
    * available configuration options.
    * All values are strings.
    */
-  // If you make changes to data attributes here, you also need to port the changes to the api-docs/template.hbs API reference template.
+  // If you make changes to data attributes here, you also need to
+  // port the changes to the api-docs/template.hbs API reference template.
   const requiredAttributes = {
     websiteId: 'a02bca75-1dd3-411e-95c0-79ee1139be4d',
     projectName: 'InfluxDB',
     projectColor: '#020a47',
     projectLogo: '/img/influx-logo-cubo-white.png',
-  }
+  };
 
   const optionalAttributes = {
-
-    modalDisclaimer: 'This AI can access [documentation for InfluxDB, clients, and related tools](https://docs.influxdata.com). Information you submit is used in accordance with our [Privacy Policy](https://www.influxdata.com/legal/privacy-policy/).',
-    modalExampleQuestions: 'Use Python to write data to InfluxDB 3,How do I query using SQL?,How do I use MQTT with Telegraf?',
+    modalDisclaimer:
+      'This AI can access [documentation for InfluxDB, clients, and related tools](https://docs.influxdata.com). Information you submit is used in accordance with our [Privacy Policy](https://www.influxdata.com/legal/privacy-policy/).',
+    modalExampleQuestions:
+      'Use Python to write data to InfluxDB 3,How do I query using SQL?,How do I use MQTT with Telegraf?',
     buttonHide: 'true',
     exampleQuestionButtonWidth: 'auto',
     modalOpenOnCommandK: 'true',
@@ -52,28 +54,32 @@ function initializeChat({onChatLoad, chatAttributes}) {
     modalHeaderBorderBottom: 'none',
     modalTitleColor: '#fff',
     modalTitleFontSize: '1.25rem',
-  }
+  };
 
   const scriptUrl = 'https://widget.kapa.ai/kapa-widget.bundle.js';
   const script = document.createElement('script');
   script.async = true;
   script.src = scriptUrl;
-  script.onload = function() {
+  script.onload = function () {
     onChatLoad();
     window.influxdatadocs.AskAI = AskAI;
   };
-  script.onerror = function() {
+  script.onerror = function () {
     console.error('Error loading AI chat widget script');
   };
 
-  const dataset = {...requiredAttributes, ...optionalAttributes, ...chatAttributes};
-  Object.keys(dataset).forEach(key => {
-     // Assign dataset attributes from the object
+  const dataset = {
+    ...requiredAttributes,
+    ...optionalAttributes,
+    ...chatAttributes,
+  };
+  Object.keys(dataset).forEach((key) => {
+    // Assign dataset attributes from the object
     script.dataset[key] = dataset[key];
   });
 
   // Check for an existing script element to remove
-  const oldScript= document.querySelector(`script[src="${scriptUrl}"]`);
+  const oldScript = document.querySelector(`script[src="${scriptUrl}"]`);
   if (oldScript) {
     oldScript.remove();
   }
@@ -82,22 +88,21 @@ function initializeChat({onChatLoad, chatAttributes}) {
 
 function getProductExampleQuestions() {
   const questions = productData?.product?.ai_sample_questions;
-    return questions?.join(',') || '';
+  return questions?.join(',') || '';
 }
 
-/** 
+/**
  * chatParams: specify custom (for example, page-specific) attribute values for the chat, pass the dataset key-values (collected in ...chatParams). See https://docs.kapa.ai/integrations/website-widget/configuration for available configuration options.
  * onChatLoad: function to call when the chat widget has loaded
  * userid: optional, a unique user ID for the user (not currently used for public docs)
-*/
+ */
 export default function AskAI({ userid, email, onChatLoad, ...chatParams }) {
-  
   const modalExampleQuestions = getProductExampleQuestions();
   const chatAttributes = {
     ...(modalExampleQuestions && { modalExampleQuestions }),
     ...chatParams,
-  }
-  initializeChat({onChatLoad, chatAttributes});
+  };
+  initializeChat({ onChatLoad, chatAttributes });
 
   if (userid) {
     setUser(userid, email);