@lumx/react 4.12.0 → 4.12.1-alpha.0

package/index.js

@@ -1,4 +1,4 @@
-import { ColorVariant as ColorVariant$1, Size as Size$1, VISUALLY_HIDDEN, Theme as Theme$1, AspectRatio as AspectRatio$1, DOCUMENT, IS_BROWSER as IS_BROWSER$1, Emphasis as Emphasis$1, WINDOW, DIALOG_TRANSITION_DURATION, Orientation as Orientation$1, NOTIFICATION_TRANSITION_DURATION, Kind as Kind$1, Alignment as Alignment$1, ColorPalette as ColorPalette$1 } from '@lumx/core/js/constants';
+import { ColorVariant as ColorVariant$1, Size as Size$1, VISUALLY_HIDDEN, Theme as Theme$1, AspectRatio as AspectRatio$1, DOCUMENT as DOCUMENT$1, IS_BROWSER as IS_BROWSER$1, Emphasis as Emphasis$1, WINDOW, DIALOG_TRANSITION_DURATION, Orientation as Orientation$1, NOTIFICATION_TRANSITION_DURATION, Kind as Kind$1, Alignment as Alignment$1, ColorPalette as ColorPalette$1 } from '@lumx/core/js/constants';
 export * from '@lumx/core/js/constants';
 export * from '@lumx/core/js/types';
 import * as React from 'react';
@@ -204,6 +204,11 @@ const ColorVariant = {
  */
 const IS_BROWSER = typeof window !== 'undefined' && !window.navigator.userAgent.includes('jsdom');
 
+/**
+ * Optional global `document` instance (not defined when running SSR).
+ */
+const DOCUMENT = typeof document !== 'undefined' ? document : undefined;
+
 function getDefaultExportFromCjs (x) {
 	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
 }
@@ -2519,23 +2524,29 @@ const isChipDisabled = chip => chip?.getAttribute('aria-disabled') === 'true';
  */
 
 /**
- * Finds the previous enabled chip before the given chip element using a TreeWalker.
- * If no currentChip is provided, returns the last enabled chip in the container.
+ * Find the nearest enabled chip in the given direction relative to `anchor`.
+ *
+ * - When `anchor` is provided, walks one step in `direction` from it.
+ * - When `anchor` is omitted, returns the first enabled chip from the matching
+ *   end of the container (last chip for 'previous', first for 'next').
  */
-function findPreviousChip(container, currentChip) {
+function findSiblingChip(container, direction, anchor) {
   const walker = createSelectorTreeWalker(container, ENABLED_CHIP_SELECTOR);
-  if (!currentChip) {
-    // Find the last enabled chip by walking to the end.
+  if (anchor) {
+    walker.currentNode = anchor;
+    const node = direction === 'next' ? walker.nextNode() : walker.previousNode();
+    return node || undefined;
+  }
+
+  // No anchor: walk from the matching end of the container.
+  if (direction === 'previous') {
     let last;
     while (walker.nextNode()) {
       last = walker.currentNode;
     }
     return last;
   }
-
-  // Position the walker at the current chip and walk backward.
-  walker.currentNode = currentChip;
-  return walker.previousNode() || undefined;
+  return walker.nextNode() || undefined;
 }
 
 /** Remove an option by its id and call onChange. */
@@ -2574,9 +2585,6 @@ function setupSelectionChipGroupEvents(options) {
   };
 
   // Delegated keydown handler on the chip group container.
-  // Enter/Space trigger removal (like click).
-  // Backspace also removes but explicitly moves focus to previous chip (overriding the
-  // roving tabindex MutationObserver which defaults to moving focus forward).
   const handleKeyDown = evt => {
     const chip = getChip(evt.target);
     const optionId = chip?.dataset.optionId;
@@ -2584,14 +2592,20 @@ function setupSelectionChipGroupEvents(options) {
     if (optionId == null || !activatingKey || isChipDisabled(chip)) {
       return;
     }
+
+    // Compute focus fallback target before removing the chip.
+    let focusTarget;
     if (evt.key === 'Backspace') {
-      // Move focus to previous option (instead of next in listbox)
-      const previousChip = findPreviousChip(container, chip);
-      const focusTarget = previousChip || options.getInput?.();
-      if (focusTarget) {
-        focusTarget.focus();
-        focusTarget.setAttribute('tabindex', '0');
-      }
+      // Custom behavior (not WAI-ARIA recommendation) => focus the previous chip, fallback on input (no more chips)
+      focusTarget = findSiblingChip(container, 'previous', chip) || options.getInput?.() || undefined;
+    } else {
+      // WAI-ARIA recommendation when removing an option in a listbox => focus the next chip, fallback on previous chip
+      // (bonus: we fallback on input when there is no more chips)
+      focusTarget = findSiblingChip(container, 'next', chip) || findSiblingChip(container, 'previous', chip) || options.getInput?.() || undefined;
+    }
+    if (focusTarget) {
+      focusTarget.focus();
+      focusTarget.setAttribute('tabindex', '0');
     }
     evt.preventDefault();
     removeOption(options, optionId);
@@ -2609,7 +2623,7 @@ function setupSelectionChipGroupEvents(options) {
       if (!backspacePressed || !cursorAtStart) return;
       evt.stopPropagation();
       evt.preventDefault();
-      const lastChip = findPreviousChip(container);
+      const lastChip = findSiblingChip(container, 'previous');
       lastChip?.focus();
     };
     input.addEventListener('keydown', inputHandler);
@@ -5051,7 +5065,7 @@ const LISTENERS = makeListenerTowerContext();
  */
 function useCallbackOnEscape(callback, closeOnEscape = true) {
   useEffect(() => {
-    const rootElement = DOCUMENT?.body;
+    const rootElement = DOCUMENT$1?.body;
     if (!closeOnEscape || !callback || !rootElement) {
       return undefined;
     }
@@ -5266,7 +5280,7 @@ const Tooltip = forwardRef((props, ref) => {
     ...forwardedProps
   } = props;
   // Disable in SSR.
-  if (!DOCUMENT) {
+  if (!DOCUMENT$1) {
     return /*#__PURE__*/jsx(Fragment, {
       children: children
     });
@@ -6770,9 +6784,9 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
       }
     },
     select(option) {
-      callbacks.onSelect({
+      callbacks.onSelect?.({
         value: option ? getOptionValue(option) : ''
-      }, handle);
+      });
     },
     registerOption(element, callback) {
       const filterLower = filterValue.toLowerCase();
@@ -7334,6 +7348,7 @@ const ComboboxButton = Object.assign(forwardRefPolymorphic((props, ref) => {
  * @returns A ComboboxHandle for interacting with the combobox.
  */
 function setupComboboxInput(input, options) {
+  let handle;
   const {
     filter = 'auto',
     onSelect: optionOnSelect
@@ -7355,21 +7370,21 @@ function setupComboboxInput(input, options) {
    * Wraps the consumer's onSelect to perform input-mode side effects after selection:
    * clears the active descendant, resets the filter, and re-opens the popup.
    */
-  const onSelect = (option, combobox) => {
-    optionOnSelect(option, combobox);
+  const onSelect = option => {
+    optionOnSelect?.(option);
 
     // Clear the active item. In multi-select, keep visual focus so the
     // user can continue navigating after selection.
-    if (!combobox.isMultiSelect) {
-      combobox.focusNav?.clear();
+    if (!handle.isMultiSelect) {
+      handle.focusNav?.clear();
     }
     userHasTyped = false;
-    combobox.setIsOpen(true);
+    handle.setIsOpen(true);
     if (autoFilter) {
-      combobox.setFilter('');
+      handle.setFilter('');
     }
   };
-  const handle = setupCombobox({
+  handle = setupCombobox({
     onSelect
   }, {
     wrapNavigation: true
@@ -8803,8 +8818,14 @@ const ComboboxOptionMoreInfo$1 = (props, {
 /** CSS selector listing all tabbable elements. */
 const TABBABLE_ELEMENTS_SELECTOR = 'a[href], button, textarea, input:not([type="hidden"]):not([hidden]), [tabindex]';
 
-/** CSS selector matching element that are disabled (should not receive focus). */
-const DISABLED_SELECTOR = '[hidden], [tabindex="-1"], [disabled]:not([disabled="false"]), [aria-disabled]:not([aria-disabled="false"])';
+/**
+ * CSS selector matching elements that should be excluded from focus traversal.
+ *
+ * Note: `aria-disabled` is intentionally NOT in this list — per ARIA semantics, an `aria-disabled` element
+ * remains focusable (and discoverable by assistive tech). To remove an element from the tab order, use
+ * `tabindex="-1"` instead.
+ */
+const DISABLED_SELECTOR = '[hidden], [tabindex="-1"], [disabled]:not([disabled="false"])';
 
 const isNotDisabled = element => !element.matches(DISABLED_SELECTOR);
 function getFocusableElements(element) {
@@ -8833,86 +8854,158 @@ function getFirstAndLastFocusable(parentElement) {
   return {};
 }
 
+/**
+ * Shared listener tower for focus traps.
+ *
+ * When multiple traps are activated, only the last registered one is active. When it tears down, the previously
+ * registered trap is re-enabled.
+ */
 const FOCUS_TRAPS = makeListenerTowerContext();
-
 /**
  * Trap 'Tab' focus switch inside the `focusZoneElement`.
  *
- * If multiple focus trap are activated, only the last one is maintained and when a focus trap closes, the previous one
- * gets activated again.
+ * Setup behavior:
+ * 1. Focus `focusElement` if provided and contained in the zone.
+ * 2. Otherwise focus the first focusable descendant.
+ * 3. Otherwise focus the zone element itself (falling back to setting `tabindex="-1"` if needed) so that
+ *    keyboard users (especially screen reader users) land inside the trapped region (e.g. an empty dialog).
  *
- * @param focusZoneElement The element in which to trap the focus.
- * @param focusElement     The element to focus when the focus trap is activated (otherwise the first focusable element
- *                         will be focused).
+ * Tab key behavior:
+ * - With at least one focusable descendant: focus cycles between the first and last focusable in the zone.
+ * - With no focusable descendant: Tab is swallowed and focus is restored to the zone element itself.
+ *
+ * Multiple traps stack — only the latest one is active; previous traps re-enable when the latest is torn down.
+ *
+ * @param options Trap configuration.
+ * @param signal  AbortSignal used to tear down the trap.
  */
-function useFocusTrap(focusZoneElement, focusElement) {
-  useEffect(() => {
-    // Body element can be undefined in SSR context.
-    const rootElement = DOCUMENT?.body;
-    if (!rootElement || !focusZoneElement) {
-      return undefined;
+function setupFocusTrap(options, signal) {
+  const {
+    focusZoneElement,
+    focusElement
+  } = options;
+
+  // Body element can be undefined in SSR context.
+  const rootElement = DOCUMENT?.body;
+  if (!rootElement || !focusZoneElement || signal.aborted) {
+    return;
+  }
+
+  // Use the shadow root as focus zone when available.
+  const focusZoneElementOrShadowRoot = focusZoneElement.shadowRoot || focusZoneElement;
+
+  // Track whether we added a `tabindex="-1"` so we can restore the original state on teardown.
+  let addedTabIndex = false;
+
+  /** Make the zone element programmatically focusable (so we can fall back to it). */
+  const ensureZoneIsFocusable = () => {
+    if (!focusZoneElement.hasAttribute('tabindex')) {
+      focusZoneElement.setAttribute('tabindex', '-1');
+      addedTabIndex = true;
     }
+  };
 
-    // Use the shadow root as focusZoneElement when available
-    const focusZoneElementOrShadowRoot = focusZoneElement.shadowRoot || focusZoneElement;
+  /** Focus the zone element itself as a last-resort fallback. */
+  const focusZoneFallback = () => {
+    ensureZoneIsFocusable();
+    focusZoneElement.focus({
+      preventScroll: true
+    });
+  };
 
-    // Trap 'Tab' key down focus switch into the focus zone.
-    const trapTabFocusInFocusZone = evt => {
-      const {
-        key
-      } = evt;
-      if (key !== 'Tab') {
-        return;
-      }
-      const focusable = getFirstAndLastFocusable(focusZoneElementOrShadowRoot);
+  // Trap 'Tab' key down focus switch into the focus zone.
+  const trapTabFocusInFocusZone = evt => {
+    if (evt.key !== 'Tab') {
+      return;
+    }
+    const focusable = getFirstAndLastFocusable(focusZoneElementOrShadowRoot);
 
-      // Prevent focus switch if no focusable available.
-      if (!focusable.first) {
-        evt.preventDefault();
-        return;
-      }
-      const activeElement = focusZoneElement.shadowRoot ? focusZoneElement.shadowRoot.activeElement : document.activeElement;
-      if (
-      // No previous focus
-      !activeElement ||
-      // Previous focus is at the end of the focus zone.
-      !evt.shiftKey && activeElement === focusable.last ||
-      // Previous focus is outside the focus zone
-      !focusZoneElementOrShadowRoot.contains(activeElement)) {
-        focusable.first.focus();
-        evt.preventDefault();
-        return;
-      }
-      if (
-      // Focus order reversed
-      evt.shiftKey &&
-      // Previous focus is at the start of the focus zone.
-      activeElement === focusable.first) {
-        focusable.last.focus();
-        evt.preventDefault();
-      }
-    };
-    const focusTrap = {
-      enable: () => rootElement.addEventListener('keydown', trapTabFocusInFocusZone),
-      disable: () => rootElement.removeEventListener('keydown', trapTabFocusInFocusZone)
-    };
+    // Prevent focus switch if no focusable available — pin focus on the zone itself.
+    if (!focusable.first) {
+      evt.preventDefault();
+      focusZoneFallback();
+      return;
+    }
+    const activeElement = focusZoneElement.shadowRoot ? focusZoneElement.shadowRoot.activeElement : DOCUMENT?.activeElement;
+    if (
+    // No previous focus.
+    !activeElement ||
+    // Previous focus is at the end of the focus zone.
+    !evt.shiftKey && activeElement === focusable.last ||
+    // Previous focus is outside the focus zone.
+    !focusZoneElementOrShadowRoot.contains(activeElement)) {
+      focusable.first.focus();
+      evt.preventDefault();
+      return;
+    }
+    if (
+    // Focus order reversed.
+    evt.shiftKey &&
+    // Previous focus is at the start of the focus zone.
+    activeElement === focusable.first) {
+      focusable.last.focus();
+      evt.preventDefault();
+    }
+  };
+  const focusTrap = {
+    enable: () => rootElement.addEventListener('keydown', trapTabFocusInFocusZone),
+    disable: () => rootElement.removeEventListener('keydown', trapTabFocusInFocusZone)
+  };
 
-    // SETUP:
-    if (focusElement && focusZoneElementOrShadowRoot.contains(focusElement)) {
-      // Focus the given element.
-      focusElement.focus({
+  // SETUP: focus initial element.
+  if (focusElement && focusZoneElementOrShadowRoot.contains(focusElement)) {
+    // Focus the given element.
+    focusElement.focus({
+      preventScroll: true
+    });
+  } else {
+    const firstFocusable = getFirstAndLastFocusable(focusZoneElementOrShadowRoot).first;
+    if (firstFocusable) {
+      // Focus the first focusable descendant.
+      firstFocusable.focus({
         preventScroll: true
       });
     } else {
-      // Focus the first focusable element in the zone.
-      getFirstAndLastFocusable(focusZoneElementOrShadowRoot).first?.focus({
-        preventScroll: true
-      });
+      // No focusable descendant — fall back to the zone itself (e.g. an empty dialog).
+      focusZoneFallback();
     }
-    FOCUS_TRAPS.register(focusTrap);
+  }
+  FOCUS_TRAPS.register(focusTrap);
 
-    // TEARDOWN:
-    return () => FOCUS_TRAPS.unregister(focusTrap);
+  // TEARDOWN.
+  signal.addEventListener('abort', () => {
+    FOCUS_TRAPS.unregister(focusTrap);
+    if (addedTabIndex) {
+      focusZoneElement.removeAttribute('tabindex');
+    }
+  }, {
+    once: true
+  });
+}
+
+/**
+ * Trap 'Tab' focus switch inside the `focusZoneElement`.
+ *
+ * If multiple focus traps are activated, only the last one is maintained and when a focus trap closes, the previous one
+ * gets activated again.
+ *
+ * If the zone has no focusable descendant, the zone element itself receives focus (with a fallback `tabindex="-1"`).
+ *
+ * @param focusZoneElement The element in which to trap the focus.
+ * @param focusElement     The element to focus when the focus trap is activated (otherwise the first focusable element
+ *                         will be focused — and finally the zone element itself if no focusable is found).
+ */
+function useFocusTrap(focusZoneElement, focusElement) {
+  useEffect(() => {
+    if (!focusZoneElement) {
+      return undefined;
+    }
+    const controller = new AbortController();
+    setupFocusTrap({
+      focusZoneElement,
+      focusElement
+    }, controller.signal);
+    return () => controller.abort();
   }, [focusElement, focusZoneElement]);
 }
 
@@ -9453,7 +9546,7 @@ _InnerPopover.displayName = COMPONENT_NAME$15;
  */
 const Popover = skipRender(
 // Skip render in SSR
-() => Boolean(DOCUMENT), _InnerPopover);
+() => Boolean(DOCUMENT$1), _InnerPopover);
 Popover.displayName = COMPONENT_NAME$15;
 Popover.className = CLASSNAME$14;
 Popover.defaultProps = DEFAULT_PROPS$V;
@@ -11738,7 +11831,7 @@ const DEFAULT_PROPS$P = {
  * @return React element.
  */
 const Dialog = forwardRef((props, ref) => {
-  if (!DOCUMENT) {
+  if (!DOCUMENT$1) {
     // Can't render in SSR.
     return null;
   }
@@ -14147,7 +14240,7 @@ const Lightbox = forwardRef((props, ref) => {
     zIndex,
     ...forwardedProps
   } = props;
-  if (!DOCUMENT) {
+  if (!DOCUMENT$1) {
     // Can't render in SSR.
     return null;
   }
@@ -15106,7 +15199,7 @@ const Notification = forwardRef((props, ref) => {
     style,
     ...forwardedProps
   } = props;
-  if (!DOCUMENT) {
+  if (!DOCUMENT$1) {
     // Can't render in SSR.
     return null;
   }