@aurodesignsystem/auro-library 2.7.0 → 2.9.0

package/.tool-versions

@@ -0,0 +1 @@
+nodejs 20.12.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Semantic Release Automated Changelog
 
+# [2.9.0](https://github.com/AlaskaAirlines/auro-library/compare/v2.8.0...v2.9.0) (2024-10-07)
+
+
+### Bug Fixes
+
+* add matchWord to md magic config ([372cb28](https://github.com/AlaskaAirlines/auro-library/commit/372cb28a1c9eb0bd5f1014a4a8a9e6415cf659e5))
+
+
+### Features
+
+* add handlebars template support ([bc3851d](https://github.com/AlaskaAirlines/auro-library/commit/bc3851dd87eb907927a3e2e22de53013c5e4e958))
+* add new processing paradigm ([9a1dd25](https://github.com/AlaskaAirlines/auro-library/commit/9a1dd254e1288a6c7873b145a62087a37233a641))
+
+# [2.8.0](https://github.com/AlaskaAirlines/auro-library/compare/v2.7.0...v2.8.0) (2024-09-19)
+
+
+### Features
+
+* add runtime script for Floating UI [#65](https://github.com/AlaskaAirlines/auro-library/issues/65) ([e180fcb](https://github.com/AlaskaAirlines/auro-library/commit/e180fcb319e9ab6673765041b5a96057e562bd60))
+
 # [2.7.0](https://github.com/AlaskaAirlines/auro-library/compare/v2.6.3...v2.7.0) (2024-08-21)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurodesignsystem/auro-library",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "This repository holds shared scripts, utilities, and workflows utilized across repositories along the Auro Design System.",
   "repository": {
     "type": "git",
@@ -74,6 +74,7 @@
     "url": "https://github.com/AlaskaAirlines/auro-library/issues"
   },
   "dependencies": {
+    "handlebars": "^4.7.8",
     "markdown-magic": "^2.6.1",
     "npm-run-all": "^4.1.5"
   }

package/scripts/build/auroFileHandler.mjs

@@ -0,0 +1,67 @@
+import fs from 'node:fs/promises';
+
+import {Logger} from "../utils/logger.mjs";
+
+export class AuroFileHandler {
+
+  /**
+   * Check if a file exists.
+   * @param {string} filePath - The file path to check.
+   * @returns {Promise<boolean>}
+   */
+  static async exists(filePath) {
+    try {
+      await fs.access(filePath);
+      return true;
+      // eslint-disable-next-line no-unused-vars
+    } catch (_err) {
+      return false;
+    }
+  }
+
+  /**
+   * Try to read a file and return its contents.
+   * @param {string} filePath - The file path to read.
+   * @returns {Promise<null|string>}
+   */
+  static async tryReadFile(filePath) {
+    try {
+      return await fs.readFile(filePath, {encoding: 'utf-8'});
+    } catch (err) {
+      Logger.error(`Error reading file: ${filePath}, ${err.message}`);
+      return null;
+    }
+  }
+
+  /**
+   * Try to write a file with the given contents.
+   * @param {string} filePath - The file path to write to.
+   * @param {string} fileContents - The contents to write to the file.
+   * @returns {Promise<boolean>}
+   */
+  static async tryWriteFile(filePath, fileContents) {
+    try {
+      await fs.writeFile(filePath, fileContents, {encoding: 'utf-8'});
+      return true;
+    } catch (err) {
+      Logger.error(`Error writing file: ${filePath}, ${err.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Try to copy a file from one location to another.
+   * @param {string} source - The source file path.
+   * @param {string} destination - The destination file path.
+   * @returns {Promise<boolean>}
+   */
+  static async tryCopyFile(source, destination) {
+    try {
+      await fs.copyFile(source, destination);
+      return true;
+    } catch (err) {
+      Logger.error(`Error copying file: ${source}, ${err.message}`);
+      return false;
+    }
+  }
+}

package/scripts/build/auroTemplateFiller.mjs

@@ -0,0 +1,169 @@
+// eslint-disable
+import Handlebars from "handlebars"
+import fs from "node:fs/promises";
+
+// declare package.json type with jsdoc
+/**
+ * @typedef {Object} ExamplePackageJson
+ * @property {string} name - Name of the package.
+ * @property {string} version - Version of the package.
+ * @property {Record<string, string>} peerDependencies - Peer dependencies of the package.
+ */
+
+// declare extracted names type with jsdoc
+/**
+ * @typedef {Object} ExtractedNames
+ * @property {string} npm - NPM of the package.
+ * @property {string} namespace - Namespace of the package.
+ * @property {string} namespaceCap - Capitalized namespace of the package.
+ * @property {string} name - Name of the package.
+ * @property {string} nameCap - Capitalized name of the package.
+ * @property {string} version - Version of the package.
+ * @property {string} tokensVersion - Version of the design tokens.
+ * @property {string} wcssVersion - Version of the webcorestylesheets.
+ */
+
+
+export class AuroTemplateFiller {
+  static designTokenPackage = '@aurodesignsystem/design-tokens';
+  static webCoreStylesheetsPackage = '@aurodesignsystem/webcorestylesheets';
+
+  constructor () {
+    /** @type {ExtractedNames} */
+    this.values = null;
+  }
+
+  async prepare() {
+    await this.extractNames()
+  }
+
+  /**
+   * Extract various data for filling template files from the package.json file.
+   * @returns {Promise<ExtractedNames>}
+   */
+  async extractNames() {
+    const packageJsonData = await fs.readFile('package.json', 'utf8');
+
+    /** @type {ExamplePackageJson} */
+    const parsedPackageJson = JSON.parse(packageJsonData);
+
+    const pName = parsedPackageJson.name;
+    const pVersion = parsedPackageJson.version;
+    const pdtVersion = parsedPackageJson.peerDependencies[AuroTemplateFiller.designTokenPackage].substring(1);
+    const wcssVersion = parsedPackageJson.peerDependencies[AuroTemplateFiller.webCoreStylesheetsPackage].substring(1);
+
+    const npmStart = pName.indexOf('@');
+    const namespaceStart = pName.indexOf('/');
+    const nameStart = pName.indexOf('-');
+
+    this.values = {
+      '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
+    };
+  }
+
+  /**
+   * @param {string} template
+   * @param {ExtractedNames} values
+   * @return {string}
+   */
+  replaceTemplateValues(template) {
+    const compileResult = Handlebars.compile(template);
+
+    // replace all handlebars placeholders FIRST, then apply legacy replacements
+    let result = compileResult({
+      // TODO: consider replacing some of these with handlebars helpers
+      name: this.values.name,
+      Name: this.values.nameCap,
+      namespace: this.values.namespace,
+      Namespace: this.values.namespaceCap,
+      Version: this.values.version,
+      dtVersion: this.values.tokensVersion,
+      wcssVersion: this.values.wcssVersion
+    }, {
+      helpers: {
+        'capitalize': (str) => str.charAt(0).toUpperCase() + str.slice(1),
+        'withAuroNamespace': (str) => `auro-${str}`,
+      }
+    })
+
+    /**
+     * Old legacy template variables. We used to use `[varName]` and are now using handlebars `{{varName}}`.
+     * @type {[{pattern: RegExp, replacement: string},{pattern: RegExp, replacement: string},{pattern: RegExp, replacement: string},{pattern: RegExp, replacement: string},{pattern: RegExp, replacement: string},null,null,null]}
+     */
+    const legacyTemplateVariables = [
+      {
+        pattern: /\[npm\]/gu,
+        replacement: this.values.npm
+      },
+      {
+        pattern: /\[name\](?!\()/gu,
+        replacement: this.values.name
+      },
+      {
+        pattern: /\[Name\](?!\()/gu,
+        replacement: this.values.nameCap
+      },
+      {
+        pattern: /\[namespace\]/gu,
+        replacement: this.values.namespace
+      },
+      {
+        pattern: /\[Namespace\]/gu,
+        replacement: this.values.namespaceCap
+      },
+      {
+        pattern: /\[Version\]/gu,
+        replacement: this.values.version
+      },
+      {
+        pattern: /\[dtVersion\]/gu,
+        replacement: this.values.tokensVersion
+      },
+      {
+        pattern: /\[wcssVersion\]/gu,
+        replacement: this.values.wcssVersion
+      }
+    ];
+
+    /**
+     * Replace legacy placeholder strings.
+     */
+    for (const { pattern, replacement } of legacyTemplateVariables) {
+      result = result.replace(pattern, replacement);
+    }
+
+    /**
+     * 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.
+
+    return result;
+  }
+
+
+  /**
+   *
+   * @param {string} content
+   */
+  formatApiTable(content) {
+    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, "");
+
+    return result
+  }
+}

package/scripts/build/generateDocs.mjs

@@ -1,229 +1,275 @@
 import path from 'path';
-import markdownMagic from 'markdown-magic';
-import fs from 'fs';
-import https from 'https';
+import * as mdMagic from 'markdown-magic';
+import fs from 'node:fs/promises';
 import { fileURLToPath } from 'url';
 
 import AuroLibraryUtils from "../utils/auroLibraryUtils.mjs";
+import { AuroTemplateFiller } from "./auroTemplateFiller.mjs";
+import { AuroFileHandler } from "./auroFileHandler.mjs";
+import {Logger} from "../utils/logger.mjs";
 
-const auroLibraryUtils = new AuroLibraryUtils();
 
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
+// This JSDoc type trickery is here so you get "decent enough" auto complete
+/** @type {typeof import('markdown-magic').markdownMagic} */
+const applyMarkdownMagic = mdMagic.default
 
-const dirDocTemplates = './docTemplates';
-const readmeFilePath = dirDocTemplates + '/README.md';
+/**
+ * Optional output configuration
+ * @typedef  {object}   OutputConfig
+ * @property {string}   [directory] - Change output path of new content. Default behavior is replacing the original file
+ * @property {boolean}  [removeComments = false] - Remove comments from output. Default is false.
+ * @property {function} [pathFormatter] - Custom function for altering output paths
+ * @property {boolean}  [applyTransformsToSource = false] - Apply transforms to source file. Default is true. This is for when outputDir is set.
+ */
 
-// List of components that do not support ESM to determine which README to use
-const nonEsmComponents = ['combobox', 'datepicker', 'menu', 'pane', 'select'];
+/**
+ * Configuration for markdown magic
+ *
+ * Below is the main config for `markdown-magic` - copy-pasted directly from the library
+ *
+ * @typedef {object} MarkdownMagicOptions
+ * @property {FilePathsOrGlobs} [files] - Files to process.
+ * @property {Array} [transforms = defaultTransforms] - Custom commands to transform block contents, see transforms & custom transforms sections below.
+ * @property {OutputConfig} [output] - Output configuration
+ * @property {SyntaxType} [syntax = 'md'] - Syntax to parse
+ * @property {string} [open = 'doc-gen'] - Opening match word
+ * @property {string} [close = 'end-doc-gen'] - Closing match word. If not defined will be same as opening word.
+ * @property {string} [cwd = process.cwd() ] - Current working directory. Default process.cwd()
+ * @property {boolean} [outputFlatten] - Flatten files that are output
+ * @property {boolean} [useGitGlob] - Use git glob for LARGE file directories
+ * @property {boolean} [dryRun = false] - See planned execution of matched blocks
+ * @property {boolean} [debug = false] - See debug details
+ * @property {boolean} [silent = false] - Silence all console output
+ * @property {boolean} [applyTransformsToSource = true] - Apply transforms to source file. Default is true.
+ * @property {boolean} [failOnMissingTransforms = false] - Fail if transform functions are missing. Default skip blocks.
+ * @property {boolean} [failOnMissingRemote = true] - Fail if remote file is missing.
+ */
 
-function generateReadmeUrl() {
-  let nameExtractionData = nameExtraction();
-  let esmString = '';
 
-  if (!nonEsmComponents.includes(nameExtractionData.name)) {
-    esmString = '_esm';
+// Config
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+/** @type {MarkdownMagicOptions} */
+export const MD_MAGIC_CONFIG = {
+  matchWord: "AURO-GENERATED-CONTENT",
+  output: {
+    directory: "./",
+    applyTransformsToSource: true
   }
+};
+
+// Initialize utility services
+export const auroLibraryUtils = new AuroLibraryUtils();
+export const templateFiller = new AuroTemplateFiller();
+export const auroFileHandler = new AuroFileHandler();
+
+// List of components that do not support ESM to determine which README to use
+export const nonEsmComponents = ['combobox', 'datepicker', 'menu', 'pane', 'select'];
 
-  return 'https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator/master/componentDocs/README' + esmString + '.md';
-}
 
+// Local utils
 /**
- * Extract NPM, NAMESPACE and NAME from package.json
+ *
+ * @param {string} pathLike - Please include the preceding slash! Like so: `/docTemplates/README.md`
+ * @return {string}
  */
+export function fromAuroComponentRoot(pathLike) {
+  const currentDir = fileURLToPath(new URL('.', import.meta.url))
+  return path.join(currentDir, `${auroLibraryUtils.projectRootFromBuildScriptDir}${pathLike}`)
+}
 
-function nameExtraction() {
-  let packageJson = fs.readFileSync('package.json', 'utf8', function(err, data) {
-    if (err) {
-      console.log('ERROR: Unable to read package.json file', err);
-    }
-  })
 
-  packageJson = JSON.parse(packageJson);
-  
-  let pName = packageJson.name;
-  let pVersion = packageJson.version;
-  let pdtVersion = packageJson.peerDependencies['\@aurodesignsystem/design-tokens'].substring(1);
-  let wcssVersion = packageJson.peerDependencies['\@aurodesignsystem/webcorestylesheets'].substring(1);
-
-  let npmStart = pName.indexOf('@');
-  let namespaceStart = pName.indexOf('/');
-  let nameStart = pName.indexOf('-');
-
-  return {
-    '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
-  };
-}
+// External assets
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 /**
- * Replace all instances of [npm], [name], [Name], [namespace] and [Namespace] accordingly
+ * @param {string} tag - the release version tag to use instead of master
+ * @param {string} [variantOverride] - override the variant string
+ * @return {string}
  */
+export function generateReadmeUrl(tag = 'master', variantOverride = '') {
+  // LEGACY CODE FOR NON-ESM COMPONENTS
 
-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'});
-}
+  const nameExtractionData = templateFiller.values;
+  let variantString = '';
 
-function formatApiTableContents(content, destination) {
-  const nameExtractionData = nameExtraction();
-  const wcName = nameExtractionData.namespace + '-' + nameExtractionData.name;
+  if (!nonEsmComponents.includes(nameExtractionData.name)) {
+    variantString = '_esm';
+  }
 
-  let result = content;
+  // END LEGACY CODE
 
-  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, "");
+  if (variantOverride !== '') {
+    variantString = variantOverride;
+  }
 
-  fs.writeFileSync(destination, result, { encoding: 'utf8'});
+  const baseRepoUrl = 'https://raw.githubusercontent.com/AlaskaAirlines/WC-Generator'
+  if (tag !== 'master') {
+    return `${baseRepoUrl}/refs/tags/${tag}/componentDocs/README` + variantString + '.md';
+  }
 
-  fs.readFile('./demo/api.md', 'utf8', function(err, data) {
-    formatTemplateFileContents(data, './demo/api.md');
-  });
+  return `${baseRepoUrl}/master/componentDocs/README` + variantString + '.md';
 }
 
+// Main Markdown magic processors
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 /**
- * Compiles `./docTemplates/README.md` -> `./README.md`
+ * This is the expected object type when passing something other than a string.
+ * @typedef {Object} InputFileType
+ * @property {string} remoteUrl - The remote template to fetch
+ * @property {string} fileName - Path including file name to store
+ * @property {boolean} [overwrite] - Default is true. Choose to overwrite the file if it exists
  */
 
-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: './'
-  };
+/**
+ * @typedef {Object} FileProcessorConfig
+ * @property {string | InputFileType} input - path to input file, including filename
+ * @property {string} output - path to output file, including filename
+ * @property {Partial<MarkdownMagicOptions>} [mdMagicConfig] - extra configuration options for md magic
+ * @property {Array<(contents: string) => string>} [postProcessors] - extra processor functions to run on content
+ */
 
-  const markdownPath = path.join(__dirname, './../../../../../docTemplates/README.md');
 
-  markdownMagic(markdownPath, config, callback);
-}
+// Individual file processing steps
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 /**
- * Compiles `./docTemplates/index.md` -> `./demo/index.md`
+ * Optionally retrieve a remote file using a provided configuration.
+ * @param {InputFileType} input - the input file configuration
+ * @return {Promise<void>}
  */
+export async function optionallyRetrieveRemoteFile(input) {
+  const bareFileName = input.fileName
+  const shouldOverwrite = input.overwrite ?? true
 
-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');
-        auroLibraryUtils.formatFileContents(data, './demo/index.md');
-      });
-    } else {
-      console.log('ERROR: ./demo/index.md file is missing');
-    }
-  };
+  // If the file exists and overwrite is false, skip fetching
+  if (await AuroFileHandler.exists(input.fileName) && !shouldOverwrite) {
+    Logger.warn(`NOTICE: Using existing "${bareFileName}" file since overwrite is FALSE`);
+
+    return;
+  }
 
-  const configDemo = {
-    matchWord: 'AURO-GENERATED-CONTENT',
-    outputDir: './demo'
-  };
+  Logger.log(`Retrieving latest "${bareFileName}" file...`);
 
-  const markdownPath = path.join(__dirname, './../../../../../docs/partials/index.md');
+  // 0b. Attempt to populate from remote file
+  const contents = await fetch(input.remoteUrl, {
+    redirect: 'follow'
+  }).then(r => r.text());
 
-  markdownMagic(markdownPath, configDemo, callback);
+  // 0c. Write remote contents to local folder as cache
+  await AuroFileHandler.tryWriteFile(input.fileName, contents);
 }
 
+
 /**
- * Compiles `./docTemplates/api.md` -> `./demo/api.md`
+ * Run markdown magic on a file.
+ * @param {string} input
+ * @param {string} output
+ * @param {Partial<MarkdownMagicOptions>} [extraMdMagicConfig] - extra configuration options for md magic
+ * @return {Promise<void>}
  */
+export async function runMarkdownMagicOnFile(input, output, extraMdMagicConfig = {}) {
+  await applyMarkdownMagic(output, {
+    ...MD_MAGIC_CONFIG,
+    ...extraMdMagicConfig
+  });
+}
 
-function processApiExamples() {
-  const callback = function(updatedContent, outputConfig) {
-    if (fs.existsSync('./demo/api.md')) {
-      fs.readFile('./demo/api.md', 'utf8', function(err, data) {
-        formatApiTableContents(data, './demo/api.md');
-      });
-    } else {
-      console.log('ERROR: ./demo/api.md file is missing');
-    }
-  };
-
-  const config = {
-    matchWord: 'AURO-GENERATED-CONTENT',
-    outputDir: './demo'
-  };
 
-  const markdownPath = path.join(__dirname, './../../../../../docs/partials/api.md');
+/**
+ * Process the content of a file.
+ *
+ * This is a high level function that performs the following via lower functions:
+ * - Read contents of file
+ * - Run "markdown-magic" on file contents (optional, *.md specific)
+ * - Run template variable replacement on file contents
+ * @param {FileProcessorConfig} config - the config for this file
+ */
+export async function processContentForFile(config) {
+  const { input: rawInput, output, mdMagicConfig } = config
 
-  markdownMagic(markdownPath, config, callback);
-}
+  // Helper vars
+  const derivedInputPath = typeof rawInput === 'string' ? rawInput : rawInput.fileName;
+  const segments = derivedInputPath.split("/")
+  const bareFileName = segments[segments.length - 1]
 
-/**
- * Copy README.md template from static source
- * */
+  // 0. Optionally retrieve a remote file
+  if (typeof rawInput === 'object') {
+    await optionallyRetrieveRemoteFile(rawInput);
+  }
 
-function copyReadmeLocally() {
-  if (!fs.existsSync(dirDocTemplates)){
-    fs.mkdirSync(dirDocTemplates);
+  // 1. Copy input or local input cache to output
+  if (!await AuroFileHandler.tryCopyFile(derivedInputPath, output)) {
+    throw new Error(`Error copying "${bareFileName}" file to output ${output}`);
   }
 
-  if (!fs.existsSync(readmeFilePath)) {
-    fs.writeFile(readmeFilePath, '', function(err) {
-      if(err) {
-        console.log('ERROR: Unable to create README.md file.', err);
-      }
-    });
+  // 2. If the file is a Markdown file, run markdown magic to inject contents and perform replacements
+  if (output.endsWith(".md")) {
+    await runMarkdownMagicOnFile(derivedInputPath, output, mdMagicConfig);
   }
 
-  https.get(generateReadmeUrl(), function(response) {
-    let writeTemplate = response.pipe(fs.createWriteStream(readmeFilePath));
+  // 3a. Read the output file contents
+  let fileContents = await fs.readFile(output, {encoding: 'utf-8'});
 
-    writeTemplate.on('finish', () => {
-      processReadme();
-    });
+  // 3b. Replace template variables in output file
+  fileContents = templateFiller.replaceTemplateValues(fileContents);
 
-  }).on('error', (err) => {
-    console.log('ERROR: Unable to fetch README.md file from server.', err);
-  });
+  // 3c. Run any post-processors
+  if (config.postProcessors) {
+    for (const processor of config.postProcessors) {
+      fileContents = processor(fileContents)
+    }
+  }
+
+  // 3d. Write the final file contents
+  if (!await AuroFileHandler.tryWriteFile(output, fileContents)) {
+    throw new Error(`Error writing "${bareFileName}" file to output ${output}`);
+  }
 }
 
+// Finally, the main function
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 /**
- * Run all the actual document generation
+ *
+ * @param {string} remoteReadmeVersion - the release version tag to use instead of master
+ * @param {string} [readmeVariant] - the release version tag to use instead of master
+ * @return {Promise<void>}
  */
-copyReadmeLocally();
-processApiExamples();
-processDemo();
+export async function processDocFiles(remoteReadmeVersion = 'master', readmeVariant = undefined) {
+  // setup
+  await templateFiller.extractNames();
+
+  // process
+  // README.md
+
+  await processContentForFile({
+    input: {
+      remoteUrl: generateReadmeUrl(remoteReadmeVersion, readmeVariant),
+      fileName: fromAuroComponentRoot(`/docTemplates/README.md`),
+    },
+    output: fromAuroComponentRoot("/README.md")
+  })
 
+  // Demo MD file
+  await processContentForFile({
+    input: fromAuroComponentRoot("/docs/partials/index.md"),
+    output: fromAuroComponentRoot("/demo/index.md"),
+    mdMagicConfig: {
+      output: {
+        directory: fromAuroComponentRoot("/demo")
+      }
+    }
+  })
+
+  // API MD file
+  await processContentForFile({
+    input: fromAuroComponentRoot("/docs/partials/api.md"),
+    output: fromAuroComponentRoot("/demo/api.md"),
+    postProcessors: [
+      templateFiller.formatApiTable
+    ]
+  })
+}

package/scripts/runtime/floatingUI.mjs

@@ -0,0 +1,141 @@
+/* eslint-disable line-comment-position, no-inline-comments */
+
+import {computePosition, offset, autoPlacement, flip} from '@floating-ui/dom';
+
+export default class AuroFloatingUI {
+  bibUpdate(element) {
+    this.position(element, element.trigger, element.bib);
+  }
+
+  position(element, referenceEl, floatingEl) {
+    const middleware = [offset(element.floaterConfig.offset || 0)];
+
+    if (element.floaterConfig.flip) {
+      middleware.push(flip());
+    }
+
+    if (element.floaterConfig.autoPlacement) {
+      middleware.push(autoPlacement());
+    }
+
+    computePosition(referenceEl, floatingEl, {
+      placement: element.floaterConfig.placement || 'bottom',
+      middleware: middleware || []
+    }).then(({x, y}) => { // eslint-disable-line id-length
+      Object.assign(floatingEl.style, {
+        left: `${x}px`,
+        top: `${y}px`,
+      });
+    });
+  }
+
+  showBib(element) {
+    if (!element.disabled && !element.isPopoverVisible) {
+      // First, close any other dropdown that is already open
+      if (document.expandedAuroDropdown) {
+        // document.expandedAuroDropdown.hideBib();
+        this.hideBib(document.expandedAuroDropdown);
+      }
+
+      document.expandedAuroDropdown = this;
+
+      // Then, show this dropdown
+      element.bib.style.display = 'block';
+      this.bibUpdate(element);
+      element.isPopoverVisible = true; // does Floating UI already surface this?
+      element.trigger.setAttribute('aria-expanded', true);
+
+      // wrap this so we can clean it up when the bib is hidden
+      // document.querySelector('body').addEventListener('click', (evt) => {
+      //   if (!evt.composedPath().includes(this)) {
+      //     this.hideBib();
+      //   }
+      // });
+      if (!element.noHideOnThisFocusLoss && !element.hasAttribute('noHideOnThisFocusLoss')) {
+        document.activeElement.addEventListener('focusout', () => {
+          if (document.activeElement !== document.querySelector('body') && !element.contains(document.activeElement)) {
+            this.hideBib(element);
+          }
+        });
+
+        document.querySelector('body').addEventListener('click', (evt) => {
+          if (!evt.composedPath().includes(element)) {
+            this.hideBib(element);
+          }
+        });
+      }
+    }
+  }
+
+  hideBib(element) {
+    if (element.isPopoverVisible && !element.disabled && !element.noToggle) { // do we really want noToggle here?
+      element.bib.style.display = ''; // should this be unset or none?
+      element.isPopoverVisible = false;
+      element.trigger.setAttribute('aria-expanded', false);
+    }
+  }
+
+  configure(element) {
+    element.trigger = element.shadowRoot.querySelector('#trigger');
+    element.bib = element.shadowRoot.querySelector('#bib');
+
+    element.trigger.addEventListener('click', (event) => this.handleEvent(event, element));
+    element.trigger.addEventListener('mouseenter', (event) => this.handleEvent(event, element));
+    element.trigger.addEventListener('mouseleave', (event) => this.handleEvent(event, element));
+    element.trigger.addEventListener('focus', (event) => this.handleEvent(event, element));
+    element.trigger.addEventListener('blur', (event) => this.handleEvent(event, element));
+  }
+
+  handleClick(element) {
+    if (this.isPopoverVisible) {
+      this.hideBib(element);
+    } else {
+      this.showBib(element);
+    }
+
+    // should this be left in dropdown?
+    const event = new CustomEvent('auroDropdown-triggerClick', {
+      composed: true,
+      details: {
+        expanded: this.isPopoverVisible
+      }
+    });
+
+    element.dispatchEvent(event);
+  }
+
+  handleEvent(event, element) {
+    if (!element.disableEventShow) {
+      switch (event.type) {
+        case 'mouseenter':
+          if (element.hoverToggle) {
+            this.showBib(element);
+          }
+          break;
+        case 'mouseleave':
+          if (element.hoverToggle) {
+            this.hideBib(element);
+          }
+          break;
+        case 'focus':
+          if (element.focusShow) {
+            // this needs to better handle clicking that gives focus - currently it shows and then immediately hides the bib
+            this.showBib(element);
+          }
+          break;
+        case 'blur':
+          // this likely needs to be improved to handle focus within the bib for datepicker
+          if (!element.noHideOnThisFocusLoss && !element.hasAttribute('noHideOnThisFocusLoss')) { // why do we have to do both here?
+            this.hideBib(element);
+          }
+          break;
+        case 'click':
+          this.handleClick(element);
+          break;
+        default:
+          // do nothing
+        // add cases for show and toggle by keyboard space and enter key - maybe this is handled already?
+      }
+    }
+  }
+}

package/scripts/utils/auroLibraryUtils.mjs

@@ -6,10 +6,16 @@
 /* eslint-disable arrow-parens, line-comment-position, no-console, no-inline-comments, no-magic-numbers, prefer-arrow-callback, require-unicode-regexp, jsdoc/require-description-complete-sentence, prefer-named-capture-group */
 
 import * as fs from 'fs';
+import fsAsync from 'node:fs/promises';
 import * as path from 'path';
 import chalk from 'chalk';
 
 export default class AuroLibraryUtils {
+  PROJECT_ROOT_FROM_SCRIPTS__BUILD = "./../../../../.."
+
+  get projectRootFromBuildScriptDir() {
+    return this.PROJECT_ROOT_FROM_SCRIPTS__BUILD
+  }
 
   /**
    * Copies and pastes all files in a source directory into a destination directory.
@@ -73,7 +79,7 @@ export default class AuroLibraryUtils {
   /**
    * Logs out messages in a readable format.
    * @param {String} message - Message to be logged.
-   * @param {String} status - Status that determines the color of the logged message.
+   * @param {"info" | "success" | "error"} status - Status that determines the color of the logged message.
    * @param {Boolean} section - If true, adds a box around the message for readability.
    */
   auroLogger(message, status, section) {
@@ -185,5 +191,19 @@ export default class AuroLibraryUtils {
      */
     fs.writeFileSync(destination, result, { encoding: 'utf8'});
   }
+
+  /**
+   * Check if a file or directory exists.
+   * @param filePath
+   * @return {Promise<boolean>}
+   */
+  async existsAsync(filePath) {
+    try {
+      await fsAsync.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
 }
 

package/scripts/utils/logger.js

@@ -0,0 +1,73 @@
+/* eslint-disable no-inline-comments, no-console, line-comment-position */
+
+import chalk from 'chalk';
+
+export class Logger {
+
+  /**
+   * Logs out messages in a readable format.
+   * @param {String} message - Message to be logged.
+   * @param {false | "info" | "success" | "error" | "warn"} status - Status that determines the color of the logged message.
+   * @param {Boolean} section - If true, adds a box around the message for readability.
+   */
+  static auroLogger(message, status, section) {
+    if (status !== false) {
+      const infoColor = '#0096FF'; // blue
+      const successColor = '#4CBB17'; // green
+      const errorColor = '#ff0000'; // red
+      const warningColor = '#FFA500'; // orange
+
+      let color = undefined; // eslint-disable-line no-undef-init
+
+      if (status === 'info') {
+        color = infoColor;
+      } else if (status === 'success') {
+        color = successColor;
+      } else if (status === 'error') {
+        color = errorColor;
+      } else if (status === 'warn') {
+        color = warningColor;
+      }
+
+      if (section) {
+        console.log(chalk.hex(color)(`╭ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ──────────────────────────────╮\n`));
+      }
+
+      console.log(chalk.hex(color)(message));
+
+      if (section) {
+        console.log(chalk.hex(color)('\n╰─────────────────────────────── ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─╯'));
+      }
+    } else {
+      if (section) {
+        console.log(`╭ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ──────────────────────────────╮\n`);
+      }
+
+      console.log(message);
+
+      if (section) {
+        console.log(`\n╰─────────────────────────────── ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─╯`);
+      }
+    }
+  }
+
+  static log(message, section = false) {
+    Logger.auroLogger(message, false, section);
+  }
+
+  static info(message, section = false) {
+    Logger.auroLogger(message, "info", section);
+  }
+
+  static warn(message, section = false) {
+    Logger.auroLogger(message, "warn", section);
+  }
+
+  static success(message, section = false) {
+    Logger.auroLogger(message, "success", section);
+  }
+
+  static error(message, section = false) {
+    Logger.auroLogger(message, "error", section);
+  }
+}