@aurodesignsystem/auro-library 5.0.2 → 5.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Semantic Release Automated Changelog
 
+# [5.1.0](https://github.com/AlaskaAirlines/auro-library/compare/v5.0.2...v5.1.0) (2025-06-18)
+
+
+### Features
+
+* add focus trap ([1ec8290](https://github.com/AlaskaAirlines/auro-library/commit/1ec82905e5fc27aa0e4769df683462ebbce08bcd))
+
 ## [5.0.2](https://github.com/AlaskaAirlines/auro-library/compare/v5.0.1...v5.0.2) (2025-06-02)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurodesignsystem/auro-library",
-  "version": "5.0.2",
+  "version": "5.1.0",
   "description": "This repository holds shared scripts, utilities, and workflows utilized across repositories along the Auro Design System.",
   "repository": {
     "type": "git",
@@ -70,16 +70,23 @@
     "esLint": "eslint ./scripts/**/*.js",
     "linters": "npm-run-all esLint",
     "build:docs": "node scripts/build/generateReadme.mjs",
-    "test": "vitest --run",
-    "test:watch": "vitest"
+    "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",
-    "@floating-ui/dom": "^1.6.11",
-    "npm-run-all": "^4.1.5"
+    "npm-run-all": "^4.1.5",
+    "sinon": "^20.0.0"
   }
 }

package/scripts/runtime/FocusTrap/FocusTrap.mjs

@@ -0,0 +1,130 @@
+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.
+   * @throws {Error} If the provided container is not a valid HTMLElement.
+   */
+  constructor(container) {
+    if (!container || !(container instanceof HTMLElement)) {
+      throw new Error("FocusTrap requires a valid HTMLElement.");
+    }
+
+    this.container = container;
+    this.tabDirection = 'forward'; // or 'backward'
+
+    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);
+  }
+
+  /**
+   * Handles keydown events to manage tab navigation within the container.
+   * Ensures that focus wraps around when reaching the first or last focusable element.
+   *
+   * @param {KeyboardEvent} e The keyboard event triggered by user interaction.
+   * @private
+   */
+  _onKeydown = (e) => {
+    
+    if (e.key === 'Tab') {
+
+      // Set the tab direction based on the key pressed
+      this.tabDirection = e.shiftKey ? 'backward' : 'forward';
+
+      // 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
+      const actives =  [
+        document.activeElement,
+        ...document.activeElement.shadowRoot && [document.activeElement.shadowRoot.activeElement] || []
+      ]
+
+      // Update the focusable elements
+      const focusables = this._getFocusableElements();
+
+      // If we're at either end of the focusable elements, wrap around to the other end
+      const focusIndex =
+        (actives.includes(focusables[0]) || actives.includes(this.container)) && this.tabDirection === 'backward'
+          ? focusables.length - 1
+          : actives.includes(focusables[focusables.length - 1]) && this.tabDirection === 'forward'
+            ? 0
+            : null;
+
+      if (focusIndex !== null) {
+        focusables[focusIndex].focus();
+        e.preventDefault(); // Prevent default tab behavior
+        e.stopPropagation(); // Stop the event from bubbling up
+      }
+    }
+  };
+
+  /**
+   * 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);
+    
+    // Filter out any elements with the 'focus-bookend' class
+    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,129 @@
+// 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-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.includes(componentName)) 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.
+ *
+ * @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);
+    }
+  }
+
+  return uniqueElements;
+}

package/scripts/runtime/Focusables/index.mjs

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

package/scripts/runtime/Focusables/test/Focusables.test.js

@@ -0,0 +1,165 @@
+/* eslint-disable max-classes-per-file */
+import { fixture, html, expect, elementUpdated } from '@open-wc/testing';
+
+import {
+  isFocusableComponent,
+  getFocusableElements
+} from '../Focusables.mjs';
+
+describe('isFocusableComponent', () => {
+  it('returns true for enabled custom focusable components', async () => {
+    for (const tag of [
+      'auro-checkbox', 'auro-radio', 'auro-dropdown', 'auro-button', 'auro-combobox',
+      'auro-input', 'auro-counter', 'auro-menu', 'auro-select', 'auro-datepicker',
+      'auro-hyperlink', 'auro-accordion'
+    ]) {
+      const el = document.createElement(tag);
+      if (tag === 'auro-hyperlink') {
+        el.setAttribute('href', '#');
+      }
+      document.body.appendChild(el);
+      expect(isFocusableComponent(el)).to.be.true;
+      el.remove();
+    }
+  });
+
+  it('returns false for custom components with disabled attribute', async () => {
+    for (const tag of [
+      'auro-checkbox', 'auro-radio', 'auro-dropdown', 'auro-button', 'auro-combobox',
+      'auro-input', 'auro-counter', 'auro-menu', 'auro-select', 'auro-datepicker',
+      'auro-hyperlink', 'auro-accordion'
+    ]) {
+      const el = document.createElement(tag);
+      el.setAttribute('disabled', '');
+      if (tag === 'auro-hyperlink') {
+        el.setAttribute('href', '#');
+      }
+      document.body.appendChild(el);
+      expect(isFocusableComponent(el)).to.be.false;
+      el.remove();
+    }
+  });
+
+  it('returns false for auro-hyperlink without href', async () => {
+    const el = document.createElement('auro-hyperlink');
+    document.body.appendChild(el);
+    expect(isFocusableComponent(el)).to.be.false;
+    el.remove();
+  });
+
+  it('returns false for non-custom elements', async () => {
+    const el = document.createElement('div');
+    document.body.appendChild(el);
+    expect(isFocusableComponent(el)).to.be.false;
+    el.remove();
+  });
+});
+
+describe('getFocusableElements', () => {
+  it('finds standard focusable elements', async () => {
+    const el = await fixture(html`
+      <div>
+        <button id="btn"></button>
+        <input id="input">
+        <a id="link" href="#"></a>
+        <textarea id="ta"></textarea>
+        <select id="sel"></select>
+      </div>
+    `);
+    const focusables = getFocusableElements(el);
+    expect(focusables.map(e => e.id)).to.include.members(['btn', 'input', 'link', 'ta', 'sel']);
+  });
+
+  it('skips disabled elements', async () => {
+    const el = await fixture(html`
+      <div>
+        <button id="btn" disabled></button>
+        <input id="input" disabled>
+        <textarea id="ta" disabled></textarea>
+        <select id="sel" disabled></select>
+      </div>
+    `);
+    const focusables = getFocusableElements(el);
+    expect(focusables.length).to.equal(0);
+  });
+
+  it('finds custom focusable components', async () => {
+    const el = await fixture(html`
+      <div>
+        <auro-checkbox id="cb"></auro-checkbox>
+        <auro-hyperlink id="hl" href="#"></auro-hyperlink>
+        <auro-button id="ab"></auro-button>
+      </div>
+    `);
+    const focusables = getFocusableElements(el);
+    expect(focusables.map(e => e.id)).to.include.members(['cb', 'hl', 'ab']);
+  });
+
+  it('skips disabled custom components', async () => {
+    const el = await fixture(html`
+      <div>
+        <auro-checkbox id="cb" disabled></auro-checkbox>
+        <auro-hyperlink id="hl" disabled href="#"></auro-hyperlink>
+      </div>
+    `);
+    const focusables = getFocusableElements(el);
+    expect(focusables.length).to.equal(0);
+  });
+
+  it('finds elements in shadow DOM', async () => {
+    class ShadowEl extends HTMLElement {
+      constructor() {
+        super();
+        this.attachShadow({ mode: 'open' });
+      }
+      connectedCallback() {
+        this.shadowRoot.innerHTML = `<button id="shadowBtn"></button>`;
+      }
+    }
+    customElements.define('shadow-el', ShadowEl);
+    const el = await fixture(html`
+      <div>
+        <shadow-el id="host"></shadow-el>
+      </div>
+    `);
+    await elementUpdated(el);
+    const focusables = getFocusableElements(el);
+    // Should find the button inside shadow DOM
+    const shadowBtn = el.querySelector('shadow-el').shadowRoot.getElementById('shadowBtn');
+    expect(focusables).to.include(shadowBtn);
+  });
+
+  it('finds elements assigned to slots', async () => {
+    class SlotEl extends HTMLElement {
+      constructor() {
+        super();
+        this.attachShadow({ mode: 'open' });
+      }
+      connectedCallback() {
+        this.shadowRoot.innerHTML = `<slot></slot>`;
+      }
+    }
+    customElements.define('slot-el', SlotEl);
+    const el = await fixture(html`
+      <slot-el>
+        <button id="slottedBtn"></button>
+      </slot-el>
+    `);
+    await elementUpdated(el);
+    const focusables = getFocusableElements(el);
+    const slottedBtn = el.querySelector('#slottedBtn');
+    expect(focusables).to.include(slottedBtn);
+  });
+
+  it('does not return duplicates', async () => {
+    // This is a contrived case, but let's check that duplicates are not returned
+    const el = await fixture(html`
+      <div>
+        <button id="btn"></button>
+      </div>
+    `);
+    const focusables = getFocusableElements(el);
+    // Should only have one instance of the button
+    expect(focusables.filter(e => e.id === 'btn').length).to.equal(1);
+  });
+});