@aurodesignsystem-dev/auro-library 0.0.0-pr187.0

package/bin/generateDocs_index.mjs

@@ -0,0 +1,210 @@
+import path from 'path';
+import markdownMagic from 'markdown-magic';
+import fs from 'fs';
+import https from 'https';
+
+const __dirname = new URL('.', import.meta.url).pathname;
+
+const readmeTemplateUrl = 'https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/README.md';
+const dirDocTemplates = './docTemplates';
+const readmeFilePath = dirDocTemplates + '/README.md';
+
+/**
+ * Extract NPM, NAMESPACE and NAME from package.json
+ */
+
+function nameExtraction() {
+  const packageJson = fs.readFileSync('package.json', 'utf8', function(err, data) {
+    if (err) {
+      console.log('ERROR: Unable to read package.json file', err);
+    }
+  })
+
+  let pName = JSON.parse(packageJson).name;
+  let pVersion = JSON.parse(packageJson).version;
+  let pdtVersion = JSON.parse(packageJson).peerDependencies['\@aurodesignsystem/design-tokens'].substring(1)
+  let wcssVersion = JSON.parse(packageJson).peerDependencies['\@aurodesignsystem/webcorestylesheets'].substring(1)
+
+  let npmStart = pName.indexOf('@');
+  let namespaceStart = pName.indexOf('/');
+  let nameStart = pName.indexOf('-');
+
+  let result = {
+    'npm': pName.substring(npmStart, namespaceStart),
+    'namespace': pName.substring(namespaceStart + 1, nameStart),
+    'namespaceCap': pName.substring(namespaceStart + 1)[0].toUpperCase() + pName.substring(namespaceStart + 2, nameStart),
+    'name': pName.substring(nameStart + 1),
+    'nameCap': pName.substring(nameStart + 1)[0].toUpperCase() + pName.substring(nameStart + 2),
+    'version': pVersion,
+    'tokensVersion': pdtVersion,
+    'wcssVersion': wcssVersion
+  };
+
+  return result;
+ }
+
+/**
+ * Replace all instances of [npm], [name], [Name], [namespace] and [Namespace] accordingly
+ */
+
+function formatTemplateFileContents(content, destination) {
+  let nameExtractionData = nameExtraction();
+  let result = content;
+
+  /**
+   * Replace placeholder strings
+   */
+  result = result.replace(/\[npm]/g, nameExtractionData.npm);
+  result = result.replace(/\[name](?!\()/g, nameExtractionData.name);
+  result = result.replace(/\[Name](?!\()/g, nameExtractionData.nameCap);
+  result = result.replace(/\[namespace]/g, nameExtractionData.namespace);
+  result = result.replace(/\[Namespace]/g, nameExtractionData.namespaceCap);
+  result = result.replace(/\[Version]/g, nameExtractionData.version);
+  result = result.replace(/\[dtVersion]/g, nameExtractionData.tokensVersion);
+  result = result.replace(/\[wcssVersion]/g, nameExtractionData.wcssVersion);
+
+  /**
+   * Cleanup line breaks
+   */
+  result = result.replace(/(\r\n|\r|\n)[\s]+(\r\n|\r|\n)/g, '\r\n\r\n'); // Replace lines containing only whitespace with a carriage return.
+  result = result.replace(/>(\r\n|\r|\n){2,}/g, '>\r\n'); // Remove empty lines directly after a closing html tag.
+  result = result.replace(/>(\r\n|\r|\n)```/g, '>\r\n\r\n```'); // Ensure an empty line before code samples.
+  result = result.replace(/>(\r\n|\r|\n){2,}```(\r\n|\r|\n)/g, '>\r\n```\r\n'); // Ensure no empty lines before close of code sample.
+  result = result.replace(/([^(\r\n|\r|\n)])(\r?\n|\r(?!\n))+#/g, "$1\r\n\r\n#"); // Ensure empty line before header sections.
+
+  /**
+   * Write the result to the destination file
+   */
+  fs.writeFileSync(destination, result, { encoding: 'utf8'});
+}
+
+function formatApiTableContents(content, destination) {
+  const nameExtractionData = nameExtraction();
+  const wcName = nameExtractionData.namespace + '-' + nameExtractionData.name;
+
+  let result = content;
+
+  result = result
+    .replace(/\r\n|\r|\n####\s`([a-zA-Z]*)`/g, `\r\n#### <a name="$1"></a>\`$1\`<a href="#" style="float: right; font-size: 1rem; font-weight: 100;">back to top</a>`)
+    .replace(/\r\n|\r|\n\|\s`([a-zA-Z]*)`/g, '\r\n| [$1](#$1)')
+    .replace(/\| \[\]\(#\)/g, "");
+
+  fs.writeFileSync(destination, result, { encoding: 'utf8'});
+
+  fs.readFile('./demo/apiExamples.md', 'utf8', function(err, data) {
+    formatTemplateFileContents(data, './demo/apiExamples.md');
+  });
+}
+
+/**
+ * Compiles `./docTemplates/README.md` -> `./README.md`
+ */
+
+function processReadme() {
+  const callback = function(updatedContent, outputConfig) {
+
+    if (fs.existsSync('./README.md')) {
+      fs.readFile('./README.md', 'utf8', function(err, data) {
+        formatTemplateFileContents(data, './README.md');
+      });
+    } else {
+      console.log('ERROR: ./README.md file is missing');
+    }
+  };
+
+  const config = {
+    matchWord: 'AURO-GENERATED-CONTENT',
+    outputDir: './'
+  };
+
+  const markdownPath = path.join(__dirname, '../docTemplates/README.md');
+
+  markdownMagic(markdownPath, config, callback);
+}
+
+/**
+ * Compiles `./docTemplates/demo.md` -> `./demo/index.md`
+ */
+
+function processDemo() {
+  const callback = function(updatedContent, outputConfig) {
+    if (fs.existsSync('./demo/index.md')) {
+      fs.readFile('./demo/index.md', 'utf8', function(err, data) {
+        formatTemplateFileContents(data, './demo/index.md');
+      });
+    } else {
+      console.log('ERROR: ./demo/index.md file is missing');
+    }
+  };
+
+  const configDemo = {
+    matchWord: 'AURO-GENERATED-CONTENT',
+    outputDir: './demo'
+  };
+
+  const markdownPath = path.join(__dirname, '../docs/partials/index.md');
+
+  markdownMagic(markdownPath, configDemo, callback);
+}
+
+/**
+ * Compiles `./docTemplates/apiExamples.md` -> `./demo/apiExamples.md`
+ */
+
+function processApiExamples() {
+  const callback = function(updatedContent, outputConfig) {
+    if (fs.existsSync('./demo/apiExamples.md')) {
+      fs.readFile('./demo/apiExamples.md', 'utf8', function(err, data) {
+        formatApiTableContents(data, './demo/apiExamples.md');
+      });
+    } else {
+      console.log('ERROR: ./demo/apiExamples.md file is missing');
+    }
+  };
+
+  const config = {
+    matchWord: 'AURO-GENERATED-CONTENT',
+    outputDir: './demo'
+  };
+
+  const markdownPath = path.join(__dirname, '../docs/partials/apiExamples.md');
+
+  markdownMagic(markdownPath, config, callback);
+}
+
+/**
+ * Copy README.md template from static source
+ * */
+
+function copyReadmeLocally() {
+
+  if (!fs.existsSync(dirDocTemplates)){
+    fs.mkdirSync(dirDocTemplates);
+  }
+
+  if (!fs.existsSync(readmeFilePath)) {
+    fs.writeFile(readmeFilePath, '', function(err) {
+      if(err) {
+        console.log('ERROR: Unable to create README.md file.', err);
+      }
+    });
+  }
+
+  https.get(readmeTemplateUrl, function(response) {
+    let writeTemplate = response.pipe(fs.createWriteStream(readmeFilePath));
+
+    writeTemplate.on('finish', () => {
+      processReadme();
+    });
+
+  }).on('error', (err) => {
+    console.log('ERROR: Unable to fetch README.md file from server.', err);
+  });
+}
+
+/**
+ * Run all the actual document generation
+ */
+copyReadmeLocally();
+processApiExamples();
+processDemo();

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@aurodesignsystem-dev/auro-library",
+  "version": "0.0.0-pr187.0",
+  "description": "This repository holds shared scripts, utilities, and workflows utilized across repositories along the Auro Design System.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AlaskaAirlines/auro-library.git"
+  },
+  "main": "index.js",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": "^20.x || ^22.x"
+  },
+  "bin": {
+    "generateDocs": "./bin/generateDocs.mjs"
+  },
+  "devDependencies": {
+    "@aurodesignsystem/eslint-config": "1.3.4",
+    "@commitlint/cli": "^18.5.0",
+    "@commitlint/config-conventional": "^18.5.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^11.0.2",
+    "eslint": "^9.8.0",
+    "eslint-plugin-jsdoc": "^48.0.2",
+    "husky": "^8.0.3",
+    "semantic-release": "^23.0.0",
+    "vitest": "^2.1.2"
+  },
+  "release": {
+    "branches": [
+      {
+        "name": "main"
+      },
+      {
+        "name": "beta",
+        "prerelease": true
+      }
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      [
+        "@semantic-release/changelog",
+        {
+          "changelogFile": "./CHANGELOG.md",
+          "changelogTitle": "# Semantic Release Automated Changelog"
+        }
+      ],
+      "@semantic-release/npm",
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "./package.json",
+            "./CHANGELOG.md",
+            "./README.md",
+            "./docs/api.md"
+          ]
+        }
+      ],
+      "@semantic-release/github"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepare": "husky install",
+    "esLint": "eslint ./scripts/**/*.js",
+    "linters": "npm-run-all esLint",
+    "build:docs": "node scripts/build/generateReadme.mjs",
+    "test:vitest": "vitest  --run",
+    "test:vitest:watch": "vitest",
+    "test:auro": "auro test --files 'scripts/**/*.test.js'",
+    "test:auro:watch": "auro test --watch --files 'scripts/**/*.test.js'",
+    "test": "npm-run-all test:vitest test:auro",
+    "test:watch": "npm-run-all test:vitest:watch test:auro:watch"
+  },
+  "bugs": {
+    "url": "https://github.com/AlaskaAirlines/auro-library/issues"
+  },
+  "dependencies": {
+    "@aurodesignsystem/auro-cli": "^2.5.0",
+    "@floating-ui/dom": "^1.6.11",
+    "@open-wc/testing": "^4.0.0",
+    "handlebars": "^4.7.8",
+    "markdown-magic": "^2.6.1",
+    "npm-run-all": "^4.1.5",
+    "sinon": "^20.0.0"
+  }
+}

package/scripts/build/generateDocs.mjs

@@ -0,0 +1,24 @@
+// ------------------------------------------------------
+// Docs Generation
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+//
+// This script will generate the docs for the component
+// based on example HTML, markdown files, and more.
+//
+// The actions in this file live in:
+// scripts/build/processors/defaultDocsProcessor.mjs
+//
+// This script is intended to be run AS-IS without modification.
+// To run a different processor, please see the defaultDocsProcessor.mjs file
+// and re-create in your repo OR add a new processor file.
+// ------------------------------------------------------
+
+import {Logger} from "../utils/logger.mjs";
+import {processDocFiles} from "./processors/defaultDocsProcessor.mjs";
+
+processDocFiles().then(() => {
+  Logger.log('Docs processed successfully');
+}).
+  catch((err) => {
+    Logger.error(`Error processing docs: ${err.message}`);
+  });

package/scripts/build/generateReadme.mjs

@@ -0,0 +1,60 @@
+import markdownMagic from 'markdown-magic';
+import * as fs from 'fs';
+
+const dirDocs = './docs';
+const readmeFilePath = dirDocs + '/README.md';
+
+import AuroLibraryUtils from "../utils/auroLibraryUtils.mjs";
+
+const auroLibraryUtils = new AuroLibraryUtils();
+
+/**
+ * Compiles `./docs/README.md` -> `./README.md`
+ */
+
+function processReadme() {
+  const callback = function() {
+
+    if (fs.existsSync('./README.md')) {
+      fs.readFile('./README.md', 'utf8', function(err, data) {
+        auroLibraryUtils.formatFileContents(data, './README.md');
+      });
+    } else {
+      console.log('ERROR: ./README.md file is missing');
+    }
+  };
+
+  const config = {
+    matchWord: 'AURO-GENERATED-CONTENT',
+    outputDir: './'
+  };
+
+  const markdownPath = './docs/README.md';
+
+  markdownMagic(markdownPath, config, callback);
+
+  fs.copyFileSync(readmeFilePath, './README.md');
+}
+
+/**
+ * Copy README.md template from static source
+ * */
+
+function copyReadmeLocally() {
+
+  if (!fs.existsSync(dirDocs)){
+    fs.mkdirSync(dirDocs);
+  }
+
+  if (!fs.existsSync(readmeFilePath)) {
+    fs.writeFile(readmeFilePath, '', function(err) {
+      if(err) {
+        console.log('ERROR: Unable to create README.md file.', err);
+      }
+    });
+  }
+
+  processReadme();
+}
+
+copyReadmeLocally();

package/scripts/build/generateWcaComponent.mjs

@@ -0,0 +1,43 @@
+import fs from 'fs';
+import path from 'path';
+import glob from 'glob';
+import util from 'util';
+import getTemplatedComponentCode from './prepWcaCompatibleCode.mjs';
+
+const promisifiedGlob = util.promisify(glob);
+
+const WAC_DIR = path.resolve(process.cwd(), './scripts/wca');
+
+async function globPath(sources) {
+  try {
+    const fileArrays = await Promise.all(
+      sources.map(source => promisifiedGlob(source))
+    );
+    return fileArrays.flat();
+  } catch (err) {
+    console.error('Error processing glob patterns:', err);
+    throw err; // Re-throw to handle failure at caller
+  }
+}
+
+async function createExtendsFile(filePaths) {
+  if (!fs.existsSync(WAC_DIR)) {
+    await fs.promises.mkdir(WAC_DIR, { recursive: true });
+  }
+
+  for (const filePath of filePaths) {
+    const resolvedPath = path.resolve(process.cwd(), filePath);
+    const fileContent = await fs.promises.readFile(resolvedPath, 'utf-8',);
+    const newPath = path.resolve(WAC_DIR, `${path.basename(filePath)}`);
+    const newCode = getTemplatedComponentCode(fileContent, path.relative(WAC_DIR, filePath));
+    await fs.promises.writeFile(newPath, newCode);
+  }
+}
+
+async function main() {
+  // files to analyze
+  const filePaths = await globPath(process.argv.slice(2));
+  await createExtendsFile(filePaths);
+}
+
+main();

package/scripts/build/postCss.mjs

@@ -0,0 +1,66 @@
+/* eslint-disable brace-style, eqeqeq, object-property-newline, arrow-parens, array-element-newline, object-shorthand, dot-location, no-use-before-define, prefer-template, consistent-return, no-underscore-dangle, prefer-arrow-callback */
+
+import autoprefixer from 'autoprefixer';
+import postcss from 'postcss';
+import comments from 'postcss-discard-comments';
+import path from 'path';
+import fs from 'fs';
+import process from 'process';
+
+const __dirname = process.cwd();
+const directoryPath = path.join(__dirname, '/src');
+
+/**
+ * Default postCSS run
+ * Locates all CSS files within the directory and loop
+ * through the standardProcessor() function.
+ */
+fs.readdir(directoryPath, function (err, files) {
+  // handling error
+  if (err) {
+    return console.log('Unable to scan directory: ' + err); // eslint-disable-line no-console
+  }
+  // listing all files using forEach
+  files.forEach(function (file) {
+    if (file.includes(".css")) {
+      standardProcessor(file);
+    }
+  });
+});
+
+/**
+ * The standardProcessor function applies tokens for fallback selectors
+ * and completes a post cleanup.
+ * @param {string} file - The file to process.
+ */
+function standardProcessor(file) {
+  fs.readFile(`src/${file}`, (err, css) => {
+    postcss([autoprefixer, comments])
+      .use(comments({
+        remove: function(comment) { return comment[0] == "@"; }
+      }))
+      .process(css, { from: `src/${file}`, to: `src/${file}` })
+      .then(result => {
+        fs.writeFile(`src/${file}`, result.css, () => true);
+      });
+  });
+}
+
+/**
+ * ALTERNATE script:
+ * The following is a static builder for rendering one
+ * CSS file at a time if that is required.
+ */
+// fs.readFile('src/style.css', (err, css) => {
+//   postcss([autoprefixer, comments])
+//     .use(comments({
+//       remove: function(comment) { return comment[0] == "@"; }
+//     }))
+//     .process(css, { from: 'src/style.css', to: 'src/style.css' })
+//     .then(result => {
+//       fs.writeFile('src/style.css', result.css, () => true)
+//       if ( result.map ) {
+//         fs.writeFile('src/style.map', result.map, () => true)
+//       }
+//     })
+// });

package/scripts/build/postinstall.mjs

@@ -0,0 +1,31 @@
+'use strict';
+
+import chalk from 'chalk';
+import { createRequire } from 'node:module';
+import { resolve } from 'path';
+
+
+const require = createRequire(import.meta.url);
+const pjson = require(resolve(process.cwd(), 'package.json'));
+
+console.log(chalk.hex('#f26135')(`
+
+ _______                   __           __ __
+|     __|.---.-.--.--.    |  |--.-----.|  |  |.-----.
+|__     ||  _  |  |  |    |     |  -__||  |  ||  _  |
+|_______||___._|___  |    |__|__|_____||__|__||_____|
+               |_____|
+ __              _______                    __
+|  |_.-----.    |   _   |.--.--.----.-----.|  |
+|   _|  _  |    |       ||  |  |   _|  _  ||__|
+|____|_____|    |___|___||_____|__| |_____||__|
+
+
+╭ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ──────────────────────────────╮
+
+        Thanks for installing the latest version
+        of `) + chalk.hex('#ffd200').bold(`${pjson.name} v${pjson.version}.`) + chalk.hex('#f26135')(`
+
+╰─────────────────────────────── ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─╯
+`)
+);

package/scripts/build/pre-commit.mjs

@@ -0,0 +1,17 @@
+/* eslint-disable no-console */
+
+import chalk from 'chalk';
+
+console.log(chalk.hex('#ffd200')(`
+
+╭ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ──────────────────────────────╮`) + chalk.hex('#f26135')(`
+
+    Are you familiar with Auro's Definition of Done?
+
+                Please be sure to review`) + chalk.hex('#ffd200')(`
+      https://auro.alaskaair.com/definition-of-done`) + chalk.hex('#f26135')(`
+            before submitting your pull request
+             to ensure that you are compliant.`) + chalk.hex('#ffd200')(`
+
+╰─────────────────────────────── ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─╯
+`));

package/scripts/build/prepWcaCompatibleCode.mjs

@@ -0,0 +1,19 @@
+export default (code, sourcePath) => {
+  const defaultTag = (code.match(/static register\(name \= (.+)\)/) || code.match(/customElements.get\((.+?)\)/))[1];
+  const className = code.match(/export class (.+) extends/)?.[1];
+  const classDesc = code.match(/\/\*\*((.|\n)*?)(\*\n|\*\/|[@])/)?.[1] || '';
+
+  if (!defaultTag || !className) {
+    return code;
+  }
+  return `
+import { ${className} } from '${sourcePath}';
+
+/**${classDesc}*/
+class ${className}WCA extends ${className} {}
+
+if (!customElements.get(${defaultTag})) {
+  customElements.define(${defaultTag}, ${className}WCA);
+}
+`;
+};

package/scripts/build/processors/defaultDocsProcessor.mjs

@@ -0,0 +1,83 @@
+import {Logger} from "../../utils/logger.mjs";
+import {
+  fromAuroComponentRoot,
+  generateReadmeUrl,
+  processContentForFile,
+  templateFiller
+} from "../../utils/sharedFileProcessorUtils.mjs";
+
+/**
+ * Processor config object.
+ * @typedef {Object} ProcessorConfig
+ * @property {boolean} [overwriteLocalCopies=true] - The release version tag to use instead of master.
+ * @property {string} [remoteReadmeVersion="master"] - The release version tag to use instead of master.
+ * @property {string} [remoteReadmeVariant=""] - The variant string to use for the README source.
+ * (like "_esm" to make README_esm.md).
+ */
+
+
+/**
+ * @param {ProcessorConfig} config - The configuration for this processor.
+ */
+export const defaultDocsProcessorConfig = {
+  overwriteLocalCopies: true,
+  remoteReadmeVersion: "master",
+  // eslint-disable-next-line no-warning-comments
+  // TODO: remove this variant when all components are updated to use latest auro-library
+  // AND the default README.md is updated to use the new paths
+  remoteReadmeVariant: "_updated_paths"
+};
+
+/**
+ * @param {ProcessorConfig} config - The configuration for this processor.
+ * @returns {import('../utils/sharedFileProcessorUtils').FileProcessorConfig[]}
+ */
+export const fileConfigs = (config) => [
+  // README.md
+  {
+    identifier: 'README.md',
+    input: {
+      remoteUrl: generateReadmeUrl(config.remoteReadmeVersion, config.remoteReadmeVariant),
+      fileName: fromAuroComponentRoot(`/docTemplates/README.md`),
+      overwrite: config.overwriteLocalCopies
+    },
+    output: fromAuroComponentRoot("/README.md")
+  },
+  // index.md
+  {
+    identifier: 'index.md',
+    input: fromAuroComponentRoot("/docs/partials/index.md"),
+    output: fromAuroComponentRoot("/demo/index.md"),
+    mdMagicConfig: {
+      output: {
+        directory: fromAuroComponentRoot("/demo")
+      }
+    }
+  },
+  // api.md
+  {
+    identifier: 'api.md',
+    input: fromAuroComponentRoot("/docs/partials/api.md"),
+    output: fromAuroComponentRoot("/demo/api.md"),
+    preProcessors: [templateFiller.formatApiTable],
+  }
+];
+
+/**
+ *
+ * @param {ProcessorConfig} config - The configuration for this processor.
+ * @return {Promise<void>}
+ */
+export async function processDocFiles(config = defaultDocsProcessorConfig) {
+  // setup
+  await templateFiller.extractNames();
+
+  for (const fileConfig of fileConfigs(config)) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await processContentForFile(fileConfig);
+    } catch (err) {
+      Logger.error(`Error processing ${fileConfig.identifier}: ${err.message}`);
+    }
+  }
+}