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

package/scripts/build/processors/defaultDotGithubSync.mjs

@@ -0,0 +1,83 @@
+import {Logger} from "../../utils/logger.mjs";
+import {
+  fromAuroComponentRoot,
+  generateWCGeneratorUrl,
+  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} [generatorTemplateVersion="master"] - The release version tag to use instead of master.
+ * (like "_esm" to make README_esm.md).
+ */
+
+const DOT_GITHUB_PATH = '.github';
+const ISSUE_TEMPLATE_PATH = `${DOT_GITHUB_PATH}/ISSUE_TEMPLATE`;
+
+/**
+ * @type {ProcessorConfig} config - The default configuration for this processor.
+ */
+const defaultGitHubSyncConfig = {
+  overwriteLocalCopies: true,
+  generatorTemplateVersion: "master",
+};
+
+/**
+ * @param {ProcessorConfig} config - The configuration for this processor.
+ * @returns {import('../utils/sharedFileProcessorUtils').FileProcessorConfig[]}
+ */
+const defaultGitHubTemplateFiles = (config = defaultGitHubSyncConfig) => [
+  // bug_report.yml
+  {
+    identifier: 'bug_report.yml',
+    input: {
+      remoteUrl: generateWCGeneratorUrl(config.generatorTemplateVersion, `templates/${ISSUE_TEMPLATE_PATH}/bug_report.yml`),
+      fileName: fromAuroComponentRoot(`docTemplates/${ISSUE_TEMPLATE_PATH}/bug_report.yml`),
+      overwrite: config.overwriteLocalCopies
+    },
+    output: fromAuroComponentRoot(`${ISSUE_TEMPLATE_PATH}/bug_report.yml`)
+  },
+  // config.yml
+  {
+    identifier: 'config.yml',
+    input: {
+      remoteUrl: generateWCGeneratorUrl(config.generatorTemplateVersion, `templates/${ISSUE_TEMPLATE_PATH}/config.yml`),
+      fileName: fromAuroComponentRoot(`docTemplates/${ISSUE_TEMPLATE_PATH}/config.yml`),
+      overwrite: config.overwriteLocalCopies
+    },
+    output: fromAuroComponentRoot(`${ISSUE_TEMPLATE_PATH}/config.yml`)
+  },
+  // PULL_REQUEST_TEMPLATE.md
+  {
+    identifier: 'PULL_REQUEST_TEMPLATE.md',
+    input: {
+      remoteUrl: generateWCGeneratorUrl(config.generatorTemplateVersion, `templates/${DOT_GITHUB_PATH}/PULL_REQUEST_TEMPLATE.md`),
+      fileName: fromAuroComponentRoot(`docTemplates/${DOT_GITHUB_PATH}/PULL_REQUEST_TEMPLATE.md`),
+      overwrite: config.overwriteLocalCopies
+    },
+    output: fromAuroComponentRoot(`${DOT_GITHUB_PATH}/PULL_REQUEST_TEMPLATE.md`)
+  },
+];
+
+/**
+ *
+ * @param {ProcessorConfig} config - The configuration for this processor.
+ * @return {Promise<void>}
+ */
+export async function syncGithubFiles(config = defaultGitHubSyncConfig) {
+  // setup
+  await templateFiller.extractNames();
+
+  for (const file of defaultGitHubTemplateFiles(config)) {
+    try {
+      Logger.log(`Processing file: ${file.identifier}`);
+      // eslint-disable-next-line no-await-in-loop
+      await processContentForFile(file);
+    } catch (error) {
+      Logger.error(`Error processing file: ${file.identifier}, ${error.message}`);
+    }
+  }
+}

package/scripts/build/staticStyles-template.js

@@ -0,0 +1,2 @@
+import { css } from 'lit';
+export default css`<% content %>`;

package/scripts/build/syncGithubFiles.mjs

@@ -0,0 +1,25 @@
+// ------------------------------------------------------
+// GitHub Config Sync
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+//
+// This script will synchronize shared GitHub config
+// files to the local repo (eventually, anything that lives
+// in the .github directory).
+//
+// The actions in this file live in:
+// scripts/build/processors/defaultDotGithubSync.mjs
+//
+// This script is intended to be run AS-IS without modification.
+// To run a different processor, please see the defaultDotGithubSync.mjs file
+// and re-create in your repo OR add a new processor file.
+// ------------------------------------------------------
+
+import {syncGithubFiles} from "./processors/defaultDotGithubSync.mjs";
+import {Logger} from "../utils/logger.mjs";
+
+syncGithubFiles().then(() => {
+  Logger.log('Docs processed successfully');
+}).
+  catch((err) => {
+    Logger.error(`Error processing docs: ${err.message}`);
+  });

package/scripts/build/versionWriter.js

@@ -0,0 +1,26 @@
+// Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
+// See LICENSE in the project root for license information.
+
+// ---------------------------------------------------------------------
+
+/* eslint-disable no-undef */
+
+const auroSubNameIndex = 5;
+
+/**
+ * Writes a version file for the specified dependency package into the `src` directory.
+ * @param {string} pkg Dependency to write version file for.
+ */
+function writeDepVersionFile(pkg) {
+  const fs = require('fs');
+  const path = `${pkg}/package.json`;
+  const json = require(path);
+  const {version} = json;
+  const elemSubName = pkg.substring(pkg.indexOf('auro-') + auroSubNameIndex);
+  const versionFilePath = `./src/${elemSubName}Version.js`;
+
+  fs.writeFileSync(versionFilePath, `export default '${version}'`);
+}
+
+// add the code below
+module.exports = { writeDepVersionFile };

package/scripts/runtime/FocusTrap/FocusTrap.mjs

@@ -0,0 +1,194 @@
+import { getFocusableElements } from '../Focusables/Focusables.mjs';
+
+/**
+ * FocusTrap manages keyboard focus within a specified container element, ensuring that focus does not leave the container when tabbing.
+ * It is commonly used for modal dialogs or overlays to improve accessibility by trapping focus within interactive UI components.
+ */
+export class FocusTrap {
+  /**
+   * Creates a new FocusTrap instance for the given container element.
+   * Initializes event listeners and prepares the container for focus management.
+   *
+   * @param {HTMLElement} container The DOM element to trap focus within.
+   * @param {boolean} [controlTabOrder=false] If true enables manual control of the tab order by the FocusTrap.
+   * @throws {Error} If the provided container is not a valid HTMLElement.
+   */
+  constructor(container, controlTabOrder = false) {
+    if (!container || !(container instanceof HTMLElement)) {
+      throw new Error("FocusTrap requires a valid HTMLElement.");
+    }
+
+    this.container = container;
+    this.tabDirection = 'forward'; // or 'backward';
+    this.controlTabOrder = controlTabOrder;
+
+    this._init();
+  }
+
+  /**
+   * Initializes the focus trap by setting up event listeners and attributes on the container.
+   * Prepares the container for focus management, including support for shadow DOM and inert attributes.
+   *
+   * @private
+   */
+  _init() {
+
+    // Add inert attribute to prevent focusing programmatically as well (if supported)
+    if ('inert' in HTMLElement.prototype) {
+      this.container.inert = false; // Ensure the container isn't inert
+      this.container.setAttribute('data-focus-trap-container', true); // Mark for identification
+    }
+
+    // Track tab direction
+    this.container.addEventListener('keydown', this._onKeydown);
+  }
+
+  /**
+   * Gets an array of currently active (focused) elements in the document and shadow DOM.
+   * @returns {Array<HTMLElement>} An array of focusable elements within the container.
+   * @private
+   */
+  _getActiveElements() {
+    // Get the active element(s) in the document and shadow root
+    // This will include the active element in the shadow DOM if it exists
+    // Active element may be inside the shadow DOM depending on delegatesFocus, so we need to check both
+    let {activeElement} = document;
+    const actives =  [activeElement];
+    while (activeElement?.shadowRoot?.activeElement) {
+      actives.push(activeElement.shadowRoot.activeElement);
+      activeElement = activeElement.shadowRoot.activeElement;
+    }
+    return actives;
+  }
+
+  /**
+   * Gets the next focus index based on the current index and focusable elements.
+   * @param {number} currentIndex The current index of the focused element.
+   * @param {Array<HTMLElement>} focusables The array of focusable elements.
+   * @returns {number|null} The next focus index or null if not determined.
+   */
+  _getNextFocusIndex(currentIndex, focusables, actives) {
+    
+    // Determine if we need to wrap
+    const atFirst = actives.includes(focusables[0]) || actives.includes(this.container);
+    const atLast = actives.includes(focusables[focusables.length - 1]);
+
+    if (this.controlTabOrder) {
+      // Calculate the new index based on the current index and tab direction
+      let newFocusIndex = currentIndex + (this.tabDirection === 'forward' ? 1 : -1);
+
+      // Wrap-around logic
+      if (newFocusIndex < 0) newFocusIndex = focusables.length - 1;
+      if (newFocusIndex >= focusables.length) newFocusIndex = 0;
+
+      return newFocusIndex;
+    }
+
+    // Only wrap if at the ends
+    if (this.tabDirection === 'backward' && atFirst) {
+      return focusables.length - 1;
+    }
+
+    if (this.tabDirection === 'forward' && atLast) {
+      return 0;
+    }
+
+    // No wrap, so don't change focus, return early
+    return null;
+  }
+
+  /**
+   * Handles the Tab key press event to manage focus within the container.
+   * @param {KeyboardEvent} e The keyboard event triggered by the user.
+   * @returns {void}
+   */
+  _handleTabKey(e) {
+
+    // Update the focusable elements
+    const focusables = this._getFocusableElements();
+
+    if (!focusables.length) {
+      console.warn('FocusTrap: No focusable elements found in the container.');
+      return;
+    }
+
+    // Set the tab direction based on the key pressed
+    this.tabDirection = e.shiftKey ? 'backward' : 'forward';
+
+    // Get the active elements that are currently focused
+    const actives = this._getActiveElements();
+
+    // If we're at either end of the focusable elements, wrap around to the other end
+    let focusIndex = focusables.findIndex((el) => actives.includes(el));
+
+    // Fallback if we have no focused element
+    if (focusIndex === -1) focusIndex = 0;
+
+    // Get the next focus index based on the current focus index, tab direction, and controlTabOrder setting
+    // Is null if no new focus index is determined
+    let newFocusIndex = this._getNextFocusIndex(focusIndex, focusables, actives);
+
+    // If we have a new focus index, set focus to that element
+    if (newFocusIndex !== null) {
+      e.preventDefault();
+      focusables[newFocusIndex].focus();
+    }
+  }
+
+  /**
+   * Catches the keydown event
+   * @param {KeyboardEvent} e The keyboard event triggered by user interaction.
+   * @private
+   */
+  _onKeydown = (e) => {
+
+    // Handle tab
+    if (e.key === 'Tab') this._handleTabKey(e);
+  };
+
+  /**
+   * Retrieves all focusable elements within the container in DOM order, including those in shadow DOM and slots.
+   * Returns a unique, ordered array of elements that can receive focus.
+   *
+   * @returns {Array<HTMLElement>} An array of focusable elements within the container.
+   * @private
+   */
+  _getFocusableElements() {
+    // Use the imported utility function to get focusable elements
+    const elements = getFocusableElements(this.container);
+    
+    // Return the elements found
+    return elements;
+  }
+
+  /**
+   * Moves focus to the first focusable element within the container.
+   * Useful for setting initial focus when activating the focus trap.
+   */
+  focusFirstElement() {
+    const focusables = this._getFocusableElements();
+    if (focusables.length) focusables[0].focus();
+  }
+
+  /**
+   * Moves focus to the last focusable element within the container.
+   * Useful for setting focus when deactivating or cycling focus in reverse.
+   */
+  focusLastElement() {
+    const focusables = this._getFocusableElements();
+    if (focusables.length) focusables[focusables.length - 1].focus();
+  }
+
+  /**
+   * Removes event listeners and attributes added by the focus trap.
+   * Call this method to clean up when the focus trap is no longer needed.
+   */
+  disconnect() {
+
+    if (this.container.hasAttribute('data-focus-trap-container')) {
+      this.container.removeAttribute('data-focus-trap-container');
+    }
+
+    this.container.removeEventListener('keydown', this._onKeydown);
+  }
+}

package/scripts/runtime/FocusTrap/index.mjs

@@ -0,0 +1 @@
+export { FocusTrap } from './FocusTrap.mjs';

package/scripts/runtime/FocusTrap/test/FocusTrap.test.js

@@ -0,0 +1,168 @@
+// Try this alternative approach
+import { expect } from '@open-wc/testing';
+import { html, render } from 'lit';
+import sinon from 'sinon';
+import { FocusTrap } from '../FocusTrap.mjs';
+
+async function fixture(template) {
+  const wrapper = document.createElement('div');
+  render(template, wrapper);
+  document.body.appendChild(wrapper);
+  await new Promise(resolve => setTimeout(resolve, 0)); // Give browser time to render
+  return wrapper.firstElementChild;
+}
+
+describe('FocusTrap', () => {
+  let container;
+  let focusTrap;
+
+  beforeEach(async () => {
+    // Create a container with focusable elements
+    container = await fixture(html`
+      <div>
+        <button id="first">First</button>
+        <input id="middle" type="text" />
+        <a href="#" id="last">Last</a>
+      </div>
+    `);
+  });
+
+  afterEach(() => {
+    if (focusTrap) {
+      focusTrap.disconnect();
+      focusTrap = null;
+    }
+  });
+
+  describe('constructor', () => {
+    it('should create a new instance with a valid container', () => {
+      expect(() => new FocusTrap(container)).to.not.throw();
+    });
+
+    it('should throw an error if container is not a valid HTMLElement', () => {
+      expect(() => new FocusTrap(null)).to.throw('FocusTrap requires a valid HTMLElement');
+      expect(() => new FocusTrap({})).to.throw('FocusTrap requires a valid HTMLElement');
+    });
+  });
+
+  describe('initialization', () => {
+    it('should set attributes on the container', () => {
+      focusTrap = new FocusTrap(container);
+
+      if ('inert' in HTMLElement.prototype) {
+        expect(container.inert).to.be.false;
+        expect(container.hasAttribute('data-focus-trap-container')).to.be.true;
+      }
+    });
+  });
+
+  describe('focus management', () => {
+    it('should focus the first element when focusFirstElement is called', () => {
+      focusTrap = new FocusTrap(container);
+      const firstButton = container.querySelector('#first');
+
+      focusTrap.focusFirstElement();
+      expect(document.activeElement).to.equal(firstButton);
+    });
+
+    it('should focus the last element when focusLastElement is called', () => {
+      focusTrap = new FocusTrap(container);
+      const lastLink = container.querySelector('#last');
+
+      focusTrap.focusLastElement();
+      expect(document.activeElement).to.equal(lastLink);
+    });
+  });
+
+  describe('keyboard navigation', () => {
+    it('should trap focus and cycle to the first element when tabbing from the last element', async () => {
+      focusTrap = new FocusTrap(container);
+      const lastLink = container.querySelector('#last');
+      const firstButton = container.querySelector('#first');
+
+      // Create a spy on the focus method of the first button
+      const firstButtonFocusSpy = sinon.spy(firstButton, 'focus');
+
+      lastLink.focus();
+      expect(document.activeElement).to.equal(lastLink);
+
+      // Simulate Tab key press
+      const tabEvent = new KeyboardEvent('keydown', {
+        key: 'Tab',
+        bubbles: true,
+        composed: true
+      });
+
+      lastLink.dispatchEvent(tabEvent);
+
+      // Check if focus method was called on the first element
+      expect(firstButtonFocusSpy.calledOnce).to.be.true;
+      firstButtonFocusSpy.restore(); // Clean up the spy
+    });
+
+    it('should trap focus and cycle to the last element when shift-tabbing from the first element', async () => {
+      focusTrap = new FocusTrap(container);
+      const firstButton = container.querySelector('#first');
+      const lastLink = container.querySelector('#last');
+
+      // Create a spy on the focus method of the last link
+      const lastLinkFocusSpy = sinon.spy(lastLink, 'focus');
+
+      firstButton.focus();
+      expect(document.activeElement).to.equal(firstButton);
+
+      // Simulate Shift+Tab key press
+      const shiftTabEvent = new KeyboardEvent('keydown', {
+        key: 'Tab',
+        shiftKey: true,
+        bubbles: true,
+        cancelable: true
+      });
+
+      firstButton.dispatchEvent(shiftTabEvent);
+
+      // Check if focus method was called on the last element
+      expect(lastLinkFocusSpy.calledOnce).to.be.true;
+      lastLinkFocusSpy.restore(); // Clean up the spy
+    });
+  });
+
+  describe('cleanup', () => {
+    it('should remove attributes when disconnected', () => {
+      focusTrap = new FocusTrap(container);
+
+      focusTrap.disconnect();
+
+      expect(container.hasAttribute('data-focus-trap-container')).to.be.false;
+    });
+  });
+
+  describe('shadow DOM support', () => {
+    it('should work with shadow DOM elements', async () => {
+      // Create a custom element with shadow DOM
+      const shadowHost = await fixture(html`
+        <div id="shadow-host"></div>
+      `);
+
+      // Create shadow root
+      const shadowRoot = shadowHost.attachShadow({ mode: 'open' });
+
+      // Add focusable elements to shadow DOM
+      shadowRoot.innerHTML = `
+        <button id="shadow-first">First</button>
+        <input id="shadow-middle" type="text" />
+        <a href="#" id="shadow-last">Last</a>
+      `;
+
+      focusTrap = new FocusTrap(shadowHost);
+      const firstButton = shadowRoot.querySelector('#shadow-first');
+      const lastLink = shadowRoot.querySelector('#shadow-last');
+
+      focusTrap.focusFirstElement();
+      expect(shadowRoot.activeElement).to.equal(firstButton);
+
+      focusTrap.focusLastElement();
+      expect(shadowRoot.activeElement).to.equal(lastLink);
+    });
+  });
+});

package/scripts/runtime/Focusables/Focusables.mjs

@@ -0,0 +1,157 @@
+// Selectors for focusable elements
+export const FOCUSABLE_SELECTORS = [
+  'a[href]',
+  'button:not([disabled])',
+  'textarea:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  '[role="tab"]:not([disabled])',
+  '[role="link"]:not([disabled])',
+  '[role="button"]:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+  '[contenteditable]:not([contenteditable="false"])'
+];
+
+// List of custom components that are known to be focusable
+export const FOCUSABLE_COMPONENTS = [
+  'auro-checkbox',
+  'auro-radio',
+  'auro-dropdown',
+  'auro-button',
+  'auro-combobox',
+  'auro-input',
+  'auro-counter',
+  // 'auro-menu', // Auro menu is not focusable by default, it uses a different interaction model
+  'auro-select',
+  'auro-datepicker',
+  'auro-hyperlink',
+  'auro-accordion',
+];
+
+/**
+ * Determines if a given element is a custom focusable component.
+ * Returns true if the element matches a known focusable component and is not disabled.
+ *
+ * @param {HTMLElement} element The element to check for focusability.
+ * @returns {boolean} True if the element is a focusable custom component, false otherwise.
+ */
+export function isFocusableComponent(element) {
+  const componentName = element.tagName.toLowerCase();
+
+  // Guard Clause: Element is a focusable component
+  if (!FOCUSABLE_COMPONENTS.some((name) => element.hasAttribute(name) || componentName === name)) return false;
+
+  // Guard Clause: Element is not disabled
+  if (element.hasAttribute('disabled')) return false;
+
+  // Guard Clause: The element is a hyperlink and has no href attribute
+  if (componentName.match("hyperlink") && !element.hasAttribute('href')) return false;
+
+  // If all guard clauses pass, the element is a focusable component
+  return true;
+}
+
+/**
+ * Retrieves all focusable elements within the container in DOM order, including those in shadow DOM and slots.
+ * Returns a unique, ordered array of elements that can receive focus.
+ * Also sorts elements with tabindex first, preserving their order.
+ *
+ * @param {HTMLElement} container The container to search within
+ * @returns {Array<HTMLElement>} An array of focusable elements within the container.
+ */
+export function getFocusableElements(container) {
+  // Get elements in DOM order by walking the tree
+  const orderedFocusableElements = [];
+
+  // Define a recursive function to collect focusable elements in DOM order
+  const collectFocusableElements = (root) => {
+    // Check if current element is focusable
+    if (root.nodeType === Node.ELEMENT_NODE) {
+      // Check if this is a custom component that is focusable
+      const isComponentFocusable = isFocusableComponent(root);
+
+      if (isComponentFocusable) {
+        // Add the component itself as a focusable element and don't traverse its shadow DOM
+        orderedFocusableElements.push(root);
+        return; // Skip traversing inside this component
+      }
+
+      // Check if the element itself matches any selector
+      for (const selector of FOCUSABLE_SELECTORS) {
+        if (root.matches?.(selector)) {
+          orderedFocusableElements.push(root);
+          break; // Once we know it's focusable, no need to check other selectors
+        }
+      }
+
+      // Process shadow DOM only for non-Auro components
+      if (root.shadowRoot) {
+        // Process shadow DOM children in order
+        if (root.shadowRoot.children) {
+          Array.from(root.shadowRoot.children).forEach(child => {
+            collectFocusableElements(child);
+          });
+        }
+      }
+
+      // Process slots and their assigned nodes in order
+      if (root.tagName === 'SLOT') {
+        const assignedNodes = root.assignedNodes({ flatten: true });
+        for (const node of assignedNodes) {
+          collectFocusableElements(node);
+        }
+      } else {
+        // Process light DOM children in order
+        if (root.children) {
+          Array.from(root.children).forEach(child => {
+            collectFocusableElements(child);
+          });
+        }
+      }
+    }
+  };
+
+  // Start the traversal from the container
+  collectFocusableElements(container);
+
+  // Remove duplicates that might have been collected through different paths
+  // while preserving order
+  const uniqueElements = [];
+  const seen = new Set();
+
+  for (const element of orderedFocusableElements) {
+    if (!seen.has(element)) {
+      seen.add(element);
+      uniqueElements.push(element);
+    }
+  }
+
+  // Move tab-indexed elements to the front while preserving their order
+  // This ensures that elements with tabindex are prioritized in the focus order
+
+  // First extract elements with tabindex
+  const elementsWithTabindex = uniqueElements.filter(el => el.hasAttribute('tabindex') && (parseInt(el.getAttribute('tabindex')) ?? -1) > 0);
+
+  // Sort these elements by their tabindex value
+  elementsWithTabindex.sort((a, b) => {
+    return parseInt(a.getAttribute('tabindex'), 10) - parseInt(b.getAttribute('tabindex'), 10);
+  });
+
+  // Elements without tabindex (preserving their original order)
+  const elementsWithoutTabindex = uniqueElements.filter(el => 
+
+    // Elements without tabindex
+    !el.hasAttribute('tabindex') || 
+
+    // Preserve tab order of elements with tabindex of 0
+    (parseInt(el.getAttribute('tabindex')) ?? -1) === 0
+  );
+
+  // Combine both arrays with tabindex elements first
+  const tabIndexedUniqueElements = [
+    ...elementsWithTabindex,
+    ...elementsWithoutTabindex
+  ];
+
+  return tabIndexedUniqueElements;
+}

package/scripts/runtime/Focusables/index.mjs

@@ -0,0 +1 @@
+export { isFocusableComponent, getFocusableElements, FOCUSABLE_SELECTORS, FOCUSABLE_COMPONENTS } from './Focusables.mjs';