Add framework for using external libs and add jslinq (#63)

* Add framework for using external libs and add jslinq.

---------

Co-authored-by: Satya Deep Maheshwari <[email protected]>

.eslintignore

@@ -1,2 +1,3 @@
 helix-importer-ui
 blocks/embed/lite-yt-embed.js
+ext-libs/**

.ext-libs-mapping.json

@@ -0,0 +1,7 @@
+[
+    {
+        "name": "jslinq",
+        "source": "node_modules/jslinq/build",
+        "target": "ext-libs/jslinq"
+    }
+]

.github/folder-compare/run-and-create-github-summary.bash

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+for var in GITHUB_SERVER_URL GITHUB_REPOSITORY GITHUB_RUN_ID GITHUB_STEP_SUMMARY GITHUB_ENV DOMAIN_MAIN DOMAIN_BRANCH; do
+  if [ -z "${!var}" ]; then
+    echo "WARN: $var is not set. Link to artifacts will not be added."
+  fi
+done
+
+
+npm run compare ./.ext-libs-mapping.json;
+
+if grep -q "Difference" difference_results.md; then
+  echo "Diffs found"
+  export SUMMARY="$(cat difference_results.md)"
+
+  echo "$SUMMARY" >> "$GITHUB_STEP_SUMMARY"
+
+  # using multi-line-vars from  https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-of-a-multiline-string
+  EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
+  echo "SUMMARY<<$EOF" >> "$GITHUB_ENV"
+  echo "$SUMMARY" >> "$GITHUB_ENV"
+  echo "$EOF" >> "$GITHUB_ENV"
+else
+  echo "No diffs found"
+  cat difference_results.md >> "$GITHUB_STEP_SUMMARY"
+  echo "SUMMARY=" >> "$GITHUB_ENV"
+fi

.github/workflows/compare-folders.yaml

@@ -0,0 +1,35 @@
+name: Compare Folders
+
+on:
+  pull_request:
+    types: [ opened, synchronize ]
+
+jobs:
+  compare-folders:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: .
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Compare folders
+        id: run-compare
+        run: |
+          ./.github/folder-compare/run-and-create-github-summary.bash
+          cat difference_results.md
+
+      - name: Comment on Pull Request
+        if: env.SUMMARY != ''
+        uses: peter-evans/create-or-update-comment@v3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issue-number: ${{ github.event.number }}
+          body: ${{ env.SUMMARY }}
+

.gitignore

@@ -11,4 +11,6 @@ helix-importer-ui
 .github/visual-tests/test-results
 .github/visual-tests/screenshots/
 .github/visual-tests/node_modules/
-.github/visual-tests/generated-test-paths.txt
+.github/visual-tests/generated-test-paths.txt
+
+difference_results.md

README.md

@@ -1,7 +1,9 @@
 # Sunstar Website
+
 Franklin project for https://www.sunstar.com/
 
 ## Environments
+
 - Preview: https://main--sunstar--hlxsites.hlx.page/
 - Live: https://main--sunstar--hlxsites.hlx.live/
 - Edit: https://adobe.sharepoint.com/:f:/r/sites/HelixProjects/Shared%20Documents/sites/sunstar/sunstar
@@ -23,3 +25,42 @@ npm run lint
 1. Install the [Helix CLI](https://github.com/adobe/helix-cli): `npm install -g @adobe/helix-cli`
 1. Start Franklin Proxy: `hlx up` (opens your browser at `http://localhost:3000`)
 1. Open the `{repo}` directory in your favorite IDE and start coding :)
+
+## Adding external JS libraries
+
+You can add external JS libraries to your project but you need to make sure to copy over the files to be used in front end code in browser to the [ext-libs](./ext-libs/) folder. This would make them available for execution in the client browser.
+
+Here are the steps to follow:
+
+1. Add the JS library to the [package.json](./package.json) file in the `dependencies` section. For example, to add the `jslinq` library, add the following line to the [package.json](./package.json) file:
+
+    ```
+    "dependencies": {
+        "jslinq": "^1.0.22"
+    }
+    ```
+
+2. Run `npm install` to install the library in the [node_modules](./node_modules) folder.
+
+3. Run
+    ```
+    npm run copy node_modules/jslinq/build ext-libs jslinq
+    ```
+    to copy the library from the [node_modules](./node_modules) folder to the [ext-libs](./ext-libs) folder.
+
+4. Add a mapping in [.ext-libs-mapping.json](./.ext-libs-mapping.json) file to map the library to its respective location on [ext-libs](./ext-libs/) folder.
+
+    For example, to map the `jslinq` library, add the following line to the [.ext-libs-mapping.json](./.ext-libs-mapping.json) file:
+
+    ```
+        {
+            "name": "jslinq",
+            "source": "node_modules/jslinq/build",
+            "target": "ext-libs/jslinq"
+        }
+    ```
+5. THe library is now available in the [ext-libs](./ext-libs/) folder and can be used in the front end code in the browser. For e.g. , add the following in the fron end code to load the `jslinq` library:
+
+    ```
+    await loadScript('/ext-libs/jslinq/jslinq.min.js');
+    ```

package.json

@@ -9,7 +9,9 @@
     "lint:js": "eslint .",
     "lint:css": "stylelint blocks/**/*.css styles/**/*.css",
     "lint": "npm run lint:js && npm run lint:css",
-    "prepare": "husky install"
+    "prepare": "husky install",
+    "copy": "node ./tools/actions/copy.js",
+    "compare": "node ./tools/actions/compare.js"
   },
   "lint-staged": {
     "*.js": "eslint .",
@@ -40,5 +42,10 @@
     "sinon": "15.2.0",
     "stylelint": "15.10.3",
     "stylelint-config-standard": "34.0.0"
+  },
+
+  "dependencies": {
+    "fs-extra": "^11.1.1",
+    "jslinq": "^1.0.22"
   }
 }

scripts/scripts.js

@@ -440,6 +440,17 @@ export async function loadScript(url, attrs = {}) {
   return loadingPromise;
 }
 
+export async function queryIndex(sheet) {
+  await loadScript('/ext-libs/jslinq/jslinq.min.js');
+  const index = await fetchIndex('query-index', sheet);
+  // Fetch the index until it is complete
+  while (!index.complete) {
+    // eslint-disable-next-line no-await-in-loop
+    await fetchIndex('query-index', sheet);
+  }
+  const { jslinq } = window;
+  return jslinq(index.data);
+}
 /**
  * Add a paging widget to the div. The paging widget looks like this:
  * <pre><code>

tools/actions/compare.js

@@ -0,0 +1,72 @@
+/* eslint-disable no-console */
+const fs = require('fs');
+const path = require('path');
+const process = require('process');
+
+function isDifferent(folder1, folder2) {
+  let different = false;
+  const entries1 = fs.readdirSync(folder1);
+  const entries2 = fs.readdirSync(folder2);
+
+  // Check if the number of entries is different
+  if (entries1.length !== entries2.length) {
+    return true;
+  }
+
+  // Check if the names of entries are different
+  const sortedEntries1 = entries1.sort();
+  const sortedEntries2 = entries2.sort();
+  for (let i = 0; i < sortedEntries1.length; i += 1) {
+    if (sortedEntries1[i] !== sortedEntries2[i]) {
+      return true;
+    }
+  }
+
+  for (let i = 0; i < sortedEntries1.length; i += 1) {
+    const filePath1 = path.join(folder1, sortedEntries1[i]);
+    const filePath2 = path.join(folder2, sortedEntries1[i]);
+
+    if (fs.statSync(filePath1).isFile() && fs.statSync(filePath2).isFile()) {
+      const content1 = fs.readFileSync(filePath1, 'utf8');
+      const content2 = fs.readFileSync(filePath2, 'utf8');
+
+      if (content1 !== content2) {
+        different = true;
+      }
+    } else if (fs.statSync(filePath1).isDirectory() && fs.statSync(filePath2).isDirectory()) {
+      different = isDifferent(filePath1, filePath2);
+    } else {
+      different = true;
+    }
+    if (different) { break; }
+  }
+  return different;
+}
+try {
+  const mappingFilePath = process.argv[2];
+  if (!mappingFilePath) {
+    console.error('Please provide the path to the config JSON file as a command line argument.');
+    process.exit(1);
+  }
+  const mappings = JSON.parse(fs.readFileSync(mappingFilePath, 'utf8'));
+  const comparisonResults = [];
+
+  mappings.forEach((mapping) => {
+    const result = isDifferent(mapping.source, mapping.target);
+    if (result) {
+      comparisonResults.push(`### :small_orange_diamond: Difference detected between \`${mapping.source}\` and \`${mapping.target}\`
+      \n#### Execute this to fix the difference: \n \`npm run copy ${mapping.source} ext-libs ${mapping.target.split('/').pop()}\`\n`);
+    }
+  });
+
+  if (comparisonResults.length > 0) {
+    fs.writeFileSync('difference_results.md', comparisonResults.join('\n'));
+    console.log('Comparison results have been written to difference_results.md');
+  } else {
+    fs.writeFileSync('difference_results.md', '### :tada: No external libs differences detected :tada:');
+    console.log('No differences detected');
+  }
+} catch (error) {
+  fs.writeFileSync('difference_results.md', 'Error reading or processing the JSON file');
+  console.error('Error reading or processing the JSON file:', error.message);
+}

tools/actions/copy.js

@@ -0,0 +1,35 @@
+/* eslint-disable no-console */
+const fs = require('fs-extra');
+const path = require('path');
+
+// Get source and target directory paths from command line arguments
+const sourceDir = process.argv[2];
+const targetDir = process.argv[3];
+const copiedFolderName = process.argv[4] || path.basename(sourceDir);
+
+if (!sourceDir || !targetDir) {
+  console.error('Usage: npm run copy <source-directory> <target-directory> [copied-folder-name]');
+  process.exit(1);
+}
+
+// Ensure that the target directory exists
+fs.ensureDirSync(targetDir);
+
+// Construct the path to the target directory including the specified copied folder name
+const targetPath = require('path').join(targetDir, copiedFolderName);
+
+// Check if the target folder already exists
+if (fs.existsSync(targetPath)) {
+  // If it exists, remove it
+  fs.removeSync(targetPath);
+  console.log(`Removed existing folder '${targetPath}'.`);
+}
+
+// Perform the folder copy operation (recursively)
+try {
+  fs.copySync(sourceDir, targetPath, { recursive: true });
+  console.log(`Folder '${sourceDir}' copied to '${targetPath}' successfully.`);
+} catch (error) {
+  console.error('Error copying folder:', error);
+  process.exit(1);
+}