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

Chore: JavaScript: 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: npx hugo --config config/production/config.yml --logLevel info --minify --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,64 @@ 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:
+
+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 for
+   Hugo's lack of source map support in the asset pipeline.
+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 Docs (console-based)" 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,18 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Docs (console-based)",
+      "type": "chrome",
+      "request": "launch",
+      "url": "http://localhost:1313",
+      "webRoot": "${workspaceFolder}",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "sourceMaps": false,
+      "trace": true,
+      "smartStep": false
+    }
+  ]
+}

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,64 @@ 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:
+
+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 for
+   Hugo's lack of source map support in the asset pipeline.
+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 Docs (console-based)" 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/components/diagram.js

@@ -0,0 +1,72 @@
+// Memoize the mermaid module import
+let mermaidPromise = null;
+
+export default function Diagram({ component }) {
+  // Import mermaid.js module (memoized)
+  if (!mermaidPromise) {
+    mermaidPromise = import('mermaid');
+  }
+  mermaidPromise.then(({ default: mermaid }) => {
+    // Configure mermaid with InfluxData theming
+    mermaid.initialize({
+      startOnLoad: false, // We'll manually call run()
+      theme: document.body.classList.contains('dark-theme') ? 'dark' : 'default',
+      themeVariables: {
+        fontFamily: 'Proxima Nova',
+        fontSize: '16px',
+        lineColor: '#22ADF6',
+        primaryColor: '#22ADF6',
+        primaryTextColor: '#545454',
+        secondaryColor: '#05CE78',
+        tertiaryColor: '#f4f5f5',
+      },
+      securityLevel: 'loose', // Required for interactive diagrams
+      logLevel: 'error'
+    });
+    
+    // Process the specific diagram component
+    try {
+      mermaid.run({ nodes: [component] });
+    } catch (error) {
+      console.error('Mermaid diagram rendering error:', error);
+    }
+    
+    // Store reference to mermaid for theme switching
+    if (!window.mermaidInstances) {
+      window.mermaidInstances = new Map();
+    }
+    window.mermaidInstances.set(component, mermaid);
+  }).catch(error => {
+    console.error('Failed to load Mermaid library:', error);
+  });
+  
+  // Listen for theme changes to refresh diagrams
+  const observer = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+      if (mutation.attributeName === 'class' && 
+          document.body.classList.contains('dark-theme') !== window.isDarkTheme) {
+        window.isDarkTheme = document.body.classList.contains('dark-theme');
+        
+        // Reload this specific diagram with new theme
+        if (window.mermaidInstances?.has(component)) {
+          const mermaid = window.mermaidInstances.get(component);
+          mermaid.initialize({
+            theme: window.isDarkTheme ? 'dark' : 'default'
+          });
+          mermaid.run({ nodes: [component] });
+        }
+      }
+    });
+  });
+  
+  // Watch for theme changes on body element
+  observer.observe(document.body, { attributes: true });
+  
+  // Return cleanup function to be called when component is destroyed
+  return () => {
+    observer.disconnect();
+    if (window.mermaidInstances?.has(component)) {
+      window.mermaidInstances.delete(component);
+    }
+  };
+}