@proyecto-viviana/solidaria 0.2.8 → 0.4.0

package/src/focus/FocusScope.tsx

@@ -13,64 +13,56 @@ import {
   type ParentComponent,
   createSignal,
   onMount,
-} from 'solid-js'
-import { isServer } from 'solid-js/web'
-import { getOwnerDocument, isFocusable } from '../utils'
-import { focusSafely } from '../utils/focus'
-
-// ============================================
-// TYPES
-// ============================================
+} from "solid-js";
+import { isServer } from "solid-js/web";
+import { getOwnerDocument, isFocusable, isTabbable } from "../utils";
+import { focusSafely } from "../utils/focus";
 
 export interface FocusScopeProps {
   /** The contents of the focus scope. */
-  children: JSX.Element
+  children: JSX.Element;
   /**
    * Whether to contain focus inside the scope, so users cannot
    * move focus outside, for example in a modal dialog.
    */
-  contain?: boolean
+  contain?: boolean;
   /**
    * Whether to restore focus back to the element that was focused
    * when the focus scope mounted, after the focus scope unmounts.
    */
-  restoreFocus?: boolean
+  restoreFocus?: boolean;
   /** Whether to auto focus the first focusable element in the focus scope on mount. */
-  autoFocus?: boolean
+  autoFocus?: boolean;
 }
 
 export interface FocusManagerOptions {
   /** The element to start searching from. The currently focused element by default. */
-  from?: Element
+  from?: Element;
   /** Whether to only include tabbable elements, or all focusable elements. */
-  tabbable?: boolean
+  tabbable?: boolean;
   /** Whether focus should wrap around when it reaches the end of the scope. */
-  wrap?: boolean
+  wrap?: boolean;
   /** A callback that determines whether the given element is focused. */
-  accept?: (node: Element) => boolean
+  accept?: (node: Element) => boolean;
 }
 
 export interface FocusManager {
   /** Moves focus to the next focusable or tabbable element in the focus scope. */
-  focusNext(opts?: FocusManagerOptions): HTMLElement | null
+  focusNext(opts?: FocusManagerOptions): HTMLElement | null;
   /** Moves focus to the previous focusable or tabbable element in the focus scope. */
-  focusPrevious(opts?: FocusManagerOptions): HTMLElement | null
+  focusPrevious(opts?: FocusManagerOptions): HTMLElement | null;
   /** Moves focus to the first focusable or tabbable element in the focus scope. */
-  focusFirst(opts?: FocusManagerOptions): HTMLElement | null
+  focusFirst(opts?: FocusManagerOptions): HTMLElement | null;
   /** Moves focus to the last focusable or tabbable element in the focus scope. */
-  focusLast(opts?: FocusManagerOptions): HTMLElement | null
+  focusLast(opts?: FocusManagerOptions): HTMLElement | null;
 }
 
-// ============================================
-// CONTEXT
-// ============================================
-
 interface FocusScopeContextValue {
-  focusManager: FocusManager
-  scopeRef: Accessor<Element[]>
+  focusManager: FocusManager;
+  scopeRef: Accessor<Element[]>;
 }
 
-const FocusScopeContext = createContext<FocusScopeContextValue | null>(null)
+const FocusScopeContext = createContext<FocusScopeContextValue | null>(null);
 
 /**
  * Returns a FocusManager interface for the parent FocusScope.
@@ -78,78 +70,146 @@ const FocusScopeContext = createContext<FocusScopeContextValue | null>(null)
  * a FocusScope, e.g. in response to user events like keyboard navigation.
  */
 export function useFocusManager(): FocusManager | undefined {
-  return useContext(FocusScopeContext)?.focusManager
-}
-
-// ============================================
-// UTILITIES
-// ============================================
-
-/**
- * Checks if an element is tabbable (focusable via Tab key).
- */
-function isTabbable(element: Element): boolean {
-  if (!isFocusable(element)) {
-    return false
-  }
-
-  // Check tabIndex
-  const tabIndex = element.getAttribute('tabindex')
-  if (tabIndex != null) {
-    return parseInt(tabIndex, 10) >= 0
-  }
-
-  return true
+  return useContext(FocusScopeContext)?.focusManager;
 }
 
 /**
  * Gets all focusable elements within a scope.
  */
 function getFocusableElements(scope: Element[], tabbable = false): HTMLElement[] {
-  const elements: HTMLElement[] = []
-  const filter = tabbable ? isTabbable : isFocusable
+  const elements: HTMLElement[] = [];
+  const filter = tabbable ? isTabbable : isFocusable;
 
   for (const scopeElement of scope) {
     // Check the element itself
     if (filter(scopeElement)) {
-      elements.push(scopeElement as HTMLElement)
+      elements.push(scopeElement as HTMLElement);
     }
 
     // Check all descendants
-    const descendants = scopeElement.querySelectorAll('*')
+    const descendants = scopeElement.querySelectorAll("*");
     for (let i = 0; i < descendants.length; i++) {
-      const el = descendants[i]
+      const el = descendants[i];
       if (filter(el)) {
-        elements.push(el as HTMLElement)
+        elements.push(el as HTMLElement);
       }
     }
   }
 
-  return elements
+  return elements;
 }
 
 /**
  * Checks if an element is within a scope.
  */
 function isElementInScope(element: Element | null, scope: Element[]): boolean {
-  if (!element) return false
-  return scope.some(node => node.contains(element))
+  if (!element) return false;
+  return scope.some((node) => node.contains(element));
 }
 
 /**
  * Gets the active element, accounting for shadow DOM.
  */
 function getActiveElement(doc: Document): Element | null {
-  let activeElement = doc.activeElement
+  let activeElement = doc.activeElement;
   while (activeElement?.shadowRoot?.activeElement) {
-    activeElement = activeElement.shadowRoot.activeElement
+    activeElement = activeElement.shadowRoot.activeElement;
+  }
+  return activeElement;
+}
+
+/**
+ * A scope is identified by its (stable) scope-elements accessor; `null` is the
+ * tree root. Mirrors @react-aria/focus's `ScopeRef`.
+ */
+type ScopeRef = Accessor<Element[]> | null;
+
+interface FocusScopeTreeNode {
+  scopeRef: ScopeRef;
+  parent: FocusScopeTreeNode | null;
+  children: Set<FocusScopeTreeNode>;
+}
+
+/**
+ * A registry of the live FocusScopes and their parent/child relationships,
+ * mirroring @react-aria/focus's `focusScopeTree`. The DOM tree alone can't
+ * express scope nesting because a child scope (e.g. a menu opened from inside a
+ * modal popover) is rendered in a portal, outside its parent scope's subtree.
+ * The tree records that nesting so containment can recognize a portaled
+ * descendant scope as "inside".
+ */
+class FocusScopeTree {
+  root: FocusScopeTreeNode;
+  private fastMap = new Map<ScopeRef, FocusScopeTreeNode>();
+
+  constructor() {
+    this.root = { scopeRef: null, parent: null, children: new Set() };
+    this.fastMap.set(null, this.root);
+  }
+
+  getTreeNode(scopeRef: ScopeRef): FocusScopeTreeNode | undefined {
+    return this.fastMap.get(scopeRef);
+  }
+
+  addTreeNode(scopeRef: ScopeRef, parent: ScopeRef): void {
+    const parentNode = this.fastMap.get(parent) ?? this.root;
+    const node: FocusScopeTreeNode = { scopeRef, parent: parentNode, children: new Set() };
+    parentNode.children.add(node);
+    this.fastMap.set(scopeRef, node);
+  }
+
+  removeTreeNode(scopeRef: ScopeRef): void {
+    // never remove the root
+    if (scopeRef === null) return;
+    const node = this.fastMap.get(scopeRef);
+    if (!node) return;
+    const parentNode = node.parent;
+    if (parentNode) {
+      parentNode.children.delete(node);
+      // Re-parent any children so a mid-tree unmount doesn't orphan descendants.
+      for (const child of node.children) {
+        child.parent = parentNode;
+        parentNode.children.add(child);
+      }
+    }
+    this.fastMap.delete(scopeRef);
+  }
+
+  // Pre-order depth-first; skips the null-scoped root, like upstream.
+  *traverse(node: FocusScopeTreeNode = this.root): Generator<FocusScopeTreeNode> {
+    if (node.scopeRef != null) {
+      yield node;
+    }
+    for (const child of node.children) {
+      yield* this.traverse(child);
+    }
   }
-  return activeElement
 }
 
-// ============================================
-// FOCUS SCOPE COMPONENT
-// ============================================
+const focusScopeTree = new FocusScopeTree();
+
+/**
+ * Whether the element is inside `scope` or any of its descendant scopes.
+ *
+ * `isElementInScope`'s `node.contains` already covers descendant scopes that
+ * are DOM children, but not those rendered in a portal. Walking the scope
+ * subtree closes that gap so focus moving into a portaled child scope still
+ * counts as "inside". Mirrors @react-aria/focus's `isElementInChildScope`.
+ */
+function isElementInChildScope(element: Element, scope: ScopeRef = null): boolean {
+  // Always allow focus to move into a top-layer element (e.g. toasts).
+  if (element instanceof Element && element.closest("[data-react-aria-top-layer]")) {
+    return true;
+  }
+
+  for (const node of focusScopeTree.traverse(focusScopeTree.getTreeNode(scope))) {
+    if (node.scopeRef && isElementInScope(element, node.scopeRef())) {
+      return true;
+    }
+  }
+
+  return false;
+}
 
 /**
  * A FocusScope manages focus for its descendants. It supports containing focus inside
@@ -160,135 +220,157 @@ function getActiveElement(doc: Document): Element | null {
  */
 export const FocusScope: ParentComponent<FocusScopeProps> = (props) => {
   if (isServer) {
-    return <>{props.children}</>
+    return <>{props.children}</>;
   }
 
-  let startRef: HTMLSpanElement | undefined
-  let endRef: HTMLSpanElement | undefined
-  const [scopeElements, setScopeElements] = createSignal<Element[]>([])
+  let startRef: HTMLSpanElement | undefined;
+  let endRef: HTMLSpanElement | undefined;
+  const [scopeElements, setScopeElements] = createSignal<Element[]>([]);
+
+  // The nearest enclosing FocusScope (through context, which Solid propagates
+  // across portals) is this scope's parent in the focus-scope tree. Read it
+  // before we shadow the context with our own provider below.
+  const parentScopeRef = useContext(FocusScopeContext)?.scopeRef ?? null;
 
   // Store the element that was focused when the scope mounted
-  let nodeToRestore: Element | null = null
+  let nodeToRestore: Element | null = null;
+
+  const getRestorableElement = (element: Element | null, doc: Document): Element | null => {
+    if (!element || element === doc.body || element === doc.documentElement) {
+      return null;
+    }
+    return element;
+  };
 
   // Create focus manager
   const focusManager: FocusManager = {
     focusNext(opts = {}) {
-      const scope = scopeElements()
-      if (scope.length === 0) return null
+      const scope = scopeElements();
+      if (scope.length === 0) return null;
 
-      const { from, tabbable = true, wrap = false, accept } = opts
-      const elements = getFocusableElements(scope, tabbable).filter(el => !accept || accept(el))
-      const doc = getOwnerDocument(scope[0])
-      const current = from || getActiveElement(doc)
+      const { from, tabbable = true, wrap = false, accept } = opts;
+      const elements = getFocusableElements(scope, tabbable).filter((el) => !accept || accept(el));
+      const doc = getOwnerDocument(scope[0]);
+      const current = from || getActiveElement(doc);
 
-      if (!current || elements.length === 0) return null
+      if (!current || elements.length === 0) return null;
 
-      const currentIndex = elements.indexOf(current as HTMLElement)
-      let nextIndex = currentIndex + 1
+      const currentIndex = elements.indexOf(current as HTMLElement);
+      let nextIndex = currentIndex + 1;
 
       if (nextIndex >= elements.length) {
         if (wrap) {
-          nextIndex = 0
+          nextIndex = 0;
         } else {
-          return null
+          return null;
         }
       }
 
-      const nextElement = elements[nextIndex]
+      const nextElement = elements[nextIndex];
       if (nextElement) {
-        focusSafely(nextElement)
-        return nextElement
+        focusSafely(nextElement);
+        return nextElement;
       }
 
-      return null
+      return null;
     },
 
     focusPrevious(opts = {}) {
-      const scope = scopeElements()
-      if (scope.length === 0) return null
+      const scope = scopeElements();
+      if (scope.length === 0) return null;
 
-      const { from, tabbable = true, wrap = false, accept } = opts
-      const elements = getFocusableElements(scope, tabbable).filter(el => !accept || accept(el))
-      const doc = getOwnerDocument(scope[0])
-      const current = from || getActiveElement(doc)
+      const { from, tabbable = true, wrap = false, accept } = opts;
+      const elements = getFocusableElements(scope, tabbable).filter((el) => !accept || accept(el));
+      const doc = getOwnerDocument(scope[0]);
+      const current = from || getActiveElement(doc);
 
-      if (!current || elements.length === 0) return null
+      if (!current || elements.length === 0) return null;
 
-      const currentIndex = elements.indexOf(current as HTMLElement)
-      let prevIndex = currentIndex - 1
+      const currentIndex = elements.indexOf(current as HTMLElement);
+      let prevIndex = currentIndex - 1;
 
       if (prevIndex < 0) {
         if (wrap) {
-          prevIndex = elements.length - 1
+          prevIndex = elements.length - 1;
         } else {
-          return null
+          return null;
         }
       }
 
-      const prevElement = elements[prevIndex]
+      const prevElement = elements[prevIndex];
       if (prevElement) {
-        focusSafely(prevElement)
-        return prevElement
+        focusSafely(prevElement);
+        return prevElement;
       }
 
-      return null
+      return null;
     },
 
     focusFirst(opts = {}) {
-      const scope = scopeElements()
-      if (scope.length === 0) return null
+      const scope = scopeElements();
+      if (scope.length === 0) return null;
 
-      const { tabbable = true, accept } = opts
-      const elements = getFocusableElements(scope, tabbable).filter(el => !accept || accept(el))
+      const { tabbable = true, accept } = opts;
+      const elements = getFocusableElements(scope, tabbable).filter((el) => !accept || accept(el));
 
       if (elements.length > 0) {
-        focusSafely(elements[0])
-        return elements[0]
+        focusSafely(elements[0]);
+        return elements[0];
       }
 
-      return null
+      return null;
     },
 
     focusLast(opts = {}) {
-      const scope = scopeElements()
-      if (scope.length === 0) return null
+      const scope = scopeElements();
+      if (scope.length === 0) return null;
 
-      const { tabbable = true, accept } = opts
-      const elements = getFocusableElements(scope, tabbable).filter(el => !accept || accept(el))
+      const { tabbable = true, accept } = opts;
+      const elements = getFocusableElements(scope, tabbable).filter((el) => !accept || accept(el));
 
       if (elements.length > 0) {
-        const lastElement = elements[elements.length - 1]
-        focusSafely(lastElement)
-        return lastElement
+        const lastElement = elements[elements.length - 1];
+        focusSafely(lastElement);
+        return lastElement;
       }
 
-      return null
+      return null;
     },
-  }
+  };
 
   // Collect scope elements after render
   onMount(() => {
-    if (!startRef || !endRef) return
+    if (!startRef || !endRef) return;
 
-    const nodes: Element[] = []
-    let node = startRef.nextSibling
+    const nodes: Element[] = [];
+    let node = startRef.nextSibling;
     while (node && node !== endRef) {
       if (node.nodeType === Node.ELEMENT_NODE) {
-        nodes.push(node as Element)
+        nodes.push(node as Element);
       }
-      node = node.nextSibling
+      node = node.nextSibling;
     }
-    setScopeElements(nodes)
-  })
+    setScopeElements(nodes);
+  });
+
+  // Register this scope in the focus-scope tree so containment can recognize a
+  // portaled descendant scope as "inside" it. The scope-elements accessor is a
+  // stable identity, so it works as the tree key even before it's populated.
+  onMount(() => {
+    focusScopeTree.addTreeNode(scopeElements, parentScopeRef);
+  });
+  onCleanup(() => {
+    focusScopeTree.removeTreeNode(scopeElements);
+  });
 
   // Save the currently focused element for restoration (must happen before autoFocus/contain effects run).
   onMount(() => {
-    if (!props.restoreFocus) return
+    if (!props.restoreFocus) return;
 
     // Focus can be in the main document, or inside this iframe's document.
-    const scopeDoc = startRef ? getOwnerDocument(startRef) : document
-    const scopeActive = getActiveElement(scopeDoc)
-    const topActive = getActiveElement(document)
+    const scopeDoc = startRef ? getOwnerDocument(startRef) : document;
+    const scopeActive = getActiveElement(scopeDoc);
+    const topActive = getActiveElement(document);
 
     // If the scope is in an iframe and that iframe is currently focused, prefer the iframe document's active element.
     if (
@@ -298,103 +380,146 @@ export const FocusScope: ParentComponent<FocusScopeProps> = (props) => {
       scopeActive &&
       scopeActive !== scopeDoc.body
     ) {
-      nodeToRestore = scopeActive
-      return
+      nodeToRestore = getRestorableElement(scopeActive, scopeDoc);
+      return;
     }
 
-    nodeToRestore = topActive
-  })
+    nodeToRestore = getRestorableElement(topActive, document);
+  });
 
   // Auto-focus first element
   createEffect(() => {
-    if (!props.autoFocus) return
+    if (!props.autoFocus) return;
 
-    const scope = scopeElements()
-    if (scope.length === 0) return
+    const scope = scopeElements();
+    if (scope.length === 0) return;
 
-    const doc = getOwnerDocument(scope[0])
-    const activeElement = getActiveElement(doc)
+    const doc = getOwnerDocument(scope[0]);
+    const activeElement = getActiveElement(doc);
 
     // Only auto-focus if focus is not already inside the scope
     if (!isElementInScope(activeElement, scope)) {
-      focusManager.focusFirst()
+      focusManager.focusFirst();
     }
-  })
+  });
 
   // Focus containment
   createEffect(() => {
-    if (!props.contain) return
+    if (!props.contain) return;
 
-    const scope = scopeElements()
-    if (scope.length === 0) return
+    const scope = scopeElements();
+    if (scope.length === 0) return;
 
-    const doc = getOwnerDocument(scope[0])
-    let focusedNode: Element | null = null
+    const doc = getOwnerDocument(scope[0]);
+    let focusedNode: Element | null = null;
 
     const onKeyDown = (e: KeyboardEvent) => {
-      if (e.key !== 'Tab' || e.altKey || e.ctrlKey || e.metaKey) {
-        return
+      if (e.key !== "Tab" || e.altKey || e.ctrlKey || e.metaKey) {
+        return;
       }
 
-      const scope = scopeElements()
-      const activeElement = getActiveElement(doc)
+      const scope = scopeElements();
+      const activeElement = getActiveElement(doc);
       if (!isElementInScope(activeElement, scope)) {
-        return
+        return;
       }
 
-      const elements = getFocusableElements(scope, true)
-      if (elements.length === 0) return
+      const elements = getFocusableElements(scope, true);
+      if (elements.length === 0) return;
 
-      const firstElement = elements[0]
-      const lastElement = elements[elements.length - 1]
+      const firstElement = elements[0];
+      const lastElement = elements[elements.length - 1];
 
       if (e.shiftKey && activeElement === firstElement) {
-        e.preventDefault()
-        focusSafely(lastElement)
+        e.preventDefault();
+        focusSafely(lastElement);
       } else if (!e.shiftKey && activeElement === lastElement) {
-        e.preventDefault()
-        focusSafely(firstElement)
+        e.preventDefault();
+        focusSafely(firstElement);
       }
-    }
+    };
 
     const onFocusIn = (e: FocusEvent) => {
-      const scope = scopeElements()
-      const target = e.target as Element
+      const scope = scopeElements();
+      const target = e.target as Element;
 
       if (isElementInScope(target, scope)) {
-        focusedNode = target
+        focusedNode = target;
+      } else if (isElementInChildScope(target, scopeElements)) {
+        // Focus moved into a descendant scope — e.g. a menu opened from inside
+        // this modal popover, rendered in a portal outside this scope's DOM
+        // subtree. Track it but don't pull focus back, which would tear the
+        // nested overlay down.
+        focusedNode = target;
       } else if (focusedNode) {
         // Focus escaped the scope, bring it back
-        focusSafely(focusedNode as HTMLElement)
+        focusSafely(focusedNode as HTMLElement);
       } else {
         // No previous focus, focus first element
-        focusManager.focusFirst()
+        focusManager.focusFirst();
       }
-    }
+    };
+
+    let restoreRaf: number | null = null;
+
+    const onFocusOut = (e: FocusEvent) => {
+      const target = e.target as Element;
+      if (!isElementInScope(target, scopeElements())) return;
+
+      // Focus left an element inside the scope. Wait a frame (like upstream's
+      // onBlur) so a synchronous refocus elsewhere can settle; if focus ended
+      // up outside every scope (e.g. blur() to body), pull it back.
+      const win = doc.defaultView ?? window;
+      if (restoreRaf != null) win.cancelAnimationFrame(restoreRaf);
+      restoreRaf = win.requestAnimationFrame(() => {
+        restoreRaf = null;
+        const scope = scopeElements();
+        const activeElement = getActiveElement(doc);
+        if (
+          activeElement &&
+          (isElementInScope(activeElement, scope) ||
+            isElementInChildScope(activeElement, scopeElements))
+        ) {
+          return;
+        }
 
-    doc.addEventListener('keydown', onKeyDown, true)
-    doc.addEventListener('focusin', onFocusIn, true)
+        if (doc.body.contains(target)) {
+          focusedNode = target;
+          focusSafely(target as HTMLElement);
+        } else {
+          focusManager.focusFirst();
+        }
+      });
+    };
+
+    doc.addEventListener("keydown", onKeyDown, true);
+    doc.addEventListener("focusin", onFocusIn, true);
+    doc.addEventListener("focusout", onFocusOut, true);
 
     onCleanup(() => {
-      doc.removeEventListener('keydown', onKeyDown, true)
-      doc.removeEventListener('focusin', onFocusIn, true)
-    })
-  })
+      doc.removeEventListener("keydown", onKeyDown, true);
+      doc.removeEventListener("focusin", onFocusIn, true);
+      doc.removeEventListener("focusout", onFocusOut, true);
+      if (restoreRaf != null) {
+        (doc.defaultView ?? window).cancelAnimationFrame(restoreRaf);
+      }
+    });
+  });
 
   // Restore focus on unmount
   onCleanup(() => {
     if (props.restoreFocus && nodeToRestore && (nodeToRestore as HTMLElement).focus) {
-      const doc = getOwnerDocument(nodeToRestore as Element)
-      const win = doc.defaultView ?? window
+      const doc = getOwnerDocument(nodeToRestore as Element);
+      const win = doc.defaultView ?? window;
 
       // Use requestAnimationFrame to ensure the element is still in the DOM
       win.requestAnimationFrame(() => {
         if (nodeToRestore && doc.body.contains(nodeToRestore as Node)) {
-          ;(nodeToRestore as HTMLElement).focus()
+          (nodeToRestore as HTMLElement).focus();
         }
-      })
+      });
     }
-  })
+  });
 
   return (
     <FocusScopeContext.Provider value={{ focusManager, scopeRef: scopeElements }}>
@@ -402,7 +527,7 @@ export const FocusScope: ParentComponent<FocusScopeProps> = (props) => {
       {props.children}
       <span data-focus-scope-end hidden ref={endRef} />
     </FocusScopeContext.Provider>
-  )
-}
+  );
+};
 
-export default FocusScope
+export default FocusScope;