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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Semantic Release Automated Changelog
 
+# [5.4.0](https://github.com/AlaskaAirlines/auro-library/compare/v5.3.3...v5.4.0) (2025-08-14)
+
+
+### Features
+
+* add a11yTransporter util ([817bb3a](https://github.com/AlaskaAirlines/auro-library/commit/817bb3acb9d20e99bc25a89f17db3a8f2ac91ab5))
+
+## [5.3.3](https://github.com/AlaskaAirlines/auro-library/compare/v5.3.2...v5.3.3) (2025-08-08)
+
+
+### Bug Fixes
+
+* move test related dependencies to devDependencies ([3d877f8](https://github.com/AlaskaAirlines/auro-library/commit/3d877f86c8a98b9ecdb44d83329fe391a8379483))
+
 ## [5.3.2](https://github.com/AlaskaAirlines/auro-library/compare/v5.3.1...v5.3.2) (2025-07-16)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurodesignsystem-dev/auro-library",
-  "version": "0.0.0-pr187.0",
+  "version": "0.0.0-pr192.0",
   "description": "This repository holds shared scripts, utilities, and workflows utilized across repositories along the Auro Design System.",
   "repository": {
     "type": "git",
@@ -14,7 +14,16 @@
   "bin": {
     "generateDocs": "./bin/generateDocs.mjs"
   },
+  "dependencies": {
+    "@floating-ui/dom": "^1.6.11",
+    "handlebars": "^4.7.8",
+    "markdown-magic": "^2.6.1"
+  },
   "devDependencies": {
+    "sinon": "^20.0.0",
+    "npm-run-all": "^4.1.5",
+    "@open-wc/testing": "^4.0.0",
+    "@aurodesignsystem/auro-cli": "^2.5.0",
     "@aurodesignsystem/eslint-config": "1.3.4",
     "@commitlint/cli": "^18.5.0",
     "@commitlint/config-conventional": "^18.5.0",
@@ -79,14 +88,5 @@
   },
   "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/runtime/FocusTrap/FocusTrap.mjs

@@ -10,17 +10,15 @@ export class FocusTrap {
    * 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) {
+  constructor(container) {
     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.tabDirection = 'forward'; // or 'backward'
 
     this._init();
   }
@@ -44,106 +42,46 @@ export class FocusTrap {
   }
 
   /**
-   * 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
+   * 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) => {
-
-    // Handle tab
-    if (e.key === 'Tab') this._handleTabKey(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
+      let activeElement = document.activeElement;
+      const actives =  [activeElement];
+      while (activeElement?.shadowRoot?.activeElement) {
+        actives.push(activeElement.shadowRoot.activeElement);
+        activeElement = 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
+      }
+    }
   };
 
   /**
@@ -157,7 +95,7 @@ export class FocusTrap {
     // Use the imported utility function to get focusable elements
     const elements = getFocusableElements(this.container);
     
-    // Return the elements found
+    // Filter out any elements with the 'focus-bookend' class
     return elements;
   }
 

package/scripts/runtime/Focusables/Focusables.mjs

@@ -21,7 +21,7 @@ export const FOCUSABLE_COMPONENTS = [
   'auro-combobox',
   'auro-input',
   'auro-counter',
-  // 'auro-menu', // Auro menu is not focusable by default, it uses a different interaction model
+  'auro-menu',
   'auro-select',
   'auro-datepicker',
   'auro-hyperlink',
@@ -54,7 +54,6 @@ export function isFocusableComponent(element) {
 /**
  * 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.
@@ -126,32 +125,5 @@ export function getFocusableElements(container) {
     }
   }
 
-  // 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;
+  return uniqueElements;
 }

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

@@ -10,7 +10,7 @@ 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-select', 'auro-datepicker',
+      'auro-input', 'auro-counter', 'auro-menu', 'auro-select', 'auro-datepicker',
       'auro-hyperlink', 'auro-accordion'
     ]) {
       const el = document.createElement(tag);
@@ -26,7 +26,7 @@ describe('isFocusableComponent', () => {
   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-select', 'auro-datepicker',
+      'auro-input', 'auro-counter', 'auro-menu', 'auro-select', 'auro-datepicker',
       'auro-hyperlink', 'auro-accordion'
     ]) {
       const el = document.createElement(tag);

package/scripts/runtime/a11yTransporter/README.md

@@ -0,0 +1,87 @@
+## Functions
+
+<dl>
+<dt><a href="#transportAriaAttributes">transportAriaAttributes</a></dt>
+<dd><p>Transfers all ARIA attributes from the host element to the target element.
+This function allows optional removal of the original attributes and the ability to ignore specific attributes.</p>
+</dd>
+<dt><a href="#transportRoleAttribute">transportRoleAttribute</a></dt>
+<dd><p>Transfers the &#39;role&#39; attribute from the host element to the target element.
+This function can optionally remove the original attribute from the host after transport.</p>
+</dd>
+<dt><a href="#transportTabIndexAttribute">transportTabIndexAttribute</a></dt>
+<dd><p>Transfers the &#39;tabindex&#39; attribute from the host element to the target element.
+This function can optionally remove the original attribute from the host after transport.</p>
+</dd>
+<dt><a href="#transportAllA11yAttributes">transportAllA11yAttributes</a></dt>
+<dd><p>Transfers all accessibility-related attributes (ARIA, role, tabindex) from the host element to the target element.
+This function allows optional removal of the original attributes and the ability to ignore specific attributes.</p>
+</dd>
+</dl>
+
+<a name="transportAriaAttributes"></a>
+
+## transportAriaAttributes
+Transfers all ARIA attributes from the host element to the target element.
+This function allows optional removal of the original attributes and the ability to ignore specific attributes.
+
+**Kind**: global constant  
+**Returns**: <code>function</code> - Function to detach the specific matcher and target pairing.  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| params | <code>Object</code> |  | The parameters object. |
+| params.host | <code>HTMLElement</code> |  | The host element to observe. |
+| params.target | <code>HTMLElement</code> |  | The target element to receive attributes. |
+| [params.removeOriginal] | <code>boolean</code> | <code>true</code> | Whether to remove original attributes. |
+| [params.ignore] | <code>Array.&lt;String&gt;</code> |  | The list of attributes not to transport. |
+
+<a name="transportRoleAttribute"></a>
+
+## transportRoleAttribute
+Transfers the 'role' attribute from the host element to the target element.
+This function can optionally remove the original attribute from the host after transport.
+
+**Kind**: global constant  
+**Returns**: <code>function</code> - Function to detach the specific matcher and target pairing.} param.  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| params | <code>Object</code> |  | The parameters object. |
+| params.host | <code>HTMLElement</code> |  | The host element to observe. |
+| params.target | <code>HTMLElement</code> |  | The target element to receive attributes. |
+| [params.removeOriginal] | <code>boolean</code> | <code>true</code> | Whether to remove original attributes. |
+
+<a name="transportTabIndexAttribute"></a>
+
+## transportTabIndexAttribute
+Transfers the 'tabindex' attribute from the host element to the target element.
+This function can optionally remove the original attribute from the host after transport.
+
+**Kind**: global constant  
+**Returns**: <code>function</code> - Function to detach the specific matcher and target pairing.} param.  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| params | <code>Object</code> |  | The parameters object. |
+| params.host | <code>HTMLElement</code> |  | The host element to observe. |
+| params.target | <code>HTMLElement</code> |  | The target element to receive attributes. |
+| [params.removeOriginal] | <code>boolean</code> | <code>true</code> | Whether to remove original attributes. |
+
+<a name="transportAllA11yAttributes"></a>
+
+## transportAllA11yAttributes
+Transfers all accessibility-related attributes (ARIA, role, tabindex) from the host element to the target element.
+This function allows optional removal of the original attributes and the ability to ignore specific attributes.
+
+**Kind**: global constant  
+**Returns**: <code>function</code> - Function to detach the specific matcher and target pairing.} param.  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| params | <code>Object</code> |  | The parameters object. |
+| params.host | <code>HTMLElement</code> |  | The host element to observe. |
+| params.target | <code>HTMLElement</code> |  | The target element to receive attributes. |
+| [params.removeOriginal] | <code>boolean</code> | <code>true</code> | Whether to remove original attributes. |
+| [params.ignore] | <code>Array.&lt;String&gt;</code> |  | The list of attributes not to transport. |
+

package/scripts/runtime/a11yTransporter/a11yTransporter.js

@@ -0,0 +1,105 @@
+import { transportAttributes } from "./transportAttributes.js";
+
+const _matchers = {
+  'aria-': attr => attr.startsWith('aria-'),
+  'role': attr => attr.match(/^role$/),
+  'tabindex': attr => attr.match(/^tabindex$/),
+};
+
+/**
+ * Transfers all ARIA attributes from the host element to the target element.
+ * This function allows optional removal of the original attributes and the ability to ignore specific attributes.
+ *
+ * @param {Object} params - The parameters object.
+ * @param {HTMLElement} params.host - The host element to observe.
+ * @param {HTMLElement} params.target - The target element to receive attributes.
+ * @param {boolean} [params.removeOriginal=true] - Whether to remove original attributes.
+ * @param {Array<String>} [params.ignore] - The list of attributes not to transport.
+ *
+ * @returns {Function} Function to detach the specific matcher and target pairing.
+ */
+
+export const transportAriaAttributes = ({ host, target, removeOriginal = true, ignore = undefined }) => {
+  return transportAttributes({
+    host,
+    target,
+    match: attr => {
+      if (ignore && ignore.includes(attr)) {
+        return false;
+      }
+      return _matchers['aria-'](attr);
+    },
+    removeOriginal
+  });
+};
+
+/**
+ * Transfers the 'role' attribute from the host element to the target element.
+ * This function can optionally remove the original attribute from the host after transport.
+ *
+ * @param {Object} params - The parameters object.
+ * @param {HTMLElement} params.host - The host element to observe.
+ * @param {HTMLElement} params.target - The target element to receive attributes.
+ * @param {boolean} [params.removeOriginal=true] - Whether to remove original attributes.
+ *
+ * @returns {Function} Function to detach the specific matcher and target pairing.} param.
+ */
+export const transportRoleAttribute = ({ host, target, removeOriginal = true }) => {
+  return transportAttributes({
+    host,
+    target,
+    match: _matchers['role'],
+    removeOriginal
+  });
+};
+
+/**
+ * Transfers the 'tabindex' attribute from the host element to the target element.
+ * This function can optionally remove the original attribute from the host after transport.
+ *
+ * @param {Object} params - The parameters object.
+ * @param {HTMLElement} params.host - The host element to observe.
+ * @param {HTMLElement} params.target - The target element to receive attributes.
+ * @param {boolean} [params.removeOriginal=true] - Whether to remove original attributes.
+ *
+ * @returns {Function} Function to detach the specific matcher and target pairing.} param.
+ */
+export const transportTabIndexAttribute = ({ host, target, removeOriginal = true }) => {
+  return transportAttributes({
+    host,
+    target,
+    match: _matchers['tabindex'],
+    removeOriginal
+  });
+};
+
+/**
+ * Transfers all accessibility-related attributes (ARIA, role, tabindex) from the host element to the target element.
+ * This function allows optional removal of the original attributes and the ability to ignore specific attributes.
+ *
+ * @param {Object} params - The parameters object.
+ * @param {HTMLElement} params.host - The host element to observe.
+ * @param {HTMLElement} params.target - The target element to receive attributes.
+ * @param {boolean} [params.removeOriginal=true] - Whether to remove original attributes.
+ * @param {Array<String>} [params.ignore] - The list of attributes not to transport.
+ *
+ * @returns {Function} Function to detach the specific matcher and target pairing.} param.
+ */
+export const transportAllA11yAttributes = ({ host, target, removeOriginal = true, ignore = undefined }) => {
+  return transportAttributes({
+    host,
+    target,
+    match: attr => {
+      if (ignore && ignore.includes(attr)) {
+        return false;
+      }
+      for (const key in _matchers) {
+        if (_matchers[key](attr)) {
+          return true;
+        }
+      }
+      return false;
+    },
+    removeOriginal
+  });
+}

package/scripts/runtime/a11yTransporter/transportAttributes.js

@@ -0,0 +1,297 @@
+/**
+ * Private module-level WeakMap to hold MutationObservers for each host element.
+ */
+const _observers = new WeakMap();
+
+/**
+ * Private module-level WeakMap to hold attribute matchers and targets for each host element.
+ * Structure: { 
+ *   host: { 
+ *     matchers: Set<Function>, 
+ *     targets: Map<HTMLElement, Map<Function, {removeOriginal: boolean, currentAttributes: Map<string, string>}>> 
+ *   } 
+ * }
+ */
+const _transportConfig = new WeakMap();
+
+/**
+ * Transfers all matching attributes from a host element to a target element and observes for future changes.
+ * 
+ * @param {Object} params - The parameters for the function.
+ * @param {HTMLElement} params.host - The host element from which attributes will be transported.
+ * @param {HTMLElement} params.target - The target element to which attributes will be transported.
+ * @param {boolean} [params.removeOriginal=true] - Whether to remove the attributes from the host element.
+ * @param {boolean} [params.observe=true] - Whether to attach a MutationObserver to the host element.
+ * @returns {Function} A function to detach the observer when no longer needed.
+ * @throws {TypeError} If the host or target parameters are not instances of HTMLElement.
+ */
+export const transportAttributes = ({ host, target, match, removeOriginal = true }) => {
+  // Guard Clause: Ensure host is valid HTMLElement instance
+  if (typeof host !== 'object' || !(host instanceof HTMLElement)) {
+    throw new TypeError('a11yUtilities.js | transportAttributes | The "host" parameter must be an instance of HTMLElement.');
+  }
+
+  // Guard Clause: Ensure target is valid HTMLElement instance
+  if (typeof target !== 'object' || !(target instanceof HTMLElement)) {
+    throw new TypeError('a11yUtilities.js | transportAttributes | The "target" parameter must be an instance of HTMLElement.');
+  }
+
+  // Guard Clause: Ensure match is a function
+  if (typeof match !== 'function') {
+    throw new TypeError('a11yUtilities.js | transportAttributes | The "match" parameter must be a function.');
+  }
+
+  // Guard Clause: Ensure removeOriginal is a boolean
+  if (typeof removeOriginal !== 'boolean') {
+    throw new TypeError('a11yUtilities.js | transportAttributes | The "removeOriginal" parameter must be a boolean.');
+  }
+  
+  // Register this transport and get cleanup function
+  return _registerTransport({
+    host,
+    target,
+    matcher: match,
+    removeOriginal
+  });
+};
+
+/**
+ * Registers a matcher and target for a host element and attaches an observer if needed.
+ *
+ * @param {Object} params - The parameters object.
+ * @param {HTMLElement} params.host - The host element to observe.
+ * @param {HTMLElement} params.target - The target element to receive attributes.
+ * @param {Function} params.matcher - Function that determines which attributes to transport.
+ * @param {boolean} [params.removeOriginal=true] - Whether to remove original attributes.
+ * @returns {Function} Function to detach the specific matcher and target pairing.
+ * @private
+ */
+const _registerTransport = ({ host, target, matcher, removeOriginal = true }) => {
+  // Initialize config for this host if it doesn't exist
+  if (!_transportConfig.has(host)) {
+    _transportConfig.set(host, {
+      matchers: new Set(),
+      targets: new Map()
+    });
+  }
+
+  const config = _transportConfig.get(host);
+  
+  // Add the matcher to the set of matchers for this host
+  config.matchers.add(matcher);
+  
+  // Initialize target entry if it doesn't exist
+  if (!config.targets.has(target)) {
+    config.targets.set(target, new Map());
+  }
+  
+  // Store the matcher with its removeOriginal setting for this target
+  config.targets.get(target).set(matcher, { 
+    removeOriginal,
+    currentAttributes: new Map()
+  });
+  
+  // Perform initial attribute transport
+  _transportAttributes({ host, target, matcher, removeOriginal });
+  
+  // Attach observer
+  _attachObserver(host);
+  
+  // Return cleanup function and utility functions
+  return {
+    cleanup: () => _cleanupTransport(host, target, matcher),
+    getObservedAttributes: () => _getObservedAttributes(host, target, matcher),
+    getObservedAttribute: (attr) => _getObservedAttribute(host, target, matcher, attr),
+  }
+};
+
+/**
+ * Cleans up resources associated with a specific matcher and target for a host element.
+ *
+ * @param {HTMLElement} host - The host element.
+ * @param {HTMLElement} target - The target element.
+ * @param {Function} matcher - The matcher function.
+ * @private
+ */
+const _cleanupTransport = (host, target, matcher) => {
+  const config = _transportConfig.get(host);
+  if (!config) return;
+  
+  // Remove this matcher from this target
+  const targetMatchers = config.targets.get(target);
+  if (targetMatchers) {
+    targetMatchers.delete(matcher);
+    
+    // If this target has no more matchers, remove it
+    if (targetMatchers.size === 0) {
+      config.targets.delete(target);
+    }
+  }
+  
+  // Check if this matcher is still used by any target
+  let matcherStillUsed = false;
+  for (const matcherMap of config.targets.values()) {
+    if (matcherMap.has(matcher)) {
+      matcherStillUsed = true;
+      break;
+    }
+  }
+  
+  // If not used anymore, remove from matchers set
+  if (!matcherStillUsed) {
+    config.matchers.delete(matcher);
+  }
+  
+  // If no more targets or matchers, detach observer
+  if (config.targets.size === 0 || config.matchers.size === 0) {
+    _detachObserver(host);
+  }
+};
+
+/**
+ * Generic function to transport attributes from a host element to a target element.
+ *
+ * @param {Object} params - The parameters object.
+ * @param {HTMLElement} params.host - The host element from which to transport attributes.
+ * @param {HTMLElement} params.target - The target element to which attributes will be transported.
+ * @param {Function} params.matcher - Function that takes an attribute name and returns true if it should be transported.
+ * @param {boolean} [params.removeOriginal=true] - Whether to remove original attributes from host.
+ * @returns {void}
+ * @private
+ */
+const _transportAttributes = ({ host, target, matcher, removeOriginal = true }) => {
+  // Get a list of all matching attributes on the host element and their values
+  const matchingAttributes = host.getAttributeNames()
+    .filter(attr => matcher(attr))
+    .reduce((acc, attr) => {
+      acc[attr] = host.getAttribute(attr);
+      return acc;
+    }, {});
+
+  // Move matching attributes to the target element, removing them from the host if removeOriginal is true
+  Object.entries(matchingAttributes).forEach(([key, value]) => {
+    _setObservedAttribute(host, target, matcher, key, value);
+    target.setAttribute(key, value);
+    if (removeOriginal) {
+      host.removeAttribute(key);
+    }
+  });
+};
+
+/**
+ * Attaches a MutationObserver to the host element to monitor attribute changes.
+ *
+ * @param {HTMLElement} host - The element to observe for attribute changes.
+ * @returns {MutationObserver} The observer instance.
+ * @private
+ */
+const _attachObserver = (host) => {
+  // If an observer for this host already exists, return it
+  if (_observers.has(host)) {
+    return _observers.get(host);
+  }
+
+  // Create a new MutationObserver
+  const observer = new MutationObserver((mutations) => {
+    const config = _transportConfig.get(host);
+    if (!config) return;
+    
+    // For each mutation affecting attributes
+    mutations
+      .filter(mutation => mutation.type === 'attributes')
+      .forEach(mutation => {
+        const attributeName = mutation.attributeName;
+        
+        // Find matchers that care about this attribute
+        for (const matcher of config.matchers) {
+          if (matcher(attributeName)) {
+            // For each target that uses this matcher
+            for (const [target, matcherConfigs] of config.targets.entries()) {
+              if (matcherConfigs.has(matcher)) {
+                const { removeOriginal } = matcherConfigs.get(matcher);
+                _transportAttributes({
+                  host,
+                  target,
+                  matcher,
+                  removeOriginal
+                });
+              }
+            }
+          }
+        }
+      });
+  });
+
+  // Start observing attribute changes
+  observer.observe(host, { attributes: true });
+  
+  // Store the observer
+  _observers.set(host, observer);
+  
+  return observer;
+};
+
+/**
+ * Detaches and cleans up the MutationObserver for a given host element.
+ * 
+ * @param {HTMLElement} host - The element whose observer should be detached.
+ * @private
+ */
+const _detachObserver = (host) => {
+  if (_observers.has(host)) {
+    const observer = _observers.get(host);
+    observer.disconnect();
+    _observers.delete(host);
+  }
+  
+  // Clean up the transport config as well
+  if (_transportConfig.has(host)) {
+    _transportConfig.delete(host);
+  }
+};
+
+/**
+ * Gets the matcher configuration for a specific host, target, and matcher.
+ * @param {HTMLElement} host - The host element.
+ * @param {HTMLElement} target - The target element.
+ * @param {Function} matcher - The matcher function.
+ * @returns {Object|undefined} The matcher configuration if found.
+ * @private
+ */
+const _getMatcherConfig = (host, target, matcher) => {
+  const config = _transportConfig.get(host);
+  if (!config) return undefined;
+  
+  const targetMatchers = config.targets.get(target);
+  if (!targetMatchers) return undefined;
+  
+  return targetMatchers.get(matcher);
+};
+
+/**
+ * Sets an observed attribute value.
+ * @param {HTMLElement} host - The host element.
+ * @param {HTMLElement} target - The target element.
+ * @param {Function} matcher - The matcher function.
+ * @param {string} key - The attribute name.
+ * @param {string} value - The attribute value.
+ * @private
+ */
+const _setObservedAttribute = (host, target, matcher, key, value) => {
+  const matcherConfig = _getMatcherConfig(host, target, matcher);
+  if (matcherConfig) {
+    matcherConfig.currentAttributes.set(key, value);
+  }
+};
+
+const _getObservedAttribute = (host, target, matcher, attr) => {
+  const matcherConfig = _getMatcherConfig(host, target, matcher);
+  if (matcherConfig) return matcherConfig.currentAttributes.get(attr);
+  return undefined;
+};
+
+const _getObservedAttributes = (host, target, matcher) => {
+  const matcherConfig = _getMatcherConfig(host, target, matcher);
+  if (matcherConfig) return Array.from(matcherConfig.currentAttributes.entries());
+  return [];
+};

package/scripts/runtime/floatingUI.mjs

@@ -1,6 +1,6 @@
 /* eslint-disable line-comment-position, no-inline-comments */
 
-import { autoUpdate, computePosition, offset, autoPlacement, flip } from '@floating-ui/dom';
+import { autoUpdate, computePosition, offset, autoPlacement, flip, shift } from '@floating-ui/dom';
 
 
 const MAX_CONFIGURATION_COUNT = 10;
@@ -166,6 +166,7 @@ export default class AuroFloatingUI {
       // Define the middlware for the floater configuration
       const middleware = [
         offset(this.element.floaterConfig?.offset || 0),
+        ...this.element.floaterConfig?.shift ? [shift()] : [], // Add shift middleware if shift is enabled.
         ...this.element.floaterConfig?.flip ? [flip()] : [], // Add flip middleware if flip is enabled.
         ...this.element.floaterConfig?.autoPlacement ? [autoPlacement()] : [], // Add autoPlacement middleware if autoPlacement is enabled.
       ];